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:

Subcommands

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:

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
   • 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.
   • If --auto is present in $ARGUMENTS: set auto_mode = true. Log: "Auto mode enabled — suppressing confirmation gates"
   • 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"
2. CRITICAL — Init first. Run the init CLI call as the FIRST action after argument parsing:

   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.
3. Resolve depth profile: run `pbr-tools config resolve