claude-raid 0.2.6 → 0.2.8

package/template/.claude/skills/raid-canonical-implementation/SKILL.md

@@ -1,101 +1,93 @@
 ---
 name: raid-canonical-implementation
-description: "Phase 4 of Canonical Quest. Wizard assigns tasks to agents in batches (round-based). Agents build with TDD. Cross-testing after each task. Wizard orchestrates and closes when all tasks complete."
+description: "Use when Phase 4 (Implementation) begins in a Canonical Quest, after the plan is approved and committed."
 ---
 
 # Raid Implementation — Phase 4
 
-One builds, two attack — and the attackers attack each other's reviews too. Every implementation earns its approval through direct adversarial pressure.
+Execute the plan. The Wizard assigns tasks strategically by domain affinity — no dice, no challengers. Agents implement with TDD, report, and move to the next task. Cross-review happens in Phase 5.
 
 <HARD-GATE>
-Do NOT implement without an approved plan (except Scout mode). Do NOT skip TDD. Do NOT let any implementation pass unchallenged. Agents communicate via SendMessage — do not spawn subagents. Use `raid-tdd` skill for all test-driven development. Use `raid-verification` before any completion claims.
+Do NOT implement without an approved plan. Do NOT skip TDD — it is an Iron Law. Use `raid-tdd` skill for all test-driven development. Use `raid-verification` before any completion claims.
 </HARD-GATE>
 
