create-harness-vibe-coding 0.2.1 → 0.3.0

package/templates/common/.claude/skills/wf-update/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: wf-update
+description: Use when the user says /wf update, wf update, update harness, or check for updates. Fetches latest template files from GitHub, compares against stored checksums, and applies incremental updates safely.
+---
+
+# WF Update
+
+GitHub-based incremental harness update. Pulls latest template files and compares against stored checksums in `Harness/.harness-version`.
+
+## Load
+
+- `Harness/.harness-version`
+- `Harness/README.md#Update Mechanism` row (when available)
+
+## How It Works
+
+1. Read `Harness/.harness-version` -- get current `generator` version and stored `checksums`.
+2. Fetch the latest template file list from GitHub:
+   - Base URL: `https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/`
+   - Fetch `.harness-version` from the repo first to get the latest version and expected file list.
+   - If the repo version equals the local version, report "Already up to date."
+3. For each file in the repo's checksums map:
+   - Compute SHA-256 of the fetched file content (normalize line endings to LF).
+   - Compare against the local stored checksum in `Harness/.harness-version`.
+4. Classify each difference:
+   - **SAFE** (TIER 1): Harness runtime files. If local checksum matches stored -> file is unmodified -> safe to overwrite with fetched version.
+   - **PRESERVE** (TIER 2): User data files. Never overwrite. (`Harness/PROGRESS.md`, `Harness/tasks/**`, `Harness/memory/**`, `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md`, `Harness/domain/ports.md`, `Harness/features/**`, root `README.md`, `.gitignore`)
+   - **MERGE** (TIER 3): Dual-purpose files. If local checksum matches stored -> safe to overwrite. If mismatch -> user modified -> report as merge candidate, never auto-overwrite. (`CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`)
+5. For files in the GitHub repo NOT in local checksums: classify as NEW, plan to create.
+6. Report update plan: `updated/N, merge/N, created/N, skipped/N`
+7. If `--check` flag: report only, do not write.
+8. Apply updates:
+   - SAFE files: overwrite with fetched content.
+   - NEW files: create.
+   - MERGE files with matching checksums: overwrite.
+   - MERGE files with mismatched checksums: skip, warn user.
+   - PRESERVE files: never touched.
+9. Update `Harness/.harness-version`:
+   - Update `generator` to latest version.
+   - Update `generated` timestamp.
+   - Recompute and store checksums for all updated files.
+10. Record update in `Harness/tasks/harness-update/PROGRESS.md` (create task capsule if needed).
+
+## Rules
+
+- Never overwrite PRESERVE files.
+- Never auto-overwrite MERGE files with mismatched checksums.
+- If offline (cannot reach GitHub), report and exit cleanly.
+- After update, suggest running `node Harness/scripts/validate-harness.mjs`.
+- Subagents are readers and reporters. Only the main agent writes updated files.
+
+## Return
+
+- Update plan summary
+- Files updated
+- Files skipped (with reasons)
+- New version
+- Validation suggestion

package/templates/common/.harness-version

@@ -0,0 +1,8 @@
+{
+  "generator": "{{generatorVersion}}",
+  "generated": "{{generatedTimestamp}}",
+  "options": [],
+  "autoCheck": true,
+  "source": "https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/",
+  "checksums": {}
+}

package/templates/common/CLAUDE.md

@@ -6,12 +6,17 @@ Root entry for Claude Code. Keep this file short.
 
 - If `Harness/` exists, this repository is governed by the Harness contract. Treat these files as mandatory operating instructions, not optional references.
 - Every session: load `Harness/MEMORY.md` first, then `Harness/README.md`.
