create-harness-vibe-coding 0.8.0 → 0.8.2

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

@@ -0,0 +1,246 @@
+# ECC Rules Guide — Stack to Rule Set Mapping
+
+ECC (Engineering Code Conventions) rules are organized by language/domain under `~/.claude/rules/ecc/`. The Harness bootstrap process MUST install the appropriate rule sets for the project's tech stack.
+
+## Installation
+
+```bash
+# From the ECC rules repository:
+cp -r rules/common .claude/rules/ecc/
+cp -r rules/<language> .claude/rules/ecc/
+
+# Verify:
+ls .claude/rules/ecc/
+```
+
+## Stack Detection (Automatic)
+
+| File Found | Stack | Install These Rules |
+|------------|-------|-------------------|
+| `package.json` + `tsconfig.json` | TypeScript/Node | `common/`, `typescript/`, `web/` |
+| `package.json` (no tsconfig) | JavaScript/Node | `common/`, `typescript/` (JS mode), `web/` |
+| `go.mod` | Go | `common/`, `golang/` |
+| `pyproject.toml` / `requirements.txt` | Python | `common/`, `python/` |
+| `Cargo.toml` | Rust | `common/`, `rust/` |
+| `Gemfile` | Ruby/Rails | `common/`, `ruby/` |
+| `composer.json` | PHP | `common/`, `php/` |
+| `build.gradle` / `pom.xml` | Java/Kotlin | `common/`, `java/` or `kotlin/` |
+| `*.sln` / `*.csproj` | C#/.NET | `common/`, `csharp/` |
+| `Package.swift` | Swift | `common/`, `swift/` |
+| Multiple frontend files (`.vue`, `.tsx`, `.jsx`) | Web frontend | Add `web/` to any stack |
+
+## Stack Detection (Ask User)
+
+If no stack markers are found (empty/new repo), ask:
+
+> "What's your tech stack? I need to install the right coding rules.
+>  Options: TypeScript/Node, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C#, Swift, or other.
+>  Frontend framework? (React, Vue, Next.js, Nuxt, none)"
+
+Based on answer, install matching rules.
+
+## Rule Set Catalog
+
+| Rule Set | What It Covers | Files |
+|----------|---------------|-------|
+| `common/` | **Required for all projects.** Immutability, error handling, file organization, git workflow, testing, security, agents, hooks, patterns. | `coding-style.md`, `git-workflow.md`, `testing.md`, `security.md`, `patterns.md`, `agents.md`, `hooks.md`, `performance.md`, `development-workflow.md` |
+| `typescript/` | TS/JS types, interfaces, immutability patterns, error handling with try-catch, Zod validation, React props, custom hooks, repository pattern. | `coding-style.md`, `testing.md`, `security.md`, `patterns.md`, `hooks.md` |
+| `web/` | Frontend: CSS custom properties, animation-only properties, semantic HTML, component composition, state management, image optimization, CSP, XSS, Core Web Vitals, bundle budgets. | `coding-style.md`, `design-quality.md`, `testing.md`, `security.md`, `patterns.md`, `performance.md`, `hooks.md` |
+| `python/` | PEP 8, type hints, immutability, async patterns, pytest, input validation. | `coding-style.md`, `testing.md`, `security.md`, `patterns.md` |
+| `golang/` | Idiomatic Go, error handling, concurrency patterns, table-driven tests, security. | `coding-style.md`, `testing.md`, `security.md`, `patterns.md` |
+| `rust/` | Ownership, lifetimes, error handling, unsafe usage, cargo-llvm-cov. | `coding-style.md`, `testing.md`, `security.md`, `patterns.md` |
+| `ruby/` | Ruby idioms, Rails patterns, RSpec, security. | `coding-style.md`, `testing.md`, `security.md` |
+| `php/` | PSR-12, Eloquent ORM, security, testing. | `coding-style.md`, `testing.md`, `security.md` |
+| `swift/` | Protocol-oriented design, value semantics, ARC, Swift Concurrency. | `coding-style.md`, `testing.md`, `security.md` |
+| `arkts/` | HarmonyOS/ArkTS specific. | `coding-style.md`, `testing.md`, `security.md` |
+| `angular/` | Angular specific patterns. | Extends `typescript/` and `web/` |
+| `vue/` | Vue 3 Composition API, reactivity, Pinia. | Extends `typescript/` and `web/` |
+| `nuxt/` | Nuxt 4 specific. | Extends `vue/` |
+
+## Recommended Combinations
+
+| Project Type | Rule Sets |
+|-------------|-----------|
+| React + TypeScript frontend | `common/`, `typescript/`, `web/` |
+| Vue 3 frontend | `common/`, `typescript/`, `web/`, `vue/` |
+| Next.js fullstack | `common/`, `typescript/`, `web/` |
+| Python backend (FastAPI) | `common/`, `python/` |
+| Go microservice | `common/`, `golang/` |
+| Rust CLI tool | `common/`, `rust/` |
+| Electron + React desktop | `common/`, `typescript/`, `web/` |
+| React Native mobile | `common/`, `typescript/`, `web/` |
+
+## Bootstrap Verification
+
+After installing ECC rules, verify:
+
+```bash
+ls .claude/rules/ecc/common/          # MUST exist
+ls .claude/rules/ecc/<language>/      # MUST exist for detected/declared stack
+```
+
+If rules are missing, the agent MUST install them before proceeding to step 1.
+
+## ECC Design Rules — Frontend + Backend Architecture
+
+Beyond coding style, ECC provides design-level guidance for both frontend and backend.
+These are NOT in Harness by default — the agent should consult them when filling
+`Harness/architecture.md` and `Harness/research/research-results.md`.
+
+### Frontend Design (web/ + typescript/)
+
+| Rule File | Design Guidance | When to Apply |
+|-----------|----------------|---------------|
+| `web/design-quality.md` | Anti-template policy, required qualities (hierarchy, depth, typography, motion, color semantics), banned patterns (stock hero, default card grids, safe gray-on-white) | Before writing any frontend code |
+| `web/patterns.md` | Compound components, render props, container/presentational split, state management (server/client/URL/form), URL as state, stale-while-revalidate, optimistic updates | When architecting frontend data flow |
+| `web/performance.md` | Core Web Vitals targets, bundle budgets, loading strategy, image optimization, font loading, animation performance | Before production build |
+| `web/security.md` | CSP (nonce-based), XSS prevention, third-party script SRI, HTTPS headers, CSRF protection | Before any user-facing deploy |
+| `web/testing.md` | Visual regression (320/768/1024/1440), a11y, Lighthouse, cross-browser, responsive | Before launch |
+| `web/hooks.md` | PostToolUse format/lint/type-check, PreToolUse file size guard, Stop build verification | CI setup |
+| `typescript/patterns.md` | API response envelope, custom hooks, Repository pattern | Backend-frontend contract |
+
+### Backend Design (python/ + golang/ + rust/)
+
+| Rule File | Design Guidance | When to Apply |
+|-----------|----------------|---------------|
+| `python/fastapi.md` | FastAPI patterns: async correctness, dependency injection, Pydantic schemas, OpenAPI quality | Python API projects |
+| `python/patterns.md` | Repository pattern, service layer, API response format | Any Python backend |
+| `golang/patterns.md` | Idiomatic Go patterns, concurrency, error handling | Go microservices |
+| `rust/patterns.md` | Ownership patterns, error handling, unsafe usage | Rust services |
+| `common/patterns.md` | Skeleton projects, Repository pattern, API response format, design pattern guidance | All projects |
+
+### Architecture Templates
+
+Write the project-specific structure in `Harness/architecture.md`. Use the ECC rule combinations above to decide which standards apply to each layer.
+
+### API Contract
+
+See [Contract Rules](#contract-rules) below for the full spec.
+
+## Agent Skills + ECC Rules
+
+Dispatch packets MUST include `ecc` and SHOULD include `skills` fields (use `skills: none` when no skill applies). `Harness/context-loading.md#ecc-rules-per-role` owns the role-to-ECC mapping. This guide owns stack detection and the catalog of available ECC rule sets.
+
+## API Contract Specification (Frontend ↔ Backend)
+
+The single most important integration pattern. Without this, frontend and backend drift apart silently.
+
+### Contract Rules
+
+1. **Backend owns the schema.** Define types in the backend language, generate frontend types.
+2. **Never duplicate types manually.** One source of truth, code-generated copies.
+3. **Validate at both boundaries.** Backend validates input (Pydantic/Zod), frontend validates API responses.
+4. **Error envelope is universal.** Use `common/patterns.md` format everywhere.
+
+### OpenAPI 3.0 Example (Generator-Readable)
+
+```yaml
+# api/openapi.yaml — Feed this to openapi-typescript or openapi-generator
+openapi: "3.0.3"
+info:
+  title: User API
+  version: "1.0.0"
+paths:
+  /api/users:
+    get:
+      operationId: listUsers
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, default: 1 }
+        - name: limit
+          in: query
+          schema: { type: integer, default: 20 }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success: { type: boolean }
+                  data:
+                    type: object
+                    properties:
+                      users: { type: array, items: { $ref: "#/components/schemas/User" } }
+                  meta:
+                    type: object
+                    properties:
+                      total: { type: integer }
+                      page: { type: integer }
+    post:
+      operationId: createUser
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateUserInput" }
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success: { type: boolean }
+                  data:
+                    type: object
+                    properties:
+                      user: { $ref: "#/components/schemas/User" }
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email, name, role, createdAt]
+      properties:
+        id: { type: string, format: uuid }
+        email: { type: string, format: email }
+        name: { type: string }
+        role: { type: string, enum: [admin, member] }
+        createdAt: { type: string, format: date-time }
+    CreateUserInput:
+      type: object
+      required: [email, name]
+      properties:
+        email: { type: string, format: email }
+        name: { type: string, minLength: 1, maxLength: 100 }
+        role: { type: string, enum: [admin, member], default: member }
+```
+
+```bash
+# Generate TypeScript types from OpenAPI:
+npx openapi-typescript api/openapi.yaml -o src/shared/api-types.ts
+```
+
+### Implementation Per Stack
+
+| Stack | Backend Schema | Frontend Types | Validation |
+|-------|---------------|----------------|------------|
+| Python BE + TS FE | Pydantic models | `openapi-typescript` from OpenAPI | Pydantic (BE) + Zod (FE) |
+| Go BE + TS FE | Go structs + OpenAPI | `openapi-generator` | Go validator (BE) + Zod (FE) |
+| Next.js fullstack | Zod schemas in `shared/` | Same Zod schemas | Zod (both sides) |
+| tRPC | tRPC router definitions | Auto-inferred from router | tRPC built-in |
+| GraphQL | GraphQL schema | `graphql-codegen` | GraphQL middleware + Zod (FE) |
+
+### Agent Dispatch with ECC + Skills
+
+When dispatching a subagent, the dispatch packet MUST include:
+
+```json
+{
+  "agentRole": "worker",
+  "task": "Implement user profile page",
+  "writeSet": ["src/components/UserProfile.tsx", "src/hooks/useUser.ts"],
+  "forbidden": ["src/backend/", "database/"],
+  "verification": ["npm test", "npm run lint"],
+  "ecc": ["web/design-quality.md", "web/patterns.md", "typescript/patterns.md"],
+  "skills": ["react-review"],
+  "apiContract": "api/contract.yaml"
+}
+```
+
+Different subagents get different `ecc` and `skills` arrays.
+A frontend implementer loads `web/` rules. A backend implementer loads `python/` or `golang/` rules.
+A reviewer loads `security/` + `testing/` rules. See `Harness/context-loading.md` for the full per-role mapping.

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.