-## Mode Behavior
-
-- **Full Raid**: 1 implements, 2 challenge (and challenge each other's reviews). Rotate implementer.
-- **Skirmish**: 1 implements, 1 challenges. Swap roles each task.
-- **Scout**: 1 agent implements. Wizard reviews. Self-challenge ruthlessly.
-
-TDD is enforced in ALL modes. This is an Iron Law.
-
 ## Process Flow
 
 ```dot
 digraph implementation {
-  "Wizard reads plan + Phase 3 plan docs" -> "Create task tracking (TaskCreate)";
-  "Create task tracking (TaskCreate)" -> "Wizard assigns task N (rotate implementer)";
-  "Wizard assigns task N (rotate implementer)" -> "Wizard opens task Dungeon";
-  "Wizard opens task Dungeon" -> "Implementer executes (TDD)";
-  "Implementer executes (TDD)" -> "Implementer reports status";
-  "Implementer reports status" -> "Status?" [shape=diamond];
-  "Status?" -> "Challengers attack directly" [label="DONE"];
-  "Status?" -> "Read concerns, decide" [label="DONE_WITH_CONCERNS"];
-  "Status?" -> "Provide context, re-dispatch" [label="NEEDS_CONTEXT"];
-  "Status?" -> "Assess blocker" [label="BLOCKED"];
-  "Read concerns, decide" -> "Challengers attack directly";
-  "Provide context, re-dispatch" -> "Implementer executes (TDD)";
-  "Assess blocker" -> "Break down task / escalate";
-  "Challengers attack directly" -> "Challengers build on each other's critiques";
-  "Challengers build on each other's critiques" -> "Implementer defends against both";
-  "Implementer defends against both" -> "All issues resolved?" [shape=diamond];
-  "All issues resolved?" -> "Challengers attack directly" [label="no, continue"];
-  "All issues resolved?" -> "Wizard closes task: ruling" [label="yes"];
-  "Wizard closes task: ruling" -> "More tasks?" [shape=diamond];
-  "More tasks?" -> "Wizard assigns task N (rotate implementer)" [label="yes"];
-  "More tasks?" -> "Archive Dungeon + invoke raid-canonical-review" [label="no", shape=doublecircle];
+  "Wizard reads plan + all prior deliverables" -> "Phase recap (PRD + Design + Plan)";
+  "Phase recap (PRD + Design + Plan)" -> "Step 0: Agents review plan for concerns";
+  "Step 0: Agents review plan for concerns" -> "Wizard divides tasks by domain affinity";
+  "Wizard divides tasks by domain affinity" -> "Wizard assigns task to agent";
+  "Wizard assigns task to agent" -> "Agent implements (TDD)";
+  "Agent implements (TDD)" -> "Agent writes breakdown in task section";
+  "Agent writes breakdown in task section" -> "Agent flags TURN_COMPLETE";
+  "Agent flags TURN_COMPLETE" -> "Wizard assigns next task" -> "More tasks?" [shape=diamond];
+  "More tasks?" -> "Wizard assigns task to agent" [label="yes"];
+  "More tasks?" -> "Wizard produces summary table" [label="no"];
+  "Wizard produces summary table" -> "Commit + report with deliverable link";
+  "Commit + report with deliverable link" -> "Ask human: Review or Wrap-up?" [shape=doublecircle];
 }
 ```
 
-## Step 0: Critical Plan Review (before any implementation)
+## Step 0: Critical Plan Review
 
-Each agent MUST review the plan independently before implementing:
+Before any implementation begins, each agent reviews the plan independently:
 - Are there concerns about feasibility or missing dependencies?
 - Are any steps unclear or ambiguous?
 - Does the plan match the design doc?
-- Are the TDD steps complete with actual test code?
 
-If concerns: raise via `WIZARD:` before starting. Fix the plan first. Never force through a flawed plan.
+If concerns: raise via `WIZARD:` before starting. Fix the plan first. For minor issues, the wizard fixes the plan inline and gets human approval before implementation begins. For fundamental plan flaws, return to Phase 3.
 
 **Branch guard:** Never implement on main/master without explicit human consent. Create a feature branch first.
 
 ## Wizard Checklist
 
-1. **Read the plan** — extract all tasks, dependencies, ordering
-2. **Read Phase 3 plan docs** — carry forward context from `{questDir}/phase-3-plan.md` and task files
-3. **Dispatch plan review** — each agent reviews plan independently, raises concerns via WIZARD:
+1. **Read the plan** — extract all tasks, dependencies, ordering from task files
+2. **Phase recap** — summarize PRD + Design + Plan findings. Present what carries forward.
+3. **Dispatch plan review** — each agent reviews the plan, raises concerns via `WIZARD:`
 4. **Resolve concerns** — fix plan issues before any implementation begins
-4. **Browser setup (if `browser.enabled` in raid.json)**:
+5. **Browser setup (if `browser.enabled` in raid.json)**:
    - Check if `browser.startup` exists — if null, invoke `raid-browser` startup discovery FIRST
    - Check if Playwright is installed — if not, first task becomes "scaffold Playwright"
-   - Assign port from `browser.portRange` to implementer
-5. **Create task tracking** — use TaskCreate for every plan task
-6. **Per task:**
-   - Assign implementer via `TaskUpdate(taskId="N", owner="warrior")`
-   - Notify via `SendMessage(to="warrior", message="Task N is yours. TDD enforced.")`
-   - Alert challengers: `SendMessage(to="archer", message="Warrior implementing Task N. Stand by to challenge.")`
-   - Observe messages (auto-delivered) + Dungeon updates
-   - Close with ruling via SendMessage to all agents
-7. **Track progress** — mark complete only after Wizard ruling per task
-8. **After all tasks** — archive Dungeon, invoke `raid-canonical-review`
+6. **Divide tasks strategically** — see Task Division below
+7. **Create task tracking** — use TaskCreate for every plan task
+8. **Dispatch tasks one at a time** — see Dispatch Protocol below
+9. **After all tasks complete** — review the evolution log, verify all task reports are filled, fill the Implementation Summary table, polish before presenting to human
+10. **Commit** — `feat(quest-{slug}): phase 4 implementation — {summary}`
+11. **Report** — link `{questDir}/phases/phase-4-implementation.md` to the human
+12. **Ask human** — Review phase or straight to Wrap-up?
+
+## Task Division — Strategic Assignment
+
+The Wizard assigns tasks deliberately. No dice roll, no rotation — strategic domain-based assignment:
+
+- **Group by affinity:** Tasks that touch the same files or domain go to the same agent. This gives the agent continuity and deeper context across related changes.
+- **Match lens to domain:** Wizard considers which agent's lens fits the task best. Infrastructure-heavy tasks suit Warrior's structural lens. Pattern-sensitive integrations suit Archer. Security/validation tasks suit Rogue.
+- **Track dependencies:** Know which tasks block which. If task 10 depends on task 3 (currently being implemented by @warrior), don't assign task 10 to @archer yet — give them a non-blocked task instead, or have them wait.
 
-## The Implementation Gauntlet (per task)
+**Example reasoning:**
+> *"Tasks 1-3 all modify the auth module — assigning to @warrior for context continuity. Tasks 4-5 are integration points that need pattern consistency — @archer. Tasks 6-7 involve input validation and error paths — @rogue. Task 8 depends on tasks 1-3, so it waits until @warrior finishes those."*
 
-### Step 1: Wizard Assigns + Opens Dungeon
+## Dispatch Template
 
-One agent implements. Others prepare to attack. **Rotate the implementer** across tasks.
+One agent at a time. Dispatch carries task assignment and file pointers. TDD protocol comes from the agent's `raid-tdd` skill. Report instructions are embedded in the evolution log.
 
-Assign via task list and notify via SendMessage:
 ```
-TaskUpdate(taskId="N", owner="warrior")
-SendMessage(to="warrior", message="Task N is yours. TDD enforced. Commit when green. Report status when done.")
-SendMessage(to="archer", message="Warrior is implementing Task N. Challenge when they report done.")
-SendMessage(to="rogue", message="Warrior is implementing Task N. Challenge when they report done.")
+TURN_DISPATCH: Task {N} — {task name}.
+Quest: {description}
+
+FIRST: Read the FULL document at {questDir}/phases/phase-4-implementation.md to understand
+  the structure and find your task section. Read the embedded instructions in your section.
+  Then read your task spec at {questDir}/spoils/tasks/phase-3-plan-task-{NN}.md.
+THEN: Implement with TDD (load raid-tdd), fill your report in your section,
+  and fill Implementation Notes in the task file.
+Signal TURN_COMPLETE with status when done.
 ```
 
-Phase 4 uses `{questDir}/phase-4-implementation.md` as the implementation log. The Wizard announces each task assignment via SendMessage. Agents flag `ROUND_COMPLETE:` when done with their task.
+After `TURN_COMPLETE:`, the Wizard reads the report, then assigns the next task.
 
-### Step 2: Implementer Executes (TDD)
+## Agent Implementation Protocol (TDD)
 
 Following `raid-tdd` strictly:
 1. Write the failing test from the plan
@@ -104,79 +96,112 @@ Following `raid-tdd` strictly:
 4. Run — verify pass
 5. Run FULL test suite — verify no regressions
 6. Self-review against acceptance criteria
-7. Commit: `feat(scope): descriptive message`
+7. Write brief implementation breakdown in the task's "Implementation Notes" section
+8. Commit: `feat(scope): descriptive message`
 
 **Browser tasks (if `browser.enabled` and task involves browser-facing code):**
 - BOOT app on assigned port before browser TDD (invoke `raid-browser`)
-- Use Playwright MCP tools to explore while authoring tests
-- CLEANUP after task is complete (or on failure — cleanup always runs)
+- Use Playwright MCP tools while authoring tests
+- CLEANUP after task is complete (or on failure)
 
-Report status: **DONE** | **DONE_WITH_CONCERNS** | **NEEDS_CONTEXT** | **BLOCKED**
+Signal `TURN_COMPLETE:` with status: **DONE** | **DONE_WITH_CONCERNS** | **NEEDS_CONTEXT** | **BLOCKED**
 
-### Step 3: Challengers Attack Directly
+## Handling Agent Status
 
-Challengers work in their own tmux panes. They communicate directly with the implementer and each other via SendMessage:
+| Status | Action |
+|--------|--------|
+| **DONE** | Wizard reads breakdown, assigns next task |
+| **DONE_WITH_CONCERNS** | Read concerns. If correctness: address before next task. If observations: note and proceed. |
+| **NEEDS_CONTEXT** | Provide missing information. Re-dispatch same task. |
+| **BLOCKED** | 1) Context → provide more. 2) Too complex → break into subtasks. 3) Plan wrong → fix plan. |
 
