claude-raid 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +84 -23
  2. package/bin/cli.js +4 -2
  3. package/package.json +1 -1
  4. package/src/descriptions.js +10 -7
  5. package/src/init.js +36 -5
  6. package/src/merge-settings.js +53 -2
  7. package/src/remove.js +1 -1
  8. package/src/setup.js +32 -0
  9. package/src/ui.js +1 -0
  10. package/src/update.js +26 -3
  11. package/template/.claude/agents/archer.md +18 -4
  12. package/template/.claude/agents/rogue.md +18 -4
  13. package/template/.claude/agents/warrior.md +18 -4
  14. package/template/.claude/agents/wizard.md +32 -5
  15. package/template/.claude/dungeon-master-rules.md +120 -31
  16. package/template/.claude/hooks/raid-lib.sh +45 -4
  17. package/template/.claude/hooks/raid-pre-compact.sh +8 -4
  18. package/template/.claude/hooks/raid-session-end.sh +2 -2
  19. package/template/.claude/hooks/raid-session-start.sh +2 -0
  20. package/template/.claude/hooks/rtk-bridge.sh +46 -0
  21. package/template/.claude/hooks/validate-dungeon.sh +11 -3
  22. package/template/.claude/hooks/validate-file-naming.sh +6 -1
  23. package/template/.claude/hooks/validate-no-placeholders.sh +13 -2
  24. package/template/.claude/hooks/validate-write-gate.sh +7 -2
  25. package/template/.claude/party-rules.md +91 -65
  26. package/template/.claude/skills/raid-browser/SKILL.md +3 -5
  27. package/template/.claude/skills/raid-browser-chrome/SKILL.md +1 -1
  28. package/template/.claude/skills/raid-canonical-design/SKILL.md +309 -162
  29. package/template/.claude/skills/raid-canonical-implementation/SKILL.md +157 -132
  30. package/template/.claude/skills/raid-canonical-implementation-plan/SKILL.md +196 -141
  31. package/template/.claude/skills/raid-canonical-prd/SKILL.md +92 -89
  32. package/template/.claude/skills/raid-canonical-protocol/SKILL.md +29 -123
  33. package/template/.claude/skills/raid-canonical-review/SKILL.md +292 -148
  34. package/template/.claude/skills/raid-debugging/SKILL.md +1 -7
  35. package/template/.claude/skills/raid-init/SKILL.md +7 -5
  36. package/template/.claude/skills/raid-tdd/SKILL.md +5 -5
  37. package/template/.claude/skills/raid-teambuff/SKILL.md +6 -24
  38. package/template/.claude/skills/raid-verification/SKILL.md +0 -6
  39. package/template/.claude/skills/raid-wrap-up/SKILL.md +30 -29
@@ -1,140 +1,144 @@
1
1
  ---
2
- name: raid-canonical-prd
3
- description: "Use when Phase 1 (PRD) begins in a Canonical Quest. The human chose to forge a PRD rather than skip to Design."
2
+ name: raid-canonical-prd
3
+ description: "Use when Phase 1 (PRD) begins in a Canonical Quest. The human chose to forge a PRD rather than skip to Design. Wizard and human only — no agents dispatched."
4
4
  ---
5
5
 
6
6
  # Raid PRD — Phase 1 (Optional)
7
7
 
8
- Forge the Product Requirements Document through agent-driven research and human-mediated discovery.
8
+ Forge the Product Requirements Document through collaborative discovery between the Wizard and the human. This phase is a dialogue — the Wizard asks questions, explores the codebase, and writes the PRD. No agents are dispatched.
9
9
 
10
10
  <HARD-GATE>
11
- Do NOT write any code. Do NOT modify any project files. Only markdown files in the quest dungeon directory are allowed. Agents communicate via SendMessagedo not spawn subagents.
11
+ Do NOT write any code. Do NOT modify any project files. Only markdown files in the quest dungeon directory are allowed. Do NOT dispatch any agents this phase is Wizard + Human only.
12
12
  </HARD-GATE>
