create-harness-vibe-coding 0.8.5 → 0.8.7

package/templates/common/Harness/subagents.md

@@ -1,15 +1,15 @@
-# Subagent Orchestration
+# Subagent Orchestration
 
 Purpose: coordinate subagents for speed without losing control of scope, evidence, or integration.
 
 Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or `/wf`.
 
-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 `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-
-Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](AGENT_ISOLATION.md)
-for role/context isolation and [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md)
-for PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, and
-REVIEW-GATE.
+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 `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+
+Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](AGENT_ISOLATION.md)
+for role/context isolation and [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md)
+for PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, and
+REVIEW-GATE.
 
 ## Source Attribution
 
@@ -54,30 +54,36 @@ Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
 | `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
 | `debugger` | reproduced failures, root cause isolation, smallest safe fix |
 | `verifier` | command execution, real browser/API checks, final evidence |
-| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
-| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
-
-## Acceptance Role Passes
-
-These are role passes that may be handled by the built-in roster above or by
-project-specific agents. They define context boundaries even when no dedicated
-agent file exists.
-
-| Role Pass | Default Agent | Reads | Writes |
-| --- | --- | --- | --- |
-| PRD Planner | `planner` | user request, memory, research | Mini PRD/task PLAN only |
-| Acceptance Agent | `planner` or `test-writer` | PRD, user scenarios, UI requirements | AC section only |
-| Contract Agent | `architect` or `test-writer` | PRD, AC, API/schema/UI requirements | UI/API/state contract section only |
-| Test Architect | `test-writer` | AC, contracts, test utilities | tests or test plan only |
-| Implementer | `implementer` | PRD, AC, contracts, tests, relevant code | assigned implementation write set only |
-| Independent Validator | `verifier` | PRD, AC, contracts, running app/API, commands | validation report/evidence only |
-| Debugger | `debugger` | failed AC, logs, trace, screenshot, diff | smallest assigned fix set |
-
-Hard rule: implementer may not be the independent validator for the same AC ID.
+| `reflector` | closeout synthesis, unresolved-risk check, acceptance gate verdict |
+| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
+| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
+
+## Acceptance Role Passes
+
+These are role passes that may be handled by the built-in roster above or by
+project-specific agents. They define context boundaries even when no dedicated
+agent file exists.
+
+| Role Pass | Default Agent | Reads | Writes |
+| --- | --- | --- | --- |
+| PRD Planner | `planner` | user request, memory, research | Mini PRD/task PLAN only |
+| Acceptance Agent | `planner` or `test-writer` | PRD, user scenarios, UI requirements | AC section only |
+| Contract Agent | `architect` or `test-writer` | PRD, AC, API/schema/UI requirements | UI/API/state contract section only |
+| Test Architect | `test-writer` | AC, contracts, test utilities | tests or test plan only |
+| Implementer | `implementer` | PRD, AC, contracts, tests, relevant code | assigned implementation write set only |
+| Independent Validator | `verifier` | PRD, AC, contracts, running app/API, commands | validation report/evidence only |
+| Cross Review | `reviewer` | PRD, AC, contracts, diff, tests, validation evidence | spec/AC and code/architecture/test findings only |
+| Reflector | `reflector` | validation evidence, reviewer findings, risks, decisions | final PASS/RETURN_TO_DEBUG/BLOCKED verdict only |
+| Debugger | `debugger` | failed AC, logs, trace, screenshot, diff | smallest assigned fix set |
+
+Hard rule: implementer may not be the independent validator for the same AC ID.
 
 ## WF Default Fan-Out
 
-Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` requires at least 3 distinct agents from `.claude/agents/` before second planning.
+Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` requires complete
+role-chain coverage from `.claude/agents/` before closeout: plan,
+research/docs research as needed, architecture, test, implement, independent
+validation, cross-review, reflector, and accept.
 
 Default starter set:
 
@@ -89,13 +95,14 @@ Then add phase-specific agents:
 
 - `test-writer` before implementation
 - `implementer` for the serial write lane
-- `reviewer` for spec and code-quality gates
+- `reviewer` for independent spec/AC and code/architecture/test gates
 - `debugger` after a reproduced verification failure
-- `verifier` for final command/browser/API evidence
+- `verifier` for command/browser/API evidence and AC matrix
+- `reflector` after cross-review to decide whether final acceptance may proceed
 - `context-master` before closeout for knowledge extraction
 - `memory-master` after repeated failures and during closeout for consolidation
 
-Collaboration mode is determined by concrete conditions, not a fixed ratio. See `Harness/WF.md#Multi-Subagent Requirement` for the full decision tree. Summary: explicit WF/WK mode → always multi-agent. 3+ files or cross-layer → multi-agent. 1-2 local files, well-understood, not in WF mode → solo acceptable. Repeated failure → stop solo, switch to multi-agent.
+Collaboration mode is determined by concrete conditions, not a fixed ratio. See `Harness/WF.md#Complete Role Chain Requirement` for the full decision tree. Summary: explicit WF/WK mode always uses the complete role chain. 3+ files or cross-layer work uses multi-agent orchestration. 1-2 local files, well-understood, not in WF mode can be solo. Repeated failure stops solo work and switches to multi-agent.
 
 ## Efficiency Ladder
 
