Plan, build, review, ship, keep: a working routine for long-term projects with your own coding agents in Cursor. Plans with to-dos you approve, review agents, staging-to-production gates that wait for your yes, and a handoff and memory that survive new chats. Follow the work in Mission Control.
Get a repository ready for the kit: runs the essential checks and tells you what to fix before your first plan.
# Command: /agent-kit-onboard
## Goal
Prepare and validate repository readiness before `/start-project`. This command is the sole Agent Kit coordinator for repository preparation.
## Hard Stops
1. Do not ask about Agent Personas, external plan review, or a first deliverable before essential readiness is complete.
2. Ask one concrete Ask questions question at a time, and only when scanner evidence cannot resolve intent.
3. Do not initialize Git, create or publish branches, add or change remotes, install hooks, create CI or deployment configuration, change protection, or perform another external or destructive mutation without explicit Ask questions confirmation.
4. A skipped or cancelled answer stops the proposed action.
5. Do not write a plan or edit product code. `/start-project` owns deliverable planning.
## Start or Resume
> **Delegation note:** The initial `agent-kit doctor --json` execution and readiness file reading below is performed by a **Task(explore) subagent** dispatched from this step. The parameters define the specification of what the worker scans. See below for the delegation pattern.
1. **Fill the template** using `.cursor/context/templates/command-worker-prompt.md` (Repo, Command, Task description, `read_scope`, `worker_contract`, `max_ticks`); exact field values: [procedure.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/agent-kit-onboard/procedure.md).
2. **Dispatch** a Task subagent with `subagent_type: explore`.
3. **Read the worker summary** — the main window uses the readiness report for the next steps.
4. Preserve an active plan or HANDOFF. Repository readiness guidance must not replace or restart active work.
5. Derive unresolved essential checks from `pillars[].checks[]`: select checks where `essential: true` and `status` is not `ready`, preserve report order, then use that check's `actions` for the next step. Do not treat `pendingActions` as an essential-only queue.
6. Resume the first unresolved essential check before considering any non-essential action. Do not restart completed checks or repeat confirmed facts.
**Fallback:** If Task dispatch is unavailable, run the doctor scan and file reads inline (same as pre-delegation behavior: run `agent-kit doctor --json`, read the returned report, `.cursor/context/readiness.json`, `.cursor/context/config.json`, and `.cursor/agent-kit.config.json` when present).
## First Useful Message
The first useful message must contain these four items in this order:
1. `Repository preparation: N of M essential checks ready.`
2. `Detected:` concise facts supported by report evidence.
3. `Fixed:` safe local fixes already applied, or `none`.
4. `Next:` exactly one action, using the first unresolved essential check.
Do not append a second call to action, settings menu, command overview, or unrelated welcome.
## Progressive Resolution
> **Delegation note:** same Task(explore) pattern as Start or Resume, applied only to the re-scan sub-step; the main window owns all HITL and decisions here.
Per-check resolution guidance and exact Ask-label examples: [procedure.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/agent-kit-onboard/procedure.md).
## Actions and Revalidation
> **Delegation note:** same pattern as Start or Resume, applied to this section's re-scan step.
- Run local, reversible, idempotent, merge-safe repairs with `agent-kit doctor --fix-safe --json`.
- After any confirmed or manual action, rerun `agent-kit doctor --json` and re-read the refreshed snapshot.
- Revalidate the affected check before advancing.
- Persist explicit non-blocking deferrals in `.cursor/context/config.json` under `onboarding.deferredItems` with `checkId`, `reason`, and `recoveryCommand`. Merge without removing existing keys.
- **Essential checks cannot be completed by deferral when the scanner offers a concrete action for them.** One exception (Amend 2026-09-20, ADR `decisions/2026-07-28_onboarding-completion-nonessential-deferral.md`): an essential check with zero listed actions may be completed by an explicit deferral. See Completion step 2 below for the exact enforcement rule.
- A check with `status: "blocked"` cannot be deferred, regardless of whether it is essential.
- `agent-kit doctor` prints `Deferred essential: <check-id> — <reason>` for each essential check completed this way (also in the `--json` output as `deferredEssentials`), so "onboarding completed" is never silently indistinguishable from "every essential check is truly ready."
## Completion
> **Delegation note:** same pattern as Start or Resume, applied to the final re-scan (step 1 below).
Completion requires every essential check to be ready, **or**, for an essential check with zero listed actions only, explicitly deferred with a reason and recovery action (Amend 2026-09-20). Every remaining non-essential check must be ready or have a valid explicit deferral with a reason and recovery action.
When complete:
1. Run `agent-kit doctor --json` once more and read the refreshed report before writing completion state.
2. Verify every check in `pillars[].checks[]` with `essential: true` has `status: "ready"`, **or** has zero `actions` and an explicit deferral (reason + recovery command) in `onboarding.deferredItems`. An essential check with a listed action always resolves through that action, never a deferral, no matter its status.
3. Verify each remaining non-essential check is ready or explicitly deferred with both a reason and recovery action. Reject deferral for any check with `status: "blocked"`.
4. If verification fails, leave `onboarding.status: "in_progress"` and `onboarded` unchanged, then resume the first unresolved essential check derived from `pillars[].checks[]`.
5. Only after verification passes, merge `onboarding.status: "completed"` and `onboarded: true` into `.cursor/context/config.json` without removing other keys.
6. **Domain-skills scaffold (optional HITL).** Before showing the final finish-setup CTA, run the scaffold gate:
- Read `.cursor/context/personalization.json` and `.cursor/agent-kit.config.json` to reuse install-time evidence. Do not invent a second detector.
- Build a short proposal from the already-applied L2 skills and L1 packs in personalization, plus any project-owned domain skills implied by the profile but not yet installed.
- Ask one question using **Ask questions** with concrete options:
> "Essentials are ready. Before finish setup, scaffold domain skills from the detected profile?"
Options: `Scaffold domain skills` / `Defer (record reason)` / `Skip`
- **Fallback when Ask questions is unavailable:** present the same options as a numbered list, ask the user to reply with the number or the label, and note they can always **type their own answer** if none of the options fit (equivalent of the built-in "Other" choice).
Domain-skills scaffold execution detail (what happens after each label): [procedure.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/agent-kit-onboard/procedure.md).
7. End with exactly one call to action:
- `Next: /start-project` when the user wants to plan a deliverable.
- `Next: finish setup` when no deliverable should start now.
The domain-skills scaffold gate is not a readiness blocker; deferring or skipping it must still allow `/start-project` to proceed.
Mission Control is also **optional** and **not** an essential readiness check. Consumer L0 installs the `/dashboard` command text but not `dashboard/**`; `agent-kit dashboard` serves the panel from the installed CLI (4.8.2 onward) when the operator wants it.
Do not block `/start-project` on Mission Control or on the domain-skills scaffold. Do not ask about skins or external review before essentials (Hard Stop 1).
Agent Personas remain available through later personalization or settings. External review is offered only when a plan reaches exhaustion.Turn a request, issue or spec into a plan with phases and to-dos. You approve the plan, then the first step; nothing is built before that.
# Command: /start-project
## Goal
Bootstrap a **plan with to-dos** from any user payload. This command does **not** mean start coding.
HITL contract, exact Ask labels, numbered fallback (path 1): [hitl-gates](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md). Broad Intake and Gate A/B detail: [start-project-intake.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/start-project-intake.md).
## Hard stops (kit failure if skipped)
1. **Broad Intake first.** Scan via Task(explore) (or inline). Plans bucket is `.cursor/context/plan-index.json` + `.cursor/HANDOFF.md` only. Do not glob `.cursor/plans/*.plan.md`. Delegation stays (ADR `2026-07-26_command-orchestration-delegation-pattern.md`).
2. **Plan file before any product edit.** Allowed writes: the new `.cursor/plans/*.plan.md` and HANDOFF disposition. Host Plan Mode does not replace Gate A/B: if the host already has a native plan, copy it into `.cursor/plans/` then run Gate A (ADR `2026-09-15_kit-plans-sot-over-host-plan-mode.md`).
3. **Goal in the same message is not execute permission.** Ask only for the deliverable goal.
4. **Two gates, two yes answers.** Gate A writes the plan and stops. Gate B runs one unit only after a second yes.
5. **Never** "create a plan and start Phase 1" in one turn. `confirm-provider` / `collaboration.provider` are warnings only; do not Ask them.
## Ask labels
**Gate A, active plan:** `Write plan and add to backlog (keep current active)` / `Park current plan, write plan and activate new` / `Modify proposal first` / `Cancel`
**Gate A, no active plan:** `Write plan file` / `Write plan and add to backlog` / `Modify proposal first` / `Cancel`
**Gate B:** `Start first unit` / `Switch to /run-plan` / `Edit plan first` / `Add to backlog` / `Stop here`
**Pending ticket (preflight, id `ticket`, only while `.cursor/context/gate-exit.json` has a pending entry):** `Read the ticket` / `Accept` / `Discard` / `Later`
Default-path Ask is Gate A. Gate B is a second yes. Inbox and `confirm-provider` are never on this path.
Numbered-list fallback is **path 1** when Ask questions is missing (one list per message).
## Procedure
1. Readiness: read `.cursor/agent-kit.config.json` and `.cursor/context/readiness.json`. Unresolved `essential: true` checks block planning; point to `/agent-kit-onboard`. Do **not** treat `pendingActions` as an essential-only queue. Non-essential pending is warnings only. A pending operator ticket is Asked before Gate A and listed as a Broad Intake `include` finding: [pending-ticket.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/pending-ticket.md).
2. Broad Intake (delegated). Triage ignore / error / include / note. Product-context extract only when the payload mixes personal and product. Autonomous scheduled mode is not intake.
3. Vague goal: Ask for 1-2 sentences, then Gate A.
4. Gate A: write plan + HANDOFF per pick. Backlog paths skip Gate B (`Mode: STOPPED` or current plan stays active).
5. Gate B (park or no-active-plan activate only): one unit, HANDOFF, stop. Suggest `/git-staging` if there is a diff. Manual mode: one phase per chat unless the operator used `/run-plan`.
## Opt-in public inbound nudge (factory)
When `publicInboundCheck.enabled` is true and the interval elapsed, after the default Gate Ask (never before it), optionally run `agent-kit public-inbound-radar --json --respect-prefs --stamp` and surface `/public-inbound-radar` route Ask if open items exist. Default off. Fail-open. See ADR `2026-09-24_public-inbound-radar.md`.Save a new plan for later without touching the plan in progress.
# Command: /backlog-add
## Goal
Enqueue a **new plan with to-dos** under HANDOFF Backlog without activating it, parking the current plan, or offering Gate B. Same Broad Intake scan as `/start-project`; activation gates are skipped on purpose. Plans inventory is `.cursor/context/plan-index.json` + `.cursor/HANDOFF.md` only (ADR `2026-07-26_command-orchestration-delegation-pattern.md`).
## When to Use
- You want a plan file and a Backlog row while the current active plan stays active
- You do not want park / activate / first-unit HITL from `/start-project`
- The goal is queueing work for later (`/continue-plan`, `/run-plan`, or `/run-plan-all`), not starting it now
## Usage
```
/backlog-add <goal>
```
Example: `/backlog-add Polish Mission Control empty-state icons`
## Hard stops
1. **Broad Intake Review first** (same buckets and triage labels as `/start-project`).
2. **Plan file + Backlog HANDOFF only** in the add turn. No product, registry, rule, or docs-of-record edits.
3. **Never park or activate.** Do not change `- **Plan:**`, phase, next to-dos, Parked list, or an in-flight Run queue.
4. **Never offer Gate B.** After write, report the path and stop.
5. **Do not invent Field Report cards** for routine enqueue.
6. **Never `/git-prod`.**
## Prepared repository
Same planning blockers as `/start-project`: unresolved essential readiness → point to `/agent-kit-onboard`. Non-essential pending is advisory only.
**Pending operator ticket:** only while `.cursor/context/gate-exit.json` has a pending entry, Ask `ticket` (`Read the ticket` / `Accept` / `Discard` / `Later`) before the write Ask, and list it as a Broad Intake `include` finding: [pending-ticket.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/pending-ticket.md).
**Never-Ask:** `confirm-provider` / `collaboration.provider` must not become an Ask. One-line advisory or silence, then continue Broad Intake → propose → write Ask. Do not halt enqueue. Distinct from an essential-readiness hard stop (that still points to `/agent-kit-onboard`). The Broad Intake worker inherits this: do not return a readiness-gate Ask for that check.
## What to Do
### 1. Broad Intake Review (required before plan proposal)
Same Broad Intake buckets, triage labels, and Task(explore) delegation as `/start-project`; the Plans bucket is index + HANDOFF only. Includes a post-write, post-default inbox Ask (`Analyze inbox now` / `Enqueue Fix now` / `Not now`, exact labels also in [hitl-gates SKILL.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md)) when Unprocessed is non-empty. Full detail: [procedure.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/backlog-add/procedure.md).
### 2. Vague goal
If the goal is missing or vague, use **Ask questions** (chat numbered-list fallback):
> "What's the goal to put on the backlog? (1-2 sentences)"
Wait before proposing.
### 3. Propose and confirm write
1. Propose phases and to-dos (align with `autogit/plan-routine.md` and `.cursor/context/templates/plan.md`).
2. Ask with **Ask questions** (one list; numbered-list fallback is path 1):
> "Write this plan to backlog (keep current active plan; no Gate B)?"
Options:
- `Write plan to backlog`
- `Modify proposal first`
- `Cancel`
3. **Cancel / skipped answer:** stop. No file or HANDOFF edits.
4. **Modify:** revise the proposal, ask again.
5. **Write plan to backlog:**
1. Create `.cursor/plans/<name>.plan.md` with frontmatter to-dos.
2. Append the basename under HANDOFF `- **Backlog plans:**` (canonical label; Checklist also accepts `- **Backlog:**`). Use the bullet field, never a `## Backlog plans` heading alone (Mission Control will not see the row).
3. Do not touch active plan fields, Parked plans, or Run queue blocks. Do **not** call `.cursor/scripts/run-plan-all-consolidate.sh` (that path is for `/run-plan-all` after confirm Ask only).
4. Stop. Tell the operator the plan path and that resume is via `/continue-plan` (or later queue inclusion), not Gate B.
## Boundaries
| Command | Difference |
|---------|------------|
| `/start-project` | May park/activate and offers Gate B when activating. Use when disposition is unknown. |
| `/continue-plan` | Starts a unit on a chosen plan. `/backlog-add` never starts units. |
| `/archive-plan` | Parked-list dispose. Not used here. |
## Ask questions requirement
Vague-goal clarify and write confirmation **must** use Ask questions per `.cursor/rules/hitl-ask-questions.mdc`. Chat fallback: one numbered list per message.
## Related
- ADR: `.cursor/memory/decisions/2026-07-26_backlog-crud-commands-contract.md`
- Disposition gate for `/start-project`: `.cursor/memory/decisions/2026-07-25_start-project-plan-disposition-gate.md`
- Cursor product-update gaps may route here via `/cursor-update-awareness` (Ask → `/backlog-add`)
- Public inbound rows may route here via `/public-inbound-radar` (Ask → `/backlog-add`; Dependabot is one batch)
## Opt-in public inbound nudge (factory)
When `publicInboundCheck.enabled` is true and the interval elapsed, after the write Ask (never before Broad Intake), optionally run `agent-kit public-inbound-radar --json --respect-prefs --stamp` and surface `/public-inbound-radar` route Ask if open items exist. Default off. Fail-open. See ADR `2026-09-24_public-inbound-radar.md`.Work through the active plan to-do by to-do until it is done or needs you, keeping the plan file and the handoff current.
# Command: /run-plan
## Goal
Run the **active plan** continuously until it is done or blocked. The agent picks the strategy (orchestrated when Task exists, in-session loop otherwise, headless `agent-kit run-plan`). Never `/git-prod` from this command.
HITL contract, exact Ask labels, numbered fallback (path 1): [hitl-gates](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md). Full tick contract: [run-plan-tick-contract.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/run-plan-tick-contract.md).
## Hard stops (kit failure if skipped)
1. **Never `/git-prod`.** Suggest it only after Final HANDOFF when staging is ahead of `main` (separate HITL).
2. **One to-do per tick.** Mark `in_progress` before work. Never stack the next to-do.
3. **Risk / API-limit stop.** PII, secrets, or ambiguous scope: Ask the risk labels. Quota or Task abort: revert the to-do to `pending`, HANDOFF the stop, do not reschedule or silent-inline.
4. **One Ask on the default path.** Inbox, owed-close, and landing Asks are opt-in or post-default, never pre-Ask blockers. Empty inbox: silent skip. Skip the inbox Ask inside a `/run-plan-all` per-plan Task.
5. **Exhaustion audits do not steal `/git-prod`.** Exit `3` is timeout-only and does not retroactively convert, upgrade, or rewrite a later monitor into success.
## Ask labels
| Gate | Labels |
|------|--------|
| Risk | `Continue with risk` / `Modify approach` / `Stop run` |
| Inbox (post-default) | `Analyze inbox now` / `Enqueue Fix now` / `Not now` |
| Exhaustion (post-default) | `Run review now` / `Always enable automatic` / `Not now` |
| Owed-close (post-default) | `Adopt existing monitor` / `Ack owed without review` / `Not now` |
| Pending ticket (preflight, id `ticket`) | `Read the ticket` / `Accept` / `Discard` / `Later` |
Numbered-list fallback is **path 1** when Ask questions is missing.
## Procedure
Check in first: `agent-kit queue lease` (also before each Ask and each plan-state write); `Queue lease held:` means stop and report that line; a `queue` usage message (older CLI) means skip the check. Out-of-queue run while `Queue status` is `running` or `paused`: set `held (by <plan>, <who>, <date>; was <previous>)` and restore it at the end ([tick contract](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/run-plan-tick-contract.md) section 1).
1. Read HANDOFF + plan + config. Preflight API-limit stop, pending operator ticket (Ask `ticket` only while `.cursor/context/gate-exit.json` has a pending entry; inside a `/run-plan-all` Task or `--no-hitl`, list the stamps instead: [pending-ticket.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/pending-ticket.md)), audits, unsatisfiable Claude reviewer, session-pile. Read a product-context extract when the plan points at one.
2. Next pending to-do. `force_task: true` or findings → Task. Lightweight docs-only → inline-first. Else Task or in-session.
3. Execute only that to-do. Findings-only for `review-*`. `autoRemediate` default false: no silent product fix.
4. Close: plan status, HANDOFF, cadence bump, `/git-staging` on a commitable diff. Staging ready: yes requires lint evidence (or `none applicable`). Dashboard HTML: `none applicable (dashboard-CSS)` covered by plugin-ux-validation. Contract string alone without that evidence is invalid.
5. Reschedule or stop (blocker, exhausted, user stop, API limit). Never `/git-prod`.
Persona chrome (`agentPersona.modes.run-plan`) after the command Ask, not instead of HITL. Default chat chrome: no cockpit emoji.Do only the next to-do of a plan, then stop so you can review it.
# Command: /continue-plan
## Goal
Resume a plan from the last handoff. Confirm the next unit, then execute **only that unit** (manual default).
HITL contract, exact Ask labels, and numbered fallback (path 1): [hitl-gates](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md). Resume detail is inline below (moved here from `hitl-gates/procedures.md` in Phase 1 of `contract-read-budget-lazy-layers-2026-09-19` — the 11-line resume section already fully overlapped this file's own Procedure, so it was folded in rather than kept as a separate one-line hop). Plans inventory is `.cursor/context/plan-index.json` + `.cursor/HANDOFF.md` only (ADR `2026-07-26_command-orchestration-delegation-pattern.md`).
## Hard stops (kit failure if skipped)
1. **Read `.cursor/HANDOFF.md` first.** No handoff: say so and suggest `/start-project`. Do not invent progress.
2. **API/usage-limit pre-flight.** If Mode / Gaps / Instruction still records an API/usage limit stop, do not mark a to-do `in_progress` until the operator confirms recovery. Numbered-list fallback is path 1.
3. **One Ask on the default path.** Confirm the next `[to-do-id]` before editing (or the multi-plan picker first when more than one resumable plan exists). Inbox, owed-close, and landing Asks are opt-in or post-default, never pre-Ask blockers. Empty inbox: silent skip.
4. **One unit per chat** unless the operator ran `/run-plan`.
5. **Do not start a competing plan.** New goal requires `/start-project`.
## Ask labels
**Default-path (next unit):** `Start [to-do-id]` / `Edit plan first` / `Switch to different plan` / `Stop here`
**Multi-plan picker (when needed):** `[plan-name.plan.md]` / `Create new plan instead`
**Inbox (post-default, Unprocessed non-empty):** `Analyze inbox now` / `Enqueue Fix now` / `Not now`
**Pending ticket (preflight, id `ticket`, only while `.cursor/context/gate-exit.json` has a pending entry):** `Read the ticket` / `Accept` / `Discard` / `Later`
Numbered-list fallback is **path 1** when Ask questions is missing.
## Procedure
1. Read HANDOFF + index. Do not glob `.cursor/plans/*.plan.md`. Check in: run `agent-kit queue lease` before the Ask and before each HANDOFF or plan write; `Queue lease held:` (exit 1) means another live session writes this workspace, so stop and report that line (no Ask, no write). A `queue` usage message (older CLI without the subcommand) is not a held lease: skip the check. A pending operator ticket is Asked before anything else: [pending-ticket.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/pending-ticket.md). If multiple resumable plans exist, Ask the picker first.
2. Default-path Ask for the next unit. Persona chrome after that Ask. Default chat chrome: no cockpit emoji.
3. On `Start [to-do-id]`: run only that unit; update plan status. Any other pick stops. When HANDOFF has `Queue status: running` or `paused` and the lease is free or stale, this is an out-of-queue run: write `- **Queue status:** held (by <plan>, <chat>, <date>; was <previous status>)` before the unit and put the previous status back when it ends.
4. When done: HANDOFF, stop, suggest `/git-staging` if there is a diff. Next phase: new conversation with `/continue-plan`.
5. Inbox skim may mention count after the entry Ask. Do not Ask inbox before it.
## Opt-in public inbound nudge (factory)
When `publicInboundCheck.enabled` is true and the interval elapsed, after the default-path Ask (never before it), optionally run `agent-kit public-inbound-radar --json --respect-prefs --stamp` and surface `/public-inbound-radar` route Ask if open items exist. Default off. Fail-open. See ADR `2026-09-24_public-inbound-radar.md`.Ship an urgent, narrow fix as a small plan of a few to-dos, then run it. It goes to staging, never straight to production.
# Command: /hotfix
## Goal
Ship a **narrow, urgent change** as a **mini plan**, then run it continuously with the same tick contract as `/run-plan` (status per to-do, HANDOFF each tick, `/git-staging` on diff, never `/git-prod`).
Use when the work is too small for a full `/start-project` Broad Intake cycle but still needs a plan panel, HANDOFF, and staging discipline.
## When to Use
- Cosmetic or single-surface fixes (icons, copy, one CSS token, one harness assertion)
- Operator-locked glyph/map choices already confirmed in chat
- You want continuous ticks ("in a row") without inventing a large multi-phase plan
Prefer `/start-project` for new features, ambiguous scope, or multi-domain work. Prefer `/backlog-add` when you only want to enqueue without running.
## Usage
```
/hotfix <goal>
```
Example: `/hotfix Monitor delivery subtype glyphs (BMP map locked in chat)`
## Hard stops
1. **Scope must be narrow.** If the goal needs Broad Intake, Gate A/B, or more than ~4 to-dos / 2 phases, stop and redirect to `/start-project` or `/backlog-add`.
2. **Confirm before write + run** with **Ask questions** (chat numbered-list fallback). Options:
- `Write mini plan and run`
- `Write mini plan only (stop)`
- `Modify proposal first`
- `Cancel`
3. **Never `/git-prod`.** Staging only via the `/run-plan` tick-close path.
4. **Park before activate when needed.** If HANDOFF `- **Plan:**` points at a plan with pending/in_progress to-dos, park it (append under `- **Parked plans:**`) before activating the hotfix plan. Exhausted/completed active plans may be replaced without a park row.
5. **Do not rewrite an in-flight `/run-plan-all` queue** (`- **Queue status:**` `running`). Finish, stop, or Ask to pause the queue first.
6. **API/usage limit pre-flight** same as `/run-plan` (refuse auto-run while HANDOFF still records a quota hard stop).
7. **Audits pre-flight** same as `/run-plan` / `/continue-plan` (`externalPlanReview.preflight`: `off` | `warn` | `block`).
## Persona
Reuse `agentPersona.modes.run-plan` (fallback Night Shift / `config.example.json`). Chat chrome only; HITL labels stay concrete.
## What to Do
### 1. Read state
- `.cursor/HANDOFF.md` (required)
- Goal from the slash message (or Ask if missing/vague)
- Skim theme-matched `.cursor/memory/plan-monitor-*.md` for open residuals (advisory; do not block solely on Review debt)
### 2. Propose a mini plan
Author a plan under `.cursor/plans/` with:
| Constraint | Rule |
|------------|------|
| Name | Prefer `hotfix-<slug>.plan.md` |
| Size | ≤ 4 to-dos, ≤ 2 phases (typical: lock → implement → tests/CHANGELOG) |
| Frontmatter | Always include `todos` with `status`; optional `read_scope` / `worker_contract` / `max_ticks` / `inline_first` |
| Body | Goal, locked decisions (glyphs, tokens), Acceptance, Constraints (out of scope) |
Align with `.cursor/context/templates/plan.md` and `autogit/plan-routine.md`. Skip full Broad Intake unless the goal is vague or conflicts with an open plan.
### 3. Confirm (HITL)
Ask questions with the four options above. **Cancel / skipped:** stop, no writes. **Modify:** revise and Ask again. **Write mini plan only:** write plan + set HANDOFF active (Mode `hotfix`), do **not** start ticks. **Write mini plan and run:** write, activate, then step 4.
### 4. Activate
Update `.cursor/HANDOFF.md`:
- `- **Plan:**` → hotfix plan basename
- `- **Mode:**` → `hotfix` (while running continuous ticks, agents may mirror `run-plan (<strategy>)` in Instruction; keep `hotfix` as the Mode root so Mission Control can recognize the path)
- Phase / next to-dos from the mini plan
- Preserve `- **Backlog plans:**` / `- **Parked plans:**` / queue fields unless parking the prior active plan
- When parking, say in the park row that it is for this hotfix only and name the plan to hand back to (the prior active plan, or the `/run-plan-all` queue cursor plan)
- If the hotfix plan was itself listed under `- **Backlog plans:**`, remove that row: a plan cannot be active and queued at once
### 5. Run (same tick contract as `/run-plan`)
Follow [`.cursor/commands/run-plan.md`](./run-plan.md) tick contract end-to-end:
1. Read state → next pending to-do → `in_progress`
2. Execute (orchestrated Task or in-session; inline-first rules unchanged)
3. Close tick: `completed` + HANDOFF + cadence bump + `/git-staging` on diff (add-by-name for monitors)
4. Reschedule until exhausted or blocked
Overrides vs full `/run-plan`:
- Default expectation is a **short** run (hours/minutes, not multi-day)
- External plan review at exhaustion: same `externalPlanReview` rules as `/run-plan` (enabled → autonomous or paste per `mode`; else `offerOnExhausted` Ask)
- Still never steal `/git-prod` confirmation
### 6. Exhausted
Final HANDOFF (`Mode: hotfix — STOPPED: plan exhausted` or equivalent). Suggest `/git-prod` only if staging is ahead of `main` (separate HITL).
**Hand back.** If step 4 parked a plan for this hotfix, or the HANDOFF has a `/run-plan-all` queue whose cursor plan still has open to-dos:
- `- **Plan:**` → that plan (the hotfix plan moves to a "Previous" note in the same row)
- Remove its row from `- **Parked plans:**` and `- **Backlog plans:**`
- `- **Mode:**` → STOPPED with the next owed step (for example `run-plan-all — STOPPED: awaiting operator merge of PR #N`), never a live run mode with no runner
Leaving `Plan:` on the exhausted hotfix plan makes Mission Control show the resumed queue as the completed hotfix.
## Typical flow
```
User: /hotfix Swap Monitor delivery subtype glyphs (map locked)
Agent: Mini plan proposed (3 to-dos). Ask: Write mini plan and run / …
User: [Write mini plan and run]
Agent: Writes hotfix-….plan.md → HANDOFF Mode hotfix → run-plan ticks → staging PRs → stop
```
## Relation to other commands
| Command | Difference |
|---------|------------|
| `/start-project` | Full Broad Intake + Gate A/B; not for tiny urgent patches |
| `/backlog-add` | Enqueue only; never activates or runs |
| `/run-plan` | Continuous runner for an **existing** active plan |
| `/run-plan-all` | Multi-plan queue; do not start a hotfix while queue `running` |
| `/continue-plan` | Manual one-unit gate; hotfix defaults to continuous |
## Troubleshooting
- **"Too large for /hotfix"** → `/start-project` or `/backlog-add`
- **"Queue running"** → stop or finish `/run-plan-all` first
- **"Ambiguous glyphs/tokens"** → Ask to lock the map before Write and runRun several plans as a queue, one after another, with one release per finished plan after your approval.
# Command: /run-plan-all
## Goal
Orchestrate multiple eligible plans as an ordered queue. The main window is a **pure orchestrator**: PO synthesis, HITL confirm, then one Task per plan running the `/run-plan` tick. When Ship auth is `per-plan-release`, this window then ships one release per completed plan. Plan Tasks never `/git-prod`.
HITL contract, exact Ask labels, numbered fallback (path 1): [hitl-gates](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md). PO synthesis, confirm queue, ship lane, and execute-queue detail: [run-plan-all-queue.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/run-plan-all-queue.md) (each queued plan's own tick runs [run-plan-tick-contract.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/run-plan-tick-contract.md)). Plans inventory is `.cursor/context/plan-index.json` + `.cursor/HANDOFF.md` only (ADR `2026-07-26_command-orchestration-delegation-pattern.md`). Asks only at four points (ADR `2026-09-25_run-plan-all-three-hitl-points.md`, amended): queue confirm, context checkpoint, novel error or expired wait, queue end with deferred rows.
## Hard stops (kit failure if skipped)
1. **One release per completed plan that has a product diff** when the confirm label sets Ship auth `per-plan-release`. `Run plans only` does not ship. Each ship is one SemVer, one `v*` tag, one promote. The next plan starts only after that ship is Done. A completed plan with no versionable product diff skips that release and the cursor advances. A red or unfinished post-prod verification, or a product diff that is not staging-ready, stops the queue (no extra patch, no next plan).
2. **Confirm before execute.** Default-path Ask is start-vs-resume (stored queue + Backlog that appeared after the last confirm) or the queue confirm (fresh synthesis). Record `- **Confirmed backlog:**` at confirm. Inbox Ask is opt-in or post-default, never a pre-Ask blocker. No silent resume that skips new-since-confirm Backlog.
3. **One Task per plan, sequential.** After the confirm Ask the orchestrator dispatches one Task subagent per queued plan. It must not implement to-dos, run tests, or write that plan's changelog. Mandatory execution Task is **per queued plan** after confirmation. No parallel plan Tasks. No co-pack with `/git-staging`. The ship lane starts only after that Task's summary is in.
4. **Missing or malformed summary:** Ask the user before advancing the cursor. Do not invent an outcome.
5. **Audits do not cut a second tag.** Mid-batch: one arm+wait, no triage Ask. Exit `3` is timeout-only and does not retroactively convert, upgrade, or rewrite a later monitor into success. Queue-end wait then `/plan-review-triage`.
## Ask labels
| Gate | Labels |
|------|--------|
| Inbox (post-default) | `Analyze inbox now` / `Enqueue Fix now` / `Not now` |
| Start vs resume | `Resume frozen queue` / `Insert new backlog` / `Re-synthesize` |
| Confirm queue | `Run as proposed` / `Run plans only` / `Edit order` / `Apply merges & drops only` / `Keep all plans as-is` / `Include Gate-B plans` / `Cancel` |
| Context checkpoint | `Continue queue` / `Stop and prepare handoff` / `Change queue` |
| Novel error / expired wait | `Retry recovery once` / `Hold and document` / `Stop the queue` |
| Queue end with deferred rows (id `queue-end-gates`) | `Resolve gates now` / `Print resolution prompt` / `Later` |
| Pending ticket (preflight, id `ticket`) | `Read the ticket` / `Accept` / `Discard` / `Later` |
`Run as proposed`, `Edit order`, `Apply merges & drops only`, and `Keep all plans as-is` set Ship auth `per-plan-release`. `Run plans only` sets `plans-only`. Numbered-list fallback is **path 1** when Ask questions is missing.
## Procedure
1. Pending operator ticket: only while `.cursor/context/gate-exit.json` has a pending entry, Ask `ticket` before the start-vs-resume or queue confirm (a preflight outside the three in-run points; ADR `2026-10-08_countdown-coming-home-generic-lane.md` point 3). Per-plan Tasks never Ask it; they list the stamps in their return: [pending-ticket.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/pending-ticket.md). Skim Unprocessed (mention only; inbox Ask is post-default). Preflight audit session-pile and unsatisfiable Claude reviewer (`warn`/`block` per `externalPlanReview.preflight`).
2. PO synthesis (Task explore; no `kind: resume`). Record per-plan ship expectations (intake runbook). On a stored queue, compare current Gate-A Backlog to `- **Confirmed backlog:**`. Resume when no new Backlog since confirm and queued files are valid. On new-since-confirm Backlog (or invalid queue item), Ask start-vs-resume.
3. Queue confirm on a fresh synthesis. Apply only approved consolidations via `.cursor/scripts/run-plan-all-consolidate.sh`. Write `- **Ship auth:**`, `- **Ship runbook:**`, and `- **Confirmed backlog:**` on HANDOFF.
4. Dispatch one `/run-plan` Task per queued plan. Worker skips chat exhaustion Ask and never `/git-prod`, checks in (`agent-kit queue lease`) before each Ask and plan write, and never reuses a worktree that `agent-kit sessions --live` lists with a live process. Record outcomes. A plan blocked on an operator gate is deferred (`deferred-operator`, no ship) and the queue continues with the next plan. Run the ship lane (consult intake runbook; self-recover before Ask) before advancing the cursor. At each plan boundary, if the orchestrator self-estimates about 50% or more window use, Ask the context checkpoint (Claude Code has no preCompact).
5. Mid-batch wait when `midBatchAudits` is on. Queue-end: Final HANDOFF, audits, `/plan-review-triage` path list. `plans-only` may then suggest `/git-prod` if staging is ahead of `main` (separate HITL). `per-plan-release` does not ship again at queue end. With `deferred-operator` rows, the last step is Ask `queue-end-gates` (`Resolve gates now` replays the gates' Asks and re-probes in-session).Check a release or a bug report against what the changelog claims: the install path, the tests and what actually changed.
# Command: /qa
## Goal
Test a **release**, **reproduce a bug**, or check that CHANGELOG feat/fix/chore claims work (install journey included). Consumers get this slash with L0. Playbook: [qa skill](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/qa/SKILL.md). HITL: [hitl-gates](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/SKILL.md). ADR: `2026-09-16_qa-l0-slash-no-new-agent.md`.
## Hard stops (kit failure if skipped)
1. **No new L0 agent.** Do not add `qa-engineer.md`. `test-suites` stays L1 pack `quality`; Task-dispatch it when present, else run `readiness.json` / profile `testCommands` in-session.
2. **One checkout per run.** Refuse to implement or install into a second repo. Ask before leaving the invocation root.
3. **Report, do not silent-fix.** Pass/fail with evidence. Residuals go through `/backlog-add`. Never invent Field Report cards for `/qa`.
4. **Not** `/plan-external-review` or `/plan-review-triage` (plan audits) and **not** `/dogfood` (inbox).
5. **Never `/git-prod`.** Never commit secrets. Landing stamp is factory-only (`HOSTINGER_API_TOKEN`).
## Ask labels
| Gate | Labels |
|------|--------|
| Mode (when ambiguous) | `QA this release` / `Repro this bug` / `Claims only` / `Cancel` |
| Scratch install | `Use a scratch git repo` / `QA this checkout only` / `Cancel` |
Numbered-list fallback is **path 1** when Ask questions is missing. Skipped or cancelled means stop.
## Procedure
1. Broad Intake (Plans = index + HANDOFF only). Ask for missing version, symptom, or checkout.
2. Build the claim matrix from CHANGELOG (public feat/fix/chore; factory private Changed when this is the factory). Docs are indicative.
3. Run the journey and tests the case needs. Hygiene-strip the report.
4. Return pass/fail with evidence. Enqueue residuals via `/backlog-add`. Stop.Bring your changes to the staging branch: Conventional Commits, a changelog entry and the checks your repository defines.
# Git staging
Follow the **git staging** routine to bring local changes to the pre-production branch (`origin/staging` in this repo, or the name configured for the project).
Factory landing wrap (not consumer L0): `/kit-staging` when that file exists. This command stays git-only.
**Auth-block hard stop:** After a successful SSH push, if `gh pr create` / `glab mr create` returns HTTP 401 (or another auth failure), print the compare/create URL and await. Stay on this command. Do not invent product (dotenv, L0, CHANGELOG, overlay hashes, hard-rules). Do not load `.env` as a GitHub token source. Details: Prompt git staging §9.
**Runs in the main window by default.** Do not dispatch this command to a Task subagent by default; Task isolation is opt-in and used only when the kit repo wants it.
1. **Read** the "Prompt: git staging" section in `autogit/gitupdate.md` (when it exists).
2. **Staging hygiene (monitors):** if `git status` shows untracked or unrelated dirty `.cursor/memory/plan-monitor-*.md`, **warn** before commit. Stage memory/monitor files **add-by-name only**; never broad `git add` of `.cursor/memory/` WIP into a product commit (ADR `decisions/2026-07-27_plan-monitor-consumer-awareness.md`, external-review staging hygiene). Warn/add-by-name forbids sweeps; it does **not** mean leave soft kit artifacts dirty. Inventory remaining safe dirt into a `docs(memory):` / `chore(kit):` bucket and ship it in this run (SoT: `autogit/gitupdate.md` Prompt git staging §1 and §7). Do not stop-and-quiz solely because a path looks out of the current flow.
3. **Lint evidence (required when code/format paths change):** before claiming staging-ready, **run** the repo formatter/linter on touched files and **record the command + result** (pass/fail) in the worker summary or tick notes. Writing `Staging ready: yes` or the contract string alone is **not** evidence. Pure markdown / docs-only with no applicable linter: state `none applicable`. Same gate as `/run-plan` Staging-ready lint gate.
**Dashboard CSS/HTML only** (`dashboard/dashboard.html` and similar, outside Biome scope): record `Tests: none applicable (dashboard-CSS); covered by plugin-ux-validation` when the UX suite pins the change (ADR `decisions/2026-07-29_dashboard-css-lint-evidence-convention.md`); do not claim Biome covered the HTML.
4. Run in order: validation (not on `main`), CHANGELOG (`[Unreleased]`), checkout staging, pull, working branch, Conventional Commits, push, MR/PR (**always `--base staging` / target `staging`**), merge, cleanup.
**Colony host:** when `COLONY_HOST_CLI` is set and the merge is operator-owed (refused or not allowed for the agent), file `"$COLONY_HOST_CLI" request merge-pr <N> --reason "<why>"` after the gates below and wait for its exit code instead of stopping the routine (0 merged: continue with cleanup; 2 denied by the operator: final for this run, stop and report the reason; 3 failed or 4 timeout: report, the merge stays operator-owed).
5. **Agent signature gate (hard stop, before push and before merge):** scan the outgoing commit messages and the PR body against the agent-signature / session-link pattern list embedded in `git-hooks/prepare-commit-msg` (`Co-Authored-By: Claude ...`, `Claude-Session:`, Cursor / Copilot / Codex / Devin trailers, `Generated with <agent>` lines, agent session URLs; `--list` prints it). Same shape as the Evidence-checks gate below: run, read the exit code, never merge over red.
- Before `git push`: `git log origin/staging..HEAD --format=%B | sh git-hooks/prepare-commit-msg --check -`
- Before `git push`, authors and committers: `sh git-hooks/prepare-commit-msg --check-authors origin/staging`. Exit 1 lists each outgoing commit whose author or committer address is an agent identity (`noreply@anthropic.com`, `cursoragent@cursor.com`, the Copilot bot, the other agent mail domains; `--list-authors` prints them). The check only reads; it never sets an identity or rewrites history.
On exit 1 **stop**: set your own identity (`git config user.name` / `user.email`; a cloud agent session sets `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` in its environment settings).
Then rewrite on the working branch: `git commit --amend --no-edit --reset-author` (last commit) or `git rebase --exec 'git commit --amend --no-edit --reset-author' origin/staging` (every outgoing commit), push again and re-run.
- After `gh pr create`, before `gh pr merge`: `gh pr view <N> --json body -q .body | sh git-hooks/prepare-commit-msg --check -`
Exit 0 prints `ok`. Exit 1 lists the offending lines with line numbers: **stop**, remove them (`git commit --amend` or `git rebase -i` on the working branch, `gh pr edit <N> --body` for the PR body), push again and re-run the scan. Exit 2 is a usage error (missing hook file, grep failure), not a pass: treat it as red. Do not route around a red scan with `--no-verify`, a hand-typed "ok", or a merge from the GitHub UI.
A squash merge folds every branch commit message into the staging commit, so a trailer left on any branch commit reaches `staging` and later `main`; that is what the pre-push scan catches. Catch it here: once that commit is merged on a protected `staging`, no PR can reword it, and `/git-prod` step 5 stops and names the operator-owned options (an operator-run history rewrite, or an exception by SHA the operator records in an Accepted ADR). ADR: `2026-09-11_agent-signature-guard-strip-hook-check-gate`.
6. **Evidence-checks gate (before merge / Gaps-none):** run `gh pr checks <N>` and confirm `build` (including the **Evidence checks** step) is green. If Evidence checks fail, fix and re-push before merge; do not write HANDOFF `- **Gaps:** none` over red. ADR: `2026-08-01_evidence-checks-merge-gate`.
7. **Never** commit directly to `main`.
8. On completion: update `.cursor/HANDOFF.md` (phase in staging); memory-loop WRITE if it applies.
9. Optional: update the project's PM tool (ClickUp, Jira, ...) if MCP is configured.Promote staging to production: closes the release and tags it, and never merges without your explicit yes.
# Git prod
Follow the **git prod** routine to promote `origin/staging` to `origin/main` (production):
Factory landing wrap (not consumer L0): `/kit-prod` when that file exists. This command stays git-only.
**Runs in the main window by default.** Do not dispatch this command to a Task subagent by default; Task isolation is opt-in.
1. **Read** the "Prompt: git prod" section in `autogit/gitupdate.md` (when it exists in the project).
2. Critical validation: no uncommitted local changes; never commit directly to main.
3. Close the release in the CHANGELOG (move `[Unreleased]` to a dated version) before merging. Keep `<!-- changelog-private -->` fences when the project uses them.
4. Show a summary of the changes (diff/log) between staging and main and **ask for explicit confirmation using Ask questions tool** before merging and pushing to main.
Options: `Proceed with production deploy` / `Review changes first` / `Cancel`
**Advisory (does not replace confirmation):** if Blocking untriaged `.cursor/memory/plan-monitor-*.md` match themes in the staging→main delta, mention them once in the summary. Never steal this Ask; Field Report / `/plan-review-triage` stay attention/HITL SoT.
**Fallback (path 1):** if Ask questions is missing, say so once, print the same three labels as a numbered list, accept number or label, and treat a typed answer as Other. Do not invent a fake tool call.
5. **Agent signature gate (hard stop, before merge to main):** after the confirmation and before any merge or push, scan everything that would reach `main`: `git log origin/main..origin/staging --format=%B | sh git-hooks/prepare-commit-msg --check -`.
Also scan the authors and committers of the same delta: `sh git-hooks/prepare-commit-msg --check-authors origin/main origin/staging`. Exit 1 lists each commit whose author or committer address is an agent identity: **stop**. A red commit not yet on `staging` is fixed through `/git-staging` (set your own identity, then `git commit --amend --no-edit --reset-author` or `git rebase --exec 'git commit --amend --no-edit --reset-author' <base>` on the working branch). Already merged on a protected `staging`: stop, never rewrite `staging`; the per-SHA continue rule below covers messages only and never clears an identity red. Option: an operator-run history rewrite.
When the promotion goes through a staging→main PR (the Claude CLI lane in `autogit/gitupdate.md`), also scan its body before merge: `gh pr view <N> --json body -q .body | sh git-hooks/prepare-commit-msg --check -`.
Exit 0 prints `ok`. Exit 1 lists the offending lines: **stop**. A red PR body is fixed with `gh pr edit <N> --body`; a red commit that is not yet on `staging` is fixed through `/git-staging` (reword it on a working branch); then re-run this step from the top.
**Red commit already merged on a protected `staging`:** no PR can reword it. Do not rewrite or force-push `staging`, squash-promote, edit a ruleset, or narrow the scan.
Name the operator-owned options and wait: an operator-run history rewrite (ruleset bypass, reword, force-push), or an operator-accepted exception by SHA recorded in an Accepted ADR in the project's decisions.
Continue past the red scan only when every red commit is a SHA the operator accepted there, checked per commit, never by editing the pinned command: list `git log origin/main..origin/staging --format=%H`, run `git log -1 --format=%B <sha> | sh git-hooks/prepare-commit-msg --check -` on each, and every SHA that exits 1 must be on that accepted list. The agent never accepts a SHA; a PR body or a commit not yet on `staging` never gets an exception.
Exit 2 (missing hook file, grep failure) is red, not a pass. Never merge, push, or tag over a red scan. Same shape as the Evidence-checks gate in `/git-staging`; pattern list: `sh git-hooks/prepare-commit-msg --list`. ADR: `2026-09-11_agent-signature-guard-strip-hook-check-gate`.
6. **One confirm, one ship:** `Proceed with production deploy` authorizes exactly one SemVer close, one annotated `v*` tag, and one promote. A red post-prod verification (step 11) is a STOP; it does not authorize another patch under the same yes. Eventually-consistent row: poll with bounded backoff. Next ship needs a new Ask.
`/run-plan-all` only: when HANDOFF `- **Ship auth:**` is `per-plan-release`, skip step 4. That queue confirm is this plan's yes. Still one tag. A red post-prod verification stops the queue.
7. Run merge to main (`git merge --no-ff` when promoting locally; real merge preferred on the staging→main PR path). Prepare local main (merge and signature scan green) before any push.
**Claude Code lane (or a recorded classifier denial of this push):** Do not run `ALLOW_MAIN_PUSH=1 git push origin main`. Ask with these exact labels:
- `I pushed main`
- `Open staging→main PR instead`
- `Cancel`
**On `I pushed main`:** The operator already pushed. Verify `origin/main` advanced, then continue with the annotated tag, staging sync, and the report. Do not run the push.
**On `Open staging→main PR instead`:** Reset local `main`, tree untouched: `git switch <staging> && git branch -f main origin/main`. GitHub: advisory `agent-kit promote rules --base main`, then `gh pr create --base main --head staging`; wait with `agent-kit promote wait --pr <N>` only (exit 3 = Ask `promote-merge-wait`). Both `promote` commands are GitHub-only; GitLab (MR with `squash=false`, `remove_source_branch=false`, bounded MR-state poll): [promote-merge-wait.md](https://github.com/agent-kit-startup/agent-kit/blob/main/.cursor/skills/core/hitl-gates/promote-merge-wait.md). Prefer a merge commit; never merge it yourself.
**On `Cancel`:** Stop. Do not tag, push, or open a PR.
**Other lanes:** Push with the authorized inline form `ALLOW_MAIN_PUSH=1 git push origin main`, then continue with the annotated tag. Bare `git push origin main` stays denied by `agent-kit guard shell` and `git-hooks/pre-push`. Keep it on one line (the guard denies an env prefix split off with a `\` continuation). Do not export `ALLOW_MAIN_PUSH=1` as a session environment variable. Do not add `--force`, `--no-verify`, or a non-main destination.
Details: `autogit/gitupdate.md` Prompt git prod step 9.
8. **Sync staging (mandatory):** immediately after `main` is pushed, if `git merge-base --is-ancestor origin/staging origin/main`, fast-forward staging with `git merge --ff-only origin/main` and push. Do not open a merge PR that only records `origin/main` as ancestor. If staging is not an ancestor, stop and report; do not back-merge in this prod session. Details: `autogit/gitupdate.md` step 10.
9. Update `.cursor/HANDOFF.md` ("promoted to production") and memory-loop WRITE if it applies.
10. Annotated `v*` tags trigger whatever tag CI the project configures. Before pushing the first `v*` tag, run the project's release preflight when it defines one (a wrapper command or `autogit/gitupdate.md` step 9.5 names it); red is a STOP before the tag.
11. **Post-prod verification (mandatory):** before ending, report `autogit/gitupdate.md` step 12. If the project defines post-prod release verification (e.g. a factory wrapper command), run it; otherwise **Done** = `origin/main` pushed, tag pushed, tag CI green, all on the same `vX.Y.Z`. Red is a **STOP** (no next patch under this yes). Eventually-consistent row: poll with bounded backoff; Ask only on timeout.
12. **Close-release / tags:** bump every version manifest the project keeps (in a consumer project `.cursor/agent-kit.json` records the installed kit, not a product manifest; a wrapper command may list extra manifests); never force-move an already-pushed `v*` tag. Release-close stays its own PR to staging (do not bundle with a main-back-merge or product fix). Retry via a new **patch** tag when the fix must republish (**new** `/git-prod` confirm); **hold** (manifests stay on the tagged SemVer, no new tag) when the existing tarball is enough; local-only recreate before first push. Same rule as `autogit/gitupdate.md` SemVer / step 9.5.Write down where the work stands, so a new chat or another agent picks it up without you explaining it again.
# Command: /handoff
## Goal
Update the handoff document to preserve current state and allow continuation in a new conversation.
**Runs in the main window by default.** Do not dispatch this command to a Task subagent by default; Task isolation is opt-in and used only when the kit repo wants it.
## When to Use
- At the end of each phase of a plan
- When context is getting full
- Before pausing work for an extended period
- When you want to record progress
## What to Do
1. **Check the active task:**
- Check whether a Context Pack exists in `.cursor/context/current/`
- Check whether an active plan exists in `.cursor/plans/`
2. **Update `.cursor/HANDOFF.md` with machine-field bullets** (Mission Control parses `- **Field:**` only; do not invent `## Backlog plans` / `## Parked plans` headings):
- `- **Plan:** \`file.plan.md\`` (or `none`)
- Last updated (timestamp)
- Phase completed
- Completed to-dos (ids)
- Next phase
- Next to-dos (ids)
- Clear instruction for the next agent (1-3 sentences)
- Keep `- **Backlog plans:**` / `- **Parked plans:**` / queue fields as bullets when present
3. **Handoff preference (first time / when offering a choice):** if the user has no saved preference in `.cursor/context/config.json`, or you are offering automatic vs manual handoff, use the **Ask questions** tool (not typed yes/no).
Options: `Automatic handoff` / `Manual handoff`
**Fallback (path 1):** if Ask questions is missing, say so once, print the same two labels as a numbered list, accept number or label, and treat a typed answer as Other. Do not invent a fake tool call.
If they pick automatic, save `{ "autoHandoff": true }` in `.cursor/context/config.json`.
4. **DevOps spine (suggest, do not run without being asked):**
- If the phase produced commitable changes (including versioned HANDOFF, `plan-monitor-*.md`, or `_index.md` Audits rows), suggest `/git-staging`. That command follows `autogit/gitupdate.md` inventory → theme-bucket → ship. Do not treat HANDOFF/memory as skippable dirt.
- If there was an error or a tradeoff decision, suggest a memory-loop WRITE (`.cursor/memory/`).
- Never suggest committing directly to `main`; production only via `/git-prod` after staging. `/git-prod` still requires a clean tree except hard excludes; staging must leave it that way.
5. **Respond to the user:**
> "Handoff updated! Continue: `/continue-plan`. With code ready: `/git-staging`. Production: `/git-prod`."
## CLI alternative
```bash
./cursor-handoff handoff
# or: agent-kit handoff
```
This updates HANDOFF.md based on the active plan / Context Pack.
## Full loop
```
plan -> work -> /handoff -> /git-staging -> (approval) -> /git-prod -> memory
```Lost track? See where the project stands on one screen: what is done, what is left and the next step.
# Command: /summary
## Goal
Give a quick summary of the current state for a user who lost track of progress.
## When to Use
- When the user seems lost
- When they ask "where are we?", "what's left?", "summary"
- After long gaps without interaction
## What to Do
1. **Identify context:**
- Read `.cursor/HANDOFF.md` if it exists
- Read the active Context Pack if it exists
- Consider the current conversation history
2. **Build a 3-part summary:**
- **Done:** short list (max 3 items)
- **In progress:** current task/to-do
- **Left to do:** next steps (max 3 items)
3. **Ask for the next step** using **Ask questions** tool (fallback to chat if tool unavailable):
> "Want to continue where we left off, or do something else?"
Options: `Continue where we left off` / `Something else` / `Show more detail`
## Response format
```
Quick summary
Done:
- Folder structure created
- Basic auth implemented
In progress:
- Implement refresh token (to-do: refresh-token)
Next:
- Auth tests
- API documentation
Continue with the refresh token, or move to something else?
```
## Tip
Keep the summary short. If the user wants details, they will ask.Open Mission Control in your browser: the plans, runs, health and memory of this repository.
# Command: /dashboard
## Goal
Start (or reuse) Mission Control for **this workspace only**, then open the printed URL in **one** browser target: the IDE browser MCP (required path below). Do not open Chrome, Safari, Firefox, or other external browsers in addition. Preferred OS browser applies only when the operator runs `agent-kit dashboard` / `npm run dashboard` without `--no-open`.
Local-dev only. Read-only. No HITL gate unless `missionControl.preferredBrowser` is unset/`ask` and the operator wants to persist a preference (optional Ask; see step 4).
**Terminal / IDE-agnostic invoke:** `agent-kit dashboard` or `npx @dadado/agent-kit-cli dashboard` from the workspace cwd (ships `dashboard/start.mjs` since 4.8.2). Fallbacks: env `MISSION_CONTROL_KIT_ROOT` / `AGENT_KIT_HOME`, sibling `../agent-kit`, or `node "$KIT_ROOT/dashboard/start.mjs"` with `MISSION_CONTROL_REPO_ROOT` set to this git root.
## When to Use
- Inspect plans / HANDOFF / git / memory for **the open workspace**
- Reload the panel after plan or HANDOFF changes (run this command again; starter reuses the same port when already up)
- Several workspaces open: each keeps its **own** instance and port. Never expect one shared `:3333` for every project.
## What to Do (required order)
### 1. Resolve roots
```bash
# Prefer nearest Agent Kit install over git toplevel (nested monorepo packages).
SNAPSHOT_ROOT="$(pwd)"
d="$(pwd)"
while [ "$d" != "/" ]; do
if [ -f "$d/.cursor/agent-kit.json" ]; then
SNAPSHOT_ROOT="$d"
break
fi
d="$(dirname "$d")"
done
if [ ! -f "$SNAPSHOT_ROOT/.cursor/agent-kit.json" ]; then
SNAPSHOT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
fi
```
Find `KIT_ROOT` (directory that contains `dashboard/start.mjs`):
1. `$SNAPSHOT_ROOT` if `dashboard/start.mjs` exists there
2. Else `$MISSION_CONTROL_KIT_ROOT` or `$AGENT_KIT_HOME` (absolute)
3. Else sibling `$(dirname "$SNAPSHOT_ROOT")/agent-kit` when that tree has `dashboard/start.mjs`
4. Else prefer running `agent-kit dashboard` (CLI resolves a Path C bundled `dashboard/start.mjs` from the installed package when present)
If none exist: stop and tell the operator to reinstall a Path C CLI, set `MISSION_CONTROL_KIT_ROOT`, or keep a sibling `agent-kit` checkout. Do **not** start a random other project's panel.
### 2. Start or reuse (always use the kit starter)
Do **not** hand-roll `serve.mjs` + `kill` on 3333. The starter picks a stable port for this `SNAPSHOT_ROOT` (range `3333–3588`), reuses when `system.repoRoot` already matches, and **never kills** another workspace.
```bash
export MISSION_CONTROL_REPO_ROOT="$SNAPSHOT_ROOT"
export HOST=127.0.0.1
unset MISSION_CONTROL_TOKEN
unset PORT
cd "$KIT_ROOT"
MISSION_CONTROL_NO_OPEN=1 node dashboard/start.mjs
```
Capture the printed URL (example: `http://127.0.0.1:3511/`). That URL is authoritative; it is often **not** `:3333`.
Running this again in the same repo is the **reload** path: same URL, same instance, fresh snapshots via SSE/poll.
### 3. Confirm this workspace owns the URL
In a **separate** shell call:
```bash
curl -sf "${MC_URL}dashboard-data.json" | node -e 'let d="";process.stdin.on("data",c=>d+=c);process.stdin.on("end",()=>{const j=JSON.parse(d); console.log(j.system?.repoRoot, j.system?.port)})'
```
`system.repoRoot` must equal `SNAPSHOT_ROOT`. If it does not, do not open that URL; re-run step 2 and use the new printed URL.
### 4. Open the panel (single path)
**Invariant:** open **at most one** browser surface. Never launch multiple external browsers.
1. Optional Ask (only when `.cursor/context/config.json` → `missionControl.preferredBrowser` is missing, null, or `"ask"`, and the operator may want a saved OS preference for CLI opens): labels `Keep IDE browser only` / `Remember preferred browser for CLI` / `Skip open`. If they pick remember, set `missionControl.preferredBrowser` to an app name (e.g. `Google Chrome`) or leave null for OS default on future CLI opens. Slash `/dashboard` itself still uses the IDE MCP path below (not a second OS open).
2. Name the single browser MCP for **this** IDE lane, not one fixed tool id: Cursor → `cursor-ide-browser`; Claude Code → the Claude in Chrome extension. That MCP → `browser_navigate` (or its lane's equivalent) with `newTab: true` and the **printed** `MC_URL` (**only** this navigate; do not also run `open` / `xdg-open` / MCP + OS).
3. If result is `chrome-error://chromewebdata/`: connection refused; fix step 2/3, then navigate **once** more (still a single surface). If instead the extension renders its own **error page** (not `chrome-error://chromewebdata/`) while step 3's `curl` already returned HTTP 200: this is a **site-permission** failure, not a dead server — see the Troubleshooting row below. Do not spend the one retry on it; a repeat navigate cannot grant the permission.
4. Copy the URL for the operator (`pbcopy` on macOS). Mention Simple Browser as a **manual** fallback for the human, not as a second agent-driven open.
### 5. Verify
Wait for the `Live` badge (~3–5s) or curl the JSON again. Header should show this workspace's basename. Confirm plan/HANDOFF counts look like **this** repo, not the kit monorepo.
## Hard rules
| Do | Do not |
|----|--------|
| Set `MISSION_CONTROL_REPO_ROOT` to the nearest Agent Kit install (or git toplevel when none) | Assume `http://localhost:3333` |
| Use `node "$KIT_ROOT/dashboard/start.mjs"` | `kill` a listener to "free" 3333 for another project |
| Open the **printed** URL once (IDE MCP) | Reuse HTTP 200 on any port without checking `system.repoRoot`; open every installed browser |
| Leave other workspaces' Mission Control running | Start `serve.mjs` from a kit tree without `MISSION_CONTROL_REPO_ROOT` |
## Notes
- Preferred browser for CLI/OS opens: `missionControl.preferredBrowser` in `.cursor/context/config.json`, env `MISSION_CONTROL_PREFERRED_BROWSER`, or `agent-kit dashboard --browser "App Name"`. ADR `2026-08-11_mission-control-preferred-browser.md`.
- Snapshot (plans, HANDOFF, git, memory) = `MISSION_CONTROL_REPO_ROOT`. Static UI = kit tree that hosts `dashboard/`.
- Explicit `PORT` overrides hashing; if that port belongs to another root, start refuses (no kill).
- Loopback only by default. LAN: `/dashboard-broadcast` (token-gated).
- Stop **this** panel only: kill the PID on **this** `system.port` whose `repoRoot` matches; never another project's instance.
- File actions stay copy-only (Quick Open paste). Checklist **Run all** copies `/run-plan-all`; it does not execute from the panel.
- Consumer L0 ships this command text, not `dashboard/**`.
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Panel shows kit plans / wrong HANDOFF | Missing `MISSION_CONTROL_REPO_ROOT` or opened another workspace's URL | Re-run step 2; open printed URL; check header basename |
| Expected `:3333` | Per-workspace port allocation | Use printed URL / `system.port` |
| `chrome-error://chromewebdata/` | Server not listening on that URL | Re-run starter; navigate again |
| Browser MCP shows its own error page while `curl "${MC_URL}"` returns 200 | Extension lacks site permission for `127.0.0.1` / loopback (private-network handling varies by extension) | Do **not** retry navigate — a permission gap does not clear on repeat. Check the browser MCP's loopback/site permission for this origin; if it cannot be granted from here, copy the URL (`pbcopy`) and hand it to the operator to open manually. Dogfood: `dogfood/cursor_dashboard_claude_code_browser_mcp_error_page_2026_09_11.md`. |
| `PORT … will not kill another workspace` | Explicit `PORT` held by another root | `unset PORT` and re-run starter |
| `No dashboard/start.mjs found` | Consumer-only tree | Set `MISSION_CONTROL_KIT_ROOT` / `AGENT_KIT_HOME`, sibling `../agent-kit`, or `npx @dadado/agent-kit-cli@latest dashboard` |
| `403 Forbidden` on CLI package fetch | Registry auth policy or private scope | `npm login`, check `.npmrc`, or use env/sibling fallback |
| Empty skeletons | Cold snapshot | Wait for `Live` |