-- If `Harness/SETUP.md` exists, follow it before normal project work; it is the install/bootstrap contract and may be deleted only after setup is complete.
+- If `Harness/SETUP.md` exists, follow it before normal project work; it is the install/bootstrap contract and may be deleted after setup is complete.
 - `Harness/MEMORY.md` is the memory/resource router: agents, skills, durable memories, and cross-session lessons. Follow its registrations when selecting agents/skills or recording memory.
 - `Harness/README.md` is the task router. For every request, check `Harness/README.md#Load By Task`; if a row matches, read and follow those docs before acting.
-- If work spans more than one step, update `Harness/PLAN.md`.
+- `Harness/PROGRESS.md` is the global task index. Load at session start to see active task and task history.
+- If work spans more than one step, create a task capsule from `Harness/tasks/_template/` and update `Harness/tasks/<task-id>/PROGRESS.md`.
 - Use `/wf`, `wf-mode`, `wf mode`, `workflow mode`, `wk mode`, or `Harness/WF.md` for long, difficult, uncertain, multi-file, or repeated-failure work.
 - Use `subagent-orchestrator` and `Harness/subagents.md` when coordinating multiple subagents.
+- Use `/wf update` to check for and apply scaffold updates from GitHub. See `.claude/skills/wf-update/SKILL.md`.
+- Subagents are readers and reporters. Only the main agent writes to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`.
+- For memory writing and consolidation (repeated failures, user corrections, closeout), dispatch `memory-master`.
+- For context analysis and compression alerts (~85% window), dispatch `context-master`.
 - Universal rules live in `.claude/rules/ecc/common.md`.
 - Never bulk-read `Harness/`; route through `Harness/README.md` and `Harness/MEMORY.md`.
 
@@ -20,7 +25,7 @@ Root entry for Claude Code. Keep this file short.
 - You must have **>=95% confidence** in user intent before writing implementation code.
 - If confidence is below 95%, stop and ask up to 3 blocking questions.
 - If multiple valid approaches exist and the choice affects architecture, scope, stack, or user-facing behavior, present trade-offs instead of picking silently.
-- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/PLAN.md`.
+- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
 - If something is unclear, stop. Name what is unclear and ask instead of guessing.
 
 ## 3. Simplicity First
@@ -44,7 +49,8 @@ Root entry for Claude Code. Keep this file short.
 
 - Define verifiable success criteria before implementation.
 - For bugs, reproduce the failure or document why reproduction is impossible before fixing.
