create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/Harness/settings.json

@@ -0,0 +1,43 @@
+{
+  "schema": "harness-settings@1",
+  "language": {
+    "userFacing": "auto"
+  },
+  "context": {
+    "startupProfile": "thin",
+    "cacheFirst": true,
+    "budgetProfile": "auto"
+  },
+  "workflow": {
+    "defaultTier": "auto",
+    "taskCapsuleCap": 5
+  },
+  "wfMax": {
+    "mode": "useful",
+    "maxWorkersTotal": 15,
+    "maxWorkersPerWave": 7,
+    "maxReviewersPerWave": 4,
+    "maxManagersTotal": 4,
+    "reviewReservePercent": 30,
+    "stopDispatchBelowTokens": 50000
+  },
+  "wfAuto": {
+    "enabled": true,
+    "maxFilesPerCycle": 3,
+    "maxNetLinesPerCycle": 50,
+    "checkpointSchedule": [2, 5, 10]
+  },
+  "wfAutoSpark": {
+    "enabled": true,
+    "minNorthStarAlignmentPercent": 50,
+    "rollingAlignmentFloorPercent": 65,
+    "roadmapReviewEveryCycles": 10
+  },
+  "telemetry": {
+    "l2Cache": {
+      "claimMinWarmTurns": 10,
+      "claimMinReadRatioPercent": 95,
+      "claimMinUpliftPoints": 2
+    }
+  }
+}

package/templates/common/Harness/{ECC-GUIDE.md → specs/guides/ECC-GUIDE.md}

@@ -85,7 +85,7 @@ If rules are missing, the agent MUST install them before proceeding to step 1.
 
 Beyond coding style, ECC provides design-level guidance for both frontend and backend.
 These are NOT in Harness by default — the agent should consult them when filling
-`Harness/architecture.md` and `Harness/research/research-results.md`.
+`Harness/project/architecture.md` and `Harness/research/research-results.md`.
 
 ### Frontend Design (web/ + typescript/)
 
@@ -111,7 +111,7 @@ These are NOT in Harness by default — the agent should consult them when filli
 
 ### Architecture Templates
 
-Write the project-specific structure in `Harness/architecture.md`. Use the ECC rule combinations above to decide which standards apply to each layer.
+Write the project-specific structure in `Harness/project/architecture.md`. Use the ECC rule combinations above to decide which standards apply to each layer.
 
 ### API Contract
 
