claude-raid 0.1.2 → 0.1.3

package/bin/cli.js

@@ -11,12 +11,26 @@ const showUpdateNotice = versionCheck.start();
 
 const COMMANDS = {
   // Primary commands
-  summon: () => require('../src/init').run(),
+  summon: () => {
+    if (process.argv.includes('--dry-run')) {
+      console.log('\n' + banner());
+      console.log(require('../src/init').dryRun(process.cwd()));
+      return;
+    }
+    return require('../src/init').run();
+  },
   update: () => require('../src/update').run(),
   dismantle: () => require('../src/remove').run(),
   heal: () => require('../src/doctor').run(),
   // Aliases (backward compat)
-  init: () => require('../src/init').run(),
+  init: () => {
+    if (process.argv.includes('--dry-run')) {
+      console.log('\n' + banner());
+      console.log(require('../src/init').dryRun(process.cwd()));
+      return;
+    }
+    return require('../src/init').run();
+  },
   remove: () => require('../src/remove').run(),
   doctor: () => require('../src/doctor').run(),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-raid",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "commonjs",
   "description": "Adversarial multi-agent development system for Claude Code",
   "author": "Pedro Picardi",

package/src/descriptions.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Single source of truth for file descriptions used by dry-run and install output.
+// Keep descriptions under 80 chars — they appear in terminal columns.
+
+const AGENTS = {
+  'wizard.md':  'Dungeon master — opens phases, dispatches team, closes with rulings',
+  'warrior.md': 'Stress-tester — breaks things under load, edge cases, pressure',
+  'archer.md':  'Pattern-seeker — traces ripple effects, naming drift, contract violations',
+  'rogue.md':   'Assumption-destroyer — thinks like a failing system, malicious input',
+};
+
+const HOOKS = {
+  lifecycle: [
+    { name: 'raid-lib.sh',            desc: 'Shared config — reads raid.json, exports session state' },
+    { name: 'raid-session-start.sh',   desc: 'Activates Raid workflow when session begins' },
+    { name: 'raid-session-end.sh',     desc: 'Archives Dungeon, cleans up when session ends' },
+    { name: 'raid-stop.sh',           desc: 'Backs up Dungeon on phase transitions' },
+    { name: 'raid-pre-compact.sh',    desc: 'Backs up Dungeon before message compaction' },
+    { name: 'raid-task-created.sh',   desc: 'Validates task subjects are meaningful' },
+    { name: 'raid-task-completed.sh', desc: 'Blocks task completion without test evidence' },
+    { name: 'raid-teammate-idle.sh',  desc: 'Nudges idle agents to participate' },
+  ],
+  gates: [
+    { name: 'validate-commit.sh',              desc: 'Enforces conventional commits + test gate' },
+    { name: 'validate-write-gate.sh',          desc: 'Blocks implementation before design doc exists' },
+    { name: 'validate-file-naming.sh',         desc: 'Enforces naming convention (kebab-case, etc.)' },
+    { name: 'validate-no-placeholders.sh',     desc: 'Blocks TBD/TODO in specs and plans' },
+    { name: 'validate-dungeon.sh',             desc: 'Requires multi-agent verification on pins' },
+    { name: 'validate-browser-tests-exist.sh', desc: 'Checks Playwright tests exist before commits' },
+    { name: 'validate-browser-cleanup.sh',     desc: 'Verifies browser processes cleaned up properly' },
+  ],
+};
+
+const 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',
+};
+
+const CONFIG = {
+  'raid.json':      'Project settings (editable)',
+  'raid-rules.md':  '17 team rules (editable)',
+  'settings.json':  'Hooks merged into existing (backup created)',
+};
+
+module.exports = { AGENTS, HOOKS, SKILLS, CONFIG };

package/src/doctor.js

@@ -1,13 +1,15 @@
 'use strict';
 
 const { runChecks, runSetup } = require('./setup');