-- For multi-step work, keep `Harness/PLAN.md` current with loaded context, task state, assumptions, and verification.
+- For multi-step work, keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current. The main agent is the only state committer; subagents return suggestions only.
+- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/tasks/<task-id>/PLAN.md`.
 - Every task needs a test, build check, validator run, or recorded manual check.
 - Do not claim web/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
 - Do not place project build scripts, git conventions, run commands, or release process in this file. Put them in `README.md`.
@@ -57,4 +63,7 @@ Root entry for Claude Code. Keep this file short.
 - **Tool reflection trigger**: record a lightweight reflection when the same tool/use pattern fails 3+ times, or when a better command pattern/environment fix is found. Write it newest-first in `Harness/memory/tool-usage-reflections.md`.
 - **User correction trigger**: record a lightweight preference/correction when the user asks to remember it, or when the user corrects the same assumption/pattern 2+ times. Write it newest-first in `Harness/memory/user-corrections-preferences.md`.
 - **Agent lesson trigger**: record reusable lessons from review/debug loops in `Harness/memory/agent-lessons-patterns.md` when they would prevent recurrence.
+- **WF auto-trigger**: when the same failure class happens 3+ times in a WF recovery loop, dispatch `memory-master` to record the failure pattern to `Harness/memory/agent-lessons-patterns.md` before asking the user.
+- **Context threshold trigger**: when context approaches ~85% of the window, dispatch `context-master` to analyze and write a non-blocking compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
+- **Closeout trigger**: during WF closeout, dispatch `context-master` to extract durable knowledge, then `memory-master` to consolidate into `Harness/memory/*`.
 - Never record secrets, credentials, tokens, or private data.

package/templates/common/MEMORY.md

@@ -14,6 +14,8 @@
 - [debugger](../.claude/agents/debugger.md) — smallest fix for a reproduced failure.
 - [reviewer](../.claude/agents/reviewer.md) — read-only diff review and closeout risk.
 - [verifier](../.claude/agents/verifier.md) — verification commands and evidence.
+- [memory-master](../.claude/agents/memory-master.md) — memory writing, dedup, consolidation, and cross-project knowledge extraction.
+- [context-master](../.claude/agents/context-master.md) — context analysis, compression alerts, and session knowledge extraction for memory-master.
 
 Stack-specific agents can be added after the product shape is known.
 
@@ -27,6 +29,7 @@ Stack-specific agents can be added after the product shape is known.
 - [wf-mode](../.claude/skills/wf-mode/SKILL.md) — long-task workflow: exploration, second plan, implementation, review, verification, heartbeat, and recovery loop.
 - [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) — controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
 - [readme-optimizer](../.claude/skills/readme-optimizer/SKILL.md) — README preservation, append-only development sections, structured tables, and approved architecture diagrams.
+- [wf-update](../.claude/skills/wf-update/SKILL.md) — GitHub-based incremental harness update, checksum comparison, and safe in-place updates.
 
 Stack-specific skills can be added after the product shape is known.
 
@@ -39,7 +42,8 @@ Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 
 ## Harness (Runtime)
 
-- [Active plan](PLAN.md)
+- [Global progress](PROGRESS.md)
+- [Task directory](tasks/)
 - [Docs router](README.md)
 - [WF mode](WF.md)
 - [0-1 lifecycle](lifecycle.md)
@@ -51,6 +55,7 @@ Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 - [Architecture docs](architecture.md)
 - [Agent workflow](agent-workflow.md)
 - [Harness validator](scripts/validate-harness.mjs)
+- [Version file](.harness-version)
 
 ## Memory Folder
 

package/templates/common/README.md

@@ -20,7 +20,7 @@ Record the real project commands after bootstrap:
 # e.g. npm run build
 ```
 
-Replace the examples with the real commands discovered from this project. If a command is unknown, record the open question in `Harness/PLAN.md`.
+Replace the examples with the real commands discovered from this project. If a command is unknown, record the open question in `Harness/tasks/<task-id>/PROGRESS.md`.
 
 ## Git And Release Notes
 
@@ -36,6 +36,6 @@ The agentic engineering harness lives in `Harness/`.
 - Follow `Harness/SETUP.md` before normal work while it exists.
 - Start at `Harness/README.md`.
 - Load memory and resource registrations from `Harness/MEMORY.md`.
-- Track active work in `Harness/PLAN.md`.
+- Track active work in `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md`.
 - Use `Harness/WF.md` or `/wf` for long, difficult, multi-agent work.
 - Use `Harness/subagents.md` when coordinating multiple agents.

package/templates/common/SETUP.md

@@ -9,7 +9,7 @@ This scaffold is a 0-1 product harness:
 - short agent entry files
 - dynamic docs router
 - PRD, research protocol, architecture, ports, data-flow, state templates
-- active `Harness/PLAN.md`
+- active `Harness/PROGRESS.md`
 - `Harness/MEMORY.md` plus a `Harness/memory/` folder for durable self-learning, user corrections, and tool reflections
 - built-in common agents
 - subagent orchestration and context-loading protocol
@@ -26,7 +26,7 @@ Start Claude Code, then say:
 ```text
 Read Harness/SETUP.md. Bootstrap this project as a 0-1 product harness.
 Use Harness/README.md as the router. Keep context small.
-First clarify the idea, then create PRD, research, architecture, Harness/PLAN.md, and the first vertical-slice task.
+First clarify the idea, then create PRD, research, architecture, Harness/PROGRESS.md and the first per-task plan, and the first vertical-slice task.
 ```
 
 ## Required Bootstrap Sequence
@@ -34,23 +34,23 @@ First clarify the idea, then create PRD, research, architecture, Harness/PLAN.md
 Claude must follow this order:
 
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, and `Harness/lifecycle.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
-2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `Harness/PLAN.md`.
+2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `Harness/tasks/<task-id>/PLAN.md`.
 3. Fill `Harness/research/PRD.md` with MVP, non-goals, and acceptance criteria.
 4. Read `Harness/research/README.md`, then fill `Harness/research/research-results.md` with adopted/rejected research choices.
 5. Fill minimum architecture: `Harness/architecture.md` and one port in `Harness/domain/ports.md`.
-6. Create the first vertical-slice plan in `Harness/PLAN.md`.
+6. Create a task capsule from `Harness/tasks/_template/` and fill the first vertical-slice plan in `Harness/tasks/<task-id>/PLAN.md`.
 7. Use `Harness/subagents.md`, `Harness/context-loading.md`, and `Harness/dispatch.md` when explicit WF/WK mode or any spawned subagents are involved.
 8. Fill `Harness/data-flow.md` or `Harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
 9. Implement only after a failing test or manual verification step is defined.
 10. Run `node Harness/scripts/validate-harness.mjs --strict`.
-11. Record final verification and next feedback step in `Harness/PLAN.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
+11. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
 
 ## Existing Project Bootstrap Sequence
 
 When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
 
 1. Scan existing project facts first: `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, and current run/build scripts.
-2. Record discovered facts and open questions in `Harness/PLAN.md` before changing harness docs.
+2. Record discovered facts and open questions in `Harness/tasks/<task-id>/PROGRESS.md` before changing harness docs.
 3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md`, and `Harness/domain/ports.md` from observed project facts plus explicit user input.
 4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, settings, hooks, package files, CI, docs routers, or workflow docs unless the user explicitly approves that exact overwrite.
 5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
@@ -123,7 +123,9 @@ The harness validator checks for specific structural invariants. When comparing
 | `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 10 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier) |
 | `Harness/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `7:3 collaboration bias`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
 | `Harness/architecture.md` | `## 2. Interface Decoupling`; `## 3. State Design`; `Avoid speculative abstraction`; layer constraints derived from actual project facts |
-| `Harness/PLAN.md` | `## Current Goal`, `## Phase`, `## Success Criteria`, `## Loaded Context`, `## Tasks`, `## Parallel Dispatch`, `## Subagent Synthesis`, `## Verification` headings |
+| `Harness/PROGRESS.md` | global task index with Active Task and task history; cross-task decisions |
+| `Harness/tasks/<id>/PROGRESS.md` | `## Current Goal`, `## Phase`, `## Heartbeat`, `## Loaded Context` headings |
+| `Harness/tasks/<id>/PLAN.md` | `## Tasks`, `## Parallel Dispatch`, `## Subagent Synthesis`, `## Verification` headings |
 | `Harness/SETUP.md` | Only meaningful for fresh projects. If the project has its own onboarding docs, skip this file entirely (it is temporary). If kept, ensure the "Existing Project Bootstrap Sequence" is present. |
 | `Harness/workflows/browser-e2e.md` (if installed as optional) | `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` requirement |
 | `Harness/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
@@ -133,7 +135,8 @@ The harness validator checks for specific structural invariants. When comparing
 
 - `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` — these are new empty files
 - `.claude/agents/*.md` — all 9 common agents
-- `.claude/skills/harness-*/SKILL.md`, `.claude/skills/wf-mode/SKILL.md`, and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills, WF mode, and subagent orchestration
+- `.claude/skills/harness-*/SKILL.md`, `.claude/skills/wf-mode/SKILL.md`, `.claude/skills/wf-update/SKILL.md`, and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills, WF mode, and subagent orchestration
+- `.claude/commands/update.md` — /wf update command bridge
 - `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
 - `.claude/settings.json` — harness settings
 - `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md`, `Harness/data-flow.md`, `Harness/state-machines.md` — harness runtime docs