-1. **Read ACTUAL CODE** (not the implementer's report — reports lie)
-2. **Challenge the implementer directly:** `CHALLENGE: @Warrior, your implementation at handler.js:23 doesn't validate...`
-3. **Build on each other's critiques:** `BUILDING: @Archer, your naming drift finding — the inconsistency also affects the test at...`
-4. **Challenge weak implementations:** `CHALLENGE: @Rogue, you claimed this handles concurrent access but there's no lock at...`
-5. **Pin verified issues to Dungeon:** `DUNGEON: Confirmed issue — handler.js:23 missing validation [verified by @Archer and @Rogue]`
+## When to STOP Executing
 
-**Browser verification (if `browser.enabled`):**
-- Challengers can BOOT on their own ports to run Playwright tests independently
-- Verify tests pass without flakiness (run 3x if suspect)
-- Explore the feature manually via Playwright MCP to find gaps the tests missed
-- Each challenger CLEANUPS their own instance when done
+STOP implementing immediately when:
+- Missing dependency not covered in plan
+- Test fails for unexpected reason (not the expected "right" failure)
+- Instruction is ambiguous — two valid interpretations exist
+- Verification fails repeatedly (2+ times on same step)
+- Implementation diverges significantly from plan
 
-**Challengers check:**
-- Spec compliance — does it match the task spec line by line?
-- Design doc compliance — does it match the design requirements?
-- Edge cases — what inputs break it?
-- Test quality — do tests prove correctness or just confirm happy path?
-- Naming consistency — do new names follow established patterns?
-- File structure — does new code follow project conventions?
+**Ask via `WIZARD:` rather than guessing.** The Wizard escalates to the human if needed.
 
-### Step 4: Implementer Defends
+## Evolution Log Template
 
-The implementer defends against BOTH challengers simultaneously:
-- Respond to each challenge with evidence or concede immediately
-- Fix conceded issues
-- Re-run all tests
-- Pin resolved issues to Dungeon: `DUNGEON: Resolved — added validation at handler.js:23 [tests pass]`
+Scaffold `{questDir}/phases/phase-4-implementation.md`. Wizard pre-fills one task slot per plan task with the assigned agent's name:
 
-### Step 5: Wizard Closes Task
+```markdown
+# Phase 4: Implementation — Evolution Log
 
-Broadcast the ruling:
-```
-SendMessage(to="warrior", message="RULING: Task N [approved | needs fixes].")
-SendMessage(to="archer", message="RULING: Task N [approved | needs fixes].")
-SendMessage(to="rogue", message="RULING: Task N [approved | needs fixes].")
-```
+## Quest: [quest description]
+## Quest Type: Canonical Quest
 
-The Wizard closes when messages + Dungeon show all issues resolved and challengers have no remaining critiques.
+## References
+- PRD: `{questDir}/spoils/prd.md` (if exists)
+- Design: `{questDir}/spoils/design.md`
+- Tasks: `{questDir}/spoils/tasks/phase-3-plan-task-*.md`
 
-## Handling Implementer Status
+## Quest Goal
+<!-- Wizard writes 2-3 lines: what the implementation aims to deliver,
+     total task count, and the division strategy (which agent gets which domain) -->
 
-| Status | Action |
-|--------|--------|
-| **DONE** | Challengers attack directly |
-| **DONE_WITH_CONCERNS** | Read concerns. If correctness: address before attack. If observations: note and proceed. |
-| **NEEDS_CONTEXT** | Provide missing information. Re-dispatch. |
-| **BLOCKED** | 1) Context → provide more. 2) Too complex → break into subtasks. 3) Plan wrong → fix plan. |
+## Task Assignment
 
-**Never ignore an escalation.** If the implementer says it's stuck, something needs to change.
+<!-- Wizard fills this table after dividing tasks by domain affinity -->
 
-## When to STOP Executing
+| Task | Agent | Domain | Blocked By | Status |
+|------|-------|--------|------------|--------|
 
-STOP implementing immediately when:
-- Missing dependency not covered in plan
-- Test fails for unexpected reason (not the expected "right" failure)
-- Instruction is ambiguous — two valid interpretations exist
-- Verification fails repeatedly (2+ times on same step)
-- Implementation diverges significantly from plan
+---
+
+## Task Reports
+
+### Task 1: [Name] — @{assigned agent}
+
+<!-- @{agent}: After completing this task, fill in the sections below.
+     Sign your report. Be concise — this is a report, not a narrative.
+     Also fill the Implementation Notes section in the Phase 3 task file.
+     Update the Task Assignment table status to "complete" when done. -->
+
+**Status:** pending | in_progress | complete | blocked
+**Files Changed:**
+<!-- List every file created or modified, with action:
+     - `src/auth/handler.ts` (created)
+     - `src/middleware.ts` (modified L45-60) -->
+
+**Summary:**
+<!-- 1-3 sentences: what was built, key decisions made, test count.
+     Reference the task file for full spec. -->
+
+**Commit:** `feat(scope): message`
+
+**Deviations from Plan:**
+<!-- If you deviated from the task spec, explain WHAT and WHY.
+     If none: "None — implemented as specified." -->
 
-**Ask via `WIZARD:` rather than guessing.** Don't force through blockers — they indicate plan gaps, not agent weakness. The Wizard escalates to the human if needed.
+---
+
+<!-- Wizard pre-scaffolds one slot per task with the assigned agent's name -->
+
+---
+
+## Implementation Summary
+
+<!-- Wizard fills this after ALL tasks are complete.
+     This is the phase deliverable — a table of all changes. -->
+
+| File | Change | Why | Task | Agent |
+|------|--------|-----|------|-------|
+
+---
+
+## Writing Guidance
+- Sign all work: `@{name}`
+- Be concise — report what happened, not how you felt about it
+- Every deviation from plan must be explained
+- Update the Task Assignment table as you go
+- If blocked: flag WIZARD: immediately, don't wait
+```
 
 ## Quality Gates Per Task
 
@@ -184,28 +209,24 @@ STOP implementing immediately when:
 - [ ] Tests fail for the right reason
 - [ ] Tests pass after implementation
 - [ ] Full test suite passes (no regressions)
-- [ ] Challengers attacked ACTUAL CODE directly
-- [ ] Challengers built on each other's critiques
-- [ ] All challenges addressed (fixed or defended with evidence)
-- [ ] Implementation matches task spec (nothing more, nothing less)
+- [ ] Implementation matches task spec
 - [ ] Naming follows established patterns
-- [ ] Verified issues pinned to Dungeon
+- [ ] Implementation breakdown written in task section
 - [ ] Code committed with descriptive message
 
 ## Red Flags
 
 | Thought | Reality |
 |---------|---------|
-| "This task is simple, skip cross-testing" | Simple tasks are where assumptions slip through. |
-| "The challengers should report to the Wizard" | Challengers attack the implementer and each other directly. |
-| "We can batch the review for multiple tasks" | Review per task. Batching lets issues compound. |
-| "I trust this agent's work" | Trust without verification is the definition of a bug farm. |
-| "The same agent can implement twice in a row" | Rotation prevents blind spots. Enforce it. |
-| "I'll wait for the Wizard to coordinate the review" | Attack directly. Build on each other's findings. |
+| "This task is simple, skip TDD" | TDD is an Iron Law. No exceptions. |
+| "Let me review my teammate's code" | No cross-review during implementation. That's Phase 5. |
+| "I'll implement tasks in whatever order" | Wizard assigns strategically. Follow the assignment. |
+| "I'll batch commits across tasks" | One commit per task. Atomic changes. |
+| "The plan is wrong, I'll improvise" | Flag to Wizard via WIZARD:. Don't improvise. |
 
 ## Escalation
 
-- **3+ fix attempts on one task:** Question whether the task spec or design is wrong.
+- **3+ attempts on one task:** Question whether the task spec or design is wrong.
 - **Agent repeatedly blocked:** The plan may need revision.
 - **Tests can't be written:** The design may not be testable. Return to Phase 2.
 
@@ -213,13 +234,20 @@ STOP implementing immediately when:
 
 ## Phase Transition
 
-When all tasks are approved and committed:
+When all tasks are complete and committed:
+
+1. Update raid-session phase via Bash:
+   ```bash
+   jq '.phase="review"' .claude/raid-session > .claude/raid-session.tmp && mv .claude/raid-session.tmp .claude/raid-session
+   ```
+2. **Commit:** `feat(quest-{slug}): phase 4 implementation — {summary}`
+3. **Report:** Link `{questDir}/phases/phase-4-implementation.md` and summary table to the human.
+4. **Ask human:** "Shall we inspect the treasure? (Review phase) Or proceed directly to wrap-up?"
+5. If review → **Load `raid-canonical-review` and begin Phase 5**
+6. If skip → **Load `raid-wrap-up` and begin Phase 6**
 
-1. Update `.claude/raid-session` phase to `"review"`
-2. **Commit**: `feat(quest-{slug}): phase 4 implementation — {summary}`
-3. **Send phase report to human**: what was built, test coverage, any concerns
-4. **Ask human**: "Shall we inspect the treasure? (Review phase) Or proceed directly to wrap-up?"
-5. If review → **Load `raid-canonical-review` skill and begin Phase 5**
-6. If skip → **Load `raid-wrap-up` skill and begin Phase 6**
+## Phase Spoils
 
-Do not wait. Do not ask twice. The next action after all tasks pass is the human's choice.
+**Two outputs:**
+- `{questDir}/phases/phase-4-implementation.md` — Evolution log with per-task breakdowns
+- Code changes committed with descriptive messages + summary table of all changed files