create-harness-vibe-coding 0.2.0 → 0.3.0

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

@@ -34,7 +34,17 @@
 - [ ] {{ACCEPTANCE_CRITERION_2}}
 - [ ] {{ACCEPTANCE_CRITERION_3}}
 
-### 1.5 UI Automation Hooks
+### 1.5 Optimistic UI Rollback
+
+If any UI mutation happens before an async operation completes (DOM replacement,
+state update, visual feedback), list the rollback path for when the operation fails:
+
+| Mutation | Failure Recovery |
+|----------|-----------------|
+| {{MUTATION_1}} | {{ROLLBACK_1}} |
+| Not applicable — no optimistic mutations are used. | |
+
+### 1.6 UI Automation Hooks
 
 For TS/React or browser workflows, define required stable accessible labels/roles and stable test hooks such as `data-testid` before implementation. These selectors must cover critical UI controls and states so CDP, Playwright, and manual verification can target inputs, buttons, filters, rows, empty/error/loading states, dialogs, navigation, and submitted/saved/error feedback without brittle DOM paths.
 

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

@@ -1,103 +1,52 @@
-# PLAN.md - Active Execution Plan
+# PLAN.md — DEPRECATED
 
-Use this file when work spans more than one step, one file, or one agent.
+Workflow state has moved to task-capsule structure. Do not append new content here.
 
-## Current Goal
+Active state:
+- `Harness/PROGRESS.md` — global task index and cross-task decisions
+- `Harness/tasks/<task-id>/PROGRESS.md` — per-task progress, phase, heartbeat
+- `Harness/tasks/<task-id>/PLAN.md` — per-task implementation plan, verification evidence
 
-{{CURRENT_GOAL}}
+Templates:
+- `Harness/tasks/_template/` — copy this directory to create a new task
 
-## Phase
+## Legacy Content (historical reference only)
 
-Choose one: Idea / Research / PRD / Architecture / Plan / Build / Verify / Feedback.
+The sections below are archived from the monolithic PLAN.md era. Active task data has been migrated to `Harness/tasks/`.
 
-Current: {{CURRENT_PHASE}}
+---
 
-## Heartbeat
+### Historical: Dogfood Bootstrap
 
-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}}
+Goal: Dogfood the generated Harness scaffold inside this repository so future agents use root `Harness/` routing instead of stale `docs/harness/` guidance.
 
-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.
+**Success Criteria** (all verified):
+- [x] Root `CLAUDE.md` routes through `Harness/MEMORY.md` and `Harness/README.md`
+- [x] Root `MEMORY.md` no longer contains stale `docs/harness/` paths or template placeholders
+- [x] Root `Harness/` and `.claude/` dogfood runtime assets exist
+- [x] Harness strict validation passes
+- [x] Repository tests pass
 
-## Progress Rules
-
-- Phase tracks lifecycle progress.
-- Task status tracks execution progress.
-- Update before handoff, after verification, and when blocked.
-
-Allowed task statuses: Pending / In Progress / Blocked / Done / Verified.
-
-- Pending: not started.
-- In Progress: active work.
-- Blocked: needs user input or external change.
-- Done: task complete, evidence not final.
-- Verified: verification evidence is recorded.
-
-## Success Criteria
-
-- [ ] {{CRITERION_1}}
-- [ ] {{CRITERION_2}}
-- [ ] {{CRITERION_3}}
-
-## Scope
-
-Allowed write set:
-- `{{PATH_OR_GLOB}}`
-
-Forbidden:
-- {{OUT_OF_SCOPE}}
-
-## Loaded Context
-
-Keep this list short. Add only docs/files used for the current phase.
-
-- `Harness/README.md`
-- `{{LOADED_DOC_OR_FILE}}`
-
-## Tasks
-
-| # | Task | Owner | Verify | Status |
-| --- | --- | --- | --- | --- |
-| 1 | {{TASK}} | {{OWNER}} | `{{COMMAND_OR_CHECK}}` | Pending |
-
-## Parallel Dispatch
-
-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 |
-| --- | --- | --- | --- |
-| {{AGENT}} | {{ROLE}} | {{DOCS_OR_FILES}} | {{SUMMARY}} |
+**Decisions:**
+| Date | Decision | Reason |
+|------|----------|--------|
+| 2026-06-24 | Dogfood root `Harness/` while keeping templates under `templates/` | Separate package source from operating harness |
+| 2026-06-24 | memory-master + context-master added to commonAgents | Global memory and context management |
 