@@ -106,11 +113,24 @@ Choose the cheapest coordination level that is safe.
 | Solo pass | one file, low risk, clear intent | no subagent |
 | Single reviewer | small change with meaningful risk | implement, then reviewer |
 | Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
-| Serial build lane | normal feature or fix | acceptance/contract -> test-writer -> implementer -> independent validator -> reviewers |
-| Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
-| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
-
-Default for automatic WF triggers: 3-5 active read-only agents before second planning. For explicit WF/WK mode, never use the solo pass unless subagents are unavailable; use bounded role passes as the recorded fallback.
+| Serial build lane | normal feature or fix | acceptance/contract -> test-writer -> implementer -> verifier evidence -> cross-review -> reflector -> acceptance |
+| Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
+| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
+
+Max parallelism removes the Harness default cap, not the runtime's physical or
+account cap. For WF-MAX, record the current runtime budget, use native
+subagents first, close completed agents before declaring the pool exhausted,
+then overflow to the other CLI (`claude -p` or `codex exec`) with explicit
+dispatch packets. Generated Harness Codex config defaults to
+`agents.max_threads = 12` and `agents.max_depth = 1`; if that becomes the
+bottleneck, ask the user before raising `agents.max_threads` and keep
+`max_depth = 1` unless recursive delegation is explicitly approved. Do not rely
+on undocumented fork/derive bypasses as stable capacity.
+
+Default for automatic WF triggers: 3-5 active read-only agents before second
+planning. For explicit WF/WK mode, never use the solo pass; schedule the
+complete role chain and use bounded role passes as the recorded fallback when
+subagents are unavailable.
 
 ## WF Orchestration Shape
 
@@ -119,12 +139,12 @@ controller intake
 -> parallel planner/researcher/docs-researcher/architect subagents
 -> controller synthesis
 -> second plan with dependencies and write sets
--> acceptance/contract/test-writer
--> implementer
--> independent validator
--> spec reviewer
--> code/architecture reviewer
--> if failed: debugger/fixer -> review -> verify -> loop
+-> acceptance/contract/test-writer
+-> implementer
+-> independent validator
+-> cross-review: spec/AC reviewer + code/architecture/test reviewer
+-> reflector
+-> if failed: debugger/fixer -> verify -> cross-review -> reflector -> loop
 -> close with evidence
 ```
 
@@ -134,19 +154,20 @@ Use this shape for `/wf`, long tasks, multi-file changes, architecture work, mig
 /wf max orchestration shape:
 controller intake
 -> wave 0: max-parallel exploration (4-14 read-only agents)
--> E-GATE: Exploration Gate — all questions answered, findings synthesized (per WF-MAX.md)
--> wave 1: architecture — 3 parallel architects → boundary decisions + interface contract
--> D-GATE: Write Decomposition Gate — Dispatch Table + Self-Audit for write-set (MANDATORY, per WF-MAX.md)
+-> E-GATE: Exploration Gate - all questions answered, findings synthesized (per WF-MAX.md)
+-> wave 1: architecture - 3 parallel architects -> boundary decisions + interface contract
+-> D-GATE: Write Decomposition Gate - Dispatch Table + Self-Audit for write-set (MANDATORY, per WF-MAX.md)
 -> wave 2: N parallel implementers (disjoint file claims, ALL spawned in ONE message)
 -> wave 2 review: parallel spec/code/security reviewers
 -> wave 3+: dependent implementers (if any; re-run D-GATE if write-set changed)
 -> integration verifier
+-> reflector after cross-review
 -> closeout with evidence
 ```
 
 ## Dispatch Pack
 
-Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained — inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
+Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
 
 ## Parallelism Rules
 
@@ -159,15 +180,16 @@ Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Ev
 
 ## Review Gates
 
-Implementation is not complete until both gates pass:
+Implementation is not complete until cross-review and reflection pass:
 
-1. **Spec review**: confirms the result matches the user request, PRD, feature doc, acceptance criteria, contracts, and non-goals. Extra features are failures.
-2. **Code-quality review**: checks correctness, maintainability, architecture, tests, security, and integration risk.
-
-Validation is separate from review. Validator must produce an AC-by-AC result
-matrix from running behavior and evidence, not from the implementer's summary.
+1. **Spec review**: confirms the result matches the user request, PRD, feature doc, acceptance criteria, contracts, and non-goals. Extra features are failures.
+2. **Code-quality review**: checks correctness, maintainability, architecture, tests, security, and integration risk.
+3. **Reflector gate**: checks reviewer findings, verifier evidence, unresolved risks, and contradictions; returns PASS, RETURN_TO_DEBUG, or BLOCKED.
+
+Validation is separate from review. Validator must produce an AC-by-AC result
+matrix from running behavior and evidence, not from the implementer's summary.
 
-If either reviewer finds issues, the implementer or debugger fixes them and the same gate runs again. Do not move to verifier with open critical/high findings.
+If either reviewer finds issues, the implementer or debugger fixes them and the same gate runs again. Do not move to final acceptance with open critical/high findings or without reflector PASS.
 
 ## Subagent Status Handling
 
@@ -199,9 +221,9 @@ Findings rejected:
 Conflicts:
 Decisions:
 Next write set:
-Verification path:
-Acceptance/contract traceability:
-Residual risk:
+Verification path:
+Acceptance/contract traceability:
+Residual risk:
 ```
 
 Only the synthesis and named files enter main context. Do not replay full subagent conversations.

package/templates/common/Harness/tasks/_template/ARTIFACTS.md

@@ -1,3 +1,3 @@
-# {{TASK_ID}} — Artifacts
+# {{TASK_ID}} - Artifacts
 
 Optional: screenshots, logs, API responses, links. Create only when evidence is too large for this task's PLAN.md verification table.

package/templates/common/Harness/tasks/_template/NOTES.md

@@ -1,3 +1,3 @@
-# {{TASK_ID}} — Notes
+# {{TASK_ID}} - Notes
 
 Optional: exploration notes, design alternatives, research leads. Create only when notes are too long for this task's PLAN.md.

package/templates/common/Harness/tasks/_template/PLAN.md

@@ -1,82 +1,75 @@
-# {{TASK_ID}} — PLAN
-
-Task-level implementation plan and evidence. Main agent writes after second planning; implementer reads before coding.
-
+# {{TASK_ID}} - PLAN
+
+Compact task record. Keep only facts needed to resume, review, and verify.
+Link files or command names instead of pasting logs or subagent transcripts.
+
+> Task ID: kebab-case, under 60 chars. Directory name = task ID.
+
 ## Goal
 
-## Mini PRD
+- Outcome:
+- Non-goals:
 
-Scope:
-- 
+## Decisions
 
-Non-scope:
-- 
+-
 
-User flow:
-1. 
+## Acceptance
 
-UI elements:
-- 
+Default: keep 1-3 concise ACs. Expand only for UI/API/security/data-loss,
+cross-module, or other high-risk behavior.
 
-API behavior:
-- 
+- AC-001:
 
-## Acceptance Criteria
+Expanded evidence required when triggered:
+- UI/browser-visible: add selector contract and real browser evidence.
+- API/integration: add endpoint/payload/response contract.
+- High-risk behavior: add AC-by-AC validation matrix.
 
-| AC ID | Given / When / Then | Verification | Evidence |
-|-------|----------------------|--------------|----------|
-| AC-001 |  |  |  |
+## Scope
 
-## UI Contract
+Allowed write set:
+-
 
-| Element | Selector / Role | States | AC IDs |
-|---------|-----------------|--------|--------|
+Forbidden:
+-
+- Truth files (PRD, ACs, UI/API contracts, test plan, validation report) unless a Change Request is recorded.
 
-## API Contract
+## Context
 
-| Endpoint | Method | Payload / Response | AC IDs |
-|----------|--------|--------------------|--------|
+- Loaded:
+- Assumptions:
 
-## Test Plan
+## Agents
 
-For browser-visible ACs, include real user actions and evidence. Syntax-only checks, import tests, shallow renders, typecheck, lint, and build success are not acceptance evidence for UI behavior.
+Only record agents or bounded passes that materially changed the decision.
+
+| Role | Read / Write Set | Result |
+|------|------------------|--------|
 
-| AC ID | Test Level | User Action / API Request | Command / File | Evidence | Status |
-|-------|------------|---------------------------|----------------|----------|--------|
-
-## Scope
-
-Allowed write set:
-- 
-
-Forbidden:
-- 
-- PRD / acceptance criteria / UI contract / API contract / test plan / validation report unless Change Request is recorded
-
-## Loaded Context
-
-- 
-
-## Subagent Dispatch
-
-| Agent | Mode | Read Set | Write Set | Status |
-|-------|------|----------|-----------|--------|
-
-## Subagent Synthesis
-
-Agents used:
-Findings accepted:
-Findings rejected:
-Conflicts:
-Decisions:
-Residual risk:
-
 ## Verification
 
-| Check | Result | Notes |
-|-------|--------|-------|
+- [ ]
+
+## Risks
+
+-
+
+## Expanded Contracts
+
+Use this section only when the Acceptance triggers above apply.
+
+### UI Contract
+
+| Element | Selector / Role | States | AC IDs |
+|---------|-----------------|--------|--------|
+
+### API Contract
+
+| Endpoint | Method | Payload / Response | AC IDs |
+|----------|--------|--------------------|--------|
 
-## Acceptance Result
+### Validation Matrix
 
 | AC ID | Result | Evidence | Notes |
 |-------|--------|----------|-------|

package/templates/common/Harness/tasks/_template/PROGRESS.md

@@ -1,29 +1,26 @@
-# {{TASK_ID}} — PROGRESS
-
-Task-level progress and heartbeat. Main agent updates; subagents read only.
-
-## Current Goal
-
-## Phase
-
-Current: Intake
-
-## Heartbeat
-
-Last beat:
-Current phase: Intake
-Current blocker: none
-Next beat trigger:
-Failure count: 0
-Recovery action: none
-
-## Tasks
-
-| # | Task | Owner | Verify | Status |
-|---|------|-------|--------|--------|
-| 1 | Define goal and scope | main agent | recorded above | Pending |
-
-## Agent Handoffs
-
-| Agent | Role | Context Pack | Result |
-|-------|------|-------------|--------|
+# {{TASK_ID}} - PROGRESS
+
+Compact heartbeat. Update on phase changes, blockers, failures, and closeout.
+Do not paste logs; record the command/file that proves the state.
+
+## Status
+
+- Phase: Intake
+- Next:
+- Blocker: none
+
+## Tasks
+
+- [ ] Define goal and scope
+
+## Changes
+
+-
+
+## Verification
+
+-
+
+## Notes
+
+-

package/templates/common/MEMORY.md

@@ -5,37 +5,38 @@
 
 ## Agents (Sub-agents)
 
-- [researcher](../.claude/agents/researcher.md) — product, market, open-source, dependency, pricing, policy, and ecosystem research.
-- [docs-researcher](../.claude/agents/docs-researcher.md) — official docs, API, SDK, config, limits, errors, and examples verification.
-- [planner](../.claude/agents/planner.md) — task split, dependencies, write sets, and dispatch table.
-- [architect](../.claude/agents/architect.md) — boundaries, ports, data-flow, and state impact.
-- [test-writer](../.claude/agents/test-writer.md) — failing tests or manual verification before implementation.
+- [researcher](../.claude/agents/researcher.md) - product, market, open-source, dependency, pricing, policy, and ecosystem research.
+- [docs-researcher](../.claude/agents/docs-researcher.md) - official docs, API, SDK, config, limits, errors, and examples verification.
+- [planner](../.claude/agents/planner.md) - task split, dependencies, write sets, and dispatch table.
+- [architect](../.claude/agents/architect.md) - boundaries, ports, data-flow, and state impact.
+- [test-writer](../.claude/agents/test-writer.md) - failing tests or manual verification before implementation.
 - [tdd-guide](../.claude/agents/tdd-guide.md) - AC-linked RED tests, browser UI acceptance, and Playwright/CDP evidence before implementation.
-- [implementer](../.claude/agents/implementer.md) — bounded implementation inside declared write set.
-- [debugger](../.claude/agents/debugger.md) — smallest fix for a reproduced failure.
-- [reviewer](../.claude/agents/reviewer.md) — read-only diff review and closeout risk.
-- [verifier](../.claude/agents/verifier.md) — verification commands and evidence.
-- [memory-master](../.claude/agents/memory-master.md) — memory writing, dedup, consolidation, and cross-project knowledge extraction.
-- [context-master](../.claude/agents/context-master.md) — context analysis, compression alerts, and session knowledge extraction for memory-master.
-- [explore-manager](../.claude/agents/explore-manager.md) — WF-MAX W0 exploration: spawn 5-10 read-only researchers, synthesize, report to CEO.
-- [architect-manager](../.claude/agents/architect-manager.md) — WF-MAX W1 architecture: spawn 3 architects, synthesize interface contracts, report to CEO.
-- [implement-manager](../.claude/agents/implement-manager.md) — WF-MAX W2 implementation: spawn 5-7 implementers (one file_claim each), merge, report to CEO.
-- [review-manager](../.claude/agents/review-manager.md) — WF-MAX W2R review: spawn 3-4 reviewers (spec/code/security/perf), deduplicate, classify severity, report to CEO.
+- [implementer](../.claude/agents/implementer.md) - bounded implementation inside declared write set.
+- [debugger](../.claude/agents/debugger.md) - smallest fix for a reproduced failure.
+- [reviewer](../.claude/agents/reviewer.md) - read-only spec/AC and code/architecture/test review.
+- [verifier](../.claude/agents/verifier.md) - verification commands and AC evidence matrix.
+- [reflector](../.claude/agents/reflector.md) - closeout synthesis, contradiction check, and final acceptance gate verdict.
+- [memory-master](../.claude/agents/memory-master.md) - memory writing, dedup, consolidation, and cross-project knowledge extraction.
+- [context-master](../.claude/agents/context-master.md) - context analysis, compression alerts, and session knowledge extraction for memory-master.
+- [explore-manager](../.claude/agents/explore-manager.md) - WF-MAX W0 exploration: spawn 5-10 read-only researchers, synthesize, report to CEO.
+- [architect-manager](../.claude/agents/architect-manager.md) - WF-MAX W1 architecture: spawn 3 architects, synthesize interface contracts, report to CEO.
+- [implement-manager](../.claude/agents/implement-manager.md) - WF-MAX W2 implementation: spawn 5-7 implementers (one file_claim each), merge, report to CEO.
+- [review-manager](../.claude/agents/review-manager.md) - WF-MAX W2R review: spawn 3-4 reviewers (spec/code/security/perf), deduplicate, classify severity, report to CEO.
 
 Stack-specific agents can be added after the product shape is known.
 
 ## Skills (Workflows)
 
-- [WF Mode](WF.md) — long-task workflow: exploration, second plan, implementation, review, verification, heartbeat, and recovery loop.
-- [wf](../.claude/skills/wf/SKILL.md) — Claude Code WF skill command; mirrored for Codex at `../.agents/skills/wf/SKILL.md`.
-- [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) — controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
-- [wf-readme](../.claude/skills/wf-readme/SKILL.md) — README preservation, append-only development sections, structured tables, and approved architecture diagrams.
-- [wf-review](../.claude/skills/wf-review/SKILL.md) — cross-model peer review: invoke the other agent CLI (Codex/Claude) for independent review.
-- [wf-update](../.claude/skills/wf-update/SKILL.md) — GitHub-based incremental harness update, checksum comparison, and safe in-place updates.
-- [wf-learn](../.claude/skills/wf-learn/SKILL.md) — force memory learning cycle: context-master -> memory-master -> project + global memory.
-- [wf-max](../.claude/skills/wf-max/SKILL.md) — maximum-parallelism workflow: write-set coloring, wave dispatch, parallel review per dimension.
+- [WF Mode](WF.md) - complete role chain: plan, research/docs, architecture, test, implement, validation, cross-review, reflector, acceptance.
+- [wf](../.claude/skills/wf/SKILL.md) - Claude Code WF skill command; mirrored for Codex at `../.agents/skills/wf/SKILL.md`.
+- [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) - controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
+- [wf-readme](../.claude/skills/wf-readme/SKILL.md) - README preservation, append-only development sections, structured tables, and approved architecture diagrams.
+- [wf-review](../.claude/skills/wf-review/SKILL.md) - cross-model peer review: invoke the other agent CLI (Codex/Claude) for independent review.
+- [wf-update](../.claude/skills/wf-update/SKILL.md) - GitHub-based incremental harness update, checksum comparison, and safe in-place updates.
+- [wf-learn](../.claude/skills/wf-learn/SKILL.md) - force memory learning cycle: context-master -> memory-master -> project + global memory.
+- [wf-max](../.claude/skills/wf-max/SKILL.md) - WF strict superset: complete role chain plus maximum parallelism, current runtime subagents first, cross-CLI overflow when available.
 - [wf-auto](../.claude/skills/wf-auto/SKILL.md) - perpetual auto-optimization: bounded ticks, 8-angle internal scan, intent checkpoints, evidence ledger.
-- [wf-auto-spark](../.claude/skills/wf-auto-spark/SKILL.md) — perpetual inspiration mode: external spark search, long-term roadmap with staged milestones, ≤50% deviation guard.
+- [wf-auto-spark](../.claude/skills/wf-auto-spark/SKILL.md) - perpetual inspiration mode: external spark search, long-term roadmap with staged milestones, <=50% deviation guard.
 - [tdd](../.claude/skills/tdd/SKILL.md) - acceptance-driven TDD: AC-linked RED tests, real UI clicks for browser-visible behavior, Playwright/CDP evidence, and configured coverage gate.
 - [wf-remove](../.claude/skills/wf-remove/SKILL.md) - safely remove Harness framework files (SAFE/MODIFIED/USER classes), auto-prune empty directories, backup option.
 
@@ -47,15 +48,11 @@ Codex repo-skill mirrors live under `../.agents/skills/` with the same skill nam
 
 Stack-specific skills can be added after the product shape is known.
 
-- [browser-e2e](workflows/browser-e2e.md)
-
-Stack-specific skills can be added after the product shape is known.
-
 ## Rules (Harness Constraints)
 
 Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 
-- [common.md](../.claude/rules/ecc/common.md) — universal harness constraints for context loading, verification, subagents, and security (alwaysApply: true)
+- [common.md](../.claude/rules/ecc/common.md) - universal harness constraints for context loading, verification, subagents, and security (alwaysApply: true)
 - Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
 
 ## Harness (Runtime)

package/templates/common/SETUP.md

@@ -31,7 +31,7 @@ First clarify the idea, then create Mini PRD, acceptance criteria, UI/API contra
 
 ## Required Bootstrap Sequence
 
-Claude must follow this order:
+Claude or Codex must follow this order during bootstrap. This sequence is broader than installation; if the user only asked to install/configure the harness in an existing project, follow the "Existing Project Fast Path" below and stop after the non-strict validator passes.
 
 0. **ECC Stack Configuration** — Detect the project's tech stack. If the repo is empty or has no stack markers (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `composer.json`, `build.gradle`, etc.), ask the user: "What's your tech stack? (language/framework)" Then install the matching ECC rule sets from `~/.claude/rules/ecc/`. See `Harness/ECC-GUIDE.md` for the stack→rules mapping. Minimum: always install `common/`. Verify with `ls .claude/rules/ecc/`.
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/lifecycle.md`, and `Harness/ACCEPTANCE_PROTOCOL.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
@@ -45,8 +45,8 @@ Claude must follow this order:
 9. Implement only after PRD-GATE, AC-GATE, CONTRACT-GATE, and TEST-GATE pass.
 10. Independently validate with an AC-by-AC result matrix; use `Harness/HARNESS_BRIDGE.md` for browser/API/CDP flows.
 11. For `/wf-auto` or memory scenario hints, read `Harness/WF-AUTO.md` and `Harness/MEMORY_PROTOCOL.md`; do not enable a background runner by default. The only allowed runtime hook is the optional `/wf-auto` bounded tick hook.
-11. Run `node Harness/scripts/validate-harness.mjs --strict`.
-12. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
+12. Run `node Harness/scripts/validate-harness.mjs --strict` after project-fact placeholders are resolved.
+13. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
 
 ## Install or Upgrade Path
 
@@ -59,20 +59,25 @@ Before writing, identify the project state:
 | Legacy architecture or older project docs | Treat existing code/docs as source of truth, dry-run first, then fill PRD, research, architecture, and task plans from observed facts |
 | Existing `Harness/` | Do not use `npx` as an updater; ask whether to run `/wf-update`, `$wf-update`, `node Harness/scripts/wf-update-check.mjs`, keep untouched, or remove/reinstall after approval |
 
-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. Get the machine-readable install report first with `npx create-harness-vibe-coding@latest <project-name> <target-dir> -y --dry-run --on-conflict skip --json`. Use `scan.markers` and `agent.aiMergeRequired` instead of hand-written root probes for install decisions. Do manual project-fact reading only after the script has created missing Harness files.
-2. Record discovered facts and open questions in `Harness/tasks/<task-id>/PROGRESS.md` before changing harness docs.
-3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md` from observed project facts plus explicit user input.
+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.
+
+### Existing Project Fast Path
+
+Use this path when the user asks only to install or configure the harness in an existing project. Do not bootstrap PRD, research, architecture, or task capsules unless the user explicitly asks for bootstrap.
+
+1. Get the machine-readable install report first with `npx create-harness-vibe-coding@latest <project-name> <target-dir> -y --dry-run --on-conflict skip --json`. Use `scan.markers` and `agent.aiMergeRequired` instead of hand-written root probes for install decisions. Do manual project-fact reading only after the script has created missing Harness files.
+2. Run the JSON `agent.safeMergeCommand` to create only missing files.
+3. Record discovered facts in the final install summary. Create or update task capsules only when bootstrap or multi-step implementation work begins.
 4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, package files, CI, docs routers, workflow docs, or installed skills/plugins/rules 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 --strict` after project-fact placeholders have been resolved or intentionally recorded as open. Use the non-strict validator only for early structural checks.
+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` as the install-complete gate.
+7. Defer `node Harness/scripts/validate-harness.mjs --strict` until bootstrap removes project-fact placeholders. If placeholders intentionally remain, report strict validation as deferred rather than treating install as failed.
 
 `npx create-harness-vibe-coding` is an install/safe-merge entry, not an update engine for a project that already has an installed Harness. If `Harness/` already exists, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs`; root entry files and user-modified Harness docs require agent-mediated merge decisions.
 
 ### Agent-Link Install Intake
 
-When the user installs by pasting the GitHub link into an agent, get the JSON install report before editing or asking generic questions. Summarize `scan.markers`, then 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.
+When the user installs by pasting the GitHub link into an agent, get the JSON install report before editing or asking generic questions. Do not fetch full template files or read package source until `agent.aiMergeRequired` names a file that needs semantic comparison. Summarize `scan.markers`, then 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 |
 | --- | --- | --- |
@@ -117,9 +122,9 @@ When `--on-conflict skip` leaves existing files untouched, the script still owns
      - **[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 --strict` once after project-fact placeholders are resolved. Run the non-strict validator earlier only when you need a quick structural check before bootstrap is complete.
