create-harness-vibe-coding 0.1.10 → 0.2.0

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

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

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

@@ -0,0 +1,136 @@
+# WF Mode - Long Task Workflow
+
+Use this when work is long, difficult, uncertain, multi-file, multi-agent, or user-triggered with `/wf`, `wf mode`, or `workflow mode`.
+
+This is a Ralph-style harness loop: keep moving through evidence, bounded exploration, second planning, implementation, review, verification, and recovery instead of stalling on the first obstacle.
+
+## Trigger
+
+Enter WF mode when any of these are true:
+
+- The user explicitly says `/wf`, `wf mode`, or asks for the full workflow.
+- The task needs more than one step, more than three files, or more than one subsystem.
+- The task needs research, architecture judgment, browser/API validation, or migration planning.
+- Confidence in intent, architecture, or implementation is below 95%.
+- The same command, test, tool, or approach fails twice.
+
+## WF Loop
+
+```text
+Intake
+-> confidence gate
+-> parallel explorer / researcher / docs-researcher / architect passes
+-> synthesis
+-> second plan
+-> test-writer
+-> implementer
+-> reviewers
+-> verifier
+-> if failed: debugger -> review -> e2e/API verification -> loop
+-> close with evidence
+```
+
+## Intake
+
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, and `Harness/PLAN.md`.
+2. State the goal, non-goals, confidence level, known risks, and write boundaries.
+3. Ask up to three blocking questions only when the next action cannot reach 95% confidence.
+4. Update `Harness/PLAN.md#Heartbeat` before dispatching agents or running long commands.
+5. Load `Harness/subagents.md` before coordinating multiple agents.
+
+## Exploration
+
+Use parallel read-only passes first. Prefer three or fewer active agents.
+
+| Agent | Purpose | Writes |
+| --- | --- | --- |
+| Explorer Pass | map local project facts, commands, app entry points, existing docs | none |
+| `researcher` | product, ecosystem, dependency, and external context | none unless returning a docs patch |
+| `docs-researcher` | official docs, SDK/API versions, browser/tool limits | none unless returning a docs patch |
+| `architect` | boundaries, ports, data flow, state impact, migration risks | none unless returning a docs patch |
+
+Use local files first. Use web search, Tavily, TinyFish, GitHub, official docs, or user-provided links only when the decision needs current or external evidence. Record tool choice and limitations in `Harness/research/research-results.md` or `Harness/PLAN.md`.
+
+## Subagent Orchestration
+
+Use `Harness/subagents.md` as the orchestration methodology and `Harness/dispatch.md` as the dispatch table protocol.
+
+- The main agent is the controller and owns synthesis, integration, and final verification.
+- Parallelize read-only exploration; serialize writers unless write sets are disjoint and isolated.
+- Every subagent gets a dispatch pack with role, goal, read set, write set, forbidden scope, injected docs, evidence, stop condition, and return format.
+- After implementation, run spec review before code-quality or architecture review.
+- If subagents are unavailable, emulate the same roles as bounded passes and record the fallback.
+
+## Second Plan
+
+After exploration, synthesize:
+
+- facts found
+- assumptions
+- risks
+- accepted/rejected options
+- tasks
+- read/write sets
+- verification path
+- rollback or recovery plan
+
+Write the result to `Harness/PLAN.md` before implementation.
+
+## Build And Review
+
+1. `test-writer` defines a failing test or written manual check first.
+2. `implementer` changes only the declared write set.
+3. At least one `reviewer` checks diff, architecture, risks, and missing tests.
+4. For cross-layer or risky work, run separate reviewers for architecture and test adequacy.
+5. `verifier` runs the declared checks and records exact evidence.
+
+## Browser And API Evidence
+
+For browser-visible changes, typecheck/build/unit tests are not enough. Use Chrome DevTools, CDP, Playwright, or a documented real-browser run:
+
+- start the app and record URL/port
+- click through the critical flow
+- capture frontend console/runtime errors
+- capture failed network requests
+- collect backend logs when the flow crosses an API
+- record screenshot, trace, video, or manual evidence path
+
+For API changes, run the project API/integration test path or a documented real request against a local service and record request, response, logs, and failure behavior.
+
+## Recovery Loop
+
+If verification fails:
+
+1. Update `Harness/PLAN.md#Heartbeat` with failure count and blocker.
+2. Dispatch `debugger` with the failing command, error output, and smallest relevant files.
+3. Fix the smallest reproduced failure.
+4. Run reviewer again.
+5. Run verifier again.
+6. Repeat until verified or blocked by missing user input/external state.
+
+If the same failure class happens three times, stop blind fixes. Record evidence, likely root causes, attempted paths, and ask the user to choose among clear options.
+
+## Heartbeat Protocol
+
+Heartbeat is a lightweight recovery protocol, not a background daemon.
+
+Update `Harness/PLAN.md#Heartbeat`:
+
+- before a long command
+- after a long command
+- before spawning subagents
+- after integrating subagent returns
+- after each failed verification
+- before stopping for user input
+
+The agent may set the next beat interval by event instead of time, such as "after next test run", "after reviewer returns", or "after browser evidence is captured".
+
+## Closeout
+
+Close only when:
+
+- acceptance criteria are satisfied
+- reviewer has no unresolved critical/high findings
+- test/API/browser evidence is recorded
+- affected Harness docs are synced
+- `Harness/PLAN.md#Heartbeat` says the task is verified or lists the exact next recovery action

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

