claude-raid 0.1.0

package/src/doctor.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+function tryExec(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function parseVersion(str) {
+  const match = str && str.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: +match[1], minor: +match[2], patch: +match[3] };
+}
+
+function versionGte(v, min) {
+  if (v.major !== min.major) return v.major > min.major;
+  if (v.minor !== min.minor) return v.minor > min.minor;
+  return v.patch >= min.patch;
+}
+
+const MIN_CLAUDE = { major: 2, minor: 1, patch: 32 };
+
+function checkNode() {
+  const v = process.version;
+  return { id: 'node', ok: true, label: 'Node.js', detail: v };
+}
+
+function checkClaude(exec) {
+  const raw = exec('claude --version');
+  if (!raw) {
+    return {
+      id: 'claude',
+      ok: false,
+      label: 'Claude Code',
+      detail: 'not found',
+      hint: 'Install: npm install -g @anthropic-ai/claude-code',
+    };
+  }
+  const ver = parseVersion(raw);
+  if (!ver) {
+    return {
+      id: 'claude',
+      ok: false,
+      label: 'Claude Code',
+      detail: `unknown version: ${raw}`,
+      hint: 'Expected semver from "claude --version"',
+    };
+  }
+  const ok = versionGte(ver, MIN_CLAUDE);
+  const tag = `v${ver.major}.${ver.minor}.${ver.patch}`;
+  return {
+    id: 'claude',
+    ok,
+    label: 'Claude Code',
+    detail: ok
+      ? `${tag} (≥ ${MIN_CLAUDE.major}.${MIN_CLAUDE.minor}.${MIN_CLAUDE.patch} required)`
+      : `${tag} — update required (≥ ${MIN_CLAUDE.major}.${MIN_CLAUDE.minor}.${MIN_CLAUDE.patch})`,
+    hint: ok ? undefined : 'Update: npm update -g @anthropic-ai/claude-code',
+  };
+}
+
+function checkTmux(exec) {
+  const raw = exec('command -v tmux');
+  if (!raw) {
+    return {
+      id: 'tmux',
+      ok: false,
+      label: 'tmux',
+      detail: 'not installed',
+      hint: process.platform === 'darwin'
+        ? 'Install: brew install tmux'
+        : 'Install tmux via your package manager (apt, dnf, brew, etc.)',
+    };
+  }
+  return { id: 'tmux', ok: true, label: 'tmux', detail: 'installed' };
+}
+
+function checkTeammateMode(homedir) {
+  const configPath = path.join(homedir, '.claude.json');
+  if (!fs.existsSync(configPath)) {
+    return {
+      id: 'teammate-mode',
+      ok: false,
+      label: 'teammateMode',
+      detail: 'not set — ~/.claude.json not found',
+      hint: 'Create ~/.claude.json with: { "teammateMode": "tmux" }',
+    };
+  }
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch {
+    return {
+      id: 'teammate-mode',
+      ok: false,
+      label: 'teammateMode',
+      detail: '~/.claude.json is not valid JSON',
+      hint: 'Fix the JSON syntax, then add: "teammateMode": "tmux"',
+    };
+  }
+  if (config.teammateMode === 'tmux') {
+    return {
+      id: 'teammate-mode',
+      ok: true,
+      label: 'teammateMode',
+      detail: 'tmux',
+    };
+  }
+  return {
+    id: 'teammate-mode',
+    ok: false,
+    label: 'teammateMode',
+    detail: config.teammateMode
+      ? `set to "${config.teammateMode}" (expected "tmux")`
+      : 'not set in ~/.claude.json',
+    hint: 'Add "teammateMode": "tmux" to ~/.claude.json',
+  };
+}
+
+function diagnose(opts = {}) {
+  const homedir = opts.homedir || os.homedir();
+  const exec = opts.exec || tryExec;
+
+  const checks = [
+    checkNode(),
+    checkClaude(exec),
+    checkTmux(exec),
+    checkTeammateMode(homedir),
+  ];
+
+  return {
+    checks,
+    allOk: checks.every(c => c.ok),
+  };
+}
+
+function formatChecks(checks) {
+  const lines = [];
+  const maxLabel = Math.max(...checks.map(c => c.label.length));
+
+  for (const check of checks) {
+    const icon = check.ok ? '✔' : '✖';
+    const pad = ' '.repeat(maxLabel - check.label.length + 2);
+    lines.push(`  ${icon} ${check.label}${pad}${check.detail}`);
+    if (check.hint) {
+      lines.push(`    → ${check.hint}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function run() {
+  const result = diagnose();
+
+  const output = `
+claude-raid doctor — Environment & Quick Start
+
+─── Prerequisites ───────────────────────────────
+
+${formatChecks(result.checks)}
+
+─── Quick Start ─────────────────────────────────
+
+  In-process mode (any terminal):
+
+    claude --agent wizard
+
+  Split-pane mode (tmux):
+
+    tmux new-session -s raid
+    claude --agent wizard --teammate-mode tmux
+
+─── Navigating Teammates ────────────────────────
+
+  Shift+Down    Cycle through teammates
+  Enter         View a teammate's session
+  Escape        Interrupt a teammate's turn
+  Ctrl+T        Toggle the shared task list
+  Click pane    Interact directly (split-pane mode)
+
+─── Raid Modes ──────────────────────────────────
+
+  Full Raid     Warrior + Archer + Rogue (3 agents)
+  Skirmish      2 agents, lightweight
+  Scout         Wizard solo review
+
+  The Wizard recommends a mode based on task
+  complexity. You confirm before agents spawn.
+`;
+
+  console.log(output);
+}
+
+module.exports = { diagnose, run };

package/src/init.js

@@ -0,0 +1,138 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { detectProject } = require('./detect-project');
+const { mergeSettings } = require('./merge-settings');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template', '.claude');
+
+function copyRecursive(src, dest, skipped) {
+  if (!fs.existsSync(src)) return;
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath, skipped);
+    } else {
+      if (fs.existsSync(destPath)) {
+        skipped.push(destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+function install(cwd) {
+  const claudeDir = path.join(cwd, '.claude');
+  const result = { skipped: [], alreadyInstalled: false, detected: null };
+
+  // Check if already installed
+  if (fs.existsSync(path.join(claudeDir, 'raid-rules.md'))) {
+    result.alreadyInstalled = true;
+  }
+
+  // Create .claude directory
+  fs.mkdirSync(claudeDir, { recursive: true });
+
+  // Detect project
+  const detected = detectProject(cwd);
+  result.detected = detected;
+
+  // Copy template files (agents, hooks, skills, raid-rules.md)
+  copyRecursive(TEMPLATE_DIR, claudeDir, result.skipped);
+
+  // Make hooks executable
+  const hooksDir = path.join(claudeDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hooks = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+    for (const hook of hooks) {
+      const hookPath = path.join(hooksDir, hook);
+      fs.chmodSync(hookPath, 0o755);
+    }
+  }
+
+  // Generate raid.json (skip if it already exists to preserve user config)
+  const raidConfigPath = path.join(claudeDir, 'raid.json');
+  if (!fs.existsSync(raidConfigPath)) {
+    const raidConfig = {
+      project: {
+        name: detected.name || path.basename(cwd),
+        language: detected.language,
+        testCommand: detected.testCommand || '',
+        lintCommand: detected.lintCommand || '',
+        buildCommand: detected.buildCommand || '',
+      },
+      paths: {
+        specs: 'docs/raid/specs',
+        plans: 'docs/raid/plans',
+        worktrees: '.worktrees',
+      },
+      conventions: {
+        fileNaming: 'none',
+        commits: 'conventional',
+      },
+      raid: {
+        defaultMode: 'full',
+      },
+    };
+    fs.writeFileSync(raidConfigPath, JSON.stringify(raidConfig, null, 2) + '\n');
+  }
+
+  // Merge settings
+  mergeSettings(cwd);
+
+  // Add raid-last-test-run to .gitignore
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const ignoreEntries = ['.claude/raid-last-test-run', '.claude/raid-session', '.claude/raid-dungeon.md', '.claude/raid-dungeon-phase-*'];
+  if (fs.existsSync(gitignorePath)) {
+    let content = fs.readFileSync(gitignorePath, 'utf8');
+    const toAdd = ignoreEntries.filter(e => !content.includes(e));
+    if (toAdd.length > 0) {
+      const sep = content.endsWith('\n') ? '' : '\n';
+      fs.appendFileSync(gitignorePath, sep + toAdd.join('\n') + '\n');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, ignoreEntries.join('\n') + '\n');
+  }
+
+  return result;
+}
+
+function run() {
+  const cwd = process.cwd();
+  console.log('\nclaude-raid — Installing The Raid\n');
+
+  const result = install(cwd);
+
+  if (result.alreadyInstalled) {
+    console.log('The Raid is already installed. Use `claude-raid update` to update.');
+    console.log('Proceeding with re-install...\n');
+  }
+
+  console.log(`Detected: ${result.detected.language}`);
+  if (result.detected.testCommand) {
+    console.log(`Test command: ${result.detected.testCommand}`);
+  }
+  if (result.skipped.length > 0) {
+    console.log(`\nSkipped (existing files):`);
+    result.skipped.forEach(f => console.log(`  - ${path.relative(cwd, f)}`));
+  }
+
+  console.log(`
+The Raid is installed.
+
+  Configuration:  .claude/raid.json (edit to customize)
+  Team rules:     .claude/raid-rules.md (editable)
+
+  Run 'claude-raid doctor' for setup guide and environment check.
+`);
+}
+
+module.exports = { install, run };

package/src/merge-settings.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RAID_ENV = {
+  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+};
+
+const RAID_PERMISSIONS = ['Read', 'Glob', 'Grep', 'Bash', 'Write', 'Edit'];
+
+const RAID_HOOK_MARKER = '#claude-raid';
+
+const RAID_HOOKS = {
+  PostToolUse: [
+    {
+      matcher: 'Write|Edit',
+      hooks: [
+        { type: 'command', command: `bash .claude/hooks/validate-file-naming.sh ${RAID_HOOK_MARKER}` },
+        { type: 'command', command: `bash .claude/hooks/validate-no-placeholders.sh ${RAID_HOOK_MARKER}` },
+      ],
+    },
+  ],
+  PreToolUse: [
+    {
+      matcher: 'Bash',
+      hooks: [
+        { type: 'command', command: `bash .claude/hooks/validate-commit-message.sh ${RAID_HOOK_MARKER}` },
+        { type: 'command', command: `bash .claude/hooks/validate-tests-pass.sh ${RAID_HOOK_MARKER}` },
+        { type: 'command', command: `bash .claude/hooks/validate-verification.sh ${RAID_HOOK_MARKER}` },
+      ],
+    },
+    {
+      matcher: 'Write',
+      hooks: [
+        { type: 'command', command: `bash .claude/hooks/validate-phase-gate.sh ${RAID_HOOK_MARKER}` },
+      ],
+    },
+  ],
+};
+
+function isRaidHookEntry(entry) {
+  return entry.hooks && entry.hooks.some(h => h.command && h.command.includes(RAID_HOOK_MARKER));
+}
+
+function mergeSettings(cwd) {
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  let existing = {};
+
+  if (fs.existsSync(settingsPath)) {
+    const backupPath = settingsPath + '.pre-raid-backup';
+    if (!fs.existsSync(backupPath)) {
+      fs.copyFileSync(settingsPath, backupPath);
+    }
+    try {
+      existing = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch {
+      throw new Error(
+        'Your existing .claude/settings.json contains invalid JSON. Please fix it before running claude-raid.'
+      );
+    }
+  }
+
+  existing.env = { ...(existing.env || {}), ...RAID_ENV };
+
+  const existingPerms = (existing.permissions && existing.permissions.allow) || [];
+  const merged = [...new Set([...existingPerms, ...RAID_PERMISSIONS])];
+  existing.permissions = { ...(existing.permissions || {}), allow: merged };
+
+  if (!existing.hooks) existing.hooks = {};
+
+  for (const [event, raidEntries] of Object.entries(RAID_HOOKS)) {
+    if (!existing.hooks[event]) {
+      existing.hooks[event] = [];
+    }
+    existing.hooks[event] = existing.hooks[event].filter(entry => !isRaidHookEntry(entry));
+    existing.hooks[event].push(...raidEntries);
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+}
+
+function removeRaidSettings(cwd) {
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  const backupPath = settingsPath + '.pre-raid-backup';
+
+  if (fs.existsSync(backupPath)) {
+    fs.copyFileSync(backupPath, settingsPath);
+    fs.unlinkSync(backupPath);
+    return;
+  }
+
+  if (!fs.existsSync(settingsPath)) return;
+
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    throw new Error(
+      'Your .claude/settings.json contains invalid JSON. Please fix it before running claude-raid remove.'
+    );
+  }
+
+  if (settings.env) {
+    delete settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+  }
+
+  if (settings.hooks) {
+    for (const event of Object.keys(settings.hooks)) {
+      settings.hooks[event] = settings.hooks[event].filter(entry => !isRaidHookEntry(entry));
+      if (settings.hooks[event].length === 0) delete settings.hooks[event];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+module.exports = { mergeSettings, removeRaidSettings };

package/src/remove.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { removeRaidSettings } = require('./merge-settings');
+
+const RAID_AGENTS = ['wizard.md', 'warrior.md', 'archer.md', 'rogue.md'];
+const RAID_SKILLS = [
+  'raid-protocol', 'raid-design', 'raid-implementation-plan', 'raid-implementation',
+  'raid-review', 'raid-finishing', 'raid-tdd', 'raid-debugging',
+  'raid-verification', 'raid-git-worktrees',
+];
+
+function rmSafe(filePath) {
+  try { fs.unlinkSync(filePath); } catch {}
+}
+
+function rmDirSafe(dirPath) {
+  try { fs.rmSync(dirPath, { recursive: true }); } catch {}
+}
+
+function rmDirIfEmpty(dirPath) {
+  try {
+    const entries = fs.readdirSync(dirPath);
+    if (entries.length === 0) fs.rmdirSync(dirPath);
+  } catch {}
+}
+
+function performRemove(cwd) {
+  const claudeDir = path.join(cwd, '.claude');
+
+  for (const agent of RAID_AGENTS) {
+    rmSafe(path.join(claudeDir, 'agents', agent));
+  }
+
+  const hooksDir = path.join(claudeDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hooks = fs.readdirSync(hooksDir).filter(f => f.startsWith('validate-') && f.endsWith('.sh'));
+    for (const hook of hooks) {
+      rmSafe(path.join(hooksDir, hook));
+    }
+  }
+
+  for (const skill of RAID_SKILLS) {
+    rmDirSafe(path.join(claudeDir, 'skills', skill));
+  }
+
+  // Clean up empty directories
+  rmDirIfEmpty(path.join(claudeDir, 'agents'));
+  rmDirIfEmpty(path.join(claudeDir, 'hooks'));
+  rmDirIfEmpty(path.join(claudeDir, 'skills'));
+
+  rmSafe(path.join(claudeDir, 'raid-rules.md'));
+  rmSafe(path.join(claudeDir, 'raid.json'));
+  rmSafe(path.join(claudeDir, 'raid-last-test-run'));
+  rmSafe(path.join(claudeDir, 'raid-session'));
+
+  // Clean up Dungeon files
+  rmSafe(path.join(claudeDir, 'raid-dungeon.md'));
+  if (fs.existsSync(claudeDir)) {
+    const dungeonFiles = fs.readdirSync(claudeDir).filter(f => f.startsWith('raid-dungeon-phase-'));
+    for (const file of dungeonFiles) {
+      rmSafe(path.join(claudeDir, file));
+    }
+  }
+
+  removeRaidSettings(cwd);
+
+  // Clean .gitignore entries
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const raidIgnoreEntries = ['.claude/raid-last-test-run', '.claude/raid-session', '.claude/raid-dungeon.md', '.claude/raid-dungeon-phase-*'];
+  if (fs.existsSync(gitignorePath)) {
+    const lines = fs.readFileSync(gitignorePath, 'utf8').split('\n');
+    const filtered = lines.filter(line => !raidIgnoreEntries.includes(line.trim()));
+    // Remove trailing blank lines caused by removal
+    while (filtered.length > 0 && filtered[filtered.length - 1] === '') {
+      filtered.pop();
+    }
+    fs.writeFileSync(gitignorePath, filtered.join('\n') + '\n');
+  }
+
+  return { success: true };
+}
+
+function run() {
+  const cwd = process.cwd();
+  console.log('\nclaude-raid — Removing The Raid\n');
+  performRemove(cwd);
+  console.log('The Raid has been removed. Your project settings have been restored.');
+}
+
+module.exports = { performRemove, run };

package/src/update.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { mergeSettings } = require('./merge-settings');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template', '.claude');
+
+function filesAreEqual(pathA, pathB) {
+  try {
+    return fs.readFileSync(pathA, 'utf8') === fs.readFileSync(pathB, 'utf8');
+  } catch {
+    return false;
+  }
+}
+
+function copyForceRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyForceRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function performUpdate(cwd) {
+  const claudeDir = path.join(cwd, '.claude');
+  const skippedAgents = [];
+
+  if (!fs.existsSync(path.join(claudeDir, 'raid-rules.md'))) {
+    return { success: false, message: 'The Raid is not installed. Run `claude-raid init` first.', skippedAgents };
+  }
+
+  // Update agents — skip if user has customized them
+  const agentsSrc = path.join(TEMPLATE_DIR, 'agents');
+  const agentsDest = path.join(claudeDir, 'agents');
+  if (fs.existsSync(agentsSrc)) {
+    fs.mkdirSync(agentsDest, { recursive: true });
+    const agents = fs.readdirSync(agentsSrc).filter(f => f.endsWith('.md'));
+    for (const agent of agents) {
+      const srcPath = path.join(agentsSrc, agent);
+      const destPath = path.join(agentsDest, agent);
+      if (fs.existsSync(destPath) && !filesAreEqual(srcPath, destPath)) {
+        skippedAgents.push(agent);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+
+  // Update hooks and skills — always overwrite (these are framework code, not user content)
+  for (const subdir of ['hooks', 'skills']) {
+    const src = path.join(TEMPLATE_DIR, subdir);
+    const dest = path.join(claudeDir, subdir);
+    if (fs.existsSync(src)) {
+      fs.mkdirSync(dest, { recursive: true });
+      copyForceRecursive(src, dest);
+    }
+  }
+
+  // Update raid-rules.md — skip if user has customized it
+  const rulesSrc = path.join(TEMPLATE_DIR, 'raid-rules.md');
+  const rulesDest = path.join(claudeDir, 'raid-rules.md');
+  let skippedRules = false;
+  if (fs.existsSync(rulesSrc)) {
+    if (fs.existsSync(rulesDest) && !filesAreEqual(rulesSrc, rulesDest)) {
+      skippedRules = true;
+    } else {
+      fs.copyFileSync(rulesSrc, rulesDest);
+    }
+  }
+
+  const hooksDir = path.join(claudeDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hooks = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+    for (const hook of hooks) {
+      fs.chmodSync(path.join(hooksDir, hook), 0o755);
+    }
+  }
+
+  mergeSettings(cwd);
+
+  let message = 'The Raid has been updated to the latest version.';
+  if (skippedAgents.length > 0) {
+    message += `\nSkipped customized agents: ${skippedAgents.join(', ')}`;
+  }
+  if (skippedRules) {
+    message += '\nSkipped customized raid-rules.md';
+  }
+  if (skippedAgents.length > 0 || skippedRules) {
+    message += '\nUse `claude-raid remove` then `claude-raid init` to reset.';
+  }
+
+  return { success: true, message, skippedAgents };
+}
+
+function run() {
+  const cwd = process.cwd();
+  console.log('\nclaude-raid — Updating The Raid\n');
+  const result = performUpdate(cwd);
+  console.log(result.message);
+}
+
+module.exports = { performUpdate, run };