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.
- package/README.md +84 -23
- package/bin/cli.js +4 -2
- package/package.json +1 -1
- package/src/descriptions.js +10 -7
- package/src/init.js +36 -5
- package/src/merge-settings.js +53 -2
- package/src/remove.js +1 -1
- package/src/setup.js +32 -0
- package/src/ui.js +1 -0
- package/src/update.js +26 -3
- package/template/.claude/agents/archer.md +18 -4
- package/template/.claude/agents/rogue.md +18 -4
- package/template/.claude/agents/warrior.md +18 -4
- package/template/.claude/agents/wizard.md +32 -5
- package/template/.claude/dungeon-master-rules.md +120 -31
- package/template/.claude/hooks/raid-lib.sh +45 -4
- package/template/.claude/hooks/raid-pre-compact.sh +8 -4
- package/template/.claude/hooks/raid-session-end.sh +2 -2
- package/template/.claude/hooks/raid-session-start.sh +2 -0
- package/template/.claude/hooks/rtk-bridge.sh +46 -0
- package/template/.claude/hooks/validate-dungeon.sh +11 -3
- package/template/.claude/hooks/validate-file-naming.sh +6 -1
- package/template/.claude/hooks/validate-no-placeholders.sh +13 -2
- package/template/.claude/hooks/validate-write-gate.sh +7 -2
- package/template/.claude/party-rules.md +91 -65
- package/template/.claude/skills/raid-browser/SKILL.md +3 -5
- package/template/.claude/skills/raid-browser-chrome/SKILL.md +1 -1
- package/template/.claude/skills/raid-canonical-design/SKILL.md +309 -162
- package/template/.claude/skills/raid-canonical-implementation/SKILL.md +157 -132
- package/template/.claude/skills/raid-canonical-implementation-plan/SKILL.md +196 -141
- package/template/.claude/skills/raid-canonical-prd/SKILL.md +92 -89
- package/template/.claude/skills/raid-canonical-protocol/SKILL.md +29 -123
- package/template/.claude/skills/raid-canonical-review/SKILL.md +292 -148
- package/template/.claude/skills/raid-debugging/SKILL.md +1 -7
- package/template/.claude/skills/raid-init/SKILL.md +7 -5
- package/template/.claude/skills/raid-tdd/SKILL.md +5 -5
- package/template/.claude/skills/raid-teambuff/SKILL.md +6 -24
- package/template/.claude/skills/raid-verification/SKILL.md +0 -6
- 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
|
|
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.
|
|
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
|
-
"
|
|
25
|
-
"
|
|
26
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
-
"
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
58
|
+
6. **Present the PRD to the human for approval.** Walk through the key sections. Ask: "Does this capture everything?"
|
|
74
59
|
|
|
75
|
-
|
|
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
|
-
|
|
62
|
+
8. **Commit:** `docs(quest-{slug}): phase 1 PRD — {summary}`
|
|
79
63
|
|
|
80
|
-
|
|
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
|
-
#
|
|
73
|
+
# [Feature Name] — Product Requirements Document
|
|
84
74
|
|
|
85
|
-
|
|
75
|
+
## Quest: [quest description]
|
|
76
|
+
## Date: YYYY-MM-DD
|
|
77
|
+
## Author: Wizard
|
|
86
78
|
|
|
87
|
-
|
|
79
|
+
## Quest Goal
|
|
80
|
+
<!-- Wizard writes 2-3 lines: what this PRD aims to capture and why -->
|
|
88
81
|
|
|
89
|
-
|
|
82
|
+
---
|
|
90
83
|
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
| "
|
|
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
|
-
| "
|
|
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
|
-
**
|
|
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,
|
|
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
|
|
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
|
-
##
|
|
44
|
+
## Party Composition
|
|
45
45
|
|
|
46
|
-
|
|
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
|
|
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 |
|
|
115
|
-
|
|
116
|
-
| PRD |
|
|
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` |
|
|
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
|
-
##
|
|
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
|
-
|
|
81
|
+
When a phase needs a dice roll, use this jq command to shuffle the turn order:
|
|
142
82
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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`.
|
|
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 —
|
|
196
|
-
| `raid-canonical-prd` | 1 | PRD creation (optional) |
|
|
197
|
-
| `raid-canonical-design` | 2 |
|
|
198
|
-
| `raid-canonical-implementation-plan` | 3 |
|
|
199
|
-
| `raid-canonical-implementation` | 4 | TDD implementation
|
|
200
|
-
| `raid-canonical-review` | 5 |
|
|
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
|
|
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" |
|
|
123
|
+
| "I'll wait for the Wizard to tell me what to do" | You wait for your turn dispatch, then work your angle fully. |
|