+4. For Merge: use targeted edits, not a full-file rewrite. In Codex, use `apply_patch` or an equivalent patch operation. Only insert sections, headings, and text that are structurally required. Do not reorder or modify existing content. Do not remove custom project-specific registrations. After merging `CLAUDE.md` or `AGENTS.md`, inspect the heading outline and remove duplicate headings or repeated bullets introduced by the merge.
+
+5. After all install merges, run `node Harness/scripts/validate-harness.mjs`. Run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders are resolved during bootstrap or release preparation.
 
 **File-specific gap checklists:**
 
@@ -131,12 +136,12 @@ The harness validator checks for specific structural invariants. When comparing
 | `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 `wf-readme` for a structure pass with tables/diagrams before broad edits |
 | `Harness/MEMORY.md` | All 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 |
+| `.claude/rules/ecc/common.md` | Required project-local universal rules. Keep it even when global `~/.claude/rules/ecc/common/` exists; that directory and this file have different scopes. Required sections: `## Context` with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` with three reflection file entries; `## Security` |
 | `Harness/README.md` | `## Keyword Routing` heading; `## Load By Task` table with at minimum the rows: "Need WF mode", "Adding harness to existing project", "Need implementation plan", "Need parallel agents", "Need subagents", "Need durable memory or reflection"; WF routing keywords include `/wf`, `wf mode`, `workflow mode`, and `wk mode`; explicit WF/WK output says subagent docs load immediately; `## Doc Map` with `memory/` and `subagents.md` entries; the durable communication invariant text; `Harness/README.md is the primary router` |
