create-harness-vibe-coding 0.1.9 → 0.2.0

package/templates/common/SETUP.md

@@ -9,9 +9,10 @@ This scaffold is a 0-1 product harness:
 - short agent entry files
 - dynamic docs router
 - PRD, research protocol, architecture, ports, data-flow, state templates
-- active `docs/harness/PLAN.md`
+- active `Harness/PLAN.md`
+- `Harness/MEMORY.md` plus a `Harness/memory/` folder for durable self-learning, user corrections, and tool reflections
 - built-in common agents
-- subagent context-loading protocol
+- subagent orchestration and context-loading protocol
 - skill-style dynamic loaders in `.claude/skills/`
 - lightweight harness validator
 - test/review/feedback loop
@@ -23,32 +24,134 @@ It does not guess your stack or business domain. Claude Code should fill those t
 Start Claude Code, then say:
 
 ```text
-Read SETUP.md. Bootstrap this project as a 0-1 product harness.
-Use docs/README.md as the router. Keep context small.
-First clarify the idea, then create PRD, research, architecture, docs/harness/PLAN.md, and the first vertical-slice task.
+Read Harness/SETUP.md. Bootstrap this project as a 0-1 product harness.
+Use Harness/README.md as the router. Keep context small.
+First clarify the idea, then create PRD, research, architecture, Harness/PLAN.md, and the first vertical-slice task.
 ```
 
 ## Required Bootstrap Sequence
 
 Claude must follow this order:
 
