git:20260719.727cff9 to git:20260917.83580e3

---

name: pan-plan

description: "pan plan <id> — 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 <id>` 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 <id>` 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 <id> [--auto] [--auto-start] [--probe] [--model <model>] [--harness claude-code|pi|codex] [--effort low|medium|high] [--local|--remote]

pan plan finalize [-w <path>] [--json] [--no-promote] [--no-quality-lint] [--no-prd]

pan plan done <id> [--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 <id>` 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 <id>` 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 <id>` instead.

## Finalizing (`pan plan finalize`)

```bash

pan plan finalize

```

What it does:

2. Validates the tasks already stored in `plan.items[]`, including their declared dependencies.

3. Flips the spec's `plan.status` from `draft` to `proposed`.

5. Returns a summary of finalized xBRIEF tasks and promotion status, or JSON with `--json`.

Use `-w <path>` 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.

### 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 `<ISSUE-ID>.md` (uppercase then lowercase) under `<projectRoot>/.pan/drafts/` then `<workspace>/.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 <id> --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.

## 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

```

## 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.

- `docs/SKILLS-CONVENTION.md` — skill/CLI naming convention.