/plan

name: plan
description: "Create a detailed plan for a phase. Research, plan, and verify before building."
allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion, Skill
argument-hint: "<phase-number> [--skip-research] [--assumptions] [--gaps] [--model <model>] [--auto] [--through <N>] [--prd <file>] | add | insert <N> | remove <N>"

**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**

/pbr:plan-phase — Phase Planning

**References:** `@references/questioning.md`, `@references/ui-brand.md`

You are the orchestrator for `/pbr:plan-phase`. This skill creates detailed, executable plans for a specific phase. Plans are the bridge between the roadmap and actual code — they must be specific enough for an executor agent to follow mechanically. Your job is to stay lean, delegate heavy work to Task() subagents, and keep the user's main context window clean.

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• **Minimize** reading subagent output — read only plan frontmatter for summaries. Exception: if `context_window_tokens` in `.planning/config.json` is >= 500000, reading full plan bodies is permitted when content is needed for inline decisions.
• **Delegate** all research and planning work to subagents — the orchestrator routes, it doesn't plan

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► PLANNING PHASE {N}                         ║
╚══════════════════════════════════════════════════════════════╝

Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.

Multi-Session Sync

Before any phase-modifying operations (writing PLAN files, updating STATE.md/ROADMAP.md), acquire a claim:

acquireClaim(phaseDir, sessionId)

If the claim fails (another session owns this phase), display: "Another session owns this phase. Use `/pbr:progress` to see active claims."

On completion or error (including all exit paths), release the claim:

releaseClaim(phaseDir, sessionId)

Prerequisites

• `.planning/config.json` exists (run `/pbr:new-project` first)
• `.planning/ROADMAP.md` exists with at least one phase
• `.planning/REQUIREMENTS.md` exists

---

Argument Parsing

Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.

Standard Invocation

`/pbr:plan-phase <N>` — Plan phase N

Parse the phase number and optional flags:

| Argument | Meaning | |----------|---------| | `3` | Plan phase 3 | | `3 --skip-research` | Plan phase 3, skip research step | | `3 --assumptions` | Surface assumptions before planning phase 3 | | `3 --gaps` | Create gap-closure plans for phase 3 (from VERIFICATION.md) | | `3 --teams` | Plan phase 3 using specialist agent teams | | `3 --model opus` | Use opus for all researcher, planner, and checker spawns in phase 3 | | (no number) | Use current phase from STATE.md | | `3 --preview` | Preview what planning would produce for phase 3 without spawning agents | | `3 --audit` | Plan phase 3, then force full plan-checker validation | | `3 --auto` | Plan phase 3 with auto mode — suppress confirmation gates, auto-advance on success | | `1 --through 3` | Plan phases 1 through 3 in a single planner session (requires planning.multi_phase: true) | | `3 --prd path/to/prd.md` | Plan phase 3 using a PRD file as input — skip discussion, generate CONTEXT.md from PRD |

Subcommands

| Subcommand | Meaning | |------------|---------| | `add` | Append a new phase to the end of the roadmap | | `insert <N>` | Insert a new phase at position N (uses decimal numbering) | | `remove <N>` | Remove phase N from the roadmap |

Freeform Text Guard — CRITICAL

**STOP. Before ANY context loading or Step 1 work**, you MUST check whether `$ARGUMENTS` looks like freeform text rather than a valid invocation. This check is non-negotiable. Valid patterns are:

• Empty (no arguments)
• A phase number: integer (`3`, `03`) or decimal (`3.1`)
• A subcommand: `add`, `insert <N>`, `remove <N>`
• A phase number followed by flags: `3 --skip-research`, `3 --assumptions`, `3 --gaps`, `3 --teams`, `3 --auto`, `3 --prd <file>`
• A phase number followed by --through and another number: `1 --through 3`
• The word `check` (legacy alias)

If `$ARGUMENTS` does NOT match any of these patterns — i.e., it contains freeform words that are not a recognized subcommand or flag — then **stop execution** and respond:

`/pbr:plan-phase` expects a phase number or subcommand.

Usage:
  /pbr:plan-phase <N>              Plan phase N
  /pbr:plan-phase <N> --gaps       Create gap-closure plans
  /pbr:plan-phase add              Add a new phase
  /pbr:plan-phase insert <N>       Insert a phase at position N
  /pbr:plan-phase remove <N>       Remove phase N

Then suggest the appropriate skill based on the text content:

| If the text looks like... | Suggest | |---------------------------|---------| | A task, idea, or feature request | `/pbr:todo` to capture it, or `/pbr:explore` to investigate | | A bug or debugging request | `/pbr:debug` to investigate the issue | | A review or quality concern | `/pbr:verify-work` to assess existing work | | Anything else | `/pbr:explore` for open-ended work |

Do NOT proceed with planning. The user needs to use the correct skill.

**Self-check**: If you reach Step 1 without having matched a valid argument pattern above, you have a bug. Stop immediately and show the usage block.

---

Orchestration Flow: Standard Planning

Execute these steps in order for standard `/pbr:plan-phase <N>` invocations.

---

Step