create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/.claude/skills/tdd/SKILL.md

@@ -5,7 +5,7 @@ description: Test-driven development. Use when the user wants to build features
 
 # TDD Adapter
 
-Thin tool adapter. Authoritative guide: `Harness/TDD-GUIDE.md`.
+Thin tool adapter. Authoritative guide: `Harness/specs/protocols/TDD-GUIDE.md`.
 
 ## Invocation
 
@@ -14,10 +14,10 @@ Thin tool adapter. Authoritative guide: `Harness/TDD-GUIDE.md`.
 
 ## Load
 
-1. `Harness/ACCEPTANCE_PROTOCOL.md`
-2. `Harness/HARNESS_BRIDGE.md`
-3. `Harness/AGENT_ISOLATION.md`
-4. `Harness/TDD-GUIDE.md`
+1. `Harness/specs/protocols/ACCEPTANCE_PROTOCOL.md`
+2. `Harness/specs/protocols/HARNESS_BRIDGE.md`
+3. `Harness/specs/protocols/AGENT_ISOLATION.md`
+4. `Harness/specs/protocols/TDD-GUIDE.md`
 5. ECC stack-specific testing rules (for example `typescript/testing.md`, `python/testing.md`)
 6. Current task `PLAN.md`
 

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

@@ -6,7 +6,7 @@ description: Use for /wf in Claude Code, $wf or /skills wf in Codex. WF is expli
 # WF Mode Adapter
 
 This skill is a thin tool adapter. The authoritative workflow lives in
-`Harness/WF.md`; do not duplicate or override it here.
+`Harness/specs/workflows/WF.md`; do not duplicate or override it here.
 
 ## Invocation
 
@@ -27,14 +27,22 @@ This skill is a thin tool adapter. The authoritative workflow lives in
 2. `Harness/MEMORY.md` (index only per Memory Preflight)
 3. `Harness/README.md`
 4. `Harness/PROGRESS.md`
-5. `Harness/WF.md`
-6. `Harness/subagents.md` before any role split
+5. `Harness/specs/workflows/WF.md`
+6. `Harness/specs/runtime/subagents.md` before any role split
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+listed loads in order, load only routed skills/tools, append task state and
+latest tool output after stable docs, and return compact evidence instead of
+logs or transcripts.
 
 ## Rules
 
-- Create or update a task capsule under `Harness/tasks/<task-id>/`.
+- Create or update a task capsule under `Harness/tasks/<task-id>/`; new task
+  ids MUST match `task-<verb>-<noun>[-detail]`.
 - Select the right WF tier: WF-Light (low-risk, planner/test/verifier), WF-Standard (multi-file, compact ACs, one review lens), WF-Full (high-risk/cross-layer, full role chain).
-- Run the WF loop from `Harness/WF.md`: intake, bounded exploration, second
+- Run the WF loop from `Harness/specs/workflows/WF.md`: intake, bounded exploration, second
   plan, implementation, review, verification, recovery, and closeout.
 - **Tier-aware acceptance**:
   - **WF-Light**: planner + test-writer + implementer + verifier suffice. Verification passes = closeout. Cross-review and reflector are NOT mandatory unless risk triggers them.