-const { banner, box, header, colors } = require('./ui');
+const { banner, header } = require('./ui');
 
 function diagnose(opts) {
   return runChecks(opts);
 }
 
 async function run() {
+  const { referenceCard } = require('./ui');
+
   console.log('\n' + banner());
   console.log(header('Diagnosing Wounds...') + '\n');
 
@@ -17,34 +19,7 @@ async function run() {
     process.exitCode = 1;
   }
 
-  const quickStart = box('Quick Start', [
-    '  In-process mode (any terminal):',
-    '    ' + colors.bold('claude --agent wizard'),
-    '',
-    '  Split-pane mode (tmux):',
-    '    ' + colors.bold('tmux new-session -s raid'),
-    '    ' + colors.bold('claude --agent wizard --teammate-mode tmux'),
-  ]);
-  console.log('\n' + quickStart);
-
-  const controls = box('Controls', [
-    '  ' + colors.bold('Shift+Down') + '    Cycle through teammates',
-    '  ' + colors.bold('Enter') + '         View a teammate\'s session',
-    '  ' + colors.bold('Escape') + '        Interrupt a teammate\'s turn',
-    '  ' + colors.bold('Ctrl+T') + '        Toggle the shared task list',
-    '  ' + colors.bold('Click pane') + '    Interact directly (split-pane)',
-  ]);
-  console.log('\n' + controls);
-
-  const modes = box('Raid Modes', [
-    '  ' + colors.bold('Full Raid') + '     Warrior + Archer + Rogue (3 agents)',
-    '  ' + colors.bold('Skirmish') + '      2 agents, lightweight',
-    '  ' + colors.bold('Scout') + '         Wizard solo review',
-    '',
-    '  The Wizard recommends a mode based on task',
-    '  complexity. You confirm before agents spawn.',
-  ]);
-  console.log('\n' + modes + '\n');
+  console.log('\n' + referenceCard() + '\n');
 }
 
 module.exports = { diagnose, run };

package/src/init.js

@@ -6,6 +6,7 @@ const { detectProject } = require('./detect-project');
 const { mergeSettings } = require('./merge-settings');
 const { runSetup } = require('./setup');
 const { banner, header, colors } = require('./ui');
+const { AGENTS, HOOKS, SKILLS, CONFIG } = require('./descriptions');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template', '.claude');
 
@@ -60,6 +61,16 @@ function install(cwd) {
     }
   }
 
