create-harness-vibe-coding 0.1.10 → 0.2.1

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

@@ -1,6 +1,6 @@
 # {{FEATURE_NAME}}
 
-> **When to use**: Every PRD scope item in `research/PRD.md` Section 2 must have a feature doc — either a new one from this template, or an iteration on an existing one. Do not code a PRD scope item without a corresponding features doc.
+> **When to use**: Every PRD scope item in `Harness/research/PRD.md` Section 2 must have a feature doc — either a new one from this template, or an iteration on an existing one. Do not code a PRD scope item without a corresponding features doc.
 >
 > **New vs iterate**: If the scope item has ≥85% overlap with an existing feature doc, iterate the existing doc (bump `Version`, add a `## Changelog` entry). If overlap is below 85%, create a new file from this template. When in doubt, ask the user.
 
@@ -52,10 +52,10 @@ For TS/React or browser workflows, define required stable accessible labels/role
 
 | Area | Impacted? | Notes |
 | --- | --- | --- |
-| `harness/architecture.md` | {{YES_NO}} | {{NOTE}} |
-| `domain/ports.md` | {{YES_NO}} | {{NOTE}} |
-| `harness/data-flow.md` | {{YES_NO}} | {{NOTE}} |
-| `harness/state-machines.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/architecture.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/domain/ports.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/data-flow.md` | {{YES_NO}} | {{NOTE}} |
+| `Harness/state-machines.md` | {{YES_NO}} | {{NOTE}} |
 | tests | {{YES_NO}} | {{NOTE}} |
 
 ### 2.2 Allowed Write Set
@@ -132,11 +132,11 @@ Estimate the context budget for this feature. If the main agent would need to re
 
 ### 4.3 Docs Sync
 
-- [ ] `harness/architecture.md`
-- [ ] `domain/ports.md`
-- [ ] `harness/data-flow.md`
-- [ ] `harness/state-machines.md`
-- [ ] `research/research-results.md`
+- [ ] `Harness/architecture.md`
+- [ ] `Harness/domain/ports.md`
+- [ ] `Harness/data-flow.md`
+- [ ] `Harness/state-machines.md`
+- [ ] `Harness/research/research-results.md`
 - [ ] Not needed because {{REASON}}
 
 ### 4.4 Decision Log

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

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

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

@@ -0,0 +1,146 @@
+# WF Mode - Long Task Workflow
+
+Use this when work is long, difficult, uncertain, multi-file, multi-agent, or user-triggered with `/wf`, `wf mode`, `workflow mode`, or `wk 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`, `workflow mode`, `wk 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.
+
+## Multi-Subagent Requirement
+
+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.
+- Default initial fan-out: `planner`, `researcher` or `docs-researcher`, and `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when the phase needs them.
+- Record every dispatch or bounded-pass fallback in `Harness/PLAN.md#Parallel Dispatch`.
+- If subagents are unavailable, emulate the same roles as separate bounded passes and record why the fallback was used.
+
+## WF Loop
+
+```text
+Intake
+-> confidence gate
+-> parallel planner / researcher / docs-researcher / architect subagents
+-> 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; explicit WF/WK mode always coordinates multiple roles.
+
+## Exploration
+
+Use parallel read-only subagents first. Explicit WF/WK mode starts with at least three distinct `.claude/agents/` roles before the second plan. For automatic WF triggers, default to 3-5 active agents unless the task is clearly small enough for the solo exception.
+
+| Agent | Purpose | Writes |
+| --- | --- | --- |
+| `planner` | map local project facts, commands, app entry points, existing docs, and initial decomposition | 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/architecture.md

@@ -41,9 +41,33 @@
 
 ---
 
-## 2. Harness Core Components
+## 2. Interface Decoupling
 
-### 2.1 Runner / Loop
+Use interfaces or ports to protect real boundaries, not to create abstraction for its own sake.
+
+- Define a port when code crosses a layer, process, network, storage, SDK, browser, or permission boundary.
+- Keep domain and application logic independent from infrastructure adapters.
+- Pass data through explicit contracts instead of reaching into another feature's internals.
+- Prefer direct calls inside the same cohesive module when there is only one caller, one implementation, and no boundary to protect.
+- Avoid speculative abstraction: do not add factories, plugin systems, service locators, generic repositories, or config layers until the feature has a concrete second use or a real testability/replacement need.
+
+---
+
+## 3. State Design
+
+State must have one owner, legal transitions, and observable recovery behavior.
+
+- Identify durable state, runtime cache, derived UI state, external system state, and audit/event history separately.
+- Name the owner of each state slice; do not let UI, application services, and infrastructure all mutate the same state directly.
+- Model long-running workflows with explicit states, guards, and failure transitions in `Harness/state-machines.md`.
+- Store resumable progress and recovery decisions in `Harness/PLAN.md#Heartbeat` or project-owned durable storage, not only in chat.
+- Keep state minimal: derive values when cheap, persist only what must survive reload, retry, or handoff.
+
+---
+
+## 4. Harness Core Components
+
+### 4.1 Runner / Loop
 
 - **Responsibility**: Drives a task from input to completion: loading context, calling application use-cases, handling stop conditions.
 - **Design Decision**:
@@ -51,28 +75,28 @@
   - Stop conditions are explicitly modeled — Rationale: prevents agent loops from running indefinitely or silently half-completing
 - **Does NOT handle**: Business rules, domain object creation details, external service implementations
 
-### 2.2 Permission Policy
+### 4.2 Permission Policy
 
 - **Responsibility**: Decides whether a given tool, file, network, or external action is allowed to execute.
 - **Design Decision**:
   - High-risk actions are denied by default, allow rules are explicitly declared — Rationale: the platform must first guarantee security boundaries
 - **Does NOT handle**: Judging whether a business action is correct
 
-### 2.3 Event Bus / Audit Trail
+### 4.3 Event Bus / Audit Trail
 
 - **Responsibility**: Records task lifecycle, tool invocations, failures, human approvals, and final results.
 - **Design Decision**:
   - Events are append-only, audit records cannot be overwritten in place — Rationale: facilitates replay, debugging, and post-mortem analysis
 - **Does NOT handle**: Saving final data on behalf of business systems
 
-### 2.4 State / Checkpoint Store
+### 4.4 State / Checkpoint Store
 
 - **Responsibility**: Saves recoverable state, context summaries, task progress, and interrupt points.
 - **Design Decision**:
   - State format must be serializable — Rationale: enables replay, resume, testing, and migration
 - **Does NOT handle**: Long-term business database modeling
 
-### 2.5 Tool Registry
+### 4.5 Tool Registry
 
 - **Responsibility**: Registers callable tools along with their input/output contracts, permission labels, and error semantics.
 - **Design Decision**:
@@ -81,7 +105,7 @@
 
 ---
 
-## 3. Architectural Constraints (Non-Negotiable)
+## 5. Architectural Constraints (Non-Negotiable)
 
 - `domain/` only defines business models, business invariants, and port protocols; does not import `harness/`, `infrastructure/`, or `interfaces/`.
 - `harness/` may orchestrate workflows, security gates, auditing, and stop conditions, but must not determine business meaning.

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/state-machines.md

@@ -10,6 +10,14 @@
 
 Fill out each stateful component using this format:
 
+Before defining states, name the state owner and persistence level. State that crosses agent handoff, retry, browser session, API workflow, or release boundary must have explicit transitions; temporary derived state should stay local and should not become a new state machine.
+
+### State Ownership
+
+| State Slice | Owner | Persistence | Notes |
+| --- | --- | --- | --- |
+| `{{STATE_SLICE}}` | `{{OWNER}}` | durable / runtime / derived / external | {{NOTES}} |
+
 ### State Enumeration
 
 | State | Description | Entry Condition | Exit Condition |