package/templates/common/.claude/skills/wf-agents-docs/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: wf-agents-docs
+description: Source-backed CLI invocation guide for Claude Code, Codex, and OpenCode automation. Use when invoking peer CLIs, writing batch tests, collecting cache telemetry, debugging command-line flags, or documenting cross-runtime agent usage for Harness workflows.
+---
+
+# WF Agents Docs
+
+Use this skill before shelling out to `claude`, `codex`, or `opencode` from Harness workflows, peer review, cache tests, or automation scripts.
+
+## Source Order
+
+1. Prefer installed help: `claude --help`, `codex exec --help`, `opencode run --help`.
+2. Check official docs for flags that affect cost, auth, JSON, resume, tools/MCP, or telemetry.
+3. When adding automation, record command, source, stdout/stderr shape, and failed patterns.
+
+## Claude Code CLI
+
+- Interactive: `claude`.
+- Non-interactive JSON: pipe ASCII or UTF-8-safe stdin into `claude -p --output-format json`.
+- Stream JSON requires verbose mode: `claude -p --output-format stream-json --verbose`.
+- Continue/resume: `claude -c -p "..."` or `claude -p --resume <session-id> "..."`; for PowerShell automation, prefer stdin and validate non-empty JSON before parsing.
+- Use `--max-budget-usd <amount>` in scripted probes.
+- Use `--strict-mcp-config` without `--mcp-config` to ignore configured MCP servers for a run. Use `--safe-mode` only to disable project customizations. Use `--bare` only for minimal CLI probes, not for Harness/cache attribution, because it skips `CLAUDE.md`, skills, plugins, MCP, hooks, and auto memory.
+- Use `--tools "Read,Grep,Glob"` or explicit `--allowedTools`/`--disallowedTools` for read-only probes.
+- Prompt-cache telemetry appears in JSON `usage.cache_read_input_tokens` / `usage.cache_creation_input_tokens`, and in statusline `context_window.current_usage.*`.
+
+## Codex CLI
+
+- Interactive: `codex`.
+- Non-interactive: `codex exec "task"`.
+- Read stdin as the full prompt: `cat prompt.txt | codex exec -`.
+- Prompt plus stdin context: `some-command | codex exec "summarize this output"`.
+- Machine output: `codex exec --json "task"` emits JSONL events; parse `turn.completed.usage`, including `cached_input_tokens` when present.
+- Resume: `codex exec resume --last "..."` or `codex exec resume <SESSION_ID> "..."`.
+- Permissions: default is read-only; set `--sandbox workspace-write` only when edits are required. Use `--ignore-user-config` / `--ignore-rules` for controlled automation.
+
+## OpenCode CLI
+
+- Interactive: `opencode`.
+- Non-interactive: `opencode run [message..]`.
+- JSON events: `opencode run --format json "task"`.
+- Resume: `opencode run --continue "..."` or `opencode run --session <id> "..."`.
+- Peer role: `opencode run --agent reviewer --dir . "review prompt"`.
+- Reuse a server to avoid MCP cold boot: `opencode serve`, then `opencode run --attach http://localhost:4096 "task"`.
+- On Windows, first verify `opencode` exists before writing automation around it.
+
+## PowerShell Automation Rules
+
+- Prefer stdin over trailing prompt args for `claude -p` in PowerShell.
+- Use ASCII prompts or explicitly UTF-8-safe input for automated probes.
+- Do not trust exit code alone. Fail on empty/non-JSON stdout or error/budget terminal fields.
+- Avoid naming function parameters `$Args`; PowerShell treats `$Args` specially.
+- Store telemetry outside the repo, e.g. `$HOME/.claude/cache-telemetry/*.json`, so git status does not perturb prefixes.
+
+## Evidence-Packet Review Pattern
+
+For peer review, route smokes, cache analysis, and audits, gather evidence
+first; the peer judges only the bounded packet.
+
+- Gather paths, line snippets, command names, exits, and invariants with `rg`,
+  `node` scripts, validators, or small reads.
+- Send only that packet. Exclude full docs, raw logs, timestamps, session IDs,
+  and screenshots unless they are the evidence.
+- Prefer no tools for judgment-only review; otherwise allow only read-only
+  tools and name the exact read set.
+- Controller accepts, rejects, or escalates findings. Peers do not own scope.
+
+## No Scratch-File Rule
+
+- Do not write CLI probe output under `%TEMP%`, `$env:TEMP`, `/tmp`, or other
+  system temp directories.
+- Prefer stdout, JSON/JSONL streaming, or in-memory parsing.
+- Persistent repo evidence goes under `Harness/tasks/<task-id>/evidence/`.
+- Cache telemetry may live under `$HOME/.claude/cache-telemetry/` to avoid repo
+  prompt-cache churn.
+- Do not create prompt temp files. Use stdin.
+
+## Subagent Output Contract
+
+Require bounded structured returns:
+
+```text
+Agent: <claude|codex|opencode|role name>
+Probe: <what was tested or reviewed>
+Mode: <read-only|review|telemetry|implementation>
+Files examined: <exact paths or none>
+Evidence: <commands, exit codes, paths, line refs>
+Passes: <confirmed invariants>
+Findings: <severity, file/path, reason, suggested fix>
+Risks: <residual uncertainty or none>
+Tool/CLI issues: <auth, timeout, budget, JSON parse, MCP, or none>
+Verdict: PASS | FAIL | BLOCKED
+Next: <smallest next controller action>
+```
+
+For JSON, use the same keys. Do not return transcripts, full file bodies, decorative logs, or speculation.
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: stable instructions first, volatile output in the dynamic suffix, and no provider cache claims without telemetry. Claude Code L2 uses `cache_read_input_tokens`; Codex JSONL may emit `cached_input_tokens`.
+
+## Batch-Test Pattern
+
+1. Probe command availability with `Get-Command claude,codex,opencode -ErrorAction SilentlyContinue`.
+2. Build a compact evidence packet before invoking peer agents; use the peer
+   only for judgment unless the test explicitly requires live agent discovery.
+3. Run a cold turn and capture session id.
+4. Resume that session for two warm turns.
+5. For each turn record input, cache creation, cache read, ratio, cost, model/session id, and exact flags.
+6. Compare against a control mode. Do not attribute a provider-wide cache feature to Harness unless the Harness-shaped run improves or stabilizes cache behavior against a comparable baseline.
+
+## Official References
+
+- Claude Code CLI reference: https://code.claude.com/docs/en/cli-reference
+- Claude Code prompt caching: https://code.claude.com/docs/en/prompt-caching
+- Claude Code status line schema: https://code.claude.com/docs/en/statusline
+- Codex CLI: https://developers.openai.com/codex/cli
+- Codex non-interactive mode: https://learn.chatgpt.com/docs/non-interactive-mode
+- OpenCode CLI: https://opencode.ai/docs/cli/

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