-1. Read `CLAUDE.md`, `MEMORY.md`, `docs/README.md`, and `docs/harness/lifecycle.md`.
-2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `docs/harness/PLAN.md`.
-3. Fill `docs/research/PRD.md` with MVP, non-goals, and acceptance criteria.
-4. Read `docs/research/README.md`, then fill `docs/research/research-results.md` with adopted/rejected research choices.
-5. Fill minimum architecture: `docs/harness/architecture.md` and one port in `docs/domain/ports.md`.
-6. Create the first vertical-slice plan in `docs/harness/PLAN.md`.
-7. Use `docs/harness/context-loading.md` and `docs/harness/dispatch.md` when spawning subagents.
-8. Fill `docs/harness/data-flow.md` or `docs/harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, and `Harness/lifecycle.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
+2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `Harness/PLAN.md`.
+3. Fill `Harness/research/PRD.md` with MVP, non-goals, and acceptance criteria.
+4. Read `Harness/research/README.md`, then fill `Harness/research/research-results.md` with adopted/rejected research choices.
+5. Fill minimum architecture: `Harness/architecture.md` and one port in `Harness/domain/ports.md`.
+6. Create the first vertical-slice plan in `Harness/PLAN.md`.
+7. Use `Harness/subagents.md`, `Harness/context-loading.md`, and `Harness/dispatch.md` when spawning subagents.
+8. Fill `Harness/data-flow.md` or `Harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
 9. Implement only after a failing test or manual verification step is defined.
-10. Run `node scripts/validate-harness.mjs --strict`.
-11. Record final verification and next feedback step in `docs/harness/PLAN.md`.
+10. Run `node Harness/scripts/validate-harness.mjs --strict`.
+11. Record final verification and next feedback step in `Harness/PLAN.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
+
+## Existing Project Bootstrap Sequence
+
+When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
+
+1. Scan existing project facts first: `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, and current run/build scripts.
+2. Record discovered facts and open questions in `Harness/PLAN.md` before changing harness docs.
+3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md`, and `Harness/domain/ports.md` from observed project facts plus explicit user input.
+4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, settings, hooks, package files, CI, docs routers, or workflow docs unless the user explicitly approves that exact overwrite.
+5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
+6. Run `node Harness/scripts/validate-harness.mjs` after registration, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders have been resolved or intentionally recorded as open.
+
+### Agent-Link Install Intake
+
+When the user installs by pasting the GitHub link into an agent, ask intake questions before editing. Ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
+
+| Topic | Ask When | Default If Unanswered |
+| --- | --- | --- |
+| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
+| Harness location | `docs/` is already used for GitHub Pages, product docs, or generated docs | Use root `Harness/`; do not write harness docs into `docs/` |
+| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
+| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `readme-optimizer`; default to append-only Development notes until the user approves a structure pass or full rewrite |
+| Extensions | ECC, Superpowers, custom rules, or stack-specific skills may be useful | Recommend first; install only after user approval |
+| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant skills only after user approval |
+| CI/CD | CI config exists or the project lacks a test/build gate | Document existing commands first; add CI/CD only after user approval |
+| Verification depth | browser-visible, API, database, auth, payment, or deployment behavior is affected | Require real command evidence; require browser/API evidence when relevant |
+| Memory/privacy | repo contains sensitive domain data, customer data, secrets, or private workflows | Enable memory index only; never record secrets or private data |
+| Branch/worktree | project has uncommitted changes, risky migration, or parallel implementation lanes | Preserve current worktree; propose branch/worktree before broad edits |
+| Package manager/stack | multiple package managers, monorepo apps, or unclear stack boundaries exist | Ask which workspace/app is in scope before writing |
+
+### Agent Conflict Resolution Protocol
+
+When `--on-conflict skip` leaves existing files untouched, the agent resolves each conflict with user supervision.
+
+**Workflow:**
+
+1. Run the harness tool in planning mode to get the conflict list:
+   ```
+   npx create-harness-vibe-coding@latest . . -y --dry-run --json
+   ```
+   Parse the JSON output. Files in `plan.skip[]` need attention. Files in `plan.create[]` are handled automatically.
+
+2. For each skipped file, locate the harness template counterpart:
+   - From npm: `node_modules/create-harness-vibe-coding/templates/common/<path>`
+   - From GitHub: `https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/<path>`
+
+3. For each skipped file:
+   - Read the existing project file.
+   - Read the harness template counterpart.
+   - Compare sections and headings. Identify structural sections, registration entries, and required text patterns that exist in the template but are missing from the existing file.
+   - If the skipped file is `CLAUDE.md`, tell the user that it is the root agent entry contract. Ask whether they consent to refactor or merge it before editing. Preserve project-specific rules while adding the Harness startup, memory, router, workflow, and subagent orchestration contract.
+   - If the skipped file is `AGENTS.md`, tell the user that it is part of the root agent entry contract and ask whether they consent to merge or replace it before editing.
+   - Present each gap to the user as a choice:
+     - **[Merge]** — Edit the existing file to add only the missing sections. Preserve all existing content, ordering, and formatting.
+     - **[Overwrite]** — Replace with the template version. Optionally backup the original first (`--on-conflict backup`).
+     - **[Keep]** — Leave the existing file as-is. Skip this file.
+
+4. For Merge: use Edit (not Write) to add missing content. Only insert sections, headings, and text that are structurally required. Do not reorder or modify existing content. Do not remove custom project-specific registrations.
+
+5. After all merges, run `node Harness/scripts/validate-harness.mjs`. Fix any remaining validation errors, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders are resolved.
+
+**File-specific gap checklists:**
+
+The harness validator checks for specific structural invariants. When comparing existing files against templates, verify these are present. Most other template content can vary; only the items below are required.
+
+| File | Required check |
+|------|----------------|
+| `CLAUDE.md` | Must be merged only after user confirmation when it already exists. Required contract: `## 1. Harness Binding & Startup` with the `Harness/SETUP.md` bootstrap contract line; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); `Never bulk-read Harness/` in Startup |
+| `AGENTS.md` | Root agent entry points to `CLAUDE.md` and `Harness/README.md`; for existing projects, merge only after explicit user consent |
+| `README.md` | Existing README is project-owned. Preserve by default; ask whether to append only Development notes or run `readme-optimizer` for a structure pass with tables/diagrams before broad edits |
+| `Harness/MEMORY.md` | All 9 common agents registered under `## Agents`; all common harness skills registered under `## Skills`; all 3 `Harness/memory/` files registered under `## Memory Folder`; `Harness/memory/` folder usage guidance; `Project Resource Index` in title |
+| `.claude/rules/ecc/common.md` | `## Context` section with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` section with three reflection file entries; `## Security` section |
+| `Harness/README.md` | `## Keyword Routing` heading; `## Load By Task` table with at minimum the rows: "Adding harness to existing project", "Need implementation plan", "Need parallel agents", "Need subagents", "Need durable memory or reflection"; `## Doc Map` with `memory/` and `subagents.md` entries; the durable communication invariant text; `Harness/README.md is the primary router` |
+| `Harness/extension.md` | `## Non-Invasive Extension Rules` section with the "Preserve existing" rule; `## Agent Contract` section; `## Registration` section |
+| `Harness/dispatch.md` | The durable communication invariant; common agent entries for all 9 agents; `## Handoff Format` heading |
+| `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 10 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier) |
+| `Harness/subagents.md` | `## Source Attribution`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
+| `Harness/PLAN.md` | `## Current Goal`, `## Phase`, `## Success Criteria`, `## Loaded Context`, `## Tasks`, `## Parallel Dispatch`, `## Subagent Synthesis`, `## Verification` headings |
+| `Harness/SETUP.md` | Only meaningful for fresh projects. If the project has its own onboarding docs, skip this file entirely (it is temporary). If kept, ensure the "Existing Project Bootstrap Sequence" is present. |
+| `Harness/workflows/browser-e2e.md` (if installed as optional) | `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` requirement |
+| `Harness/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
+| `Harness/features/_template.md` | `## 1.5 UI Automation Hooks` with `data-testid` table |
+
+**Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
+
+- `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` — these are new empty files
+- `.claude/agents/*.md` — all 9 common agents
+- `.claude/skills/harness-*/SKILL.md`, `.claude/skills/wf-mode/SKILL.md`, and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills, WF mode, and subagent orchestration
+- `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
+- `.claude/settings.json` — harness settings
+- `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md`, `Harness/data-flow.md`, `Harness/state-machines.md` — harness runtime docs
+- `Harness/research/*.md` — research protocol and templates
+- `Harness/domain/ports.md` — port contract template
+- `AGENTS.md` — agent registry; if it already exists, ask for user consent before merging or replacing it
+- `Harness/scripts/validate-harness.mjs` and `tests/.gitkeep` — tooling
+
+Optional workflow examples:
+
+```bash
+npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
+npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
+```
 
 ### Template Fill Guide
 
-Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeholder expects. Replace all markers in the doc before moving to the next doc. If a section does not apply yet, leave the `{{...}}` but record why in `docs/harness/PLAN.md`.
+Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeholder expects. Replace all markers in the doc before moving to the next doc. If a section does not apply yet, leave the `{{...}}` but record why in `Harness/PLAN.md`.
 
-**`docs/research/PRD.md`** — Product scope. Fill with product facts from user input, not guesses:
+**`Harness/research/PRD.md`** — Product scope. Fill with product facts from user input, not guesses:
 - `{{WHY_THIS_PROJECT_EXISTS}}`: one-sentence motivation
 - `{{MUST_1..3}}`: concrete, testable MVP items (checkbox form)
 - `{{NON_GOAL_1..3}}`: explicitly out-of-scope items
@@ -56,25 +159,25 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - `{{ACCEPTANCE_1..3}}`: verifiable project-level acceptance criteria
 - `{{DIMENSION}}`, `{{TARGET}}`, `{{MEASUREMENT}}`: non-functional requirements (perf, security, etc.)
 
-**`docs/research/research-results.md`** — Tech decisions. Research before filling:
-- Use `docs/research/README.md` as the research protocol.
+**`Harness/research/research-results.md`** — Tech decisions. Research before filling:
+- Use `Harness/research/README.md` as the research protocol.
 - `{{CANDIDATE_1..3}}`: each candidate (framework, library, architecture style) with Purpose/Strength/Weakness/Decision/Link.
 - `{{Architecture Style}}`: the chosen architectural style (e.g., Hexagonal, Modular Monolith).
 - `{{CONSTRAINT_1..3}}`: hard technical constraints derived from research.
 - `{{ALTERNATIVE_1..2}}`: rejected candidates worth watching for future.
 
-**`docs/harness/architecture.md`** — Layer structure. Derive from research-results:
+**`Harness/architecture.md`** — Layer structure. Derive from research-results:
 - Fill the ASCII layer diagram with actual layer names. Do NOT add layers without a proven need.
 - `2.1–2.5`: describe each harness core component (Runner, Permission Policy, Event Bus, State Store, Tool Registry) in project-specific terms.
 - `3. Architectural Constraints`: add project-specific non-negotiables. Keep the domain/harness purity rules.
 
-**`docs/domain/ports.md`** — Cross-layer contracts. One driving port + one driven port from the first slice:
+**`Harness/domain/ports.md`** — Cross-layer contracts. One driving port + one driven port from the first slice:
 - `{{INBOUND_PORT_1}}`: the first inbound port (e.g., "CreateOrderPort").
 - `{{OUTBOUND_PORT_1}}`: the first outbound port (e.g., "OrderRepository").
 - For each port: fill Purpose, Preconditions, Postconditions, Error Semantics, Idempotency.
 - Leave remaining rows as `{{...}}` until more slices add ports.
 
-**`docs/harness/PLAN.md`** — Active execution state. Update continuously:
+**`Harness/PLAN.md`** — Active execution state. Update continuously:
 - `## Current Goal`: one sentence, what this iteration achieves.
 - `## Phase`: current lifecycle phase (Idea/Research/PRD/Architecture/Plan/Build/Verify/Feedback).
 - `## Success Criteria`: verifiable outcomes for this iteration.
@@ -82,13 +185,18 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - `## Parallel Dispatch`: only when spawning subagents — fill agent roles, read/write boundaries.
 - `## Verification`: record test results, review findings, docs sync checklist.
 
-**`docs/harness/data-flow.md`** — Runtime event paths (only when first slice has async/multi-step flow):
+**`Harness/memory/`** — Durable self-evolution notes:
+- `Harness/memory/tool-usage-reflections.md`: repeated tool failures, better command patterns, environment-specific fixes.
+- `Harness/memory/user-corrections-preferences.md`: repeated user corrections, durable preferences, common-sense course corrections.
+- `Harness/memory/agent-lessons-patterns.md`: reusable lessons from review, debugging, validation, and handoff loops.
+
+**`Harness/data-flow.md`** — Runtime event paths (only when first slice has async/multi-step flow):
 - `{{EVENT_1}}`: the first event type with producer, consumers, payload fields, delivery semantics.
 - Happy Path: fill the Mermaid sequence diagram with actual ports and actions.
 - Failure Paths: for each failure point, document trigger, system behavior, event, caller perception, recovery.
 - If the first slice is synchronous and stateless, leave this doc as `{{...}}` and note in PLAN.md.
 
-**`docs/harness/state-machines.md`** — State transitions (only when first slice has stateful entities):
+**`Harness/state-machines.md`** — State transitions (only when first slice has stateful entities):
 - Define states, transitions, guards, and illegal transitions for the first stateful entity.
 - If no stateful entity exists in the first slice, leave as `{{...}}` and note in PLAN.md.
 
@@ -96,11 +204,11 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - Replace `{{projectName}}` with the actual project name immediately.
 - Never invent content for a `{{...}}` marker. If you lack facts, ask the user or leave the marker.
 - `<!-- HTML comments -->` in templates are instructions to you. Read them. Delete them after filling the section.
-- After filling all templates in a phase, run `node scripts/validate-harness.mjs --strict`. Any remaining `{{...}}` in project-fact files will be flagged.
+- After filling all templates in a phase, run `node Harness/scripts/validate-harness.mjs --strict`. Any remaining `{{...}}` in project-fact files will be flagged.
 
 ## Architecture Research (Dynamic)
 
-Do not guess the architecture. Use `docs/research/README.md` as the protocol and the high-star repos below as seed references. Search within them; do not read them whole.
+Do not guess the architecture. Use `Harness/research/README.md` as the protocol and the high-star repos below as seed references. Search within them; do not read them whole.
 
 ### Seed Repositories (High-Star, High-Trust)
 
@@ -117,12 +225,12 @@ Do not guess the architecture. Use `docs/research/README.md` as the protocol and
 
 After research, fill these docs in order:
 
-1. `docs/research/research-results.md` — Record candidate architectures with Adopt / Reject / Watch decisions. Use the `## Candidate References` template.
-2. `docs/harness/architecture.md` — Fill the layering diagram, core components, and constraints. Do NOT add speculative layers. One layer per proven need.
-3. `docs/domain/ports.md` — Define ONE driving port and ONE driven port from the first vertical slice. More ports come with more slices.
-4. `docs/harness/data-flow.md` — Fill the happy path for the first slice only. Add failure paths when they differ from the happy path.
+1. `Harness/research/research-results.md` — Record candidate architectures with Adopt / Reject / Watch decisions. Use the `## Candidate References` template.
+2. `Harness/architecture.md` — Fill the layering diagram, core components, and constraints. Do NOT add speculative layers. One layer per proven need.
+3. `Harness/domain/ports.md` — Define ONE driving port and ONE driven port from the first vertical slice. More ports come with more slices.
+4. `Harness/data-flow.md` — Fill the happy path for the first slice only. Add failure paths when they differ from the happy path.
 
-**Constraint**: If the research does not give you enough confidence to fill a section, leave the `{{...}}` placeholder and record the open question in `docs/harness/PLAN.md`. The strict validator will catch it.
+**Constraint**: If the research does not give you enough confidence to fill a section, leave the `{{...}}` placeholder and record the open question in `Harness/PLAN.md`. The strict validator will catch it.
 
 ## User Confirmation Protocol (Non-Negotiable)
 
@@ -133,7 +241,7 @@ When user intent is unclear or ambiguous:
 - **Maximum 3 blocking questions per decision point.** Ask the highest-impact questions first.
 - **Do not act on assumptions that affect architecture, scope, stack, or user-facing behavior.**
 - **You must have ≥95% confidence before writing implementation code.** If below that threshold, stop and ask.
-- **Record every assumption explicitly** in `docs/harness/PLAN.md` so the user can correct it later.
+- **Record every assumption explicitly** in `Harness/PLAN.md` so the user can correct it later.
 - **Silent picks are forbidden.** If two valid approaches exist and you cannot decide with high confidence, present both to the user with trade-offs.
 
 False confidence is worse than a question. If you catch yourself thinking "this is probably what they want," stop and ask.
@@ -159,20 +267,20 @@ npx skills search "react testing"
 npx skills search "python api"
 ```
 
-**Manual discovery**: search GitHub and npm directly using patterns from `docs/research/README.md#Architecture Decision References`.
+**Manual discovery**: search GitHub and npm directly using patterns from `Harness/research/README.md#Architecture Decision References`.
 
 **Priority order**:
 1. `/find-skills` first — fastest discovery, respects your tool environment.
 2. Superpowers registry — broad community coverage.
 3. GitHub search — when the first two miss niche domains.
 
-**What to install**: after finding skills, add them to `.claude/skills/<name>/SKILL.md`. Follow `docs/harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
+**What to install**: after finding skills, add them to `.claude/skills/<name>/SKILL.md`. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
 
 This scaffold includes built-in harness skills (`.claude/skills/harness-*`). Keep those. Add stack-specific ones alongside them.
 
 ## Optional Agent Assets
 
-After the product shape is known, Claude may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Follow `docs/harness/extension.md` for every added asset.
+After the product shape is known, Claude may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Follow `Harness/extension.md` for every added asset.
 
 Examples:
 
@@ -186,14 +294,14 @@ This is a Go service. Add API, security, and integration-test agents.
 
 This file is designed to be orphaned. When all configuration is complete:
 
-1. Open `CLAUDE.md`. Delete the line: `If SETUP.md exists in the project root, read it first.`
+1. Open `CLAUDE.md`. Delete the setup bootstrap line that starts with: ``If `Harness/SETUP.md` exists, follow it before normal project work``.
 2. Delete this file.
 
 ```bash
-rm SETUP.md
+rm Harness/SETUP.md
 ```
 
-After both steps, `SETUP.md` is fully isolated — no file references it, no trace remains. You are free to delete it at any time. It is a bootstrap scaffold, not a permanent fixture.
+After both steps, `Harness/SETUP.md` is fully isolated — no file references it, no trace remains. You are free to delete it at any time. It is a bootstrap scaffold, not a permanent fixture.
 
 ---
 
@@ -213,7 +321,7 @@ npx create-harness-vibe-coding@latest my-agent-project ./my-agent-project -y
 
 After scaffolding, bootstrap the harness yourself:
 
-1. Read `CLAUDE.md`, `MEMORY.md`, and `docs/README.md`.
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 2. Follow the Required Bootstrap Sequence above.
-3. Run `node scripts/validate-harness.mjs --strict` when done.
-4. Delete `SETUP.md`.
+3. Run `node Harness/scripts/validate-harness.mjs --strict` when done.
+4. Delete `Harness/SETUP.md`.

package/templates/common/docs/README.md

@@ -1,8 +1,8 @@
 # {{projectName}} - Harness Router
 
-Purpose: route humans and agents to the smallest useful context.
+Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
 
-Default load: `CLAUDE.md`, `MEMORY.md`, this file, and `docs/harness/PLAN.md` when work is active. Do not read the whole docs tree.
+Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PLAN.md` when work is active. Do not read the whole `Harness/` tree.
 
 ## 0-1 Flow
 
@@ -10,19 +10,26 @@ Default load: `CLAUDE.md`, `MEMORY.md`, this file, and `docs/harness/PLAN.md` wh
 Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
 ```
 
-For the full phase contract, load [harness/lifecycle.md](harness/lifecycle.md).
+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 [PLAN.md](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 `readme-optimizer` 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`.
-- Phase rules live in [harness/lifecycle.md](harness/lifecycle.md).
-- Build, review, test, and subagent rules live in [harness/agent-workflow.md](harness/agent-workflow.md).
-- Parallel dispatch rules live in [harness/dispatch.md](harness/dispatch.md).
-- Extension rules live in [harness/extension.md](harness/extension.md).
-- Context-loading rules live in [harness/context-loading.md](harness/context-loading.md).
-- Progress lives in [harness/PLAN.md](harness/PLAN.md) and the current feature doc.
+- 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 [PLAN.md](PLAN.md) and the current feature doc.
 
 ## Keyword Routing
 
@@ -32,11 +39,11 @@ Use this only when the task is ambiguous or the matching row is unclear.
 2. Search the project docs first:
 
 ```bash
-rg -n "keyword1|keyword2|keyword3" CLAUDE.md MEMORY.md docs
+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 `docs/harness/PLAN.md`.
+4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/PLAN.md`.
 
 Keywords are retrieval hints, not project facts.
 
@@ -44,58 +51,76 @@ Keywords are retrieval hints, not project facts.
 
 Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
 
+Routing priority: if a request is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` may 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 | [harness/lifecycle.md](harness/lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
+| 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, domain, port, adapter, dependency | [harness/architecture.md](harness/architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
-| Need implementation plan | plan, task, write set, verify, milestone, progress | [harness/PLAN.md](harness/PLAN.md), [harness/agent-workflow.md](harness/agent-workflow.md) | tasks, write set, verification commands |
-| Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [harness/dispatch.md](harness/dispatch.md), [harness/context-loading.md](harness/context-loading.md), [harness/PLAN.md](harness/PLAN.md) | dispatch table, agent roles, read/write sets |
-| Adding stack-specific agents/skills | extension, agent, skill, rule, hook, stack-specific, compatibility | [harness/extension.md](harness/extension.md), [harness/dispatch.md](harness/dispatch.md) | compatible agents, skills, rules, hooks |
-| Need subagents | subagent, role pack, context, inject, return format | [harness/context-loading.md](harness/context-loading.md) | role-specific context pack |
-| Need feature work | feature, implementation, TDD, test, review, closeout | [features/_template.md](features/_template.md), [harness/agent-workflow.md](harness/agent-workflow.md) | feature doc, tests, implementation loop |
-| Flow or failure behavior changes | data flow, event, failure, retry, recovery, caller behavior | [harness/data-flow.md](harness/data-flow.md) | happy path, failure path, caller behavior |
-| Stateful behavior changes | state, transition, guard, illegal transition, state machine | [harness/state-machines.md](harness/state-machines.md) | states, transitions, illegal transitions |
-| Review or release check | review, release, finding, risk, evidence, verification | [harness/agent-workflow.md](harness/agent-workflow.md), current feature doc | findings, verification evidence |
-| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `scripts/validate-harness.mjs`, `scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
+| Need architecture or boundaries | architecture, boundary, layer, domain, port, adapter, dependency | [architecture.md](architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
+| Need WF mode | wf, /wf, workflow mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PLAN.md](PLAN.md) | exploration plan, second plan, heartbeat, recovery loop; load subagent docs only when needed |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PLAN.md](PLAN.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/readme-optimizer/SKILL.md`, [PLAN.md](PLAN.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 | [PLAN.md](PLAN.md), [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
+| Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [subagents.md](subagents.md), [dispatch.md](dispatch.md), [context-loading.md](context-loading.md), [PLAN.md](PLAN.md) | orchestration plan, dispatch table, agent roles, read/write sets |
+| Adding stack-specific agents/skills | extension, agent, skill, rule, hook, stack-specific, compatibility | [extension.md](extension.md), [dispatch.md](dispatch.md) | compatible agents, skills, rules, hooks |
+| Optional workflow installed | workflow, optional, browser-e2e, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md`, [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 | [features/_template.md](features/_template.md), [agent-workflow.md](agent-workflow.md) | feature doc, tests, implementation loop |
+| Flow or failure behavior changes | data flow, event, failure, retry, recovery, caller behavior | [data-flow.md](data-flow.md) | happy path, failure path, caller behavior |
+| Stateful behavior changes | state, transition, guard, illegal transition, state machine | [state-machines.md](state-machines.md) | states, transitions, illegal transitions |
+| 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 |
 
 ## Gates
 
 - Move phases in order unless the user asks for a fast lane.
+- Use `/wf` 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.
 - Do not cross a layer boundary without reading `domain/ports.md` and updating architecture or ports.
-- Before adding failure paths, read `harness/data-flow.md`.
-- Before modifying stateful components, read `harness/state-machines.md`.
-- Unsure whether to open a feature doc? Read `harness/agent-workflow.md` Section 1.
+- Before adding failure paths, read `data-flow.md`.
+- Before modifying stateful components, read `state-machines.md`.
+- Unsure whether to open a feature doc? Read `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/PLAN.md#Parallel Dispatch` and follow `harness/dispatch.md`.
-- Do not add stack-specific agents or skills without following `harness/extension.md`.
+- Before coordinating multiple agents, fill `PLAN.md#Parallel Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
+- In WF mode, update `PLAN.md#Heartbeat` before long commands, after failures, and at closeout.
+- 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 `harness/PLAN.md` or the feature doc.
-- Run `node scripts/validate-harness.mjs` for scaffold structure; run `node scripts/validate-harness.mjs --strict` after bootstrap and before release.
+- Do not mark work `Verified` until evidence is recorded in `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
-docs/README.md                  router only
-docs/harness/PLAN.md            active execution plan
-docs/harness/lifecycle.md       0-1 product flow
-docs/harness/context-loading.md dynamic loading and subagent packs
-docs/harness/dispatch.md       lightweight parallel dispatch protocol
-docs/harness/extension.md      stack-specific asset contract
-docs/harness/agent-workflow.md  build/review/test loop
-docs/harness/architecture.md    layer boundaries
-docs/harness/data-flow.md       runtime/failure paths
-docs/harness/state-machines.md  state transitions
-docs/domain/ports.md            cross-layer contracts
-docs/features/_template.md      feature work packet
-docs/research/README.md         research protocol
-docs/research/PRD.md            product scope
-docs/research/research-results.md research results
-scripts/validate-harness.mjs    lightweight harness gate
-.claude/agents/*                built-in common agents
-.claude/skills/*                skill-style dynamic loaders
+Harness/README.md                  router only
+Harness/MEMORY.md                  resource index
+Harness/PLAN.md                    active execution plan and heartbeat
+Harness/WF.md                      long-task workflow and recovery loop
+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/data-flow.md               runtime/failure paths
+Harness/state-machines.md          state transitions
+Harness/domain/ports.md            cross-layer contracts
+Harness/features/_template.md      feature work packet
+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
+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/*                   skill-style dynamic loaders
+.claude/skills/readme-optimizer/SKILL.md README preservation and optional structure pass
+.claude/commands/wf.md             slash command bridge into wf-mode
 ```

package/templates/common/docs/domain/ports.md

@@ -70,4 +70,4 @@ Fill in each port using the format below:
 
 ---
 
-> **Note**: The current ports.md is a template. Replace `{{...}}` placeholders with your project's domain details. Refer to `docs/harness/data-flow.md` to understand how ports are orchestrated.
+> **Note**: The current ports.md is a template. Replace `{{...}}` placeholders with your project's domain details. Refer to `Harness/data-flow.md` to understand how ports are orchestrated.

package/templates/common/docs/features/_template.md

@@ -1,6 +1,6 @@
 # {{FEATURE_NAME}}
 
-> **When to use**: Every PRD scope item in `research/PRD.md` Section 2 must have a feature doc — either a new one from this template, or an iteration on an existing one. Do not code a PRD scope item without a corresponding features doc.
+> **When to use**: Every PRD scope item in `Harness/research/PRD.md` Section 2 must have a feature doc — either a new one from this template, or an iteration on an existing one. Do not code a PRD scope item without a corresponding features doc.
 >
 > **New vs iterate**: If the scope item has ≥85% overlap with an existing feature doc, iterate the existing doc (bump `Version`, add a `## Changelog` entry). If overlap is below 85%, create a new file from this template. When in doubt, ask the user.
 
@@ -34,6 +34,16 @@
 - [ ] {{ACCEPTANCE_CRITERION_2}}
 - [ ] {{ACCEPTANCE_CRITERION_3}}
 
+### 1.5 UI Automation Hooks
+
+For TS/React or browser workflows, define required stable accessible labels/roles and stable test hooks such as `data-testid` before implementation. These selectors must cover critical UI controls and states so CDP, Playwright, and manual verification can target inputs, buttons, filters, rows, empty/error/loading states, dialogs, navigation, and submitted/saved/error feedback without brittle DOM paths.
+
+| Element / State | Accessible Role / Label | `data-testid` | Verification Target |
+| --- | --- | --- | --- |
+| {{INPUT_OR_CONTROL}} | {{ROLE_OR_LABEL}} | {{DATA_TESTID}} | {{PLAYWRIGHT_OR_MANUAL_CHECK}} |
+| {{EMPTY_ERROR_LOADING_OR_ROW_STATE}} | {{ROLE_OR_LABEL}} | {{DATA_TESTID}} | {{PLAYWRIGHT_OR_MANUAL_CHECK}} |
+| Not UI-facing | N/A | N/A | N/A |
+
 ---
 
 ## 2. Design
@@ -42,10 +52,10 @@
 
 | Area | Impacted? | Notes |
 | --- | --- | --- |
-| `harness/architecture.md` | {{YES_NO}} | {{NOTE}} |
-| `domain/ports.md` | {{YES_NO}} | {{NOTE}} |
-| `harness/data-flow.md` | {{YES_NO}} | {{NOTE}} |
-| `harness/state-machines.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/architecture.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/domain/ports.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/data-flow.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/state-machines.md` | {{YES_NO}} | {{NOTE}} |
 | tests | {{YES_NO}} | {{NOTE}} |
 
 ### 2.2 Allowed Write Set
@@ -122,11 +132,11 @@ Estimate the context budget for this feature. If the main agent would need to re
 
 ### 4.3 Docs Sync
 
-- [ ] `harness/architecture.md`
-- [ ] `domain/ports.md`
-- [ ] `harness/data-flow.md`
-- [ ] `harness/state-machines.md`
-- [ ] `research/research-results.md`
+- [ ] `Harness/architecture.md`
+- [ ] `Harness/domain/ports.md`
+- [ ] `Harness/data-flow.md`
+- [ ] `Harness/state-machines.md`
+- [ ] `Harness/research/research-results.md`
 - [ ] Not needed because {{REASON}}
 
 ### 4.4 Decision Log

package/templates/common/docs/harness/PLAN.md

@@ -12,6 +12,18 @@ Choose one: Idea / Research / PRD / Architecture / Plan / Build / Verify / Feedb
 
 Current: {{CURRENT_PHASE}}
 
+## Heartbeat
+
+Mode: normal
+Last beat: {{LAST_BEAT}}
+Current phase: {{CURRENT_PHASE}}
+Current blocker: {{CURRENT_BLOCKER_OR_NONE}}
+Next beat trigger: {{NEXT_BEAT_TRIGGER}}
+Failure count: 0
+Recovery action: {{RECOVERY_ACTION_OR_NONE}}
+
+Update this section before long commands, after long commands, before and after subagent handoffs, after failed verification, and before stopping for user input. In `wf-mode`, use this as the resume point after context loss or interruption.
+
 ## Progress Rules
 
 - Phase tracks lifecycle progress.
@@ -44,7 +56,7 @@ Forbidden:
 
 Keep this list short. Add only docs/files used for the current phase.
 
-- `docs/README.md`
+- `Harness/README.md`
 - `{{LOADED_DOC_OR_FILE}}`
 
 ## Tasks
@@ -55,12 +67,23 @@ Keep this list short. Add only docs/files used for the current phase.
 
 ## Parallel Dispatch
 
-Use [dispatch.md](dispatch.md) when more than one agent or bounded pass is useful.
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) when more than one agent or bounded pass is useful.
 
 | Task | Agent | Mode | Read Set | Write Set | Depends On | Output | Status |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | {{TASK}} | {{AGENT}} | Parallel Read / Serial Write / Isolated Worktree | `{{READ_SET}}` | `{{WRITE_SET_OR_NONE}}` | {{DEPENDENCY_OR_NONE}} | {{EXPECTED_OUTPUT}} | Pending |
 
+## Subagent Synthesis
+
+Agents used:
+Findings accepted:
+Findings rejected:
+Conflicts:
+Decisions:
+Next write set:
+Verification path:
+Residual risk:
+
 ## Agent Handoffs
 
 | Agent | Role | Context Pack | Result |