create-harness-vibe-coding 0.2.1 → 0.3.1

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 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 |
 | --- | --- | --- | --- |
@@ -59,13 +59,14 @@ 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 |
+| 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 |
+| 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 +74,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 +87,12 @@ 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.
+- 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 `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,8 +101,14 @@ 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/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
@@ -114,7 +123,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 +132,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 |
+|------|----------|--------|

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
 
@@ -21,9 +22,11 @@ WF mode requires multi-subagent orchestration by default.
 - Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents from `.claude/agents/` before second planning unless the runtime cannot spawn subagents.
 - Use a 7:3 collaboration bias: prefer multi-agent collaboration for long, uncertain, cross-file, cross-layer, browser/API, migration, or repeated-failure work; reserve solo mode for clearly local, low-risk, one-file tasks outside explicit WF/WK mode.
 - Default initial fan-out: `planner`, `researcher` or `docs-researcher`, and `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when the phase needs them.
-- Record every dispatch or bounded-pass fallback in `Harness/PLAN.md#Parallel Dispatch`.
+- Record every dispatch or bounded-pass fallback in `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`.
 - If subagents are unavailable, emulate the same roles as separate bounded passes and record why the fallback was used.
 
+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
@@ -42,10 +45,10 @@ Intake
 
 ## Intake
 
-1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, and `Harness/PLAN.md`.
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/PROGRESS.md`, and the current task's `PROGRESS.md` and `PLAN.md` under `Harness/tasks/<task-id>/`.
 2. State the goal, non-goals, confidence level, known risks, and write boundaries.
 3. Ask up to three blocking questions only when the next action cannot reach 95% confidence.
-4. Update `Harness/PLAN.md#Heartbeat` before dispatching agents or running long commands.
+4. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before dispatching agents or running long commands.
 5. Load `Harness/subagents.md` before coordinating multiple agents; explicit WF/WK mode always coordinates multiple roles.
 
 ## Exploration
@@ -59,13 +62,14 @@ Use parallel read-only subagents first. Explicit WF/WK mode starts with at least
 | `docs-researcher` | official docs, SDK/API versions, browser/tool limits | none unless returning a docs patch |
 | `architect` | boundaries, ports, data flow, state impact, migration risks | none unless returning a docs patch |
 
-Use local files first. Use web search, Tavily, TinyFish, GitHub, official docs, or user-provided links only when the decision needs current or external evidence. Record tool choice and limitations in `Harness/research/research-results.md` or `Harness/PLAN.md`.
+Use local files first. Use web search, Tavily, TinyFish, GitHub, official docs, or user-provided links only when the decision needs current or external evidence. Record tool choice and limitations in `Harness/research/research-results.md` or `Harness/tasks/<task-id>/PLAN.md`.
 
 ## Subagent Orchestration
 
 Use `Harness/subagents.md` as the orchestration methodology and `Harness/dispatch.md` as the dispatch table protocol.
 
 - The main agent is the controller and owns synthesis, integration, and final verification.
+- Subagents are readers and reporters. Only the main agent writes to task PROGRESS.md and PLAN.md. Subagents return PLAN patch suggestions which the main agent reviews before committing.
 - Parallelize read-only exploration; serialize writers unless write sets are disjoint and isolated.
 - Every subagent gets a dispatch pack with role, goal, read set, write set, forbidden scope, injected docs, evidence, stop condition, and return format.
 - After implementation, run spec review before code-quality or architecture review.
@@ -84,7 +88,7 @@ After exploration, synthesize:
 - verification path
 - rollback or recovery plan
 
-Write the result to `Harness/PLAN.md` before implementation.
+Write the result to `Harness/tasks/<task-id>/PLAN.md` before implementation. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
 
 ## Build And Review
 
@@ -111,20 +115,20 @@ For API changes, run the project API/integration test path or a documented real
 
 If verification fails:
 
-1. Update `Harness/PLAN.md#Heartbeat` with failure count and blocker.
+1. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` with failure count and blocker.
 2. Dispatch `debugger` with the failing command, error output, and smallest relevant files.
 3. Fix the smallest reproduced failure.
 4. Run reviewer again.
 5. Run verifier again.
 6. Repeat until verified or blocked by missing user input/external state.
 
-If the same failure class happens three times, stop blind fixes. Record evidence, likely root causes, attempted paths, and ask the user to choose among clear options.
+If the same failure class happens three times, stop blind fixes. Before asking the user, dispatch `memory-master` to record the failure pattern, attempted paths, and root cause hypothesis to `Harness/memory/agent-lessons-patterns.md`. Then present evidence-backed options to the user.
 
 ## Heartbeat Protocol
 
 Heartbeat is a lightweight recovery protocol, not a background daemon.
 
-Update `Harness/PLAN.md#Heartbeat`:
+Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`:
 
 - before a long command
 - after a long command
@@ -135,6 +139,8 @@ Update `Harness/PLAN.md#Heartbeat`:
 
 The agent may set the next beat interval by event instead of time, such as "after next test run", "after reviewer returns", or "after browser evidence is captured".
 