-## Decisions
+### Historical: WF Conflict Fix
 
-| Date | Decision | Reason |
-| --- | --- | --- |
-| {{YYYY-MM-DD}} | {{DECISION}} | {{REASON}} |
+Goal: Fix WF-mode orphaned files and conflicts: align commands/wf.md, resolve subagent count tension, fix README "may" vs "MUST", add memory-master and context-master agents.
 
-## Verification
+**Subagent Dispatch:**
+| Agent | Mode | Purpose | Status |
+|-------|------|---------|--------|
+| Subagent 1 | Serial Write | Create memory-master.md, context-master.md, update commands/wf.md | Verified |
+| Subagent 2 | Serial Write | Fix agent-workflow.md, dispatch.md, README.md conflicts | Verified |
+| Subagent 3 | Serial Write | Update WF.md, wf-mode/SKILL.md, subagents.md, MEMORY.md, context-loading.md, CLAUDE.md, validate-harness.mjs | Verified |
+| Subagent 4 | Serial Write | Sync template changes to dogfood runtime files | Verified |
 
+**Verification:**
 | Check | Result | Notes |
-| --- | --- | --- |
-| `{{CHECK}}` | Not run | {{NOTES}} |
+|-------|--------|-------|
+| `node Harness/scripts/validate-harness.mjs --strict` | Pass | all invariants preserved |
+| `npm test` | Pass | 58/58 tests passed |

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

@@ -0,0 +1,17 @@
+# PROGRESS.md
+
+Global task index. Load at session start to see what is active and what was done.
+
+## Active Task
+
+None — create a new task from `Harness/tasks/_template/` when work spans more than one step.
+
+## Task Index
+
+| ID | Goal | Phase | Closed |
+|----|------|-------|--------|
+
+## Cross-Task Decisions
+
+| Date | Decision | Reason |
+|------|----------|--------|

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

@@ -1,6 +1,6 @@
 # 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`.
+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.
 
@@ -8,18 +8,28 @@ This is a Ralph-style harness loop: keep moving through evidence, bounded explor
 
 Enter WF mode when any of these are true:
 
-- The user explicitly says `/wf`, `wf mode`, or asks for the full workflow.
+- 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/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.
+
 ## WF Loop
 
 ```text
 Intake
 -> confidence gate
--> parallel explorer / researcher / docs-researcher / architect passes
+-> parallel planner / researcher / docs-researcher / architect subagents
 -> synthesis
 -> second plan
 -> test-writer
@@ -32,30 +42,31 @@ Intake
 
 ## Intake
 
-1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, and `Harness/PLAN.md`.
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/PROGRESS.md`, and the current task's `PROGRESS.md` and `PLAN.md` under `Harness/tasks/<task-id>/`.
 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.