@@ -151,7 +154,7 @@ npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
 
 ### Template Fill Guide
 
-Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeholder expects. Replace all markers in the doc before moving to the next doc. If a section does not apply yet, leave the `{{...}}` but record why in `Harness/PLAN.md`.
+Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeholder expects. Replace all markers in the doc before moving to the next doc. If a section does not apply yet, leave the `{{...}}` but record why in `Harness/tasks/<task-id>/PLAN.md`.
 
 **`Harness/research/PRD.md`** — Product scope. Fill with product facts from user input, not guesses:
 - `{{WHY_THIS_PROJECT_EXISTS}}`: one-sentence motivation
@@ -181,9 +184,16 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - For each port: fill Purpose, Preconditions, Postconditions, Error Semantics, Idempotency.
 - Leave remaining rows as `{{...}}` until more slices add ports.
 
-**`Harness/PLAN.md`** — Active execution state. Update continuously:
+**`Harness/PROGRESS.md`** — Global task index. Update at session start and task closeout:
+- `## Active Task`: current active task ID.
+- `## Task History`: closed tasks with date, result, and archive path.
+
+**`Harness/tasks/<id>/PROGRESS.md`** — Per-task progress state. Update continuously:
 - `## Current Goal`: one sentence, what this iteration achieves.
 - `## Phase`: current lifecycle phase (Idea/Research/PRD/Architecture/Plan/Build/Verify/Feedback).