-| `Harness/WF.md` | `WF mode requires multi-subagent orchestration by default`; explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` requires at least 3 distinct role passes before second planning; `collaboration decision tree`; `Heartbeat Protocol` |
+| `Harness/WF.md` | `WF mode requires the complete role chain by default`; explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` requires plan, research/docs, architecture, test, implement, validation, cross-review, reflector, and acceptance before closeout; `collaboration decision tree`; `Heartbeat Protocol` |
 | `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/dispatch.md` | The durable communication invariant; registered common agent entries; `## Handoff Format` heading |
+| `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 12 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier, Memory Master, Context Master) |
 | `Harness/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `collaboration decision tree`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
 | `Harness/architecture.md` | `## 2. Interface Decoupling`; `## 3. State Design`; `Avoid speculative abstraction`; layer constraints derived from actual project facts |
 | `Harness/PROGRESS.md` | global task index with Active Task and task history; cross-task decisions |
@@ -146,12 +151,14 @@ The harness validator checks for specific structural invariants. When comparing
 | `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 |
 
-**Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
+**Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
+
+The generated file list is authoritative by path, not by stale count labels. Current common scaffolds include WF-MAX manager agents and `tdd-guide`; keep every file created by the scaffold unless a removal workflow explicitly classifies it as safe to remove.
 
 - `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/agents/*.md` - all built-in common agent files, including WF-MAX managers and `tdd-guide`
 - `.claude/skills/*.md` and mirrored `.agents/skills/*.md` — Claude Code and Codex skill adapters over the same Harness docs
-- `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
+- `.claude/rules/ecc/common.md` - required project-local universal rules. Do not delete this file as a duplicate of a global `~/.claude/rules/ecc/common/` directory; they are different scopes.
 - `.claude/settings.json` — harness settings
 - `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs
 - `Harness/research/*.md` — research protocol and templates
@@ -314,5 +321,5 @@ After scaffolding, use the JSON output first. Files in `plan.create[]` were hand
 
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 2. Follow the Required Bootstrap Sequence above.
-3. Run `node Harness/scripts/validate-harness.mjs --strict` when done.
+3. Run `node Harness/scripts/validate-harness.mjs` after install. Run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap resolves project-fact placeholders.
 4. Delete `Harness/SETUP.md`.