+4. Update `Harness/tasks/<task-id>/PROGRESS.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 passes first. Prefer three or fewer active agents.
+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 |
 | --- | --- | --- |
-| Explorer Pass | map local project facts, commands, app entry points, existing docs | none |
+| `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`.
+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/tasks/<task-id>/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.
+- Subagents are readers and reporters. Only the main agent writes to task PROGRESS.md and PLAN.md. Subagents return PLAN patch suggestions which the main agent reviews before committing.
 - 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.
@@ -74,7 +85,7 @@ After exploration, synthesize:
 - verification path
 - rollback or recovery plan
 
-Write the result to `Harness/PLAN.md` before implementation.
+Write the result to `Harness/tasks/<task-id>/PLAN.md` before implementation. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
 
 ## Build And Review
 
@@ -101,20 +112,20 @@ For API changes, run the project API/integration test path or a documented real
 
 If verification fails:
 
-1. Update `Harness/PLAN.md#Heartbeat` with failure count and blocker.
+1. Update `Harness/tasks/<task-id>/PROGRESS.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.
+If the same failure class happens three times, stop blind fixes. Before asking the user, dispatch `memory-master` to record the failure pattern, attempted paths, and root cause hypothesis to `Harness/memory/agent-lessons-patterns.md`. Then present evidence-backed options to the user.
 
 ## Heartbeat Protocol
 
 Heartbeat is a lightweight recovery protocol, not a background daemon.
 
-Update `Harness/PLAN.md#Heartbeat`:
+Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`:
 
 - before a long command
 - after a long command
@@ -125,6 +136,8 @@ Update `Harness/PLAN.md#Heartbeat`:
 
 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".
 