+- `## Heartbeat`: last beat time, mode, blocker, recovery action.
+
+**`Harness/tasks/<id>/PLAN.md`** — Per-task implementation plan and evidence. Update continuously:
 - `## Success Criteria`: verifiable outcomes for this iteration.
 - `## Tasks`: numbered tasks with owner, write set, and verify command.
 - `## Parallel Dispatch`: only when spawning subagents — fill agent roles, read/write boundaries.
@@ -198,11 +208,11 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - `{{EVENT_1}}`: the first event type with producer, consumers, payload fields, delivery semantics.
 - Happy Path: fill the Mermaid sequence diagram with actual ports and actions.
 - Failure Paths: for each failure point, document trigger, system behavior, event, caller perception, recovery.
-- If the first slice is synchronous and stateless, leave this doc as `{{...}}` and note in PLAN.md.
+- If the first slice is synchronous and stateless, leave this doc as `{{...}}` and note in `Harness/tasks/<task-id>/PLAN.md`.
 
 **`Harness/state-machines.md`** — State transitions (only when first slice has stateful entities):
 - Define states, transitions, guards, and illegal transitions for the first stateful entity.
-- If no stateful entity exists in the first slice, leave as `{{...}}` and note in PLAN.md.
+- If no stateful entity exists in the first slice, leave as `{{...}}` and note in `Harness/tasks/<task-id>/PLAN.md`.
 
 **General rules for all templates**:
 - Replace `{{projectName}}` with the actual project name immediately.
@@ -234,7 +244,7 @@ After research, fill these docs in order:
 3. `Harness/domain/ports.md` — Define ONE driving port and ONE driven port from the first vertical slice. More ports come with more slices.
 4. `Harness/data-flow.md` — Fill the happy path for the first slice only. Add failure paths when they differ from the happy path.
 
-**Constraint**: If the research does not give you enough confidence to fill a section, leave the `{{...}}` placeholder and record the open question in `Harness/PLAN.md`. The strict validator will catch it.
+**Constraint**: If the research does not give you enough confidence to fill a section, leave the `{{...}}` placeholder and record the open question in `Harness/tasks/<task-id>/PLAN.md`. The strict validator will catch it.
 
 ## User Confirmation Protocol (Non-Negotiable)
 
