create-harness-vibe-coding 0.8.1 → 0.8.2

package/templates/common/Harness/README.md

@@ -1,132 +1,131 @@
-# create-harness-vibe-coding - Harness Router
-
-Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
-
-Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS.md` when work is active. Do not read the whole `Harness/` tree.
-
-## 0-1 Flow
-
-```text
-Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
-```
-
-For the full phase contract, load [lifecycle.md](lifecycle.md).
-
-## Development Contract
-
-- This file is a router, not a full spec.
-- If the task does not clearly match a row below, search by keywords before loading more docs.
-- project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
-- Important assumptions, decisions, blockers, evidence, and handoffs must be written to the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
-- README rewrites are optional project-doc work. Use `wf-readme` and preserve existing public docs unless the user approves a broader restructure.
-- Code architecture belongs in [architecture.md](architecture.md) or the current feature doc, not `CLAUDE.md`.
-- Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
-- WF mode rules live in [WF.md](WF.md).
-- Phase rules live in [lifecycle.md](lifecycle.md).
-- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md).
-- Parallel dispatch rules live in [dispatch.md](dispatch.md).
-- Subagent orchestration methodology lives in [subagents.md](subagents.md).
-- Extension rules live in [extension.md](extension.md).
-- Context-loading rules live in [context-loading.md](context-loading.md).
-- Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
-
-## Keyword Routing
-
-Use this only when the task is ambiguous or the matching row is unclear.
-
-1. Extract 2-5 concrete keywords from the user request.
-2. Search the project docs first:
-
-```bash
-rg -n "keyword1|keyword2|keyword3" CLAUDE.md README.md Harness
-```
-
-3. Load only the top matching doc or the smallest matching doc pair.
-4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`.
-
-Keywords are retrieval hints, not project facts.
-
-## Load By Task
-
-Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
-
-Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. Load `Harness/WF.md` directly, then delegate subagent coordination to `subagent-orchestrator`.
-
-| When to Read | Keywords | Load | Output |
-| --- | --- | --- | --- |
-| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
-| Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
-| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
-| Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](architecture.md) | layer map, ports, constraints |
+# create-harness-vibe-coding - Harness Router
+
+Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
+
+Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS.md` when work is active. Do not read the whole `Harness/` tree.
+
+## 0-1 Flow
+
+```text
+Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
+```
+
+For the full phase contract, load [lifecycle.md](lifecycle.md).
+
+## Development Contract
+
+- This file is a router, not a full spec.
+- If the task does not clearly match a row below, search by keywords before loading more docs.
+- project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+- Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
+- README rewrites are optional project-doc work. Use `wf-readme` and preserve existing public docs unless the user approves a broader restructure.
+- Code architecture belongs in [architecture.md](architecture.md) or the current feature doc, not `CLAUDE.md`.
+- Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
+- WF mode rules live in [WF.md](WF.md).
+- Phase rules live in [lifecycle.md](lifecycle.md).
+- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md).
+- Parallel dispatch rules live in [dispatch.md](dispatch.md).
+- Subagent orchestration methodology lives in [subagents.md](subagents.md).
+- Extension rules live in [extension.md](extension.md).
+- Context-loading rules live in [context-loading.md](context-loading.md).
+- Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
+
+## Keyword Routing
+
+Use this only when the task is ambiguous or the matching row is unclear.
+
+1. Extract 2-5 concrete keywords from the user request.
+2. Search the project docs first:
+
+```bash
+rg -n "keyword1|keyword2|keyword3" CLAUDE.md README.md Harness
+```
+
+3. Load only the top matching doc or the smallest matching doc pair.
+4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`.
+
+Keywords are retrieval hints, not project facts.
+
+## Load By Task
+
+Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
+
+Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. Load `Harness/WF.md` directly, then delegate subagent coordination to `subagent-orchestrator`. If the request says `/wf-auto`, `$wf-auto`, `wf auto`, or `auto mode`, choose the WF-AUTO row and load `Harness/WF-AUTO.md`.
+
+| When to Read | Keywords | Load | Output |
+| --- | --- | --- | --- |
+| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
+| Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
+| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
+| Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](architecture.md) | layer map, ports, constraints |
 | Need WF mode | wf, /wf, $wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
