create-harness-vibe-coding 0.2.1 → 0.3.1

package/README-CN.md

@@ -1,8 +1,14 @@
 # create-harness-vibe-coding 中文说明
 
-0-1 产品 Harness 脚手架，用于 AI 辅助工程：从想法、调研、PRD、架构、计划，到实现、验证和反馈闭环。
+0-1 产品 Harness 脚手架，AI 辅助工程全流程。English: [README.md](README.md)
 
-English README: [README.md](README.md)
+## 一条命令
+
+```bash
+npx create-harness-vibe-coding@latest my-project
+```
+
+---
 
 ## 一句话交给 Agent
 
@@ -12,77 +18,74 @@ English README: [README.md](README.md)
 
 ## 两种安装方式
 
-### 1. npx 安装
-
-适合需要确定性写入、明确冲突策略、可重复 dry-run 的场景。
-
-### 2. 直接把链接丢给 agent
-
-适合老项目、老架构升级、已有复杂 `CLAUDE.md` / `AGENTS.md` / `.claude/` 的场景。agent 应该读取这个仓库 README，理解当前项目结构，执行或模拟 dry-run，然后给出最小迁移方案。
+### npx 安装
+适合确定性写入、明确冲突策略、可重复 dry-run 的场景。
+
+### 直接把链接丢给 Agent
+适合老项目升级。Agent 会读取仓库 README，理解当前项目结构，执行或模拟 dry-run，给出最小迁移方案。如果已有 `CLAUDE.md`，Agent 必须先请求用户确认再合并。
+
+## Harness 工作流
+
+```mermaid
+graph TD
+    A[ /wf 进入工作流 ] --> B[ 探索: 3个并行subagent ]
+    B --> C[ 二阶段计划 ]
+    C --> D[ 构建: test write加implement ]
+    D --> E[ 双门禁审查 ]
+    E --> F{ 通过? }
+    F -->| 否 | G[ debugger 修复 循环 ]
+    G --> E
+    F -->| 是 | H[ 收尾: context加memory ]
+    H --> I[ wf update 增量更新 ]
+```
 
-如果项目里已经有 `CLAUDE.md`，agent 必须先告诉用户：`CLAUDE.md` 是根 agent 入口合同，不能静默覆盖或乱合并。正确流程是先请求用户确认是否重构/合并 `CLAUDE.md`，再在保留原项目规则的基础上补入 Harness 的 startup、memory、router、workflow、subagents 编排约束。
+## 核心文件
 
-Agent-link 安装前置问题，编辑前先问：
+| 文件 | 用途 |
+|------|------|
+| `CLAUDE.md` | Claude Code 根入口，保持短小 |
+| `Harness/README.md` | 文档路由器——按任务关键词加载最少文档 |
+| `Harness/WF.md` | 长任务工作流：摄入 → 探索 → 计划 → 构建 → 审查 → 验证 → 恢复 |
+| `Harness/PROGRESS.md` | 全局任务索引 |
+| `Harness/tasks/<id>/` | 每任务胶囊：PROGRESS.md（进度+心跳）+ PLAN.md（实施+证据） |
+| `.claude/agents/` | 11 个通用 Agent：planner, researcher, architect, implementer, reviewer, debugger, verifier, memory-master, context-master... |
+| `.claude/skills/` | wf-mode, subagent-orchestrator, wf-update, harness-router... |
 
-只询问会影响写入、架构、安全或工作流的选择。开始时最多问 3 个 blocking 问题，其余采用安全默认值并记录到计划里，等真正触发时再继续追问。
+## WF 模式
 
-| 主题 | 什么时候问 | 没回答时的默认值 |
-| --- | --- | --- |
-| 根 agent 入口 | 已存在 `CLAUDE.md`、`AGENTS.md`、`.claude/` 或其他 agent 入口文件 | 保留现有文件；合并 Harness 入口合同前必须询问用户 |
-| Harness 存放位置 | `docs/` 已经用于 GitHub Pages、产品文档或生成文档 | 默认使用根目录 `Harness/`；不要把 Harness 文档写进 `docs/` |
-| README 归属 | 根 `README.md` 是公开产品页、包文档或已有大量自定义内容 | 保留现有 README，只提议追加最小 Development section |
-| README 优化 | 已有 README 过时、太单薄、缺少命令表格，或用户想要架构图/更生动的文档 | 可推荐 `readme-optimizer`；默认只追加 Development notes，结构化优化或重写必须先得到用户确认 |
-| 扩展能力 | ECC、Superpowers、自定义 rules 或栈相关 skills 可能有用 | 先推荐；只有用户同意后才安装 |
-| Skills | 技术栈已明确，测试、前端、后端、review、浏览器证据可用 optional skills 增强 | 用户同意后只安装 1-2 个最相关 skills |
-| CI/CD | 已有 CI 配置，或项目缺少测试/构建 gate | 先记录现有命令；只有用户同意后才新增或规范 CI/CD |
-| 验证深度 | 涉及浏览器可见行为、API、数据库、鉴权、支付或部署 | 必须有真实命令证据；相关场景必须有浏览器/API 证据 |
-| Memory/隐私 | 仓库包含敏感领域数据、客户数据、密钥或私有流程 | 只启用 memory index；禁止记录 secrets 或私有数据 |
-| Branch/worktree | 存在未提交改动、风险迁移或并行实现 lane | 保护当前工作区；大改前先提议 branch/worktree |
-| 包管理器/技术栈 | 存在多个包管理器、monorepo apps 或技术栈边界不清 | 写文件前先确认当前 workspace/app 范围 |
-
-## 一条命令
+输入 `/wf`、`wf mode`、`workflow mode` 或 `wk mode` 进入长任务工作流。默认启动 3 个并行只读 subagent 做探索，然后二阶段计划 → 实现 → 双门禁审查 → 验证。失败时自动进入恢复循环（debugger → review → verify）。收尾时 context-master 提取知识，memory-master 写入记忆。
 
 ```bash
-npx create-harness-vibe-coding@latest my-project
+# 进入 WF 模式
+"用 /wf 处理这个长任务迁移。"
+"wf mode — 帮我重构认证层。"
 ```
 
