claude-raid 0.1.6 → 0.2.1

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,6 +207,19 @@ 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.
+
+---
+
+## Phase Transition
+
+When all tasks are approved and committed:
+
+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**
 
-**Terminal state:** All tasks approved. Archive Dungeon. Invoke `raid-review`.
+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:**
@@ -181,4 +212,15 @@ Fix issues inline. If a spec requirement has no task, add the task.
 | "Tests can be added later" | TDD means tests are in the plan. No test = no task. |
 | "The naming will be consistent enough" | Check it explicitly. Naming drift is the #1 source of bugs. |
 
-**Terminal state:** RULING: Plan approved. Commit. Archive Dungeon. Invoke `raid-implementation`.
+---
+
+## Phase Transition
+
+When the plan is approved and committed:
+
+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.

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

@@ -0,0 +1,211 @@
+---
+name: raid-canonical-protocol
+description: "Canonical Quest protocol. Establishes the 6-phase workflow (PRD, Design, Plan, Implementation, Review, Wrap Up), round-based interaction, Dungeon lifecycle, quest types, communication signals, and phase transition gates."
+---
+
+# Canonical Quest Protocol
+
+The canonical workflow for full-cycle development. Every feature, refactor, or system built through the Raid follows this sequence.
+
+<HARD-GATE>
+Do NOT skip phases. Do NOT let a single agent work unchallenged (except Scout mode). Do NOT proceed without a Wizard ruling. Agents communicate via SendMessage — do not spawn subagents.
+</HARD-GATE>
+
+## Session Lifecycle
+
+```dot
+digraph session {
+  "Wizard starts" -> "Load raid-init";
+  "Load raid-init" -> "Greet human + quest selection";
+  "Greet human + quest selection" -> "Canonical Quest selected";
+  "Canonical Quest selected" -> "PRD needed?";
+  "PRD needed?" -> "Phase 1: PRD (raid-canonical-prd)" [label="yes"];
+  "PRD needed?" -> "Phase 2: Design (raid-canonical-design)" [label="no"];
+  "Phase 1: PRD (raid-canonical-prd)" -> "Phase 2: Design (raid-canonical-design)";
+  "Phase 2: Design (raid-canonical-design)" -> "Phase 3: Plan (raid-canonical-implementation-plan)";
+  "Phase 3: Plan (raid-canonical-implementation-plan)" -> "Phase 4: Implementation (raid-canonical-implementation)";
+  "Phase 4: Implementation (raid-canonical-implementation)" -> "Review wanted?";
+  "Review wanted?" -> "Phase 5: Review (raid-canonical-review)" [label="yes"];
+  "Review wanted?" -> "Phase 6: Wrap Up (raid-wrap-up)" [label="no"];
+  "Phase 5: Review (raid-canonical-review)" -> "Phase 6: Wrap Up (raid-wrap-up)";
+  "Phase 6: Wrap Up (raid-wrap-up)" -> "Archive to vault + session end";
+}
+```
+
+## Team
+
+| Agent | Role | Color |
+|-------|------|-------|
+| **Wizard** (Dungeon Master) | Opens phases, observes, digests, rules. NEVER implements. | Purple |
+| **Warrior** | Stress-tests to destruction, edge cases, load testing | Red |
+| **Archer** | Pattern-seeker, traces ripple effects, naming drift | Green |
+| **Rogue** | Adversarial assumption-destroyer, attack scenarios | Orange |
+
+## Modes
+
+| Aspect | Full Raid | Skirmish | Scout |
+|--------|-----------|----------|-------|
+| Agents | 3 | 2 | 1 |
+| PRD phase | Full | Lightweight | Skip |
+| Design | Full adversarial | Lightweight | Inline |
+| Plan | Full adversarial | Combined with design | Inline |
+| Implementation | 1 builds, 2 cross-test | 1 builds, 1 cross-tests | 1 builds, Wizard reviews |
+| Review | 3 independent + fighting | 1 review + Wizard | Wizard only |
+| TDD | **Enforced** | **Enforced** | **Enforced** |
+
+## Round-Based Interaction
+
+Think turn-based RPG, not real-time:
+
+```
+ROUND START → Wizard dispatches tasks/angles
+    ↓
+PARALLEL WORK → Each agent works independently
+    ↓
+FLAG COMPLETION → Agent signals ROUND_COMPLETE: to Wizard
+    ↓
+CROSS-TESTING → Wizard assigns completed work for review
+    ↓
+REACTIONS → Agents test, challenge, build
+    ↓
+RESOLUTION → Findings pinned to dungeon or conceded
+    ↓
+ROUND END → Wizard assesses: next round or phase close
+```
+
+**Rules:**
+- No mid-thinking interruptions between agents (only Wizard can interrupt)
+- Each message must carry evidence + conclusion (no shallow exchanges)
+- Converge in 2-3 exchanges per finding; escalate to Wizard after 3
+- Party is silent during phase transitions
+
+## Question Chain
+
+Agents → Wizard → Human. Agents NEVER ask the human directly.
+
+1. Agent discovers gap → sends `WIZARD:` with question
+2. Wizard reasons: can I answer from PRD, codebase, context?
+3. If confident → answers agent directly
+4. If unsure → digests question, asks human one clear question
+5. Wizard passes answer back with interpretation
+
+## Phase Transition Gates
+
+| From | To | Gate | Commit Format |
+|------|----|------|---------------|
+| PRD | Design | PRD approved by Wizard | `docs(quest-{slug}): phase 1 PRD` |
+| Design | Plan | Design doc approved, committed | `docs(quest-{slug}): phase 2 design` |
+| Plan | Implementation | Plan approved, committed | `docs(quest-{slug}): phase 3 plan` |
+| Implementation | Review | All tasks done, tests pass | `feat(quest-{slug}): phase 4 implementation` |
+| Review | Wrap Up | Wizard ruling: approved | `fix(quest-{slug}): phase 5 review` |
+
+**Wizard commits at EVERY phase transition.** No exceptions.
+
+## Phase Spoils
+
+Every phase MUST produce at least one detailed markdown artifact:
+
+| Phase | Output File |
+|-------|-------------|
+| PRD | `{questDir}/phase-1-prd.md` |
+| Design | `{questDir}/phase-2-design.md` |
+| Plan | `{questDir}/phase-3-plan.md` + task files |
+| Implementation | `{questDir}/phase-4-implementation.md` |
+| Review | `{questDir}/phase-5-review.md` |
+| Wrap Up | `{questDir}/phase-6-wrap-up.md` |
+
+## Communication Signals
+
+| Signal | Who | Meaning | Goes to Dungeon? |
+|--------|-----|---------|-----------------|
+| `DISPATCH:` | Wizard | Opening a phase, assigning angles | No |
+| `ROUND_COMPLETE:` | Any agent | Finished assigned task | No |
+| `FINDING:` | Any agent | Discovery with own evidence | No |
+| `CHALLENGE:` | Any agent | Independently verified, found problem | No |
+| `BUILDING:` | Any agent | Independently verified, goes deeper | No |
+| `DUNGEON:` | Any agent | Pinning finding verified by 2+ agents | **Yes** |
+| `BLACKCARD:` | Any agent | High-concern finding blocking progress | **Yes** |
+| `WIZARD:` | Any agent | Escalation — needs Wizard input | Yes (escalation) |
+| `CONCEDE:` | Any agent | Proven wrong, moving on | No |
+| `RULING:` | Wizard | Binding decision, phase close | Archived |
+| `REDIRECT:` | Wizard | Course correction, one sentence | No |
+
+## Black Card System
+
+A `BLACKCARD:` is a finding that fundamentally breaks the architecture — unfixable within current design.
+
+**Flow:** Agent plays → 2+ agents verify → Wizard escalates to human → Options: (a) rollback to earlier phase, (b) accept limitation.
+
+Black cards are RARE. Most issues are Critical or Important, not black cards.
+
+## The Dungeon
+
+Quest directory at `.claude/dungeon/{quest-slug}/`. Each phase produces a file.
+
+| Event | Action | Who |
+|-------|--------|-----|
+| Quest starts | Create quest directory | Hook |
+| Phase opens | Create `{questDir}/phase-N-{name}.md` with boilerplate | Wizard |
+| During phase | Pin findings via `DUNGEON:` | Agents |
+| Phase closes | Wrap up doc, commit | Wizard |
+| Quest ends | Move to `.claude/vault/{quest-slug}/` | Wizard |
+
+**The Dungeon is a scoreboard, not a chat log.** Only verified findings, resolved battles, shared knowledge.
+
+## Wizard Behavior
+
+- **90% thinking / 10% talking** — thinks 5x before speaking
+- **NEVER implements** — dispatches, observes, digests, rules
+- **Opens and closes every phase** — creates phase file, dispatches, then goes silent
+- **Phase reports** — at every close, summarizes for human: what was done, what's next
+- **Question gatekeeper** — digests before passing in either direction
+- **Commits at every transition** — with quest name + phase + summary
+
+## Configuration
+
+Read `.claude/raid.json` for project settings:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `project.testCommand` | (none) | Command to run tests |
+| `project.packageManager` | (auto) | Package manager |
+| `raid.defaultMode` | `full` | Default mode |
+| `raid.agentEffort` | `medium` | Agent effort level (Wizard always max) |
+| `raid.vault.path` | `.claude/vault` | Vault location |
+| `browser.enabled` | `false` | Browser testing active |
+
+## Browser Testing
+
+When `browser.enabled` is `true`:
+- **Phase 4 (Implementation):** Browser-facing code uses TDD with Playwright via `raid-tdd`. Challengers verify on isolated ports.
+- **Phase 5 (Review):** Live adversarial Chrome inspection via `raid-browser-chrome`. Each agent on separate port.
+- Invoke `raid-browser` for startup discovery and pre-flight.
+
+## Skills Reference
+
+| Skill | Phase | Purpose |
+|-------|-------|---------|
+| `raid-init` | Pre-phase | Quest selection, greeting, session setup |
+| `raid-canonical-protocol` | Start | This doc — session lifecycle, rules, reference |
+| `raid-canonical-prd` | 1 | PRD creation (optional) |
+| `raid-canonical-design` | 2 | Adversarial design exploration |
+| `raid-canonical-implementation-plan` | 3 | Task decomposition |
+| `raid-canonical-implementation` | 4 | TDD implementation with cross-testing |
+| `raid-canonical-review` | 5 | Pinning + fixing + black cards (optional) |
+| `raid-wrap-up` | 6 | Storyboard, PR, vault archival |
+| `raid-tdd` | Any | RED-GREEN-REFACTOR enforcement |
+| `raid-verification` | Any | Evidence-before-claims gate |
+| `raid-debugging` | Any | Root-cause investigation |
+| `raid-browser` | 4, 5 | Browser orchestration |
+| `raid-browser-chrome` | 5 | Live Chrome inspection |
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This phase is obvious, skip it" | Obvious phases hide assumptions. |
+| "The agents agree, no need for cross-testing" | Agreement without challenge is groupthink. |
+| "TDD would slow us down" | TDD is an Iron Law. No exceptions. |
+| "Let me ask the human directly" | Route through the Wizard. Always. |
+| "Let me just post everything to the Dungeon" | Pin only what survived challenge. |
+| "I'll wait for the Wizard to tell me what to do" | Self-organize within the round. |