13
13
 
14
- ## Mode Behavior
15
-
16
- - **Full Raid**: All 3 agents explore from different research angles, battle-test findings. Full PRD.
17
- - **Skirmish**: 2 agents research and cross-test. Lighter PRD.
18
- - **Scout**: Wizard drafts PRD alone from human input. Minimal research.
19
-
20
14
  ## Process Flow
21
15
 
22
16
  ```dot
23
17
  digraph prd {
24
- "Wizard updates phase to prd" -> "Create phase-1-prd.md with boilerplate";
25
- "Create phase-1-prd.md with boilerplate" -> "Wizard digests human's task description";
26
- "Wizard digests human's task description" -> "Dispatch party with research angles";
27
- "Dispatch party with research angles" -> "Agents research independently (parallel)";
28
- "Agents research independently (parallel)" -> "Agents flag ROUND_COMPLETE:";
29
- "Agents flag ROUND_COMPLETE:" -> "Wizard dispatches cross-testing";
30
- "Wizard dispatches cross-testing" -> "Agents battle-test findings";
31
- "Agents battle-test findings" -> "Surviving findings pinned to dungeon";
32
- "Surviving findings pinned to dungeon" -> "More research needed?" [shape=diamond];
33
- "More research needed?" -> "Agents research independently (parallel)" [label="yes"];
34
- "More research needed?" -> "Wizard wraps up PRD" [label="no"];
35
- "Wizard wraps up PRD" -> "Send phase report to human";
36
- "Send phase report to human" -> "Commit + transition to Design" [shape=doublecircle];
18
+ "Update raid-session phase to prd" -> "Explore codebase for context";
19
+ "Explore codebase for context" -> "Ask human clarifying questions (one at a time)";
20
+ "Ask human clarifying questions (one at a time)" -> "All questions answered?" [shape=diamond];
21
+ "All questions answered?" -> "Ask human clarifying questions (one at a time)" [label="no, more gaps"];
22
+ "All questions answered?" -> "Write prd.md in quest dir" [label="yes"];
23
+ "Write prd.md in quest dir" -> "Present PRD to human";
24
+ "Present PRD to human" -> "Approved?" [shape=diamond];
25
+ "Approved?" -> "Ask why not approved, understand feedback" [label="no"];
26
+ "Ask why not approved, understand feedback" -> "Revise prd.md" -> "Present PRD to human";
27
+ "Approved?" -> "Commit + report with file link" [label="yes"];
28
+ "Commit + report with file link" -> "Load raid-canonical-design" [shape=doublecircle];
37
29
  }
38
30
  ```
39
31
 
32
+ ## Why This Phase Matters
33
+
34
+ The Wizard is the master of requirements — a visionary who thinks in future-proof solutions and business rules. This phase is where the Wizard builds the complete picture: understanding every constraint, every assumption, every edge case before the party enters the arena. The deeper the Wizard's understanding here, the sharper the direction for every subsequent phase.
35
+
40
36
  ## Wizard Checklist
41
37
 
42
38
  1. **Update raid-session** via Bash (write gate blocks Write/Edit on this file):
43
39
  ```bash
44
40
  jq '.phase="prd"' .claude/raid-session > .claude/raid-session.tmp && mv .claude/raid-session.tmp .claude/raid-session
45
41
  ```
