@flavor-code/superharness 1.0.0

package/skills/go/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: go
+description: Use when the user gives a task goal to complete end-to-end under superharness discipline - drives the full autonomous workflow from goal to verified, reviewed, committed result
+argument-hint: [task goal]
+---
+
+# Superharness Go — Autonomous Task Workflow
+
+**Task goal:** $ARGUMENTS
+
+If the goal above is empty, ask your human partner for the task goal and stop.
+
+**Announce at start:** "Superharness engaged. Working on: <goal>."
+
+You will now drive this goal to completion under the constraints in `HARNESS.md`
+(in this plugin's root directory — read it now if it is not already in your context).
+Work autonomously: only stop to ask when a decision genuinely belongs to your human
+partner (destructive actions, ambiguous product choices). Everything else, decide and proceed.
+
+**State root:** the superharness state root follows the host — `.claude/superharness/`
+under Claude Code, `.flavor/superharness/` under flavor-code. Everywhere below,
+`.claude/superharness/` stands for whichever state root applies to your host.
+
+## Phase 0 — Understand
+
+1. Restate the goal in one sentence.
+2. Explore the relevant code (Glob/Grep/Read) until you can name the files involved.
+3. If the goal is ambiguous in a way that changes the architecture, ask ONE round of
+   clarifying questions. Otherwise proceed with the most reasonable interpretation and
+   note your assumptions in the plan.
+
+## Phase 0.5 — Isolate
+
+**REQUIRED SUB-SKILL:** `superharness:using-git-worktrees`
+
+Set up an isolated workspace before changing anything. In a git project this
+creates a worktree on a new branch **by default** (no consent prompt) so a run
+that goes wrong can be discarded cleanly. If the project is not a git repo, or
+worktree creation fails, work in place — never block. Everything after this
+(plan, trace, implementation, commits) happens in whatever workspace this leaves.
+
+## Phase 1 — Plan
+
+**REQUIRED SUB-SKILL:** `superharness:writing-plans`
+
+- For any goal needing 3+ steps, write the plan to `.claude/superharness/plans/YYYY-MM-DD-<slug>.md`
+  (create the folder if missing).
+- Bite-sized tasks, 2–5 minutes each. Every code step shows the actual code.
+  Every task follows the TDD step sequence: failing test → verify RED → minimal
+  implementation → verify GREEN → commit.
+- Trivial goals (1–2 steps) may skip the plan file but NOT the TDD cycle.
+- Create one TodoWrite/Task item per plan task and keep statuses current.
+- **Ralph tracking is already auto-started — you only enrich it.** The moment this
+  `/superharness:go` prompt was submitted, the UserPromptSubmit hook bootstrapped the
+  ralph state under `.claude/superharness/ralph/`: it ran `Set-RalphCurrentTask` to
+  write the `.current-task` pointer (the single active-task marker), seeded an empty
+  `task.json`, and opened `trace.jsonl` with a `task:started` event. Dot-source the
+  ralph library first: `.claude/superharness/plugins/superharness/scripts/ralph-lib.ps1`
+  (Claude Code) or `.flavor/plugins/superharness/scripts/ralph-lib.ps1` (flavor-code);
+  on macOS/Linux use the `ralph-lib.sh` counterpart at the same location.
+  - **Fallback — guarantee the files exist.** Check `Get-RalphCurrentTask -Root <project>`.
+    If it returns `$null` the hook did NOT fire (a brand-new session is needed to register
+    hooks, or this runner skips UserPromptSubmit for slash commands). In that case
+    bootstrap it yourself NOW, as the very first action, so the runtime files appear under
+    `.claude/superharness/ralph/` regardless:
+    `Start-RalphTask -Root <project> -TaskId '<YYYY-MM-DD-slug>' -Goal '<goal>'`.
+    If it already returns a task id, the hook handled it — do not recreate.
+  - Then **enrich** the (now-present) state:
+  - `Initialize-RalphTasks -Root <project> -Tasks @(@{ id=1; name='scaffold lib' }, @{ id=2; name='add ledger' }) -Phase 'plan' -SprintTotal <N>`
+    — replace the empty list in `.claude/superharness/ralph/task.json` with the plan's
+    task list (each `pending`). **Each entry MUST be a hashtable with `id` and `name`
+    keys** — one per plan task. Passing bare strings (e.g. `@('scaffold','ledger')`)
+    silently produces empty `{id:null, name:""}` rows, because the function reads
+    `$t.id` / `$t.name` off each element. Set `-SprintTotal` to the task count.
+  - `Add-RalphTrace -Root <project> -Phase 'plan' -Event 'plan:done' -Detail '<one-line plan summary>'`
+    — append to the `.claude/superharness/ralph/trace.jsonl` execution ledger.
+  The Stop hook records a `round` heartbeat each round while `.current-task` exists.
+  Track **one active go task per project** at a time: `.current-task` is the single
+  active-task marker, so do not run concurrent `go` tasks in the same project (a new
+  go invocation auto-repoints the pointer to a new task).
+
+## Phase 2 — Implement (TDD, no exceptions)
+
+**REQUIRED SUB-SKILLS:** `superharness:subagent-driven-development` (for plans
+with multiple independent tasks) and `superharness:test-driven-development`.
+
+- **Multi-task plan:** delegate to `superharness:subagent-driven-development` —
+  it dispatches a fresh subagent per task so this main context stays on plan and
+  review. Each subagent does TDD and commits; you coordinate and handle BLOCKED.
+- **Trivial goal (1–2 steps) or tightly-coupled tasks:** implement inline here
+  with `superharness:test-driven-development` (no subagent overhead).
+
+Either way, every task follows TDD with no exceptions:
+
+1. **RED** — write the failing test first. Run it. Confirm it fails for the expected reason.
+2. **GREEN** — write the minimal implementation. Run the test. Confirm it passes.
+3. **REFACTOR** — clean up while keeping tests green.
+4. **Commit** with a descriptive message.
+
+If implementation code was written before its test: delete it, write the test, start over.
+If anything behaves unexpectedly, switch to `superharness:systematic-debugging` —
+no guess-and-patch fixes.
+
+> Ralph trace note: at each task boundary, record execution events with
+> `Add-RalphTrace -Root <project> -Phase 'implement' -Event '<task-id>:<red|green|commit>' -Detail '<short>'`,
+> and flip status with `Set-RalphTaskStatus -Root <project> -Id <task-id> -Status in_progress|done`.
+> Implementer subagents do not write trace markers; the main agent records them. The
+> Stop hook independently appends a `round` heartbeat each round as a backstop.
+
+## Phase 3 — Verify
+
+**REQUIRED SUB-SKILL:** `superharness:verification-before-completion`
+
+- Run the FULL test suite, not just the new tests. Paste actual output.
+- **Record the verification + auto-retry (cap 5).** After running the FULL suite:
+  - All green → `Add-RalphTrace -Root <project> -Phase 'verify' -Event 'verify:success' -Detail '<test cmd>'`,
+    then `Set-RalphTaskStatus` the task to `done` and `Reset-RalphRetry -Root <project>`.
+  - One or more failing → `Add-RalphTrace -Root <project> -Phase 'verify' -Event 'verify:failure' -Detail '<failing test + assertion>'`,
+    then `Add-RalphRetry -Root <project>`. If `Test-RalphRetryExhausted -Root <project>`
+    is true (the counter hit the cap of 5), **stop and report** — do not loop forever.
+    Otherwise **automatically retry in this same run**: go back to Phase 2 via
+    `superharness:systematic-debugging` (reproduce → root cause → fix → re-verify). This
+    is an autonomous retry loop, not a blind re-run, and it does not pause to ask.
+- Run linters/builds the project defines.
+- Never report partial success as success.
+
+## Phase 4 — Review
+
+**REQUIRED SUB-SKILL:** `superharness:requesting-code-review`
+
+- Dispatch a code-reviewer subagent over the change (base SHA → head SHA) using the
+  template in `superharness:requesting-code-review`.
+- Fix Critical and Important issues (each fix goes through the TDD cycle again).
+  Note Minor issues in the final report.
+
+## Phase 5 — Finish & Report
+
+**REQUIRED SUB-SKILL:** `superharness:finishing-a-development-branch`
+
+If Phase 0.5 created a worktree or branch, close it out now: merge the branch
+back, remove the worktree, delete the branch — follow
+`superharness:finishing-a-development-branch`. If the project is not a git repo
+or work was done in place, there is nothing to finish; proceed to the report.
+Never push to a remote as part of finishing — pushing stays with your human
+partner.
+
+Deliver a final summary containing:
+
+- What was built/changed and where (file paths)
+- Evidence: test commands run and their actual results
+- Review outcome and what was fixed
+- Assumptions made and any noted Minor issues / follow-ups
+- How the work was finished (merge + worktree cleanup, or in-place)
+
+**Close the trace.** On final completion, record the terminal event and clear the
+active marker: `Add-RalphTrace -Root <project> -Phase 'done' -Event 'task:completed' -Detail '<summary>'`
+(or `task:failed` / `task:abandoned`), mark the remaining tasks `done` via
+`Set-RalphTaskStatus`, and remove `.claude/superharness/ralph/.current-task` so the Stop hook
+stops recording. The full execution history stays in `.claude/superharness/ralph/trace.jsonl`
+(plus the per-round Stop-hook heartbeats) for cold-start resume via `Get-RalphResumeContext`.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The goal is simple, skip the plan" | Fine — but never skip TDD or verification. |
+| "Tests after coding just this once" | No. RED first, always. |
+| "Full suite takes too long" | Run it anyway. That's the evidence. |
+| "Review is overkill here" | Multi-file or behavior-changing work gets reviewed. |

package/skills/light/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: light
+description: Use when the user gives a small, focused task goal that needs discipline without the full go machinery - quick fixes, small features, config or docs tweaks, prototypes, or when go feels too heavy. Keeps TDD (with explicit exemptions), real-output verification, and root-cause debugging while dropping worktrees, plan files, parallel dispatch, formal code review, and ralph tracking. For heavy multi-file work use superharness:go instead.
+argument-hint: [task goal]
+---
+
+# Superharness Light — lightweight autonomous tasks
+
+**Task goal:** $ARGUMENTS
+
+If the goal above is empty, ask your human partner for the task goal and stop.
+
+**Announce at start:** "Superharness light engaged. Working on: <goal>."
+
+`light` is the lightweight tier of `/superharness:go`. Core discipline is kept (TDD, real-output verification, root-cause debugging); the heavy machinery is dropped. If the task turns out bigger than expected (touches multiple subsystems, needs formal review), proactively switch back to `/superharness:go` and explain why.
+
+## When to use which
+
+| Scenario | Command |
+|----------|---------|
+| Small bug fixes, small features, config/copy tweaks, prototype validation, when go feels too heavy | `/superharness:light` |
+| Multi-file work, behavior changes, needs an isolated workspace / resumable runs / formal code review | `/superharness:go` |
+
+## What light does NOT do
+
+- No worktree/branch — works in place by default
+- No plan file — the task list is managed with TodoWrite, nothing is written to disk
+- No subagent dispatch for implementation or review — everything is done inline in the current session, closed out with a self-check list
+- No ralph tracking — no `.current-task` / `task.json` / `trace.jsonl` are written, the Stop hook automatically no-ops, zero bookkeeping overhead; if interrupted, just re-run
+
+> Note: if the project already has an active go task (`.claude/superharness/ralph/.current-task` exists — `.flavor/superharness/ralph/.current-task` under flavor-code), tell the user first — light will not take over or finish that task. Recommend closing out the go task before running light, to avoid the two flows crossing.
+
+## Phase 1 — Understand
+
+1. Restate the goal in one sentence.
+2. Quickly locate the relevant files (Glob/Grep/Read) until you can say which files need to change.
+3. Ask one round of clarifying questions if there is ambiguity; otherwise proceed with the most reasonable interpretation and record the assumptions in the final report.
+
+## Phase 2 — Implement (TDD with explicit exemptions)
+
+**Strict TDD by default**, see `superharness:test-driven-development`: failing test first (RED) → minimal implementation (GREEN) → refactor → commit.
+
+**TDD Exemptions (no need to ask, but Phase 3 verification is still required):**
+- Pure config: dependency manifests, build config, environment variables
+- Pure copy/docs/comments
+- Generated code / scaffolding
+- One-off prototypes (not entering the main code path)
+
+Exemptions still require: minimal, explainable changes, and verification after completion.
+
+**Branch strategy:** work in place by default. Only create a one-off branch (no worktree) when the change heavily modifies existing code and the project is a git repo; merge or discard it when done.
+
+**Commits:** one commit per cohesive unit; not every TDD cycle needs its own commit.
+
+## Phase 3 — Verification (non-negotiable)
+
+- Run the affected tests plus the project's test command (if the project defines one, run the full suite), and paste the real output.
+- On failure → follow the `superharness:systematic-debugging` root-cause flow: reproduce → locate root cause → fix (with a regression test) → re-verify.
+- "Should be fine" is not an acceptable way to close out.
+
+## Phase 4 — Self-check list (replaces formal review)
+
+Go through this once the change is complete:
+
+- [ ] No debug leftovers in the diff (console.log / debugger / temp code)
+- [ ] No dead code / unused imports
+- [ ] Naming consistent with existing code
+- [ ] Tests actually failed (RED evidence), or the change falls under an exemption category
+- [ ] Edge cases quickly reviewed
+
+Does the change touch multiple modules or a public API? Proactively suggest running `/superharness:go` afterwards for the full flow.
+
+## Phase 5 — Report
+
+Report concisely: what changed (file paths), what commands were run, real results, assumptions.
+No trace, no `.current-task` — light leaves no runtime footprint.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This change is too simple, no need to verify" | Verification is non-negotiable: run tests, paste output. |
+| "Change the code first, add tests later" | TDD by default: failing test first. Exemptions only cover config/copy/scaffolding. |
+| "It failed, just try a different approach" | Follow root-cause debugging; no guess-and-patch. |
+| "The task is bigger than expected, keep pushing through" | Switch back to `/superharness:go`. |

package/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+---
+
+# Requesting Code Review
+
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code reviewer subagent:**
+
+Use Task tool with `general-purpose` type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{DESCRIPTION}` - Brief summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each task or at natural checkpoints
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,168 @@
+# Code Reviewer Prompt Template
+
+Use this template when dispatching a code reviewer subagent.
+
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+
+```
+Task tool (general-purpose):
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan
+
+    {PLAN_OR_REQUIREMENTS}
+
+    ## Git Range to Review
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `{DESCRIPTION}` — brief summary of what was built
+- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
+- `{BASE_SHA}` — starting commit
+- `{HEAD_SHA}` — ending commit
+
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: subagent-driven-development
+description: Use when executing an implementation plan whose tasks are mostly independent - dispatches a fresh subagent per task to keep the controller's context clean, with per-task self-review and a single final review
+---
+
+# Subagent-Driven Development
+
+## Overview
+
+Execute a plan by dispatching a **fresh subagent per task**. The controller (you)
+keeps only plan + coordination context; each implementer subagent gets exactly
+the task it needs and nothing else. This preserves your context for the long run
+and keeps each task focused.
+
+**Announce at start:** "Executing the plan with subagent-driven-development."
+
+**Core principle:** Fresh subagent per task + per-task self-review + one final
+review = focused context, fast iteration.
+
+**superharness scope:** Per-task review is **self-review only** — there are no
+per-task reviewer subagents. Whole-change quality is gated once, by the caller's
+final `superharness:requesting-code-review` pass (`go` Phase 4).
+
+## When to use
+
+- You have a written plan (from `superharness:writing-plans`).
+- Its tasks are **mostly independent** (not tightly coupled).
+- You are staying in this session.
+
+If tasks are tightly coupled, or the goal is trivial (1–2 steps), skip subagents
+and implement inline with `superharness:test-driven-development`.
+
+## Process
+
+1. **Read the plan once.** Extract every task with its full text and surrounding
+   context (where it fits, files involved). Create one TodoWrite item per task.
+2. **Per task, in order** (never dispatch two implementers in parallel — they
+   would fight over the working tree):
+   - Dispatch a fresh implementer subagent with the **complete task text +
+     scene-setting context**. The subagent does NOT read the plan file — you
+     hand it everything.
+   - The implementer follows `superharness:test-driven-development`
+     (RED → GREEN → REFACTOR → commit), runs that task's tests, self-reviews,
+     and commits.
+   - Handle the returned status (below). When DONE and clean, mark the TodoWrite
+     item complete and move on.
+3. **After all tasks**, return control to the caller (`go` Phase 3/4) for the
+   full-suite verification and the single final code review.
+
+```dot
+digraph sdd {
+  "Read plan, extract all tasks, TodoWrite" [shape=box];
+  "More tasks?" [shape=diamond];
+  "Dispatch fresh implementer subagent (full task text + context)" [shape=box];
+  "Status?" [shape=diamond];
+  "Supply context / stronger model / split / escalate" [shape=box];
+  "Mark task complete" [shape=box];
+  "Return to caller for verify + final review" [shape=box];
+
+  "Read plan, extract all tasks, TodoWrite" -> "More tasks?";
+  "More tasks?" -> "Dispatch fresh implementer subagent (full task text + context)" [label="yes"];
+  "More tasks?" -> "Return to caller for verify + final review" [label="no"];
+  "Dispatch fresh implementer subagent (full task text + context)" -> "Status?";
+  "Status?" -> "Mark task complete" [label="DONE"];
+  "Status?" -> "Supply context / stronger model / split / escalate" [label="NEEDS_CONTEXT / BLOCKED"];
+  "Supply context / stronger model / split / escalate" -> "Dispatch fresh implementer subagent (full task text + context)";
+  "Mark task complete" -> "More tasks?";
+}
+```
+
+## Implementer dispatch template
+
+Fill this in and send it as the subagent's prompt (do not point it at the plan
+file — hand it the full text):
+
+```
+You are implementing ONE task under superharness discipline. Use
+superharness:test-driven-development — write the failing test first, watch it
+fail (RED), write the minimal code to pass (GREEN), refactor, then commit.
+
+Task: <full task text, verbatim from the plan>
+
+Context you need:
+- Where this fits: <one or two sentences>
+- Files involved: <exact paths>
+- Conventions/patterns to follow: <as needed>
+
+When done, self-review your diff, then report ONE status:
+- DONE — implemented, tests green, committed
+- DONE_WITH_CONCERNS — done, but I flag: <concern>
+- NEEDS_CONTEXT — I need: <what>
+- BLOCKED — I cannot proceed because: <why>
+Report the test command you ran and its actual result.
+```
+
+## Handling implementer status
+
+- **DONE** — mark complete, next task.
+- **DONE_WITH_CONCERNS** — read the concern. If it affects correctness or scope,
+  resolve it before moving on; if it's an observation, note it and proceed.
+- **NEEDS_CONTEXT** — supply exactly what's missing and re-dispatch.
+- **BLOCKED** — assess: more context? re-dispatch with it. Needs more reasoning?
+  re-dispatch with a more capable model. Too large? split it. Plan wrong?
+  escalate to your human partner. Never re-dispatch the same model unchanged.
+
+## Model selection
+
+Use the cheapest model that fits: mechanical 1–2 file tasks with a complete spec
+→ a fast model; multi-file integration → a standard model; design judgment or
+broad codebase understanding → the most capable model.
+
+## Continuous execution
+
+Do not check in with your human partner between tasks. Stop only for an
+unresolvable BLOCKED, genuine ambiguity, or when all tasks are complete.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "I'll let the subagent read the plan" | No. Hand it the full task text + context. |
+| "Run two implementers at once to go faster" | They'll corrupt the working tree. One at a time. |
+| "Skip self-review, the final review will catch it" | Self-review is the per-task gate. Always do it. |
+| "BLOCKED — I'll just retry the same way" | Change something: context, model, or task size. |
+| "Tasks are coupled but I'll force subagents" | Fall back to inline TDD for coupled work. |