create-harness-vibe-coding 0.8.13 → 0.8.16

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,23 +135,23 @@ 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/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. |
 | `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 |
 
@@ -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
@@ -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/{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. 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](../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
 

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

@@ -4,10 +4,15 @@ Purpose: coordinate subagents for speed without losing control of scope, evidenc
 
 Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or explicit `/wf` / `/wf-max` invocation.
 
+Cache-first discipline: subagent context packs follow
+`Harness/specs/runtime/context-loading.md#Cache-First Context Contract`. Inject only routed
+docs and selected files, keep dispatch fields in deterministic order, defer
+unused skill/tool schemas, and return bounded summaries instead of transcripts.
+
 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.
 
-Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](AGENT_ISOLATION.md)
-for role/context isolation and [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md)
+Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](../protocols/AGENT_ISOLATION.md)
+for role/context isolation and [ACCEPTANCE_PROTOCOL.md](../protocols/ACCEPTANCE_PROTOCOL.md)
 for PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, and
 REVIEW-GATE.
 
@@ -82,7 +87,7 @@ Hard rule: implementer may not be the independent validator for the same AC ID.
 
 ## WF Default Fan-Out
 
-Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/WF.md`.
+Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/specs/workflows/WF.md`.
 WF-Light: planner + test-writer + implementer + verifier.
 WF-Standard: adds research/docs + one review lens.
 WF-Full: complete role-chain coverage from `.claude/agents/` before closeout: plan,
@@ -106,7 +111,7 @@ Then add phase-specific agents:
 - `context-master` before closeout for knowledge extraction
 - `memory-master` after repeated failures and during closeout for consolidation
 
-Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
+Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/specs/workflows/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
 
 ## Efficiency Ladder
 
@@ -168,7 +173,7 @@ controller intake
 
 ## Dispatch Pack
 
-Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](WF-STATE.md) to resume the dispatch ledger and ready queue.
+Use the canonical dispatch input and handoff format in `Harness/specs/runtime/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/specs/runtime/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](../workflows/WF-STATE.md) to resume the dispatch ledger and ready queue.
 
 ## Parallelism Rules
 

package/templates/common/Harness/{WF-AUTO-SPARK.md → specs/workflows/WF-AUTO-SPARK.md}

@@ -22,7 +22,7 @@ But perpetual search without direction = drift. The **Roadmap** is the anchor.
 
 WF-AUTO-SPARK is a `/wf` variant layered on WF-AUTO: it inherits the WF-KERNEL contract via WF-AUTO and WF constraints, and does not define an independent heavy process. External spark search replaces discovery only; it does not replace acceptance, implementation, review, verification, reflection, or evidence.
 
-Accepted spark candidates re-enter the standard W2-W5 gates per [WF-KERNEL.md](WF-KERNEL.md): implementer (one file_claim, ≤3 files, ≤50 lines), verifier, reviewer(s), reflector. Spark searchers are read-only. Any implementation must use the dispatch packet from `Harness/dispatch.md` with explicit write set, forbidden truth files, AC IDs, and verification commands. A candidate with no verifier evidence or no reflector PASS is not accepted, even if the idea is valuable.
+Accepted spark candidates re-enter the standard W2-W5 gates per [WF-KERNEL.md](WF-KERNEL.md): implementer (one file_claim, ≤3 files, ≤50 lines), verifier, reviewer(s), reflector. Spark searchers are read-only. Any implementation must use the dispatch packet from `Harness/specs/runtime/dispatch.md` with explicit write set, forbidden truth files, AC IDs, and verification commands. A candidate with no verifier evidence or no reflector PASS is not accepted, even if the idea is valuable.
 
 For task-state writes, CEO provides concise bullets and decisions; task-scribe formats task-state writes for roadmap, cycle PLAN, heartbeat, evidence pointers, and closeout. If task-scribe is unavailable, CEO may write the smallest durable checkpoint and must record that degradation in `PROGRESS.md`. This keeps the high-reasoning controller focused on decisions instead of spending tokens formatting process files.
 
@@ -313,7 +313,7 @@ This replaces the broken `/wf-auto` auto-continue. No silent drift across sessio
 
 | File | Purpose |
 |------|---------|
-| `Harness/WF-AUTO-SPARK.md` | This spec |
+| `Harness/specs/workflows/WF-AUTO-SPARK.md` | This spec |
 | `Harness/tasks/auto/SPARK-ROADMAP.md` | Active roadmap (created at startup) |
 | `Harness/tasks/auto/PLAN.md` | Per-cycle change spec |
 | `Harness/tasks/auto/PROGRESS.md` | Cycle log, heartbeat, evidence ledger |

package/templates/common/Harness/{WF-AUTO.md → specs/workflows/WF-AUTO.md}

@@ -302,6 +302,11 @@ Runtime hooks are disabled by default across the Harness scaffold. The only
 allowed exception is an explicitly enabled `/wf-auto` tick hook for long-running
 auto-optimization.
 
+Manual or benchmark-driven single-cycle `/wf-auto` runs use the same bounded
+tick contract: they may stop because the caller explicitly requested one tick,
+but they still MUST create or update `Harness/tasks/auto/PLAN.md` and
+`Harness/tasks/auto/PROGRESS.md` before returning.
+
 The hook is not a role-enforcement mechanism, not a memory injection mechanism,
 and not WF-MAX state. It is only a bounded tick trigger:
 
@@ -368,7 +373,7 @@ Spark is NOT a separate optimization engine. It is a **candidate provider** plug
 - User explicitly requests `/wf-auto-spark` → full perpetual inspiration mode (see `WF-AUTO-SPARK.md`)
 - User says "I don't know" at an Intent Checkpoint
 
-**`/wf-auto-spark` is a standalone perpetual mode** (spec: `Harness/WF-AUTO-SPARK.md`). Unlike vanilla spark which is a candidate provider inside `/wf-auto`, the standalone mode:
+**`/wf-auto-spark` is a standalone perpetual mode** (spec: `Harness/specs/workflows/WF-AUTO-SPARK.md`). Unlike vanilla spark which is a candidate provider inside `/wf-auto`, the standalone mode:
 - Never auto-stops — only user can stop it
 - Requires a roadmap (North Star + staged milestones) declared at startup
 - Enforces ≤50% deviation guard against North Star

package/templates/common/Harness/{WF-KERNEL.md → specs/workflows/WF-KERNEL.md}

@@ -2,6 +2,16 @@
 
 The WF Kernel is the shared engine for `/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, and `/wf-browser`. Variants extend the kernel; they do not duplicate the orchestration logic.
 
+## Cache-First Context Contract
+
+All WF variants preserve prompt-cache shape: stable workflow instructions and
+deterministic dispatch schema first; task-specific state, current runtime facts,
+and latest tool outputs last. Use
+`Harness/specs/runtime/context-loading.md#Cache-First Context Contract` for load ordering.
+Dispatch packets keep canonical field order, load only selected skills/tools,
+and return bounded summaries through `MaxReturnTokens` and `ReturnSchema`
+instead of transcripts.
+
 ## Role / Model Matrix
 
 The orchestrator dispatches agents by role, model tier, and task type. No single agent type handles all work.