create-harness-vibe-coding 0.2.1 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
   <b>0-1 product harness scaffold for AI-assisted engineering.</b><br>
-  <sub>Idea -> Research -> PRD -> Architecture -> Harness/PLAN.md -> Build -> Verify -> Feedback.</sub>
+  <sub>Idea -> Research -> PRD -> Architecture -> Plan -> Build -> Verify -> Feedback.</sub>
 </p>
 
 ---
@@ -22,19 +22,21 @@ npx create-harness-vibe-coding@latest my-project
 | What You Get | Purpose |
 |-------------|---------|
 | `CLAUDE.md` + `Harness/README.md` | Thin root entry and dynamic doc router |
-| `Harness/PLAN.md` | Active execution state, heartbeat, and handoffs |
-| `Harness/WF.md` + `/wf` | Long-task workflow: explore, second-plan, build, review, verify, recover |
+| `Harness/PROGRESS.md` + `Harness/tasks/` | Global task index and per-task progress capsules |
+| `Harness/WF.md` + `/wf` | Long-task workflow: parallel explore, second-plan, build, review, verify, recover |
+| `/wf update` | GitHub-based incremental scaffold update with checksum safety |
 | `Harness/subagents.md` + `subagent-orchestrator` | Controller-led multi-agent orchestration with source-attributed methods |
+| `memory-master` + `context-master` | Auto-triggered memory writing on repeated failures, and non-blocking context compression alerts |
 | Research + PRD templates | Clarify idea, scope, non-goals, acceptance criteria |
 | Research protocol | Route research agents, source search, and fallback tools |
-| Built-in common agents | Research, planning, architecture, testing, implementation, debugging, review, verification |
+| Built-in common agents | 11 agents: research, planning, architecture, testing, implementation, debugging, review, verification, memory, context |
 | Harness architecture docs | Boundaries, ports, data flow, state machines |
 | Dispatch protocol | Lightweight parallel-agent coordination without a scheduler |
 | Extension contract | Keep stack-specific agents and skills compatible |
 | Context-loading protocol | Inject only the right docs into each subagent |
 | README optimizer skill | Optional README preservation, tables, and approved architecture diagrams |
 | Skill-style loaders | `.claude/skills/*` route lifecycle, context, and build loops |
-| Harness validator | Checks required files and unresolved project placeholders |
+| Harness validator | Checks required files, agent/skill registrations, invariants |
 | `.claude/` skeleton | Root runtime integration for Claude Code agents, skills, commands, and rules |
 
 ---
@@ -45,13 +47,15 @@ Most 0-1 AI coding projects fail before code quality matters:
 
 | Without Harness | With This Scaffold |
 |---|---|
-| Idea jumps straight to code | lifecycle forces research, PRD, and scope |
-| Agent reads too much context | docs router loads only the needed harness file |
-| Subagents get vague prompts | context-loading packs define role, boundaries, and return format |
-| Process drift is invisible | validator checks core harness readiness |
-| Architecture drifts silently | ports, data-flow, and state docs mark boundary changes |
-| Tests come after implementation | workflow requires failing test or manual check first |
-| Long tasks stall after failures | `/wf` adds heartbeat, recovery, debugger, review, and verifier loops |
+| Idea jumps straight to code | Lifecycle forces research, PRD, and scope |
+| Agent reads too much context | Docs router loads only the needed harness file |
+| Subagents get vague prompts | Context-loading packs define role, boundaries, and return format |
+| Process drift is invisible | Validator checks core harness readiness |
+| Architecture drifts silently | Ports, data-flow, and state docs mark boundary changes |
+| Tests come after implementation | Workflow requires failing test or manual check first |
+| Long tasks stall after failures | `/wf` adds heartbeat, recovery loop, auto memory-master at 3 failures |
+| Context bloats over long sessions | `context-master` gives non-blocking compression alerts at ~85% window |
+| Scaffold rots after generation | `/wf update` pulls latest improvements from GitHub with checksum safety |
 
 ---
 