46
- 2. **Create phase file** — `{questDir}/phase-1-prd.md` with boilerplate sections
47
- 3. **Digest the human's request** — understand intent, identify gaps, map the problem space
48
- 4. **Dispatch party with research angles** via SendMessage:
49
- - **@Warrior**: Explore the technical stack. What infrastructure exists? What APIs are available? What technical constraints apply? What precedents exist in the codebase?
50
- - **@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?
51
- - **@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?
52
- 5. **Round 1: Research** — agents research in parallel. Each investigates their angle independently. Pin findings. Signal `ROUND_COMPLETE:`. **Stop.** Agents do NOT self-initiate cross-testing. Go silent and observe.
53
- 6. **Mediate questions** — agents ask Wizard, Wizard reasons, Wizard asks human only if unsure
54
- 7. **Round 2: Cross-testing** — when ALL agents have flagged `ROUND_COMPLETE:`, dispatch explicit cross-verification assignments. Each agent challenges specific findings from the others. Agents signal `ROUND_COMPLETE:` when done. **Stop.**
55
- 8. **Repeat if needed** — if more research is needed, dispatch a new research round with refined angles
56
- 9. **Close phase** — broadcast `HOLD`, wrap up PRD, send report, commit
57
-
58
- ## Phase File (Dungeon Scoreboard)
59
-
60
- Create `{questDir}/phase-1-prd.md` — this is the **dungeon scoreboard**, not the deliverable. It tracks discoveries, battles, and shared knowledge from agent research. Every line in Discoveries/Active Battles must use a recognized prefix (`DUNGEON:`, `UNRESOLVED:`, `BLACKCARD:`, `RESOLVED:`, `TASK:`). Freeform content is only allowed in Resolved, Shared Knowledge, and Escalations sections.
61
42
 
62
- ```markdown
63
- # Phase 1: PRD — Product Requirements Document
64
- ## Quest: <task description>
65
- ## Mode: <Full Raid | Skirmish | Scout>
43
+ 2. **Explore the codebase** — read files, grep for patterns, understand the architecture, dependencies, conventions, and existing solutions. You need this context to ask the right questions and write a thorough PRD.
66
44
 
67
- ### Discoveries
45
+ 3. **Ask the human clarifying questions — one at a time.** This is a dialogue, not an interview dump. Each question should build on the previous answer. Focus on:
46
+ - The real problem beneath the stated problem
47
+ - Who the users are and what they actually need
48
+ - Business rules and constraints
49
+ - Success criteria — how will we know this works?
50
+ - Non-goals — what are we explicitly NOT building?
51
+ - Edge cases the human may not have considered
52
+ - Dependencies on other systems or teams
68
53
 
69
- ### Active Battles
54
+ 4. **Use all available tools to fill gaps** — MCP tools, web search, doc fetching, codebase analysis. The goal is to minimize questions to the human by answering what you can yourself.
70
55
 
71
- ### Resolved
56
+ 5. **Write `prd.md`** in the quest directory. This is the deliverable — not a scoreboard, not an evolution log. A complete, polished PRD.
72
57
 
73
- ### Shared Knowledge
58
+ 6. **Present the PRD to the human for approval.** Walk through the key sections. Ask: "Does this capture everything?"
74
59
 
75
- ### Escalations
76
- ```
60
+ 7. **If not approved:** Ask why — repeatedly if needed — until you fully understand what's wrong or missing. Revise and re-present. Repeat until the human approves.
77
61
 
78
- ## Phase Deliverable (PRD Document)
62
+ 8. **Commit:** `docs(quest-{slug}): phase 1 PRD — {summary}`
79
63
 
80
- The actual PRD is a **separate file**: `{questDir}/prd.md`. This file is not validated by the dungeon hook and can contain freeform markdown. Write it when closing the phase — synthesize from the scoreboard findings.
64
+ 9. **Report to human** with a link to the `prd.md` file path so they can open it directly.
65
+
66
+ 10. **Transition:** Load `raid-canonical-design` skill, begin Phase 2.
67
+
68
+ ## PRD Document Template
69
+
70
+ Write `{questDir}/spoils/prd.md`:
81
71
 
