claude-raid 0.1.0

package/template/.claude/hooks/validate-file-naming.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Raid quality gate: validates file naming conventions
+# PostToolUse hook for Write and Edit operations
+# Reads conventions from .claude/raid.json
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+RAID_CONFIG=".claude/raid.json"
+ISSUES=""
+
+# Read naming convention from config (default: none)
+NAMING="none"
+if [ -f "$RAID_CONFIG" ]; then
+  NAMING=$(jq -r '.conventions.fileNaming // "none"' "$RAID_CONFIG")
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Check 1: No spaces in filenames (always enforced)
+if echo "$BASENAME" | grep -qE '[[:space:]]'; then
+  ISSUES="${ISSUES}NAMING: File '$BASENAME' contains spaces. Use hyphens or underscores.\n"
+fi
+
+# Check 2: Naming convention (if configured)
+if [ "$NAMING" != "none" ]; then
+  # Strip extension for naming check
+  NAME_PART=$(echo "$BASENAME" | sed 's/\.[^.]*$//')
+
+  case "$NAMING" in
+    kebab-case)
+      if ! echo "$NAME_PART" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$'; then
+        ISSUES="${ISSUES}NAMING: File '$BASENAME' does not follow kebab-case convention.\n"
+      fi
+      ;;
+    snake_case)
+      if ! echo "$NAME_PART" | grep -qE '^[a-z0-9]+(_[a-z0-9]+)*$'; then
+        ISSUES="${ISSUES}NAMING: File '$BASENAME' does not follow snake_case convention.\n"
+      fi
+      ;;
+    camelCase)
+      if ! echo "$NAME_PART" | grep -qE '^[a-z][a-zA-Z0-9]*$'; then
+        ISSUES="${ISSUES}NAMING: File '$BASENAME' does not follow camelCase convention.\n"
+      fi
+      ;;
+  esac
+fi
+
+# Check 3: Directory depth (default max 8)
+MAX_DEPTH=8
+if [ -f "$RAID_CONFIG" ]; then
+  CONFIGURED_DEPTH=$(jq -r '.conventions.maxDepth // empty' "$RAID_CONFIG")
+  if [ -n "$CONFIGURED_DEPTH" ]; then
+    MAX_DEPTH="$CONFIGURED_DEPTH"
+  fi
+fi
+
+DEPTH=$(echo "$FILE_PATH" | awk -F'/' '{print NF}')
+if [ "$DEPTH" -gt "$MAX_DEPTH" ]; then
+  ISSUES="${ISSUES}STRUCTURE: File at depth $DEPTH ($FILE_PATH). Maximum is $MAX_DEPTH.\n"
+fi
+
+if [ -n "$ISSUES" ]; then
+  printf "Raid Quality Check:\n%b" "$ISSUES" >&2
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/validate-no-placeholders.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Raid quality gate: blocks placeholder text in specs and plans
+# PostToolUse hook for Write and Edit operations
+# Only checks files within configured specs/plans paths
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+RAID_CONFIG=".claude/raid.json"
+
+# Read paths from config (defaults)
+SPECS_PATH="docs/raid/specs"
+PLANS_PATH="docs/raid/plans"
+if [ -f "$RAID_CONFIG" ]; then
+  CONFIGURED_SPECS=$(jq -r '.paths.specs // empty' "$RAID_CONFIG")
+  CONFIGURED_PLANS=$(jq -r '.paths.plans // empty' "$RAID_CONFIG")
+  [ -n "$CONFIGURED_SPECS" ] && SPECS_PATH="$CONFIGURED_SPECS"
+  [ -n "$CONFIGURED_PLANS" ] && PLANS_PATH="$CONFIGURED_PLANS"
+fi
+
+# Only check files in specs or plans directories
+IS_RAID_DOC=false
+case "$FILE_PATH" in
+  "$SPECS_PATH"/*|"$PLANS_PATH"/*) IS_RAID_DOC=true ;;
+esac
+
+if [ "$IS_RAID_DOC" = false ]; then
+  exit 0
+fi
+
+# Read the actual file content (tool_output is the tool's response message, not file content)
+CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  CONTENT=$(cat "$FILE_PATH")
+fi
+
+if [ -z "$CONTENT" ]; then
+  exit 0
+fi
+
+ISSUES=""
+LINE_NUM=0
+
+# Scan for placeholder patterns (case-insensitive)
+while IFS= read -r line; do
+  LINE_NUM=$((LINE_NUM + 1))
+  LOWER_LINE=$(echo "$line" | tr '[:upper:]' '[:lower:]')
+
+  for PATTERN in "tbd" "todo" "fixme" "implement later" "add appropriate" "similar to task" "handle edge cases" "fill in"; do
+    if echo "$LOWER_LINE" | grep -qi "$PATTERN"; then
+      ISSUES="${ISSUES}Line ${LINE_NUM}: Found '${PATTERN}' — ${line}\n"
+      break
+    fi
+  done
+done <<< "$CONTENT"
+
+if [ -n "$ISSUES" ]; then
+  printf "Raid Placeholder Check:\nBLOCKED: Placeholders found in %s:\n%b\nRemove all placeholders before proceeding.\n" "$FILE_PATH" "$ISSUES" >&2
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/validate-phase-gate.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Raid quality gate: blocks implementation without a design doc
+# PreToolUse hook for Write operations
+# Reads mode and paths from .claude/raid.json
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+RAID_CONFIG=".claude/raid.json"
+
+# Skip if no config (Raid not initialized)
+if [ ! -f "$RAID_CONFIG" ]; then
+  exit 0
+fi
+
+# Skip if no active Raid session — don't block normal work
+# The Wizard creates .claude/raid-session when a Raid starts
+if [ ! -f ".claude/raid-session" ]; then
+  exit 0
+fi
+
+# Read mode and specs path
+MODE=$(jq -r '.raid.defaultMode // "full"' "$RAID_CONFIG")
+SPECS_PATH=$(jq -r '.paths.specs // "docs/raid/specs"' "$RAID_CONFIG")
+
+# Scout mode: no phase gate
+if [ "$MODE" = "scout" ]; then
+  exit 0
+fi
+
+# Skip checks for non-implementation files
+# Allow: docs, tests, config files, raid files, markdown
+case "$FILE_PATH" in
+  docs/*|test/*|tests/*|*.test.*|*.spec.*|*_test.*|*_spec.*) exit 0 ;;
+  .claude/*|*.json|*.yml|*.yaml|*.toml|*.md|*.lock) exit 0 ;;
+  *.config.*|*.rc|.gitignore|Makefile|Dockerfile) exit 0 ;;
+esac
+
+# Check if any design doc exists in specs path
+if [ -d "$SPECS_PATH" ]; then
+  DOC_COUNT=$(find "$SPECS_PATH" -name "*.md" -type f 2>/dev/null | head -1)
+  if [ -n "$DOC_COUNT" ]; then
+    exit 0
+  fi
+fi
+
+# No design doc found
+if [ "$MODE" = "full" ]; then
+  printf "Raid Phase Gate:\nBLOCKED: No design doc found in %s.\nCreate a design doc before writing implementation code.\nUse 'raid-design' skill or set mode to 'scout' in .claude/raid.json.\n" "$SPECS_PATH" >&2
+  exit 2
+fi
+
+# Skirmish mode: warn only
+printf "Raid Phase Gate:\nWARNING: No design doc found in %s. Consider creating one.\n" "$SPECS_PATH" >&2
+exit 0

package/template/.claude/hooks/validate-tests-pass.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Raid quality gate: runs tests before allowing commits
+# PreToolUse hook for Bash commands containing 'git commit'
+# Reads test command from .claude/raid.json
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only check git commit commands
+if ! echo "$COMMAND" | grep -qE 'git commit'; then
+  exit 0
+fi
+
+RAID_CONFIG=".claude/raid.json"
+
+# Skip if no active Raid session
+if [ ! -f ".claude/raid-session" ]; then
+  exit 0
+fi
+
+# Read test command from config
+TEST_CMD=""
+if [ -f "$RAID_CONFIG" ]; then
+  TEST_CMD=$(jq -r '.project.testCommand // empty' "$RAID_CONFIG")
+fi
+
+# No test command configured — warn but allow
+if [ -z "$TEST_CMD" ]; then
+  exit 0
+fi
+
+# Run tests
+if ! eval "$TEST_CMD" > /dev/null 2>&1; then
+  printf "Raid Quality Check:\nTESTS: Tests failed. Fix before committing.\nCommand: %s\n" "$TEST_CMD" >&2
+  exit 2
+fi
+
+# Write timestamp for verification hook
+mkdir -p .claude
+date +%s > .claude/raid-last-test-run
+
+exit 0

package/template/.claude/hooks/validate-verification.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Raid quality gate: blocks completion claims without recent test evidence
+# PreToolUse hook for Bash commands containing 'git commit'
+# Checks for .claude/raid-last-test-run timestamp (written by validate-tests-pass.sh)
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Only check git commit commands
+if ! echo "$COMMAND" | grep -qE 'git commit'; then
+  exit 0
+fi
+
+# Skip if no active Raid session
+if [ ! -f ".claude/raid-session" ]; then
+  exit 0
+fi
+
+# Extract commit message
+MSG=""
+if echo "$COMMAND" | grep -qE -- '-m '; then
+  MSG=$(echo "$COMMAND" | sed -n 's/.*-m "\([^"]*\)".*/\1/p' | head -1)
+  if [ -z "$MSG" ]; then
+    MSG=$(echo "$COMMAND" | sed -n "s/.*-m '\\([^']*\\)'.*/\\1/p" | head -1)
+  fi
+fi
+
+# Try heredoc
+if [ -z "$MSG" ]; then
+  MSG=$(echo "$COMMAND" | sed -n 's/.*cat <<.*//;n;s/^ *//;p' | head -1)
+fi
+
+if [ -z "$MSG" ]; then
+  exit 0
+fi
+
+# Check if message claims completion
+LOWER_MSG=$(echo "$MSG" | tr '[:upper:]' '[:lower:]')
+HAS_COMPLETION=false
+for WORD in "complete" "done" "finish" "final"; do
+  if echo "$LOWER_MSG" | grep -qiw "$WORD"; then
+    HAS_COMPLETION=true
+    break
+  fi
+done
+
+if [ "$HAS_COMPLETION" = false ]; then
+  exit 0
+fi
+
+# Check for recent test run
+TIMESTAMP_FILE=".claude/raid-last-test-run"
+MAX_AGE=600  # 10 minutes in seconds
+
+if [ ! -f "$TIMESTAMP_FILE" ]; then
+  printf "Raid Verification Check:\nBLOCKED: Commit claims completion but no test run evidence found.\nRun tests before claiming work is complete.\n" >&2
+  exit 2
+fi
+
+LAST_RUN=$(cat "$TIMESTAMP_FILE")
+NOW=$(date +%s)
+AGE=$((NOW - LAST_RUN))
+
+if [ "$AGE" -gt "$MAX_AGE" ]; then
+  printf "Raid Verification Check:\nBLOCKED: Last test run was %d minutes ago. Run tests again before claiming completion.\n" "$((AGE / 60))" >&2
+  exit 2
+fi
+
+exit 0

