--- name: pan-plan description: "pan plan — start issue planning, including non-interactive --auto mode; also finalize/done planning artifacts" triggers: - pan plan - plan issue - auto plan - plan finalize - plan done - finalize planning - complete planning allowed-tools: - Bash - Read - Glob - Grep --- # Overdeck Planning Lifecycle `pan plan ` is the plan-ONLY verb: it starts a planning session for an issue and produces a PRD and xBRIEF, but it does not start the work agent. Use `pan start ` when you want planning and work in one command. Use `--auto` when the user wants the planning agent to run non-interactively and infer defensible defaults. Use `--probe` when the plan needs an adversarial pre-finalize self-pass; `--effort high` enables the same probe instructions automatically. ## Available commands ```bash pan plan [--auto] [--auto-start] [--probe] [--model ] [--harness claude-code|pi|codex] [--effort low|medium|high] [--local|--remote] pan plan finalize [-w ] [--json] [--no-promote] [--no-quality-lint] [--no-prd] pan plan done [--no-prd] ``` ## Starting planning ```bash pan plan PAN-1071 ``` This calls the dashboard planning endpoint, creates the planning workspace, and starts the planning agent. The dashboard can also start the same flow from the issue card's **Plan…** action. ## Auto-planning ```bash pan plan PAN-1071 --auto ``` Auto-planning runs the same planning agent without interactive questions: - The agent must not ask the user questions. - Ambiguous but non-contradictory choices are resolved with defensible defaults. - Inferred choices are recorded in `plan.autoDecisions[]` with a summary and rationale. - The agent escalates only when authoritative inputs genuinely contradict each other. The dashboard issue card's **Auto-plan** action sends the same `auto: true` request. ## Probe pass ```bash pan plan PAN-1071 --probe ``` `--probe` adds an adversarial self-review section to the planning prompt before finalize. The planner attacks hidden assumptions, ambiguous "done" criteria, unhandled failure modes, and missing dependency edges, then records acted-on findings in `continue.json` decisions with a `PROBE:` prefix. `--effort high` includes this section automatically. ## Auto-start after planning ```bash pan start PAN-1071 ``` `pan start ` is the paved-road way to plan (non-interactively by default) and start the work agent in one command. The work agent auto-starts after planning finalizes. The legacy `--auto-start` flag on `pan plan ` is deprecated and kept only through the deprecation window. It stamped `autoSpawnOnFinalize: true` into the planning agent state so `pan plan finalize` could start the work agent after it promoted the plan; use `pan start ` instead. ## Finalizing (`pan plan finalize`) Run this from inside the planning workspace after the planning agent has produced a complete `.overdeck/spec.vbrief.json`. ```bash pan plan finalize ``` What it does: 1. Reads `.overdeck/spec.vbrief.json` from the current workspace (walks up if needed). 2. Validates the tasks already stored in `plan.items[]`, including their declared dependencies. 3. Flips the spec's `plan.status` from `draft` to `proposed`. 4. Calls the dashboard's complete-planning endpoint to promote the canonical spec into `.pan/specs/` in the project repo (or the configured plan-home repo for polyrepo projects), commit and push the feature branch, transition the tracker state to Planned, and terminate the planning session — same flow as `pan plan done` and the dashboard Done button. 5. Returns a summary of finalized xBRIEF tasks and promotion status, or JSON with `--json`. Use `-w ` to point at another workspace. Use `--no-promote` to leave the spec at `status=proposed` without promoting (rare; for humans who want to review the plan in the dashboard before clicking Done). Finalize runs xBRIEF quality lint by default; use `--no-quality-lint` only as a loud one-run emergency bypass when the plan must be promoted despite known quality issues. Use `--critic` to require a plan critique (see "Plan critic" below) on an issue that has no critic label. ### PRD-first gate Finalize and complete-planning refuse to promote a plan unless a **PRD draft** of at least 20 lines exists for the issue. `roles/plan.md` has always required the PRD as the first artifact; this gate makes it mechanical. The gate searches, in order, for `.md` (uppercase then lowercase) under `/.pan/drafts/` then `/.pan/drafts/`; the first existing file with ≥20 lines satisfies it. A found-but-thinner draft fails with its line count; a fully missing draft fails naming the canonical path to write. `pan start --auto` is structurally exempt (it synthesizes a minimal xBRIEF and never POSTs complete-planning, so the gate cannot block it). Use `--no-prd` (on `finalize` or `done`) only for a genuinely trivial issue that went through interactive planning anyway — it prints a yellow `⚠ PRD gate SKIPPED` warning and tells the endpoint to skip the check too. ### Plan critic A flagged plan gets one independent critique before finalize promotes it (PAN-4341). A plan is flagged when its issue carries the label `architecture`, `substrate-improvement` or `security`, or when finalize runs with `--critic`. There is no bypass flag; the operator's bypass is removing the label. If the labels cannot be read, finalize warns and treats the plan as not flagged. - **Config.** Set `roles.plan.sub.critic.model` in `~/.overdeck/config.yaml` to a model from a different family than the planner (for example a GPT model under a Claude planner). There is no default. When it is unset or in the planner's family, finalize refuses. - **Dispatch.** On a missing or stale critique, finalize starts one read-only worker named `plan-critic-r` on that model, waits up to 540 s for its report, and writes `.pan/drafts/-critique.md` (round 2: `-critique-2.md`) next to the PRD. Line 1 is `plan-digest: ` of the draft without lifecycle and finalize-stamp fields. - **Findings.** Each finding is a heading `## blocks-the-design: `, `## sharpens-framing: <title>` or `## footnote: <title>`. Only `blocks-the-design` findings block. - **Answering.** Answer each `blocks-the-design` finding with a `### <title>` heading under `## Critique response` in the PRD, then re-run finalize. Change the draft only when the finding requires it; a changed draft makes the critique stale and starts the next round. Never edit the critique file. - **Cap.** After two rounds finalize proceeds, and complete-planning lists unanswered titles under `### Unresolved after two critic rounds` in the PRD. - **Exit code.** Any critique-gate refusal exits 5. With `--json` it prints `{ "success": false, "error": "Plan critique gate failed", "message", "critiqueGate" }`. The Done button and `pan plan done` verify the same gate and return 422 when a required critique is missing; they never start a critic. When the issue is flagged, run `pan plan finalize` with a 600 s Bash timeout or `run_in_background: true`; a finalize killed mid-wait leaves the critic running, and the next run waits on it. ## Completing planning (`pan plan done`) `pan plan done <id>` exists for cases where finalize was run with `--no-promote`, or where a planning agent crashed between writing the spec and promoting. It calls the same complete-planning endpoint that `finalize` chains to. ```bash pan plan done PAN-1071 ``` This promotes the workspace xBRIEF to `.pan/specs/` in the project repo, syncs xBRIEF tasks, and transitions the tracker state to Planned. It is subject to the same PRD-first gate as `finalize`; pass `--no-prd` only for a genuinely trivial issue. ## Related commands - `pan start <id>` — the paved road: plan (if needed) and start implementation in one command. - `pan tell <id> <message>` — send feedback to a running planning or work agent. - `pan kill <id>` — stop a planning or work agent without deleting the workspace. ## See also - `roles/plan.md` — planning role prompt. - `docs/XBRIEF.md` — xBRIEF schema, artifact locations, lifecycle states.