claude-raid 0.1.2 → 0.1.4

package/README.md

@@ -5,231 +5,291 @@
 
 [1;33m      ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗[0m
 [1;33m     ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝[0m
-[1;33m     ██║     ██║     ███████║██║   ██║██║  ██║█████╗  [0m
-[1;33m     ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝  [0m
-[1;33m     ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗[0m
-[1;33m      ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝[0m
+[33m     ██║     ██║     ███████║██║   ██║██║  ██║█████╗  [0m
+[33m     ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝  [0m
+[33m     ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗[0m
+[1;31m      ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝[0m
 [1;31m              ██████╗  █████╗ ██╗██████╗ [0m
 [1;31m              ██╔══██╗██╔══██╗██║██╔══██╗[0m
-[1;31m              ██████╔╝███████║██║██║  ██║[0m
-[1;31m              ██╔══██╗██╔══██║██║██║  ██║[0m
-[1;31m              ██║  ██║██║  ██║██║██████╔╝[0m
-[1;31m              ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═════╝ [0m
+[31m              ██████╔╝███████║██║██║  ██║[0m
+[31m              ██╔══██╗██╔══██║██║██║  ██║[0m
+[31m              ██║  ██║██║  ██║██║██████╔╝[0m
+[2;31m              ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═════╝ [0m
 
-[90m      Adversarial multi-agent warfare for Claude Code[0m
+[90m      Adversarial multi-agent development for Claude Code[0m
 
 [33m  ⚔ ═══════════════════════════════════════════════════════ ⚔[0m
 ```
 
-Four agents -- Wizard, Warrior, Archer, Rogue -- work through a strict 4-phase workflow where every decision, implementation, and review is stress-tested by competing agents who learn from each other's mistakes and push every finding to its edges.
+Four AI agents work through a strict 4-phase workflow where every design decision, implementation choice, and code review is stress-tested by competing perspectives before it ships.
+
+Built for [Claude Code](https://claude.ai/claude-code). Zero dependencies. One command to install.
 
 Adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent.
 
 ---
 
-## Summon the Party
+## Quick Start
 
 ```bash
+# Install into any project
 npx claude-raid summon
-```
 
-The installer auto-detects your realm (project type), copies agents, skills, and hooks into `.claude/`, and walks you through environment setup -- all in one command.
+# Preview what gets installed (no changes made)
+npx claude-raid summon --dry-run
 
-Then start a Raid:
-
-```bash
+# Start a tmux session, then start the Raid
+tmux new-session -s raid
 claude --agent wizard
 ```
 
-That's it. Describe your task and the Wizard takes over.
+Each agent gets its own tmux pane. You can click into any pane to talk directly to that agent. Describe your task and the Wizard takes over.
 
 ### Prerequisites
 
-The setup wizard checks these automatically during `summon`:
-
 | Requirement | Why | Auto-configured? |
 |---|---|---|
-| **Claude Code** v2.1.32+ | Agent teams support | No -- install/update manually |
-| **Node.js** 18+ | Runs the installer | No -- install manually |
-| **teammateMode** in `~/.claude.json` | Display mode for agent sessions | Yes -- wizard prompts you |
-| **tmux** or **iTerm2** | Split-pane mode (optional) | No -- install manually |
-
-`jq` is required for hooks (pre-installed on macOS, `apt install jq` on Linux).
+| **Node.js** 18+ | Runs the installer | No |
+| **Claude Code** v2.1.32+ | Agent teams support | No |
+| **tmux** | Multi-pane agent display | No — `brew install tmux` |
+| **jq** | Hook config parsing | Pre-installed on macOS |
+| **teammateMode** | Set to `tmux` in `~/.claude.json` | Yes (wizard prompts) |
 
-The experimental agent teams flag (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`) is set automatically in your project's `.claude/settings.json` during install.
+**tmux is required for the multi-pane experience.** Each agent runs in its own pane so you can observe and interact with them independently. Without tmux, agents run in-process (single pane, cycle with Shift+Down).
 
-Diagnose your environment anytime:
+The setup wizard checks all of these during `summon` and offers to fix what it can.
 
-```bash
-npx claude-raid heal
-```
+---
 
 ## How It Works
 
-You describe your task. The Wizard assesses complexity, recommends a mode, and opens the Dungeon:
+You describe a task. The Wizard assesses complexity, recommends a mode, and opens the Dungeon — a shared knowledge artifact where agents pin verified findings throughout each phase.
 
 ```
-Phase 1: DESIGN          Wizard opens the Dungeon, dispatches with angles.
-                          Agents explore freely, challenge each other directly,
-                          roast weak findings, build on discoveries.
-                          Verified findings pinned to the Dungeon.
-                          Wizard closes when design is battle-tested.
-
-Phase 2: PLAN             Agents decompose the design into tasks.
-                          They fight directly over compliance, naming,
-                          test coverage, and ordering.
-                          Agreed tasks pinned to the Dungeon.
-
-Phase 3: IMPLEMENTATION   One agent implements each task. The others attack
-                          directly -- and attack each other's reviews too.
-                          TDD enforced. Every task earns approval.
-
-Phase 4: REVIEW           Independent reviews, then agents fight over findings
-                          AND missing findings. Issues pinned by severity.
-                          Critical and Important must be fixed.
-
-         FINISHING        Agents debate completeness directly.
-                          Wizard presents merge options. Dungeon cleaned up.
-```
-
-Every phase follows the same pattern: Wizard opens the Dungeon and dispatches with angles, agents self-organize and interact directly (challenge, roast, build on each other's work), pin verified findings to the Dungeon, and the Wizard closes with a binding ruling. No phase is skipped. No work passes unchallenged.
-
-## The Team
+Phase 1: DESIGN          Agents explore the problem from competing angles.
+                          Challenge each other's findings. Pin what survives.
+                          Wizard closes when the design is battle-tested.
 
-### Wizard (Dungeon Master)
+Phase 2: PLAN             Decompose the design into testable tasks.
+                          Fight over naming, ordering, coverage, compliance.
+                          Pin the agreed task list.
 
-Purple. Model: Opus 4.6. Observes 90%, acts 10%.
+Phase 3: IMPLEMENTATION   One agent builds each task (TDD enforced).
+                          The others attack the implementation directly.
+                          Every task earns approval before moving on.
 
-The Wizard doesn't write code -- it thinks. Every response has been turned over 3, 4, 5 times before a single word is committed. It reads the full prompt three times, identifies the real problem beneath the stated one, maps the blast radius, and only then opens the Dungeon and dispatches the team with precise angles.
+Phase 4: REVIEW           Independent reviews against design and plan.
+                          Agents fight over findings AND missing findings.
+                          Critical and Important issues must be fixed.
 
-After dispatch, the Wizard goes silent. Agents own the phase -- they interact directly, challenge each other, build on discoveries, and pin verified findings to the Dungeon. The Wizard watches, intervening only on destructive loops, drift, deadlock, laziness, ego, or misinformation. When the phase objective is met, the Wizard closes with a binding ruling citing Dungeon evidence.
+         FINISHING        Agents debate completeness. Wizard presents
+                          merge options: merge, PR, keep branch, or discard.
+```
 
-### Warrior
+No phase is skipped. No work passes unchallenged.
 
-Red. Aggressive thoroughness. Stress-tests to destruction.
+---
 
-The Warrior doesn't skim -- it rips things apart. When @Archer or @Rogue present findings, its first instinct is: *"Where is this wrong?"* It demands evidence, proposes counter-examples, and pushes until things break. Race conditions, null input, scale, memory pressure -- nothing passes unchecked. It builds on teammates' discoveries and roasts weak analysis. Every move counts, and it concedes instantly when proven wrong.
+## The Team
 
-**Signals:** `🔍 FINDING:` / `⚔️ CHALLENGE:` / `🔥 ROAST:` / `🔗 BUILDING ON @Name:` / `📌 DUNGEON:` / `🆘 WIZARD:` / `✅ CONCEDE:`
+### Wizard — Dungeon Master
 
-### Archer
+Thinks 5 times before speaking. Opens phases, dispatches the team with precise angles, observes silently (90% of the time), and closes each phase with a binding ruling citing Dungeon evidence. The Wizard doesn't write code — it ensures the process produces the best possible outcome.
 
-Green. Precision over brute force. Pattern recognition.
+### Warrior — Stress Tester
 
-The Archer finds what brute force misses. It spots naming mismatches, violated conventions, and design drift. It traces ripple effects -- changing X in module A silently breaks Y in module C through an implicit contract in Z. It challenges @Warrior and @Rogue from unexpected angles, building on their discoveries with surgical precision. Every finding includes the exact location and the exact consequence.
+Rips things apart. Race conditions, null input, scale, memory pressure — nothing passes unchecked. Demands evidence, proposes counter-examples, and pushes until things break. Concedes instantly when proven wrong.
 
-**Signals:** `🎯 FINDING:` / `🏹 CHALLENGE:` / `🔥 ROAST:` / `🔗 BUILDING ON @Name:` / `📌 DUNGEON:` / `🆘 WIZARD:` / `✅ CONCEDE:`
+### Archer — Pattern Seeker
 
-### Rogue
+Finds what brute force misses. Naming mismatches, violated conventions, design drift. Traces ripple effects — changing X in module A silently breaks Y in module C through an implicit contract in Z. Every finding includes the exact location and the exact consequence.
 
-Orange. Adversarial mindset. Assumption destroyer.
+### Rogue — Assumption Destroyer
 
-The Rogue thinks like a malicious user, a failing network, a corrupted database, a race condition at 3 AM. *"This will never be null."* Oh really? *"Users won't do that."* Watch me. It constructs the exact sequence of events that turns a minor oversight into a critical failure. It weaponizes @Warrior and @Archer's findings to build nastier scenarios. Every finding is a concrete attack scenario, not a theoretical concern.
+Thinks like a malicious user, a failing network, a corrupted database, a race condition at 3 AM. Constructs the exact sequence of events that turns a minor oversight into a critical failure. Every finding is a concrete attack scenario, not a theoretical concern.
 
-**Signals:** `💀 FINDING:` / `🗡️ CHALLENGE:` / `🔥 ROAST:` / `🔗 BUILDING ON @Name:` / `📌 DUNGEON:` / `🆘 WIZARD:` / `✅ CONCEDE:`
+---
 
 ## Modes
 
-Not every task needs all four agents. The Wizard recommends a mode based on complexity, or you can specify one directly.
+Not every task needs all four agents. The Wizard recommends a mode based on complexity, or you can override directly.
 
 | | Full Raid | Skirmish | Scout |
 |---|---|---|---|
-| **Agents** | 3 | 2 | 1 |
-| **Design phase** | Full adversarial | Lightweight | Skip (inline) |
-| **Plan phase** | Full adversarial | Merged with design | Skip (inline) |
+| **Agents** | 3 + Wizard | 2 + Wizard | 1 + Wizard |
+| **Design** | Full adversarial | Lightweight | Inline |
+| **Planning** | Full adversarial | Merged with design | Inline |
 | **Implementation** | 1 builds, 2 attack | 1 builds, 1 attacks | 1 builds, Wizard reviews |
 | **Review** | 3 independent reviews | 1 review + Wizard | Wizard only |
-| **TDD** | **Enforced** | **Enforced** | **Enforced** |
-| **Verification** | Triple | Double | Single + Wizard |
+| **TDD** | Enforced | Enforced | Enforced |
 
-**When to use:**
+**When to use each:**
 
-- **Full Raid** -- Complex features, architecture decisions, critical security reviews, major refactors, cross-layer changes
-- **Skirmish** -- Medium features, non-trivial bugfixes, multi-file changes
-- **Scout** -- Simple bugfixes, config changes, documentation, single-file changes
+- **Full Raid** — Architecture decisions, security-critical code, major refactors, cross-layer changes
+- **Skirmish** — Medium features, non-trivial bugfixes, multi-file changes
+- **Scout** — Config changes, documentation, single-file fixes
 
 Override the Wizard's recommendation: *"Full Raid this"*, *"Skirmish this bugfix"*, *"Scout this"*.
 
 The Wizard can escalate mid-task (Scout to Skirmish, Skirmish to Full Raid) with your approval. It cannot de-escalate without asking.
 
-**TDD is non-negotiable in all modes.** No production code without a failing test first.
+---
 
 ## The Dungeon
 
-The Dungeon (`.claude/raid-dungeon.md`) is the team's shared knowledge artifact -- a curated board where agents pin verified findings during each phase.
+The Dungeon (`.claude/raid-dungeon.md`) is the team's shared knowledge artifact — a curated board where agents pin verified findings during each phase.
 
-**What goes in the Dungeon:** Findings that survived challenge, active unresolved battles, shared knowledge verified by 2+ agents, key decisions, escalation points.
+**What goes in:** Findings that survived challenge from 2+ agents, active unresolved battles, key decisions, escalation points.
 
 **What stays in conversation:** The back-and-forth of challenges and roasts, exploratory thinking, concessions. The conversation is the sparring ring. The Dungeon is the scoreboard.
 
-**Lifecycle:** Wizard creates the Dungeon when opening a phase, agents pin findings with `📌 DUNGEON:`, Wizard archives it when closing (`.claude/raid-dungeon-phase-N.md`), and agents can reference archived Dungeons from prior phases. All Dungeon files are cleaned up when the session ends.
+**Lifecycle:** Wizard creates it when opening a phase, agents pin findings with `DUNGEON:` prefix, Wizard archives it when closing (`raid-dungeon-phase-N.md`), and all Dungeon files are cleaned up when the session ends.
 
-**Direct interaction:** Agents talk to each other directly (`@Name`), build on discoveries (`🔗 BUILDING ON @Name:`), roast weak analysis (`🔥 ROAST:`), and escalate to the Wizard only when genuinely stuck (`🆘 WIZARD:`). The Wizard observes silently and intervenes only on destructive loops, drift, deadlock, laziness, ego, or misinformation.
+Agents interact directly — `@Name` mentions, building on each other's discoveries, roasting weak analysis. The Wizard observes silently, intervening only on destructive loops, drift, deadlock, or misinformation.
 
-## Skills
+---
 
-10 specialized skills guide agent behavior at each stage:
+## What Gets Installed
 
-| Skill | When It's Used | What It Does |
-|---|---|---|
-| `raid-protocol` | Session start | Establishes workflow, modes, team rules, reference tables. The Wizard's operating manual. |
-| `raid-design` | Phase 1 | Read-only exploration. Agents cover performance, robustness, testability, edge cases, architecture, DRY. Produces design specification. |
-| `raid-implementation-plan` | Phase 2 | Collaborative decomposition with compliance testing. Every requirement gets a task, every task gets tests, naming is consistent, ordering is correct. |
-| `raid-implementation` | Phase 3 | One implements, others attack, rotate. Task tracking via Claude Code's built-in system. Implementer rotation enforced. |
-| `raid-review` | Phase 4 | Independent reviews against design doc and plan. Issues classified as Critical (must fix), Important (must fix), or Minor (note). |
-| `raid-finishing` | After Phase 4 | Completeness debate. Tests verified. Four options: merge, PR, keep branch, discard. |
-| `raid-tdd` | During implementation | Strict RED-GREEN-REFACTOR. Challengers attack test quality. Rationalization table prevents shortcuts. |
-| `raid-debugging` | On bugs | Competing hypotheses in parallel. No fixes without root cause. 3+ failed fixes triggers architecture discussion. |
-| `raid-verification` | Before completion claims | Evidence before assertions. Fresh test run required. Forbidden phrases without evidence: "done", "working", "fixed". |
-| `raid-git-worktrees` | Before implementation | Isolated workspace with safety verification and clean test baseline. |
+```
+.claude/
+├── raid.json                        # Project config (auto-detected, editable)
+├── raid-rules.md                    # 17 team rules across 3 pillars (editable)
+├── settings.json                    # Hooks merged with existing (backup created)
+├── agents/
+│   ├── wizard.md                    # Dungeon master
+│   ├── warrior.md                   # Stress tester
+│   ├── archer.md                    # Pattern seeker
+│   └── rogue.md                     # Assumption destroyer
+├── hooks/
+│   ├── raid-lib.sh                  # Shared config and session state
+│   ├── raid-session-start.sh        # Session activation
+│   ├── raid-session-end.sh          # Archive and cleanup
+│   ├── raid-stop.sh                 # Phase transition backup
+│   ├── raid-pre-compact.sh          # Pre-compaction backup
+│   ├── raid-task-created.sh         # Task subject validation
+│   ├── raid-task-completed.sh       # Test evidence gate
+│   ├── raid-teammate-idle.sh        # Idle agent nudge
+│   ├── validate-commit.sh           # Conventional commits + test gate
+│   ├── validate-write-gate.sh       # Design doc before implementation
+│   ├── validate-file-naming.sh      # Naming convention enforcement
+│   ├── validate-no-placeholders.sh  # No TBD/TODO in specs
+│   ├── validate-dungeon.sh          # Multi-agent verification on pins
+│   ├── validate-browser-tests-exist.sh  # Playwright test detection
+│   └── validate-browser-cleanup.sh  # Browser process cleanup
+└── skills/
+    ├── raid-protocol/               # Session lifecycle and team rules
+    ├── raid-design/                 # Phase 1: adversarial exploration
+    ├── raid-implementation-plan/    # Phase 2: task decomposition
+    ├── raid-implementation/         # Phase 3: TDD with direct challenge
+    ├── raid-review/                 # Phase 4: independent review + fighting
+    ├── raid-finishing/              # Completeness debate + merge options
+    ├── raid-tdd/                    # RED-GREEN-REFACTOR enforcement
+    ├── raid-debugging/              # Root-cause investigation
+    ├── raid-verification/           # Evidence-before-claims gate
+    ├── raid-git-worktrees/          # Isolated workspace creation
+    ├── raid-browser/                # Browser startup discovery
+    ├── raid-browser-playwright/     # Playwright test authoring
+    └── raid-browser-chrome/         # Live browser inspection
+```
+
+Dungeon files (`raid-dungeon.md`, `raid-dungeon-phase-*.md`) and session state (`raid-session`) are created at runtime during Raid sessions and cleaned up automatically.
+
+---
 
 ## Hooks
 
-6 quality gates enforced automatically. All hooks are POSIX-compatible (work on macOS and Linux), read configuration from `.claude/raid.json`, and use `#claude-raid` markers so they never collide with your existing hooks.
+Hooks enforce workflow discipline automatically. They split into two categories:
 
-Hooks that enforce workflow discipline (phase-gate, test-pass, verification) only activate during Raid sessions -- they won't interfere with normal coding outside of a Raid.
+### Lifecycle Hooks
 
-| Hook | Trigger | What It Does |
+Manage session state without manual intervention. These activate and deactivate as sessions begin and end.
+
+| Hook | Trigger | Purpose |
+|---|---|---|
+| **raid-session-start** | SessionStart | Activates Raid workflow, checks Vault for past quests |
+| **raid-session-end** | SessionEnd | Archives Dungeon, drafts Vault entry, removes session |
+| **raid-stop** | Stop | Backs up Dungeon on phase transitions |
+| **raid-pre-compact** | PreCompact | Backs up Dungeon before message compaction |
+| **raid-task-created** | TaskCreated | Validates task subjects are meaningful |
+| **raid-task-completed** | TaskCompleted | Blocks task completion without test evidence |
+| **raid-teammate-idle** | TeammateIdle | Nudges idle agents to participate |
+
+### Quality Gates
+
+Enforce code standards and workflow compliance. Quality gates only activate during Raid sessions — they won't interfere with normal coding.
+
+| Hook | Trigger | Purpose |
 |---|---|---|
-| **validate-file-naming.sh** | After Write/Edit | Enforces configured naming convention (kebab-case, snake_case, camelCase). Always blocks spaces in filenames. Blocks files nested deeper than configured max depth (default 8). |
-| **validate-commit-message.sh** | Before Bash (git commit) | Enforces conventional commit format: `type(scope): description`. Blocks messages shorter than 15 characters. Blocks generic messages (update, fix, wip). Handles heredoc and quoted commit messages. |
-| **validate-tests-pass.sh** | Before Bash (git commit) | Runs your test command before allowing commits. Writes a timestamp to `.claude/raid-last-test-run` on success (used by the verification hook). Only active during Raid sessions. |
-| **validate-phase-gate.sh** | Before Write | Blocks writing implementation files when no design doc exists in the specs path. Full Raid: blocks. Skirmish: warns. Scout: skips. Only active during Raid sessions. |
-| **validate-no-placeholders.sh** | After Write/Edit | Scans specs and plans for placeholder text: TBD, TODO, FIXME, "implement later", "add appropriate", "similar to Task", "handle edge cases". Blocks with line numbers. |
-| **validate-verification.sh** | Before Bash (git commit) | Blocks commits that claim completion ("complete", "done", "final") unless tests were run within the last 10 minutes. Enforces the verification Iron Law. Only active during Raid sessions. |
+| **validate-commit** | PreToolUse (Bash) | Conventional commit format + test gate before commits |
+| **validate-write-gate** | PreToolUse (Write) | Blocks implementation files before design doc exists |
+| **validate-file-naming** | PostToolUse (Write) | Enforces naming convention (kebab-case, snake_case, etc.) |
+| **validate-no-placeholders** | PostToolUse (Write) | Blocks TBD/TODO/FIXME in specs and plans |
+| **validate-dungeon** | PostToolUse (Write) | Requires 2+ agents verified on Dungeon pins |
+| **validate-browser-tests-exist** | PreToolUse (Bash) | Checks Playwright tests exist before commits |
+| **validate-browser-cleanup** | PostToolUse (Bash) | Verifies browser processes cleaned up properly |
 
-### Hook exit codes
+All hooks are POSIX-compatible, read configuration from `raid.json`, and use `#claude-raid` markers to avoid collisions with your existing hooks.
 
-- `0` -- pass, no issues
-- `2` -- block with message (agent sees the error and must fix it)
+**Exit codes:** `0` = pass, `2` = block with message (agent sees the error and must fix it).
+
+---
+
+## Skills
+
+13 specialized skills guide agent behavior at each stage of the workflow.
+
+### Phase Skills
+
+| Skill | Purpose |
+|---|---|
+| **raid-protocol** | Master orchestration. Session lifecycle, team composition, modes, rules, reference tables. Loaded at session start. |
+| **raid-design** | Phase 1. Agents independently explore from assigned angles, challenge findings, pin discoveries. Produces a battle-tested design spec. |
+| **raid-implementation-plan** | Phase 2. Decompose design into testable tasks. Agents debate naming, ordering, coverage, compliance. |
+| **raid-implementation** | Phase 3. One implements (TDD), others attack. Rotate implementer per task. No task passes without all issues resolved. |
+| **raid-review** | Phase 4. Independent reviews against design and plan. Issues classified as Critical (must fix), Important (must fix), or Minor (note). |
+| **raid-finishing** | Completeness debate. Agents argue whether work is done. Four merge options: merge, PR, keep branch, discard. |
+
+### Discipline Skills
+
+| Skill | Purpose |
+|---|---|
+| **raid-tdd** | Strict RED-GREEN-REFACTOR. No production code before a failing test. Challengers attack test quality. |
+| **raid-debugging** | Competing hypotheses in parallel. No fixes without confirmed root cause. 3+ failed fixes triggers architecture rethink. |
+| **raid-verification** | Evidence before assertions. Fresh test run required. Forbidden phrases without evidence: "done", "working", "fixed". |
+| **raid-git-worktrees** | Isolated workspace creation with safety verification and clean test baseline. |
+
+### Browser Skills
+
+| Skill | Purpose |
+|---|---|
+| **raid-browser** | Browser startup discovery. Detects dev server, auth requirements, startup steps. |
+| **raid-browser-playwright** | Playwright MCP test authoring with network and console assertions. |
+| **raid-browser-chrome** | Live browser inspection via Claude-in-Chrome MCP. Angle-driven investigation. |
+
+---
 
 ## Team Rules
 
-17 non-negotiable rules that every agent follows, stored in `.claude/raid-rules.md`:
-
-1. **No subagents** -- agent teams only
-2. **No laziness** -- every challenge carries evidence
-3. **No trust without verification** -- verify independently, reports lie
-4. **Learn from mistakes** -- yours and others'
-5. **Make every move count** -- no endless disputes
-6. **Share knowledge** -- competitors but a team
-7. **No ego** -- evidence or concede, instantly
-8. **Stay active** -- all assigned agents participate
-9. **Wizard is the human interface** -- agents ask the Wizard, Wizard asks you
-10. **Wizard is impartial** -- judges by evidence, not source
-11. **Wizard observes 90%, acts 10%** -- speaks when 90% confident
-12. **Maximum effort, always**
-13. **No hallucination** -- say "I don't know" when uncertain
-14. **Dungeon discipline** -- only pin verified findings, don't spam
-15. **Direct engagement** -- address agents by name, build on each other's work
-16. **Escalate wisely** -- pull the Wizard only when genuinely stuck
-17. **Roast with evidence** -- every critique carries proof
-
-Edit this file to add project-specific rules. Updates via `claude-raid update` will overwrite it, so keep a backup if you've customized it.
+17 non-negotiable rules organized into 3 pillars. Stored in `.claude/raid-rules.md` (editable).
+
+### Pillar 1: Intellectual Honesty
+
+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.
+
+### Pillar 2: Zero Ego Collaboration
+
+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.
+
+### Pillar 3: Discipline and Efficiency
+
+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.
+
+---
 
 ## Configuration
 
-`claude-raid summon` auto-detects your realm and generates `.claude/raid.json`:
+`claude-raid summon` auto-detects your project and generates `.claude/raid.json`:
 
 ```json
 {
@@ -250,149 +310,161 @@ Edit this file to add project-specific rules. Updates via `claude-raid update` w
     "commits": "conventional"
   },
   "raid": {
-    "defaultMode": "full"
+    "defaultMode": "full",
+    "vault": { "path": ".claude/vault", "enabled": true },
+    "lifecycle": {
+      "autoSessionManagement": true,
+      "testWindowMinutes": 10
+    }
   }
 }
 ```
 
-### Auto-detected languages
+### Auto-Detection
 
-| Marker File | Language | Test Command | Lint Command | Build Command |
-|---|---|---|---|---|
-| `package.json` | JavaScript | `npm test` | `npm run lint` | `npm run build` |
-| `Cargo.toml` | Rust | `cargo test` | `cargo clippy` | `cargo build` |
-| `pyproject.toml` | Python | `pytest` / `poetry run pytest` | `ruff check .` | `python -m build` / `poetry build` |
-| `requirements.txt` | Python | `pytest` | `ruff check .` | -- |
-| `go.mod` | Go | `go test ./...` | `go vet ./...` | `go build ./...` |
+| Marker File | Language | Test Command | Lint Command |
+|---|---|---|---|
+| `package.json` | JavaScript | `npm test` | `npm run lint` |
+| `Cargo.toml` | Rust | `cargo test` | `cargo clippy` |
+| `pyproject.toml` | Python | `pytest` / `poetry run pytest` | `ruff check .` |
+| `requirements.txt` | Python | `pytest` | `ruff check .` |
+| `go.mod` | Go | `go test ./...` | `go vet ./...` |
 
-Commands are auto-detected from your project files (e.g., `scripts.test` in `package.json`). Edit `raid.json` to override.
+Commands are extracted from your project files (e.g., `scripts.test` in `package.json`). Package manager is auto-detected (npm, pnpm, yarn, bun, uv, poetry). Edit `raid.json` to override any value.
 
-### Configuration reference
+### Configuration Reference
 
 | Key | Default | Description |
 |---|---|---|
 | `project.testCommand` | auto-detected | Command to run tests |
 | `project.lintCommand` | auto-detected | Command to run linting |
 | `project.buildCommand` | auto-detected | Command to build |
-| `paths.specs` | `docs/raid/specs` | Where design specs are saved |
-| `paths.plans` | `docs/raid/plans` | Where implementation plans are saved |
-| `paths.worktrees` | `.worktrees` | Where git worktrees are created |
-| `conventions.fileNaming` | `none` | Naming convention: `kebab-case`, `snake_case`, `camelCase`, `none` |
-| `conventions.commits` | `conventional` | Commit format |
+| `paths.specs` | `docs/raid/specs` | Design spec output directory |
+| `paths.plans` | `docs/raid/plans` | Implementation plan output directory |
+| `paths.worktrees` | `.worktrees` | Git worktree directory |
+| `conventions.fileNaming` | `none` | `kebab-case`, `snake_case`, `camelCase`, or `none` |
+| `conventions.commits` | `conventional` | Commit message format |
 | `conventions.commitMinLength` | `15` | Minimum commit message length |
 | `conventions.maxDepth` | `8` | Maximum file nesting depth |
 | `raid.defaultMode` | `full` | Default mode: `full`, `skirmish`, `scout` |
+| `raid.lifecycle.testWindowMinutes` | `10` | Max age (minutes) of test run for verification |
+
+### Browser Testing
 
-## Commands
+When a browser framework is detected (Next.js, Vite, Angular, etc.), a `browser` section is added to `raid.json`:
 
-| Command | What it does |
+```json
+{
+  "browser": {
+    "enabled": true,
+    "framework": "next",
+    "devCommand": "npm run dev",
+    "baseUrl": "http://localhost:3000",
+    "defaultPort": 3000,
+    "playwrightConfig": "playwright.config.ts"
+  }
+}
+```
+
+This enables browser-specific hooks and skills — Playwright test detection, browser process cleanup, and live browser inspection during reviews.
+
+---
+
+## CLI Commands
+
+| Command | Purpose |
 |---|---|
-| `claude-raid summon` | Summon the party into this realm |
-| `claude-raid update` | Reforge the party's arsenal |
-| `claude-raid dismantle` | Dismantle the camp and retreat |
-| `claude-raid heal` | Diagnose wounds and prepare for battle |
+| `claude-raid summon` | Install Raid into your project |
+| `claude-raid summon --dry-run` | Preview what would be installed |
+| `claude-raid update` | Upgrade hooks, skills, and rules to latest version |
+| `claude-raid dismantle` | Remove all Raid files, restore original settings |
+| `claude-raid heal` | Check environment health, show reference card |
 
-> Old names (`init`, `remove`, `doctor`) still work as aliases.
+Old names (`init`, `remove`, `doctor`) still work as aliases.
 
 ### `summon`
 
-Summons the full Raid party into your project.
+Installs the full Raid system into your project. Auto-detects project type, copies agents/hooks/skills, generates `raid.json`, merges settings (with backup), and runs the setup wizard.
 
-- Creates `.claude/` if absent
-- Auto-detects project type and generates `raid.json`
-- Copies agents, hooks, skills, and `raid-rules.md`
-- Merges settings into existing `settings.json` (with backup)
-- Makes hooks executable
-- Adds session files to `.gitignore`
-- Runs the setup wizard to check and configure prerequisites
-- **Never overwrites** existing files with the same name
+- Never overwrites existing files — customized agents are preserved
+- Idempotent — safe to run multiple times
+- `--dry-run` shows exactly what would be created without touching disk
 
 ### `update`
 
-Reforges the party's weapons and armor with the latest version.
-
-- Overwrites hooks, skills, and `raid-rules.md` with latest versions
-- **Skips customized agents** (warns you which warriors were preserved)
-- Does **not** touch `raid.json` (your realm config stays intact)
-- Re-runs settings merge to pick up new hooks
+Upgrades hooks, skills, and `raid-rules.md` to the latest version. Skips customized agents (warns which ones were preserved). Does not touch `raid.json` — your project config stays intact.
 
 ### `dismantle`
 
-Dismantles the camp and restores your realm to its former state.
-
-- Removes all Raid agents, hooks, skills, and config files
-- Restores `settings.json` from backup (if backup exists)
-- Preserves non-Raid files in `.claude/`
+Removes all Raid agents, hooks, skills, and config files. Restores `settings.json` from the backup created during install. Preserves non-Raid files in `.claude/`.
 
 ### `heal`
 
-Diagnoses wounds and prepares the party for battle.
+Checks Node.js, Claude Code, jq, teammateMode, and split-pane support. Offers to fix missing configuration interactively. Shows the "How It Works" reference card with modes, phases, hook enforcement, and controls.
 
-- Checks Node.js, Claude Code, teammateMode, and split-pane support
-- Offers to fix missing configuration interactively
-- Shows Quick Start, Controls, and Raid Modes reference
-- Exits with code 1 in CI when required checks fail
+---
 
-## What Gets Installed
+## Controls
 
-```
-.claude/
-├── raid.json                        # Realm config (auto-generated, editable)
-├── raid-rules.md                    # Team rules (editable)
-├── settings.json                    # Merged with existing (backup at .pre-raid-backup)
-├── agents/
-│   ├── wizard.md                    # Dungeon master
-│   ├── warrior.md                   # Aggressive stress-tester
-│   ├── archer.md                    # Precision pattern-seeker
-│   └── rogue.md                     # Adversarial assumption-destroyer
-├── hooks/
-│   ├── validate-file-naming.sh      # Naming conventions
-│   ├── validate-commit-message.sh   # Conventional commits
-│   ├── validate-tests-pass.sh       # Test gate before commits
-│   ├── validate-phase-gate.sh       # Design doc before implementation
-│   ├── validate-no-placeholders.sh  # No TBD/TODO in specs
-│   └── validate-verification.sh     # Test evidence before completion
-└── skills/
-    ├── raid-protocol/               # Master orchestration
-    ├── raid-design/                 # Phase 1
-    ├── raid-implementation-plan/    # Phase 2
-    ├── raid-implementation/         # Phase 3
-    ├── raid-review/                 # Phase 4
-    ├── raid-finishing/              # Completeness + merge
-    ├── raid-tdd/                    # Test-driven development
-    ├── raid-debugging/              # Root cause analysis
-    ├── raid-verification/           # Evidence before claims
-    └── raid-git-worktrees/          # Isolated workspaces
+**tmux pane navigation (recommended):**
+
+| Action | How |
+|---|---|
+| **Switch to agent pane** | Click the pane, or `Ctrl+B` then arrow key |
+| **Talk to an agent** | Click their pane and type |
+| **View all agents** | All panes visible simultaneously |
+
+**In-process mode (no tmux):**
+
+| Shortcut | Action |
+|---|---|
+| **Shift+Down** | Cycle through teammates |
+| **Enter** | View a teammate's session |
+| **Escape** | Interrupt a teammate's turn |
+| **Ctrl+T** | Toggle the shared task list |
+
+### Starting a Raid session
+
+```bash
+# Always start tmux first for multi-pane
+tmux new-session -s raid
+
+# Then start the Wizard inside tmux
+claude --agent wizard
 ```
 
-**Note:** Dungeon files (`.claude/raid-dungeon.md`, `.claude/raid-dungeon-phase-*.md`) are created at runtime during Raid sessions, not during installation. They are session artifacts and are automatically cleaned up.
+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).
+
+---
 
 ## Non-Invasive Design
 
 The Raid is a tool in your toolkit, not your project's operating system.
 
-- **Never touches your `CLAUDE.md`** -- your project instructions stay yours
+- **Never touches your `CLAUDE.md`** — your project instructions stay yours
 - **Merges settings** alongside your existing config, with automatic backup
 - **Won't overwrite** existing agents, hooks, or skills that share a name
-- **Session-scoped hooks** -- workflow hooks only activate during Raid sessions (`.claude/raid-session`), never during normal coding
+- **Session-scoped hooks** — workflow hooks only activate during Raid sessions, never during normal coding
 - **Clean removal** restores your original `settings.json` from backup
-- **Zero npm dependencies** -- pure Node.js stdlib, fast `npx` cold-start
+- **Zero npm dependencies** — pure Node.js stdlib, fast `npx` cold-start
+
+---
 
 ## Inherited from Superpowers
 
 The Raid inherits and adapts the [Superpowers](https://github.com/obra/superpowers) behavioral harness:
 
-| Concept | How The Raid Uses It |
+| Concept | How the Raid Uses It |
 |---|---|
 | HARD-GATEs | No code before design approval. No implementation before plan approval. |
 | TDD Iron Law | No production code without a failing test first. Enforced in all modes. |
 | Verification Iron Law | No completion claims without fresh test evidence. |
-| No Placeholders | Plans must contain complete code, not "TBD" or "implement later". |
-| Red Flags / Rationalization tables | Built into TDD, debugging, and verification skills. |
-| YAGNI / DRY | Remove unnecessary features. Don't duplicate logic. |
-| Conventional commits | Enforced via hook: `type(scope): description`. |
+| No Placeholders | Specs and plans must contain complete content, not "TBD" or "implement later". |
+| Conventional Commits | Enforced via hook: `type(scope): description`. |
+
+**What's different:** Superpowers uses a single agent with subagent delegation. The Raid uses 4 agents in an agent team with adversarial cross-testing, direct interaction, and collaborative learning. Agents talk to each other (not through the Wizard), pin verified findings to a shared Dungeon, and self-organize within phases. Every decision is stress-tested from multiple angles before it passes.
 
-**What's different:** Superpowers uses a single agent with subagent delegation. The Raid uses 4 agents in an agent team with adversarial cross-testing, competitive exploration, and collaborative learning. Agents interact directly with each other (not through the Wizard), pin verified findings to a shared Dungeon, and self-organize within phases. The Wizard observes 90%, acts 10% -- opening and closing phases, but never mediating every exchange. Every decision is stress-tested from multiple angles before it passes.
+---
 
 ## License