claude-raid 0.2.4 → 0.2.6
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 +280 -252
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,160 +1,246 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
```
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
```
|
|
4
|
+
⚔ ══════════════════════════════════════════════════════════ ⚔
|
|
5
|
+
|
|
6
|
+
██████╗██╗ █████╗ ██╗ ██╗██████╗ ███████╗
|
|
7
|
+
██╔════╝██║ ██╔══██╗██║ ██║██╔══██╗██╔════╝
|
|
8
|
+
██║ ██║ ███████║██║ ██║██║ ██║█████╗
|
|
9
|
+
██║ ██║ ██╔══██║██║ ██║██║ ██║██╔══╝
|
|
10
|
+
╚██████╗███████╗██║ ██║╚██████╔╝██████╔╝███████╗
|
|
11
|
+
╚═════╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
|
|
12
|
+
██████╗ █████╗ ██╗██████╗
|
|
13
|
+
██╔══██╗██╔══██╗██║██╔══██╗
|
|
14
|
+
██████╔╝███████║██║██║ ██║
|
|
15
|
+
██╔══██╗██╔══██║██║██║ ██║
|
|
16
|
+
██║ ██║██║ ██║██║██████╔╝
|
|
17
|
+
╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚═════╝
|
|
18
|
+
|
|
19
|
+
Round-based Adversarial Intelligence Dungeon
|
|
20
|
+
for Claude Code
|
|
21
|
+
|
|
22
|
+
⚔ ══════════════════════════════════════════════════════════ ⚔
|
|
22
23
|
```
|
|
23
24
|
|
|
24
|
-
Four AI agents
|
|
25
|
+
**Four AI agents. One shared dungeon. Every decision stress-tested before it ships.**
|
|
26
|
+
|
|
27
|
+
[](LICENSE)
|
|
28
|
+
[](#)
|
|
29
|
+
[](#prerequisites)
|
|
30
|
+
[](#)
|
|
31
|
+
|
|
32
|
+
[Quick Start](#quick-start) · [The Canonical Quest](#the-canonical-quest) · [The Party](#the-party) · [The Dungeon](#the-dungeon) · [Configuration](#configuration) · [CLI Reference](#cli-reference)
|
|
33
|
+
|
|
34
|
+
</div>
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## What is Claude Raid?
|
|
39
|
+
|
|
40
|
+
Claude Raid turns a single Claude Code session into a **4-agent adversarial team** that designs, plans, builds, reviews, and ships code through structured phases. Instead of one AI guessing at a solution, four agents challenge each other's work until only battle-tested decisions survive.
|
|
25
41
|
|
|
26
|
-
|
|
42
|
+
The **Wizard** orchestrates. The **Warrior**, **Archer**, and **Rogue** each bring a different lens — stress tolerance, pattern coherence, and assumption destruction. They work in rounds, pin verified findings to a shared **Dungeon**, and no phase closes until the Wizard rules.
|
|
27
43
|
|
|
28
|
-
|
|
44
|
+
One command installs the system. One command starts a quest.
|
|
29
45
|
|
|
30
46
|
---
|
|
31
47
|
|
|
32
48
|
## Quick Start
|
|
33
49
|
|
|
34
50
|
```bash
|
|
35
|
-
# Install into any project
|
|
36
51
|
npx claude-raid summon
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
That's it. One command installs agents, hooks, skills, and config into your project's `.claude/` directory.
|
|
37
55
|
|
|
38
|
-
|
|
56
|
+
```bash
|
|
57
|
+
# Preview what gets installed (no changes)
|
|
39
58
|
npx claude-raid summon --dry-run
|
|
40
59
|
|
|
41
|
-
# Start a
|
|
42
|
-
|
|
43
|
-
claude --agent wizard
|
|
60
|
+
# Start a quest
|
|
61
|
+
claude-raid start
|
|
44
62
|
```
|
|
45
63
|
|
|
46
|
-
|
|
64
|
+
The Wizard greets you, you describe your task, and the quest begins.
|
|
47
65
|
|
|
48
66
|
### Prerequisites
|
|
49
67
|
|
|
50
|
-
| Requirement | Why |
|
|
51
|
-
|
|
52
|
-
| **Node.js** 18+ | Runs the
|
|
53
|
-
| **Claude Code** v2.1.32+ | Agent teams support |
|
|
54
|
-
| **tmux** | Multi-pane agent display
|
|
55
|
-
| **jq** |
|
|
56
|
-
| **teammateMode** | Set to `tmux` in `~/.claude.json` | Yes (wizard prompts) |
|
|
68
|
+
| Requirement | Why |
|
|
69
|
+
|:--|:--|
|
|
70
|
+
| **Node.js** 18+ | Runs the CLI |
|
|
71
|
+
| **Claude Code** v2.1.32+ | Agent teams support |
|
|
72
|
+
| **tmux** | Multi-pane agent display (`brew install tmux`) |
|
|
73
|
+
| **jq** | Config parsing (pre-installed on macOS) |
|
|
57
74
|
|
|
58
|
-
**tmux
|
|
75
|
+
> **tmux** gives each agent its own pane — click into any pane to observe or talk to that agent directly. Without tmux, agents run in-process and you cycle between them with `Shift+Down`.
|
|
59
76
|
|
|
60
|
-
The setup wizard checks all
|
|
77
|
+
The setup wizard checks all prerequisites during `summon` and offers to fix what it can.
|
|
61
78
|
|
|
62
79
|
---
|
|
63
80
|
|
|
64
|
-
##
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
81
|
+
## The Canonical Quest
|
|
82
|
+
|
|
83
|
+
The Canonical Quest is a 6-phase development cycle. Every feature, refactor, or system built through the Raid follows this sequence.
|
|
84
|
+
|
|
85
|
+
```mermaid
|
|
86
|
+
flowchart LR
|
|
87
|
+
PRD["Phase 1\nPRD"]
|
|
88
|
+
Design["Phase 2\nDesign"]
|
|
89
|
+
Plan["Phase 3\nPlan"]
|
|
90
|
+
Impl["Phase 4\nImplementation"]
|
|
91
|
+
Review["Phase 5\nReview"]
|
|
92
|
+
Wrap["Phase 6\nWrap Up"]
|
|
93
|
+
|
|
94
|
+
PRD -->|"optional"| Design
|
|
95
|
+
Design --> Plan
|
|
96
|
+
Plan --> Impl
|
|
97
|
+
Impl --> Review
|
|
98
|
+
Review -->|"optional"| Wrap
|
|
99
|
+
Impl -->|"skip review"| Wrap
|
|
100
|
+
|
|
101
|
+
style PRD fill:#6c5ce7,color:#fff
|
|
102
|
+
style Design fill:#6c5ce7,color:#fff
|
|
103
|
+
style Plan fill:#6c5ce7,color:#fff
|
|
104
|
+
style Impl fill:#e17055,color:#fff
|
|
105
|
+
style Review fill:#00b894,color:#fff
|
|
106
|
+
style Wrap fill:#fdcb6e,color:#000
|
|
68
107
|
```
|
|
69
|
-
Phase 1: DESIGN Agents explore the problem from competing angles.
|
|
70
|
-
Challenge each other's findings. Pin what survives.
|
|
71
|
-
Wizard closes when the design is battle-tested.
|
|
72
108
|
|
|
73
|
-
Phase
|
|
74
|
-
Fight over naming, ordering, coverage, compliance.
|
|
75
|
-
Pin the agreed task list.
|
|
109
|
+
### Phase 1 — PRD *(optional)*
|
|
76
110
|
|
|
77
|
-
|
|
78
|
-
The others attack the implementation directly.
|
|
79
|
-
Every task earns approval before moving on.
|
|
111
|
+
Agents research the problem space and produce a complete Product Requirements Document. No code. The Wizard mediates questions between agents and the human.
|
|
80
112
|
|
|
81
|
-
|
|
82
|
-
Agents fight over findings AND missing findings.
|
|
83
|
-
Critical and Important issues must be fixed.
|
|
113
|
+
**Output:** `phase-1-prd.md`
|
|
84
114
|
|
|
85
|
-
|
|
86
|
-
merge options: merge, PR, keep branch, or discard.
|
|
87
|
-
```
|
|
115
|
+
### Phase 2 — Design
|
|
88
116
|
|
|
89
|
-
|
|
117
|
+
Agents explore design approaches from competing angles. Each brings their lens — the Warrior stress-tests architecture choices, the Archer traces ripple effects, the Rogue attacks assumptions. The design survives only if it withstands all three.
|
|
90
118
|
|
|
91
|
-
|
|
119
|
+
**Output:** `phase-2-design.md` with mermaid diagrams and battle-tested decisions
|
|
92
120
|
|
|
93
|
-
|
|
121
|
+
### Phase 3 — Plan
|
|
94
122
|
|
|
95
|
-
|
|
123
|
+
Agents decompose the approved design into discrete, testable tasks. They fight over ordering, scope boundaries, naming, and test coverage until the plan earns consensus.
|
|
96
124
|
|
|
97
|
-
|
|
125
|
+
**Output:** `phase-3-plan.md` + individual task files (`phase-3-plan-task-01.md`, etc.)
|
|
98
126
|
|
|
99
|
-
###
|
|
127
|
+
### Phase 4 — Implementation
|
|
100
128
|
|
|
101
|
-
|
|
129
|
+
The Wizard assigns tasks in batches. One agent builds each task using strict **TDD** (RED-GREEN-REFACTOR). The others cross-test the implementation — reading code, running tests, and challenging decisions. Every task earns approval before the next batch starts.
|
|
102
130
|
|
|
103
|
-
|
|
131
|
+
**Output:** `phase-4-implementation.md` + committed, tested code
|
|
104
132
|
|
|
105
|
-
|
|
133
|
+
### Phase 5 — Review *(optional)*
|
|
106
134
|
|
|
107
|
-
|
|
135
|
+
Two sub-phases: **Pinning** (find issues) and **Fixing** (resolve them). Agents review independently, then fight over findings *and* missing findings. Critical and Important issues must be fixed. The **Black Card** system handles breaking architectural concerns.
|
|
108
136
|
|
|
109
|
-
|
|
137
|
+
**Output:** `phase-5-review.md`
|
|
110
138
|
|
|
111
|
-
|
|
139
|
+
### Phase 6 — Wrap Up
|
|
112
140
|
|
|
113
|
-
|
|
141
|
+
The Wizard generates a quest storyboard summarizing what was built and why. Creates the PR, archives the dungeon to the vault, and dismisses the party.
|
|
114
142
|
|
|
115
|
-
|
|
143
|
+
**Output:** `phase-6-wrap-up.md` + PR + vault archive
|
|
116
144
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## The Party
|
|
148
|
+
|
|
149
|
+
Four agents, each with a distinct lens. They collaborate through rigor, not agreement.
|
|
150
|
+
|
|
151
|
+
<table>
|
|
152
|
+
<tr>
|
|
153
|
+
<td width="25%" align="center"><h3>Wizard</h3><em>Dungeon Master</em></td>
|
|
154
|
+
<td width="25%" align="center"><h3>Warrior</h3><em>Stress Tester</em></td>
|
|
155
|
+
<td width="25%" align="center"><h3>Archer</h3><em>Pattern Seeker</em></td>
|
|
156
|
+
<td width="25%" align="center"><h3>Rogue</h3><em>Assumption Destroyer</em></td>
|
|
157
|
+
</tr>
|
|
158
|
+
<tr>
|
|
159
|
+
<td valign="top">Thinks 5 times before speaking. Opens phases, dispatches the team, observes, and closes with binding rulings. The bridge between agents, dungeon, and human. <strong>Never writes code.</strong></td>
|
|
160
|
+
<td valign="top">Does this hold under pressure? Tests boundaries, load, edge cases, and failure modes. Brings the exact scenario that breaks it — not just "this is wrong."</td>
|
|
161
|
+
<td valign="top">Does this fit? Traces how changes ripple through the system. Catches naming drift, contract violations, and implicit dependencies that break silently.</td>
|
|
162
|
+
<td valign="top">What did everyone assume that isn't guaranteed? Thinks like a failing system, a malicious input, a race condition. Constructs the attack sequence that turns oversight into failure.</td>
|
|
163
|
+
</tr>
|
|
164
|
+
</table>
|
|
165
|
+
|
|
166
|
+
### How They Work Together
|
|
167
|
+
|
|
168
|
+
```mermaid
|
|
169
|
+
sequenceDiagram
|
|
170
|
+
participant W as Wizard
|
|
171
|
+
participant Party as Warrior / Archer / Rogue
|
|
172
|
+
|
|
173
|
+
W->>Party: Dispatch tasks + angles
|
|
174
|
+
Note over Party: Parallel independent work
|
|
175
|
+
Party->>W: ROUND_COMPLETE
|
|
176
|
+
W->>Party: Cross-test each other's work
|
|
177
|
+
Note over Party: Challenge, verify, concede or escalate
|
|
178
|
+
Party->>W: Findings + evidence
|
|
179
|
+
W->>W: Pin verified findings to Dungeon
|
|
180
|
+
Note over W: Next round or phase close
|
|
181
|
+
```
|
|
125
182
|
|
|
126
|
-
**
|
|
183
|
+
**Round-based, not real-time.** Agents work independently, flag completion, then cross-test. No mid-thinking interruptions. Each message carries evidence and a conclusion. Converge in 2-3 exchanges per finding — escalate to the Wizard after 3.
|
|
127
184
|
|
|
128
|
-
|
|
129
|
-
- **Skirmish** — Medium features, non-trivial bugfixes, multi-file changes
|
|
130
|
-
- **Scout** — Config changes, documentation, single-file fixes
|
|
185
|
+
### Seven Pillars
|
|
131
186
|
|
|
132
|
-
|
|
187
|
+
Every agent, every phase, every interaction:
|
|
133
188
|
|
|
134
|
-
|
|
189
|
+
1. **Intellectual Honesty** — Every claim backed by evidence gathered this turn. No guessing.
|
|
190
|
+
2. **Zero Ego** — Concede instantly when proven wrong. A teammate catching your mistake is a gift.
|
|
191
|
+
3. **Discipline** — Every interaction carries work forward. If you're not adding information, stop talking.
|
|
192
|
+
4. **Round-Based Interaction** — Turn-based work, flag completion, cross-test on dispatch.
|
|
193
|
+
5. **Question Chain** — Agents never ask the human directly. All questions flow through the Wizard.
|
|
194
|
+
6. **Phase Spoils** — Every phase produces a detailed markdown artifact. No exceptions.
|
|
195
|
+
7. **Black Cards** — Architecture-breaking findings that cannot be fixed within the current design. Escalated to the human with rollback options.
|
|
135
196
|
|
|
136
197
|
---
|
|
137
198
|
|
|
138
199
|
## The Dungeon
|
|
139
200
|
|
|
140
|
-
The Dungeon
|
|
201
|
+
The Dungeon is the team's shared knowledge artifact — a curated board where agents pin verified findings during each phase.
|
|
202
|
+
|
|
203
|
+
| Concept | What It Means |
|
|
204
|
+
|:--|:--|
|
|
205
|
+
| **Quest** | A complete session — from greeting to PR |
|
|
206
|
+
| **Dungeon** | The quest's artifact directory: phase files, task files, findings |
|
|
207
|
+
| **Vault** | Archive of completed quests for institutional memory |
|
|
208
|
+
| **Phase Spoils** | Mandatory output of each phase: a detailed markdown report |
|
|
209
|
+
| **Black Card** | A finding that fundamentally breaks the architecture — requires human decision |
|
|
210
|
+
| **Pin** | A verified finding that survived challenge from 2+ agents |
|
|
141
211
|
|
|
142
|
-
|
|
212
|
+
### Dungeon Filesystem
|
|
143
213
|
|
|
144
|
-
|
|
214
|
+
```
|
|
215
|
+
.claude/dungeon/{quest-slug}/ # Active quest artifacts
|
|
216
|
+
├── phase-1-prd.md # PRD (optional)
|
|
217
|
+
├── phase-2-design.md # Battle-tested design
|
|
218
|
+
├── phase-3-plan.md # Task index
|
|
219
|
+
├── phase-3-plan-task-01.md # Individual task specs
|
|
220
|
+
├── phase-4-implementation.md # Implementation log
|
|
221
|
+
├── phase-5-review.md # Review board (optional)
|
|
222
|
+
└── phase-6-wrap-up.md # Quest storyboard
|
|
223
|
+
|
|
224
|
+
.claude/vault/{quest-slug}/ # Archived completed quests
|
|
225
|
+
.claude/raid-session # Active session state
|
|
226
|
+
```
|
|
145
227
|
|
|
146
|
-
**
|
|
228
|
+
**What goes in the Dungeon:** Findings that survived challenge from 2+ agents, key decisions, escalation points.
|
|
147
229
|
|
|
148
|
-
|
|
230
|
+
**What stays in conversation:** Back-and-forth challenges, exploratory thinking, concessions. The conversation is the sparring ring. The Dungeon is the scoreboard.
|
|
149
231
|
|
|
150
232
|
---
|
|
151
233
|
|
|
152
234
|
## What Gets Installed
|
|
153
235
|
|
|
236
|
+
<details>
|
|
237
|
+
<summary><strong>Full file tree</strong></summary>
|
|
238
|
+
|
|
154
239
|
```
|
|
155
240
|
.claude/
|
|
156
241
|
├── raid.json # Project config (auto-detected, editable)
|
|
157
|
-
├──
|
|
242
|
+
├── party-rules.md # Party agent rules (editable)
|
|
243
|
+
├── dungeon-master-rules.md # Wizard rules (editable)
|
|
158
244
|
├── settings.json # Hooks merged with existing (backup created)
|
|
159
245
|
├── agents/
|
|
160
246
|
│ ├── wizard.md # Dungeon master
|
|
@@ -163,127 +249,59 @@ Agents interact directly — `@Name` mentions, building on each other's discover
|
|
|
163
249
|
│ └── rogue.md # Assumption destroyer
|
|
164
250
|
├── hooks/
|
|
165
251
|
│ ├── raid-lib.sh # Shared config and session state
|
|
166
|
-
│ ├── raid-session-start.sh # Session activation
|
|
167
|
-
│ ├── raid-session-end.sh # Archive
|
|
168
|
-
│ ├── raid-
|
|
169
|
-
│ ├── raid-pre-compact.sh # Pre-compaction backup
|
|
252
|
+
│ ├── raid-session-start.sh # Session activation + quest directory
|
|
253
|
+
│ ├── raid-session-end.sh # Archive to vault + cleanup
|
|
254
|
+
│ ├── raid-pre-compact.sh # Pre-compaction dungeon backup
|
|
170
255
|
│ ├── raid-task-created.sh # Task subject validation
|
|
171
|
-
│ ├──
|
|
172
|
-
│ ├──
|
|
173
|
-
│ ├── validate-commit.sh # Conventional commits + test gate
|
|
174
|
-
│ ├── validate-write-gate.sh # Design doc before implementation
|
|
256
|
+
│ ├── validate-commit.sh # Conventional commits
|
|
257
|
+
│ ├── validate-write-gate.sh # Phase-based write protection
|
|
175
258
|
│ ├── validate-file-naming.sh # Naming convention enforcement
|
|
176
259
|
│ ├── validate-no-placeholders.sh # No TBD/TODO in specs
|
|
177
260
|
│ ├── validate-dungeon.sh # Multi-agent verification on pins
|
|
178
261
|
│ ├── validate-browser-tests-exist.sh # Playwright test detection
|
|
179
262
|
│ └── validate-browser-cleanup.sh # Browser process cleanup
|
|
180
263
|
└── skills/
|
|
181
|
-
├── raid-
|
|
182
|
-
├── raid-
|
|
183
|
-
├── raid-
|
|
184
|
-
├── raid-
|
|
185
|
-
├── raid-
|
|
186
|
-
├── raid-
|
|
264
|
+
├── raid-init/ # Quest selection and session setup
|
|
265
|
+
├── raid-canonical-protocol/ # Canonical Quest rules and signals
|
|
266
|
+
├── raid-canonical-prd/ # Phase 1: PRD creation
|
|
267
|
+
├── raid-canonical-design/ # Phase 2: Adversarial design
|
|
268
|
+
├── raid-canonical-implementation-plan/ # Phase 3: Task decomposition
|
|
269
|
+
├── raid-canonical-implementation/ # Phase 4: TDD + cross-testing
|
|
270
|
+
├── raid-canonical-review/ # Phase 5: Pinning + fixing
|
|
271
|
+
├── raid-wrap-up/ # Phase 6: Storyboard + PR + vault
|
|
187
272
|
├── raid-tdd/ # RED-GREEN-REFACTOR enforcement
|
|
188
|
-
├── raid-debugging/ # Root-cause investigation
|
|
189
273
|
├── raid-verification/ # Evidence-before-claims gate
|
|
190
|
-
├── raid-
|
|
191
|
-
├── raid-browser/ # Browser
|
|
192
|
-
|
|
193
|
-
└── raid-browser-chrome/ # Live browser inspection
|
|
274
|
+
├── raid-debugging/ # Root-cause investigation
|
|
275
|
+
├── raid-browser/ # Browser orchestration
|
|
276
|
+
└── raid-browser-chrome/ # Live Chrome inspection
|
|
194
277
|
```
|
|
195
278
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
---
|
|
199
|
-
|
|
200
|
-
## Hooks
|
|
201
|
-
|
|
202
|
-
Hooks enforce workflow discipline automatically. They split into two categories:
|
|
203
|
-
|
|
204
|
-
### Lifecycle Hooks
|
|
205
|
-
|
|
206
|
-
Manage session state without manual intervention. These activate and deactivate as sessions begin and end.
|
|
207
|
-
|
|
208
|
-
| Hook | Trigger | Purpose |
|
|
209
|
-
|---|---|---|
|
|
210
|
-
| **raid-session-start** | SessionStart | Activates Raid workflow, checks Vault for past quests |
|
|
211
|
-
| **raid-session-end** | SessionEnd | Archives Dungeon, drafts Vault entry, removes session |
|
|
212
|
-
| **raid-stop** | Stop | Backs up Dungeon on phase transitions |
|
|
213
|
-
| **raid-pre-compact** | PreCompact | Backs up Dungeon before message compaction |
|
|
214
|
-
| **raid-task-created** | TaskCreated | Validates task subjects are meaningful |
|
|
215
|
-
| **raid-task-completed** | TaskCompleted | Blocks task completion without test evidence |
|
|
216
|
-
| **raid-teammate-idle** | TeammateIdle | Nudges idle agents to participate |
|
|
279
|
+
</details>
|
|
217
280
|
|
|
218
|
-
###
|
|
281
|
+
### Agents (4)
|
|
219
282
|
|
|
220
|
-
|
|
283
|
+
The Wizard orchestrates. Warrior, Archer, and Rogue each bring a specialized lens. All agents run on Claude Opus 4.6.
|
|
221
284
|
|
|
222
|
-
|
|
223
|
-
|---|---|---|
|
|
224
|
-
| **validate-commit** | PreToolUse (Bash) | Conventional commit format + test gate before commits |
|
|
225
|
-
| **validate-write-gate** | PreToolUse (Write) | Blocks implementation files before design doc exists |
|
|
226
|
-
| **validate-file-naming** | PostToolUse (Write) | Enforces naming convention (kebab-case, snake_case, etc.) |
|
|
227
|
-
| **validate-no-placeholders** | PostToolUse (Write) | Blocks TBD/TODO/FIXME in specs and plans |
|
|
228
|
-
| **validate-dungeon** | PostToolUse (Write) | Requires 2+ agents verified on Dungeon pins |
|
|
229
|
-
| **validate-browser-tests-exist** | PreToolUse (Bash) | Checks Playwright tests exist before commits |
|
|
230
|
-
| **validate-browser-cleanup** | PostToolUse (Bash) | Verifies browser processes cleaned up properly |
|
|
285
|
+
### Hooks (12)
|
|
231
286
|
|
|
232
|
-
|
|
287
|
+
Hooks enforce workflow discipline automatically and **only activate during Raid sessions** — they never interfere with normal coding.
|
|
233
288
|
|
|
234
|
-
**
|
|
289
|
+
**Lifecycle hooks** manage session start/end, quest directory creation, vault archival, and context compaction backup.
|
|
235
290
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
## Skills
|
|
239
|
-
|
|
240
|
-
13 specialized skills guide agent behavior at each stage of the workflow.
|
|
241
|
-
|
|
242
|
-
### Phase Skills
|
|
243
|
-
|
|
244
|
-
| Skill | Purpose |
|
|
245
|
-
|---|---|
|
|
246
|
-
| **raid-protocol** | Master orchestration. Session lifecycle, team composition, modes, rules, reference tables. Loaded at session start. |
|
|
247
|
-
| **raid-design** | Phase 1. Agents independently explore from assigned angles, challenge findings, pin discoveries. Produces a battle-tested design spec. |
|
|
248
|
-
| **raid-implementation-plan** | Phase 2. Decompose design into testable tasks. Agents debate naming, ordering, coverage, compliance. |
|
|
249
|
-
| **raid-implementation** | Phase 3. One implements (TDD), others attack. Rotate implementer per task. No task passes without all issues resolved. |
|
|
250
|
-
| **raid-review** | Phase 4. Independent reviews against design and plan. Issues classified as Critical (must fix), Important (must fix), or Minor (note). |
|
|
251
|
-
| **raid-finishing** | Completeness debate. Agents argue whether work is done. Four merge options: merge, PR, keep branch, discard. |
|
|
291
|
+
**Quality gate hooks** enforce conventional commits, phase-based write protection, naming conventions, placeholder blocking, multi-agent verification on dungeon pins, and browser test detection.
|
|
252
292
|
|
|
253
|
-
|
|
293
|
+
All hooks are POSIX-compatible and use `#claude-raid` markers to coexist safely with your existing hooks.
|
|
254
294
|
|
|
255
|
-
|
|
256
|
-
|---|---|
|
|
257
|
-
| **raid-tdd** | Strict RED-GREEN-REFACTOR. No production code before a failing test. Challengers attack test quality. |
|
|
258
|
-
| **raid-debugging** | Competing hypotheses in parallel. No fixes without confirmed root cause. 3+ failed fixes triggers architecture rethink. |
|
|
259
|
-
| **raid-verification** | Evidence before assertions. Fresh test run required. Forbidden phrases without evidence: "done", "working", "fixed". |
|
|
260
|
-
| **raid-git-worktrees** | Isolated workspace creation with safety verification and clean test baseline. |
|
|
295
|
+
### Skills (13)
|
|
261
296
|
|
|
262
|
-
|
|
297
|
+
Skills guide agent behavior across the workflow. Three categories:
|
|
263
298
|
|
|
264
|
-
|
|
|
265
|
-
|
|
266
|
-
| **
|
|
267
|
-
| **
|
|
268
|
-
| **raid-
|
|
269
|
-
|
|
270
|
-
---
|
|
271
|
-
|
|
272
|
-
## Team Rules
|
|
273
|
-
|
|
274
|
-
17 non-negotiable rules organized into 3 pillars. Stored in `.claude/raid-rules.md` (editable).
|
|
275
|
-
|
|
276
|
-
### Pillar 1: Intellectual Honesty
|
|
277
|
-
|
|
278
|
-
Every claim has evidence you gathered yourself. If you haven't read the code or run the command this turn, you don't know what it says. Never fabricate evidence, certainty, or findings.
|
|
279
|
-
|
|
280
|
-
### Pillar 2: Zero Ego Collaboration
|
|
281
|
-
|
|
282
|
-
When proven wrong, concede instantly. Defend with evidence, never with authority. A teammate catching your mistake is a gift. Build on each other's work — the best findings come from combining perspectives.
|
|
283
|
-
|
|
284
|
-
### Pillar 3: Discipline and Efficiency
|
|
285
|
-
|
|
286
|
-
Maximum effort on every task. Every interaction carries work forward. Agents talk directly to each other — the Wizard is not a relay. Escalate to the Wizard only after you've tried to resolve it yourself.
|
|
299
|
+
| Category | Skills | Purpose |
|
|
300
|
+
|:--|:--|:--|
|
|
301
|
+
| **Core** | `raid-init` | Quest selection, greeting, session bootstrap |
|
|
302
|
+
| **Canonical Quest** | 7 phase skills | One skill per phase, chained in order |
|
|
303
|
+
| **Discipline** | `raid-tdd`, `raid-verification`, `raid-debugging` | Quest-agnostic enforcement — invoked within any phase |
|
|
304
|
+
| **Browser** | `raid-browser`, `raid-browser-chrome` | Browser orchestration and live inspection |
|
|
287
305
|
|
|
288
306
|
---
|
|
289
307
|
|
|
@@ -323,19 +341,20 @@ Maximum effort on every task. Every interaction carries work forward. Agents tal
|
|
|
323
341
|
### Auto-Detection
|
|
324
342
|
|
|
325
343
|
| Marker File | Language | Test Command | Lint Command |
|
|
326
|
-
|
|
327
|
-
| `package.json` | JavaScript | `npm test` | `npm run lint` |
|
|
344
|
+
|:--|:--|:--|:--|
|
|
345
|
+
| `package.json` | JavaScript/TypeScript | `npm test` | `npm run lint` |
|
|
328
346
|
| `Cargo.toml` | Rust | `cargo test` | `cargo clippy` |
|
|
329
347
|
| `pyproject.toml` | Python | `pytest` / `poetry run pytest` | `ruff check .` |
|
|
330
348
|
| `requirements.txt` | Python | `pytest` | `ruff check .` |
|
|
331
349
|
| `go.mod` | Go | `go test ./...` | `go vet ./...` |
|
|
332
350
|
|
|
333
|
-
|
|
351
|
+
Package manager is auto-detected (npm, pnpm, yarn, bun, uv, poetry). Commands are extracted from your project files where possible. Edit `raid.json` to override any value.
|
|
334
352
|
|
|
335
|
-
|
|
353
|
+
<details>
|
|
354
|
+
<summary><strong>Full configuration reference</strong></summary>
|
|
336
355
|
|
|
337
356
|
| Key | Default | Description |
|
|
338
|
-
|
|
357
|
+
|:--|:--|:--|
|
|
339
358
|
| `project.testCommand` | auto-detected | Command to run tests |
|
|
340
359
|
| `project.lintCommand` | auto-detected | Command to run linting |
|
|
341
360
|
| `project.buildCommand` | auto-detected | Command to build |
|
|
@@ -346,9 +365,10 @@ Commands are extracted from your project files (e.g., `scripts.test` in `package
|
|
|
346
365
|
| `conventions.commits` | `conventional` | Commit message format |
|
|
347
366
|
| `conventions.commitMinLength` | `15` | Minimum commit message length |
|
|
348
367
|
| `conventions.maxDepth` | `8` | Maximum file nesting depth |
|
|
349
|
-
| `raid.defaultMode` | `full` | Default mode: `full`, `skirmish`, `scout` |
|
|
350
368
|
| `raid.lifecycle.testWindowMinutes` | `10` | Max age (minutes) of test run for verification |
|
|
351
369
|
|
|
370
|
+
</details>
|
|
371
|
+
|
|
352
372
|
### Browser Testing
|
|
353
373
|
|
|
354
374
|
When a browser framework is detected (Next.js, Vite, Angular, etc.), a `browser` section is added to `raid.json`:
|
|
@@ -366,25 +386,31 @@ When a browser framework is detected (Next.js, Vite, Angular, etc.), a `browser`
|
|
|
366
386
|
}
|
|
367
387
|
```
|
|
368
388
|
|
|
369
|
-
This enables browser-specific hooks and skills — Playwright test detection, browser process cleanup, and live
|
|
389
|
+
This enables browser-specific hooks and skills — Playwright test detection, browser process cleanup, and live Chrome inspection during reviews.
|
|
370
390
|
|
|
371
391
|
---
|
|
372
392
|
|
|
373
|
-
## CLI
|
|
393
|
+
## CLI Reference
|
|
394
|
+
|
|
395
|
+
| Command | Alias | Purpose |
|
|
396
|
+
|:--|:--|:--|
|
|
397
|
+
| `claude-raid start` | — | Launch the Wizard and begin a quest |
|
|
398
|
+
| `claude-raid summon` | `init` | Install Raid into your project |
|
|
399
|
+
| `claude-raid update` | — | Upgrade hooks, skills, and rules to latest |
|
|
400
|
+
| `claude-raid dismantle` | `remove` | Remove all Raid files, restore original settings |
|
|
401
|
+
| `claude-raid heal` | `doctor` | Check environment health |
|
|
402
|
+
| `claude-raid sync` | — | Git pull + re-summon |
|
|
374
403
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
| `claude-raid summon` | Install Raid into your project |
|
|
378
|
-
| `claude-raid summon --dry-run` | Preview what would be installed |
|
|
379
|
-
| `claude-raid update` | Upgrade hooks, skills, and rules to latest version |
|
|
380
|
-
| `claude-raid dismantle` | Remove all Raid files, restore original settings |
|
|
381
|
-
| `claude-raid heal` | Check environment health, show reference card |
|
|
404
|
+
<details>
|
|
405
|
+
<summary><strong>Command details</strong></summary>
|
|
382
406
|
|
|
383
|
-
|
|
407
|
+
### `start`
|
|
408
|
+
|
|
409
|
+
Launches `claude --agent wizard` with full permissions. The Wizard loads its rules, greets you, and begins quest selection. This is the primary entry point for running a quest.
|
|
384
410
|
|
|
385
411
|
### `summon`
|
|
386
412
|
|
|
387
|
-
Installs the full Raid system
|
|
413
|
+
Installs the full Raid system. Auto-detects project type, copies agents/hooks/skills, generates `raid.json`, merges settings (with backup), and runs the setup wizard.
|
|
388
414
|
|
|
389
415
|
- Never overwrites existing files — customized agents are preserved
|
|
390
416
|
- Idempotent — safe to run multiple times
|
|
@@ -392,15 +418,21 @@ Installs the full Raid system into your project. Auto-detects project type, copi
|
|
|
392
418
|
|
|
393
419
|
### `update`
|
|
394
420
|
|
|
395
|
-
Upgrades hooks, skills, and
|
|
421
|
+
Upgrades hooks, skills, and rules to the latest version. Skips customized agents and warns which ones were preserved. Does not touch `raid.json`.
|
|
396
422
|
|
|
397
423
|
### `dismantle`
|
|
398
424
|
|
|
399
|
-
Removes all Raid agents, hooks, skills, and config files. Restores `settings.json` from the backup created during install.
|
|
425
|
+
Removes all Raid agents, hooks, skills, and config files. Restores `settings.json` from the backup created during install.
|
|
400
426
|
|
|
401
427
|
### `heal`
|
|
402
428
|
|
|
403
|
-
Checks Node.js, Claude Code, jq,
|
|
429
|
+
Checks Node.js, Claude Code, jq, tmux, and teammateMode. Offers to fix missing configuration interactively.
|
|
430
|
+
|
|
431
|
+
### `sync`
|
|
432
|
+
|
|
433
|
+
Pulls latest from remote and re-runs summon to pick up any template changes. Useful after CI bumps the version.
|
|
434
|
+
|
|
435
|
+
</details>
|
|
404
436
|
|
|
405
437
|
---
|
|
406
438
|
|
|
@@ -409,63 +441,59 @@ Checks Node.js, Claude Code, jq, teammateMode, and split-pane support. Offers to
|
|
|
409
441
|
**tmux pane navigation (recommended):**
|
|
410
442
|
|
|
411
443
|
| Action | How |
|
|
412
|
-
|
|
413
|
-
|
|
|
414
|
-
|
|
|
415
|
-
|
|
|
444
|
+
|:--|:--|
|
|
445
|
+
| Switch to agent pane | Click the pane, or `Ctrl+B` then arrow key |
|
|
446
|
+
| Talk to an agent | Click their pane and type |
|
|
447
|
+
| View all agents | All panes visible simultaneously |
|
|
416
448
|
|
|
417
449
|
**In-process mode (no tmux):**
|
|
418
450
|
|
|
419
451
|
| Shortcut | Action |
|
|
420
|
-
|
|
421
|
-
|
|
|
422
|
-
|
|
|
423
|
-
|
|
|
424
|
-
|
|
|
425
|
-
|
|
426
|
-
### Starting a Raid session
|
|
427
|
-
|
|
428
|
-
```bash
|
|
429
|
-
# Always start tmux first for multi-pane
|
|
430
|
-
tmux new-session -s raid
|
|
431
|
-
|
|
432
|
-
# Then start the Wizard inside tmux
|
|
433
|
-
claude --agent wizard
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
The Wizard creates a team and spawns agents — each gets its own tmux pane automatically. If you're not inside tmux, agents fall back to in-process mode (single pane).
|
|
452
|
+
|:--|:--|
|
|
453
|
+
| `Shift+Down` | Cycle through teammates |
|
|
454
|
+
| `Enter` | View a teammate's session |
|
|
455
|
+
| `Escape` | Interrupt a teammate's turn |
|
|
456
|
+
| `Ctrl+T` | Toggle the shared task list |
|
|
437
457
|
|
|
438
458
|
---
|
|
439
459
|
|
|
440
|
-
##
|
|
460
|
+
## Design Principles
|
|
441
461
|
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
- **
|
|
445
|
-
- **
|
|
446
|
-
- **
|
|
447
|
-
- **
|
|
448
|
-
- **
|
|
449
|
-
- **
|
|
462
|
+
- **Non-invasive** — Never touches your `CLAUDE.md`. Merges settings alongside your existing config with automatic backup. Clean removal restores originals.
|
|
463
|
+
- **Session-scoped** — Quality gate hooks only activate during Raid sessions. Normal coding is never affected.
|
|
464
|
+
- **Zero dependencies** — Pure Node.js stdlib. Fast `npx` cold-start.
|
|
465
|
+
- **Safe by default** — Never overwrites existing files. Customized agents and rules are always preserved.
|
|
466
|
+
- **Round-based discipline** — Agents work in parallel, flag completion, then cross-test. No mid-thinking interruptions.
|
|
467
|
+
- **Question chain** — Agents never ask the human directly. All questions flow through the Wizard.
|
|
468
|
+
- **Wizard never implements** — Dispatches, observes, digests, rules. The party writes code.
|
|
469
|
+
- **Phase commits** — The Wizard commits at every phase transition with the quest name, phase, and summary.
|
|
450
470
|
|
|
451
471
|
---
|
|
452
472
|
|
|
453
|
-
##
|
|
473
|
+
## Heritage
|
|
454
474
|
|
|
455
|
-
|
|
475
|
+
Adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent. The Raid inherits five core enforcement principles:
|
|
456
476
|
|
|
457
|
-
|
|
|
458
|
-
|
|
459
|
-
| HARD-GATEs | No code before design approval. No implementation before plan approval. |
|
|
460
|
-
| TDD Iron Law | No production code without a failing test first. Enforced in
|
|
461
|
-
| Verification Iron Law | No completion claims without fresh test evidence. |
|
|
462
|
-
| No Placeholders | Specs and plans must contain complete content
|
|
463
|
-
| Conventional Commits | Enforced via hook: `type(scope): description`. |
|
|
477
|
+
| Principle | How the Raid Enforces It |
|
|
478
|
+
|:--|:--|
|
|
479
|
+
| **HARD-GATEs** | No code before design approval. No implementation before plan approval. |
|
|
480
|
+
| **TDD Iron Law** | No production code without a failing test first. Enforced in every phase. |
|
|
481
|
+
| **Verification Iron Law** | No completion claims without fresh test evidence. |
|
|
482
|
+
| **No Placeholders** | Specs and plans must contain complete content — no "TBD" or "implement later". |
|
|
483
|
+
| **Conventional Commits** | Enforced via hook: `type(scope): description`. |
|
|
464
484
|
|
|
465
|
-
**What's different:** Superpowers uses a single agent with subagent delegation. The Raid uses 4 agents
|
|
485
|
+
**What's different:** Superpowers uses a single agent with subagent delegation. The Raid uses 4 persistent agents with adversarial cross-testing. Agents challenge each other directly, pin verified findings to a shared Dungeon, and self-organize within phases. Every decision is stress-tested from three angles before it passes.
|
|
466
486
|
|
|
467
487
|
---
|
|
468
488
|
|
|
469
489
|
## License
|
|
470
490
|
|
|
471
491
|
MIT
|
|
492
|
+
|
|
493
|
+
---
|
|
494
|
+
|
|
495
|
+
<div align="center">
|
|
496
|
+
|
|
497
|
+
Built for [Claude Code](https://claude.ai/claude-code).
|
|
498
|
+
|
|
499
|
+
</div>
|