claude-raid 0.1.7 → 0.2.1

package/template/.claude/skills/raid-wrap-up/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: raid-wrap-up
+description: "Phase 6 of Canonical Quest. Generates quest storyboard report, creates PR, archives dungeon to vault, dismisses party. No new code."
+---
+
+# Raid Wrap Up — Phase 6
+
+The quest ends. The bard sings the tale. The treasure is committed. The party rests.
+
+<HARD-GATE>
+Do NOT write new code. This phase is about reporting, cleanup, PR creation, and archival. Agents are dismissed, not dispatched.
+</HARD-GATE>
+
+## Mode Behavior
+
+- **Full Raid**: Wizard writes full storyboard from all phase files. Full PR with narrative.
+- **Skirmish**: Wizard writes condensed storyboard. Standard PR.
+- **Scout**: Wizard writes brief summary. Quick PR.
+
+## Process Flow
+
+```dot
+digraph wrapup {
+  "Wizard updates phase to wrap-up" -> "Create phase-6-wrap-up.md";
+  "Create phase-6-wrap-up.md" -> "Write phase-by-phase storyboard";
+  "Write phase-by-phase storyboard" -> "Cleanup temp files";
+  "Cleanup temp files" -> "Verify all tests pass (fresh run)";
+  "Verify all tests pass (fresh run)" -> "Tests pass?" [shape=diamond];
+  "Tests pass?" -> "Fix first. Do not proceed." [label="no"];
+  "Fix first. Do not proceed." -> "Verify all tests pass (fresh run)";
+  "Tests pass?" -> "Present merge options" [label="yes"];
+  "Present merge options" -> "Human chooses";
+  "Human chooses" -> "Execute choice";
+  "Execute choice" -> "Dismiss party";
+  "Dismiss party" -> "Archive to vault";
+  "Archive to vault" -> "Final commit + cleanup" [shape=doublecircle];
+}
+```
+
+## Wizard Checklist
+
+1. **Update raid-session** — set phase to `"wrap-up"`
+2. **Create storyboard** — `{questDir}/phase-6-wrap-up.md`
+3. **Write narrative** — phase-by-phase story from quest files
+4. **Cleanup** — remove temp configs, debug files, stale artifacts
+5. **Verify tests** — fresh full run, must pass
+6. **Present options** — 4 merge choices
+7. **Execute choice** — merge, PR, keep, or discard
+8. **Dismiss party** — RPG flavor shutdown
+9. **Archive** — move dungeon to vault
+10. **Final commit** — `docs(quest-{slug}): phase 6 wrap-up — quest complete`
+11. **Session cleanup** — remove `.claude/raid-session`
+
+## Step 1: The Quest Storyboard
+
+Create `{questDir}/phase-6-wrap-up.md` and write a phase-by-phase narrative:
+
+```markdown
+# Phase 6: Wrap Up — Quest Storyboard
+## Quest: <quest name>
+## Mode: <mode>
+
+### Phase 1: PRD — Forging the Scroll
+(if phase-1-prd.md exists)
+- What requirements were established
+- Key decisions from research
+
+### Phase 2: Design — Charting the Map
+- Architecture chosen and why
+- Key trade-offs resolved
+- Alternatives considered and rejected
+
+### Phase 3: Implementation Plan — Marshaling the Forces
+- Number of tasks, dependency structure
+- Risk areas identified
+
+### Phase 4: Implementation — Into the Fray
+- What was built
+- Challenges overcome
+- Test coverage highlights
+
+### Phase 5: Review — Inspecting the Treasure
+(if phase-5-review.md exists)
+- Findings pinned and resolved
+- Black cards (if any)
+- Fixes applied
+
+### Summary
+- Total phases completed
+- Key achievements
+- Known limitations
+```
+
+Read all prior phase files from the quest directory to build this narrative.
+
+## Step 2: Cleanup
+
+Remove temporary artifacts:
+- Debug files
+- Temp configs
+- Stale backups in the quest directory
+
+## Step 3: Final Verification
+
+```
+1. IDENTIFY: test command from .claude/raid.json
+2. RUN: Execute the FULL test suite (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Zero failures?
+   If NO → STOP. Fix first. Do not present options.
+   If YES → Proceed with evidence.
+```
+
+## Step 4: Present Options
+
+```
+RULING: The quest is complete and verified.
+
+Tests: [N] passing, 0 failures (evidence: [command output])
+
+Options:
+1. Merge back to [base-branch] locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (handle later)
+4. Discard this work
+
+Which option?
+```
+
+**For option 2 (PR):** Create the PR with:
+- **Title**: Descriptive, includes quest name
+- **Body**: The phase-by-phase storyboard from the wrap-up doc
+
+## Step 5: Execute
+
+| Option | Actions |
+|--------|---------|
+| **1. Merge** | Checkout base -> pull -> merge -> run tests on merged result -> delete branch -> clean up |
+| **2. PR** | Push with -u -> create PR via gh with storyboard body -> clean up |
+| **3. Keep** | Report branch location. Done. |
+| **4. Discard** | Require typed "discard" confirmation -> delete branch (force) -> clean up |
+
+## Step 6: Dismiss the Party
+
+Send shutdown to all teammates with RPG flavor:
+
+> "The quest is done, brave engineers. The bards will sing of **{quest-name}**. Sheathe your tools — until the next adventure."
+
+```
+SendMessage(to="warrior", message={"type": "shutdown_request"})
+SendMessage(to="archer", message={"type": "shutdown_request"})
+SendMessage(to="rogue", message={"type": "shutdown_request"})
+```
+
+## Step 7: Archive to Vault
+
+1. Move quest directory to vault:
+   ```
+   mv .claude/dungeon/{quest-slug}/ .claude/vault/{quest-slug}/
+   ```
+2. Update vault index at `.claude/vault/index.md`:
+   ```
+   | {date} | [{quest-name}]({quest-slug}/quest.md) | {mode} | {tags} |
+   ```
+
+## Step 8: Final Commit & Cleanup
+
+1. **Commit**: `docs(quest-{slug}): phase 6 wrap-up — quest complete`
+2. **Remove**: `.claude/raid-session`
+3. **Session is over. No further skills to load.**
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "Tests passed earlier, no need to re-run" | Fresh run or no claim. Always. |
+| "Skip the storyboard, just make the PR" | The storyboard IS the PR body. It documents the journey. |
+| "Leave the dungeon files, they might be useful" | Archive to vault. Session artifacts don't belong in the repo. |
+| "Merge without testing the merged result" | Merges introduce conflicts. Test after merge. |
+| "I'll write the code fix myself" | You are the Wizard. Dispatch the fix to an agent. |
+
+## Phase Spoils
+
+**Output**: `{questDir}/phase-6-wrap-up.md` — The complete quest narrative, phase by phase.