@@ -5,14 +5,14 @@ Use when implementing, reviewing, debugging, or coordinating subagents.
 ## ReAct Loop
 
 ```text
-Observe -> Load minimal context -> Plan -> Act -> Verify -> Update docs/harness/PLAN.md
+Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/PLAN.md
 ```
 
-If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [dispatch.md](dispatch.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 (`research/PRD.md` Section 2) must have its own feature doc at `docs/features/<name>.md` created from `docs/features/_template.md`. One feature = one doc = one implementation unit. Do not code without a feature doc.
+Every PRD scope item (`research/PRD.md` Section 2) must have its own feature doc at `Harness/features/<name>.md` created from `Harness/features/_template.md`. One feature = one doc = one implementation unit. Do not code without a feature doc.
 
 Small scope is not an exception — a short feature doc is better than none. If the work is truly too small for a full feature doc (single-file fix, no behavior change), it is not a PRD scope item.
 
@@ -32,7 +32,7 @@ PRD/feature packet
 
 ## Subagent Use
 
-Use subagents when a task needs broad reading, parallel work, cross-layer changes, independent review, or isolated debugging.
+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:
 
@@ -58,16 +58,16 @@ Rules:
 
 ## Parallel Dispatch
 
-Use [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents. Prefer parallel read-only work first, then serial writes.
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents. 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, docs/harness/PLAN.md, architecture, ports, tests, or code disagree:
+If PRD, Harness/PLAN.md, architecture, ports, tests, or code disagree:
 
 1. stop implementation
-2. record the conflict in `docs/harness/PLAN.md` or the feature doc
+2. record the conflict in `Harness/PLAN.md` or the feature doc
 3. choose the smallest reversible decision
 4. ask the maintainer when user-visible behavior or security is affected
 
@@ -79,4 +79,4 @@ Close only when:
 - verification evidence is recorded
 - architecture, ports, data-flow, or state docs are synced if affected
 - no unresolved critical/high review findings remain
-- `docs/harness/PLAN.md` states the final status or next iteration
+- `Harness/PLAN.md` states the final status or next iteration

package/templates/common/docs/harness/context-loading.md

@@ -4,20 +4,20 @@ Use when context is growing, subagents are needed, or an agent is unsure which h
 
 ## Routing Authority
 
-`docs/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
+`Harness/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
 
-If this file and `docs/README.md` disagree, follow `docs/README.md`, record the assumption in `docs/harness/PLAN.md`, and update this file later.
+If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `Harness/PLAN.md`, and update this file later.
 
-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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
+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/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Main Context
 
 Always keep:
 
 - `CLAUDE.md`
-- `MEMORY.md`
-- `docs/README.md`
-- `docs/harness/PLAN.md` when active
+- `Harness/MEMORY.md`
+- `Harness/README.md`
+- `Harness/PLAN.md` when active
 - current feature doc when active
 
 Load other docs only by trigger.
@@ -26,16 +26,16 @@ Load other docs only by trigger.
 
 | Trigger | Load |
 | --- | --- |
-| idea, scope, MVP | `docs/harness/lifecycle.md`, `docs/research/PRD.md` |
-| research, competitors, stack choice | `docs/research/README.md`, `docs/research/research-results.md` |
-| official docs, API, SDK, version, limits | `docs/research/README.md`, `docs/harness/architecture.md`, `docs/domain/ports.md` as needed |
-| layer, dependency, module boundary | `docs/harness/architecture.md`, `docs/domain/ports.md` |
-| task split, owner, write set | `docs/harness/PLAN.md`, `docs/harness/agent-workflow.md` |
-| parallel agents, dispatch, worktree decision | `docs/harness/dispatch.md`, `docs/harness/PLAN.md` |
-| memory, repeated tool failure, repeated user correction, reusable lesson | `MEMORY.md`, the relevant `memory/*.md` file |
-| event, retry, failure path | `docs/harness/data-flow.md` |
-| status, transition, resume | `docs/harness/state-machines.md` |
-| subagent spawn | this file plus the role pack below |
+| idea, scope, MVP | `Harness/lifecycle.md`, `Harness/research/PRD.md` |
+| research, competitors, stack choice | `Harness/research/README.md`, `Harness/research/research-results.md` |
+| official docs, API, SDK, version, limits | `Harness/research/README.md`, `Harness/architecture.md`, `Harness/domain/ports.md` as needed |
+| layer, dependency, module boundary | `Harness/architecture.md`, `Harness/domain/ports.md` |
+| task split, owner, write set | `Harness/PLAN.md`, `Harness/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/PLAN.md` |
+| memory, repeated tool failure, repeated user correction, reusable lesson | `Harness/MEMORY.md`, the relevant `Harness/memory/*.md` file |
+| event, retry, failure path | `Harness/data-flow.md` |
+| status, transition, resume | `Harness/state-machines.md` |
+| subagent spawn | `Harness/subagents.md`, this file plus the role pack below |
 
 ## Subagent Packs
 

package/templates/common/docs/harness/data-flow.md

@@ -1,7 +1,7 @@
 # Data Flow — {{projectName}}
 
 > **Purpose**: Define the complete lifecycle of each event/request — happy path + all failure branches.
-> **This is the most important file in the entire docs folder** — what AI most often invents during implementation is failure-path behavior. Write it clearly and it won't.
+> **This is the most important runtime-flow file in `Harness/`** — what AI most often invents during implementation is failure-path behavior. Write it clearly and it won't.
 >
 > Philosophy source: EventCatalog pattern + arc42 Chapter 6 (Runtime View).
 

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

@@ -2,13 +2,15 @@
 
 Purpose: coordinate a small set of subagents without building a scheduler.
 
+Use [subagents.md](subagents.md) for orchestration strategy. Use this file for the dispatch table, handoff format, and status protocol.
+
 Use when work needs parallel reading, independent review, cross-layer analysis, or more than one bounded implementation pass.
 
 ## Principles
 
 - Main agent owns the final decision, integration, and verification.
 - 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 `docs/harness/PLAN.md`, the current feature doc, `MEMORY.md`, or `memory/*` as appropriate.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 - Prefer three or fewer active agents.
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint.
@@ -20,6 +22,7 @@ Use when work needs parallel reading, independent review, cross-layer analysis,
 ```text
 Goal
 -> Fill PLAN tasks and Parallel Dispatch
+-> Apply subagents.md efficiency ladder
 -> Run parallel read-only agents
 -> Main agent integrates findings
 -> Test Writer defines failing test or manual check
@@ -78,7 +81,7 @@ PLAN patch:
 ```
 
 Use `Files changed: none` for read-only agents. Use `PLAN patch: none` when no state update is needed.
-If a handoff matters after context loss, write it to `docs/harness/PLAN.md`, the current feature doc, or `memory/*`; do not rely on chat transcript state.
+If a handoff matters after context loss, write it to `Harness/PLAN.md`, the current feature doc, or `Harness/memory/*`; do not rely on chat transcript state.
 
 ## Statuses
 

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

@@ -8,12 +8,12 @@ Use during setup whenever adding assets from ECC, SuperClaude, toolboxes, or loc
 
 Extensions must preserve project and harness ownership boundaries.
 
-- Preserve existing `.claude/`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`, `docs/README.md`, `docs/workflows/*.md`, settings, hooks, and local rules unless the user explicitly requests an overwrite.
+- Preserve existing `.claude/`, `CLAUDE.md`, `AGENTS.md`, `.gitignore`, `Harness/README.md`, `Harness/workflows/*.md`, settings, hooks, and local rules unless the user explicitly requests an overwrite.
 - Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
-- Register added agents, skills, workflows, rules, and hooks in `MEMORY.md` and this docs router where applicable.
-- Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `docs/workflows/`, but they must not replace core harness docs.
-- Core harness docs are `docs/README.md`, `docs/harness/PLAN.md`, `docs/harness/context-loading.md`, `docs/harness/dispatch.md`, `docs/harness/agent-workflow.md`, and this file.
-- If an optional workflow needs a new command or tool, document the command and fallback in `docs/workflows/<name>.md` instead of changing core harness behavior.
+- Register added agents, skills, workflows, rules, and hooks in `Harness/MEMORY.md` and this docs router where applicable.
+- Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `Harness/workflows/`, but they must not replace core harness docs.
+- Core harness docs are `Harness/README.md`, `Harness/PLAN.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
+- If an optional workflow needs a new command or tool, document the command and fallback in `Harness/workflows/<name>.md` instead of changing core harness behavior.
 
 ## Agent Contract
 
@@ -44,7 +44,7 @@ Agent body must state:
 - allowed write set or read-only
 - forbidden scope
 - verification or evidence
-- return format from [dispatch.md](dispatch.md)
+- return format from [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
 
 ## Skill Contract
 
@@ -55,10 +55,10 @@ Every added skill must state:
 - required inputs
 - allowed writes
 - output format
-- whether to update `docs/harness/PLAN.md`
-- whether to use [dispatch.md](dispatch.md)
+- whether to update `Harness/PLAN.md`
+- whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
 
-Skills should extend the harness. They should not replace `docs/README.md`, `PLAN.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
+Skills should extend the harness. They should not replace `Harness/README.md`, `PLAN.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
 
 ## Rules
 
@@ -72,8 +72,8 @@ Skills should extend the harness. They should not replace `docs/README.md`, `PLA
 
 After adding assets:
 
-- list agents in `MEMORY.md#Agents`
-- list skills in `MEMORY.md#Skills`
-- list workflows by path in `MEMORY.md` or `docs/README.md`
-- update `docs/harness/PLAN.md` when the asset affects current work
-- run `node scripts/validate-harness.mjs`
+- list agents in `Harness/MEMORY.md#Agents`
+- list skills in `Harness/MEMORY.md#Skills`
+- list workflows by path in `Harness/MEMORY.md` or `Harness/README.md`
+- update `Harness/PLAN.md` when the asset affects current work
+- run `node Harness/scripts/validate-harness.mjs`

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

@@ -9,8 +9,8 @@ Use when starting a new product, clarifying a vague idea, or deciding the next p
 | Idea | user intent | problem, target user, non-goals | unclear points asked or assumptions recorded |
 | Research | problem and constraints | `research/research-results.md` | `research/README.md` followed; at least 3 references or explicit reason not possible |
 | PRD | research decision | `research/PRD.md` | MVP, non-goals, acceptance criteria are verifiable |
-| Architecture | PRD | `harness/architecture.md`, `domain/ports.md` | boundaries and first ports are defined |
-| Plan | PRD and architecture | `docs/harness/PLAN.md`, optional `docs/harness/dispatch.md`, one `docs/features/<name>.md` per PRD scope item | tasks have owners, write sets, verification |
+| Architecture | PRD | `Harness/architecture.md`, `Harness/domain/ports.md` | boundaries and first ports are defined |
+| Plan | PRD and architecture | `Harness/PLAN.md`, optional `Harness/dispatch.md`, one `Harness/features/<name>.md` per PRD scope item | tasks have owners, write sets, verification |
 | Build | plan and tests | minimal vertical slice | tests or manual checks prove behavior |
 | Verify | implementation | review findings, test evidence | no unresolved critical/high findings |
 | Feedback | verified slice | next iteration or release decision | learnings recorded in PRD, PLAN, or MEMORY |

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

@@ -0,0 +1,140 @@
+# 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/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+
+## Source Attribution
+
+This harness distills ideas from these sources. Keep the protocol local and conservative; do not import external runtimes by default.
+
+| Source | Found By | Adopted Idea |
+| --- | --- | --- |
+| `superpowers:dispatching-parallel-agents` | local skill | Dispatch one agent per independent problem domain; give focused scope and exact context. |
+| `superpowers:subagent-driven-development` | local skill | Fresh implementer per task; spec review before code-quality review; handle `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, and `BLOCKED`. |
+| [`flc1125/skills@subagent-orchestrator`](https://skills.sh/flc1125/skills/subagent-orchestrator) | `npx skills find "subagent orchestration"` | Explicit subagent invocation, role-specific prompts, tool permission awareness. |
+| [`davila7/claude-code-templates@parallel-agents`](https://skills.sh/davila7/claude-code-templates/parallel-agents) | `npx skills find "parallel agents"` | Discovery -> domain agents -> synthesis; one unified synthesis instead of scattered reports. |
+| [`ruvnet/ruflo@agent-workflow`](https://skills.sh/ruvnet/ruflo/agent-workflow) | `npx skills find "agent workflow"` | Workflow thinking: triggers, agent assignments, parallel processing, and stateful handoffs. |
+| [`pcvelz/superpowers@subagent-driven-development`](https://skills.sh/pcvelz/superpowers/subagent-driven-development) | `npx skills find "subagent driven development"` | Implementer plus review gates for spec compliance and code quality. |
+| [`oimiragieo/agent-studio`](https://skills.sh/oimiragieo/agent-studio/dispatching-parallel-agents) | Skills CLI / public docs | Router-subordinate architecture and durable handoff discipline. |
+| [`subagent-orchestration-skill`](https://skills.rest/rjtaryn/skills/subagent-orchestration-skill) | public docs | Multi-stage executor, spec reviewer, code reviewer, circuit breaker, and escalation pattern. |
+
+## Controller Role
+
+The main agent is the controller. It owns:
+
+- intent confidence and user questions
+- task decomposition
+- read/write set boundaries
+- dispatch table in `Harness/PLAN.md`
+- integration of returned summaries
+- final verification and closeout
+
+Subagents provide bounded work. They do not own final scope, architecture, release claims, or user-facing decisions.
+
+## Efficiency Ladder
+
+Choose the cheapest coordination level that is safe.
+
+| Level | Use When | Pattern |
+| --- | --- | --- |
+| 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 | test-writer -> implementer -> reviewers -> verifier |
+| Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
+
+Default: at most three active subagents. More agents increase coordination cost and conflict risk.
+
+## WF Orchestration Shape
+
+```text
+controller intake
+-> parallel explorer/researcher/docs-researcher/architect passes
+-> controller synthesis
+-> second plan with dependencies and write sets
+-> test-writer
+-> implementer
+-> spec reviewer
+-> code/architecture reviewer
+-> verifier
+-> if failed: debugger/fixer -> review -> verify -> loop
+-> close with evidence
+```
+
+Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
+
+## Dispatch Pack
+
+Every subagent dispatch must be self-contained:
+
+```text
+Role:
+Goal:
+Mode: read-only | write
+Read set:
+Write set:
+Forbidden scope:
+Injected docs:
+Dependencies:
+Expected evidence:
+Stop condition:
+Return format:
+```
+
+Do not make a subagent rediscover the entire project or read the whole harness. Inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
+
+## Parallelism Rules
+
+- Read-only agents may run in parallel.
+- Writing agents run serially unless write sets are disjoint and the controller has chosen an isolated worktree.
+- Reviewers may run in parallel after implementation, but spec compliance is evaluated before code-quality approval.
+- Do not let two agents edit `Harness/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
+- If two agents disagree, the controller records the conflict in `Harness/PLAN.md` and chooses the smallest reversible next step.
+
+## Review Gates
+
+Implementation is not complete until both gates pass:
+
+1. **Spec review**: confirms the result matches the user request, PRD, feature doc, acceptance criteria, and non-goals. Extra features are failures.
+2. **Code-quality review**: checks correctness, maintainability, architecture, tests, security, and integration risk.
+
+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.
+
+## Subagent Status Handling
+
+| Status | Controller Action |
+| --- | --- |
+| `DONE` | start review gates |
+| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `PLAN.md` |
+| `NEEDS_CONTEXT` | provide only missing context and re-dispatch |
+| `BLOCKED` | change something: add context, split task, upgrade reasoning, use debugger, or ask user |
+
+Never retry the same failed prompt unchanged.
+
+## Failure Recovery
+
+- First failed verification: record evidence, dispatch debugger with the smallest reproduced failure.
+- Second same-class failure: narrow scope, update `PLAN.md#Heartbeat`, and add a reviewer before another fix.
+- Third same-class failure: stop blind fixes. Present evidence-backed options to the user.
+
+The recovery loop must preserve the same evidence standard as the main workflow: real commands, real browser/API checks when applicable, and recorded logs or artifacts.
+
+## Synthesis Output
+
+After subagents return, the controller writes one synthesis into `Harness/PLAN.md`:
+
+```text
+Agents used:
+Findings accepted:
+Findings rejected:
+Conflicts:
+Decisions:
+Next write set:
+Verification path:
+Residual risk:
+```
+
+Only the synthesis and named files enter main context. Do not replay full subagent conversations.

package/templates/common/docs/research/PRD.md

@@ -15,7 +15,7 @@
 
 ### v0.1 Must Be Able To
 
-> Each item below must be split into a separate `docs/features/<name>.md` created from `docs/features/_template.md` before implementation begins. One feature = one doc = one implementation unit.
+> Each item below must be split into a separate `Harness/features/<name>.md` created from `Harness/features/_template.md` before implementation begins. One feature = one doc = one implementation unit.
 
 - [ ] {{MUST_1}}
 - [ ] {{MUST_2}}

package/templates/common/docs/research/README.md

@@ -6,7 +6,7 @@ Purpose: guide agent research. Record conclusions in [research-results.md](resea
 
 Use this before PRD, stack choice, external API use, public dependency choice, pricing/legal/security assumptions, or any fact likely to change.
 
-Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `docs/harness/PLAN.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/PLAN.md`.
 
 ## Research Agent
 
@@ -21,7 +21,7 @@ Built-in agents:
 - `.claude/agents/researcher.md`: product, market, open-source, dependency, pricing, policy, and ecosystem research.
 - `.claude/agents/docs-researcher.md`: official docs, API, SDK, config, limits, errors, and examples verification.
 
-For multi-agent research plus build work, create the dispatch table in `docs/harness/PLAN.md` and follow `docs/harness/dispatch.md`.
+For multi-agent research plus build work, create the dispatch table in `Harness/PLAN.md` and follow `Harness/dispatch.md`.
 
 Research Agent input:
 
@@ -104,14 +104,14 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Write Target
 
-- Research process, queries, and limitations: this file or `docs/harness/PLAN.md`.
+- Research process, queries, and limitations: this file or `Harness/PLAN.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
-- Architecture consequences: `docs/harness/architecture.md` and `docs/domain/ports.md`.
+- Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.
 
 ## Architecture Decision References
 
-When filling `docs/harness/architecture.md`, `docs/domain/ports.md`, and `docs/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
+When filling `Harness/architecture.md`, `Harness/domain/ports.md`, and `Harness/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
 
 ### System Design & Architecture Patterns