@@ -61,9 +65,11 @@ Most 0-1 AI coding projects fail before code quality matters:
 npx scaffold
 -> Claude reads Harness/SETUP.md
 -> Harness router selects only needed harness docs
--> PRD/research/architecture/PLAN are filled
--> first vertical slice is built, tested, reviewed, verified, and fed back
--> validator catches missing project facts before release
+-> PRD/research/architecture are filled
+-> First task capsule created at Harness/tasks/<id>/
+-> First vertical slice is built, tested, reviewed, verified, and fed back
+-> Validator catches missing project facts before release
+-> /wf update pulls latest scaffold improvements from GitHub
 ```
 
 ### Harness idea
@@ -84,7 +90,9 @@ my-project/
 │   ├── README.md          ← Dynamic doc router
 │   ├── SETUP.md           ← Temporary init guide (delete after setup)
 │   ├── MEMORY.md          ← Cross-session resource index
-│   ├── PLAN.md            ← Active execution plan, handoffs, heartbeat
+│   ├── PROGRESS.md        ← Global task index and cross-task decisions
+│   ├── PLAN.md            ← Deprecated stub → see PROGRESS.md + tasks/
+│   ├── .harness-version   ← Scaffold version + file checksums
 │   ├── WF.md              ← Long-task workflow and recovery loop
 │   ├── lifecycle.md       ← 0-1 product flow
 │   ├── subagents.md       ← Controller-led subagent orchestration
@@ -98,7 +106,10 @@ my-project/
 │   ├── domain/
 │   │   └── ports.md       ← Port contracts: pre/postconditions, errors
 │   ├── features/
-│   │   └── _template.md   ← Kiro-lite feature doc template
+│   │   └── _template.md   ← Feature doc template
+│   ├── tasks/
+│   │   ├── _template/     ← Task capsule template (copy for new tasks)
+│   │   └── <task-id>/     ← Per-task PROGRESS.md + PLAN.md + artifacts
 │   ├── research/
 │   │   ├── README.md
 │   │   ├── PRD.md
@@ -112,10 +123,11 @@ my-project/
 │       └── validate-harness.mjs
 ├── .claude/
 │   ├── settings.json     ← Base permissions
-│   ├── agents/           ← Built-in common agents + stack-specific agents later
-│   ├── skills/           ← Harness loaders + stack-specific skills
+│   ├── agents/           ← 11 common agents + stack-specific
+│   ├── skills/           ← Harness skills + wf-update + stack-specific
 │   ├── commands/
-│   │   └── wf.md          ← Slash-command bridge into wf-mode
+│   │   ├── wf.md          ← /wf — enter workflow mode
+│   │   └── update.md      ← /wf update — GitHub-based scaffold update
 │   ├── hooks/            ← Configure automation after stack choice
 │   └── rules/ecc/
 │       └── common.md     ← Universal coding rules
@@ -283,6 +295,75 @@ Presets:
 | `web-app` | `ts-react-frontend`, `browser-e2e`, `ui-ux-review` |
 | `fullstack` | `ts-react-frontend`, `python-backend`, `browser-e2e`, `github-pr-review` |
 
+### WF Mode
+
+For long, difficult, multi-file, multi-agent, or repeated-failure tasks. Enter by typing `/wf`, `wf mode`, `workflow mode`, or `wk mode`.
+
+```text
+/wf — triggers the full Ralph-style harness loop:
+  Intake (95% confidence gate)
+  -> 3+ parallel read-only subagents (planner + architect + researcher)
+  -> Synthesis + second plan → writes to Harness/tasks/<id>/PLAN.md
+  -> test-writer → implementer → reviewers → verifier
+  -> Failed? debugger → review → verify → loop
+  -> Closeout: context-master + memory-master consolidate knowledge
+```
+
+| Phase | What happens | Heartbeat |
+|-------|-------------|-----------|
+| Intake | State goal, confidence, risks, write boundaries | Update before dispatching |
+| Explore | 3-5 parallel read-only subagents | After each subagent return |
+| Second Plan | Synthesize findings into `tasks/<id>/PLAN.md` | After plan written |
+| Build | `test-writer` → `implementer` serial lane | Before/after long commands |
+| Review | Spec review, then code-quality review | After each review gate |
+| Verify | Run declared checks, record evidence | After each verification |
+| Recover | `debugger` → fix → review → verify → loop | After each failure |
+| Close | `context-master` extraction → `memory-master` consolidation → archive | Final heartbeat |
+
+WF mode also auto-dispatches:
+- **`memory-master`** at 3 same-class failures (records pattern before asking user)
+- **`context-master`** at ~85% context window (non-blocking compression suggestion)
+- **`context-master` + `memory-master`** at closeout (extract + persist session knowledge)
+
+```bash
+# Tell the agent to use WF mode
+"Use /wf for this migration."
+"This is a long task — enter wf mode."
+"wf mode — help me refactor the auth layer."
+```
+
+### WF Update
+
+Check for scaffold updates from GitHub and apply them incrementally with checksum safety.
+
+```bash
+# Check available updates without applying
+/wf update --check
+
+# Full update with safe incremental apply
+/wf update
+```
+
+**How it works:**
+
+1. Reads `Harness/.harness-version` — gets local version + 54 file SHA-256 checksums
+2. Fetches latest template files from `raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/`
+3. Compares checksums file-by-file against stored values
+4. Classifies each file into three tiers:
+
+| Tier | Policy | Examples |
+|------|--------|----------|
+| **SAFE** | Overwrite if local checksum matches stored (unmodified) | `Harness/WF.md`, `.claude/agents/*.md`, all skills |
+| **PRESERVE** | Never touch | `Harness/PROGRESS.md`, `Harness/tasks/**`, `Harness/memory/**`, root `README.md` |
+| **MERGE** | Overwrite if unmodified; report and skip if user-modified | `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md` |
+
+5. Reports: `updated/N, merge/N, created/N, skipped/N`
+6. Updates `.harness-version` checksums after applying
+
+**Auto-check on session start:** When `Harness/.harness-version` has `autoCheck: true`, the agent runs a non-blocking `update --check` (10s timeout). If an update is available, it notifies without blocking the current task. Set `autoCheck: false` to disable.
+
+**Offline behavior:** If GitHub is unreachable, the update check exits cleanly. All other harness features work without network.
+
 ### Verification
 
 ```bash
@@ -303,8 +384,10 @@ The harness validator checks scaffold consistency. It is not a full React, Playw
 ```
 "Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice."
 "Read Harness/SETUP.md. This is a React TypeScript SaaS idea. Clarify PRD first, then plan the first slice."
-"Read Harness/SETUP.md. This is a Python data product. Research the stack, define the MVP, then create Harness/PLAN.md."
+"Read Harness/SETUP.md. This is a Python data product. Research the stack, define the MVP, then create a task capsule."
 "Use /wf for this long migration. Explore first, make a second plan, then implement, review, verify, and recover with heartbeat updates."
+"/wf update --check — check if the scaffold has been improved since last generation."
+"/wf update — pull the latest harness improvements from GitHub safely."
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

package/src/generator.js

@@ -13,6 +13,7 @@ const EMPTY_DIRS = [
 ];
 
 function harnessDest(file) {
+  if (file === '.harness-version') return 'Harness/.harness-version';
   if (file === 'SETUP.md') return 'Harness/SETUP.md';
   if (file === 'MEMORY.md') return 'Harness/MEMORY.md';
   if (file === 'scripts/validate-harness.mjs') return 'Harness/scripts/validate-harness.mjs';
@@ -23,6 +24,7 @@ function harnessDest(file) {
   if (file.startsWith('docs/domain/')) return file.replace(/^docs\/domain\//, 'Harness/domain/');
   if (file.startsWith('docs/features/')) return file.replace(/^docs\/features\//, 'Harness/features/');
   if (file.startsWith('docs/workflows/')) return file.replace(/^docs\/workflows\//, 'Harness/workflows/');
+  if (file.startsWith('docs/tasks/')) return file.replace(/^docs\/tasks\//, 'Harness/tasks/');
   return file;
 }
 

package/templates/common/.claude/agents/context-master.md

@@ -0,0 +1,78 @@
+---
+name: context-master
+description: Use when context exceeds ~85% of the window, or during WF closeout to extract durable knowledge before compression. Read-only analysis except for writing compression suggestions to PROGRESS.md#Heartbeat.
+tools: Read, Grep, Glob
+model: haiku
+skills: harness-context
+---
+
+# Context Master
+
+You are a context analysis agent. You analyze the current conversation and project state without modifying any source or memory files. Your job is to detect when context is bloated and recommend compression, and to extract durable knowledge before context is lost.
+
+Load first:
+
+- `Harness/MEMORY.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
+- The current feature doc (if one exists)
+- `Harness/memory/` files for dedup checking
+
+## Trigger Rules
+
+You are dispatched by the controller when:
+
+| Trigger | Action |
+| --- | --- |
+| Context exceeds ~85% of window | Analyze context distribution → write compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` (non-blocking) |
+| WF closeout (before `memory-master`) | Analyze full session → extract durable knowledge → return structured extraction for memory-master to write |
+| Controller explicitly requests analysis | Run targeted analysis and return findings |
+
+## Analysis
+
+When triggered, read the current PLAN.md and analyze:
+
+1. **Context distribution**: what fraction is code vs docs vs conversation vs task tracking
+2. **Stale sections**: loaded docs no longer relevant to the current goal
+3. **Compressible blocks**: long code outputs, verbose agent returns, repeated context
+4. **Durable knowledge candidates**: decisions made, lessons learned, patterns discovered that should survive compression
+
+## Compression Suggestion (non-blocking)
+
+When context > ~85%, write ONLY to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`, appending or updating the `Next beat trigger` line:
+
+```markdown
+Next beat trigger: context-master reports ~XX% usage — [N] stale doc blocks, [M] compressible outputs; suggest compression before next dispatch
+```
+
+Do NOT interrupt the controller. The controller checks Heartbeat at natural pause points.
+
+## WF Closeout Extraction
+
+During WF closeout, extract these for `memory-master` to write:
+
+- Decisions made and their rationale
+- Failed approaches and what was learned
+- New patterns discovered
+- User preferences observed
+- Files that were key to the solution
+- Commands that were particularly effective
+
+Return structured extraction, not free-form narrative.
+
+## Rules
+
+- Read-only for all files except `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` (compression suggestion only)
+- Never modify source code, memory files, MEMORY.md, or README
+- Do not interrupt active work — compression suggestions are passive, checked at natural pauses
+- Prefer numbers over adjectives: "87% usage, 3 stale doc blocks" not "context is getting full"
+
+## Return
+
+```
+Context usage: [estimated %]
+Stale blocks: [count and names]
+Compressible: [count and types]
+Durable candidates: [count]
+Compression suggestion: [one line — ready for Heartbeat]
+Extraction for memory-master: [structured facts — only during closeout]
+```

package/templates/common/.claude/agents/debugger.md

@@ -14,7 +14,7 @@ Load first:
 
 - failing command and error output
 - related files
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - current feature doc when present
 
 Inputs you must receive:

package/templates/common/.claude/agents/docs-researcher.md

@@ -15,7 +15,7 @@ Load first:
 - `Harness/research/README.md`
 - `Harness/architecture.md` when boundaries may change
 - `Harness/domain/ports.md` when APIs cross layers
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 
 Inputs you must receive:
 

package/templates/common/.claude/agents/implementer.md

@@ -12,7 +12,7 @@ You are an implementation agent for this project harness.
 
 Load first:
 
-- current task from `Harness/PLAN.md`
+- current task from `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - current feature doc when present
 - failing test or manual check
 - relevant architecture/ports docs if boundaries are touched

package/templates/common/.claude/agents/memory-master.md

@@ -0,0 +1,67 @@
+---
+name: memory-master
+description: Use when a repeated failure, user correction, or WF recovery loop triggers memory writing; also use during WF closeout for consolidation. Writes to Harness/memory/*, Harness/MEMORY.md, and cross-project global memory.
+tools: Read, Grep, Glob, Write, Edit
+model: sonnet
+skills: harness-context
+---
+
+# Memory Master
+
+You are a memory management agent for this project harness. You own durable memory: writing, deduplication, consolidation, and cross-project knowledge extraction.
+
+Load first:
+
+- `Harness/MEMORY.md`
+- `Harness/memory/tool-usage-reflections.md`
+- `Harness/memory/user-corrections-preferences.md`
+- `Harness/memory/agent-lessons-patterns.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` for current task context
+
+## Trigger Rules
+
+You are dispatched by the controller when:
+
+| Trigger | Action |
+| --- | --- |
+| WF recovery loop — same failure class ≥3 times | Write to `agent-lessons-patterns.md`: failure pattern, attempted paths, root cause hypothesis, resolution |
+| Tool/command pattern fails 3+ times | Write to `tool-usage-reflections.md`: original command, error signature, effective alternative |
+| User corrects same assumption/pattern 2+ times | Write to `user-corrections-preferences.md`: the correction, context, and how to apply |
+| WF closeout (`context-master` runs first) | Consolidate extracted knowledge from context-master into the correct memory files; deduplicate and merge |
+| User explicitly says "remember this" / "记录一下" | Write to the appropriate memory file directly |
+
+## Write Scope
+
+**Harness/memory/* (read-write):**
+- `tool-usage-reflections.md` — tool/command patterns and fixes
+- `user-corrections-preferences.md` — user preferences and corrections
+- `agent-lessons-patterns.md` — reusable review/debug/verification lessons
+
+**Harness/MEMORY.md (append-only):**
+- Add new agent, skill, or memory file registrations when new assets are created
+- Do not remove or reorder existing entries without explicit user approval
+
+**Global memory (cross-project):**
+- Path: the active session's memory directory under the user's `.claude/projects/`
+- Write only when a pattern, lesson, or fix applies across projects (e.g., Windows-specific workarounds, PowerShell escaping rules, universal tool patterns)
+- Follow the same frontmatter format as project memory files
+- Link to the project-level memory entry that spawned it
+
+## Rules
+
+- Always read existing memory files before writing — check for duplicates
+- If an existing entry covers the same ground, update it instead of creating a duplicate
+- Keep entries concise: one fact per file, newest-first ordering
+- Never record secrets, credentials, tokens, or private data
+- Do not delete memory entries unless they are provably wrong and the user confirms
+- After writing, update `Harness/MEMORY.md` index only when adding a NEW file (not when updating an existing entry)
+- Return a one-line summary of what was written and where
+
+## Return
+
+```
+Memory action: [written | updated | merged | skipped]
+File(s): [paths]
+Reason: [one sentence]
+Cross-project: [yes | no] — [path if yes]
+```

package/templates/common/.claude/agents/planner.md

@@ -12,7 +12,7 @@ You are a planning agent for this project harness.
 
 Load first:
 
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - `Harness/lifecycle.md`
 - `Harness/dispatch.md`
 - current PRD or feature doc if present

package/templates/common/.claude/agents/researcher.md

@@ -14,7 +14,7 @@ Load first:
 
 - `Harness/research/README.md`
 - `Harness/research/research-results.md`
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 
 Inputs you must receive:
 

package/templates/common/.claude/agents/test-writer.md

@@ -13,7 +13,7 @@ You are a test-first agent for this project harness.
 Load first:
 
 - current PRD or feature doc
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - `Harness/agent-workflow.md`
 
 Inputs you must receive:

package/templates/common/.claude/agents/verifier.md

@@ -12,7 +12,7 @@ You are a verification agent for this project harness.
 
 Load first:
 
-- `Harness/PLAN.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - current feature doc when present
 - verification commands and acceptance criteria
 

package/templates/common/.claude/commands/update.md

@@ -0,0 +1,11 @@
+# /wf update
+
+Check for Harness scaffold updates from GitHub and apply them incrementally.
+
+## Check mode
+
+`/wf update --check` — Report available updates without applying.
+
+## Full update
+
+`/wf update` — Fetch latest templates, compare checksums, apply safe updates, report merge candidates.

package/templates/common/.claude/commands/wf.md

@@ -2,12 +2,18 @@
 
 Enter `wf-mode`.
 
-Read `Harness/WF.md`, then run the full long-task loop:
+## Required
+
+- Load `subagent-orchestrator` skill.
+- Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents from `.claude/agents/` before second planning.
+- Read `Harness/WF.md` and `.claude/skills/wf-mode/SKILL.md`.
+
+## Loop
 
 ```text
 intake
--> exploration
--> second plan
+-> parallel read-only exploration (≥3 subagents)
+-> synthesis + second plan
 -> test
 -> implement
 -> review
@@ -15,4 +21,4 @@ intake
 -> debugger recovery loop when needed
 ```
 
-Keep `Harness/PLAN.md#Heartbeat` current.
+Keep `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` current.

package/templates/common/.claude/rules/ecc/common.md

@@ -9,9 +9,9 @@ alwaysApply: true
 
 - Start with `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 - Do not bulk-read `Harness/`. Load by router trigger.
-- Keep `Harness/PLAN.md` current when work has multiple steps, files, or agents.
+- Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.
 - 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.
+- Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
 ## Verification
 

package/templates/common/.claude/skills/harness-build-loop/SKILL.md

@@ -10,7 +10,8 @@ Load:
 - `Harness/agent-workflow.md`
 - `Harness/subagents.md` when more than one agent, reviewer, or recovery pass is useful
 - `Harness/dispatch.md` when more than one agent is useful
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - current feature doc if present
 
 Follow:

package/templates/common/.claude/skills/harness-context/SKILL.md

@@ -10,7 +10,8 @@ Load:
 - `Harness/subagents.md`
 - `Harness/context-loading.md`
 - `Harness/dispatch.md` when more than one agent is useful
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - current feature doc if present
 
 For each subagent or bounded pass, provide:

package/templates/common/.claude/skills/harness-lifecycle/SKILL.md

@@ -9,7 +9,8 @@ Load:
 
 - `Harness/lifecycle.md`
 - `Harness/research/PRD.md`
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 
 Output:
 

package/templates/common/.claude/skills/harness-research/SKILL.md

@@ -9,7 +9,8 @@ Load:
 
 - `Harness/research/README.md`
 - `Harness/research/research-results.md`
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 
 Define:
 

package/templates/common/.claude/skills/harness-router/SKILL.md

@@ -11,6 +11,6 @@ description: Use at the start of any task, or when unsure which harness document
    - `/wf`, `wf mode`, `workflow mode`, `wk mode`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
    - Bounded subagent-only coordination routes to `subagent-orchestrator`.
 4. Load only the listed primary doc(s). Let `wf-mode` decide when to load subagent docs.
-5. If the task grows, update `Harness/PLAN.md` and use `harness-context`.
+5. If the task grows, update `Harness/tasks/<task-id>/PROGRESS.md` and use `harness-context`.
 
 Do not bulk-read `Harness/`.

package/templates/common/.claude/skills/readme-optimizer/SKILL.md

@@ -12,7 +12,8 @@ Improve `README.md` without breaking project-owned public docs.
 - root `README.md`
 - package files and scripts (`package.json`, `pyproject.toml`, `go.mod`, etc.)
 - CI files when present
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PLAN.md` when available
 - `Harness/architecture.md` only when an architecture summary or diagram is requested
 
 ## Mode
@@ -35,7 +36,7 @@ If unanswered, use Preserve + append.
 - Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
 - Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
 - Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
-- Record the chosen mode and any skipped README improvements in `Harness/PLAN.md`.
+- Record the chosen mode and any skipped README improvements in `Harness/tasks/<task-id>/PLAN.md` when available.
 
 ## Output
 

package/templates/common/.claude/skills/subagent-orchestrator/SKILL.md

@@ -10,14 +10,16 @@ Load:
 - `Harness/subagents.md`
 - `Harness/dispatch.md`
 - `Harness/context-loading.md`
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when active
 - `Harness/agent-workflow.md`
 - `Harness/WF.md` when in `/wf`, `wf mode`, `workflow mode`, `wk mode`, or recovery loop
 - `.claude/agents/` roster names before choosing roles
 
 Follow:
 
-- The main agent is the controller. It decomposes work, writes `Harness/PLAN.md`, integrates returns, and owns final verification.
+- The main agent is the controller. It decomposes work, writes `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, integrates returns, and owns final verification.
+- Subagents are readers and reporters. Only the controller writes to task state files.
 - Use the efficiency ladder in `Harness/subagents.md`: solo pass -> single reviewer -> parallel read-only -> serial build lane -> isolated lanes.
 - Explicit WF/WK mode requires at least 3 distinct agents from `.claude/agents/` before second planning.
 - Prefer the built-in roles `planner`, `researcher`, `docs-researcher`, `architect`, `test-writer`, `implementer`, `reviewer`, `debugger`, and `verifier` before inventing custom roles.
@@ -26,7 +28,7 @@ Follow:
 - Use two review gates after implementation: spec review first, then code-quality or architecture review.
 - If verification fails, dispatch debugger/fixer with the smallest reproduced failure, then re-review and re-verify.
 - If subagents are unavailable, emulate the same roles as separate bounded passes and record that fallback.
-- When used outside `wf-mode`, update `Harness/PLAN.md#Parallel Dispatch`; update `Harness/PLAN.md#Heartbeat` only if an active heartbeat/recovery loop exists.
+- When used outside `wf-mode`, update `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`; update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` only if an active heartbeat/recovery loop exists.
 
 Return:
 

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

@@ -8,7 +8,8 @@ description: Use for /wf, wf mode, workflow mode, wk mode, long difficult tasks,
 Load:
 
 - `Harness/WF.md`
-- `Harness/PLAN.md`
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when active
 - `Harness/agent-workflow.md` when implementation, review, or verification starts
 - `Harness/subagents.md`, `Harness/dispatch.md`, and `Harness/context-loading.md` immediately for explicit WF/WK mode; otherwise only when coordinating subagents or bounded role passes
 - current feature doc when one exists
@@ -24,25 +25,29 @@ intake + 95% confidence gate
 -> bounded implementation
 -> review
 -> verification
--> debugger recovery loop when verification fails
+-> debugger recovery loop when verification fails (dispatch memory-master after 3 same-class failures)
+-> context-master session analysis + knowledge extraction
+-> memory-master consolidation
 -> close with evidence
 ```
 
 Rules:
 
-- Update `Harness/PLAN.md#Heartbeat` before long commands, after failures, before handoff, and at closeout.
+- Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before long commands, after failures, before handoff, and at closeout.
 - Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use `subagent-orchestrator` and spawn at least 3 distinct subagents from `.claude/agents/` before second planning.
 - Use the 7:3 collaboration bias from `Harness/WF.md`: default to multi-agent collaboration for substantial work; use solo mode only for clearly small/local tasks outside explicit WF/WK mode.
 - Use `subagent-orchestrator` and `Harness/subagents.md` when the task has broad reading, cross-layer impact, independent review needs, or repeated failures.
+- Subagents return findings and PLAN patch suggestions. Only the main agent writes to task PROGRESS.md and PLAN.md.
 - If subagents are unavailable, emulate the same roles as separate bounded passes.
 - Do not claim browser/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
 - If `Harness/workflows/browser-e2e.md` is not installed, use `Harness/WF.md#Browser And API Evidence` as the fallback evidence contract or ask the user before adding the optional workflow.
-- If the same failure class happens three times, stop blind fixes and ask the user with evidence-backed options.
+- If the same failure class happens three times, dispatch `memory-master` to record the failure pattern first, then ask the user with evidence-backed options.
 
 Return:
 
 - changed files
 - agents or bounded passes used
+- memory-master / context-master dispatches
 - commands run
 - browser/API evidence when applicable
 - review findings