create-harness-vibe-coding 0.2.1 → 0.3.0

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

@@ -21,7 +21,7 @@ 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`.
+- 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
@@ -42,10 +42,10 @@ 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.
+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
@@ -59,13 +59,14 @@ Use parallel read-only subagents first. Explicit WF/WK mode starts with at least
 | `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.
@@ -84,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
 
@@ -111,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
@@ -135,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:
@@ -143,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

@@ -60,7 +60,7 @@ 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.
+- 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.
 
 ---

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/subagents.md

@@ -4,7 +4,7 @@ Purpose: coordinate subagents for speed without losing control of scope, evidenc
 
 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.
+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.
 
 ## Source Attribution
 
@@ -28,7 +28,7 @@ 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`
+- dispatch table in `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`
 - integration of returned summaries
 - final verification and closeout
 
@@ -49,6 +49,8 @@ Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
 | `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
 | `debugger` | reproduced failures, root cause isolation, smallest safe fix |
 | `verifier` | command execution, real browser/API checks, final evidence |
+| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
+| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
 
 ## WF Default Fan-Out
 
@@ -67,6 +69,8 @@ Then add phase-specific agents:
 - `reviewer` for spec and code-quality gates
 - `debugger` after a reproduced verification failure
 - `verifier` for final command/browser/API evidence
+- `context-master` before closeout for knowledge extraction
+- `memory-master` after repeated failures and during closeout for consolidation
 
 The default decision ratio is a 7:3 collaboration bias: choose multi-agent collaboration for substantial or uncertain work about 70% of the time; choose solo mode only for clearly local, low-risk work that is not explicitly in WF/WK mode.
 
@@ -127,8 +131,9 @@ Do not make a subagent rediscover the entire project or read the whole harness.
 - 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.
+- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) commits state changes to task files.
+- Do not let two agents edit `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/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/tasks/<task-id>/PLAN.md` and chooses the smallest reversible next step.
 
 ## Review Gates
 
@@ -144,7 +149,7 @@ If either reviewer finds issues, the implementer or debugger fixes them and the
 | Status | Controller Action |
 | --- | --- |
 | `DONE` | start review gates |
-| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `PLAN.md` |
+| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `Harness/tasks/<task-id>/PROGRESS.md` |
 | `NEEDS_CONTEXT` | provide only missing context and re-dispatch |
 | `BLOCKED` | change something: add context, split task, upgrade reasoning, use debugger, or ask user |
 
@@ -153,14 +158,14 @@ 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.
+- Second same-class failure: narrow scope, update `Harness/tasks/<task-id>/PROGRESS.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`:
+After subagents return, the controller writes one synthesis into `Harness/tasks/<task-id>/PLAN.md`:
 
 ```text
 Agents used:

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 `Harness/PLAN.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PROGRESS.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 `Harness/PLAN.md` and follow `Harness/dispatch.md`.
+For multi-agent research plus build work, create the dispatch table in `Harness/tasks/<task-id>/PLAN.md` and follow `Harness/dispatch.md`.
 
 Research Agent input:
 
@@ -104,7 +104,7 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Write Target
 
-- Research process, queries, and limitations: this file or `Harness/PLAN.md`.
+- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PROGRESS.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
 - Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.

package/templates/common/docs/tasks/_template/ARTIFACTS.md

@@ -0,0 +1,3 @@
+# {{TASK_ID}} — Artifacts
+
+Optional: screenshots, logs, API responses, links. Create only when evidence is too large for this task's PLAN.md verification table.

package/templates/common/docs/tasks/_template/NOTES.md

@@ -0,0 +1,3 @@
+# {{TASK_ID}} — Notes
+
+Optional: exploration notes, design alternatives, research leads. Create only when notes are too long for this task's PLAN.md.

package/templates/common/docs/tasks/_template/PLAN.md

@@ -0,0 +1,40 @@
+# {{TASK_ID}} — PLAN
+
+Task-level implementation plan and evidence. Main agent writes after second planning; implementer reads before coding.
+
+## Goal
+
+## Acceptance Criteria
+
+- [ ]
+
+## Scope
+
+Allowed write set:
+- 
+
+Forbidden:
+- 
+
+## Loaded Context
+
+- 
+
+## Subagent Dispatch
+
+| Agent | Mode | Read Set | Write Set | Status |
+|-------|------|----------|-----------|--------|
+
+## Subagent Synthesis
+
+Agents used:
+Findings accepted:
+Findings rejected:
+Conflicts:
+Decisions:
+Residual risk:
+
+## Verification
+
+| Check | Result | Notes |
+|-------|--------|-------|

