create-harness-vibe-coding 0.6.4 → 0.7.0

package/templates/common/CLAUDE.md

@@ -1,77 +1,94 @@
-# CLAUDE.md
-
-This repository dogfoods the generated Harness scaffold. Scaffold source files live under `templates/common/` and `templates/optional/`; generated dogfood runtime files live under root `Harness/` and `.claude/`.
-
-## 1. Harness Binding & Startup
-
-- If `Harness/` exists, this repository is governed by the Harness contract. Treat these files as mandatory operating instructions, not optional references.
-- Every session: load `Harness/MEMORY.md` first, then `Harness/README.md`.
-- If `Harness/SETUP.md` exists, follow it before normal project work; it is the install/bootstrap contract and may be deleted after setup is complete.
-- `Harness/MEMORY.md` is the memory/resource router: agents, skills, durable memories, and cross-session lessons. Follow its registrations when selecting agents/skills or recording memory.
-- `Harness/README.md` is the task router. For every request, check `Harness/README.md#Load By Task`; if a row matches, read and follow those docs before acting.
-- `Harness/PROGRESS.md` is the global task index. Load at session start to see active task and task history.
-- If work spans more than one step, create a task capsule from `Harness/tasks/_template/` and update `Harness/tasks/<task-id>/PROGRESS.md`.
-- Use `/wf <task>`, `/wf-review [focus]`, `wf mode`, `workflow mode`, or `wk mode` for long, difficult, uncertain, multi-file, or repeated-failure work.
-- Use `subagent-orchestrator` and `Harness/subagents.md` when coordinating multiple subagents.
-- Use `/wf update` to check for and apply scaffold updates from GitHub. See `.claude/skills/wf-update/SKILL.md`.
-- Subagents are readers and reporters. Only the main agent writes to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`.
-- For memory writing and consolidation (repeated failures, user corrections, closeout), dispatch `memory-master`.
-- For context analysis and compression alerts (~85% window), dispatch `context-master`.
-- Universal rules live in `.claude/rules/ecc/common.md`.
-- Never bulk-read `Harness/`; route through `Harness/README.md` and `Harness/MEMORY.md`.
-- Scaffold source files live under `templates/common/` and `templates/optional/`; generated dogfood runtime files live under root `Harness/` and `.claude/`.
-
-## 2. Think Before Coding
-
-- You must have **>=95% confidence** in user intent before writing implementation code.
-- If confidence is below 95%, stop and ask up to 3 blocking questions.
-- If multiple valid approaches exist and the choice affects architecture, scope, stack, or user-facing behavior, present trade-offs instead of picking silently.
-- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
-- If something is unclear, stop. Name what is unclear and ask instead of guessing.
-- Before asserting a fact about the codebase, read the file that proves it. If you cannot cite the file and line, do not assert.
-
-## 3. Simplicity First
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No unrequested flexibility, configurability, or speculative error handling.
-- Use explicit interfaces or state models only when they protect a real boundary, clarify ownership, or make verification/recovery simpler.
-- If a simpler approach exists, say so and prefer the smallest change that satisfies the request.
-- If the solution is growing faster than the problem, reduce scope before coding more.
-
-## 4. Surgical Changes
-
-- Touch only files and lines required by the task.
-- Do not improve adjacent code, comments, formatting, or architecture unless it is required for the task.
-- Match existing style even when you would choose a different style in a new project.
-- Clean up imports, variables, functions, and files made unused by your own changes; do not delete pre-existing dead code unless asked.
-- Keep every changed line traceable to the user's request.
-
-## 5. Goal-Driven Execution
-
-- Define verifiable success criteria before implementation.
-- For bugs, reproduce the failure or document why reproduction is impossible before fixing.
-- For multi-step work, keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current. The main agent is the only state committer; subagents return suggestions only.
-- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
-- Every task needs a test, build check, validator run, or recorded manual check.
-- Do not claim web/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
-- Do not place project build scripts, git conventions, run commands, or release process in this file. Put them in `README.md`.
-- Do not place code architecture here. Put architecture in `Harness/architecture.md` or the current feature doc.
-- If this file has accumulated unrelated project notes, pause and propose moving them to the right place: `README.md` for development operations, `Harness/architecture.md` for architecture, `Harness/WF.md` or `Harness/workflows/` for workflow rules.
-
-## 6. Memory & Self-Learning
-
-- `Harness/MEMORY.md` is the resource index. Detailed durable memory lives in `Harness/memory/`.
-- **Tool reflection trigger**: record a lightweight reflection when the same tool/use pattern fails 3+ times, or when a better command pattern/environment fix is found. Write it newest-first in `Harness/memory/tool-usage-reflections.md`.
-- **User correction trigger**: record a lightweight preference/correction when the user asks to remember it, or when the user corrects the same assumption/pattern 2+ times. Write it newest-first in `Harness/memory/user-corrections-preferences.md`.
-- **Agent lesson trigger**: record reusable lessons from review/debug loops in `Harness/memory/agent-lessons-patterns.md` when they would prevent recurrence.
-- **WF auto-trigger**: before WF closeout, dispatch `context-master` then `memory-master` (or use `/wf-learn`). The old "3x same failure" auto-trigger is unreliable — make this a mandatory closeout gate.
-- **Context threshold trigger**: when context approaches ~85% of the window, dispatch `context-master` to analyze and write a non-blocking compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
-- **Closeout trigger**: during WF closeout, dispatch `context-master` to extract durable knowledge, then `memory-master` to consolidate into `Harness/memory/*`.
-- Never record secrets, credentials, tokens, or private data in memory.
-
-## 7. CEO Constraints
-
-- Never call `EnterPlanMode` — delegate planning to `planner` subagents (see `Harness/WF.md`).
-- Never write code directly in `/wf` or `/wf-max` mode — delegate all implementation to subagents (see `Harness/WF-MAX.md`).
-- **Enforcement**: `.claude/settings.json` denies `EnterPlanMode` via the `deny` list. No hooks or `allowTools` needed — the tool is blocked at the permission layer.
+# CLAUDE.md
+
+This repository dogfoods the generated Harness scaffold. Scaffold source files live under `templates/common/` and `templates/optional/`; generated dogfood runtime files live under root `Harness/` and `.claude/`.
+
+## 1. Harness Binding & Startup
+
+- If `Harness/` exists, this repository is governed by the Harness contract. Treat these files as mandatory operating instructions, not optional references.
+- Every session: load `Harness/MEMORY.md` first, then `Harness/README.md`.
+- If `Harness/SETUP.md` exists, follow it before normal project work; it is the install/bootstrap contract and may be deleted after setup is complete.
+
+### 1a. CEO Contract (READ BEFORE ANY TOOL USE)
+
+`/wf-max` active → you are **CEO, not implementer** (enforced by hooks + `.runtime/current-mode.json`).
+
+| ALLOWED (W0) | FORBIDDEN (always on source) |
+|---|---|
+| Read Harness docs, CLAUDE.md | Edit / Write / MultiEdit |
+| Grep/Glob for scoping | Bash (except `ls`/`dir`/`tree`/`git`) |
+| Agent spawn (ONE message) | Deep source reads → delegate to Worker |
+| Write PLAN.md / PROGRESS.md | Sequential spawn (AP6) |
+
+**Tempted to edit source? STOP. Spawn a Worker.**
+
+- `Harness/MEMORY.md` is the memory/resource router: agents, skills, durable memories, and cross-session lessons. Follow its registrations when selecting agents/skills or recording memory.
+- `Harness/README.md` is the task router. For every request, check `Harness/README.md#Load By Task`; if a row matches, read and follow those docs before acting.
+- `Harness/PROGRESS.md` is the global task index. Load at session start to see active task and task history.
+- If work spans more than one step, create a task capsule from `Harness/tasks/_template/` and update `Harness/tasks/<task-id>/PROGRESS.md`.
+- Use `/wf <task>`, `/wf-review [focus]`, `wf mode`, `workflow mode`, or `wk mode` for long, difficult, uncertain, multi-file, or repeated-failure work.
+- Use `/wf-max [task]` for maximum parallelism — CEO→Manager→Worker hierarchy. CEO never writes code directly.
+- Use `/wf-auto` for perpetual self-directed optimization — never stops, continuously improves until 8-angle exhaustion.
+- Use `subagent-orchestrator` and `Harness/subagents.md` when coordinating multiple subagents.
+- Use `/wf-update` to check for and apply scaffold updates from GitHub. See `.claude/skills/wf-update/SKILL.md`.
+- Subagents are readers and reporters. Only the main agent writes to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`.
+- For memory writing and consolidation (repeated failures, user corrections, closeout), dispatch `memory-master`.
+- For context analysis and compression alerts (~85% window), dispatch `context-master`.
+- Universal rules live in `.claude/rules/ecc/common.md`.
+- Never bulk-read `Harness/`; route through `Harness/README.md` and `Harness/MEMORY.md`.
+- Scaffold source files live under `templates/common/` and `templates/optional/`; generated dogfood runtime files live under root `Harness/` and `.claude/`.
+
+## 2. Think Before Coding
+
+- You must have **>=95% confidence** in user intent before writing implementation code.
+- If confidence is below 95%, stop and ask up to 3 blocking questions.
+- If multiple valid approaches exist and the choice affects architecture, scope, stack, or user-facing behavior, present trade-offs instead of picking silently.
+- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
+- If something is unclear, stop. Name what is unclear and ask instead of guessing.
+- Before asserting a fact about the codebase, read the file that proves it. If you cannot cite the file and line, do not assert.
+
+## 3. Simplicity First
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No unrequested flexibility, configurability, or speculative error handling.
+- Use explicit interfaces or state models only when they protect a real boundary, clarify ownership, or make verification/recovery simpler.
+- If a simpler approach exists, say so and prefer the smallest change that satisfies the request.
+- If the solution is growing faster than the problem, reduce scope before coding more.
+
+## 4. Surgical Changes
+
+- Touch only files and lines required by the task.
+- Do not improve adjacent code, comments, formatting, or architecture unless it is required for the task.
+- Match existing style even when you would choose a different style in a new project.
+- Clean up imports, variables, functions, and files made unused by your own changes; do not delete pre-existing dead code unless asked.
+- Keep every changed line traceable to the user's request.
+
+## 5. Goal-Driven Execution
+
+- Define verifiable success criteria before implementation.
+- For bugs, reproduce the failure or document why reproduction is impossible before fixing.
+- For multi-step work, keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current. The main agent is the only state committer; subagents return suggestions only.
+- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
+- Every task needs a test, build check, validator run, or recorded manual check.
+- Do not claim web/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
+- Do not place project build scripts, git conventions, run commands, or release process in this file. Put them in `README.md`.
+- Do not place code architecture here. Put architecture in `Harness/architecture.md` or the current feature doc.
+- If this file has accumulated unrelated project notes, pause and propose moving them to the right place: `README.md` for development operations, `Harness/architecture.md` for architecture, `Harness/WF.md` or `Harness/workflows/` for workflow rules.
+
+## 6. Memory & Self-Learning
+
+- `Harness/MEMORY.md` is the resource index. Detailed durable memory lives in `Harness/memory/`.
+- **Tool reflection trigger**: record a lightweight reflection when the same tool/use pattern fails 3+ times, or when a better command pattern/environment fix is found. Write it newest-first in `Harness/memory/tool-usage-reflections.md`.
+- **User correction trigger**: record a lightweight preference/correction when the user asks to remember it, or when the user corrects the same assumption/pattern 2+ times. Write it newest-first in `Harness/memory/user-corrections-preferences.md`.
+- **Agent lesson trigger**: record reusable lessons from review/debug loops in `Harness/memory/agent-lessons-patterns.md` when they would prevent recurrence.
+- **WF auto-trigger**: before WF closeout, dispatch `context-master` then `memory-master` (or use `/wf-learn`). The old "3x same failure" auto-trigger is unreliable — make this a mandatory closeout gate.
+- **Context threshold trigger**: when context approaches ~85% of the window, dispatch `context-master` to analyze and write a non-blocking compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
+- **Closeout trigger**: during WF closeout, dispatch `context-master` to extract durable knowledge, then `memory-master` to consolidate into `Harness/memory/*`.
+- Never record secrets, credentials, tokens, or private data in memory.
+
+## 7. CEO Constraints
+
+- Never call `EnterPlanMode` — delegate planning to `planner` subagents (see `Harness/WF.md`).
+- Never write code directly in `/wf` or `/wf-max` mode — delegate all implementation to subagents (see `Harness/WF-MAX.md`).
+- **Enforcement**: `.claude/settings.json` denies `EnterPlanMode` via the `deny` list. CEO contract is in [Section 1a](#1a-ceo-contract-read-before-any-tool-use) — read it first.
+- WF-MAX hooks in `.claude/settings.json` block CEO Edit/Write/MultiEdit/Bash on source files. `Harness/.runtime/current-mode.json` persists mode state across sessions.

package/templates/common/MEMORY.md

@@ -1,73 +1,75 @@
-# MEMORY.md - create-harness-vibe-coding Project Resource Index
-
-> The project fact source is reached via `CLAUDE.md -> Harness/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
-> Detailed memory lives in `Harness/memory/`. Keep entries short, newest first, and free of secrets.
-
-## 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.
-- [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.
-
-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.
-- [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.
-- learn: /wf-learn
-- [wf-browser](../.claude/skills/wf-browser/SKILL.md) — AI-driven browser automation via Browser Use (89.1% WebVoyager): E2E testing, form filling, screenshots, web scraping. CLI mode (~50ms) + Python Agent API.
-- [browser-use](~/.claude/skills/browser-use/SKILL.md) — external user-level skill (auto-installed via `pip install browser-use[cli]`): CLI commands, browser profiles, cloud browsers, daemon management.
-- [browser-e2e](workflows/browser-e2e.md) — optional workflow contract: install guide, evidence contract, integration points, fallback paths.
-
-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)
-- Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
-
-## Harness (Runtime)
-
-- [Docs router](README.md)
-- [WF mode](WF.md)
-- [WF Max mode](WF-MAX.md)
-- [0-1 lifecycle](lifecycle.md)
-- [Research protocol](research/README.md)
-- [Context loading protocol](context-loading.md)
-- [Dispatch protocol](dispatch.md)
-- [Subagent orchestration](subagents.md)
-- [Extension contract](extension.md)
-- [Architecture docs](architecture.md)
-- [Agent workflow](agent-workflow.md)
-- [Harness validator](scripts/validate-harness.mjs)
-- [Version file](.harness-version)
-
-## Memory Folder
-
-- [Tool usage/reflections](memory/tool-usage-reflections.md) - repeated tool failures, better command patterns, environment-specific fixes.
-- [User corrections/preferences](memory/user-corrections-preferences.md) - repeated user corrections, durable preferences, common-sense course corrections.
-- [Agent lessons/patterns](memory/agent-lessons-patterns.md) - reusable lessons from review, debugging, validation, and handoff loops.
-
-Write to the memory folder when the guidance should survive chat context loss:
-
-- Use `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times, a better command pattern is found, or an environment-specific fix should be reused.
-- Use `memory/user-corrections-preferences.md` when the user explicitly asks to remember a preference, or the user corrects the same assumption/pattern 2+ times.
-- Use `memory/agent-lessons-patterns.md` when a review/debug loop yields a reusable lesson or regression guard.
-- Use this file for the resource index and routing pointers, not long-form lessons.
-- Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.
+# MEMORY.md - create-harness-vibe-coding Project Resource Index
+
+> The project fact source is reached via `CLAUDE.md -> Harness/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
+> Detailed memory lives in `Harness/memory/`. Keep entries short, newest first, and free of secrets.
+
+## 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.
+- [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.
+
+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.
+- [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-remove](../.claude/skills/wf-remove/SKILL.md) — Safely remove Harness framework files (SAFE/MODIFIED/USER classes), auto-prune empty directories, backup option.
+- learn: /wf-learn
+
+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)
+- Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
+
+## Harness (Runtime)
+
+- [Docs router](README.md)
+- [WF mode](WF.md)
+- [WF Max mode](WF-MAX.md)
+- [0-1 lifecycle](lifecycle.md)
+- [Research protocol](research/README.md)
+- [Context loading protocol](context-loading.md)
+- [Dispatch protocol](dispatch.md)
+- [Subagent orchestration](subagents.md)
+- [Extension contract](extension.md)
+- [Architecture docs](architecture.md)
+- [Agent workflow](agent-workflow.md)
+- [Harness validator](scripts/validate-harness.mjs)
+- [Version file](.harness-version)
+
+## Memory Folder
+
+- [Tool usage/reflections](memory/tool-usage-reflections.md) - repeated tool failures, better command patterns, environment-specific fixes.
+- [User corrections/preferences](memory/user-corrections-preferences.md) - repeated user corrections, durable preferences, common-sense course corrections.
+- [Agent lessons/patterns](memory/agent-lessons-patterns.md) - reusable lessons from review, debugging, validation, and handoff loops.
+
+Write to the memory folder when the guidance should survive chat context loss:
+
+- Use `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times, a better command pattern is found, or an environment-specific fix should be reused.
+- Use `memory/user-corrections-preferences.md` when the user explicitly asks to remember a preference, or the user corrects the same assumption/pattern 2+ times.
+- Use `memory/agent-lessons-patterns.md` when a review/debug loop yields a reusable lesson or regression guard.
+- Use this file for the resource index and routing pointers, not long-form lessons.
+- Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.

package/templates/common/SETUP.md

@@ -133,8 +133,7 @@ The harness validator checks for specific structural invariants. When comparing
 
 - `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-update/SKILL.md`, and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills and subagent orchestration
-- `.claude/commands/update.md` — /wf update command bridge
+- `.claude/skills/wf-update/SKILL.md` and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills 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/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs

package/templates/common/docs/README.md

@@ -64,7 +64,7 @@ Routing priority: if a request explicitly says `/wf <task>`, `wf mode`, `workflo
 | 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 | [workflows/browser-e2e.md](workflows/browser-e2e.md), `.claude/skills/wf-browser/SKILL.md`, `~/.claude/skills/browser-use/SKILL.md` | CLI commands, screenshots, agent history, verification pass/fail evidence |
+| 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 |
@@ -126,6 +126,6 @@ Harness/scripts/validate-harness.mjs lightweight harness gate
 .claude/skills/wf-readme/SKILL.md README preservation and optional structure pass
 .claude/commands/wf.md             slash command bridge into WF mode
 .claude/skills/wf-update/SKILL.md   GitHub-based harness update
-.claude/commands/update.md           /wf update slash command bridge
+.claude/commands/wf-update.md        /wf-update slash command bridge
 Harness/.harness-version             scaffold version and file checksums
 ```

package/templates/common/docs/harness/WF-MAX.md

@@ -7,6 +7,12 @@
 - parallelismScore = (files × avgLines × 3 / 800) × independenceFactor
   - spawn ≥2.0 | maybe 1.0-2.0 | skip <1.0 (degrade to /wf)
 
+## Explicit Invocation Is an Absolute Fan-Out Mandate
+
+When the user types `/wf-max` (or `wf max`), spawning subagents is **mandatory and unconditional**. File count, task size, line count, and overhead estimates DO NOT apply to explicit invocation — they govern ONLY auto-triggering (whether the harness enters wf-max on its own). A 1-file task invoked with `/wf-max` still fans out to parallel subagents.
+
+"Degrade to /wf" changes the **organization** (flat vs CEO→Manager→Worker), never the **fact** of fan-out: `/wf` itself requires ≥3 subagents before second planning. There is no path from an explicitly typed command to a solo main-thread pass. If you find yourself reading source files and editing them directly after the user typed `/wf-max`, you have violated this mandate — stop and dispatch.
+
 ## Companion Docs
 
 - [subagents.md](subagents.md) — agent roster, controller role, efficiency ladder
@@ -26,16 +32,91 @@ CEO(1) ──┬── Manager₁(span) ──┬── Worker₁..ₙ
 - Worker: single file per write Worker (implementer, one file_claim). Single dimension/topic per read Worker (reviewer, researcher). File claims must be file-level disjoint. Topic-level splitting within a single file is only allowed for read-only Workers.
 - depth ≥3: Manager spawns Sub-Manager (span ≤7) instead of Worker. Recursive until leaf condition met.
 
-## Span Formula
+## Decomposition Gate (MANDATORY — CEO-level, before ANY Worker dispatch)
+
+The Decomposition Gate is a hard stop. No code changes, no Worker spawns until the gate passes. The CEO MUST produce a Dispatch Table artifact and pass the Self-Audit Checklist. This is the single most important enforcement mechanism in WF-MAX — it exists because **models default to "do it myself" rather than "decompose and delegate."**
+
+### Gate Artifact: Dispatch Table
+
+CEO MUST write this table in the task PLAN.md after W1 architecture defines the write-set and before W2 implementation dispatch:
 
 ```
-span = min(ceil(sqrt(files)), domain_cap)
+| File | Concern | Worker Type | Worker Label | Read-Only? |
+|------|---------|------------|--------------|------------|
+| src/a.ts | Auth middleware | implementer | impl-auth | No |
+| src/b.ts | DB schema | implementer | impl-db | No |
+| docs/arch.md | Research existing patterns | researcher | res-arch | Yes |
+```
+
+### Gate Rules (any violation = gate fail, retry)
+
+1. **Every file in the write-set MUST have exactly one write Worker.** Unassigned files = fail. This is the anti-bundling rule — one Worker touching >1 write file = fail. (Read Workers may span multiple files.)
+2. **Manager count MUST ≥ span_min = ceil(sqrt(write_files) / 3).** This is the anti-under-decomposition rule at the domain level. Fewer than the minimum number of Managers means domains are too coarse. "One Manager can handle everything" is NOT valid in WF-MAX — if the task were that simple, degrade to /wf.
+3. **Each Manager MUST have ≥2 Workers and ≤7 Workers.** 0-1 Workers = Phantom Manager → dissolve. >7 Workers → Manager context is overloaded → split the domain and add a Manager.
+4. **CEO MUST NOT appear as a Worker row.** CEO writes no production code — fail.
+
+### CEO Tool Boundary
+
+The CEO operates under a strict tool restriction model for production code:
+
+| CEO Has | CEO MUST NOT Use (on source code) |
+|---------|-----------------------------------|
+| Task (spawn agents) | Edit (on source files) |
+| Read (for scoping) | Write (on source files) |
+| TodoWrite (tracking) | Bash (except final verification) |
+| Grep/Glob (for scoping) | MultiEdit (on source files) |
+
+**Exception**: CEO MAY write to `Harness/tasks/<id>/PLAN.md` and `Harness/tasks/<id>/PROGRESS.md` — these are task-tracking artifacts, not production code. The Dispatch Table, Self-Audit Checklist, and synthesis reports are the CEO's primary durable artifacts.
+
+If the CEO finds itself reaching for Edit/Write/Bash on source files, it is violating role boundaries. Stop. Delegate to a Worker.
+
+### Self-Audit Checklist
+
+After producing the Dispatch Table, CEO MUST answer all before proceeding:
+
+- [ ] Did I assign myself any source file? (must be **No** — PLAN.md/PROGRESS.md writes are the exception)
+- [ ] Is every file with planned changes assigned to exactly one write Worker? (must be **Yes**)
+- [ ] Does any Worker have >1 write file? (must be **No**)
+- [ ] Is Manager count ≥ ceil(sqrt(write_files) / 3)? (must be **Yes**, or justification written)
+- [ ] Does every Manager have 2-7 Workers? (<2 = Phantom Manager, >7 = overloaded)
+- [ ] Are there files >200 lines or with >1 concern that should be split into separate files?
+- [ ] Could any serial chain be parallelized? (different files with no shared imports = parallelize)
+- [ ] Will all Workers be spawned in ONE message?
+
+Gate retries until all checks pass. **CEO may NOT proceed to W1 with a failing gate.**
+
+## Anti-Pattern Catalog
+
+Before every wave dispatch, CEO MUST scan for these patterns. **Any match = stop and re-decompose.**
+
+| # | Anti-Pattern | Symptom | Detection | Fix |
+|---|-------------|---------|-----------|-----|
+| AP1 | **CEO-as-Worker** | CEO assigns itself a file or starts writing code | CEO in Dispatch Table; Edit/Write/Bash used by CEO | Re-delegate to a Worker immediately |
+| AP2 | **Under-decomposition** | Fewer Workers than `ceil(sqrt(files))` | Count check fails; "1-2 agents is enough for this" | Split files by concern, module, or layer |
+| AP3 | **Serialization trap** | "Let me do X first, then I'll know how to dispatch Y" | Sequential plan without parallel candidates | Dispatch X and Y in parallel NOW; Worker-X returns spec that Worker-Y consumes |
+| AP4 | **Fake parallelism** | Multiple Workers assigned same file | Duplicate file path in Dispatch Table | One file = one Writer. Split file into separate modules, or serialize |
+| AP5 | **Phantom Manager** | Manager spawns 0-1 Workers | Manager's sub-table has <2 Workers | Dissolve Manager; CEO or sibling absorbs domain |
+| AP6 | **Sequential spawn** | Workers spawned one-per-turn instead of batched | Only 1 Task() call per message | Batch ALL Task() calls into ONE message |
+| AP7 | **Silent degrade** | CEO switches to /wf without recording reason | No Dispatch Table; flat agent spawns | Explicit decision + justification in PLAN.md; only valid reason is overhead > 0.30 |
+
+## Span Formula (Prescriptive Floor)
+
+```
+Manager_min = ceil(sqrt(write_files) / 3)   # HARD FLOOR — you MUST have ≥ this many Managers
+Manager_max = min(Manager_min × 2, 7)       # per-wave; exceed only with written justification
+Worker_max_per_manager = 7                   # hard cap; split domain if exceeded
+
+Worker count per wave = write_files (one Worker per write file, guaranteed by Gate Rule #1)
+
+Domain caps (workers per Manager by type):
   Architecture:    cap = 3
-  Implementation:  cap = 5-7
-  Review:          cap = 7-10
-  Research:        cap = 10-12
+  Implementation:  cap = 7
+  Review:          cap = 10
+  Research:        cap = 12
 ```
 
+**Manager_min is a floor, not a target.** The span formula prevents domain-level under-decomposition — the real failure mode where one Manager tries to coordinate too many Workers across unrelated concerns. Worker-level under-decomposition is prevented by Gate Rule #1 (one file per Worker).
+
 ## Total Agents (recursive, scales to 1000)
 
 ```
@@ -92,15 +173,21 @@ total(depth, span) = Σ span^L for L=0..depth
 ## Wave Orchestration
 
 ```
-W0:  Explore-Mgr    → N parallel researchers → synthesize → CEO
-W1:  Architect-Mgr  → 3 parallel → boundary decisions + interface contract → CEO approval
-W2:  Implement-Mgr  → write-set coloring → wave dispatch: N parallel implementers (disjoint file_claims) → merge → CEO
-W2R: Review-Mgr     → 3-4 parallel reviewers → dedupe + severity → CEO assigns fixes
-W3+: Dependent implementation waves (repeat W2 pattern)
+W0:    Explore-Mgr    → N parallel researchers → synthesize → CEO
+E-GATE:               → Exploration Gate: CEO verifies all exploration questions answered, findings synthesized (lightweight; see WF.md Decomposition Gate)
+W1:    Architect-Mgr  → 3 parallel → boundary decisions + interface contract → CEO approval
+D-GATE:               → Write Decomposition Gate: CEO produces Dispatch Table + Self-Audit → GATE PASS/FAIL (MANDATORY, applied to the write-set defined by architecture)
+W2:    Implement-Mgr  → write-set coloring → wave dispatch: ALL Workers spawned in ONE message → merge → CEO
+W2R:   Review-Mgr     → 3-4 parallel reviewers → dedupe + severity → CEO assigns fixes
+W3+:   Dependent waves (repeat W2 pattern; re-run D-GATE if write-set changed significantly)
 INTEGRATION: CEO → verifier → fail → debugger → loop (cap=3)
 CLOSEOUT:   CEO → context-master + memory-master (direct, no Manager)
 ```
 
+- **E-GATE** (Exploration Gate): read-only agents each had a specific question; all returns are synthesized into PLAN.md. No exploration blind spots.
+- **D-GATE** (Write Decomposition Gate): applies AFTER architecture defines the write-set, BEFORE any implementation Worker spawns. Dispatch Table covers the actual write-set. Gate is non-negotiable.
+- W2 dispatch: ALL Workers for a wave MUST be spawned in a single message — not one per turn. Batching is what makes parallelism real.
+
 - Wave scheduling: Managers serial across domains, Workers parallel within domain.
 - CEO validates wave output before starting next wave. No pipelining.
 
@@ -115,6 +202,8 @@ overhead(depth) = 0.10 (depth≤2) | 0.20 (depth=3) | 0.35 (depth≥4)
 
 ## When NOT to use /wf-max
 
+These conditions govern **auto-trigger degradation only** (wf-max → /wf). They never apply when the user explicitly types `/wf-max`, and "degrade" always means the flat /wf multi-subagent loop, never a solo pass.
+
 - files < 5 → use /wf
 - all changes share single interface → serial dependency
 - import/re-export refactor → global consistency required

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

@@ -15,6 +15,11 @@ Enter WF mode when any of these are true:
 - The same command, test, tool, or approach fails twice.
 - The user explicitly says `/wf-max [task]` or `wf max` (for maximum-parallelism mode, see [WF-MAX.md](WF-MAX.md)).
 
+**Two distinct trigger classes — do not conflate them:**
+
+- **Explicit invocation** (`/wf`, `wf mode`, `workflow mode`, `wk mode`, `/wf-max`): subagent fan-out is **mandatory and unconditional**. File count, task size, and subsystem count are IRRELEVANT — a 1-file task typed with `/wf` still fans out to ≥3 subagents before the second plan. There is no "too small for WF" exception once the user types the command.
+- **Auto-triggering** (the file-count / multi-subsystem / repeated-failure bullets above): these decide whether the harness enters WF mode *on its own*. They are the ONLY place file count matters, and they can only ESCALATE into WF — never downgrade an explicit command out of it.
+
 ## Multi-Subagent Requirement
 
 WF mode requires multi-subagent orchestration by default.

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

@@ -57,6 +57,10 @@ Goal
 | `verifier` | Parallel Read | run checks and record evidence |
 | `memory-master` | Serial Write | write/consolidate memory entries, dedup, cross-project extraction |
 | `context-master` | Parallel Read | analyze context usage, recommend compression, extract session knowledge |
+| `explore-manager` | Parallel Read | WF-MAX W0: spawn 5-10 researchers, synthesize, report to CEO |
+| `architect-manager` | Parallel Read | WF-MAX W1: spawn 3 architects, synthesize interface contracts |
+| `implement-manager` | Serial Write | WF-MAX W2: spawn implementers (one file_claim each), merge results |
+| `review-manager` | Parallel Read | WF-MAX W2R: spawn 3-4 reviewers, deduplicate, classify severity |
 
 ## Dispatch Rules