create-harness-vibe-coding 0.2.0 → 0.3.0

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

@@ -8,9 +8,9 @@ description: Use at the start of any task, or when unsure which harness document
 1. Read `Harness/README.md`.
 2. Identify the current situation from "Load By Task".
 3. Apply routing priority before loading extra files:
-   - `/wf`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
+   - `/wf`, `wf mode`, `workflow mode`, `wk mode`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
    - Bounded subagent-only coordination routes to `subagent-orchestrator`.
 4. Load only the listed primary doc(s). Let `wf-mode` decide when to load subagent docs.
-5. If the task grows, update `Harness/PLAN.md` and use `harness-context`.
+5. If the task grows, update `Harness/tasks/<task-id>/PROGRESS.md` and use `harness-context`.
 
 Do not bulk-read `Harness/`.

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

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

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

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

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

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

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

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

package/templates/common/.harness-version

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

package/templates/common/CLAUDE.md

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

package/templates/common/MEMORY.md

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

package/templates/common/README.md

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

package/templates/common/SETUP.md

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

package/templates/common/docs/README.md

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

package/templates/common/docs/domain/ports.md

@@ -10,6 +10,8 @@
 
 ## 1. Port Classification
 
+Create a port only for a real boundary: external service, storage, SDK, process, browser/API boundary, permission boundary, or cross-layer dependency. Do not create a port only because an interface might be useful someday.
+
 ### 1.1 Driving Ports (Inbound — external calls application)
 
 | Port | Definition Location | Purpose |
@@ -67,6 +69,7 @@ Fill in each port using the format below:
 - {{INVARIANT_1}}
 - {{INVARIANT_2}}
 - New ports must be defined in `domain/ports`; adapters go in `infrastructure/`.
+- Each port needs one clear owner and at least one real caller. Avoid speculative ports without a concrete adapter or testability need.
 
 ---