@@ -5,15 +5,32 @@ description: Perpetual adaptive auto-optimization mode. Selects probes from proj
 
 # WF Auto - Perpetual Auto-Optimization
 
+## Memory Preflight
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` index only, then `Harness/README.md`
+   before planning, dispatch, edits, validation, or review.
+2. Load detailed `Harness/memory/*` files only when `MEMORY_PROTOCOL.md`
+   scenario hints match; otherwise record "memory hints: none".
+
 ## Load
 
-- `Harness/WF-AUTO.md`
-- `Harness/WF-AUTO-ANGLES.md`
-- `Harness/subagents.md`
-- `Harness/dispatch.md`
-- `Harness/agent-workflow.md`
+- `CLAUDE.md`
+- `Harness/MEMORY.md` (index only per Memory Preflight)
+- `Harness/README.md`
+- `Harness/specs/workflows/WF-AUTO.md`
+- `Harness/specs/workflows/WF-AUTO-ANGLES.md`
+- `Harness/specs/runtime/subagents.md`
+- `Harness/specs/runtime/dispatch.md`
+- `Harness/specs/runtime/agent-workflow.md`
 - `.claude/skills/wf-review/SKILL.md`
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+auto-mode docs in listed order, run selected probes only, append fresh probe
+outputs last, and record compact evidence instead of carrying full logs between
+cycles.
+
 ## Trigger
 
 - Claude `/wf-auto`
@@ -44,6 +61,9 @@ that auto scanning costs more than it helps.
    below 3.
 8. Intent Checkpoint is adaptive: 2 -> 5 -> 10 cycles, exactly two questions.
 9. Record compact evidence per cycle; do not paste full logs or transcripts.
+10. A bounded test tick still creates or updates `Harness/tasks/auto/PLAN.md`
+    and `Harness/tasks/auto/PROGRESS.md`; missing auto capsule evidence is a
+    failed cycle record.
 
 ## Loop
 
@@ -58,5 +78,5 @@ LOOP: next W0
 
 ## Return
 
-Report cycles run, findings addressed by source, evidence ledger, exhaustion
-evidence if any, weak spark count, final state, and residual risks.
+Report cycles run, findings addressed by source, evidence ledger path/summary,
+exhaustion evidence if any, weak spark count, final state, and residual risks.

package/templates/common/.claude/skills/wf-auto-spark/SKILL.md

@@ -5,7 +5,7 @@ description: Perpetual inspiration mode for /wf-auto-spark or $wf-auto-spark. In
 
 # WF-AUTO-SPARK Adapter
 
-The authoritative workflow lives in `Harness/WF-AUTO-SPARK.md`; this adapter
+The authoritative workflow lives in `Harness/specs/workflows/WF-AUTO-SPARK.md`; this adapter
 only routes and summarizes hard constraints.
 
 ## Invocation
@@ -18,10 +18,17 @@ only routes and summarizes hard constraints.
 1. `CLAUDE.md`
 2. `Harness/MEMORY.md`
 3. `Harness/README.md`
-4. `Harness/WF-AUTO-SPARK.md`
-5. `Harness/WF-AUTO.md`
-6. `Harness/subagents.md`
-7. `Harness/dispatch.md`
+4. `Harness/specs/workflows/WF-AUTO-SPARK.md`
+5. `Harness/specs/workflows/WF-AUTO.md`
+6. `Harness/specs/runtime/subagents.md`
+7. `Harness/specs/runtime/dispatch.md`
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep roadmap
+and workflow docs stable, put fresh spark search results in the dynamic suffix,
+defer unused tools/skills, and let task-scribe write compact state instead of
+replaying search transcripts.
 
 ## Rules
 

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

@@ -0,0 +1,176 @@
+---
+name: wf-browser
+description: Built-in browser automation and E2E verification workflow. Use for Claude /wf-browser, Codex $wf-browser or /skills wf-browser, Browser Use, Playwright, Chrome DevTools/CDP, screenshots, forms, UI verification, and browser-visible acceptance.
+---
+
+# WF Browser
+
+This skill is the single Browser E2E entry. Do not use or create a separate
+browser E2E skill. The browser evidence contract lives here plus
+`Harness/specs/protocols/HARNESS_BRIDGE.md`.
+
+## Invocation
+
+- Claude Code: use `/wf-browser <task>` or select the `wf-browser` skill.
+- Codex CLI or IDE: use `$wf-browser <task>` or `/skills` then choose `wf-browser`.
+- OpenCode: use `/wf-browser <task>`.
+
+## Load
+
+- `CLAUDE.md`
+- `Harness/MEMORY.md` index only per Memory Preflight
+- `Harness/README.md`
+- `Harness/specs/protocols/HARNESS_BRIDGE.md`
+- Project run/build/test instructions
+- Official Browser Use skill text from `browser-use skill` when Browser Use is used
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep stable
+workflow docs first, then append only the current URL, selectors, concise browser
+state, screenshot paths, trace paths, and failing assertions. Do not paste full
+accessibility trees, browser logs, screenshots, videos, or network dumps into
+task state.
+
+## Browser Evidence Contract
+
+Every browser-visible claim needs real browser evidence:
+
+1. URL and viewport/browser scope.
+2. Stable selector contract using `data-testid` and accessible labels/roles.
+3. Real interaction evidence from Browser Use, Playwright, Chrome DevTools/CDP,
+   or documented manual browser checks.
+4. Console and network checks for runtime exceptions, failed requests, and
+   frontend-backend side effects.
+5. Screenshot, trace, video, state snapshot, or command output path.
+6. AC-by-AC validation matrix when acceptance criteria exist.
+
+No `data-testid` or stable accessible selector, no UI acceptance. No API
+contract, no backend integration acceptance.
+
+## Controllable UI Contract
+
+UI built for browser control must expose targetable, user-meaningful controls:
+
+| Category | Required control surface |
+| --- | --- |
+| Inputs | `<label>` association or `aria-label`, `data-testid`, disabled/invalid states, deterministic placeholder only as fallback |
+| Buttons | accessible name, `data-testid`, disabled/loading state, no icon-only button without `aria-label` |
+| Filters | stable test id for input/menu/chip, selected state, clear/reset control |
+| Rows/items | stable row/item test id plus durable item key such as `data-row-id`; avoid index-only targeting |
+| Empty state | visible empty container with `data-testid="empty-state"` or feature-specific equivalent |
+| Error state | inline error/toast/banner with stable test id and accessible role when appropriate |
+| Loading state | stable spinner/skeleton/progress test id; verify duplicate submit prevention |
+
+Required coverage targets: inputs, buttons, filters, rows, empty/error/loading states.
+
+Selector priority:
+
+1. `data-testid`
+2. accessible labels/roles
+3. visible text for stable user-facing copy
+
+Do not use generated class names, brittle CSS chains, XPath, DOM index selectors,
+or raw coordinates as the primary test contract. Coordinates are acceptable only
+after locating an element through the accessibility tree or when testing canvas
+or other non-DOM UI.
+
+## Browser Use CLI
+
+Use the current script-style Browser Use CLI; old `browser-use open/state/click/screenshot/input/wait` subcommands are removed from the current CLI and must not be used in new docs or tests.
+
+Health check:
+
+```bash
+browser-use --doctor
+browser-use skill
+```
+
+PowerShell smoke:
+
+```powershell
+@'
+new_tab("https://example.com")
+wait_for_load()
+print(page_info())
+path = capture_screenshot("Harness/tasks/<task-id>/evidence/example.png")
+print(path)
+'@ | browser-use
+```
+
+Bash smoke:
+
+```bash
+browser-use <<'PY'
+new_tab("https://example.com")
+wait_for_load()
+print(page_info())
+path = capture_screenshot("Harness/tasks/<task-id>/evidence/example.png")
+print(path)
+PY
+```
+
+Useful helpers include `new_tab(url)`, `goto_url(url)`, `page_info()`,
+`capture_screenshot(path)`, `click_at_xy(x, y)`, `type_text(text)`,
+`fill_input(selector, text)`, `press_key(key)`, `scroll(x, y)`, `js(code)`,
+`cdp(method, ...)`, `wait_for_load()`, `wait_for_element(selector)`,
+`list_tabs()`, `switch_tab(target)`, and `close_tab(target)`.
+
+For local Chrome connection problems, run `browser-use --doctor`. If Chrome asks
+to allow remote debugging, stop and ask the user to approve the browser prompt.
+
+## Playwright Test Pattern
+
+Prefer Playwright for repeatable E2E tests and Browser Use/CDP for exploratory
+or interactive checks.
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test("AC-001 user can submit the form", async ({ page }) => {
+  const requests: Array<{ url: string; method: string; postData: string | null }> = [];
+  page.on("request", request => {
+    requests.push({
+      url: request.url(),
+      method: request.method(),
+      postData: request.postData(),
+    });
+  });
+
+  await page.goto("/example");
+  await page.getByTestId("email-input").fill("test@example.com");
+  await page.getByRole("button", { name: "Submit" }).click();
+
+  await expect(page.getByTestId("loading-spinner")).toBeHidden();
+  await expect(page.getByTestId("result-row")).toBeVisible();
+  expect(requests.some(request => request.url.includes("/api/example"))).toBe(true);
+});
+```
+
+## Chrome DevTools / CDP Checklist
+
+- [ ] Record URL, port, browser, and viewport.
+- [ ] Verify available Browser Use, Playwright, CDP, MCP, or manual tooling.
+- [ ] Check not just HTTP 200.
+- [ ] Verify no runtime exceptions, console errors, and failed network requests.
+- [ ] Confirm stable accessible labels/roles or `data-testid` on interactive elements.
+- [ ] Test the critical flow end-to-end with real user actions.
+- [ ] Capture screenshot, trace, video, state snapshot, or result artifact paths.
+- [ ] Produce an AC-by-AC validation matrix.
+- [ ] Clean up dev server or browser processes that the task started.
+
+## Security
+
+- Never log or screenshot real credentials, API keys, tokens, or private data.
+- Use placeholder credentials in examples.
+- Ask before using a real Chrome profile because it contains cookies and private sessions.
+- Ask before leaving a remote/cloud browser running.
+- For scraping or repeated automated visits, confirm the user owns the target or has permission.
+
+## Return
+
+- Commands or scripts run
+- Selectors used
+- Screenshot/trace/video/state paths
+- Verified flows and AC matrix
+- Failures and remaining risks

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

@@ -0,0 +1,30 @@
+---
+name: wf-help
+description: Codex compatibility: use $wf-help or /skills wf-help in Codex to show the Harness WF command table. Claude Code and OpenCode use the direct /wf-help command.
+---
+
+# WF Help Adapter
+
+This skill is a Codex compatibility shim. It does not start WF mode, dispatch
+agents, or edit files.
+
+## Invocation
+
+- Codex CLI or IDE: use `$wf-help` or `/skills` then choose `wf-help`.
+- Claude Code: use `/wf-help` direct command from `.claude/commands/wf-help.md`.
+- OpenCode: use `/wf-help` direct command from `.opencode/commands/wf-help.md`.
+
+## Load
+
+- `.claude/commands/wf-help.md`
+
+## Rules
+
+Return the command table from `.claude/commands/wf-help.md` directly.
+Do not load `Harness/MEMORY.md`, do not enter WF, and do not invoke workflow
+skills while answering help.
+
+## Return
+
+- WF command table
+- One short note that Codex uses `$wf-*` or `/skills wf-*` for skill-backed entries

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

@@ -22,6 +22,12 @@ fallback.
 - `Harness/memory/agent-lessons-patterns.md`
 - Current `Harness/PROGRESS.md` and active task capsule, if any
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: load memory
+indexes first, then only the routed detailed memory files; summarize durable
+patterns by file path and signal instead of pasting session transcripts.
+
 ## Flow
 
 1. Analyze the session for repeated failures, durable user corrections, and

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

@@ -5,7 +5,7 @@ description: Use for /wf-max in Claude Code, $wf-max or /skills wf-max in Codex.
 
 # WF-MAX Adapter
 
-The authoritative workflow lives in `Harness/WF-MAX.md`; this adapter only
+The authoritative workflow lives in `Harness/specs/workflows/WF-MAX.md`; this adapter only
 routes and summarizes hard constraints.
 
 ## Invocation
@@ -24,35 +24,50 @@ routes and summarizes hard constraints.
 1. `CLAUDE.md`
 2. `Harness/MEMORY.md` (index only per Memory Preflight)
 3. `Harness/README.md`
-4. `Harness/WF-MAX.md`
-5. `Harness/subagents.md`
-6. `Harness/dispatch.md`
-7. `Harness/agent-workflow.md`
+4. `Harness/specs/workflows/WF-MAX.md`
+5. `Harness/specs/runtime/subagents.md`
+6. `Harness/specs/runtime/dispatch.md`
+7. `Harness/specs/runtime/agent-workflow.md`
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+listed loads in order, defer unused skill/tool schemas, append volatile task
+state and runtime facts last, and bound Worker returns through dispatch
+`MaxReturnTokens`/`ReturnSchema`.
 
 ## Rules
 
 WF-MAX inherits the selected WF tier and the shared WF-KERNEL gates
-(`Harness/WF-KERNEL.md`), then expands safe parallelism. WF-Max-Useful is
+(`Harness/specs/workflows/WF-KERNEL.md`), then expands safe parallelism. WF-Max-Useful is
 default; WF-Max-Strict only on explicit strict request. Execution expands
 through:
 
+- New task state directories MUST use task ids matching
+  `task-<verb>-<noun>[-detail]` under `Harness/tasks/<task-id>/`; never
+  create bare `fix-*` task ids.
 1. Global mode: `wf-max`
 2. Agent role: `ceo | manager | worker | reviewer | verifier | reflector`
 3. Dispatch permission: `writeSet`, `forbidden`, `verification`
 
 WF-Max-Useful (default): `/wf-max` fans out only where write sets or review
 lenses are meaningfully independent. Overhead > 0.30 degrades the wave.
+Degrading fan-out does not authorize CEO source edits; source implementation
+still goes through an implementer/Worker role, or the run records an honest
+downgrade before editing.
 
 WF-Max-Strict (explicit override): user says `--strict`, `strict wf-max`, or
 `strict mode`. Unconditional fan-out per the original span formula.
 
 - CEO reads, plans, dispatches, synthesizes, and writes task state only. CEO
   never edits production source.
+- Task-state updates must preserve required `Harness/PROGRESS.md` headings:
+  `## Active Task`, `## Task Index`, and `## Cross-Task Decisions`.
 - Workers edit only the dispatch `writeSet`; outside write set is blocked.
 - Managers coordinate and synthesize. Reviewers read/report only.
 - D-GATE is mandatory before implementation waves: dispatch table, AC IDs,
   disjoint file claims, self-audit, and reviewer plan.
-- Final acceptance is tier-aware per `Harness/WF-KERNEL.md`:
+- Final acceptance is tier-aware per `Harness/specs/workflows/WF-KERNEL.md`:
   - WF-Light + `/wf-max`: verification + state evidence suffices unless risk
     triggers review/reflector.
   - WF-Standard + `/wf-max`: verifier evidence + one independent review PASS.
@@ -60,16 +75,30 @@ WF-Max-Strict (explicit override): user says `--strict`, `strict wf-max`, or
 
 ## Fan-Out Discipline
 
+- MUST attempt native subagent fan-out before implementation planning is
+  considered complete. A solo controller path is allowed only after recording
+  `fanoutAttempted: true`, the runtime, channel tried, agents requested,
+  limit/cap facts, failure reason, and fallback path in task state.
 - Use as many useful subagents as the runtime safely allows.
-- Codex capacity may be configured through official `agents.max_threads` and
-  `agents.max_depth`; generated Harness config defaults to
-  `.codex/config.toml` with `max_threads = 12` and `max_depth = 1`.
+- Claude Code documents session, concurrent, and spawn-depth subagent caps:
+  `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and
+  `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`; Harness still enforces its lower
+  WF-MAX caps unless the user explicitly approves a task-local override.
+- Codex capacity is configured through official
+  `agents.max_concurrent_threads_per_session`; `agents.max_threads` is a
+  legacy alias. Do not scaffold scalar `[agents]` caps into
+  `.codex/config.toml`; codex-cli 0.144.x can reject them during TUI
+  `skills/list`. Treat Codex capacity as a runtime probe and manage Harness
+  caps in the dispatch ledger unless the installed Codex version is verified
+  with `codex --strict-config doctor`.
+- OpenCode uses `subagent_depth` for nesting. WF-MAX manager -> worker fan-out
+  requires `subagent_depth >= 2` plus manager `permission.task` allowlists; the
+  scaffold sets `subagent_depth = 2`.
 - Close completed agents before declaring the pool exhausted.
 - If Codex remains bottlenecked, ask the user before raising
-  `agents.max_threads` above the scaffold default. Do not silently edit project
-  or global Codex config.
-- Keep `agents.max_depth = 1` unless the user explicitly approves recursive
-  delegation.
+  `agents.max_concurrent_threads_per_session`. Do not silently edit project or
+  global Codex config.
 - If the current runtime is exhausted, overflow to a peer CLI with explicit
   dispatch packets: `claude -p`, `codex exec`, or
   `opencode run --agent <role> --dir .`.

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

@@ -14,7 +14,13 @@ Improve `README.md` without breaking project-owned public docs.
 - CI files when present
 - `Harness/PROGRESS.md`
 - `Harness/tasks/<task-id>/PLAN.md` when available
-- `Harness/architecture.md` only when an architecture summary or diagram is requested
+- `Harness/project/architecture.md` only when an architecture summary or diagram is requested
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: load project
+facts in the listed order, inspect only relevant README/package/CI sections, and
+keep unknowns or command output in the dynamic suffix.
 
 ## Mode
 
@@ -34,7 +40,7 @@ If unanswered, use Preserve + append.
 - Do not invent features, benchmarks, roadmap, support policy, badges, install commands, or CI status.
 - Use tables for command matrices, environment variables, endpoints, and deployment notes when facts are known.
 - Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
-- Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
+- Keep detailed architecture in `Harness/project/architecture.md`; README may link to it or show a short overview.
 - Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
 - Record the chosen mode and any skipped README improvements in `Harness/tasks/<task-id>/PLAN.md` when available.
 

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

@@ -18,6 +18,12 @@ description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove
 - `Harness/.harness-version`
 - `Harness/scripts/wf-remove.mjs`
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: use the
+script's compact JSON plan as the dynamic suffix, avoid manual directory dumps,
+and keep user decisions in task progress rather than chat transcript.
+
 ## Flow
 
 1. On plain `/wf-remove`, run `node Harness/scripts/wf-remove.mjs --json` for

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

@@ -22,6 +22,13 @@ The main agent is the controller. It owns final decisions, accepted/rejected
 findings, fixes, release claims, and user-facing recommendations. Review
 agents only provide evidence-backed suggestions.
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: build review
+context from changed-file lists, ACs, validation evidence, and targeted diffs;
+avoid pasting unrelated history, full transcripts, or unused tool schemas into
+the review prompt.
+
 ## Runtime Selection
 
 1. Build one review prompt containing the relevant diff, task acceptance
@@ -66,8 +73,8 @@ AgentName: reviewer
 Mode: read-only
 Objective: review the current diff for correctness, security, architecture,
 performance, tests, and spec/AC compliance
-Read set: changed files, tests, task PLAN/PROGRESS, Harness/agent-workflow.md,
-Harness/subagents.md, Harness/dispatch.md, architecture docs when affected
+Read set: changed files, tests, task PLAN/PROGRESS, Harness/specs/runtime/agent-workflow.md,
+Harness/specs/runtime/subagents.md, Harness/specs/runtime/dispatch.md, architecture docs when affected
 Write set: none
 Forbidden: file edits, git mutations, formatting-only advice, ungrounded claims
 ReturnSchema: findings by severity, file/line refs, missing verification,
@@ -80,6 +87,6 @@ deduplicate reviewer output and decide what to accept.
 
 ## Context
 
-Include the relevant diff, `Harness/architecture.md` when architecture is in
+Include the relevant diff, `Harness/project/architecture.md` when architecture is in
 scope, and any task acceptance criteria. If the diff is too large, ask for a
 narrower scope before invoking a peer CLI or reviewer subagent.