claude-raid 0.1.7 → 0.2.2

package/template/.claude/skills/{raid-design → raid-canonical-design}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: raid-design
-description: "Phase 1 of Raid protocol. Wizard opens the Dungeon, agents explore freely from different angles, challenge and build on each other directly, and pin verified findings. Wizard closes when design is battle-tested."
+name: raid-canonical-design
+description: "Phase 2 of Canonical Quest. Agents explore design approaches from different angles based on PRD. Battle-tested design doc with mermaid diagrams. No code writing. Question chain: agents→wizard→human."
 ---
 
-# Raid Design — Phase 1
+# Raid Design — Phase 2
 
 Turn ideas into battle-tested designs through agent-driven adversarial exploration.
 
@@ -11,6 +11,12 @@ Turn ideas into battle-tested designs through agent-driven adversarial explorati
 Do NOT write any code, scaffold any project, or take any implementation action until the Wizard has approved the design and it is committed to git. All assigned agents participate. Agents communicate via SendMessage — do not spawn subagents.
 </HARD-GATE>
 
+## Scope Check
+
+Before asking detailed questions, assess scope. If the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend rounds refining details of a project that needs decomposition first.
+
+If too large for a single design: help the human decompose into sub-quests. Each sub-quest gets its own design → plan → implementation cycle. Design the first sub-quest through the normal flow.
+
 ## Mode Behavior
 
 - **Full Raid**: All 3 agents explore from different angles, fight directly, pin findings to Dungeon. Full design doc required.
@@ -41,7 +47,7 @@ digraph design {
   "Write design doc" -> "Adversarial spec review (agents attack directly)";
   "Adversarial spec review (agents attack directly)" -> "Spec self-review (fix inline)";
   "Spec self-review (fix inline)" -> "Human reviews written spec";
-  "Human reviews written spec" -> "Commit + invoke raid-implementation-plan" [shape=doublecircle];
+  "Human reviews written spec" -> "Commit + invoke raid-canonical-implementation-plan" [shape=doublecircle];
 }
 ```
 
@@ -54,7 +60,7 @@ Complete in order:
 3. **Explore project context** — files, docs, recent commits, dependencies, conventions, patterns
 4. **Research dependencies** — API surface, versioning, compatibility, known issues. Read docs COMPLETELY.
 5. **Ask clarifying questions** — one at a time to the human, eliminate every ambiguity
-6. **Open the Dungeon** — create `.claude/raid-dungeon.md` with Phase 1 header, quest, mode
+6. **Open the Dungeon** — create `{questDir}/phase-2-design.md` with Phase 2 header, quest, mode. Read PRD doc if it exists.
 7. **Dispatch with angles** — send each agent their angle via SendMessage, then go silent:
    ```
    SendMessage(to="warrior", message="DISPATCH: [quest]. Your angle: [X]...")
@@ -64,23 +70,35 @@ Complete in order:
 8. **Observe** — agents explore in their own panes, challenge each other via SendMessage, and pin findings to Dungeon. You receive messages automatically. Intervene only on protocol violations.
 9. **Close the phase** — when Dungeon has sufficient verified findings to form 2-3 approaches
 10. **Synthesize approaches** — propose 2-3 approaches from Dungeon evidence, with trade-offs and recommendation
-11. **Present design** — in sections scaled to complexity, get human approval per section
-12. **Write design doc** — save to specs path from `.claude/raid.json`
+11. **Present design section by section** — scale each section to its complexity (a few sentences if straightforward, up to 200-300 words if nuanced). Ask the human after each section: "Does this look right so far?" Be ready to revise before moving on. Cover: architecture, components, data flow, error handling, testing.
+12. **Write design doc** — save to `{questDir}/phase-2-design.md`. May also create `{questDir}/phase-2-diagrams.md` for mermaid charts.
 13. **Adversarial spec review** — agents attack the written spec directly, challenging each other
 14. **Spec self-review** — fix issues inline (see checklist below)
 15. **Human reviews written spec** — human approves before proceeding
-16. **Commit** — `docs(design): <topic> specification`
-17. **Archive Dungeon** — rename to `.claude/raid-dungeon-phase-1.md`
-18. **Transition** — invoke `raid-implementation-plan`
+16. **Commit** — `docs(quest-{slug}): phase 2 design — {summary}`
+17. **Transition** — invoke `raid-canonical-implementation-plan`
 
 ## Opening the Dungeon
 