-## 现有项目渐进安装
+## WF Update
 
-先预览，不写文件：
+从 GitHub 增量更新脚手架，校验和安全。
 
 ```bash
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
+/wf update --check   # 只检查
+/wf update           # 完整更新
 ```
 
-再保留现有文件，只补缺失的 Harness 文件：
+## 已有项目安装
 
 ```bash
+# 先预览
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
+
+# 保留现有文件，只补缺失
 npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
 ```
 
-安装后让 agent 先读 `Harness/SETUP.md`，再开始正常工作。
-
-## 核心约束
-
-- `CLAUDE.md` 只做薄入口和路由，不放项目架构、构建脚本、git 规范。
-- 项目开发命令、构建、测试、git、发布流程放根目录 `README.md`。
-- 架构说明放 `Harness/architecture.md` 或当前 feature 文档。
-- Harness 文档、状态、记忆、工作流默认放根目录 `Harness/`。
-- 如果已有 `AGENTS.md`，agent 必须先询问用户是否同意修改。
-- 长任务、多文件、多 subagents、低置信度或重复失败时使用 `/wf`、`wf-mode` 和 `Harness/WF.md`。
-
-## 常用生成物
-
-| 文件 | 用途 |
-| --- | --- |
-| `CLAUDE.md` | Claude Code 根入口，保持短小 |
-| `Harness/README.md` | Harness 路由器 |
-| `Harness/SETUP.md` | 初次安装和 bootstrap 指南 |
-| `Harness/MEMORY.md` | agents、skills、记忆文件索引 |
-| `Harness/PLAN.md` | 当前计划、heartbeat、handoff、验证证据 |
-| `Harness/WF.md` | 长链路 workflow 和恢复循环 |
-| `Harness/subagents.md` | 多 subagents 编排方法论 |
-| `.claude/skills/*` | Claude Code 可加载的 Harness skills |
+| 冲突模式 | 含义 |
+|----------|------|
+| `fail`（默认） | 目标文件已存在则停止 |
+| `skip` | 保留现有文件，只创建缺失 |
+| `backup` | 备份 → 写入新文件 |
+| `overwrite` | 直接覆盖 |
 
 ## 验证
 
@@ -90,5 +93,3 @@ npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
 npm test
 node Harness/scripts/validate-harness.mjs
 ```
-
-生成项目后，`Harness/scripts/validate-harness.mjs` 用于检查 Harness 结构、注册关系和必要规范是否完整。

package/README.md

@@ -8,33 +8,37 @@
 <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>
 
----
-
 ## One Command
 
 ```bash
 npx create-harness-vibe-coding@latest my-project
 ```
 
+Chinese README: [README-CN.md](README-CN.md)
+
+---
+
 | 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 +49,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 +67,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 +92,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 +108,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 +125,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 +297,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 +386,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.1",
   "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-max.md

@@ -0,0 +1,28 @@
+# /wf max
+
+Enter maximum-parallelism workflow mode. Splits tasks into minimal non-conflicting units and dispatches as many subagents as possible in parallel waves.
+
+## Required
+
+- Load `wf-max` skill.
+- MUST run exploration fan-out with as many read-only subagents as useful.
+- MUST partition implementation into disjoint write sets across parallel waves.
+- MUST run parallel reviewers per dimension after each implementation wave.
+
+## Loop
+
+```text
+intake
+-> max-parallel exploration (5-14 read-only agents)
+-> synthesis + write-set coloring → dependency graph
+-> wave 1: N parallel implementers (disjoint file claims)
+-> wave 1 review: parallel spec/code/security reviewers
+-> wave 2: M parallel implementers (depend on wave 1)
+-> wave 2 review
+-> verifier integration
+-> closeout with context-master + memory-master
+```
+
+Full organization model, span formula, Manager types, leaf condition, and synthesis protocol: [WF-MAX.md](Harness/WF-MAX.md).
+
+Keep `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` current.