create-harness-vibe-coding 0.3.0 → 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

@@ -11,14 +11,16 @@
   <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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.3.0",
+  "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/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.

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

@@ -0,0 +1,95 @@
+---
+name: wf-max
+description: Use for /wf max or maximum parallelism. Three-tier CEO→Manager→Worker hierarchy with recursive depth, per-domain span caps, and leaf-condition stop rules.
+---
+
+# WF Max
+
+CEO → Managers → Workers. Scale to 1000 agents via recursive depth. Full spec: `Harness/WF-MAX.md`.
+
+## Load
+
+- `Harness/WF-MAX.md` — organization model, span formula, wave orchestration
+- `Harness/subagents.md` — agent roster, controller role
+- `Harness/dispatch.md` — File claim, Concurrency group handoff fields
+- `Harness/agent-workflow.md` — cohesion rule (feature doc < Worker granularity)
+
+## Organization
+
+```
+CEO(1) → Managers(span) → Workers(leaf) or Sub-Managers(depth≥3)
+```
+
+- CEO: intent, scope, integration, final verification.
+- Manager: domain partition → parallel dispatch → synthesize → report.
+- Worker: single file (write) or single dimension (read). File claims must be file-level disjoint.
+- depth≥3: Manager spawns Sub-Manager (span≤7). No mixed Worker+Sub-Manager in same wave.
+
+## Span Formula
+
+```
+span = min(ceil(sqrt(files)), domain_cap)
+  Architecture:   3
+  Implementation: 5-7
+  Review:         7-10
+  Research:       10-12
+```
+
+## Total Agents
+
+```
+total(depth, span) = Σ span^L for L=0..depth
+```
+
+No hard cap. Governed by leaf condition + overhead filter.
+
+## Leaf Condition
+
+```
+stop if: files ≤ span×2 | avgLines < 50 | overhead > 0.30
+```
+
+Overhead threshold: `overhead > 0.30 → degrade to /wf`
+
+## Manager Types (4)
+
+| Type | Span | Workers |
+|------|------|---------|
+| Explore-Mgr | 5-10 | researcher₁..ₙ, domain-explorer₁..ₙ |
+| Architect-Mgr | 3 | boundary-researcher, interface-designer, data-flow-mapper |
+| Implement-Mgr | 5-7 | implementer₁..ₙ (1 file_claim/Worker) |
+| Review-Mgr | 3-4 | reviewer-spec, reviewer-code, reviewer-security |
+
+## Manager Synthesis
+
+```
+1. COLLECT → 2. DEDUPLICATE → 3. CONFLICT (flag, no silent resolve) → 4. SYNTHESIZE → 5. REPORT
+```
+Worker failure: retry 1× → absorb or escalate to CEO.
+
+## Wave Orchestration
+
+```
+W0: Explore-Mgr → N parallel → synthesize → CEO
+W1: Architect-Mgr → 3 parallel → boundary contract → CEO approval
+W2: Implement-Mgr → write-set coloring → wave dispatch: N parallel → merge → CEO
+W2R: Review-Mgr → 3-4 parallel → dedupe+severity → CEO assigns fixes
+W3+: Dependent waves (repeat W2)
+CLOSEOUT: CEO → context-master + memory-master (direct)
+```
+
+## When NOT to Use
+
+- files <5 → /wf
+- all changes share single interface → serial
+- overhead > 30% → degrade
+
+## /wf vs /wf max
+
+| | /wf | /wf max |
+|---|-----|------|
+| Organization | flat | CEO→Mgr→Worker (3-tier) |
+| Span formula | none | sqrt(files) + domain cap |
+| Recursive depth | 0 | 1-3 (scales to 1000) |
+| Granularity floor | none | <50 lines no split |
+| Context threshold | ~85% | ~70% |

package/templates/common/CLAUDE.md

@@ -11,7 +11,7 @@ Root entry for Claude Code. Keep this file short.
 - `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.
 - `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 `/wf`, `/wf max`, `wf-mode`, `wf mode`, `workflow mode`, `wk mode`, `Harness/WF.md`, or `Harness/WF-MAX.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`.

package/templates/common/MEMORY.md