-| Need peer review | /wf-review, $wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `.agents/skills/wf-review/SKILL.md`, `Harness/README.md` | cross-model review via other CLI (Codex/Claude) |
-| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
-| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
-| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
-| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use | browser-e2e workflow, wf-browser skill, Browser Use skill | CLI commands, screenshots, agent history, verification pass/fail evidence |
-| Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
-| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
-| Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
-| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md) | task plan, tests, implementation loop |
-| Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
-| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
-| Need harness update | update, /wf-update, $wf-update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `.agents/skills/wf-update/SKILL.md`, `Harness/.harness-version` | update plan, safe incremental update, merge candidates |
-
-## Gates
-
-- Move phases in order unless the user asks for a fast lane.
+| Need perpetual auto-optimization | /wf-auto, $wf-auto, wf auto, auto mode, never stop, self-improve, continuous optimize | [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | perpetual loop, 8-angle scan, spark search, intent checkpoint, evidence ledger; CEO never writes code |
+| Need perpetual inspiration mode | /wf-auto-spark, $wf-auto-spark, wf auto spark, spark mode, external inspiration, discover mode, never stop | [WF-AUTO-SPARK.md](WF-AUTO-SPARK.md), [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | roadmap-anchored: North Star + milestones; external spark search; ≤50% deviation guard; never auto-stops |
+| Need WF-MAX mode | /wf-max, $wf-max, wf max, maximum parallelism, CEO, Manager, Worker, fan-out | [WF-MAX.md](WF-MAX.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | CEO-only dispatch, W0 fan-out, D-GATE, wave evidence |
+| Need peer review | /wf-review, $wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `.agents/skills/wf-review/SKILL.md`, `Harness/README.md` | cross-model multi-dimension review with severity classification |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
+| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
+| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
+| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use | browser-e2e workflow, wf-browser skill, Browser Use skill | CLI commands, screenshots, agent history, verification pass/fail evidence |
+| Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
+| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
+| Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
+| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md) | task plan, tests, implementation loop |
+| Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
+| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
+| Need harness update | /wf-update, $wf-update, update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `.agents/skills/wf-update/SKILL.md`, `Harness/.harness-version`, `Harness/scripts/wf-update-check.mjs` | script-driven comparison, SAFE/CONFLICT/PRESERVE classification, user decides conflicts |
+| Need harness removal | /wf-remove, $wf-remove, wf remove, remove harness, uninstall harness | `.claude/skills/wf-remove/SKILL.md`, `.agents/skills/wf-remove/SKILL.md`, `Harness/scripts/wf-remove.mjs` | safe removal plan: auto-remove SAFE, confirm MODIFIED, never touch USER DATA |
+
+## Gates
+
+- Move phases in order unless the user asks for a fast lane.
 - Use `/wf <task>` in Claude Code, `$wf` in Codex, `/wf-max [task]` or `$wf-max`, `wf mode`, `workflow mode`, or `wk mode` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
-- Do not code before the PRD has MVP, non-goals, and acceptance criteria.
-- Unsure whether to open a task? Read [agent-workflow.md](agent-workflow.md) Section 1.
-- Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
-- Do not run writing agents in parallel unless write sets are disjoint.
-- Before coordinating multiple agents, fill `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
-- In WF mode, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, and at closeout.
-- In WF Max mode, never dispatch two implementers with overlapping file claims. Verify disjointness before each wave.
-- Do not add stack-specific agents or skills without following `extension.md`.
-- Do not close work without tests or recorded manual verification.
-- Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
-- Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
-- If a doc still has `{{...}}`, treat that section as a template, not project fact.
-
-## Doc Map
-
-```text
-Harness/README.md                  router only
-Harness/MEMORY.md                  resource index
-Harness/PROGRESS.md                global task index and cross-task decisions
-Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat
-Harness/tasks/<id>/PLAN.md         per-task implementation plan and evidence
-Harness/tasks/_template/           task capsule template (copy to create new task)
-Harness/WF.md                      long-task workflow and recovery loop
-Harness/WF-MAX.md                  max-parallelism workflow with wave dispatch
-.claude/skills/wf/SKILL.md         Claude Code WF skill command
-.claude/skills/wf-max/SKILL.md     Claude Code max-parallelism skill command
-.claude/skills/wf-review/SKILL.md  Claude Code cross-model peer review skill
-.agents/skills/wf/SKILL.md         Codex WF repo skill
-.agents/skills/wf-max/SKILL.md     Codex max-parallelism repo skill
-.agents/skills/wf-review/SKILL.md  Codex cross-model peer review repo skill
-Harness/lifecycle.md               0-1 product flow
-Harness/subagents.md               controller-led subagent orchestration
-Harness/context-loading.md         dynamic loading and subagent packs
-Harness/dispatch.md                lightweight parallel dispatch protocol
-Harness/extension.md               stack-specific asset contract
-Harness/agent-workflow.md          build/review/test loop
-Harness/architecture.md            layer boundaries
-Harness/research/README.md         research protocol
-Harness/research/PRD.md            product scope
-Harness/research/research-results.md research results
-Harness/workflows/*.md             optional workflow evidence rules (if installed)
-Harness/memory/tool-usage-reflections.md repeated tool failures and better command patterns
-Harness/memory/user-corrections-preferences.md durable user corrections and preferences
-Harness/memory/agent-lessons-patterns.md reusable review/debug lessons
-Harness/scripts/validate-harness.mjs lightweight harness gate
-.claude/agents/*                   built-in common agents
-.claude/skills/*                   Claude Code skill commands
-.agents/skills/*                   Codex repo skills mirrored from .claude/skills
-.claude/skills/wf-readme/SKILL.md README preservation and optional structure pass
-.claude/skills/wf-update/SKILL.md   GitHub-based harness update
-.agents/skills/wf-update/SKILL.md   Codex harness update skill
-Harness/.harness-version             scaffold version and file checksums
-```
+- Use `/wf-auto` for perpetual self-directed optimization that never stops until 8-angle exhaustion.
+- **WF-MAX Role Contract**: Three-layer architecture — global mode (`wf-max`), agent role (`ceo|manager|worker|reviewer`), dispatch permission (`writeSet`, `forbidden`, `verification`). CEO never writes source code. Workers edit only dispatch.writeSet. Edit/Write/MultiEdit enforced by PreToolUse hook per agentRole. See `CLAUDE.md` §1a.
+- **WF-REVIEW Anti-Self-Review**: Must invoke the OTHER CLI (Codex↔Claude). Same-model simulation is forbidden.
+- Mode state persists in `Harness/.runtime/current-mode.json` (gitignored). SessionStart hook injects role-aware context (CEO/Worker/Manager/Reviewer). Stale modes (>30 min) auto-clear. Per-turn reinforcement prevents drift after compression.
+- Do not code before the PRD has MVP, non-goals, and acceptance criteria.
+- Unsure whether to open a task? Read [agent-workflow.md](agent-workflow.md) Section 1.
+- Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
+- Do not run writing agents in parallel unless write sets are disjoint.
+- Before coordinating multiple agents, fill `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
+- In WF mode, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, and at closeout.
+- In WF Max mode, never dispatch two implementers with overlapping file claims. Verify disjointness before each wave.
+- In WF Max mode, D-GATE (Dispatch Table + Self-Audit Checklist) is mandatory before W2 implementation dispatch.
+- Do not add stack-specific agents or skills without following `extension.md`.
+- Do not close work without tests or recorded manual verification.
+- Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
+- Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
+- Run `node tests/e2e-wf-hooks.test.mjs` to verify hook enforcement works before deploying WF-MAX.
+- If a doc still has `{{...}}`, treat that section as a template, not project fact.
+
+## Doc Map
+
+| Category | Files |
+|----------|-------|
+| **Router + Index** | `README.md`, `MEMORY.md`, `PROGRESS.md` |
+| **Task Capsule** | `tasks/<id>/PROGRESS.md`, `tasks/<id>/PLAN.md`, `tasks/_template/` |
+| **Workflows** | `WF.md`, `WF-MAX.md`, `WF-AUTO.md`, `WF-AUTO-SPARK.md` |
+| **Guides** | `ECC-GUIDE.md`, `TDD-GUIDE.md`, `lifecycle.md`, `architecture.md` |
+| **Orchestration** | `subagents.md`, `context-loading.md`, `dispatch.md`, `agent-workflow.md`, `extension.md` |
+| **Research** | `research/README.md`, `research/PRD.md`, `research/research-results.md` |
+| **Memory** | `memory/tool-usage-reflections.md`, `memory/user-corrections-preferences.md`, `memory/agent-lessons-patterns.md` |
+| **Scripts** | `scripts/wf-mode-hook.mjs`, `scripts/validate-harness.mjs`, `scripts/wf-update-check.mjs`, `scripts/wf-remove.mjs` |
+| **Runtime** | `.runtime/current-mode.json` (gitignored, hook-managed), `.harness-version` |
+| **Agents + Skills** | `.claude/agents/*`, `.claude/skills/*`, `.agents/skills/*` |
+
+## Skill Commands
+
+| Claude Code | Codex | Purpose |
+|---|---|---|
+| `/wf <task>` | `$wf <task>` | Long-task workflow: explore -> plan -> implement -> review -> verify |
+| `/wf-max [task]` | `$wf-max [task]` | Maximum parallelism: CEO -> Manager -> Worker hierarchy |
+| `/wf-auto` | `$wf-auto` | Perpetual auto-optimization: never stops until 8-angle exhaustion |
+| `/wf-auto-spark` | `$wf-auto-spark` | Perpetual inspiration: spark search, roadmap-anchored, ≤50% deviation guard, never auto-stops |
+| `/wf-review [focus]` | `$wf-review [focus]` | Cross-model peer review via Codex <-> Claude |
+| `/wf-learn` | `$wf-learn` | Force learning cycle: context-master -> memory-master |
+| `/wf-browser [task]` | `$wf-browser [task]` | AI-driven browser automation for E2E testing |
+| `/wf-update` | `$wf-update` | Script-driven harness update: fetch + compare + apply |
+| `/wf-remove` | `$wf-remove` | Safe harness removal: auto-delete SAFE, confirm MODIFIED, preserve USER DATA |
+```

package/templates/common/Harness/TDD-GUIDE.md

@@ -0,0 +1,83 @@
+# TDD Guide — Test-Driven Development in Harness
+
+TDD is NOT optional in Harness. The agent-workflow loop requires a failing test before implementation.
+This guide specifies when, how, and what to test.
+
+## When TDD is Mandatory
+
+| Trigger | Action |
+|---------|--------|
+| New feature | Write failing test first. Implementation MUST NOT start without it. |
+| Bug fix | Write failing regression test that reproduces the bug. Fix only after test fails. |
+| Refactor | Existing tests MUST be green before refactoring. Keep green throughout. |
+| API endpoint | Integration test first (request → expected response). |
+| UI component | Visual regression or behavior test first (render → user action → expected state). |
+| Database change | Migration test first (apply → verify schema → rollback → verify). |
+
+## TDD Cycle (Red-Green-Refactor)
+
+```
+RED:    Write minimal failing test
+        → Run test → FAILS (if it passes, test is wrong)
+GREEN:  Write minimal code to make test pass
+        → Run test → PASSES
+        → Run ALL tests → ALL GREEN
+IMPROVE: Refactor while keeping green
+        → Run ALL tests → ALL GREEN
+        → Coverage check (≥80%)
+```
+
+## ECC Testing Rules
+
+Coverage thresholds, AAA structure, test naming, and per-stack setup live in ECC testing rules (`common/testing.md` + stack-specific). This guide defines Harness sequencing only: failing test/manual check first, implementation second, verification last.
+
+## Agent Dispatch — TDD Gate
+
+Before dispatching an Implementer, the Planner MUST verify:
+
+1. [ ] Test file exists for the target module
+2. [ ] Test is RED (fails) for new feature / bug fix
+3. [ ] Test covers acceptance criteria
+4. [ ] Test covers error paths (not just happy path)
+5. [ ] Coverage threshold declared in PLAN.md
+
+If any check fails → dispatch Test Writer first, then Implementer.
+
+## TDD Anti-Patterns
+
+| Anti-Pattern | Symptom | Fix |
+|-------------|---------|-----|
+| **Test-last** | Writing implementation first, then tests "to verify" | Reverse order. Tests first. |
+| **Test-the-test** | Test passes immediately (testing nothing) | Add real assertion. Delete and rewrite. |
+| **Giant test** | One test covering entire feature | Split into unit (logic) + integration (API) + E2E (flow) |
+| **Mock everything** | All dependencies mocked, no real behavior tested | Mock only external I/O (network, disk). Test real logic. |
+| **Skip coverage** | "80% is too hard, let's move on" | Coverage is a gate. Don't merge without it. |
+
+## TDD in WF-MAX Mode
+
+In `/wf-max`, tests and implementation are dispatched in SEPARATE waves.
+Test Writers MUST complete before Implementers start. No parallel overlap.
+
+```
+W2a — TEST WAVE (Test Writers, parallel):
+  1. Test Writer (FE) → write failing tests for UserProfile
+  2. Test Writer (BE) → write failing API tests for GET /users
+  ↓ BARRIER: all tests written and confirmed RED ↓
+
+W2b — IMPLEMENTATION WAVE (Implementers, parallel):
+  3. Implementer (FE) → make FE tests pass
+  4. Implementer (BE) → make BE tests pass
+  ↓ BARRIER: all tests GREEN ↓
+
+W2R — REVIEW WAVE:
+  5. Reviewer → verify test coverage + implementation correctness
+```
+
+**Why separate waves:** Workers in the same WF-MAX wave run in parallel.
+If Test Writers and Implementers share a wave, Implementers start before RED
+tests exist — violating the TDD gate. Two waves with an explicit barrier
+ensures tests exist before any implementation begins.
+
+## Verification
+
+Run the verification commands declared in the task PLAN or dispatch packet. Do not claim TDD completion until RED, GREEN, and full-check evidence are recorded.