82
72
  ```markdown
83
- # <Feature Name> — Product Requirements Document
73
+ # [Feature Name] — Product Requirements Document
84
74
 
85
- ### Problem Statement
75
+ ## Quest: [quest description]
76
+ ## Date: YYYY-MM-DD
77
+ ## Author: Wizard
86
78
 
87
- ### Goals & Non-Goals
79
+ ## Quest Goal
80
+ <!-- Wizard writes 2-3 lines: what this PRD aims to capture and why -->
88
81
 
89
- #### Goals
82
+ ---
90
83
 
91
- #### Non-Goals
84
+ ### Problem Statement
85
+ <!-- What problem exists today? Who is affected? What's the cost of not solving it?
86
+ Be specific — reference actual code, systems, or user pain points discovered
87
+ during codebase exploration. -->
88
+
89
+ ### Goals
90
+ <!-- What does success look like? Each goal should be measurable or verifiable.
91
+ Number them. -->
92
+
93
+ ### Non-Goals
94
+ <!-- What are we explicitly NOT building? This prevents scope creep.
95
+ Be specific about what's out of scope and why. -->
92
96
 
93
97
  ### User Stories
98
+ <!-- Describe how users will interact with the feature. Write naturally —
99
+ not locked to a rigid format, but professional and clear.
100
+ Cover the primary flow, then edge cases and error scenarios.
101
+ Each story should be concrete enough that you could write a test for it. -->
94
102
 
95
103
  ### Functional Requirements
104
+ <!-- Numbered list. Each requirement is specific, unambiguous, and testable.
105
+ Group by domain if the feature spans multiple areas.
106
+ Reference user stories where applicable. -->
96
107
 
97
108
  ### Non-Functional Requirements
109
+ <!-- Performance, scalability, security, accessibility, compatibility.
110
+ Include concrete targets where possible (e.g., "responds within 200ms
111
+ at p95 under 1000 concurrent users"). Omit categories that don't apply
112
+ with "N/A — [reason]". -->
98
113
 
99
114
  ### Business Logic
115
+ <!-- Rules, calculations, state machines, validation logic.
116
+ Be precise — this section drives implementation decisions.
117
+ Use examples: "When X happens and Y is true, then Z." -->
100
118
 
101
119
  ### Constraints & Assumptions
120
+ <!-- Technical constraints (language, framework, infrastructure).
121
+ Business constraints (timeline, budget, compliance).
122
+ Assumptions that, if wrong, would change the approach. -->
102
123
 
103
124
  ### Success Criteria
125
+ <!-- How do we verify this feature works? Define acceptance criteria
126
+ at the feature level. These become the basis for the review phase. -->
104
127
 
105
128
  ### Open Questions
106
- ```
107
-
108
- ## Research Angles
109
-
110
- Agents should use all available tools to research:
111
- - **MCP tools** — query context servers, fetch documentation
112
- - **Web search** — find related patterns, prior art, library docs
113
- - **Doc fetching** — read official docs for relevant technologies
114
- - **Codebase analysis** — explore existing code, patterns, conventions
115
- - **Skill discovery** — find relevant skills that may help
116
-
117
- ## Question Chain
129
+ <!-- Questions that surfaced during exploration that the human needs to answer.
130
+ Each question includes context on why it matters and what decision it blocks. -->
118
131
 
119
- **Agents NEVER ask the human directly.** The flow is:
120
-
121
- 1. Agent discovers a gap → sends `WIZARD:` with the question and context
122
- 2. Wizard reasons: "Can I answer this from the PRD description, codebase, or prior knowledge?"
123
- 3. If confident → answer the agent directly via SendMessage
124
- 4. If unsure → digest the question into a clear, contextual question for the human
125
- 5. Wizard asks the human one well-formulated question (not the raw agent question)
126
- 6. Wizard receives answer → interprets, adds context → passes to party
127
-
128
- **Goal:** Minimize questions to human. Batch related questions. The party should figure out as much as possible themselves.
129
-
130
- ## Closing the Phase
132
+ ---
131
133
 
