npm - create-harness-vibe-coding - Versions diffs - 0.6.2 → 0.6.4 - Mend

create-harness-vibe-coding 0.6.2 → 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

package/templates/common/docs/README.md CHANGED Viewed

@@ -1,145 +1,131 @@
-# {{projectName}} - Harness Router
-Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
-Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS.md` when work is active. Do not read the whole `Harness/` tree.
-## 0-1 Flow
-```text
-Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
-```
-For the full phase contract, load [lifecycle.md](lifecycle.md).
-## Development Contract
-- This file is a router, not a full spec.
-- If the task does not clearly match a row below, search by keywords before loading more docs.
-- project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
-- Important assumptions, decisions, blockers, evidence, and handoffs must be written to the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
-- README rewrites are optional project-doc work. Use `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`.
-- WF mode rules live in [WF.md](WF.md).
-- Phase rules live in [lifecycle.md](lifecycle.md).
-- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md).
-- Parallel dispatch rules live in [dispatch.md](dispatch.md).
-- Subagent orchestration methodology lives in [subagents.md](subagents.md).
-- Extension rules live in [extension.md](extension.md).
-- Context-loading rules live in [context-loading.md](context-loading.md).
-- Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
-## Keyword Routing
-Use this only when the task is ambiguous or the matching row is unclear.
-1. Extract 2-5 concrete keywords from the user request.
-2. Search the project docs first:
-```bash
-rg -n "keyword1|keyword2|keyword3" CLAUDE.md README.md Harness
-```
-3. Load only the top matching doc or the smallest matching doc pair.
-4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`.
-Keywords are retrieval hints, not project facts.
-## Load By Task
-Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
-Routing priority: if a request explicitly says `/wf <task>`, `/wf-max [task]`, `/wf-learn`, `wf mode`, `wf max`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` MUST then delegate subagent coordination to `subagent-orchestrator`.
-| When to Read | Keywords | Load | Output |
-| --- | --- | --- | --- |
-| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
-| Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
-| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
-| Need architecture or boundaries | architecture, boundary, layer, domain, port, adapter, dependency | [architecture.md](architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
-| Need WF mode | wf, /wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
-| Need to learn from errors | /wf-learn, wf learn, learn, remember, memory, lesson | [MEMORY.md](MEMORY.md), `.claude/skills/wf-learn/SKILL.md`, `Harness/memory/*` | context-master → memory-master → project + global memory |
-| Need peer review | /wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `Harness/README.md` | cross-model review via other CLI (Codex/Claude) |
-| Need WF Max mode | /wf-max, wf max, maximum parallelism, max parallel | [WF-MAX.md](WF-MAX.md), [WF.md](WF.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | max-parallel exploration, write-set coloring, wave dispatch |
-| 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/readme-optimizer/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 |
-| Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [subagents.md](subagents.md), [dispatch.md](dispatch.md), [context-loading.md](context-loading.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/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` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
-| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
-| Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
-| Need feature work | feature, implementation, TDD, test, review, closeout | [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 |
-| Need harness update | update, /wf update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `Harness/.harness-version` | update plan, safe incremental update, merge candidates |
-## Gates
-- Move phases in order unless the user asks for a fast lane.
-- Use `/wf <task>`, `/wf-max [task]`, `wf mode`, `workflow mode`, or `wk mode` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
-- Do not code before the PRD has MVP, non-goals, and acceptance criteria.
-- Do not cross a layer boundary without reading `domain/ports.md` and updating architecture or ports.
-- 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/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
-- In WF mode, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, and at closeout.
-- In WF Max mode, never dispatch two implementers with overlapping file claims. Verify disjointness before each wave.
-- Do not add stack-specific agents or skills without following `extension.md`.
-- Do not close work without tests or recorded manual verification.
-- Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
-- Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
-- If a doc still has `{{...}}`, treat that section as a template, not project fact.
-## Doc Map
-```text
-Harness/README.md                  router only
-Harness/MEMORY.md                  resource index
-Harness/PLAN.md                    project-level plan (redirects to tasks/<id>/PLAN.md)
-Harness/SETUP.md                   install/bootstrap contract
-Harness/PROGRESS.md                global task index and cross-task decisions
-Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat
-Harness/tasks/<id>/PLAN.md         per-task implementation plan and evidence
-Harness/tasks/_template/           task capsule template (copy to create new task)
-Harness/WF.md                      long-task workflow and recovery loop
-Harness/WF-MAX.md                  max-parallelism workflow with wave dispatch
-.claude/skills/wf-max/SKILL.md     max-parallelism skill loader
-.claude/skills/wf-review/SKILL.md  cross-model peer review skill
-.claude/commands/wf-max.md         /wf-max slash command bridge
-.claude/commands/learn.md          /wf-learn slash command bridge
-.claude/commands/wf-review.md      /wf-review slash command bridge
-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 (if installed)
-Harness/memory/tool-usage-reflections.md repeated tool failures and better command patterns
-Harness/memory/user-corrections-preferences.md durable user corrections and preferences
-Harness/memory/agent-lessons-patterns.md reusable review/debug lessons
-Harness/scripts/validate-harness.mjs lightweight harness gate
-.claude/agents/*                   built-in common agents
-.claude/skills/*                   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
-.claude/skills/wf-update/SKILL.md   GitHub-based harness update
-.claude/commands/update.md           /wf update slash command bridge
-Harness/.harness-version             scaffold version and file checksums
-```
+# create-harness-vibe-coding - Harness Router
+Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
+Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS.md` when work is active. Do not read the whole `Harness/` tree.
+## 0-1 Flow
+```text
+Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback
+```
+For the full phase contract, load [lifecycle.md](lifecycle.md).
+## Development Contract
+- This file is a router, not a full spec.
+- If the task does not clearly match a row below, search by keywords before loading more docs.
+- project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+- Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
+- README rewrites are optional project-doc work. Use `wf-readme` and preserve existing public docs unless the user approves a broader restructure.
+- Code architecture belongs in [architecture.md](architecture.md) or the current feature doc, not `CLAUDE.md`.
+- Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
+- WF mode rules live in [WF.md](WF.md).
+- Phase rules live in [lifecycle.md](lifecycle.md).
+- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md).
+- Parallel dispatch rules live in [dispatch.md](dispatch.md).
+- Subagent orchestration methodology lives in [subagents.md](subagents.md).
+- Extension rules live in [extension.md](extension.md).
+- Context-loading rules live in [context-loading.md](context-loading.md).
+- Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
+## Keyword Routing
+Use this only when the task is ambiguous or the matching row is unclear.
+1. Extract 2-5 concrete keywords from the user request.
+2. Search the project docs first:
+```bash
+rg -n "keyword1|keyword2|keyword3" CLAUDE.md README.md Harness
+```
+3. Load only the top matching doc or the smallest matching doc pair.
+4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`.
+Keywords are retrieval hints, not project facts.
+## Load By Task
+Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
+Routing priority: if a request explicitly says `/wf <task>`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. Load `Harness/WF.md` directly, then delegate subagent coordination to `subagent-orchestrator`.
+| When to Read | Keywords | Load | Output |
+| --- | --- | --- | --- |
+| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
+| Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
+| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
+| Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](architecture.md) | layer map, ports, constraints |
+| Need WF mode | wf, /wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
+| Need peer review | /wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `Harness/README.md` | cross-model review via other CLI (Codex/Claude) |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
+| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
+| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
+| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use | [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 |
+| Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
+| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
+| Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
+| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md) | task plan, tests, implementation loop |
+| Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
+| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
+| Need harness update | update, /wf update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `Harness/.harness-version` | update plan, safe incremental update, merge candidates |
+## Gates
+- Move phases in order unless the user asks for a fast lane.
+- Use `/wf <task>`, `/wf-max [task]`, `wf mode`, `workflow mode`, or `wk mode` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
+- Do not code before the PRD has MVP, non-goals, and acceptance criteria.
+- Unsure whether to open a task? Read [agent-workflow.md](agent-workflow.md) Section 1.
+- Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
+- Do not run writing agents in parallel unless write sets are disjoint.
+- Before coordinating multiple agents, fill `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
+- In WF mode, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, and at closeout.
+- In WF Max mode, never dispatch two implementers with overlapping file claims. Verify disjointness before each wave.
+- Do not add stack-specific agents or skills without following `extension.md`.
+- Do not close work without tests or recorded manual verification.
+- Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
+- Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
+- If a doc still has `{{...}}`, treat that section as a template, not project fact.
+## Doc Map
+```text
+Harness/README.md                  router only
+Harness/MEMORY.md                  resource index
+Harness/PROGRESS.md                global task index and cross-task decisions
+Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat
+Harness/tasks/<id>/PLAN.md         per-task implementation plan and evidence
+Harness/tasks/_template/           task capsule template (copy to create new task)
+Harness/WF.md                      long-task workflow and recovery loop
+Harness/WF-MAX.md                  max-parallelism workflow with wave dispatch
+.claude/skills/wf-max/SKILL.md     max-parallelism skill loader
+.claude/skills/wf-review/SKILL.md  cross-model peer review skill
+.claude/commands/wf-max.md         /wf-max slash command bridge
+.claude/commands/learn.md          /wf-learn slash command bridge
+.claude/commands/wf-review.md      /wf-review slash command bridge
+Harness/lifecycle.md               0-1 product flow
+Harness/subagents.md               controller-led subagent orchestration
+Harness/context-loading.md         dynamic loading and subagent packs
+Harness/dispatch.md                lightweight parallel dispatch protocol
+Harness/extension.md               stack-specific asset contract
+Harness/agent-workflow.md          build/review/test loop
+Harness/architecture.md            layer boundaries
+Harness/research/README.md         research protocol
+Harness/research/PRD.md            product scope
+Harness/research/research-results.md research results
+Harness/workflows/*.md             optional workflow evidence rules (if installed)
+Harness/memory/tool-usage-reflections.md repeated tool failures and better command patterns
+Harness/memory/user-corrections-preferences.md durable user corrections and preferences
+Harness/memory/agent-lessons-patterns.md reusable review/debug lessons
+Harness/scripts/validate-harness.mjs lightweight harness gate
+.claude/agents/*                   built-in common agents
+.claude/skills/*                   skill-style dynamic loaders
+.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
+Harness/.harness-version             scaffold version and file checksums
+```

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

@@ -20,8 +20,20 @@ Enter WF mode when any of these are true:
 WF mode requires multi-subagent orchestration by default.
 - Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents from `.claude/agents/` before second planning unless the runtime cannot spawn subagents.
-- Use a 7:3 collaboration bias: prefer multi-agent collaboration for long, uncertain, cross-file, cross-layer, browser/API, migration, or repeated-failure work; reserve solo mode for clearly local, low-risk, one-file tasks outside explicit WF/WK mode.
+- Collaboration decision tree (replaces the old "7:3" heuristic — concrete conditions, not a magic number):
+  - **In explicit WF/WK mode** → ALWAYS multi-agent (≥3 subagents before second plan). No exceptions.
+  - **3+ files changed** → multi-agent (at minimum: planner + implementer + reviewer).
+  - **Cross-layer change** (DB + API + UI) → multi-agent with architect + implementer(s) + reviewer.
+  - **Uncertain scope or approach** → multi-agent exploration (planner + researcher + architect).
+  - **1-2 files, well-understood, not in WF mode** → solo is acceptable.
+  - **Repeated failure on same task** → STOP solo, switch to multi-agent.
 - Default initial fan-out: `planner`, `researcher` or `docs-researcher`, and `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when the phase needs them.
+- **Exploration Gate (HARD):**
+  - [ ] CEO has NOT read any source files — only `Harness/` docs, `CLAUDE.md`, and subagent returns. This is the #1 rule. **Exception**: if subagents are genuinely unavailable, fall back to bounded-pass emulation and record `Fallback: subagents unavailable` in PLAN.md.
+  - [ ] CEO overrides model per-agent: default `sonnet` for real code understanding; `haiku` only for shallow scans (directory listing, file counts); `opus` if user requests.
+  - [ ] ≥3 distinct agent types, each with ONE specific question.
+  - [ ] All spawned in ONE message block.
+  - [ ] Agent count ≥ max(3, ceil(estimated_dirs / 2)) — estimate from prompt/docs; run a second wave if returns reveal more.
 - Record every dispatch or bounded-pass fallback in `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`.
 - If subagents are unavailable, emulate the same roles as separate bounded passes and record why the fallback was used.

package/templates/common/docs/harness/agent-workflow.md CHANGED Viewed

@@ -1,94 +1,94 @@
-# Agent Workflow
-Use when implementing, reviewing, debugging, or coordinating subagents.
-## ReAct Loop
-```text
-Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/tasks/<task-id>/PROGRESS.md
-```
-If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [subagents.md](subagents.md) and [dispatch.md](dispatch.md).
-## Feature Packet
-Every PRD scope item must be covered by a feature doc at `Harness/features/<name>.md`
-created from `Harness/features/_template.md`. Do not code without a feature doc.
-**Cohesion rule**: if multiple PRD scope items share the same write set, the same
-test/verification path, and the same review boundary, group them into a single
-feature doc. The PRD owns scope decomposition; the feature doc owns the
-implementation unit. The number of feature docs should reflect the number of
-distinguishable implementation units, not the number of PRD checkboxes.
-**Minimum bar**: a feature doc is still required when the implementation touches
-more than one file or changes user-visible behavior. Only skip a feature doc
-entirely when the work is a single-file fix with no behavior change — in that
-case, record the change in `Harness/tasks/<task-id>/PLAN.md` instead.
-**New vs iterate**: if a PRD scope item has ≥85% overlap with an existing feature doc, open the existing doc, bump `Version`, and add a `## Changelog` entry. Only create a new file when the scope is substantially different. When unsure, ask.
-## Standard Build Loop
-```text
-PRD/feature packet
--> failing test or manual check
--> minimal implementation
--> verification
--> review
--> docs sync
--> close or iterate
-```
-## Subagent Use
-Use subagents when a task needs broad reading, parallel work, cross-layer changes, independent review, or isolated debugging. Follow [subagents.md](subagents.md) for controller-led orchestration and [dispatch.md](dispatch.md) for the dispatch table.
-Before spawn, define:
-- role
-- task
-- mode
-- read boundary
-- write boundary
-- dependency
-- injected docs from [context-loading.md](context-loading.md)
-- return format
-Rules:
-- Explorer Pass, Reviewer, and Verifier are read-only.
-- Researcher and Docs Researcher are read-only unless explicitly asked to return a docs patch.
-- Planner and Architect are read-only unless explicitly asked to return a docs patch.
-- Test Writer writes tests before Implementer writes production code.
-- Implementer only writes inside its declared write set.
-- Writing agents run serially unless write sets are disjoint.
-- Debugger fixes the smallest failing path, not adjacent design.
-- Main agent integrates summaries, resolves conflicts, and runs final verification.
-## Parallel Dispatch
-Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). In `/wf max`, the CEO/Manager/Worker hierarchy in [WF-MAX.md](WF-MAX.md) overrides this limit entirely with wave-based parallel dispatch. Prefer parallel read-only work first, then serial writes.
-Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
-## Conflict Rule
-If PRD, task PLAN.md, architecture, ports, tests, or code disagree:
-1. stop implementation
-2. record the conflict in `Harness/tasks/<task-id>/PROGRESS.md` or the feature doc
-3. choose the smallest reversible decision
-4. ask the maintainer when user-visible behavior or security is affected
-## Completion Gate
-Close only when:
-- acceptance criteria are satisfied
-- verification evidence is recorded
-- architecture, ports, data-flow, or state docs are synced if affected
-- no unresolved critical/high review findings remain
-- any optimistic UI mutation has a declared and verified rollback path
-- any file declared as DONE in PLAN.md or PROGRESS.md exists on disk (chat output is not durable evidence)
-- `Harness/tasks/<task-id>/PROGRESS.md` states the final status or next iteration
+# Agent Workflow
+Use when implementing, reviewing, debugging, or coordinating subagents.
+## ReAct Loop
+```text
+Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/tasks/<task-id>/PROGRESS.md
+```
+If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [subagents.md](subagents.md) and [dispatch.md](dispatch.md).
+## Feature Packet
+Every PRD scope item must be covered by a task plan at `Harness/tasks/<task-id>/PLAN.md`
+created from `Harness/tasks/_template/PLAN.md` (the primary work tracking system).
+**Cohesion rule**: if multiple PRD scope items share the same write set, the same
+test/verification path, and the same review boundary, group them into a single
+feature doc. The PRD owns scope decomposition; the feature doc owns the
+implementation unit. The number of feature docs should reflect the number of
+distinguishable implementation units, not the number of PRD checkboxes.
+**Minimum bar**: a task plan is required when the implementation touches more than one
+file or changes user-visible behavior. Record the plan in `Harness/tasks/<task-id>/PLAN.md`.
+For single-file fixes with no behavior change, a brief note in `PROGRESS.md` is enough.
+**New vs iterate**: if a PRD scope item overlaps with an existing task, reopen the existing
+task capsule and append to its `PROGRESS.md`. Only create a new task capsule when the
+scope is substantially different. When unsure, ask.
+## Standard Build Loop
+```text
+PRD/task plan
+-> failing test or manual check
+-> minimal implementation
+-> verification
+-> review
+-> docs sync
+-> close or iterate
+```
+## Subagent Use
+Use subagents when a task needs broad reading, parallel work, cross-layer changes, independent review, or isolated debugging. Follow [subagents.md](subagents.md) for controller-led orchestration and [dispatch.md](dispatch.md) for the dispatch table.
+Before spawn, define:
+- role
+- task
+- mode
+- read boundary
+- write boundary
+- dependency
+- injected docs from [context-loading.md](context-loading.md)
+- return format
+Rules:
+- Explorer Pass, Reviewer, and Verifier are read-only.
+- Researcher and Docs Researcher are read-only unless explicitly asked to return a docs patch.
+- Planner and Architect are read-only unless explicitly asked to return a docs patch.
+- Test Writer writes tests before Implementer writes production code.
+- Implementer only writes inside its declared write set.
+- Writing agents run serially unless write sets are disjoint.
+- Debugger fixes the smallest failing path, not adjacent design.
+- Main agent integrates summaries, resolves conflicts, and runs final verification.
+## Parallel Dispatch
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). In `/wf max`, the CEO/Manager/Worker hierarchy in [WF-MAX.md](WF-MAX.md) overrides this limit entirely with wave-based parallel dispatch. Prefer parallel read-only work first, then serial writes.
+Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
+## Conflict Rule
+If PRD, task PLAN.md, architecture, ports, tests, or code disagree:
+1. stop implementation
+2. record the conflict in `Harness/tasks/<task-id>/PROGRESS.md` or the feature doc
+3. choose the smallest reversible decision
+4. ask the maintainer when user-visible behavior or security is affected
+## Completion Gate
+Close only when:
+- acceptance criteria are satisfied
+- verification evidence is recorded
+- architecture docs are synced if affected
+- no unresolved critical/high review findings remain
+- any optimistic UI mutation has a declared and verified rollback path
+- any file declared as DONE in PLAN.md or PROGRESS.md exists on disk (chat output is not durable evidence)
+- `Harness/tasks/<task-id>/PROGRESS.md` states the final status or next iteration

package/templates/common/docs/harness/architecture.md CHANGED Viewed

@@ -123,4 +123,4 @@ CLI args / prompts
 - Interactive confirmation currently happens before full conflict-plan display in interactive mode.
 - Some README tests assert exact prose and can be made more structural.
-- `wf-mode` and `subagent-orchestrator` routing priority should continue to be tightened in templates.
+- `subagent-orchestrator` routing priority should continue to be tightened in templates.