package/template/.claude/raid-rules.md

@@ -0,0 +1,21 @@
+# Raid Team Rules
+
+These are non-negotiable. Every agent follows them at all times.
+
+1. **No subagents.** This team uses agent teams only. Never delegate to subagents.
+2. **No laziness.** Every review is genuine. Every challenge carries new evidence or a new angle. No rubber-stamping.
+3. **No trust without verification.** Verify independently. Reports lie — read actual code.
+4. **Learn from mistakes.** When proven wrong, absorb the lesson. When another agent errs, learn from that too. Don't repeat errors.
+5. **Make every move count.** Limited moves, like a board game. No endless disputes. No circular arguments. Every interaction must carry the work forward. If you've made your point and been heard, move on.
+6. **Share knowledge.** Competitors but also a team. Discoveries are shared. The goal is maximum quality, not personal victory.
+7. **No ego.** Defend ideas with evidence. If you don't have evidence, don't defend. If proven wrong, concede instantly. Don't be stubborn. Don't hallucinate. Hesitate if uncertain.
+8. **Stay active.** All assigned agents participate at every step. No sitting idle while others work.
+9. **Wizard is the human interface.** Agents ask the Wizard for clarification. Only the Wizard asks the human important questions. Agents may ask the human only if the Wizard explicitly permits it.
+10. **Wizard is impartial.** No preference for any agent. Judge by evidence, not by source.
+11. **Wizard observes 90%, acts 10%.** The Wizard analyzes, judges, and maintains order. Speaks only when 90% confident or when the team is misaligned.
+12. **Maximum effort. Always.** Every agent runs at full capability on every task.
+13. **No hallucination.** If you don't know something, say so. Never fabricate evidence, certainty, or findings.
+14. **Dungeon discipline.** Only pin verified findings with `📌 DUNGEON:`. Don't spam. If challenged on a pin, defend with evidence or remove it. The Dungeon is a scoreboard, not a chat log.
+15. **Direct engagement.** Address agents by name with `@Name`. Build on each other's work explicitly with `🔗 BUILDING ON @Name:`. No broadcasting into void. No waiting for the Wizard to relay.
+16. **Escalate wisely.** Pull the Wizard with `🆘 WIZARD:` when genuinely stuck, split on fundamentals, or uncertain about project-level context. If you can resolve it by reading code or talking to another agent, do that first. Lazy escalation wastes the Wizard's attention.
+17. **Roast with evidence.** Every `🔥 ROAST:` carries proof — file paths, line numbers, concrete scenarios. "This is wrong" without showing why is laziness, not challenge.