@@ -119,7 +119,7 @@ See [Contract Rules](#contract-rules) below for the full spec.
 
 ## Agent Skills + ECC Rules
 
-Dispatch packets MUST include `ecc` and SHOULD include `skills` fields (use `skills: none` when no skill applies). `Harness/context-loading.md#ecc-rules-per-role` owns the role-to-ECC mapping. This guide owns stack detection and the catalog of available ECC rule sets.
+Dispatch packets MUST include `ecc` and SHOULD include `skills` fields (use `skills: none` when no skill applies). `Harness/specs/runtime/context-loading.md#ecc-rules-per-role` owns the role-to-ECC mapping. This guide owns stack detection and the catalog of available ECC rule sets.
 
 ## API Contract Specification (Frontend ↔ Backend)
 
@@ -243,4 +243,4 @@ When dispatching a subagent, the dispatch packet MUST include:
 
 Different subagents get different `ecc` and `skills` arrays.
 A frontend implementer loads `web/` rules. A backend implementer loads `python/` or `golang/` rules.
-A reviewer loads `security/` + `testing/` rules. See `Harness/context-loading.md` for the full per-role mapping.
+A reviewer loads `security/` + `testing/` rules. See `Harness/specs/runtime/context-loading.md` for the full per-role mapping.

package/templates/common/Harness/{SETUP.md → specs/guides/SETUP.md}

@@ -1,6 +1,9 @@
 # SETUP.md - Bootstrap This Product Harness
 
-Temporary file. Delete after the first vertical slice is verified.
+Retained install/bootstrap reference. Keep this file available for setup,
+migration, upgrade decisions, and explicit bootstrap requests. Normal sessions
+start from `CLAUDE.md`; `Harness/README.md` is the Harness workflow router when
+a routed task needs it.
 
 ## What This Is
 
@@ -24,7 +27,7 @@ It does not guess your stack or business domain. The agent MUST detect or ask, t
 Start Claude Code or Codex, then say:
 
 ```text
-Read Harness/SETUP.md. Bootstrap this project as a 0-1 product harness.
+Read Harness/specs/guides/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 Mini PRD, acceptance criteria, UI/API contracts, test plan, research, architecture, Harness/PROGRESS.md, the first per-task plan, and the first vertical-slice task.
 ```
@@ -33,18 +36,18 @@ First clarify the idea, then create Mini PRD, acceptance criteria, UI/API contra
 
 Claude or Codex must follow this order during bootstrap. This sequence is broader than installation; if the user only asked to install/configure the harness in an existing project, follow the "Existing Project Fast Path" below and stop after the non-strict validator passes.
 
-0. **ECC Stack Configuration** — Detect the project's tech stack. If the repo is empty or has no stack markers (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `composer.json`, `build.gradle`, etc.), ask the user: "What's your tech stack? (language/framework)" Then install the matching ECC rule sets from `~/.claude/rules/ecc/`. See `Harness/ECC-GUIDE.md` for the stack→rules mapping. Minimum: always install `common/`. Verify with `ls .claude/rules/ecc/`.
-1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/lifecycle.md`, and `Harness/ACCEPTANCE_PROTOCOL.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
+0. **ECC Stack Configuration** — Detect the project's tech stack. If the repo is empty or has no stack markers (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `composer.json`, `build.gradle`, etc.), ask the user: "What's your tech stack? (language/framework)" Then install the matching ECC rule sets from `~/.claude/rules/ecc/`. See `Harness/specs/guides/ECC-GUIDE.md` for the stack→rules mapping. Minimum: always install `common/`. Verify with `ls .claude/rules/ecc/`.
+1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/specs/guides/lifecycle.md`, and `Harness/specs/protocols/ACCEPTANCE_PROTOCOL.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/tasks/<task-id>/PLAN.md`.
 3. Fill `Harness/research/PRD.md` or the first task PLAN with Mini PRD fields: goal, scope, non-scope, user flow, UI elements, API behavior, acceptance criteria, and verification commands.
 4. Read `Harness/research/README.md`, then fill `Harness/research/research-results.md` with adopted/rejected research choices.
 5. Create AC IDs, UI/API contract tables, and a test plan before implementation. Use `Harness/templates/*` when helpful.
-6. Fill `Harness/architecture.md`.
+6. Fill `Harness/project/architecture.md`.
 7. Create a task capsule from `Harness/tasks/_template/` and fill the first vertical-slice plan in `Harness/tasks/<task-id>/PLAN.md`.
-8. Use `Harness/AGENT_ISOLATION.md`, `Harness/subagents.md`, `Harness/context-loading.md`, and `Harness/dispatch.md` when explicit WF/WK mode or any spawned subagents are involved.
+8. Use `Harness/specs/protocols/AGENT_ISOLATION.md`, `Harness/specs/runtime/subagents.md`, `Harness/specs/runtime/context-loading.md`, and `Harness/specs/runtime/dispatch.md` when explicit WF/WK mode or any spawned subagents are involved.
 9. Implement only after PRD-GATE, AC-GATE, CONTRACT-GATE, and TEST-GATE pass.
-10. Independently validate with an AC-by-AC result matrix; use `Harness/HARNESS_BRIDGE.md` for browser/API/CDP flows.
-11. For `/wf-auto` or memory scenario hints, read `Harness/WF-AUTO.md` and `Harness/MEMORY_PROTOCOL.md`; do not enable a background runner by default. The only allowed runtime hook is the optional `/wf-auto` bounded tick hook.
+10. Independently validate with an AC-by-AC result matrix; use `Harness/specs/protocols/HARNESS_BRIDGE.md` for browser/API/CDP flows.
+11. For `/wf-auto` or memory scenario hints, read `Harness/specs/workflows/WF-AUTO.md` and `Harness/specs/protocols/MEMORY_PROTOCOL.md`; do not enable a background runner by default. The only allowed runtime hook is the optional `/wf-auto` bounded tick hook.
 12. Run `node Harness/scripts/validate-harness.mjs --strict` after project-fact placeholders are resolved.
 13. 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.
 
@@ -69,7 +72,7 @@ Use this path when the user asks only to install or configure the harness in an
 2. Run the JSON `agent.safeMergeCommand` to create only missing files.
 3. Record discovered facts in the final install summary. Create or update task capsules only when bootstrap or multi-step implementation work begins.
 4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, package files, CI, docs routers, workflow docs, or installed skills/plugins/rules 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`.
+5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/specs/guides/extension.md`.
 6. Run `node Harness/scripts/validate-harness.mjs` as the install-complete gate.
 7. Defer `node Harness/scripts/validate-harness.mjs --strict` until bootstrap removes project-fact placeholders. If placeholders intentionally remain, report strict validation as deferred rather than treating install as failed.
 
@@ -132,24 +135,24 @@ The harness validator checks for specific structural invariants. When comparing
 
 | File | Required check |
 |------|----------------|
-| `CLAUDE.md` | Must be merged only after user confirmation when it already exists. Required contract: `## 1. Harness Binding & Startup` with the `Harness/SETUP.md` bootstrap contract line; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); `Never bulk-read Harness/` in Startup |
+| `CLAUDE.md` | Must be merged only after user confirmation when it already exists. Required contract: `## 1. Harness Binding & Startup`; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); startup-hints routing; no startup dependency on this setup reference |
 | `AGENTS.md` | Root agent entry points to `CLAUDE.md` and `Harness/README.md`; for existing projects, merge only after explicit user consent |
 | `README.md` | Existing README is project-owned. Preserve by default; ask whether to append only Development notes or run `wf-readme` for a structure pass with tables/diagrams before broad edits |
 | `Harness/MEMORY.md` | All 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` | Required project-local universal rules. Keep it even when global `~/.claude/rules/ecc/common/` exists; that directory and this file have different scopes. Required sections: `## Context` with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` with three reflection file entries; `## Security` |
 | `Harness/README.md` | `## Keyword Routing` heading; `## Load By Task` table with at minimum the rows: "Need WF mode (explicit only)", "Adding harness to existing project", "Need implementation plan", "Need parallel agents", "Need subagents", "Need durable memory or reflection"; WF routing keywords include `/wf`, `$wf`, `/skills wf`, `/wf-max`, `$wf-max`, `/skills wf-max`; explicit WF entry only — no auto-triggering from task complexity, failure count, or old aliases; `## Doc Map` with `memory/` and `subagents.md` entries; the durable communication invariant text; `Harness/README.md is the primary Harness documentation router` |
-| `Harness/WF.md` | `WF is explicit only`; tier-aware contract: `WF-Light` (planner/test/verifier, no mandatory cross-review/reflector), `WF-Standard` (adds research + one review lens), `WF-Full` (complete role chain with cross-review + reflector PASS); `Collaboration tier guide`; `Heartbeat Protocol` |
-| `Harness/WF-MAX.md` | `WF-MAX is explicit only`; `WF-Max-Useful` (default, fan-out only where independent); `WF-Max-Strict` (explicit strict override); three-layer architecture; D-GATE; span formula |
-| `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; registered common agent entries; `## Handoff Format` heading |
-| `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary Harness documentation router`; all 12 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier, Memory Master, Context Master) |
-| `Harness/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `collaboration decision tree`; 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/specs/workflows/WF.md` | `WF is explicit only`; tier-aware contract: `WF-Light` (planner/test/verifier, no mandatory cross-review/reflector), `WF-Standard` (adds research + one review lens), `WF-Full` (complete role chain with cross-review + reflector PASS); `Collaboration tier guide`; `Heartbeat Protocol` |
+| `Harness/specs/workflows/WF-MAX.md` | `WF-MAX is explicit only`; `WF-Max-Useful` (default, fan-out only where independent); `WF-Max-Strict` (explicit strict override); three-layer architecture; D-GATE; span formula |
+| `Harness/specs/guides/extension.md` | `## Non-Invasive Extension Rules` section with the "Preserve existing" rule; `## Agent Contract` section; `## Registration` section |
+| `Harness/specs/runtime/dispatch.md` | The durable communication invariant; registered common agent entries; `## Handoff Format` heading |
+| `Harness/specs/runtime/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary Harness documentation router`; all 12 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier, Memory Master, Context Master) |
+| `Harness/specs/runtime/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `collaboration decision tree`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
+| `Harness/project/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` | Temporary install/bootstrap guide for new projects, existing projects, legacy upgrades, and Harness update decisions. If kept, ensure "Install or Upgrade Path" 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/specs/guides/SETUP.md` | Retained install/bootstrap guide for new projects, existing projects, legacy upgrades, and Harness update decisions. Keep "Install or Upgrade Path" present. |
+| `.claude/skills/wf-browser/SKILL.md` and `.agents/skills/wf-browser/SKILL.md` | Built-in browser workflow requires `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` guidance |
 | `Harness/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
 
 **Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
@@ -161,7 +164,7 @@ The generated file list is authoritative by path, not by stale count labels. Cur
 - `.claude/skills/*.md` and mirrored `.agents/skills/*.md` — Claude Code and Codex skill adapters over the same Harness docs
 - `.claude/rules/ecc/common.md` - required project-local universal rules. Do not delete this file as a duplicate of a global `~/.claude/rules/ecc/common/` directory; they are different scopes.
 - `.claude/settings.json` — harness settings
-- `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs
+- `Harness/specs/workflows/WF.md`, `Harness/specs/guides/lifecycle.md`, `Harness/specs/runtime/subagents.md`, `Harness/specs/runtime/agent-workflow.md`, `Harness/project/architecture.md` — harness runtime docs
 - `Harness/research/*.md` — research protocol and templates
 - `AGENTS.md` — agent registry; if it already exists, ask for user consent before merging or replacing it
 - `Harness/scripts/validate-harness.mjs` and `tests/.gitkeep` — tooling
@@ -169,7 +172,7 @@ The generated file list is authoritative by path, not by stale count labels. Cur
 Optional workflow examples:
 
 ```bash
-npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
+npx create-harness-vibe-coding@latest my-app ./my-app -y --with ts-react-frontend,ui-ux-review
 npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
 npx create-harness-vibe-coding@latest my-app ./my-app -y --recommend superpowers,codegraph
 ```
@@ -196,7 +199,7 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 - `{{CONSTRAINT_1..3}}`: hard technical constraints derived from research.
 - `{{ALTERNATIVE_1..2}}`: rejected candidates worth watching for future.
 
-**`Harness/architecture.md`** — Layer structure. Derive from research-results:
+**`Harness/project/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.
 - `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.
@@ -261,7 +264,7 @@ ECC and Superpowers overlap ~80% in topic coverage but serve different purposes:
 | **Unique** | Design quality, performance budgets, security CSP, per-language idioms | Brainstorming, git worktrees |
 
 **Installation rule:**
-1. **ECC is mandatory.** Install `common/` + stack-specific rules during bootstrap step 0. See `Harness/ECC-GUIDE.md`.
+1. **ECC is mandatory.** Install `common/` + stack-specific rules during bootstrap step 0. See `Harness/specs/guides/ECC-GUIDE.md`.
 2. **Superpowers is recommended.** Install after ECC. It adds ~14 workflow skills that teach agents *how* to execute ECC standards.
 3. **No duplicates from other sources.** If a Superpowers skill has an ECC equivalent, keep both — they don't conflict. ECC sets the bar, Superpowers shows the path.
 4. **Priority**: ECC rules take precedence when there's a conflict. ECC is the contract; Superpowers is the training manual.
@@ -274,13 +277,13 @@ ECC and Superpowers overlap ~80% in topic coverage but serve different purposes:
 3. Selected external GitHub links - let the user's agent read that project's README and install only after approval.
 4. GitHub search - when the first three miss niche domains.
 
-**What to install**: after finding skills, add the canonical copy to `.claude/skills/<name>/SKILL.md` and mirror the same file to `.agents/skills/<name>/SKILL.md` when Codex should discover it. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
+**What to install**: after finding skills, add the canonical copy to `.claude/skills/<name>/SKILL.md` and mirror the same file to `.agents/skills/<name>/SKILL.md` when Codex should discover it. Follow `Harness/specs/guides/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
 
 This scaffold includes built-in harness skills in `.claude/skills/*` and mirrored Codex repo skills in `.agents/skills/*`. Keep those. Add stack-specific ones alongside them.
 
 ## Optional Agent Assets
 
-After the product shape is known, Claude Code may also install or copy stack-specific agents and rules into `.claude/`. Codex-discoverable workflow skills belong in `.agents/skills/`. Follow `Harness/extension.md` for every added asset.
+After the product shape is known, Claude Code may also install or copy stack-specific agents and rules into `.claude/`. Codex-discoverable workflow skills belong in `.agents/skills/`. Follow `Harness/specs/guides/extension.md` for every added asset.
 
 Examples:
 
@@ -290,18 +293,12 @@ This is a Python data product. Add data pipeline and pytest workflow agents.
 This is a Go service. Add API, security, and integration-test agents.
 ```
 
-## Cleanup (Isolate & Remove)
+## Retention
 
-This file is designed to be orphaned. When all configuration is complete:
-
-1. Open `CLAUDE.md`. Confirm the setup line reads the bootstrap-only contract (starts with: ``Harness/SETUP.md` is a bootstrap-only document``). It stays valid after this file is deleted.
-2. Delete this file.
-
-```bash
-rm Harness/SETUP.md
-```
-
-After both steps, `Harness/SETUP.md` is fully isolated — no file references it, no trace remains. You are free to delete it at any time. It is a bootstrap scaffold, not a permanent fixture.
+Keep this file as a setup reference. It is not part of the normal startup path:
+routine sessions start at `CLAUDE.md` and `Harness/memory/startup-hints.md`;
+`Harness/README.md` is the workflow router when routed. Re-open this file only for install/bootstrap,
+migration, upgrade decisions, or explicit user requests for setup guidance.
 
 ---
 
@@ -324,4 +321,4 @@ After scaffolding, use the JSON output first. Files in `plan.create[]` were hand
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 2. Follow the Required Bootstrap Sequence above.
 3. Run `node Harness/scripts/validate-harness.mjs` after install. Run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap resolves project-fact placeholders.
-4. Delete `Harness/SETUP.md`.
+4. Keep `Harness/specs/guides/SETUP.md` as a setup reference; normal sessions start at `CLAUDE.md`, and routed workflow work uses `Harness/README.md` as the router.

package/templates/common/Harness/{extension.md → specs/guides/extension.md}

@@ -12,7 +12,7 @@ Extensions must preserve project and harness ownership boundaries.
 - Treat existing project config as project fact. Read it before adding assets, then adapt new assets to the project instead of replacing the project.
 - Register added agents, skills, workflows, and rules in `Harness/MEMORY.md` and this docs router where applicable.
 - Added assets may extend `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, or `Harness/workflows/`, but they must not replace core harness docs.
-- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.md`, `Harness/subagents.md`, `Harness/context-loading.md`, `Harness/dispatch.md`, `Harness/agent-workflow.md`, and this file.
+- Core harness docs are `Harness/README.md`, `Harness/PROGRESS.md`, `Harness/specs/runtime/subagents.md`, `Harness/specs/runtime/context-loading.md`, `Harness/specs/runtime/dispatch.md`, `Harness/specs/runtime/agent-workflow.md`, and this file.
 - If an optional workflow needs a new command or tool, document the command and fallback in `Harness/workflows/<name>.md` instead of changing core harness behavior.
 
 ## Agent Contract
@@ -35,7 +35,7 @@ Agent body must state:
 - allowed write set or read-only
 - forbidden scope
 - verification or evidence
-- return format from [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
+- return format from [subagents.md](../runtime/subagents.md) and [dispatch.md](../runtime/dispatch.md)
 
 ## Skill Contract
 
@@ -47,7 +47,7 @@ Every added skill must state:
 - allowed writes
 - output format
 - whether to update `Harness/PROGRESS.md` and task files
-- whether to use [subagents.md](subagents.md) and [dispatch.md](dispatch.md)
+- whether to use [subagents.md](../runtime/subagents.md) and [dispatch.md](../runtime/dispatch.md)
 
 Skills should extend the harness. They should not replace `Harness/README.md`, `Harness/PROGRESS.md`, `subagents.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
 

package/templates/common/Harness/{lifecycle.md → specs/guides/lifecycle.md}

@@ -12,8 +12,8 @@ Use when starting a new product, clarifying a vague idea, or deciding the next p
 | Acceptance | PRD | AC IDs in `ACCEPTANCE.md` section, feature doc, or task PLAN | every user-visible behavior has Given/When/Then and evidence method |
 | Contract | acceptance criteria | UI/API/state contract tables | UI selectors, API payloads, state changes, and negative assertions are testable |
 | Test Plan | contracts | `TEST_PLAN.md` section or task PLAN verification matrix | tests map to AC IDs before implementation starts |
-| Architecture | PRD and contracts | `Harness/architecture.md` | boundaries and first ports are defined |
-| Plan | PRD, AC, contracts, architecture | `Harness/tasks/<task-id>/PLAN.md`, optional `Harness/dispatch.md` | tasks have owners, write sets, forbidden truth files, and verification |
+| Architecture | PRD and contracts | `Harness/project/architecture.md` | boundaries and first ports are defined |
+| Plan | PRD, AC, contracts, architecture | `Harness/tasks/<task-id>/PLAN.md`, optional `Harness/specs/runtime/dispatch.md` | tasks have owners, write sets, forbidden truth files, and verification |
 | Build | plan and tests | minimal vertical slice | implementation satisfies AC IDs without modifying truth files |
 | Independent Validation | running slice | acceptance result matrix, screenshots/traces/logs | validator is not implementer; no unresolved critical/high findings |
 | Debug | failed AC evidence | root-cause handoff and smallest fix | failing layer identified before edits |

package/templates/common/Harness/specs/protocols/TASK_ARCHIVE.md

@@ -0,0 +1,76 @@
+# TASK_ARCHIVE - Task Archive Mechanism
+
+Purpose: keep `Harness/tasks/` lean by archiving completed/abandoned tasks while
+preserving all evidence.
+
+## Archive Location
+
+Active tasks stay in `Harness/tasks/<task-id>/`.
+Archived tasks move to `Harness/tasks/_archive/YYYY/<task-id>/`.
+
+## What Is Never Archived
+
+- `Harness/tasks/_template/` - scaffold template, never moved.
+- `Harness/tasks/auto/` - WF-AUTO permanent state capsule, never moved unless
+  explicitly allowed by WF-AUTO docs.
+- `Harness/tasks/_archive/` - the archive directory itself.
+- Active, blocked, in-progress, running, pending, or needs-user-decision tasks.
+- Tasks whose STATE.json status is `active`, `blocked`, `in_progress`,
+  `running`, `pending`, or `needs-user-decision`.
+
+## What May Be Archived
+
+Tasks whose STATE.json or reconciled phase is: `complete`, `verified`,
+`archived`, `abandoned`, `obsolete`, `done`, `closed`, or `closeout`.
+
+`Harness/scripts/task-state.mjs` reads STATE.json `status`/`phase` first, then
+uses root/task PROGRESS phases only as reconciliation evidence. Missing or
+invalid STATE.json is skipped until
+`node Harness/scripts/task-state.mjs reconcile --apply` creates or repairs
+machine state.
+
+## Archive Process
+
+1. Verify the task is not active/blocked/running/pending.
+2. Ensure `Harness/tasks/_archive/YYYY/` exists.
+3. Move `Harness/tasks/<task-id>/` to
+   `Harness/tasks/_archive/YYYY/<task-id>/`.
+4. Update the moved STATE.json: `status` to `archived`, `phase` to `archived`.
+5. Update `Harness/tasks/_archive/INDEX.md`.
+6. Rewrite `Harness/PROGRESS.md` Task Index from the remaining non-archived
+   task capsules.
+
+## Retention
+
+- Archived tasks retain: PLAN, PROGRESS, STATE, ARTIFACTS, NOTES.
+- Do NOT delete historical evidence.
+- `Harness/PROGRESS.md` keeps the last 5 non-archived task entries in the Task
+  Index.
+- When outer task capsules exceed 5 completed/abandoned/obsolete tasks, archive
+  the oldest safe tasks.
+- The validator (`Harness/scripts/validate-harness.mjs`) warns when
+  `Harness/tasks/` holds more than 5 outer task capsules (excluding `_archive`,
+  `_template`, `auto`) and fails in `--strict` mode.
+
+## Script
+
+Use `Harness/scripts/task-state.mjs archive`:
+
+- Default: dry-run.
+- `--apply` to execute.
+- `--keep 5` to set the non-archived task threshold.
+- `--task <task-id>` to archive a specific task.
+- `--json` for machine-readable output.
+- Run `node Harness/scripts/task-state.mjs archive --dry-run --json` before
+  applying a risky cleanup.
+
+Compatibility entry: `Harness/scripts/archive-tasks.mjs` delegates to
+`task-state.mjs archive` and accepts the same archive flags.
+
+## Safety Rules
+
+- Windows path safe. Use `path.resolve()` before moving.
+- Confirm target is within `Harness/tasks/` before any move.
+- Do NOT recursively delete.
+- Tasks with `needs-user-decision` status are never auto-archived.
+- Missing or invalid STATE.json is never archived without reconciliation.

package/templates/common/Harness/{agent-workflow.md → specs/runtime/agent-workflow.md}

@@ -4,10 +4,10 @@ Use when implementing, reviewing, debugging, or coordinating subagents.
 
 This workflow is acceptance-driven. PRD-derived Acceptance Criteria are the
 source of truth; implementation, tests, review, validation, debug, and memory
-must trace to AC IDs. Load [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) for
-gate rules, [TDD-GUIDE.md](TDD-GUIDE.md) for AC-linked RED tests,
-[HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) for UI/API/browser evidence, and
-[AGENT_ISOLATION.md](AGENT_ISOLATION.md) before role splits.
+must trace to AC IDs. Load [ACCEPTANCE_PROTOCOL.md](../protocols/ACCEPTANCE_PROTOCOL.md) for
+gate rules, [TDD-GUIDE.md](../protocols/TDD-GUIDE.md) for AC-linked RED tests,
+[HARNESS_BRIDGE.md](../protocols/HARNESS_BRIDGE.md) for UI/API/browser evidence, and
+[AGENT_ISOLATION.md](../protocols/AGENT_ISOLATION.md) before role splits.
 
 ## ReAct Loop
 
@@ -118,8 +118,8 @@ Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent
 | Mode | Agent Count Rule | Source |
 |------|-----------------|--------|
 | Default (non-WF) | up to 3 active agents by default | This file |
-| `/wf` | WF-KERNEL tier selection (Light/Standard/Full) by risk and scope; full role chain only at WF-Full | [WF.md](WF.md) |
-| `/wf-max` | WF kernel plus maximum useful fan-out (WF-Max-Useful default; WF-Max-Strict explicit only) | [WF-MAX.md](WF-MAX.md) |
+| `/wf` | WF-KERNEL tier selection (Light/Standard/Full) by risk and scope; full role chain only at WF-Full | [WF.md](../workflows/WF.md) |
+| `/wf-max` | WF kernel plus maximum useful fan-out (WF-Max-Useful default; WF-Max-Strict explicit only) | [WF-MAX.md](../workflows/WF-MAX.md) |
 
 Prefer parallel read-only work first, then serial writes.
 

package/templates/common/Harness/{context-loading.md → specs/runtime/context-loading.md}

@@ -10,33 +10,97 @@ If this file and `Harness/README.md` disagree, follow `Harness/README.md`, recor
 
 project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
-## Main Context
-
-Always keep:
-
-- `CLAUDE.md`
-- `Harness/MEMORY.md`
-- `Harness/README.md`
-- `Harness/PROGRESS.md` when active
-- `Harness/tasks/<task-id>/PROGRESS.md` when active
-- `Harness/tasks/<task-id>/PLAN.md` when active
-- current feature doc when active
-
-Load other docs only by trigger.
+## Context Tiers
+
+These tiers are automatic route profiles, not user-selected modes. The agent
+selects a profile from the explicit command, user request, active task state,
+router row, skill trigger, and concrete file references.
+
+Budgets are regression guards, not exclusion rules. If correctness requires a
+file outside the current profile, load that file and record the reason in the
+task notes/progress when the work is in WF. Do not skip required rules, source
+files, contracts, tests, or evidence to stay under budget.
+
+| Tier | When | Keep | Do Not Load |
+| --- | --- | --- | --- |
+| Thin startup | New installed-project session before task routing | `CLAUDE.md`, `Harness/memory/startup-hints.md` | `Harness/MEMORY.md`, `Harness/README.md`, `Harness/PROGRESS.md`, workflow docs, skill bodies |
+| Direct task | Simple, single-step, low-risk request | `CLAUDE.md` plus only files needed for the task | full router, task capsules, unrelated Harness docs |
+| Router prefix | Explicit `/wf-*`, `$wf-*`, or `/skills wf-*` command | `CLAUDE.md`, `Harness/MEMORY.md` index, `Harness/README.md`, `Harness/PROGRESS.md` only when active | unrelated workflow docs, all skills, all agents, unused tool schemas |
+| Active task scope | Router found an active task | `STATE.json` first, then task `PROGRESS.md`, task `PLAN.md` only when decisions/scope need review, current feature doc when active | archived tasks, unrelated task directories, broad task history |
+| Routed skill/doc | Router, command, or `tool_search` selects a specific capability | selected skill body and adjacent docs named by that skill/doc | all skill bodies, all tool schemas, whole `Harness/` tree |
+
+After the tier is selected, load other docs only by trigger.
+
+Escalation rule: when unsure whether a file is required, prefer targeted
+keyword search or a one-file read over guessing from memory. Escalate from a
+smaller profile to the next targeted profile only when the new file directly
+proves or disproves the current decision.
+
+## Cache-First Context Contract
+
+Prompt-cache hit rate is a context-layout constraint. Preserve this order for
+WF commands, skill adapters, and subagent packets:
+
+1. Stable prefix: `CLAUDE.md`, `Harness/MEMORY.md` index, `Harness/README.md`,
+   selected workflow docs, and stable skill/agent indexes in deterministic
+   order.
+2. Scoped references: task `STATE.json`, `PLAN.md`, contracts, selected source
+   files, and selected docs only.
+3. Dynamic suffix: newest user message, active question, current heartbeat,
+   current date/time, cwd/runtime/model/channel, fresh search results, tool
+   output, command logs, screenshots, and validation evidence.
+
+Rules:
+
+- Do not reorder stable loads during a task.
+- Put volatile values after the stable prefix; do not place timestamps, request
+  IDs, latest tool output, or fresh search results in startup/router text.
+- Load skill bodies and tool schemas only when routed by the explicit command,
+  `Harness/README.md`, or `tool_search`; do not preload all skills or tools.
+- Keep dispatch packets deterministic: canonical field order, stable tool/skill
+  list order, bounded `MaxReturnTokens`, and short `ReturnSchema`.
+- Prefer file paths and compact task-state summaries over pasted logs or
+  transcripts. Append-only `PROGRESS.md`/`STATE.json` beats rewritten summaries
+  until compaction is required.
+- Treat a model switch, reasoning/context-size change, enabled-tool/MCP change,
+  or compaction as a cache boundary and record it in task progress.
+
+## Cache Validation Levels
+
+- **L0 structure**: `validate-harness.mjs` proves the Harness still preserves
+  stable-prefix/dynamic-suffix routing, deferred skills/tools, and bounded
+  summaries. This is regression protection only.
+- **L1 prefix simulation**: compare two serialized dispatch/context packets and
+  prove the stable prefix bytes are identical while only the dynamic suffix
+  changes. Use this when a runtime exposes prompt assembly locally.
+  Covered by `tests/l1-prefix-simulation.test.js` (positive match + negative
+  controls + anti-pollution detection).
+- **L2 provider telemetry**: prove real cache behavior from model response
+  usage fields, such as OpenAI `cached_tokens` / `cache_write_tokens` or
+  Anthropic `cache_read_input_tokens` / `cache_creation_input_tokens`, across a
+  warm-up request and repeated same-prefix requests.
+  For Claude Code scripted probes, use
+  `node Harness/scripts/l2-cache-telemetry.mjs`; it records the exact CLI
+  flags, session IDs, usage fields, cost, duration, and claim-gate result in
+  `$HOME/.claude/cache-telemetry/`.
+
+Do not claim real cache hits or hit-rate improvement from structure checks
+alone. A real cache-hit claim requires L2 telemetry, or an explicit statement
+that the current runtime does not expose provider cache metrics.
 
 ## Trigger Matrix
 
 | Trigger | Load |
 | --- | --- |
-| idea, scope, MVP | `Harness/lifecycle.md`, `Harness/research/PRD.md`, `Harness/ACCEPTANCE_PROTOCOL.md` |
-| acceptance, AC, criteria, contract, validation matrix | `Harness/ACCEPTANCE_PROTOCOL.md`, `Harness/AGENT_ISOLATION.md`, `Harness/HARNESS_BRIDGE.md` as needed |
+| idea, scope, MVP | `Harness/specs/guides/lifecycle.md`, `Harness/research/PRD.md`, `Harness/specs/protocols/ACCEPTANCE_PROTOCOL.md` |
+| acceptance, AC, criteria, contract, validation matrix | `Harness/specs/protocols/ACCEPTANCE_PROTOCOL.md`, `Harness/specs/protocols/AGENT_ISOLATION.md`, `Harness/specs/protocols/HARNESS_BRIDGE.md` as needed |
 | research, competitors, stack choice | `Harness/research/README.md`, `Harness/research/research-results.md` |
-| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/agent-workflow.md` |
-| parallel agents, dispatch, worktree decision | `Harness/subagents.md`, `Harness/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
-| `/wf` mode (explicit only) | [Harness/WF.md](WF.md), [Harness/subagents.md](subagents.md), [Harness/dispatch.md](dispatch.md), [Harness/tasks/<task-id>/PLAN.md](tasks/<task-id>/PLAN.md) |
-| `/wf-max` (explicit only) | [Harness/WF-MAX.md](WF-MAX.md), [Harness/subagents.md](subagents.md), [Harness/dispatch.md](dispatch.md), [Harness/tasks/<task-id>/PLAN.md](tasks/<task-id>/PLAN.md) |
-| memory, scenario memory, repeated tool failure, repeated user correction, reusable lesson | `Harness/MEMORY.md`, `Harness/MEMORY_PROTOCOL.md`, the relevant `Harness/memory/*.md` file |
-| subagent spawn | `Harness/subagents.md`, `Harness/AGENT_ISOLATION.md`, this file plus the role pack below |
+| task split, owner, write set | `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/specs/runtime/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `Harness/specs/runtime/subagents.md`, `Harness/specs/runtime/dispatch.md`, `Harness/tasks/<task-id>/PLAN.md` |
+| `/wf` mode (explicit only) | [Harness/specs/workflows/WF.md](../workflows/WF.md), [Harness/specs/runtime/subagents.md](subagents.md), [Harness/specs/runtime/dispatch.md](dispatch.md), [Harness/tasks/<task-id>/PLAN.md](../../tasks/<task-id>/PLAN.md) |
+| `/wf-max` (explicit only) | [Harness/specs/workflows/WF-MAX.md](../workflows/WF-MAX.md), [Harness/specs/runtime/subagents.md](subagents.md), [Harness/specs/runtime/dispatch.md](dispatch.md), [Harness/tasks/<task-id>/PLAN.md](../../tasks/<task-id>/PLAN.md) |
+| memory, scenario memory, repeated tool failure, repeated user correction, reusable lesson | `Harness/MEMORY.md`, `Harness/specs/protocols/MEMORY_PROTOCOL.md`, the relevant `Harness/memory/*.md` file |
+| subagent spawn | `Harness/specs/runtime/subagents.md`, `Harness/specs/protocols/AGENT_ISOLATION.md`, this file plus the role pack below |
 
 ## ECC Rules Per Role
 

package/templates/common/Harness/{dispatch.md → specs/runtime/dispatch.md}

@@ -11,14 +11,15 @@ Use when work needs parallel reading, independent review, cross-layer analysis,
 - Main agent owns the final decision, integration, and verification.
 - project files are the only durable communication channel; chat/subagent transcript state is non-authoritative.
 - Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-- Resumable state is governed by [WF-STATE.md](WF-STATE.md). On session start, the controller reads STATE.json before building a fresh dispatch table.
+- Resumable state is governed by [WF-STATE.md](../workflows/WF-STATE.md). On session start, the controller reads STATE.json before building a fresh dispatch table.
 - PRD-derived Acceptance Criteria are the source of truth. Dispatch packets must carry the relevant AC IDs and contracts.
-- Agent count: default (non-WF) <=3 active agents; `/wf` selects a tier dynamically per [WF-KERNEL.md](WF-KERNEL.md) (Light/Standard/Full); `/wf-max` inherits the selected tier and adds maximum safe fan-out (WF-Max-Useful default; WF-Max-Strict explicit only), removing the Harness default cap through the span formula. Real concurrency is still bounded by runtime thread budget, config, billing, and local resources. Use current runtime subagents first, close completed agents, then peer-CLI overflow (`claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`). Generated Codex config defaults to `agents.max_threads = 12` and `agents.max_depth = 1`; ask the user before raising `agents.max_threads` above that default. See [WF.md](WF.md) and [WF-MAX.md](WF-MAX.md).
+- Agent count: default (non-WF) <=3 active agents; `/wf` selects a tier dynamically per [WF-KERNEL.md](../workflows/WF-KERNEL.md) (Light/Standard/Full); `/wf-max` inherits the selected tier and adds maximum safe fan-out (WF-Max-Useful default; WF-Max-Strict explicit only), removing the Harness default cap through the span formula. WF-MAX must attempt native subagent fan-out and record `fanoutAttempted: true` before any solo fallback. Real concurrency is still bounded by runtime thread budget, config, billing, and local resources. Use current runtime subagents first, close completed agents, then peer-CLI overflow (`claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`). Do not scaffold Codex scalar `[agents]` capacity fields into project `.codex/config.toml`; probe the installed runtime and manage Codex caps through the dispatch ledger unless the installed version accepts the config shape. Generated OpenCode config defaults to `subagent_depth = 2` for manager -> worker nesting. See [WF.md](../workflows/WF.md) and [WF-MAX.md](../workflows/WF-MAX.md).
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint.
 - Use a worktree when two agents may touch overlapping files or long-running branches.
 - Only summaries enter main context. Load named files directly when details are needed.
 - Only the controller or task-scribe writes task state (PROGRESS.md, PLAN.md). Production source agents (implementer, debugger, test-writer) never write task state unless explicitly dispatched as task-scribe.
+- Cache-first dispatch follows `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: canonical field order, stable tool/skill list order, dynamic evidence/logs last, and bounded `MaxReturnTokens`/`ReturnSchema`.
 
 ## Scope
 
@@ -67,7 +68,7 @@ Objective:           <one-sentence goal>
 TaskType:            ui-browser | api-backend | architecture-migration | docs-readme | dependency-sdk | bug-fix | refactor | chore
 ModelTier:           small-fast | standard | high-reasoning
 AgentName:           <the agent file name, e.g. task-scribe, codebase-explorer, implementer>
-Skills:              <which skills to activate, e.g. tdd, browser-e2e>
+Skills:              <which skills to activate, e.g. tdd, wf-browser>
 ECC:                 <which ECC rules to load, e.g. web/design-quality.md, python/fastapi.md>
 PRD:                 <path or task PLAN section containing Mini PRD>
 Acceptance IDs:      <AC-001, AC-002, or "none" for non-behavioral work>