+When context approaches ~85% of the window, dispatch `context-master` to analyze and append a compression suggestion to `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`. The suggestion is non-blocking; the controller checks it at the next natural pause point.
+
 ## Closeout
 
 Close only when:
@@ -143,4 +149,9 @@ Close only when:
 - reviewer has no unresolved critical/high findings
 - test/API/browser evidence is recorded
 - affected Harness docs are synced
-- `Harness/PLAN.md#Heartbeat` says the task is verified or lists the exact next recovery action
+- `context-master` has analyzed the session and extracted durable knowledge
+- `memory-master` has consolidated extracted knowledge into `Harness/memory/*` and `Harness/MEMORY.md`
+- Current task PROGRESS.md and PLAN.md are archived under `Harness/tasks/<task-id>/` with Phase set to Verified
+- `Harness/PROGRESS.md` task index is updated (Closed column filled, Active Task cleared or set to next task)
+- `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` says the task is verified or lists the exact next recovery action
+- `Harness/PROGRESS.md` task index reflects the closed task

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

@@ -5,16 +5,26 @@ Use when implementing, reviewing, debugging, or coordinating subagents.
 ## ReAct Loop
 
 ```text
-Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/PLAN.md
+Observe -> Load minimal context -> Plan -> Act -> Verify -> Update Harness/tasks/<task-id>/PROGRESS.md
 ```
 
 If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [subagents.md](subagents.md) and [dispatch.md](dispatch.md).
 
 ## Feature Packet
 
-Every PRD scope item (`research/PRD.md` Section 2) must have its own feature doc at `Harness/features/<name>.md` created from `Harness/features/_template.md`. One feature = one doc = one implementation unit. Do not code without a feature doc.
+Every PRD scope item must be covered by a feature doc at `Harness/features/<name>.md`
+created from `Harness/features/_template.md`. Do not code without a feature doc.
 
-Small scope is not an exception — a short feature doc is better than none. If the work is truly too small for a full feature doc (single-file fix, no behavior change), it is not a PRD scope item.
+**Cohesion rule**: if multiple PRD scope items share the same write set, the same
+test/verification path, and the same review boundary, group them into a single
+feature doc. The PRD owns scope decomposition; the feature doc owns the
+implementation unit. The number of feature docs should reflect the number of
+distinguishable implementation units, not the number of PRD checkboxes.
+
+**Minimum bar**: a feature doc is still required when the implementation touches
+more than one file or changes user-visible behavior. Only skip a feature doc
+entirely when the work is a single-file fix with no behavior change — in that
+case, record the change in `Harness/tasks/<task-id>/PLAN.md` instead.
 
 **New vs iterate**: if a PRD scope item has ≥85% overlap with an existing feature doc, open the existing doc, bump `Version`, and add a `## Changelog` entry. Only create a new file when the scope is substantially different. When unsure, ask.
 
@@ -58,16 +68,16 @@ Rules:
 
 ## Parallel Dispatch
 
-Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents. Prefer parallel read-only work first, then serial writes.
+Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents (WF mode overrides this; see [WF.md](WF.md)). 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).
 
 ## Conflict Rule
 
-If PRD, Harness/PLAN.md, architecture, ports, tests, or code disagree:
+If PRD, task PLAN.md, architecture, ports, tests, or code disagree:
 
 1. stop implementation
-2. record the conflict in `Harness/PLAN.md` or the feature doc
+2. record the conflict in `Harness/tasks/<task-id>/PROGRESS.md` or the feature doc
 3. choose the smallest reversible decision
 4. ask the maintainer when user-visible behavior or security is affected
 
@@ -79,4 +89,6 @@ Close only when:
 - verification evidence is recorded
 - architecture, ports, data-flow, or state docs are synced if affected
 - no unresolved critical/high review findings remain
-- `Harness/PLAN.md` states the final status or next iteration
+- any optimistic UI mutation has a declared and verified rollback path
+- any file declared as DONE in PLAN.md or PROGRESS.md exists on disk (chat output is not durable evidence)
+- `Harness/tasks/<task-id>/PROGRESS.md` states the final status or next iteration

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

@@ -60,7 +60,7 @@ State must have one owner, legal transitions, and observable recovery behavior.
 - Identify durable state, runtime cache, derived UI state, external system state, and audit/event history separately.
 - Name the owner of each state slice; do not let UI, application services, and infrastructure all mutate the same state directly.
 - Model long-running workflows with explicit states, guards, and failure transitions in `Harness/state-machines.md`.
-- Store resumable progress and recovery decisions in `Harness/PLAN.md#Heartbeat` or project-owned durable storage, not only in chat.
+- Store resumable progress and recovery decisions in `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` or project-owned durable storage, not only in chat.
 - Keep state minimal: derive values when cheap, persist only what must survive reload, retry, or handoff.
 
 ---