package/template/.claude/hooks/raid-stop.sh

@@ -1,20 +0,0 @@
-#!/usr/bin/env bash
-# Raid lifecycle hook: Stop
-# Detects phase transitions and injects human confirmation gate.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/raid-lib.sh"
-
-if [ "$RAID_ACTIVE" != "true" ]; then
-  exit 0
-fi
-
-if [ "$RAID_LIFECYCLE_PHASE_CONFIRM" != "true" ]; then
-  exit 0
-fi
-
-# Phase transitions are managed by the Wizard via raid_session_set().
-# No automatic detection needed — the Wizard explicitly updates the session.
-
-exit 0

package/template/.claude/hooks/raid-task-completed.sh

@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-# Raid lifecycle hook: TaskCompleted
-# Blocks task completion if tests haven't run recently.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/raid-lib.sh"
-
-if [ "$RAID_ACTIVE" != "true" ]; then
-  exit 0
-fi
-
-if [ "$RAID_LIFECYCLE_COMPLETION_GATE" != "true" ]; then
-  exit 0
-fi
-
-# Design and plan phases have no code to test — skip test-run requirement
-case "${RAID_PHASE:-}" in
-  design|plan) exit 0 ;;
-esac
-
-TEST_RUN_FILE=".claude/raid-last-test-run"
-
-if [ ! -f "$TEST_RUN_FILE" ]; then
-  raid_block "Tests must pass before marking a task complete. No test run recorded — run your test command first."
-fi
-
-LAST_RUN=$(cat "$TEST_RUN_FILE" 2>/dev/null | tr -d '[:space:]')
-NOW=$(date +%s)
-WINDOW=$((RAID_LIFECYCLE_TEST_WINDOW * 60))
-# Guard against corrupted/non-numeric timestamp
-case "$LAST_RUN" in
-  ''|*[!0-9]*) raid_block "Tests must pass before marking a task complete. Test run timestamp is invalid — run your test command first." ;;
-esac
-AGE=$((NOW - LAST_RUN))
-
-if [ "$AGE" -gt "$WINDOW" ]; then
-  MINS_AGO=$((AGE / 60))
-  raid_block "Tests last ran $MINS_AGO minutes ago (window is $RAID_LIFECYCLE_TEST_WINDOW min). Run tests again before marking this task complete."
-fi
-
-exit 0