+  // Count copied files by category
+  const agentsDir = path.join(claudeDir, 'agents');
+  const hooksDir2 = path.join(claudeDir, 'hooks');
+  const skillsDir = path.join(claudeDir, 'skills');
+  result.counts = {
+    agents: fs.existsSync(agentsDir) ? fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')).length : 0,
+    hooks: fs.existsSync(hooksDir2) ? fs.readdirSync(hooksDir2).filter(f => f.endsWith('.sh')).length : 0,
+    skills: fs.existsSync(skillsDir) ? fs.readdirSync(skillsDir).filter(f => !f.startsWith('.')).length : 0,
+  };
+
   // Generate raid.json (skip if it already exists to preserve user config)
   const raidConfigPath = path.join(claudeDir, 'raid.json');
   if (!fs.existsSync(raidConfigPath)) {
@@ -139,7 +150,8 @@ function install(cwd) {
   ];
   if (fs.existsSync(gitignorePath)) {
     let content = fs.readFileSync(gitignorePath, 'utf8');
-    const toAdd = ignoreEntries.filter(e => !content.includes(e));
+    const lines = content.split('\n').map(l => l.trim());
+    const toAdd = ignoreEntries.filter(e => !lines.includes(e.trim()));
     if (toAdd.length > 0) {
       const sep = content.endsWith('\n') ? '' : '\n';
       fs.appendFileSync(gitignorePath, sep + toAdd.join('\n') + '\n');
@@ -153,26 +165,149 @@ function install(cwd) {
 
 async function run() {
   const cwd = process.cwd();
+  const { bold, dim } = colors;
+
   console.log('\n' + banner());
   console.log(header('Summoning the Party...') + '\n');
 
   const result = install(cwd);
 
   if (result.alreadyInstalled) {
-    console.log('  The party is already here. Use ' + colors.bold('claude-raid update') + ' to reforge.');
+    console.log('  The party is already here. Use ' + bold('claude-raid update') + ' to reforge.');
     console.log('  Proceeding with re-summon...\n');
   }
 
-  console.log('  Realm detected: ' + colors.bold(result.detected.language));
+  // Detection summary
+  console.log('  Realm detected: ' + bold(result.detected.language));
   if (result.detected.testCommand) {
-    console.log('  Battle cry:     ' + colors.bold(result.detected.testCommand));
+    console.log('  Test command:   ' + bold(result.detected.testCommand));
+  }
+  if (result.detected.lintCommand) {
+    console.log('  Lint command:   ' + bold(result.detected.lintCommand));
   }
+
+  // Agents
+  console.log('');
+  console.log('  ' + header('Agents') + dim(`                                      ${result.counts.agents} files`));
+  console.log('    Copied wizard.md, warrior.md, archer.md, rogue.md');
+  console.log(dim('    AI teammates that challenge each other\'s work from'));
+  console.log(dim('    competing angles. Start a session with: claude --agent wizard'));
+
+  // Hooks
+  console.log('');
+  console.log('  ' + header('Hooks') + dim(`                                     ${result.counts.hooks} files`));
+  console.log('    Copied ' + bold(`${HOOKS.lifecycle.length} lifecycle hooks`) + ' + ' + bold(`${HOOKS.gates.length} quality gates`));
+  console.log(dim('    Lifecycle hooks manage session state automatically.'));
+  console.log(dim('    Quality gates block bad commits, missing tests, and'));
+  console.log(dim('    placeholder text \u2014 only active during Raid sessions.'));
+
+  // Skills
+  console.log('');
+  console.log('  ' + header('Skills') + dim(`                                ${result.counts.skills} folders`));
+  const skillNames = Object.keys(SKILLS).join(', ');
+  console.log('    ' + dim(skillNames));
+  console.log(dim('    Phase-specific workflows that guide agent behavior.'));
+
+  // Config
+  console.log('');
+  console.log('  ' + header('Config'));
+  console.log('    Generated ' + bold('raid.json') + '          ' + dim('Project settings (editable)'));
+  console.log('    Copied ' + bold('raid-rules.md') + '         ' + dim('17 team rules (editable)'));
+  console.log('    Merged ' + bold('settings.json') + '         ' + dim('Backup at .pre-raid-backup'));
+
+  // Skipped files
   if (result.skipped.length > 0) {
-    console.log('\n  ' + colors.dim('Preserved existing scrolls:'));
-    result.skipped.forEach(f => console.log('    ' + colors.dim('→ ' + path.relative(cwd, f))));
+    console.log('');
+    console.log('  ' + dim('Preserved existing scrolls:'));
+    result.skipped.forEach(f => console.log('    ' + dim('\u2192 ' + path.relative(cwd, f))));
   }
 
+  // Setup wizard
   await runSetup();
+
+  // Reference card
+  const { referenceCard } = require('./ui');
+  console.log('\n' + referenceCard() + '\n');
+}
+
+function dryRun(cwd) {
+  const detected = detectProject(cwd);
+  const lines = [];
+
+  lines.push(header('Dry Run — nothing will be written') + '\n');
+
+  // Realm
+  lines.push('  Realm detected: ' + colors.bold(detected.language));
+  if (detected.testCommand) {
+    lines.push('  Test command:   ' + colors.bold(detected.testCommand));
+  }
+  if (detected.lintCommand) {
+    lines.push('  Lint command:   ' + colors.bold(detected.lintCommand));
+  }
+  lines.push('');
+
+  // Helper: check if a file already exists
+  const claudeDir = path.join(cwd, '.claude');
+  function tag(relPath) {
+    const full = path.join(claudeDir, relPath);
+    return fs.existsSync(full) ? ' ' + colors.dim('(preserved)') : '';
+  }
+
+  // Agents
+  lines.push(header('Agents') + '\n');
+  for (const [file, desc] of Object.entries(AGENTS)) {
+    lines.push('  ' + colors.bold(file.padEnd(14)) + desc + tag('agents/' + file));
+  }
+  lines.push('');
+
+  // Hooks — Lifecycle
+  lines.push(header('Hooks — Lifecycle') + '\n');
+  for (const h of HOOKS.lifecycle) {
+    lines.push('  ' + colors.bold(h.name.padEnd(28)) + h.desc + tag('hooks/' + h.name));
+  }
+  lines.push('');
+
+  // Hooks — Quality Gates
+  lines.push(header('Hooks — Quality Gates') + '\n');
+  for (const h of HOOKS.gates) {
+    lines.push('  ' + colors.bold(h.name.padEnd(36)) + h.desc + tag('hooks/' + h.name));
+  }
+  lines.push('');
+
+  // Skills
+  lines.push(header('Skills') + '\n');
+  for (const [folder, desc] of Object.entries(SKILLS)) {
+    lines.push('  ' + colors.bold(folder.padEnd(28)) + desc + tag('skills/' + folder));
+  }
+  lines.push('');
+
+  // Config
+  lines.push(header('Config') + '\n');
+  for (const [file, desc] of Object.entries(CONFIG)) {
+    lines.push('  ' + colors.bold(file.padEnd(20)) + desc + tag(file));
+  }
+  lines.push('');
+
+  // .gitignore
+  lines.push(header('.gitignore entries') + '\n');
+  const ignoreEntries = [
+    '.claude/raid-last-test-run',
+    '.claude/raid-session',
+    '.claude/raid-dungeon.md',
+    '.claude/raid-dungeon-phase-*',
+    '.claude/raid-dungeon-backup.md',
+    '.claude/raid-dungeon-phase-*-backup.md',
+    '.claude/vault/.draft/',
+    '.env.raid',
+  ];
+  for (const entry of ignoreEntries) {
+    lines.push('  ' + colors.dim(entry));
+  }
+  lines.push('');
+
+  lines.push('  Run without --dry-run to install.');
+
+  return lines.join('\n');
 }
 
-module.exports = { install, run };
+module.exports = { install, run, dryRun };

package/src/merge-settings.js

@@ -126,7 +126,7 @@ function mergeSettings(cwd) {
   if (!existing.hooks) existing.hooks = {};
 
   for (const [event, raidEntries] of Object.entries(RAID_HOOKS)) {
-    if (!existing.hooks[event]) {
+    if (!Array.isArray(existing.hooks[event])) {
       existing.hooks[event] = [];
     }
     existing.hooks[event] = existing.hooks[event].filter(entry => !isRaidHookEntry(entry));

package/src/setup.js

@@ -34,7 +34,7 @@ function versionGte(v, min) {
 const MIN_NODE = { major: 18, minor: 0, patch: 0 };
 const MIN_CLAUDE = { major: 2, minor: 1, patch: 32 };
 const VALID_TEAMMATE_MODES = ['tmux', 'in-process', 'auto'];
-const REQUIRED_IDS = ['node', 'claude'];
+const REQUIRED_IDS = ['node', 'claude', 'jq'];
 
 // --- Check functions (private) ---
 
@@ -166,11 +166,10 @@ function checkPlaywright(exec, cwd) {
   }
 
   // Determine exec command prefix (e.g. "npx" or "pnpm dlx")
-  const execCommand = raidConfig.execCommand || 'npx';
+  const execCommand = (raidConfig.project && raidConfig.project.execCommand) || 'npx';
 
   // Check if playwright config file exists
   const configFile = (raidConfig.browser && raidConfig.browser.playwrightConfig) || 'playwright.config.ts';
-  const configExists = cwd && fs.existsSync(path.join(cwd, configFile));
 
   // Check playwright version
   const raw = exec(`${execCommand} playwright --version`);
@@ -197,6 +196,45 @@ function checkPlaywright(exec, cwd) {
   };
 }
 
+function checkJq(exec) {
+  const found = exec('command -v jq');
+  if (found) {
+    return {
+      id: 'jq',
+      ok: true,
+      label: 'jq',
+      detail: 'installed',
+    };
+  }
+  return {
+    id: 'jq',
+    ok: false,
+    label: 'jq',
+    detail: 'not found',
+    hint: process.platform === 'darwin'
+      ? 'Install: brew install jq'
+      : 'Install jq via your package manager (apt, dnf, brew, etc.)',
+  };
+}
+
+function checkPlatform(platform) {
+  if (platform === 'win32') {
+    return {
+      id: 'platform',
+      ok: false,
+      label: 'Platform',
+      detail: 'Windows is not supported — hooks require POSIX bash',
+      hint: 'Use WSL2 (Windows Subsystem for Linux) for full compatibility',
+    };
+  }
+  return {
+    id: 'platform',
+    ok: true,
+    label: 'Platform',
+    detail: platform,
+  };
+}
+
 function checkSplitPane(exec) {
   const tmux = exec('command -v tmux');
   const it2 = exec('command -v it2');
@@ -273,9 +311,13 @@ function runChecks(opts = {}) {
 
   const nodeVersion = opts.nodeVersion || undefined;
 
+  const platform = opts.platform || process.platform;
+
   const checks = [
+    checkPlatform(platform),
     checkNode(nodeVersion),
     checkClaude(exec),
+    checkJq(exec),
     checkTeammateMode(homedir),
     checkSplitPane(exec),
     checkPlaywright(exec, cwd),

package/src/ui.js

@@ -16,6 +16,7 @@ const colors = {
   bold: wrap('1'),
   boldAmber: wrap('1;33'),
   boldRed: wrap('1;31'),
+  dimRed: wrap('2;31'),
 };
 
 function stripAnsi(str) {
@@ -23,7 +24,7 @@ function stripAnsi(str) {
 }
 
 function banner() {
-  const { amber, boldAmber, boldRed, dim } = colors;
+  const { amber, boldAmber, boldRed, red, dimRed, dim } = colors;
   const rule = amber('  ⚔ ═══════════════════════════════════════════════════════ ⚔');
 
   const claudeArt = [
@@ -44,14 +45,30 @@ function banner() {
     '              ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═════╝ ',
   ];
 
-  const tagline = '      Adversarial multi-agent warfare for Claude Code';
+  // 5-tone vertical gradient: boldAmber -> amber -> boldRed -> red -> dimRed
+  // Lines 1-2 (CLAUDE top): boldAmber
+  // Lines 3-5 (CLAUDE bottom + transition): amber
+  // Line 6 (CLAUDE/RAID boundary): boldRed
+  // Lines 7-8 (RAID top): boldRed
+  // Lines 9-11 (RAID middle): red
+  // Line 12 (RAID bottom): dimRed
+  const gradientColors = [
+    boldAmber, boldAmber,       // claudeArt[0-1]
+    amber, amber, amber,        // claudeArt[2-4]
+    boldRed,                    // claudeArt[5]
+    boldRed, boldRed,           // raidArt[0-1]
+    red, red, red,              // raidArt[2-4]
+    dimRed,                     // raidArt[5]
+  ];
+
+  const allArt = [...claudeArt, ...raidArt];
+  const tagline = '      Adversarial multi-agent development for Claude Code';
 
   const lines = [
     '',
     rule,
     '',
-    ...claudeArt.map(l => boldAmber(l)),
-    ...raidArt.map(l => boldRed(l)),
+    ...allArt.map((l, i) => gradientColors[i](l)),
     '',
     dim(tagline),
     '',
@@ -100,4 +117,52 @@ function header(text) {
   return `  ${amber(bold(`\u2694 ${text}`))}`;
 }
 
-module.exports = { colors, banner, box, header, stripAnsi };
+function referenceCard() {
+  const howItWorks = box('How It Works', [
+    '  You describe a task. The Wizard assesses complexity and',
+    '  recommends a mode:',
+    '',
+    '  ' + colors.bold('Full Raid') + '    3 agents attack from competing angles',
+    '  ' + colors.bold('Skirmish') + '     2 agents, lighter process',
+    '  ' + colors.bold('Scout') + '        1 agent + Wizard review',
+    '',
+    '  Every task flows through 4 phases:',
+    '',
+    '  1. ' + colors.bold('Design') + '     Agents explore and challenge the approach',
+    '  2. ' + colors.bold('Plan') + '       Agents decompose into testable tasks',
+    '  3. ' + colors.bold('Implement') + '  One builds (TDD), others attack',
+    '  4. ' + colors.bold('Review') + '     Independent reviews, fight over findings',
+    '',
+    '  Hooks enforce discipline automatically:',
+    '  ' + colors.dim('\u2022') + ' No implementation without a design doc',
+    '  ' + colors.dim('\u2022') + ' No commits without passing tests',
+    '  ' + colors.dim('\u2022') + ' No completion claims without fresh test evidence',
+    '  ' + colors.dim('\u2022') + ' Conventional commit messages required',
+    '',
+    '  ' + colors.dim('Hooks only activate during Raid sessions \u2014 they won\'t'),
+    '  ' + colors.dim('interfere with normal coding outside of a Raid.'),
+    '',
+    '  Config:  ' + colors.bold('.claude/raid.json') + '       ' + colors.dim('project settings'),
+    '  Rules:   ' + colors.bold('.claude/raid-rules.md') + '   ' + colors.dim('editable team rules'),
+  ]);
+
+  const nextStep = box('Next Step', [
+    '  ' + colors.bold('claude --agent wizard'),
+    '',
+    '  Describe your task and the Wizard takes over.',
+    '  ' + colors.dim('Tip: start with a small task (bugfix, config change) to'),
+    '  ' + colors.dim('see the workflow before tackling something complex.'),
+    '',
+    '  ' + colors.bold('Controls'),
+    '  ' + colors.bold('Shift+Down') + '    Cycle through teammates',
+    '  ' + colors.bold('Enter') + '         View a teammate\'s session',
+    '  ' + colors.bold('Escape') + '        Interrupt a teammate\'s turn',
+    '  ' + colors.bold('Ctrl+T') + '        Toggle the shared task list',
+    '',
+    '  Review this anytime:  ' + colors.bold('claude-raid heal'),
+  ]);
+
+  return howItWorks + '\n' + nextStep;
+}
+
+module.exports = { colors, banner, box, header, stripAnsi, referenceCard };

package/template/.claude/agents/wizard.md

@@ -64,9 +64,9 @@ Read `.claude/raid.json` at session start for project-specific settings (test co
 
 ## How You Lead
 
-### Phase 1 — Comprehension (you alone)
+### Pre-Phase — Comprehension (you alone)
 
-When a task arrives, you do NOT immediately delegate. You:
+When a task arrives, you do NOT immediately delegate. Before opening any phase, you:
 1. Read the full prompt. Read it again. Read it a third time.
 2. Identify the real problem beneath the stated problem.
 3. Map the blast radius — what does this touch? What could break?
@@ -75,7 +75,9 @@ When a task arrives, you do NOT immediately delegate. You:
 6. Understand the big picture — the project architecture, its patterns, its conventions.
 7. Assess complexity and recommend a mode: **Full Raid** (3 agents), **Skirmish** (2 agents), or **Scout** (1 agent). Present recommendation. Proceed only after human confirms.
 
-### Phase 2 — Open the Dungeon
+Then proceed to **Phase 1 — Design** (multi-agent exploration via `raid-design`).
+
+### Phase 1 — Open the Dungeon
 
 You set the stage. You give each agent:
 - The core objective