@@ -30,6 +30,7 @@ Stack-specific agents can be added after the product shape is known.
 - [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.
+- [wf-max](../.claude/skills/wf-max/SKILL.md) — maximum-parallelism workflow: write-set coloring, wave dispatch, parallel review per dimension.
 
 Stack-specific skills can be added after the product shape is known.
 
@@ -46,6 +47,7 @@ Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 - [Task directory](tasks/)
 - [Docs router](README.md)
 - [WF mode](WF.md)
+- [WF Max mode](WF-MAX.md)
 - [0-1 lifecycle](lifecycle.md)
 - [Research protocol](research/README.md)
 - [Context loading protocol](context-loading.md)

package/templates/common/docs/README.md

@@ -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` MUST then delegate subagent coordination to `subagent-orchestrator`.
+Routing priority: if a request explicitly says `/wf`, `/wf max`, `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 |
 | --- | --- | --- | --- |
@@ -60,6 +60,7 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 | 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), [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 |
+| Need WF Max mode | /wf max, wf max, maximum parallelism, max parallel | [WF-MAX.md](WF-MAX.md), [WF.md](WF.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | max-parallel exploration, write-set coloring, wave dispatch |
 | 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 |
@@ -88,6 +89,7 @@ Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`
 - Do not run writing agents in parallel unless write sets are disjoint.
 - 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.
+- In WF Max mode, never dispatch two implementers with overlapping file claims. Verify disjointness before each wave.
 - 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 the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
@@ -104,6 +106,9 @@ 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/WF-MAX.md                  max-parallelism workflow with wave dispatch
+.claude/skills/wf-max/SKILL.md     max-parallelism skill loader
+.claude/commands/wf-max.md         /wf max slash command bridge
 Harness/lifecycle.md               0-1 product flow
 Harness/subagents.md               controller-led subagent orchestration
 Harness/context-loading.md         dynamic loading and subagent packs

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

@@ -0,0 +1,134 @@
+# WF-MAX — Maximum Parallelism Workflow
+
+## Trigger
+
+- Explicit: `/wf max`
+- Auto: WF task with write-set ≥5 files AND clear disjoint boundaries
+- parallelismScore = (files × avgLines × 3 / 800) × independenceFactor
+  - spawn ≥2.0 | maybe 1.0-2.0 | skip <1.0 (degrade to /wf)
+
+## Companion Docs
+
+- [subagents.md](subagents.md) — agent roster, controller role, efficiency ladder
+- [dispatch.md](dispatch.md) — handoff format, File claim, Concurrency group fields
+- [agent-workflow.md](agent-workflow.md) — build/test/review loop, cohesion rule, completion gate
+
+## Organization Model
+
+```
+CEO(1) ──┬── Manager₁(span) ──┬── Worker₁..ₙ
+         │                     └── Sub-Manager(span) → Worker₁..ₙ  [depth ≥3]
+         └── Manager₂(span) ── Worker₁..ₙ
+```
+
+- CEO: intent, scope, integration, final verification. Direct reports 3-5 Managers.
+- Manager: domain partition → parallel dispatch → synthesize → report. Serial across domains; parallel within domain.
+- Worker: single file per write Worker (implementer, one file_claim). Single dimension/topic per read Worker (reviewer, researcher). File claims must be file-level disjoint. Topic-level splitting within a single file is only allowed for read-only Workers.
+- depth ≥3: Manager spawns Sub-Manager (span ≤7) instead of Worker. Recursive until leaf condition met.
+
+## Span Formula
+
+```
+span = min(ceil(sqrt(files)), domain_cap)
+  Architecture:    cap = 3
+  Implementation:  cap = 5-7
+  Review:          cap = 7-10
+  Research:        cap = 10-12
+```
+
+## Total Agents (recursive, scales to 1000)
+
+```
+total(depth, span) = Σ span^L for L=0..depth
+```
+
+- depth=0: CEO + Workers only (XS)
+- depth=1: CEO + Managers + Workers
+- depth=2: CEO + Managers + Workers
+- depth≥3: CEO + Managers + Sub-Managers + Workers (recursive)
+- no hard agent cap; recursion governed by leaf condition + overhead filter
+
+## Sizing Table
+
+| Scale | Files   | Depth | CEO | Mgrs | Workers | Total |
+|-------|---------|-------|-----|------|---------|-------|
+| XS    | 1-4     | 0     | 1   | 0    | 1-3     | 2-4   |
+| S     | 5-12    | 1     | 1   | 2    | 6       | 9     |
+| M     | 13-30   | 1     | 1   | 3    | 15      | 19    |
+| L     | 31-60   | 2     | 1   | 5    | 35      | 41    |
+| XL    | 61-200  | 2     | 1   | 7    | 49      | 57    |
+| XXL   | 201-500 | 3     | 1   | 7    | 343     | 351   |
+| XXXL  | 501-1000| 3     | 1   | 7    | 686     | 694   |
+
+- depth≥3: Managers spawn Sub-Managers (span≤7). No mixed Worker+Sub-Manager dispatch in same wave.
+
+## Leaf Condition (stop splitting)
+
+- files ≤ span×2
+- OR avgLines < 50
+- OR overhead > 0.30 (degrade to /wf)
+
+## Manager Types (4)
+
+| Type          | Trigger                       | Span | Worker Roles                                                  |
+|---------------|-------------------------------|------|---------------------------------------------------------------|
+| Architect-Mgr | cross-file interfaces, new ports | 3  | boundary-researcher, interface-designer, data-flow-mapper     |
+| Implement-Mgr | write-set defined             | 5-7  | implementer₁..ₙ (1 file_claim each)                           |
+| Review-Mgr    | implementation wave complete  | 3-4  | reviewer-spec, reviewer-code, reviewer-security               |
+| Explore-Mgr   | L+ project, uncertain scope   | 5-10 | researcher₁..ₙ, domain-explorer₁..ₙ                           |
+
+## Manager Synthesis Protocol
+
+```
+1. COLLECT      → await all Worker returns
+2. DEDUPLICATE  → dedupe, merge overlap
+3. CONFLICT     → flag contradictions (file_claim overlap, interface mismatch); no silent resolve
+4. SYNTHESIZE   → single integrated artifact
+5. REPORT       → CEO-actionable synthesis + raw Worker returns (audit)
+```
+
+- Worker failure: retry 1× → on 2nd failure, Manager absorbs or escalates to CEO for replan.
+
+## Wave Orchestration
+
+```
+W0:  Explore-Mgr    → N parallel researchers → synthesize → CEO
+W1:  Architect-Mgr  → 3 parallel → boundary decisions + interface contract → CEO approval
+W2:  Implement-Mgr  → write-set coloring → wave dispatch: N parallel implementers (disjoint file_claims) → merge → CEO
+W2R: Review-Mgr     → 3-4 parallel reviewers → dedupe + severity → CEO assigns fixes
+W3+: Dependent implementation waves (repeat W2 pattern)
+INTEGRATION: CEO → verifier → fail → debugger → loop (cap=3)
+CLOSEOUT:   CEO → context-master + memory-master (direct, no Manager)
+```
+
+- Wave scheduling: Managers serial across domains, Workers parallel within domain.
+- CEO validates wave output before starting next wave. No pipelining.
+
+## Overhead & Cost Filter
+
+```
+overhead(depth) = 0.10 (depth≤2) | 0.20 (depth=3) | 0.35 (depth≥4)
+```
+
+- overhead > 0.30 → degrade to /wf
+- independenceFactor: 1.0 (no deps) | 0.3-0.7 (shared imports)
+
+## When NOT to use /wf max
+
+- files < 5 → use /wf
+- all changes share single interface → serial dependency
+- import/re-export refactor → global consistency required
+- communication overhead > 30% → degrade
+
+## /wf vs /wf max
+
+| Dimension        | /wf              | /wf max                          |
+|------------------|------------------|----------------------------------|
+| Organization     | flat             | CEO → Mgr → Worker (3-tier)      |
+| Exploration      | 3-5 serial       | Mgr → 10 parallel                |
+| Implementation   | 1 serial         | Mgr → N parallel (span 5-7)      |
+| Review           | 1-2 serial gate  | Mgr → 3-4 parallel dimensions    |
+| Span formula     | none             | sqrt(files) + domain cap         |
+| Recursive depth  | 0                | 1-3 (scales to 1000 agents)      |
+| Context threshold| ~85%             | ~70%                             |
+| Granularity floor| none             | <50 lines → no split             |

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

@@ -13,6 +13,7 @@ Enter WF mode when any of these are true:
 - The task needs research, architecture judgment, browser/API validation, or migration planning.
 - Confidence in intent, architecture, or implementation is below 95%.
 - The same command, test, tool, or approach fails twice.
+- The user explicitly says `/wf max` or `wf max` (for maximum-parallelism mode, see [WF-MAX.md](WF-MAX.md)).
 
 ## Multi-Subagent Requirement
 
@@ -24,6 +25,8 @@ WF mode requires multi-subagent orchestration by default.
 - Record every dispatch or bounded-pass fallback in `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`.
 - If subagents are unavailable, emulate the same roles as separate bounded passes and record why the fallback was used.
 
+For maximum-parallelism mode (write-set coloring, wave dispatch, parallel reviewers), use `/wf max` and see [WF-MAX.md](WF-MAX.md).
+
 ## WF Loop
 
 ```text

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

@@ -68,7 +68,7 @@ Rules:
 
 ## Parallel Dispatch
 
-Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). Prefer parallel read-only work first, then serial writes.
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). In `/wf max`, the CEO/Manager/Worker hierarchy in [WF-MAX.md](WF-MAX.md) overrides this limit entirely with wave-based parallel dispatch. Prefer parallel read-only work first, then serial writes.
 
 Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
 

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