package/template/.claude/hooks/validate-bash-writes.sh

@@ -1,157 +0,0 @@
-#!/usr/bin/env bash
-# Raid Bash write-gate: intercepts file-writing Bash commands
-# PreToolUse hook for Bash operations — defense-in-depth layer.
-# Detects: redirects (> >>), tee, sed -i, cp, mv, curl -o,
-# and scripting language writes (python3/node/ruby/perl).
-# Protects .claude/raid-session and .claude/raid-last-test-run from all Bash writes.
-set -euo pipefail
-
-HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$HOOK_DIR/raid-lib.sh"
-
-raid_read_input
-
-# No command — nothing to gate
-if [ -z "${RAID_COMMAND:-}" ]; then
-  exit 0
-fi
-
-# No active session — allow everything
-if [ "$RAID_ACTIVE" = "false" ]; then
-  exit 0
-fi
-
-# --- Extract target file paths from known write patterns ---
-
-# Collects candidate target paths from the command string.
-# This is regex heuristics on a Bash command — it catches the 90% case,
-# not arbitrary scripting. Defense in depth, not a security boundary.
-_targets=()
-
-_cmd="$RAID_COMMAND"
-
-# Pattern 1: Redirects — command > file, command >> file
-# Matches: > path, >> path (with optional whitespace)
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE '>{1,2}\s*[^ |;&)]+' | sed 's/^>*[[:space:]]*//')
-
-# Pattern 2: tee [-a] file [file...]
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE 'tee\s+(-a\s+)?[^ |;&)]+' | sed 's/^tee\s\+\(-a\s\+\)\?//' | sed 's/^tee[[:space:]]*\(-a[[:space:]]*\)\{0,1\}//')
-
-# Pattern 3: sed -i[suffix] 's/.../.../g' file
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE "sed\s+-i[^ ]*\s+'[^']*'\s+[^ |;&)]+" | rev | cut -d' ' -f1 | rev)
-
-# Pattern 4: cp source target (last arg is target)
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE 'cp\s+(-[a-zA-Z]+\s+)*[^ |;&)]+\s+[^ |;&)]+' | rev | cut -d' ' -f1 | rev)
-
-# Pattern 5: mv source target (last arg is target)
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE 'mv\s+(-[a-zA-Z]+\s+)*[^ |;&)]+\s+[^ |;&)]+' | rev | cut -d' ' -f1 | rev)
-
-# Pattern 6: curl -o file / curl --output file
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE 'curl\s+.*-o\s+[^ |;&)]+' | grep -oE '\-o\s+[^ |;&)]+' | sed 's/^-o[[:space:]]*//')
-
-# Pattern 7: Scripting language inline writes — extract quoted paths
-# python3 -c "open('path', 'w')..."
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE "python3?\s+-c\s+['\"].*['\"]" | grep -oE "open\(['\"][^'\"]+['\"]" | sed "s/^open(['\"]//;s/['\"]$//")
-
-# node -e "fs.writeFileSync('path', ...)"
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE "node\s+-e\s+['\"].*['\"]" | grep -oE "writeFileSync\(['\"][^'\"]+['\"]" | sed "s/^writeFileSync(['\"]//;s/['\"]$//")
-
-# ruby -e "File.write('path', ...)"
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE "ruby\s+-e\s+['\"].*['\"]" | grep -oE "File\.write\(['\"][^'\"]+['\"]" | sed "s/^File\.write(['\"]//;s/['\"]$//")
-
-# perl -e 'open(F,">path")...'
-while IFS= read -r _match; do
-  [ -n "$_match" ] && _targets+=("$_match")
-done < <(echo "$_cmd" | grep -oE "perl\s+-e\s+['\"].*['\"]" | grep -oE '>[^"'\'']+['\''"]' | sed "s/^>//;s/['\"]$//")
-
-# No write targets detected — allow
-if [ ${#_targets[@]} -eq 0 ]; then
-  exit 0
-fi
-
-# --- Check each target ---
-
-for _target in "${_targets[@]}"; do
-  # Normalize path: resolve .., //, and strip absolute prefix
-  _norm="$_target"
-  # Convert to absolute for uniform handling
-  if [[ "$_norm" != /* ]]; then
-    _norm="$PWD/$_norm"
-  fi
-  # Collapse // and resolve /dir/../ components (portable — no GNU sed labels)
-  _norm=$(echo "$_norm" | sed 's|//\{1,\}|/|g' | while read -r _p; do
-    # Iteratively resolve ../ until none remain
-    while echo "$_p" | grep -q '/[^/][^/]*/\.\./'; do
-      _p=$(echo "$_p" | sed 's|/[^/][^/]*/\.\./|/|')
-    done
-    echo "$_p"
-  done)
-  # Strip PWD prefix to get relative path
-  _norm="${_norm#"$PWD"/}"
-
-  # Check 1: Protected files — always blocked during active session
-  case "$_norm" in
-    .claude/raid-session|.claude/raid-last-test-run)
-      raid_block "File '${_norm}' is protected. It is managed by hooks and the Wizard."
-      ;;
-  esac
-
-  # Check 2: Non-production files — always allowed
-  if ! raid_is_production_file "$_norm"; then
-    continue
-  fi
-
-  # Check 3: Phase-based enforcement on production files
-  case "${RAID_PHASE:-}" in
-    design)
-      raid_block "Bash write to production file '${_norm}' blocked. Read-only phase (design)."
-      ;;
-    plan)
-      raid_block "Bash write to production file '${_norm}' blocked. Read-only phase (plan)."
-      ;;
-    implementation)
-      # Scout mode: skip implementer check
-      if [ "$RAID_MODE" = "scout" ]; then
-        continue
-      fi
-      # Only the designated implementer may write production code via Bash
-      if [ -n "$RAID_IMPLEMENTER" ] && [ "$RAID_CURRENT_AGENT" != "$RAID_IMPLEMENTER" ]; then
-        raid_block "Bash write to production file '${_norm}' blocked. Only ${RAID_IMPLEMENTER} writes production code this task."
-      fi
-      continue
-      ;;
-    review)
-      raid_block "Bash write to production file '${_norm}' blocked. Read-only phase (review)."
-      ;;
-    finishing)
-      raid_block "Bash write to production file '${_norm}' blocked. Finishing phase."
-      ;;
-    "")
-      # Bootstrap — allow with warning (consistent with write-gate)
-      raid_warn "Session active but phase is empty — allowing Bash writes during bootstrap."
-      ;;
-    *)
-      raid_block "Bash write to production file '${_norm}' blocked. Unknown phase '${RAID_PHASE}'."
-      ;;
-  esac
-done
-
-exit 0