-Create `.claude/raid-dungeon.md`:
+Create `{questDir}/phase-2-design.md` (where `{questDir}` is from raid-session):
 
 ```markdown
-# Dungeon — Phase 1: Design
+# Phase 2: Design
 ## Quest: <task description from human>
 ## Mode: <Full Raid | Skirmish>
+## PRD: <link to phase-1-prd.md if it exists>
+
+### Architecture Overview
+
+### Data Flow
+
+### Component Design
+
+### API Contracts
+
+### Edge Cases & Error Handling
+
+### Trade-offs & Decisions
 
 ### Discoveries
 
@@ -93,6 +111,16 @@ Create `.claude/raid-dungeon.md`:
 ### Escalations
 ```
 
+## Question Chain
+
+**Agents NEVER ask the human directly.** The question flow is:
+1. Agent discovers they need clarification → sends `WIZARD:` with the question
+2. Wizard reasons: can I answer this confidently from the PRD, codebase, or prior context?
+3. If yes → answer the agent directly via SendMessage
+4. If unsure → digest the question, formulate it clearly for the human, ask human
+5. Wizard passes human's answer back to agents with his own interpretation added
+6. Goal: minimize questions to human, batch related questions
+
 ## Dispatch Pattern
 
 Each agent gets the same objective but a different starting angle. After dispatch, the Wizard goes silent.
@@ -107,6 +135,13 @@ Each agent gets the same objective but a different starting angle. After dispatc
 >
 > **All**: Read the Dungeon. Build on each other's discoveries. Challenge everything. Pin only what survives. Escalate to me with `WIZARD:` only when genuinely stuck.
 
+## Design Principles
+
+- **Isolation:** Break into units with one clear purpose, well-defined interfaces, testable independently. For each unit: what does it do, how do you use it, what does it depend on?
+- **Encapsulation:** Can someone understand a unit without reading its internals? Can you change internals without breaking consumers? If not, the boundaries need work.
+- **Size:** Smaller, well-bounded units are easier to reason about. When a file grows large, that's a signal it's doing too much.
+- **Existing codebases:** Explore current structure first. Follow existing patterns. Only include targeted improvements where they serve the current goal — no unrelated refactoring.
+
 ## What Agents Must Cover
 
 Every agent addresses ALL of these from their assigned angle:
@@ -164,7 +199,7 @@ Fix issues inline.
 
 ## Design Document Structure
 