package/template/.claude/skills/raid-debugging/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: raid-debugging
+description: "Use when encountering any bug, test failure, or unexpected behavior. Agents investigate competing hypotheses in parallel. No fixes without root cause. No subagents."
+---
+
+# Raid Debugging — Adversarial Root Cause Analysis
+
+Three investigators, three hypotheses, one truth.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## Mode Behavior
+
+- **Full Raid**: 3 agents investigate competing hypotheses in parallel.
+- **Skirmish**: 2 agents with different hypotheses.
+- **Scout**: 1 agent investigates + Wizard challenges the hypothesis.
+
+## Process Flow
+
+```dot
+digraph debugging {
+  "Bug encountered" -> "Phase 1: Root Cause Investigation";
+  "Phase 1: Root Cause Investigation" -> "Reproduce consistently?";
+  "Reproduce consistently?" -> "Gather more data" [label="no"];
+  "Gather more data" -> "Reproduce consistently?";
+  "Reproduce consistently?" -> "Dispatch competing hypotheses" [label="yes"];
+  "Dispatch competing hypotheses" -> "Agents investigate independently";
+  "Agents investigate independently" -> "Phase 2: Pattern Analysis";
+  "Phase 2: Pattern Analysis" -> "Phase 3: Hypothesis Testing";
+  "Phase 3: Hypothesis Testing" -> "Hypothesis confirmed?" [shape=diamond];
+  "Hypothesis confirmed?" -> "New hypothesis" [label="no"];
+  "New hypothesis" -> "Phase 3: Hypothesis Testing";
+  "Hypothesis confirmed?" -> "Wizard ruling: root cause identified" [label="yes"];
+  "Wizard ruling: root cause identified" -> "Phase 4: Fix (TDD)";
+  "Phase 4: Fix (TDD)" -> "Fix works?" [shape=diamond];
+  "Fix works?" -> "3+ failed fixes?" [label="no"];
+  "3+ failed fixes?" -> "Question architecture" [label="yes"];
+  "3+ failed fixes?" -> "New hypothesis" [label="no"];
+  "Fix works?" -> "Cross-test fix + verify" [label="yes"];
+  "Cross-test fix + verify" -> "Done" [shape=doublecircle];
+}
+```
+
+## The Four Phases
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read error messages carefully** — stack traces, line numbers, error codes. Don't skip past them. The answer is often in the first error.
+2. **Reproduce consistently** — exact steps, every time. If not reproducible, gather more data — don't guess. An unreproducible bug is not understood.
+3. **Check recent changes** — `git diff`, recent commits, new dependencies, config changes. What changed since it last worked?
+4. **Gather evidence at boundaries** — in multi-component systems, log what enters and exits each component boundary. Run once to see WHERE it breaks. THEN investigate that component.
+5. **Trace data flow** — where does the bad value originate? Keep tracing upstream until you find the source. Fix at source, not at symptom.
+
+### Phase 2: Pattern Analysis
+
+1. **Find working examples** of similar code in the same codebase
+2. **Read reference implementations COMPLETELY** — don't skim. The difference between working and broken is often subtle.
+3. **List every difference** between working and broken, however small
+4. **Understand dependency assumptions** — what does this code expect from its environment?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form a single, specific hypothesis:** "X is the root cause because Y"
+2. **Make the SMALLEST possible change** to test it. One variable at a time.
+3. **Did it work?** -> Phase 4. **Didn't work?** -> NEW hypothesis. Don't pile fixes on top of failed fixes.
+
+### Phase 4: Fix Implementation
+
+1. **Write a failing test** that reproduces the bug (use `raid-tdd`)
+2. **Implement single fix** addressing root cause
+3. **Verify** — test passes, no regressions (run test command from `.claude/raid.json`)
+4. **Cross-testing** by challengers — does the fix introduce new issues?
+
+## Raid-Specific: Competing Hypotheses
+
+The Wizard dispatches all agents with different hypotheses. After dispatch, agents debate directly:
+
+**📡 DISPATCH:**
+> **@Warrior**: Investigate [structural/data cause]. Reproduce. Trace data flow. Gather evidence at boundaries.
+> **@Archer**: Investigate [integration/contract cause]. Check interfaces, type mismatches, implicit contracts, dependency versions.
+> **@Rogue**: Investigate [timing/state/adversarial cause]. Race conditions, stale state, environment assumptions, concurrent access.
+>
+> **All**: Investigate independently, then debate directly. Challenge each other's hypotheses with evidence. Build on each other's findings. Pin verified evidence to the Dungeon. The hypothesis that survives cross-testing wins. Escalate to me with `🆘 WIZARD:` only if stuck.
+
+**How agents debate root cause:**
+- `⚔️ CHALLENGE: @Rogue, your race condition hypothesis doesn't explain why it fails on single-threaded test runs — evidence: [test output]`
+- `🔗 BUILDING ON @Warrior: Your data flow trace reveals the value originates from the config loader, not the API call — here's the upstream path: ...`
+- `📌 DUNGEON: Root cause evidence — config loader at config.js:47 returns stale cache when called concurrently [verified by @Archer and @Warrior]`
+
+The hypothesis that survives direct cross-testing gets the Wizard's ruling:
+
+⚡ WIZARD RULING: Root cause is [X] because [evidence from Dungeon].
+
+## Root Cause Tracing
+
+When tracing a bad value upstream:
+
+```
+1. Start at the symptom (where the bug manifests)
+2. Find where the bad value is used
+3. Find where it was set
+4. Is THIS the source? Or was it passed from somewhere else?
+5. If passed: go to the caller. Repeat from step 2.
+6. When you find where the value ORIGINATES incorrectly: that's the root cause.
+7. Fix at the source. Add validation at boundaries for defense-in-depth.
+```
+
+## 3+ Fixes Failed? Question Architecture
+
+If 3 or more fix attempts fail, **STOP fixing and question architecture:**
+
+- Each fix revealing a new problem in a different place = architectural issue, not implementation bug
+- All three agents discuss fundamentals
+- Wizard decides: fix architecture or escalate to human with evidence
+
+This is not failure — it's the system working. Detecting architectural problems before sinking more time into symptom fixes.
+
+## Defense in Depth
+
+After finding and fixing the root cause, add validation at multiple layers:
+
+1. **Entry point** — validate at the boundary where bad data enters
+2. **Business logic** — assert preconditions at the function that broke
+3. **Environment guards** — check assumptions about dependencies/state
+4. **Debug instrumentation** — add logging at key boundaries for future diagnosis
+
+## Red Flags — STOP and Follow Process
+
+| Thought | Reality |
+|---------|---------|
+| "Quick fix for now" | NO. Find root cause. Quick fixes become permanent. |
+| "Just try changing X" | NO. Hypothesize first. Random changes = random results. |
+| "I'm confident it's Y" | Confidence ≠ evidence. Verify before acting. |
+| "One more fix attempt" (after 2 failures) | STOP. Question architecture. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. Trace it. |
+| "The issue is simple, don't need process" | Simple issues have root causes too. Process is fast. |
+| "Emergency, no time" | Systematic debugging is FASTER than thrashing. Always. |
+| "Just try this first" | The first fix sets the pattern. Do it right. |
+
+## Escalation
+
+| Situation | Action |
+|-----------|--------|
+| Can't reproduce | Gather more data. Instrument boundaries. Don't guess. |
+| Root cause identified but fix is risky | Present to human with evidence and risk assessment. |
+| 3+ fixes failed | Architectural discussion. Don't force through. |
+| Bug is in a dependency | Document, workaround, and report upstream. |