+When context approaches ~85% of the window, dispatch `context-master` to analyze and append a compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`. The suggestion is non-blocking; the controller checks it at the next natural pause point.
+
 ## Closeout
 
 Close only when:
@@ -133,4 +146,9 @@ Close only when:
 - 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
+- `context-master` has analyzed the session and extracted durable knowledge
+- `memory-master` has consolidated extracted knowledge into `Harness/memory/*` and `Harness/MEMORY.md`
+- Current task PROGRESS.md and PLAN.md are archived under `Harness/tasks/<task-id>/` with Phase set to Verified
+- `Harness/PROGRESS.md` task index is updated (Closed column filled, Active Task cleared or set to next task)
+- `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` says the task is verified or lists the exact next recovery action
+- `Harness/PROGRESS.md` task index reflects the closed task

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

@@ -5,16 +5,26 @@ Use when implementing, reviewing, debugging, or coordinating subagents.
 ## ReAct Loop
 
 ```text
-Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/PLAN.md
+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 (`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.
+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.
 
-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.
+**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.
 
@@ -58,16 +68,16 @@ Rules:
 
 ## Parallel Dispatch
 
-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.
+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)). 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, Harness/PLAN.md, architecture, ports, tests, or code disagree:
+If PRD, task PLAN.md, architecture, ports, tests, or code disagree:
 
 1. stop implementation
-2. record the conflict in `Harness/PLAN.md` or the feature doc
+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
 
@@ -79,4 +89,6 @@ 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
-- `Harness/PLAN.md` states the final status or next iteration
+- 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

@@ -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/tasks/<task-id>/PROGRESS.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

@@ -6,9 +6,9 @@ Use when context is growing, subagents are needed, or an agent is unsure which h
 
 `Harness/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
 
-If this file and `Harness/README.md` disagree, follow `Harness/README.md`, record the assumption in `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/tasks/<task-id>/PROGRESS.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 `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/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/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Main Context
 
@@ -17,7 +17,9 @@ Always keep:
 - `CLAUDE.md`
 - `Harness/MEMORY.md`
 - `Harness/README.md`
-- `Harness/PLAN.md` when active
+- `Harness/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PROGRESS.md` when active
+- `Harness/tasks/<task-id>/PLAN.md` when active
 - current feature doc when active
 
 Load other docs only by trigger.
@@ -30,8 +32,8 @@ Load other docs only by trigger.
 | 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` |
+| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/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` |
@@ -89,6 +91,16 @@ Verifier:
 - forbid: code changes
 - return: commands run, results, residual risk
 
+Memory Master:
+- inject: trigger reason, current failure/user-correction/closeout context, task PROGRESS.md section
+- forbid: source code, unrelated Harness docs
+- return: memory action summary, files written, cross-project flag
+
+Context Master:
+- inject: trigger reason (threshold % or closeout), current task PROGRESS.md, task phase
+- forbid: source code, memory files, MEMORY.md writes
+- return: context usage %, stale blocks, compressible blocks, durable knowledge candidates, compression suggestion
+
 ## Handoff Rule
 
 Only the subagent summary enters main context. If details are needed, load the named files directly instead of replaying the subagent conversation.

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

@@ -10,18 +10,19 @@ Use when work needs parallel reading, independent review, cross-layer analysis,
 
 - 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 `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Prefer three or fewer active agents.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+- Prefer three or fewer active agents (WF mode overrides this; see [WF.md](WF.md)).
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint.
 - Use a worktree when two agents may touch overlapping files or long-running branches.
 - Only summaries enter main context. Load named files directly when details are needed.
+- Subagents read task files, return findings and PLAN patch suggestions. Only the main agent commits changes to PROGRESS.md and PLAN.md.
 
 ## Dispatch Loop
 
 ```text
 Goal
--> Fill PLAN tasks and Parallel Dispatch
+-> Fill task PROGRESS.md and PLAN.md
 -> Apply subagents.md efficiency ladder
 -> Run parallel read-only agents
 -> Main agent integrates findings
@@ -29,7 +30,7 @@ Goal
 -> Implementer makes bounded change
 -> Reviewer checks diff
 -> Verifier records evidence
--> Main agent updates PLAN and closes or iterates
+-> Main agent updates task files and closes or iterates
 ```
 
 ## Modes
@@ -54,6 +55,8 @@ Goal
 | `debugger` | Serial Write | smallest fix for a reproduced failure |
 | `reviewer` | Parallel Read | diff review, risks, missing tests |
 | `verifier` | Parallel Read | run checks and record evidence |
+| `memory-master` | Serial Write | write/consolidate memory entries, dedup, cross-project extraction |
+| `context-master` | Parallel Read | analyze context usage, recommend compression, extract session knowledge |
 
 ## Dispatch Rules
 
@@ -61,7 +64,7 @@ Goal
 - A write set of `none` means read-only.
 - If two write sets overlap, do not run those agents in parallel.
 - If an agent returns uncertainty, mark the row `Blocked` or add a follow-up row.
-- If docs, tests, and code disagree, stop implementation and record the conflict in `PLAN.md`.
+- If docs, tests, and code disagree, stop implementation and record the conflict in `Harness/tasks/<task-id>/PROGRESS.md`.
 
 ## Handoff Format
 
@@ -81,7 +84,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 `Harness/PLAN.md`, the current feature doc, or `Harness/memory/*`; do not rely on chat transcript state.
+If a handoff matters after context loss, write it to `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, or `Harness/memory/*`; do not rely on chat transcript state.
 
 ## Statuses
 

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

@@ -12,7 +12,7 @@ Extensions must preserve project and harness ownership boundaries.
 - 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 `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.
+- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.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
@@ -55,10 +55,10 @@ Every added skill must state:
 - required inputs
 - allowed writes
 - output format
-- whether to update `Harness/PLAN.md`
+- whether to update `Harness/PROGRESS.md` and task files
 - whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.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`.
+Skills should extend the harness. They should not replace `Harness/README.md`, `Harness/PROGRESS.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
 
 ## Rules
 
@@ -75,5 +75,5 @@ After adding assets:
 - 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
+- update `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md` when the asset affects current work
 - run `node Harness/scripts/validate-harness.mjs`

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

@@ -10,10 +10,10 @@ Use when starting a new product, clarifying a vague idea, or deciding the next p
 | 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`, `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 |
+| Plan | PRD and architecture | `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/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 |
+| Feedback | verified slice | next iteration or release decision | learnings recorded in PRD, `Harness/tasks/<task-id>/PROGRESS.md`, or MEMORY |
 
 ## Operating Rules
 

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 |