-Save to: specs path from `.claude/raid.json` (default: `docs/raid/specs/YYYY-MM-DD-<topic>-design.md`)
+Save to: `{questDir}/phase-2-design.md`
 
 ```markdown
 # [Feature Name] Design Specification
@@ -216,8 +251,9 @@ If the team is stuck on a fundamental design choice after genuine direct debate:
 
 When the design is approved and committed:
 
-1. Archive the Dungeon: rename `.claude/raid-dungeon.md` to `.claude/raid-dungeon-phase-1.md`
-2. Update `.claude/raid-session` phase to `"plan"`
-3. **Load the `raid-implementation-plan` skill now and begin Phase 2.**
+1. Update `.claude/raid-session` phase to `"plan"`
+2. **Commit:** `docs(quest-{slug}): phase 2 design — {summary}`
+3. **Send phase report to human:** summarize key design decisions, trade-offs resolved, what's next
+4. **Load the `raid-canonical-implementation-plan` skill now and begin Phase 3.**
 
 Do not wait. Do not ask. The next action after committing the design doc is loading the next skill.

package/template/.claude/skills/{raid-implementation → raid-canonical-implementation}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: raid-implementation
-description: "Phase 3 of Raid protocol. Wizard assigns implementer and opens task Dungeon. Implementer builds with TDD. Challengers attack directly, building on each other's critiques. Wizard rotates and closes each task."
+name: raid-canonical-implementation
+description: "Phase 4 of Canonical Quest. Wizard assigns tasks to agents in batches (round-based). Agents build with TDD. Cross-testing after each task. Wizard orchestrates and closes when all tasks complete."
 ---
 
-# Raid Implementation — Phase 3
+# Raid Implementation — Phase 4
 
 One builds, two attack — and the attackers attack each other's reviews too. Every implementation earns its approval through direct adversarial pressure.
 
@@ -23,7 +23,7 @@ TDD is enforced in ALL modes. This is an Iron Law.
 
 ```dot
 digraph implementation {
-  "Wizard reads plan + Phase 2 Dungeon" -> "Create task tracking (TaskCreate)";
+  "Wizard reads plan + Phase 3 plan docs" -> "Create task tracking (TaskCreate)";
   "Create task tracking (TaskCreate)" -> "Wizard assigns task N (rotate implementer)";
   "Wizard assigns task N (rotate implementer)" -> "Wizard opens task Dungeon";
   "Wizard opens task Dungeon" -> "Implementer executes (TDD)";
@@ -43,15 +43,28 @@ digraph implementation {
   "All issues resolved?" -> "Wizard closes task: ruling" [label="yes"];
   "Wizard closes task: ruling" -> "More tasks?" [shape=diamond];
   "More tasks?" -> "Wizard assigns task N (rotate implementer)" [label="yes"];
-  "More tasks?" -> "Archive Dungeon + invoke raid-review" [label="no", shape=doublecircle];
+  "More tasks?" -> "Archive Dungeon + invoke raid-canonical-review" [label="no", shape=doublecircle];
 }
 ```
 
+## Step 0: Critical Plan Review (before any implementation)
+
+Each agent MUST review the plan independently before implementing:
+- Are there concerns about feasibility or missing dependencies?
+- Are any steps unclear or ambiguous?
+- Does the plan match the design doc?
+- Are the TDD steps complete with actual test code?
+
+If concerns: raise via `WIZARD:` before starting. Fix the plan first. Never force through a flawed plan.
+
+**Branch guard:** Never implement on main/master without explicit human consent. Create a feature branch first.
+
 ## Wizard Checklist
 
 1. **Read the plan** — extract all tasks, dependencies, ordering
-2. **Read Phase 2 archived Dungeon** — carry forward context
-3. **Set up worktree** — use `raid-git-worktrees` for isolation (optional)
+2. **Read Phase 3 plan docs** — carry forward context from `{questDir}/phase-3-plan.md` and task files
+3. **Dispatch plan review** — each agent reviews plan independently, raises concerns via WIZARD:
+4. **Resolve concerns** — fix plan issues before any implementation begins
 4. **Browser setup (if `browser.enabled` in raid.json)**:
    - Check if `browser.startup` exists — if null, invoke `raid-browser` startup discovery FIRST
    - Check if Playwright is installed — if not, first task becomes "scaffold Playwright"
@@ -64,7 +77,7 @@ digraph implementation {
    - Observe messages (auto-delivered) + Dungeon updates
    - Close with ruling via SendMessage to all agents
 7. **Track progress** — mark complete only after Wizard ruling per task
-8. **After all tasks** — archive Dungeon, invoke `raid-review`
+8. **After all tasks** — archive Dungeon, invoke `raid-canonical-review`
 
 ## The Implementation Gauntlet (per task)
 
@@ -80,7 +93,7 @@ SendMessage(to="archer", message="Warrior is implementing Task N. Challenge when
 SendMessage(to="rogue", message="Warrior is implementing Task N. Challenge when they report done.")
 ```
 
-Phase 3 uses a single continuous Dungeon (`.claude/raid-dungeon.md`) across all tasks. The Wizard announces each task assignment via SendMessage.
+Phase 4 uses `{questDir}/phase-4-implementation.md` as the implementation log. The Wizard announces each task assignment via SendMessage. Agents flag `ROUND_COMPLETE:` when done with their task.
 
 ### Step 2: Implementer Executes (TDD)
 
@@ -154,6 +167,17 @@ The Wizard closes when messages + Dungeon show all issues resolved and challenge
 
 **Never ignore an escalation.** If the implementer says it's stuck, something needs to change.
 
+## When to STOP Executing
+
+STOP implementing immediately when:
+- Missing dependency not covered in plan
+- Test fails for unexpected reason (not the expected "right" failure)
+- Instruction is ambiguous — two valid interpretations exist
+- Verification fails repeatedly (2+ times on same step)
+- Implementation diverges significantly from plan
+
+**Ask via `WIZARD:` rather than guessing.** Don't force through blockers — they indicate plan gaps, not agent weakness. The Wizard escalates to the human if needed.
+
 ## Quality Gates Per Task
 
 - [ ] Tests written BEFORE implementation (TDD)
@@ -183,7 +207,7 @@ The Wizard closes when messages + Dungeon show all issues resolved and challenge
 
 - **3+ fix attempts on one task:** Question whether the task spec or design is wrong.
 - **Agent repeatedly blocked:** The plan may need revision.
-- **Tests can't be written:** The design may not be testable. Return to Phase 1.
+- **Tests can't be written:** The design may not be testable. Return to Phase 2.
 
 ---
 
@@ -191,8 +215,11 @@ The Wizard closes when messages + Dungeon show all issues resolved and challenge
 
 When all tasks are approved and committed:
 
-1. Archive the Dungeon: rename `.claude/raid-dungeon.md` to `.claude/raid-dungeon-phase-3.md`
-2. Update `.claude/raid-session` phase to `"review"`
-3. **Load the `raid-review` skill now and begin Phase 4.**
+1. Update `.claude/raid-session` phase to `"review"`
+2. **Commit**: `feat(quest-{slug}): phase 4 implementation — {summary}`
+3. **Send phase report to human**: what was built, test coverage, any concerns
+4. **Ask human**: "Shall we inspect the treasure? (Review phase) Or proceed directly to wrap-up?"
+5. If review → **Load `raid-canonical-review` skill and begin Phase 5**
+6. If skip → **Load `raid-wrap-up` skill and begin Phase 6**
 
-Do not wait. Do not ask. The next action after all implementation tasks pass is loading the next skill.
+Do not wait. Do not ask twice. The next action after all tasks pass is the human's choice.

package/template/.claude/skills/{raid-implementation-plan → raid-canonical-implementation-plan}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: raid-implementation-plan
-description: "Phase 2 of Raid protocol. Wizard opens the Dungeon, agents decompose the design into tasks through direct debate, test each other for compliance, and pin agreed tasks. Wizard closes when plan is battle-tested."
+name: raid-canonical-implementation-plan
+description: "Phase 3 of Canonical Quest. Agents decompose the design into tasks through round-based debate. No code writing. Output: task index + individual task files in quest directory."
 ---
 
-# Raid Implementation Plan — Phase 2
+# Raid Implementation Plan — Phase 3
 
 Break the design into bite-sized, battle-tested tasks through agent-driven adversarial decomposition.
 
@@ -21,7 +21,7 @@ Do NOT start implementation until the plan is approved by the Wizard and committ
 
 ```dot
 digraph plan {
-  "Wizard reads design doc + Phase 1 Dungeon" -> "Wizard opens Dungeon + dispatches";
+  "Wizard reads design doc + Phase 2 design doc" -> "Wizard opens Dungeon + dispatches";
   "Wizard opens Dungeon + dispatches" -> "Agents decompose independently";
   "Agents decompose independently" -> "Agents compare and fight directly";
   "Agents compare and fight directly" -> "Agents test compliance collaboratively";
@@ -34,32 +34,31 @@ digraph plan {
   "Write plan doc" -> "Adversarial plan review (agents attack directly)";
   "Adversarial plan review (agents attack directly)" -> "Self-review (6-point checklist)";
   "Self-review (6-point checklist)" -> "Wizard ruling + commit";
-  "Wizard ruling + commit" -> "Archive Dungeon + invoke raid-implementation" [shape=doublecircle];
+  "Wizard ruling + commit" -> "Archive Dungeon + invoke raid-canonical-implementation" [shape=doublecircle];
 }
 ```
 
 ## Wizard Checklist
 
 1. **Read the approved design doc** — every requirement, every constraint
-2. **Read the Phase 1 archived Dungeon** — carry forward verified knowledge
-3. **Open the Dungeon** — create `.claude/raid-dungeon.md` with Phase 2 header
-4. **Dispatch decomposition** — all agents decompose independently with different angles, then interact directly
+2. **Read the Phase 2 design doc** — carry forward verified knowledge from `{questDir}/phase-2-design.md`
+3. **Open the Dungeon** — create `{questDir}/phase-3-plan.md` with Phase 3 header
+4. **Dispatch decomposition** — all agents decompose independently with different angles, then interact directly (round-based)
 5. **Observe the fight** — agents test each other's plans, argue ordering, coverage, naming. Intervene only on triggers.
 6. **Close the phase** — when Dungeon has complete, verified task list
-7. **Synthesize** — write plan doc from Dungeon evidence
+7. **Synthesize** — write plan doc from Dungeon evidence. Create individual task files: `{questDir}/phase-3-plan-task-NN.md`
 8. **Adversarial plan review** — agents attack the written plan directly
 9. **Self-review** — 6-point checklist (see below)
 10. **Wizard ruling** — final plan approval
-11. **Commit** — `docs(plan): <feature> implementation plan`
-12. **Archive Dungeon** — rename to `.claude/raid-dungeon-phase-2.md`
-13. **Transition** — invoke `raid-implementation`
+11. **Commit** — `docs(quest-{slug}): phase 3 plan — {N} tasks, {summary}`
+12. **Transition** — invoke `raid-canonical-implementation` and begin Phase 4
 
 ## Opening the Dungeon
 
-Create `.claude/raid-dungeon.md`:
+Create `{questDir}/phase-3-plan.md`:
 
 ```markdown
-# Dungeon — Phase 2: Plan
+# Phase 3: Implementation Plan
 ## Quest: Decompose <design topic> into implementation tasks
 ## Mode: <Full Raid | Skirmish>
 
@@ -74,6 +73,38 @@ Create `.claude/raid-dungeon.md`:
 ### Escalations
 ```
 
+## File Structure Mapping
+
+Before defining tasks, map ALL files to be created or modified:
+
+```markdown
+## File Map
+
+| File | Action | Responsibility |
+|------|--------|---------------|
+| `src/auth/handler.ts` | Create | Token validation and refresh |
+| `src/auth/types.ts` | Create | Auth types and interfaces |
+| `tests/auth/handler.test.ts` | Create | Unit tests for handler |
+| `src/middleware.ts` | Modify (L45-60) | Add auth middleware hook |
+```
+
+- Each file should have one clear responsibility
+- Files that change together should live together
+- Follow existing codebase patterns — don't restructure unless it serves the current goal
+- This map informs the task decomposition: each task should produce self-contained changes
+
+## Plan Document Header
+
+Every plan MUST start with:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Goal:** [One sentence describing what this builds]
+**Architecture:** [2-3 sentences about approach]
+**Tech Stack:** [Key technologies/libraries]
+```
+
 ## Dispatch for Decomposition
 
 **DISPATCH:**
@@ -187,8 +218,9 @@ Fix issues inline. If a spec requirement has no task, add the task.
 
 When the plan is approved and committed:
 
-1. Archive the Dungeon: rename `.claude/raid-dungeon.md` to `.claude/raid-dungeon-phase-2.md`
-2. Update `.claude/raid-session` phase to `"implementation"`
-3. **Load the `raid-implementation` skill now and begin Phase 3.**
+1. Update `.claude/raid-session` phase to `"implementation"`
+2. **Commit**: `docs(quest-{slug}): phase 3 plan — {N} tasks, {summary}`
+3. **Send phase report to human**: task count, dependency graph, estimated scope
+4. **Load the `raid-canonical-implementation` skill now and begin Phase 4.**
 
 Do not wait. Do not ask. The next action after committing the plan doc is loading the next skill.

package/template/.claude/skills/raid-canonical-prd/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: raid-canonical-prd 
+description: "Phase 1 of Canonical Quest (optional). Agents research and explore to produce a complete PRD. No code writing. Wizard mediates human questions. Output: phase-1-prd.md in quest directory."
+---
+
+# Raid PRD — Phase 1 (Optional)
+
+Forge the Product Requirements Document through agent-driven research and human-mediated discovery.
+
+<HARD-GATE>
+Do NOT write any code. Do NOT modify any project files. Only markdown files in the quest dungeon directory are allowed. Agents communicate via SendMessage — do not spawn subagents.
+</HARD-GATE>
+
+## Mode Behavior
+
+- **Full Raid**: All 3 agents explore from different research angles, battle-test findings. Full PRD.
+- **Skirmish**: 2 agents research and cross-test. Lighter PRD.
+- **Scout**: Wizard drafts PRD alone from human input. Minimal research.
+
+## Process Flow
+
+```dot
+digraph prd {
+  "Wizard updates phase to prd" -> "Create phase-1-prd.md with boilerplate";
+  "Create phase-1-prd.md with boilerplate" -> "Wizard digests human's task description";
+  "Wizard digests human's task description" -> "Dispatch party with research angles";
+  "Dispatch party with research angles" -> "Agents research independently (parallel)";
+  "Agents research independently (parallel)" -> "Agents flag ROUND_COMPLETE:";
+  "Agents flag ROUND_COMPLETE:" -> "Wizard dispatches cross-testing";
+  "Wizard dispatches cross-testing" -> "Agents battle-test findings";
+  "Agents battle-test findings" -> "Surviving findings pinned to dungeon";
+  "Surviving findings pinned to dungeon" -> "More research needed?" [shape=diamond];
+  "More research needed?" -> "Agents research independently (parallel)" [label="yes"];
+  "More research needed?" -> "Wizard wraps up PRD" [label="no"];
+  "Wizard wraps up PRD" -> "Send phase report to human";
+  "Send phase report to human" -> "Commit + transition to Design" [shape=doublecircle];
+}
+```
+
+## Wizard Checklist
+
+1. **Update raid-session** — set phase to `"prd"`
+2. **Create phase file** — `{questDir}/phase-1-prd.md` with boilerplate sections
+3. **Digest the human's request** — understand intent, identify gaps, map the problem space
+4. **Dispatch party with research angles** via SendMessage:
+   - **@Warrior**: Explore the technical stack. What infrastructure exists? What APIs are available? What technical constraints apply? What precedents exist in the codebase?
+   - **@Archer**: Explore the patterns. How does this fit existing architecture? What conventions apply? What similar features exist? What naming and structure patterns should we follow?
+   - **@Rogue**: Explore the edge cases. What could go wrong? What assumptions are we making? What requirements are we missing? What will users actually do vs what we think they'll do?
+5. **Observe** — agents research in parallel. Go silent.
+6. **Mediate questions** — agents ask Wizard, Wizard reasons, Wizard asks human only if unsure
+7. **Dispatch cross-testing** — when agents flag ROUND_COMPLETE:, assign their findings to others
+8. **Close phase** — wrap up PRD, send report, commit
+
+## Phase File Template
+
+Create `{questDir}/phase-1-prd.md`:
+
+```markdown
+# Phase 1: PRD — Product Requirements Document
+## Quest: <task description>
+## Mode: <Full Raid | Skirmish | Scout>
+
+### Problem Statement
+
+### Goals & Non-Goals
+
+#### Goals
+
+#### Non-Goals
+
+### User Stories
+
+### Functional Requirements
+
+### Non-Functional Requirements
+
+### Business Logic
+
+### Constraints & Assumptions
+
+### Success Criteria
+
+### Open Questions
+
+### Discoveries
+
+### Shared Knowledge
+```
+
+## Research Angles
+
+Agents should use all available tools to research:
+- **MCP tools** — query context servers, fetch documentation
+- **Web search** — find related patterns, prior art, library docs
+- **Doc fetching** — read official docs for relevant technologies
+- **Codebase analysis** — explore existing code, patterns, conventions
+- **Skill discovery** — find relevant skills that may help
+
+## Question Chain
+
+**Agents NEVER ask the human directly.** The flow is:
+
+1. Agent discovers a gap → sends `WIZARD:` with the question and context
+2. Wizard reasons: "Can I answer this from the PRD description, codebase, or prior knowledge?"
+3. If confident → answer the agent directly via SendMessage
+4. If unsure → digest the question into a clear, contextual question for the human
+5. Wizard asks the human one well-formulated question (not the raw agent question)
+6. Wizard receives answer → interprets, adds context → passes to party
+
+**Goal:** Minimize questions to human. Batch related questions. The party should figure out as much as possible themselves.
+
+## Closing the Phase
+
+When the PRD is complete (all sections filled, open questions resolved):
+
+1. **Wrap up the PRD document** — fill gaps, ensure coherence across sections
+2. **Send phase report to human**: "The PRD is forged. Here's what we established: [key points]"
+3. **Commit**: `docs(quest-{slug}): phase 1 PRD — {summary}`
+4. **Transition**: Load `raid-canonical-design` skill and begin Phase 2
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The requirements are obvious, skip PRD" | If they were obvious, the human would have skipped this phase. |
+| "Let me start coding to test an idea" | PRD phase. No code. Research and write. |
+| "I'll ask the human every question" | Exhaust your own research first. Use MCP, docs, codebase. |
+| "This PRD section doesn't apply" | Fill every section. Write "N/A — [reason]" if truly not applicable. |
+| "Let me ask the human directly" | Route through the Wizard. Always. |
+
+## Phase Spoils
+
+**Output**: `{questDir}/phase-1-prd.md` — Complete Product Requirements Document with all sections filled, open questions resolved, and discoveries from cross-testing documented.