@@ -245,7 +255,7 @@ When user intent is unclear or ambiguous:
 - **Maximum 3 blocking questions per decision point.** Ask the highest-impact questions first.
 - **Do not act on assumptions that affect architecture, scope, stack, or user-facing behavior.**
 - **You must have ≥95% confidence before writing implementation code.** If below that threshold, stop and ask.
-- **Record every assumption explicitly** in `Harness/PLAN.md` so the user can correct it later.
+- **Record every assumption explicitly** in `Harness/tasks/<task-id>/PLAN.md` so the user can correct it later.
 - **Silent picks are forbidden.** If two valid approaches exist and you cannot decide with high confidence, present both to the user with trade-offs.
 
 False confidence is worse than a question. If you catch yourself thinking "this is probably what they want," stop and ask.

package/templates/common/docs/README.md

@@ -2,7 +2,7 @@
 
 Purpose: route humans and agents to the smallest useful context. `Harness/README.md` is the primary router.
 
-Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PLAN.md` when work is active. Do not read the whole `Harness/` tree.
+Default load: `CLAUDE.md`, `Harness/MEMORY.md`, this file, and `Harness/PROGRESS.md` when work is active. Do not read the whole `Harness/` tree.
 
 ## 0-1 Flow
 
@@ -17,7 +17,7 @@ For the full phase contract, load [lifecycle.md](lifecycle.md).
 - This file is a router, not a full spec.
 - If the task does not clearly match a row below, search by keywords before loading more docs.
 - project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
-- Important assumptions, decisions, blockers, evidence, and handoffs must be written to [PLAN.md](PLAN.md), the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 - Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
 - README rewrites are optional project-doc work. Use `readme-optimizer` and preserve existing public docs unless the user approves a broader restructure.
 - Code architecture belongs in [architecture.md](architecture.md) or the current feature doc, not `CLAUDE.md`.
@@ -29,7 +29,7 @@ For the full phase contract, load [lifecycle.md](lifecycle.md).
 - Subagent orchestration methodology lives in [subagents.md](subagents.md).
 - Extension rules live in [extension.md](extension.md).
 - Context-loading rules live in [context-loading.md](context-loading.md).
-- Progress lives in [PLAN.md](PLAN.md) and the current feature doc.
+- Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
 
 ## Keyword Routing
 
@@ -43,7 +43,7 @@ rg -n "keyword1|keyword2|keyword3" CLAUDE.md README.md Harness
 ```
 
 3. Load only the top matching doc or the smallest matching doc pair.