package/template/.claude/skills/raid-browser-playwright/SKILL.md

@@ -1,163 +0,0 @@
----
-name: raid-browser-playwright
-description: "Playwright MCP automated browser test authoring. Extends TDD RED-GREEN-REFACTOR with .spec.ts files. Console + network assertions mandatory. Invoked from raid-tdd and raid-implementation during Phase 3."
----
-
-# Raid Browser Playwright — Automated Test Authoring
-
-Write browser tests as part of TDD. Use Playwright MCP to explore, then encode verified interactions into durable `.spec.ts` files.
-
-<HARD-GATE>
-Do NOT write browser tests without invoking `raid-browser` pre-flight first. Do NOT skip console/network assertions. Do NOT write tests without watching them fail first (TDD RED step). No subagents.
-</HARD-GATE>
-
-## When to Write Browser Tests vs Unit Tests
-
-Not every task needs a browser test. The implementer decides and states reasoning. Challengers attack this decision.
-
-| Write Browser Test | Write Unit Test Only |
-|---|---|
-| New user-facing flow (signup, checkout) | Pure utility function |
-| UI interaction (drag-drop, modal, form) | API endpoint logic |
-| Client-side routing / navigation | Data transformation |
-| Visual state changes (loading, error, empty) | Business rule validation |
-| Integration between frontend and API | Database queries |
-
-**If unsure:** Write the browser test. It's easier to remove an unnecessary test than to find a bug in production.
-
-## Browser TDD Cycle
-
-### RED (browser)
-
-1. Write Playwright test file: `tests/e2e/<feature>.spec.ts`
-2. Test describes **user behavior**, not implementation:
-   - Navigate to page
-   - Interact (click, type, select, drag)
-   - Assert visible outcome (text appears, redirect happens, element state changes)
-3. Include mandatory infrastructure assertions (see below)
-4. Run test → **MUST fail**
-5. Verify it fails for the **RIGHT reason** (page/element missing — not test syntax error)
-
-### GREEN (browser)
-
-1. Implement the feature code
-2. Run Playwright test → **MUST pass**
-3. Run full test suite (unit + browser) → all green
-
-### REFACTOR
-
-1. Clean up implementation and test code
-2. Re-run all tests → still green
-
-## Using Playwright MCP During Test Authoring
-
-While writing the test, the implementer explores interactively to understand the current state and find correct selectors:
-
-| Tool | Purpose |
-|---|---|
-| `browser_navigate` | Load the page, see what's there |
-| `browser_snapshot` | Get DOM state, find correct selectors |
-| `browser_click` / `browser_fill_form` | Test interactions manually first |
-| `browser_console_messages` | Check for errors during interaction |
-| `browser_network_requests` | Verify API calls, check payloads |
-| `browser_take_screenshot` | Capture visual state for evidence |
-
-**The MCP tools are the exploratory scratchpad. The `.spec.ts` file is the durable artifact.**
-
-Encode what you verified interactively into the test file. The test must run headlessly in CI without MCP tools.
-
-## Mandatory Assertions
-
-Every browser test file MUST include at least:
-
-### 1. Console-Clean Assertion
-
-```typescript
-test('no console errors during <feature> flow', async ({ page }) => {
-  const errors: string[] = [];
-  page.on('console', msg => {
-    if (msg.type() === 'error') errors.push(msg.text());
-  });
-
-  // ... perform the feature flow ...
-
-  expect(errors).toEqual([]);
-});
-```
-
-### 2. Network-Health Assertion
-
-```typescript
-test('API calls succeed during <feature> flow', async ({ page }) => {
-  const failures: string[] = [];
-  page.on('response', response => {
-    if (response.status() >= 400) {
-      failures.push(`${response.status()} ${response.url()}`);
-    }
-  });
-
-  // ... perform the feature flow ...
-
-  expect(failures).toEqual([]);
-});
-```
-
-**Missing either of these is an automatic challenge from any reviewer.**
-
-## Selector Best Practices
-
-| Prefer | Avoid | Why |
-|---|---|---|
-| `data-testid="submit-btn"` | `button.btn-primary` | CSS classes change for styling reasons |
-| `getByRole('button', { name: 'Submit' })` | `#submit` | Accessible and resilient |
-| `getByText('Welcome back')` | `.header > div:nth-child(2)` | Structural selectors break on layout changes |
-
-## Challenger Attacks on Browser Tests (Phase 3)
-
-**Warrior attacks:**
-- "You only tested the happy path — what happens with network failure?"
-- "No test for rapid double-submit on the form"
-- "What about a 10,000-character input in the name field?"
-- "You didn't test with JavaScript disabled / slow network"
-
-**Archer attacks:**
-- "Your selector `button[type=submit]` is fragile — use `data-testid`"
-- "No assertion on console errors — the feature works but throws warnings"
-- "Missing network assertion — you don't verify the POST payload"
-- "Tested at desktop width only — what about mobile viewport?"
-
-**Rogue attacks:**
-- "What happens if the user is already logged in and hits /register?"
-- "No test for XSS in the input fields"
-- "What if the API returns 200 but with an error body?"
-- "Race condition: what if the user navigates away during submission?"
-
-**Each challenger BOOTS their own app instance** (on their own port via `raid-browser`), runs the tests independently, and verifies they pass without flakiness.
-
-## Running Browser Tests
-
-Use the test command from `.claude/raid.json`:
-- Read `project.execCommand` (e.g., `pnpm dlx`, `npx`, `bunx`)
-- Run: `{execCommand} playwright test`
-- For a specific test: `{execCommand} playwright test tests/e2e/<feature>.spec.ts`
-
-## Test File Organization
-
-```
-tests/
-  e2e/
-    <feature-name>.spec.ts       # One file per feature/flow
-    auth/
-      login.spec.ts              # Group related flows in directories
-      registration.spec.ts
-```
-
-## Red Flags
-
-| Thought | Reality |
-|---------|---------|
-| "The feature is too simple for a browser test" | Simple features break in the browser. If it's user-facing, test it. |
-| "I'll add console assertions later" | Later never comes. Add them now. |
-| "The unit tests cover this" | Unit tests don't catch hydration mismatches, missing CSS, broken routing. |
-| "I tested it manually with MCP tools" | Manual verification isn't reproducible. Write the `.spec.ts`. |
-| "Selectors are fine, they work" | They work today. Will they work after a CSS refactor? Use `data-testid`. |