plan

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 1: Parse and Validate (inline)

Reference: skills/shared/config-loading.md for the tooling shortcut (state load, plan-index, phase-info) and config field reference.

1. Parse $ARGUMENTS for phase number and flags
2. If --model <value> is present in $ARGUMENTS, extract the value (sonnet, opus, haiku, inherit). Store as override_model. When spawning researcher, planner, and plan-checker Task() agents, use override_model instead of the config-derived model values. If an invalid value is provided, display an error and list valid values.
3. If --auto is present in $ARGUMENTS: set auto_mode = true. Log: "Auto mode enabled — suppressing confirmation gates"
4. If --through <M> is present:

a. Read planning.multi_phase from config b. If planning.multi_phase is false or unset: display error: "--through requires planning.multi_phase: true in config. Set it with: /pbr:config set planning.multi_phase true" Then STOP. c. Parse start phase (N) and end phase (M). Validate both exist in ROADMAP.md. d. Store through_phases = [N, N+1, ..., M] e. Log: "Multi-phase planning: phases {N} through {M}"

• If --prd <file> is present in $ARGUMENTS:

a. Extract the file path from the argument b. Set prd_mode = true c. Log: "PRD express path — will generate CONTEXT.md from PRD, skip discussion"

1. CRITICAL — Init first. Run the init CLI call as the FIRST action after argument parsing:

``bash node plugins/pbr/scripts/pbr-tools.js init plan-phase {N} ` Store the JSON result as blob. All downstream steps MUST reference blob fields instead of re-reading files. Key fields: blob.phase.dir, blob.phase.goal, blob.phase.depends_on, blob.config.depth, blob.config.profile, blob.researcher_model, blob.planner_model, blob.checker_model, blob.existing_artifacts, blob.workflow.research_phase, blob.workflow.plan_checking, blob.drift. Speculative mode guard: If $ARGUMENTS contains --speculative or --no-state-update, SKIP the .active-skill write below — the autonomous orchestrator owns .active-skill during speculative planning. CRITICAL (hook-enforced): Write .active-skill NOW. Write the text "plan" to .planning/.active-skill` using the Write tool.

1. Resolve depth profile: run `pbr-tools config resolve