-4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/PLAN.md`.
+4. If keyword search conflicts with the table below, follow the table and record the assumption in `Harness/tasks/<task-id>/PROGRESS.md`.
 
 Keywords are retrieval hints, not project facts.
 
@@ -51,7 +51,7 @@ Keywords are retrieval hints, not project facts.
 
 Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
 
-Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` may then delegate subagent coordination to `subagent-orchestrator`.
+Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` MUST then delegate subagent coordination to `subagent-orchestrator`.
 
 | When to Read | Keywords | Load | Output |
 | --- | --- | --- | --- |
@@ -59,13 +59,13 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 | Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
 | Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
 | Need architecture or boundaries | architecture, boundary, layer, domain, port, adapter, dependency | [architecture.md](architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
-| Need WF mode | wf, /wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PLAN.md](PLAN.md) | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
-| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PLAN.md](PLAN.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
-| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/readme-optimizer/SKILL.md`, [PLAN.md](PLAN.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
-| Need implementation plan | plan, task, write set, verify, milestone, progress | [PLAN.md](PLAN.md), [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
-| Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [subagents.md](subagents.md), [dispatch.md](dispatch.md), [context-loading.md](context-loading.md), [PLAN.md](PLAN.md) | orchestration plan, dispatch table, agent roles, read/write sets |
+| Need WF mode | wf, /wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
+| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/readme-optimizer/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
+| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
+| Need parallel agents | parallel, dispatch, handoff, write set, dependency, status | [subagents.md](subagents.md), [dispatch.md](dispatch.md), [context-loading.md](context-loading.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | orchestration plan, dispatch table, agent roles, read/write sets |
 | Adding stack-specific agents/skills | extension, agent, skill, rule, hook, stack-specific, compatibility | [extension.md](extension.md), [dispatch.md](dispatch.md) | compatible agents, skills, rules, hooks |
-| Optional workflow installed | workflow, optional, browser-e2e, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md`, [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
+| Optional workflow installed | workflow, optional, browser-e2e, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
 | Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection | [MEMORY.md](MEMORY.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry or no-op rationale |
 | Need subagents | subagent, role pack, context, inject, return format, orchestrator | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md) | controller plan, role-specific context pack, dispatch pack |
 | Need feature work | feature, implementation, TDD, test, review, closeout | [features/_template.md](features/_template.md), [agent-workflow.md](agent-workflow.md) | feature doc, tests, implementation loop |
@@ -73,6 +73,7 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 | Stateful behavior changes | state, transition, guard, illegal transition, state machine | [state-machines.md](state-machines.md) | states, transitions, illegal transitions |
 | Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
 | Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
+| Need harness update | update, /wf update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `Harness/.harness-version` | update plan, safe incremental update, merge candidates |
 
 ## Gates
 
@@ -85,11 +86,11 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 - Unsure whether to open a feature doc? Read `agent-workflow.md` Section 1.
 - Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
 - Do not run writing agents in parallel unless write sets are disjoint.
-- Before coordinating multiple agents, fill `PLAN.md#Parallel Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
-- In WF mode, update `PLAN.md#Heartbeat` before long commands, after failures, and at closeout.
+- Before coordinating multiple agents, fill `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
+- In WF mode, update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, and at closeout.
 - Do not add stack-specific agents or skills without following `extension.md`.
 - Do not close work without tests or recorded manual verification.
-- Do not mark work `Verified` until evidence is recorded in `PLAN.md` or the feature doc.
+- Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
 - Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
 - If a doc still has `{{...}}`, treat that section as a template, not project fact.
 
@@ -98,7 +99,10 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 ```text
 Harness/README.md                  router only
 Harness/MEMORY.md                  resource index
-Harness/PLAN.md                    active execution plan and heartbeat
+Harness/PROGRESS.md                global task index and cross-task decisions
+Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat
+Harness/tasks/<id>/PLAN.md         per-task implementation plan and evidence
+Harness/tasks/_template/           task capsule template (copy to create new task)
 Harness/WF.md                      long-task workflow and recovery loop
 Harness/lifecycle.md               0-1 product flow
 Harness/subagents.md               controller-led subagent orchestration
@@ -114,7 +118,7 @@ Harness/features/_template.md      feature work packet
 Harness/research/README.md         research protocol
 Harness/research/PRD.md            product scope
 Harness/research/research-results.md research results
-Harness/workflows/*.md             optional workflow evidence rules
+Harness/workflows/*.md             optional workflow evidence rules (if installed)
 Harness/memory/tool-usage-reflections.md repeated tool failures and better command patterns
 Harness/memory/user-corrections-preferences.md durable user corrections and preferences
 Harness/memory/agent-lessons-patterns.md reusable review/debug lessons
@@ -123,4 +127,7 @@ Harness/scripts/validate-harness.mjs lightweight harness gate
 .claude/skills/*                   skill-style dynamic loaders
 .claude/skills/readme-optimizer/SKILL.md README preservation and optional structure pass
 .claude/commands/wf.md             slash command bridge into wf-mode
+.claude/skills/wf-update/SKILL.md   GitHub-based harness update
+.claude/commands/update.md           /wf update slash command bridge
+Harness/.harness-version             scaffold version and file checksums
 ```

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 |
+|------|----------|--------|