@@ -65,6 +65,7 @@ Goal
 - If two write sets overlap, do not run those agents in parallel.
 - If an agent returns uncertainty, mark the row `Blocked` or add a follow-up row.
 - If docs, tests, and code disagree, stop implementation and record the conflict in `Harness/tasks/<task-id>/PROGRESS.md`.
+- In /wf max, file claims must respect WF-MAX.md leaf condition: no split below 50 avgLines, no split when files ≤ span×2.
 
 ## Handoff Format
 
@@ -81,6 +82,9 @@ Evidence:
 Risks:
 Next:
 PLAN patch:
+Concurrency group:  <wave number — 0=exploration, 1,2,3,...=implementation waves. Optional; only used in /wf max.>
+File claim:         <list of exact file paths this agent exclusively owns. Optional; only used in /wf max.>
+Granularity floor:  <50 avgLines → do NOT spawn. Apply leaf condition from WF-MAX.md.>
 ```
 
 Use `Files changed: none` for read-only agents. Use `PLAN patch: none` when no state update is needed.

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

@@ -85,6 +85,7 @@ Choose the cheapest coordination level that is safe.
 | Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
 | Serial build lane | normal feature or fix | test-writer -> implementer -> reviewers -> verifier |
 | Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
+| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
 
 Default for automatic WF triggers: 3-5 active read-only agents before second planning. For explicit WF/WK mode, never use the solo pass unless subagents are unavailable; use bounded role passes as the recorded fallback.
 
@@ -106,6 +107,18 @@ controller intake
 
 Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
 
+```text
+/wf max orchestration shape:
+controller intake
+-> wave 0: max-parallel exploration (4-14 read-only agents)
+-> controller synthesis: dependency graph + write-set coloring
+-> wave 1: N parallel implementers (disjoint file claims)
+-> wave 1 review: parallel spec/code/security reviewers
+-> wave 2+: dependent implementers (if any)
+-> integration verifier
+-> closeout with evidence
+```
+
 ## Dispatch Pack
 
 Every subagent dispatch must be self-contained:

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

@@ -37,6 +37,7 @@ const commonSkills = [
   'harness-build-loop',
   'wf-mode',
   'wf-update',
+  'wf-max',
   'subagent-orchestrator',
   'readme-optimizer',
 ];
@@ -53,9 +54,11 @@ const required = [
   'README.md',
   'Harness/MEMORY.md',
   'Harness/WF.md',
+  'Harness/WF-MAX.md',
   ...memoryFiles,
   '.claude/settings.json',
   '.claude/commands/wf.md',
+  '.claude/commands/wf-max.md',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
   ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
@@ -436,6 +439,14 @@ requireText('Harness/architecture.md', 'Avoid speculative abstraction', 'anti-ov
 requireText('CLAUDE.md', 'Use explicit interfaces or state models only when they protect a real boundary', 'CLAUDE interface/state simplicity rule');
 requireText('CLAUDE.md', '/wf update', 'wf update startup instruction');
 requireText('Harness/README.md', 'Need harness update', 'update routing row');
+requireText('Harness/WF-MAX.md', 'write-set coloring', 'WF-MAX coloring algorithm');
+requireText('Harness/WF-MAX.md', 'wave dispatch', 'WF-MAX wave dispatch');
+requireText('Harness/README.md', '/wf max', 'wf max router alias');
+requireText('Harness/README.md', 'WF-MAX.md', 'WF-MAX router reference');
+requireText('Harness/subagents.md', 'Max parallelism', 'subagents max parallelism row');
+requireText('Harness/dispatch.md', 'Concurrency group', 'dispatch concurrency group field');
+requireText('Harness/dispatch.md', 'File claim', 'dispatch file claim field');
+requireText('CLAUDE.md', '/wf max', 'wf max startup instruction');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);