@qball-inc/the-bulwark 1.0.0

package/skills/plan-creation/SKILL.md

@@ -0,0 +1,497 @@
+---
+name: plan-creation
+description: Create structured implementation plans using a 4-role scrum team with optional Agent Teams peer debate
+user-invocable: true
+argument-hint: "<topic, filepath, or directory> [--research <synthesis-file>]"
+skills:
+  - subagent-prompting
+---
+
+# Plan Creation
+
+Create structured implementation plans through a 4-role collaborative scrum team: Product Owner, Technical Architect, Engineering & Delivery Lead, and QA/Critic. The Product Owner explores the codebase first, then Architect and Eng Lead analyze in parallel, and the QA/Critic challenges everything last. The orchestrator synthesizes all outputs into a hybrid Markdown + YAML plan.
+
+---
+
+## When to Use This Skill
+
+**Load this skill when the user request matches ANY of these patterns:**
+
+| Trigger Pattern | Example User Request |
+|-----------------|---------------------|
+| Implementation planning | "Create an implementation plan for X" |
+| Feature planning | "Plan how we'd build X" |
+| Project scoping | "Break down X into phases and workpackages" |
+| Post-research planning | "We've researched X, now create a plan" |
+| Task brief creation | "Create a task brief for X" |
+
+**DO NOT use for:**
+- Initial topic research (use `bulwark-research` first)
+- Feasibility brainstorming (use `bulwark-brainstorm`)
+- Quick technical questions (ask directly)
+- Code review or debugging (use `code-review` or `issue-debugging`)
+
+---
+
+## Dependencies
+
+| Category | Files | Requirement | When to Load |
+|----------|-------|-------------|--------------|
+| **Plan output template** | `templates/plan-output.md` | **REQUIRED** | Load at Stage 5 for plan structure |
+| **Critic output template** | `templates/critic-output.md` | **REQUIRED** | Include in QA/Critic agent prompt |
+| **Synthesis template** | `templates/synthesis-output.md` | **REQUIRED** | Use when writing synthesis |
+| **Diagnostic template** | `templates/diagnostic-output.yaml` | **REQUIRED** | Use at Stage 6 |
+| **Role output reference** | `templates/role-output.md` | OPTIONAL | Reference for parsing agent outputs |
+| **Subagent prompting** | `subagent-prompting` skill | **REQUIRED** | Load at Stage 1 for 4-part prompt template |
+| **Research synthesis** | `--research <file>` | OPTIONAL | If provided, include in all agent prompts |
+
+**Fallback behavior:**
+- If an agent fails to spawn: Re-spawn once. If still fails, skip that role and document in synthesis under "Incomplete Coverage"
+- If PO fails: STOP — all downstream agents depend on PO output. Inform user.
+- If output template is missing: Use the schema from this SKILL.md directly
+- If research synthesis not provided: Agents work from problem statement alone (warn user that quality may be lower)
+
+---
+
+## Mandatory Execution Checklist (BINDING)
+
+**Every item below is mandatory. No deviations. No substitutions. No skipping.**
+
+This skill uses a multi-stage pipeline. You are the orchestrator. Follow every item in order. Do NOT return to the user until all applicable items are checked.
+
+- [ ] **Stage 1 — Pre-Flight**: Topic parsed (from argument, --doc, or AskUserQuestion)
+- [ ] **Stage 1 — Pre-Flight**: subagent-prompting skill loaded
+- [ ] **Stage 1 — Pre-Flight**: If topic is ambiguous or under-specified, AskUserQuestion interview conducted (2-3 questions per round)
+- [ ] **Stage 1 — Pre-Flight**: If --research not provided, user warned via displayed message AND asked to confirm proceeding
+- [ ] **Stage 1 — Mode Detection**: `$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var checked — you MUST check this, no exceptions
+- [ ] **Stage 1 — Mode Detection**: If env var is SET, user offered choice via AskUserQuestion (Agent Teams vs Task tool) — you MUST NOT default silently
+- [ ] **Stage 1 — Mode Detection**: If user selects Agent Teams, AT Confirmation Flow executed (RED banner + model class choice)
+- [ ] **Stage 2 — Product Owner**: PO spawned via Task tool (`plan-creation-po`, Opus) and output read
+- [ ] **Stage 3A or 3B**: Correct mode executed based on user's Stage 1 choice
+- [ ] **Stage 3A (Task tool)**: Architect + Eng Lead spawned in parallel, then QA/Critic spawned with all 3 prior outputs
+- [ ] **Stage 3B (Agent Teams)**: Agent files read, delegate mode entered, 3 teammates spawned with correct model class
+- [ ] **Stage 5 — Synthesis**: ALL role outputs read, synthesis written, plan drafted using template
+- [ ] **Stage 5 — Approval**: Plan presented to user via AskUserQuestion — you MUST NOT write the final plan without user approval
+- [ ] **Stage 5 — Plan Written**: Final plan written to `plans/{slug}/plan_v{N}.md`
+- [ ] **Stage 6 — Diagnostics**: Diagnostic YAML written to `$PROJECT_DIR/logs/diagnostics/`
+
+---
+
+## Usage
+
+```
+/plan-creation <topic-or-prompt> [--research <synthesis-file>]
+/plan-creation --doc <path-to-document> [--research <synthesis-file>]
+```
+
+**Arguments:**
+- `<topic-or-prompt>` - Free-text topic description or problem statement
+- `--doc <path>` - Use a document as the topic source
+- `--research <synthesis-file>` - Path to research synthesis (from bulwark-research or bulwark-brainstorm). Strongly recommended.
+
+**Examples:**
+- `/plan-creation "add user authentication" --research logs/research/auth/synthesis.md`
+- `/plan-creation --doc plans/proposal.md`
+- `/plan-creation "migrate database to PostgreSQL"`
+
+**Plan Versioning:**
+
+Plans are written to `plans/{slug}/plan_v{N}.md` with automatic version detection:
+
+| Scenario | Version | Example |
+|----------|---------|---------|
+| First plan for a topic | `v1` | `plans/add-auth/plan_v1.md` |
+| Minor revision (user iterates on current plan) | `v1.1`, `v1.2` | Approval gate feedback → revision |
+| Major version (full re-run or pivot) | `v2`, `v3` | New invocation for same slug |
+
+The skill checks for existing `plans/{slug}/plan_v*.md` files before writing. When ambiguous (re-run vs revision), it asks the user.
+
+---
+
+## Stages
+
+### Stage 1: Pre-Flight
+
+```
+Stage 1: Pre-Flight
+├── Read problem statement / document
+├── Load research synthesis if --research provided
+├── AskUserQuestion if ambiguous (iterative, 2-3 questions per round)
+├── Slugify topic for output directory
+├── Create output directory: $PROJECT_DIR/logs/plan-creation/{slug}/
+├── Load subagent-prompting skill
+├── Detect mode: Task tool (default) or Agent Teams (opt-in)
+└── Token budget check (warn if >30% consumed)
+```
+
+**AskUserQuestion Protocol (Pre-Spawn):**
+
+If the problem statement is ambiguous, under-specified, or could benefit from scope boundaries:
+
+1. Ask 2-3 clarifying questions using AskUserQuestion
+2. Assess whether the answers provide sufficient clarity to construct high-quality prompts
+3. If not, ask up to 3 more questions in a follow-up round
+4. Repeat until clarity is achieved (no hard cap on rounds, but each round is 2-3 questions max)
+5. If the problem statement is clear and well-scoped from the start, skip this step and note in diagnostics: `pre_flight_interview: skipped (problem statement sufficient)`
+
+If `--research` was not provided, warn the user: "No research synthesis provided. Plan quality is significantly higher when preceded by `/bulwark-research` or `/bulwark-brainstorm`. Proceed without research?"
+
+**Mode Detection:**
+
+1. Check `$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var
+2. If env var is SET: offer user choice via AskUserQuestion — "Agent Teams enhanced mode is available. Use Agent Teams or Task tool?" Default to Task tool if user doesn't specify.
+3. If env var is NOT SET: use Task tool mode. If user explicitly requested Agent Teams, notify: "Agent Teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Using Task tool mode."
+
+**AT Confirmation Flow (if user selects Agent Teams):**
+
+Execute this confirmation flow BEFORE spawning any teammates:
+
+**Step 1 — Display RED warning banner** using ANSI color `\033[38;2;255;154;150m` (#FF9A96):
+
+```
+⚠️  NOTICE: Claude Code's Agent Teams is an experimental feature. Unexpected
+issues like teammates being stuck or unresponsive may occur. Agent Teams mode
+is also significantly more token-expensive than Task tool mode (4 concurrent
+agents vs sequential sub-agents).
+
+If you run into issues, start a new session and re-run /plan-creation.
+If the final output does not match expectations, re-run with Task tool mode.
+```
+
+**Step 2 — AskUserQuestion: model class + mode confirmation**
+
+Present a single question with 3 options:
+
+| Option | Label | Description |
+|--------|-------|-------------|
+| 1 | Opus agents (Recommended) | Higher quality analysis, highest token cost. Opus-class agents for all roles. |
+| 2 | Sonnet agents | Good quality, lower token cost. Sonnet-class agents for all roles. |
+| 3 | Switch to Task tool mode | Cancel Agent Teams and use sequential sub-agents instead. |
+
+- Option 1: proceed with Opus agents in AT mode (Stage 3B)
+- Option 2: proceed with Sonnet agents in AT mode (Stage 3B)
+- Option 3: fall back to Task tool mode (Stage 3A), skip AT entirely
+
+### Stage 2: Product Owner (Opus, Sequential — First)
+
+```
+Stage 2: Product Owner
+├── Construct prompt using 4-part template
+│   ├── GOAL: Explore codebase and produce requirements analysis for {topic}
+│   ├── CONSTRAINTS: Do not make architectural decisions or estimate effort
+│   ├── CONTEXT: Problem statement + research synthesis (if available)
+│   └── OUTPUT: $PROJECT_DIR/logs/plan-creation/{slug}/01-product-owner.md
+├── Spawn plan-creation-po agent via Task tool
+│   ├── subagent_type: plan-creation-po
+│   ├── model: opus (specified in agent frontmatter)
+│   ├── Agent autonomously explores codebase (Glob, Grep, Read)
+│   └── NO hardcoded document paths — agent discovers what's relevant
+├── Read PO output from logs/plan-creation/{slug}/01-product-owner.md
+└── Token budget check
+```
+
+**CRITICAL — PO Autonomy**: The PO agent MUST NOT receive hardcoded project document paths. Instead:
+
+- PO receives the problem statement and (optionally) research synthesis
+- PO is spawned as `plan-creation-po` subagent type
+- PO autonomously explores the codebase using Glob, Grep, Read
+- PO output documents which files it read and why
+
+This makes the skill portable across any project.
+
+### Stage 3A: Scrum Team — Task Tool Mode
+
+```
+Stage 3A: Scrum Team (Task Tool Mode)
+├── Read PO output in full
+├── Construct 2 prompts using 4-part template:
+│   ├── Technical Architect:
+│   │   ├── GOAL: Analyze system design, components, integration, trade-offs for {topic}
+│   │   ├── CONSTRAINTS: Do not estimate effort or sequence work
+│   │   ├── CONTEXT: Problem statement + research synthesis + PO output (full text)
+│   │   └── OUTPUT: $PROJECT_DIR/logs/plan-creation/{slug}/02-technical-architect.md
+│   └── Engineering & Delivery Lead:
+│       ├── GOAL: Produce WBS, estimates, dependencies, milestones, risk register for {topic}
+│       ├── CONSTRAINTS: Do not redesign architecture — work with Architect's design
+│       ├── CONTEXT: Problem statement + research synthesis + PO output (full text)
+│       └── OUTPUT: $PROJECT_DIR/logs/plan-creation/{slug}/03-eng-delivery-lead.md
+├── Spawn BOTH agents in parallel via Task tool (single message, 2 Task tool calls)
+│   ├── subagent_type: plan-creation-architect (opus)
+│   └── subagent_type: plan-creation-eng-lead (sonnet)
+├── Read both outputs
+└── Token budget check (checkpoint if >55%)
+```
+
+**CRITICAL**: Spawn both agents in a single message with 2 Task tool calls. Do NOT spawn sequentially.
+
+**Note**: Both Architect and Eng Lead receive the PO output directly in their prompt CONTEXT. They do NOT read each other's output — they work independently in parallel. The QA/Critic cross-references their outputs in Stage 4.
+
+### Stage 3B: Scrum Team — Agent Teams Mode (Enhanced, Opt-In)
+
+**Pre-condition**: User selected Agent Teams in Pre-Flight AND confirmed model class in AT Confirmation Flow.
+
+```
+Stage 3B: Scrum Team (Agent Teams Mode)
+├── Read PO output in full (from Stage 2)
+├── Read agent definition files from .claude/agents/:
+│   ├── .claude/agents/plan-creation-architect.md
+│   ├── .claude/agents/plan-creation-eng-lead.md
+│   └── .claude/agents/plan-creation-qa-critic.md
+├── YOU (the orchestrator) become the delegate-mode Scrum Lead
+│   └── Your role: coordination ONLY — do not perform analysis yourself
+├── Enter delegate mode with 3 teammates
+├── Create shared task list with initial tasks:
+│   ├── "[Architect] Analyze system design for {topic}"
+│   ├── "[Eng Lead] Produce WBS and delivery plan for {topic}"
+│   └── "[QA/Critic] Adversarially review all analyses for {topic}"
+├── Spawn 3 teammates using agent file content as system prompts:
+│   ├── Technical Architect (model: user's choice from AT Confirmation)
+│   ├── Engineering & Delivery Lead (model: user's choice from AT Confirmation)
+│   └── QA / Critic (model: user's choice from AT Confirmation)
+├── Each teammate prompt MUST include (in addition to agent file content):
+│   ├── Problem statement + research synthesis (if available)
+│   ├── PO output (full text)
+│   ├── Dual-output contract (see below)
+│   ├── CC-to-lead instruction (see below)
+│   ├── Task list coordination instruction (see below)
+│   └── Rendezvous instruction (see below)
+├── Use in-process display mode (WSL2 safe — no tmux)
+├── Shutdown gate: see below
+└── Token budget check
+```
+
+**Dual-Output Contract** (include in EVERY teammate prompt):
+
+> You MUST produce two outputs:
+> 1. **Full analysis** → Write to `$PROJECT_DIR/logs/plan-creation/{slug}/{NN}-{role-name}.md` using the Write tool. This is your SA2-compliant artifact. Include all analysis, tables, and findings.
+> 2. **Coordination summary** → Send a 3-5 sentence summary of your key findings and conclusions to the Scrum Lead via mailbox. This is for coordination only — the full analysis is in the log file.
+
+**CC-to-Lead Instruction** (include in EVERY teammate prompt):
+
+> When sending peer DMs to other teammates with work instructions, challenges, or significant findings, also send a 1-line summary to the Scrum Lead. Example: "Sent Architect a challenge on component coupling — see my full analysis in logs."
+
+**Task List Coordination Instruction** (include in EVERY teammate prompt):
+
+> When you receive work from a peer via DM (e.g., "review this section", "stress-test this estimate"), create a new task in the shared task list describing the peer-dispatched work before starting it. Mark it in_progress immediately. This gives the Scrum Lead visibility into peer-coordinated work.
+
+**Rendezvous Instruction** (include in EVERY teammate prompt):
+
+> Your FINAL action before going idle is to send the Scrum Lead: "WORK COMPLETE — all tasks done, log written to {path}". Do NOT go idle without sending this message.
+
+**Shutdown Gate** (Scrum Lead logic — YOU enforce this):
+
+The Scrum Lead (you, the orchestrator) MUST NOT call `requestShutdown` for ANY teammate until ALL of the following are true:
+
+1. All shared task list tasks are in terminal state (completed or blocked)
+2. WORK COMPLETE message received from ALL 3 teammates
+3. All 3 log files exist and are non-empty:
+   - `logs/plan-creation/{slug}/02-technical-architect.md`
+   - `logs/plan-creation/{slug}/03-eng-delivery-lead.md`
+   - `logs/plan-creation/{slug}/04-qa-critic.md`
+
+If a teammate appears idle but has NOT sent WORK COMPLETE:
+- Check the shared task list for in-progress tasks assigned to that teammate
+- Send a status check message: "Status update? Are you still working on [task]?"
+- Do NOT send `requestShutdown` — they may be executing a long tool call
+
+**AT Completion Banner** (display after ALL teammates shut down):
+
+After Agent Teams execution completes successfully, display an AMBER banner using ANSI color `\033[38;2;255;244;176m` (#FFF4B0):
+
+```
+ℹ️  Agent Teams is an experimental feature. If the final plan does not match
+your expectations, try re-running /plan-creation with Task tool mode
+(sequential sub-agents). Individual role outputs are preserved in
+logs/plan-creation/{slug}/ for inspection.
+```
+
+Then proceed to Stage 5 (Synthesis) — Stage 4 is skipped in AT mode.
+
+**CRITICAL — Agent File Reuse**: The 3 agent files in `.claude/agents/` contain the role expertise (system prompts, output formats, tool constraints). For AT mode, read each file's content and use it as the teammate's system prompt. This keeps a single source of truth per role — the agent files serve both Task tool mode (via `subagent_type`) and AT mode (content embedded in teammate prompts).
+
+**Note**: In AT mode, the QA/Critic participates throughout — it can challenge the Architect and Eng Lead via peer DMs during their analysis, not just after. This is the primary quality advantage over Task tool mode.
+
+---
+
+### Stage 4: QA / Critic (Sonnet, Sequential — Last, Task Tool Mode ONLY)
+
+```
+Stage 4: QA / Critic
+├── Load templates/critic-output.md
+├── Read ALL 3 prior output files:
+│   ├── 01-product-owner.md
+│   ├── 02-technical-architect.md
+│   └── 03-eng-delivery-lead.md
+├── Construct prompt using 4-part template
+│   ├── GOAL: Adversarially review all prior analyses — challenge assumptions, identify gaps, stress-test estimates, produce APPROVE/MODIFY/REJECT verdict
+│   ├── CONSTRAINTS: Do not redesign or re-plan — only challenge and validate
+│   ├── CONTEXT: Problem statement + research synthesis + ALL 3 prior outputs (full text) + critic-output.md template
+│   └── OUTPUT: $PROJECT_DIR/logs/plan-creation/{slug}/04-qa-critic.md
+├── Spawn plan-creation-qa-critic agent via Task tool
+│   ├── subagent_type: plan-creation-qa-critic
+│   └── model: sonnet (specified in agent frontmatter)
+├── Read Critic output
+└── Token budget check
+```
+
+**CRITICAL**: The QA/Critic MUST receive ALL 3 prior outputs in full. This is the entire point — the Critic cross-references PO requirements against Architect components against Eng Lead workpackages to find gaps.
+
+**Skip condition**: If Agent Teams mode was used (Stage 3B), skip Stage 4 entirely — the QA/Critic already participated throughout Stage 3B via peer debate. Proceed directly to Stage 5.
+
+### Stage 5: Synthesis & Plan Output (SHARED — Mode-Aware)
+
+```
+Stage 5: Synthesis
+├── Read ALL 4 agent output files (MANDATORY — do not skip any):
+│   ├── logs/plan-creation/{slug}/01-product-owner.md
+│   ├── logs/plan-creation/{slug}/02-technical-architect.md
+│   ├── logs/plan-creation/{slug}/03-eng-delivery-lead.md
+│   └── logs/plan-creation/{slug}/04-qa-critic.md
+├── If Agent Teams mode: also review lead coordination notes from the AT session
+├── If any output is missing or empty → re-spawn that agent once (max 1 retry)
+│   └── In AT mode: re-spawning is NOT possible — document gap in "Incomplete Coverage"
+├── If retry fails → document gap in synthesis under "Incomplete Coverage"
+├── Load templates/synthesis-output.md
+├── Load templates/plan-output.md
+├── Write synthesis to $PROJECT_DIR/logs/plan-creation/{slug}/synthesis.md
+├── Compose plan draft:
+│   ├── Executive Summary from synthesis consensus + PO problem statement
+│   ├── YAML body from:
+│   │   ├── Phases and workpackages: Eng Lead's WBS + Architect's component structure
+│   │   ├── Milestones: Eng Lead's milestones
+│   │   ├── Dependency graph: Eng Lead's dependency analysis + Architect's integration order
+│   │   ├── Risks: Consolidated from all roles, prioritized by Critic
+│   │   └── Kill criteria: From Critic's verdict
+│   └── Apply Critic's MODIFY requirements (if verdict was MODIFY)
+├── Present draft plan to user via AskUserQuestion approval gate
+├── Critical Evaluation Gate (see below)
+├── Determine plan version:
+│   ├── Glob for existing plans/{slug}/plan_v*.md
+│   ├── If none found: version = v1 (first plan)
+│   ├── If user is iterating on the current plan (minor revision): bump minor (v1 → v1.1, v1.1 → v1.2)
+│   ├── If user is starting fresh or pivoting: bump major (v1 → v2, v2 → v3)
+│   └── When ambiguous, ask user: "This is a revision of the existing plan (v1.1) or a new plan (v2)?"
+├── On approval: write final plan to plans/{slug}/plan_v{N}.md
+└── Token budget check (must be <65% after synthesis)
+```
+
+**Enforcement**: Do NOT begin writing synthesis until ALL available agent outputs have been read. The orchestrator must reference every agent's output at least once in the synthesis.
+
+#### Critical Evaluation Gate (Post-User Q&A)
+
+After each AskUserQuestion round, do NOT blindly incorporate user responses. Instead:
+
+**Step 1 — Classify each user response:**
+
+| Classification | Definition | Action |
+|---------------|------------|--------|
+| **Preference** | Scope, priority, or UX choice (e.g., "I'd prefer v1 to focus on X", "Let's defer Y") | Incorporate directly. These are user decisions — no validation needed. |
+| **Technical Claim** | Assertion about a technology, library, or API (e.g., "Library X supports this", "That API has rate limits") | **Do NOT incorporate.** Trigger Step 2. |
+| **Architectural Suggestion** | Proposed structural approach (e.g., "What if we structure it as a plugin?", "We could use event sourcing") | **Do NOT incorporate.** Trigger Step 2. |
+
+**Step 2 — For Technical Claims and Architectural Suggestions, present to user:**
+
+> "Your suggestion about [X] involves a technical claim / architectural approach that hasn't been validated against the codebase and research. I recommend a targeted follow-up with 2 focused agents (Technical Architect + QA/Critic) to verify feasibility and stress-test the approach.
+>
+> This will spawn 2 agents and consume additional token budget.
+>
+> [Run follow-up validation / Incorporate as-is with LOW confidence caveat]"
+
+**Step 3 — If follow-up validation approved:**
+
+1. Spawn 2 agents in parallel (single message, 2 Task tool calls):
+   - **Technical Architect** (`plan-creation-architect`) — validates the suggestion against the codebase and research
+   - **QA/Critic** (`plan-creation-qa-critic`) — stress-tests the suggestion
+2. Use the same 4-part prompt template (GOAL/CONSTRAINTS/CONTEXT/OUTPUT)
+3. Provide both agents with: original research synthesis, PO output, and the specific user suggestion
+4. Output to: `$PROJECT_DIR/logs/plan-creation/{slug}/followup-{NN}-architect.md` and `followup-{NN}-critic.md`
+5. Read both outputs, then update plan with validated findings
+6. Tag follow-up findings in plan with: `[Follow-up: validated]` or `[Follow-up: refuted]` or `[Follow-up: mixed — see details]`
+
+**Step 4 — If user declines follow-up:**
+
+Incorporate the user's suggestion into the plan with an explicit caveat:
+> **[Unvalidated — user suggestion, not verified against codebase or research]**: {suggestion}
+
+**Repeat**: After updating the plan, ask if user has additional input. Apply the same classification gate to each round. Each round with Technical Claim / Architectural Suggestion input that triggers validation consumes ~10-15% token budget (2 agents) — warn user if approaching 55%.
+
+### Stage 6: Diagnostics (REQUIRED)
+
+```
+Stage 6: Diagnostics
+├── Write diagnostic YAML to $PROJECT_DIR/logs/diagnostics/plan-creation-{YYYYMMDD-HHMMSS}.yaml
+└── Verify Mandatory Execution Checklist (top of skill)
+```
+
+---
+
+## Execution Flow (F# Pipeline)
+
+```fsharp
+// Task tool mode (default)
+ProductOwner(topic, research?)                          // Stage 2: Opus, solo
+|> [Architect, EngDeliveryLead](po_output)              // Stage 3A: parallel Task tool
+|> QACritic(all_prior_outputs)                          // Stage 4: sequential Task tool
+|> Synthesis |> ApprovalGate |> PlanOutput(plan_v{N})   // Stage 5: versioned output
+
+// Agent Teams mode (enhanced, opt-in)
+ProductOwner(topic, research?)                          // Stage 2: Opus, Task tool (solo)
+|> AgentTeam[Architect, EngDeliveryLead, QACritic](po_output)  // Stage 3B: peer debate
+|> Synthesis |> ApprovalGate |> PlanOutput(plan_v{N})   // Stage 5: versioned output
+// Note: Stage 4 skipped in AT mode — QA/Critic participates throughout Stage 3B
+```
+
+---
+
+## Token Budget Management
+
+| Checkpoint | Threshold | Action |
+|------------|-----------|--------|
+| After constructing PO prompt | >30% consumed | Warn user: "4 agents will consume significant context" |
+| After reading Stage 3A outputs | Running tally | If approaching 55%, checkpoint with user |
+| After synthesis | Must be <65% | Leave room for plan approval + session closing |
+| Synthesis complete at >65% | Immediate | Write plan as-is, create handoff, do not start additional work |
+
+If token budget is insufficient to complete all 4 agents + synthesis, inform the user and suggest splitting (e.g., "PO + Architect/Eng Lead this session, Critic + synthesis next session").
+
+---
+
+## Error Handling
+
+**Both modes:**
+
+| Scenario | Action |
+|----------|--------|
+| Agent returns empty output | Re-spawn once. If still empty, document gap in synthesis. |
+| Agent returns truncated output | Accept as-is, note in diagnostics. |
+| Agent fails to spawn | Re-spawn once. If still fails, skip role, document. |
+| PO fails | STOP — subsequent agents depend on PO. Inform user. |
+| Token budget exceeded mid-session | Stop spawning, synthesize from available outputs, note incomplete. |
+| Research synthesis not provided | Warn user, proceed with lower quality. |
+| User rejects plan draft | Ask what needs to change, re-enter Critical Evaluation Gate. |
+
+**Agent Teams mode only:**
+
+| Scenario | Action |
+|----------|--------|
+| Teammate appears stuck (no WORK COMPLETE, no task updates) | Send status check via mailbox. Wait for response before any shutdown attempt. |
+| Teammate never sends WORK COMPLETE | After status check + 1 follow-up, check if log file was written. If log exists and is non-empty, treat as implicit completion. Document in diagnostics. |
+| Peer DM traffic invisible to lead | Expected — this is an AT architectural constraint. Rely on CC-to-lead summaries and task list state. |
+| One teammate fails, others succeed | Document gap. Do NOT shut down working teammates — let them complete. Synthesize from available outputs. |
+| AT env var absent but user requested AT | Notify user, fall back to Task tool mode (Stage 3A). |
+| User selects "Switch to Task tool" in AT Confirmation | Execute Stage 3A instead. No AT infrastructure spawned. |
+
+---
+
+## Diagnostic Output (REQUIRED)
+
+**MANDATORY**: You MUST write diagnostic output after every invocation. This is Stage 6 and cannot be skipped.
+
+Write to: `$PROJECT_DIR/logs/diagnostics/plan-creation-{YYYYMMDD-HHMMSS}.yaml`
+
+**Template**: Use `templates/diagnostic-output.yaml` for the schema. Fill in actual values from the session.
+
+---
+
+
+**Do NOT return to user until all applicable checkboxes can be marked complete.**