132
- When the PRD is complete (all sections filled, open questions resolved):
134
+ ## Writing Guidance
135
+ - Every section filled. Write "N/A — [reason]" if truly not applicable.
136
+ - Be specific over comprehensive — concrete examples beat abstract descriptions.
137
+ - Reference actual code paths, files, and systems discovered during exploration.
138
+ - Requirements must be testable — if you can't verify it, rewrite it.
139
+ ```
133
140
 
134
- 1. **Wrap up the PRD document** fill gaps, ensure coherence across sections
135
- 2. **Send phase report to human**: "The PRD is forged. Here's what we established: [key points]"
136
- 3. **Commit**: `docs(quest-{slug}): phase 1 PRD — {summary}`
137
- 4. **Transition**: Load `raid-canonical-design` skill and begin Phase 2
141
+ Fill every section. Write "N/A [reason]" if a section truly does not apply.
138
142
 
139
143
  ## Red Flags
140
144
 
@@ -142,12 +146,11 @@ When the PRD is complete (all sections filled, open questions resolved):
142
146
  |---------|---------|
143
147
  | "The requirements are obvious, skip PRD" | If they were obvious, the human would have skipped this phase. |
144
148
  | "Let me start coding to test an idea" | PRD phase. No code. Research and write. |
145
- | "I'll ask the human every question" | Exhaust your own research first. Use MCP, docs, codebase. |
149
+ | "Let me dispatch the agents for research" | PRD is Wizard + Human only. No agents. |
150
+ | "I'll ask 10 questions at once" | One question at a time. Build on answers. |
146
151
  | "This PRD section doesn't apply" | Fill every section. Write "N/A — [reason]" if truly not applicable. |
147
- | "Let me ask the human directly" | Route through the Wizard. Always. |
152
+ | "Good enough, let's move on" | Present to human. Only they decide when it's good enough. |
148
153
 
149
154
  ## Phase Spoils
150
155
 
151
- **Two outputs**:
152
- - `{questDir}/phase-1-prd.md` — Dungeon scoreboard with pinned discoveries, resolved battles, and shared knowledge from agent research
153
- - `{questDir}/prd.md` — Complete Product Requirements Document with all sections filled, synthesized from scoreboard findings
156
+ **One output**: `{questDir}/spoils/prd.md` — Complete Product Requirements Document with all sections filled.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: raid-canonical-protocol
3
- description: "Use at the start of any Canonical Quest. Reference for phase lifecycle, round-based interaction rules, communication signals, and phase transition gates."
3
+ description: "Use at the start of any Canonical Quest. Reference for phase lifecycle, transition gates, phase spoils, and skills map."
4
4
  ---
5
5
 
6
6
  # Canonical Quest Protocol
@@ -8,7 +8,7 @@ description: "Use at the start of any Canonical Quest. Reference for phase lifec
8
8
  The canonical workflow for full-cycle development. Every feature, refactor, or system built through the Raid follows this sequence.
9
9
 
10
10
  <HARD-GATE>
11
- 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.
11
+ Do NOT skip phases. Do NOT let a single agent work unchallenged. Do NOT proceed without a Wizard ruling. Agents communicate via SendMessage — do not spawn subagents.
12
12
  </HARD-GATE>
13
13
 
14
14
  ## Session Lifecycle
@@ -41,17 +41,9 @@ digraph session {
41
41
  | **Archer** | Pattern-seeker, traces ripple effects, naming drift | Green |
42
42
  | **Rogue** | Adversarial assumption-destroyer, attack scenarios | Orange |
43
43
 
44
- ## Modes
44
+ ## Party Composition
45
45
 
46
- | Aspect | Full Raid | Skirmish | Scout |
47
- |--------|-----------|----------|-------|
48
- | Agents | 3 | 2 | 1 |
49
- | PRD phase | Full | Lightweight | Skip |
50
- | Design | Full adversarial | Lightweight | Inline |
51
- | Plan | Full adversarial | Combined with design | Inline |
52
- | Implementation | 1 builds, 2 cross-test | 1 builds, 1 cross-tests | 1 builds, Wizard reviews |
53
- | Review | 3 independent + fighting | 1 review + Wizard | Wizard only |
54
- | TDD | **Enforced** | **Enforced** | **Enforced** |
46
+ The Canonical Quest always runs with the full party: Wizard + Warrior + Archer + Rogue (4 agents). 3 sequential turns per round, 2-3 rounds per phase. TDD enforced. No reduced-party modes.
55
47
 
56
48
  ## Plan Mode
57
49
 
@@ -59,47 +51,11 @@ Claude Code's plan mode is incompatible with the Raid. The Raid has its own perm
59
51
 
60
52
  The Wizard detects plan mode at session start (Step 0 in `raid-init`) and asks the human to exit it before proceeding.
61
53
 
62
- ## Round-Based Interaction
63
-
64
- Think turn-based RPG, not real-time:
65
-
66
- ```
67
- ROUND START → Wizard dispatches tasks/angles
68
-
69
- PARALLEL WORK → Each agent works independently
70
-
71
- FLAG COMPLETION → Agent signals ROUND_COMPLETE: to Wizard
72
-
73
- CROSS-TESTING → Wizard assigns completed work for review
74
-
75
- REACTIONS → Agents test, challenge, build
76
-
77
- RESOLUTION → Findings pinned to dungeon or conceded
78
-
79
- ROUND END → Wizard assesses: next round or phase close
80
- ```
81
-
82
- **Rules:**
83
- - No mid-thinking interruptions between agents (only Wizard can interrupt)
84
- - Each message must carry evidence + conclusion (no shallow exchanges)
85
- - Converge in 2-3 exchanges per finding; escalate to Wizard after 3
86
- - Party is silent during phase transitions
87
-
88
- ## Question Chain
89
-
90
- Agents → Wizard → Human. Agents NEVER ask the human directly.
91
-
92
- 1. Agent discovers gap → sends `WIZARD:` with question
93
- 2. Wizard reasons: can I answer from PRD, codebase, context?
94
- 3. If confident → answers agent directly
95
- 4. If unsure → digests question, asks human one clear question
96
- 5. Wizard passes answer back with interpretation
97
-
98
54
  ## Phase Transition Gates
99
55
 
100
56
  | From | To | Gate | Commit Format |
101
57
  |------|----|------|---------------|
102
- | PRD | Design | PRD approved by Wizard | `docs(quest-{slug}): phase 1 PRD` |
58
+ | PRD | Design | PRD approved by Human | `docs(quest-{slug}): phase 1 PRD` |
103
59
  | Design | Plan | Design doc approved, committed | `docs(quest-{slug}): phase 2 design` |
104
60
  | Plan | Implementation | Plan approved, committed | `docs(quest-{slug}): phase 3 plan` |
105
61
  | Implementation | Review | All tasks done, tests pass | `feat(quest-{slug}): phase 4 implementation` |
@@ -111,79 +67,29 @@ Agents → Wizard → Human. Agents NEVER ask the human directly.
111
67
 
112
68
  Every phase MUST produce at least one detailed markdown artifact:
113
69
 
114
- | Phase | Scoreboard (phase file) | Deliverable |
115
- |-------|--------------------------|-------------|
116
- | PRD | `{questDir}/phase-1-prd.md` | `{questDir}/prd.md` |
117
- | Design | `{questDir}/phase-2-design.md` | `{questDir}/design.md` |
118
- | Plan | `{questDir}/phase-3-plan.md` | task files (`phase-3-plan-task-NN.md`) |
119
- | Implementation | `{questDir}/phase-4-implementation.md` | code changes |
120
- | Review | `{questDir}/phase-5-review.md` | fixes |
70
+ | Phase | Evolution Log | Deliverable |
71
+ |-------|---------------|-------------|
72
+ | PRD | (none — wizard+human only) | `{questDir}/spoils/prd.md` |
73
+ | Design | `{questDir}/phases/phase-2-design.md` | `{questDir}/spoils/design.md` |
74
+ | Plan | `{questDir}/phases/phase-3-plan.md` | task files (`spoils/tasks/phase-3-plan-task-NN.md`) |
75
+ | Implementation | `{questDir}/phases/phase-4-implementation.md` | code changes + summary table |
76
+ | Review | `{questDir}/phases/phase-5-review.md` | `{questDir}/spoils/review.md` (fix plan) |
121
77
  | Wrap Up | `{questDir}/phase-6-wrap-up.md` | PR + storyboard |
122
78
 
123
- ## Communication Signals
124
-
125
- | Signal | Who | Meaning | Goes to Dungeon? |
126
- |--------|-----|---------|-----------------|
127
- | `DISPATCH:` | Wizard | Opening a phase, assigning angles | No |
128
- | `ROUND_COMPLETE:` | Any agent | Finished assigned task | No |
129
- | `FINDING:` | Any agent | Discovery with own evidence | No |
130
- | `CHALLENGE:` | Any agent | Independently verified, found problem | No |
131
- | `BUILDING:` | Any agent | Independently verified, goes deeper | No |
132
- | `DUNGEON:` | Any agent | Pinning finding verified by 2+ agents | **Yes** |
133
- | `BLACKCARD:` | Any agent | High-concern finding blocking progress | **Yes** |
134
- | `WIZARD:` | Any agent | Escalation — needs Wizard input | Yes (escalation) |
135
- | `CONCEDE:` | Any agent | Proven wrong, moving on | No |
136
- | `RULING:` | Wizard | Binding decision, phase close | Archived |
137
- | `REDIRECT:` | Wizard | Course correction, one sentence | No |
138
-
139
- ## Black Card System
79
+ ## Dice Roll Reference
140
80
 
141
- A `BLACKCARD:` is a finding that fundamentally breaks the architecture unfixable within current design.
81
+ When a phase needs a dice roll, use this jq command to shuffle the turn order:
142
82
 
143
- **Flow:** Agent plays → 2+ agents verify → Wizard escalates to human → Options: (a) rollback to earlier phase, (b) accept limitation.
144
-
145
- Black cards are RARE. Most issues are Critical or Important, not black cards.
146
-
147
- ## The Dungeon
148
-
149
- Quest directory at `.claude/dungeon/{quest-slug}/`. Each phase produces a file.
150
-
151
- | Event | Action | Who |
152
- |-------|--------|-----|
153
- | Quest starts | Create quest directory | Hook |
154
- | Phase opens | Create `{questDir}/phase-N-{name}.md` with boilerplate | Wizard |
155
- | During phase | Pin findings via `DUNGEON:` | Agents |
156
- | Phase closes | Wrap up doc, commit | Wizard |
157
- | Quest ends | Move to `.claude/vault/{quest-slug}/` | Wizard |
158
-
159
- **The Dungeon is a scoreboard, not a chat log.** Only verified findings, resolved battles, shared knowledge.
160
-
161
- ## Wizard Behavior
162
-
163
- - **90% thinking / 10% talking** — thinks 5x before speaking
164
- - **NEVER implements** — dispatches, observes, digests, rules
165
- - **Opens and closes every phase** — creates phase file, dispatches, then goes silent
166
- - **Phase reports** — at every close, summarizes for human: what was done, what's next
167
- - **Question gatekeeper** — digests before passing in either direction
168
- - **Commits at every transition** — with quest name + phase + summary
169
-
170
- ## Configuration
171
-
172
- Read `.claude/raid.json` for project settings:
173
-
174
- | Key | Default | Purpose |
175
- |-----|---------|---------|
176
- | `project.testCommand` | (none) | Command to run tests |
177
- | `project.packageManager` | (auto) | Package manager |
178
- | `raid.defaultMode` | `full` | Default mode |
179
- | `raid.agentEffort` | `medium` | Agent effort level (Wizard always max) |
180
- | `raid.vault.path` | `.claude/vault` | Vault location |
181
- | `browser.enabled` | `false` | Browser testing active |
83
+ ```bash
84
+ jq --argjson to '["warrior","archer","rogue"]' \
85
+ '.turnOrder=($to | [.[] | {name: ., r: (now * 1000 % 997 | floor)}] | sort_by(.r) | [.[].name]) | .currentRound=1 | .currentTurnIndex=0 | .maxRounds=3' \
86
+ .claude/raid-session > .claude/raid-session.tmp && mv .claude/raid-session.tmp .claude/raid-session
87
+ ```
182
88
 
183
89
  ## Browser Testing
184
90
 
185
- When `browser.enabled` is `true`:
186
- - **Phase 4 (Implementation):** Browser-facing code uses TDD with Playwright via `raid-tdd`. Challengers verify on isolated ports.
91
+ When `browser.enabled` is `true` in `raid.json`:
92
+ - **Phase 4 (Implementation):** Browser-facing code uses TDD with Playwright via `raid-tdd`.
187
93
  - **Phase 5 (Review):** Live adversarial Chrome inspection via `raid-browser-chrome`. Each agent on separate port.
188
94
  - Invoke `raid-browser` for startup discovery and pre-flight.
189
95
 
@@ -192,12 +98,12 @@ When `browser.enabled` is `true`:
192
98
  | Skill | Phase | Purpose |
193
99
  |-------|-------|---------|
194
100
  | `raid-init` | Pre-phase | Quest selection, greeting, session setup |
195
- | `raid-canonical-protocol` | Start | This doc — session lifecycle, rules, reference |
196
- | `raid-canonical-prd` | 1 | PRD creation (optional) |
197
- | `raid-canonical-design` | 2 | Adversarial design exploration |
198
- | `raid-canonical-implementation-plan` | 3 | Task decomposition |
199
- | `raid-canonical-implementation` | 4 | TDD implementation with cross-testing |
200
- | `raid-canonical-review` | 5 | Pinning + fixing + black cards (optional) |
101
+ | `raid-canonical-protocol` | Start | This doc — lifecycle, gates, spoils, reference |
102
+ | `raid-canonical-prd` | 1 | PRD creation — wizard+human only (optional) |
103
+ | `raid-canonical-design` | 2 | Writer/reviewer design with defend-concede |
104
+ | `raid-canonical-implementation-plan` | 3 | Writer/reviewer task decomposition |
105
+ | `raid-canonical-implementation` | 4 | Strategic TDD implementation no challengers |
106
+ | `raid-canonical-review` | 5 | Review + fix sub-phase (optional) |
201
107
  | `raid-wrap-up` | 6 | Storyboard, PR, vault archival |
202
108
  | `raid-tdd` | Any | RED-GREEN-REFACTOR enforcement |
203
109
  | `raid-verification` | Any | Evidence-before-claims gate |
@@ -210,8 +116,8 @@ When `browser.enabled` is `true`:
210
116
  | Thought | Reality |
211
117
  |---------|---------|
212
118
  | "This phase is obvious, skip it" | Obvious phases hide assumptions. |
213
- | "The agents agree, no need for cross-testing" | Agreement without challenge is groupthink. |
119
+ | "The agents agree after one round, let's close" | Minimum 2 rounds. Agreement without challenge is groupthink. |
214
120
  | "TDD would slow us down" | TDD is an Iron Law. No exceptions. |
215
121
  | "Let me ask the human directly" | Route through the Wizard. Always. |
216
122
  | "Let me just post everything to the Dungeon" | Pin only what survived challenge. |
217
- | "I'll wait for the Wizard to tell me what to do" | Self-organize within the round. |
123
+ | "I'll wait for the Wizard to tell me what to do" | You wait for your turn dispatch, then work your angle fully. |