package/templates/common/docs/tasks/_template/PROGRESS.md

@@ -0,0 +1,29 @@
+# {{TASK_ID}} — PROGRESS
+
+Task-level progress and heartbeat. Main agent updates; subagents read only.
+
+## Current Goal
+
+## Phase
+
+Current: Intake
+
+## Heartbeat
+
+Last beat:
+Current phase: Intake
+Current blocker: none
+Next beat trigger:
+Failure count: 0
+Recovery action: none
+
+## Tasks
+
+| # | Task | Owner | Verify | Status |
+|---|------|-------|--------|--------|
+| 1 | Define goal and scope | main agent | recorded above | Pending |
+
+## Agent Handoffs
+
+| Agent | Role | Context Pack | Result |
+|-------|------|-------------|--------|

package/templates/common/scripts/validate-harness.mjs

@@ -25,6 +25,8 @@ const commonAgents = [
   'debugger',
   'reviewer',
   'verifier',
+  'memory-master',
+  'context-master',
 ];
 
 const commonSkills = [
@@ -34,6 +36,7 @@ const commonSkills = [
   'harness-context',
   'harness-build-loop',
   'wf-mode',
+  'wf-update',
   'subagent-orchestrator',
   'readme-optimizer',
 ];
@@ -57,6 +60,7 @@ const required = [
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
   ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
   'Harness/README.md',
+  'Harness/PROGRESS.md',
   'Harness/PLAN.md',
   'Harness/lifecycle.md',
   'Harness/subagents.md',
@@ -72,10 +76,13 @@ const required = [
   'Harness/research/research-results.md',
   'Harness/research/PRD.md',
   'Harness/domain/ports.md',
+  '.claude/skills/wf-update/SKILL.md',
+  '.claude/commands/update.md',
+  'Harness/.harness-version',
 ];
 
 const projectFacts = [
-  'Harness/PLAN.md',
+  'Harness/PROGRESS.md',
   'Harness/research/PRD.md',
   'Harness/research/research-results.md',
   'Harness/architecture.md',
@@ -93,6 +100,8 @@ const contextPacks = [
   'Reviewer:',
   'Debugger:',
   'Verifier:',
+  'Memory Master:',
+  'Context Master:',
 ];
 
 const durableCommunicationDocs = [
@@ -181,6 +190,37 @@ for (const rel of required) {
   }
 }
 
+// Task capsule template files
+const taskTemplateDir = path.join(root, 'Harness', 'tasks', '_template');
+if (!fs.existsSync(taskTemplateDir)) {
+  errors.push('missing directory: Harness/tasks/_template/');
+} else {
+  for (const f of ['PROGRESS.md', 'PLAN.md']) {
+    if (!fs.existsSync(path.join(taskTemplateDir, f))) {
+      errors.push(`missing task template file: Harness/tasks/_template/${f}`);
+    }
+  }
+}
+
+// Cross-reference: DONE files in task PLAN.md must exist on disk
+const taskDirs = fs.existsSync(path.join(root, 'Harness', 'tasks'))
+  ? fs.readdirSync(path.join(root, 'Harness', 'tasks'), { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== '_template')
+      .map(e => e.name)
+  : [];
+for (const taskDir of taskDirs) {
+  const planPath = `Harness/tasks/${taskDir}/PLAN.md`;
+  const planText = read(planPath);
+  if (!planText) continue;
+  const donePattern = /`([^`]+\.(?:md|mjs|js|ts|json|html|css))`[^\n]*DONE/gi;
+  for (const match of planText.matchAll(donePattern)) {
+    const claimedFile = match[1];
+    if (!fs.existsSync(path.join(root, claimedFile))) {
+      errors.push(`${planPath} claims '${claimedFile}' is DONE but file does not exist`);
+    }
+  }
+}
+
 if (fs.existsSync(path.join(root, 'Harness/research/scaffolds.md'))) {
   errors.push('legacy research file should be renamed: Harness/research/scaffolds.md -> Harness/research/research-results.md');
 }
@@ -218,17 +258,26 @@ requireText('CLAUDE.md', 'Harness/MEMORY.md` is the memory/resource router', 'me
 requireText('CLAUDE.md', 'Harness/README.md#Load By Task', 'Harness task router');
 requireText('CLAUDE.md', 'Harness/SETUP.md` exists, follow it before normal project work', 'setup bootstrap contract');
 requireText('CLAUDE.md', 'subagent-orchestrator` and `Harness/subagents.md', 'subagent orchestrator entry trigger');
+requireText('CLAUDE.md', 'Harness/PROGRESS.md` is the global task index', 'PROGRESS global task index');
+requireText('CLAUDE.md', 'Harness/tasks/', 'task capsule directory reference');
+requireText('CLAUDE.md', 'Subagents are readers and reporters', 'subagent state committer rule');
 for (const heading of ['## 2. Think Before Coding', '## 3. Simplicity First', '## 4. Surgical Changes', '## 5. Goal-Driven Execution']) {
   requireText('CLAUDE.md', heading, `Karpathy-style rule heading: ${heading}`);
 }
 
+// Root PROGRESS.md structure check
+const progress = read('Harness/PROGRESS.md');
+if (progress) {
+  for (const heading of ['## Active Task', '## Task Index', '## Cross-Task Decisions']) {
+    if (!progress.includes(heading)) errors.push(`Harness/PROGRESS.md missing heading: ${heading}`);
+  }
+}
+
+// Legacy PLAN.md deprecation check (it exists as stub, no longer requires active task headings)
 const plan = read('Harness/PLAN.md');
 if (plan) {
-  for (const heading of ['## Current Goal', '## Phase', '## Heartbeat', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Subagent Synthesis', '## Verification']) {
-    if (!plan.includes(heading)) errors.push(`Harness/PLAN.md missing heading: ${heading}`);
-  }
-  for (const marker of ['Next beat trigger', 'Recovery action']) {
-    if (!plan.includes(marker)) errors.push(`Harness/PLAN.md missing heartbeat marker: ${marker}`);
+  if (!plan.includes('DEPRECATED')) {
+    errors.push('Harness/PLAN.md should be a deprecation stub; see Harness/PROGRESS.md');
   }
 }
 
@@ -349,7 +398,7 @@ for (const agent of commonAgents) {
 }
 
 requireText('Harness/extension.md', 'Skills should extend the harness');
-requireText('Harness/agent-workflow.md', 'Harness/PLAN.md');
+requireText('Harness/agent-workflow.md', 'Harness/tasks/<task-id>/PROGRESS.md');
 requireText('Harness/research/README.md', 'research-results.md');
 requireText('Harness/WF.md', 'Ralph-style harness loop', 'WF loop description');
 requireText('Harness/WF.md', 'Heartbeat Protocol', 'heartbeat protocol');
@@ -357,6 +406,7 @@ requireText('Harness/WF.md', 'WF mode requires multi-subagent orchestration by d
 requireText('Harness/WF.md', 'Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents', 'explicit WF/WK subagent minimum');
 requireText('Harness/WF.md', '.claude/agents/', 'WF built-in agent roster path');
 requireText('Harness/WF.md', '7:3 collaboration bias', 'WF collaboration bias');
+requireText('Harness/WF.md', 'Harness/tasks/', 'WF task directory reference');
 requireText('Harness/README.md', '`/wf`, `wf mode`, `workflow mode`, or `wk mode`', 'WF/WK router aliases');
 requireText('Harness/README.md', 'explicit WF/WK loads subagent docs immediately', 'explicit WF/WK router output');
 requireText('.claude/skills/harness-router/SKILL.md', '`/wf`, `wf mode`, `workflow mode`, `wk mode`', 'harness-router WF/WK aliases');
@@ -384,6 +434,8 @@ requireText('Harness/architecture.md', '## 2. Interface Decoupling', 'architectu
 requireText('Harness/architecture.md', '## 3. State Design', 'architecture state design');
 requireText('Harness/architecture.md', 'Avoid speculative abstraction', 'anti-overengineering architecture rule');
 requireText('CLAUDE.md', 'Use explicit interfaces or state models only when they protect a real boundary', 'CLAUDE interface/state simplicity rule');
+requireText('CLAUDE.md', '/wf update', 'wf update startup instruction');
+requireText('Harness/README.md', 'Need harness update', 'update routing row');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);