create-harness-vibe-coding 0.8.13 → 0.8.16

package/src/index.js

@@ -294,9 +294,9 @@ function printResult(result, targetDir) {
     console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
     console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
     console.log(`  ${pc.cyan('opencode')}                        # Or start OpenCode`);
-    console.log(`  Tell your agent: "${pc.yellow('Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
+    console.log(`  Tell your agent: "${pc.yellow('Read Harness/specs/guides/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
     console.log('');
-    console.log(pc.dim('  Harness/SETUP.md is temporary. Delete it after initialization.'));
+    console.log(pc.dim('  Keep Harness/specs/guides/SETUP.md as a setup reference; normal sessions start at CLAUDE.md, with Harness/README.md as the routed workflow router.'));
     console.log('');
 
   } else {
@@ -742,7 +742,7 @@ function createAgentGuidance(result, { projectName, targetDir, options, scan })
   } else if (result.success) {
     next.push({
       action: 'bootstrap',
-      command: 'Read Harness/SETUP.md and use this JSON plan before opening any package templates.',
+      command: 'Read Harness/specs/guides/SETUP.md and use this JSON plan before opening any package templates.',
       reason: 'Scaffold files were written; bootstrap project facts from local evidence.',
     });
   } else {
@@ -820,7 +820,7 @@ function createFileGuidance(file) {
 }
 
 function templateHintFor(file) {
-  if (file === 'Harness/SETUP.md') return 'templates/common/SETUP.md';
+  if (file === 'Harness/specs/guides/SETUP.md') return 'templates/common/Harness/specs/guides/SETUP.md';
   return `templates/common/${file}`;
 }
 

package/templates/common/.claude/agents/architect-manager.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: architect-manager
 description: WF-MAX Manager for W1 architecture wave. Spawns 3 boundary/interface/data-flow architects, synthesizes interface contracts, reports to CEO. Read-only + Agent spawn; no Edit/Write.
 tools: Read, Grep, Glob, Agent, Bash(git *), Bash(ls *), Bash(dir *)

package/templates/common/.claude/agents/architect.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: architect
 description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
 tools: Read, Grep, Glob
@@ -11,7 +12,7 @@ You are an architecture review agent for this project harness.
 
 Load first:
 
-- `Harness/architecture.md`
+- `Harness/project/architecture.md`
 - current PRD or feature doc
 
 Rules:

package/templates/common/.claude/agents/codebase-explorer.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: codebase-explorer
 description: Use for scoped read-only source exploration, file discovery, symbol tracing, and simple codebase summaries before planning or implementation.
 tools: Read, Grep, Glob, Bash(rg *), Bash(git grep *), Bash(git ls-files *)

package/templates/common/.claude/agents/context-master.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: context-master
 description: Use when context exceeds ~85% of the window, or during WF closeout to extract durable knowledge before compression. Read-only analysis except for writing compression suggestions to PROGRESS.md#Heartbeat.
 tools: Read, Grep, Glob, Write
@@ -12,7 +13,7 @@ You are a context analysis agent. You analyze the current conversation and proje
 Load first:
 
 - `Harness/MEMORY.md`
-- `Harness/MEMORY_PROTOCOL.md`
+- `Harness/specs/protocols/MEMORY_PROTOCOL.md`
 - `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 - The current feature doc (if one exists)
 - `Harness/memory/` files for dedup checking

package/templates/common/.claude/agents/debugger.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: debugger
 description: Use to isolate a failing command, reproduce the smallest failing path, and propose the narrowest fix.
 tools: Read, Grep, Glob, Bash, Write, Edit, MultiEdit

package/templates/common/.claude/agents/docs-researcher.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: docs-researcher
 description: Use to verify official documentation, APIs, SDK behavior, config options, version changes, limits, error semantics, and examples before implementation.
 tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
@@ -12,7 +13,7 @@ You are a documentation verification agent for this project harness.
 Load first:
 
 - `Harness/research/README.md`
-- `Harness/architecture.md` when boundaries may change
+- `Harness/project/architecture.md` when boundaries may change
 - `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
 
 Inputs you must receive:

package/templates/common/.claude/agents/explore-manager.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: explore-manager
 description: WF-MAX Manager for W0 exploration wave. Spawns 5-10 read-only researchers/explorers, synthesizes findings, reports to CEO. Read-only + Agent spawn; no Edit/Write.
 tools: Read, Grep, Glob, Agent, Bash(git *), Bash(ls *), Bash(dir *), Bash(tree *)

package/templates/common/.claude/agents/implement-manager.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: implement-manager
 description: WF-MAX Manager for W2 implementation wave. Spawns 5-7 implementers (one file_claim each), merges results, reports to CEO. Agent spawn + synthesis only; does NOT write code directly.
 tools: Read, Grep, Glob, Agent, Bash(git *), Bash(node *), Bash(npm *)

package/templates/common/.claude/agents/implementer.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: implementer
 description: Use to implement the smallest change inside a declared write set after tests or manual checks are defined.
 tools: Read, Grep, Glob, Write, Edit, MultiEdit, Bash

package/templates/common/.claude/agents/memory-master.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: memory-master
 description: Use when a repeated failure, user correction, or WF recovery loop triggers memory writing; also use during WF closeout for consolidation. Writes to Harness/memory/*, Harness/MEMORY.md, and cross-project global memory.
 tools: Read, Grep, Glob, Write, Edit
@@ -12,7 +13,7 @@ You are a memory management agent for this project harness. You own durable memo
 Load first:
 
 - `Harness/MEMORY.md`
-- `Harness/MEMORY_PROTOCOL.md`
+- `Harness/specs/protocols/MEMORY_PROTOCOL.md`
 - `Harness/memory/tool-usage-reflections.md`
 - `Harness/memory/user-corrections-preferences.md`
 - `Harness/memory/agent-lessons-patterns.md`

package/templates/common/.claude/agents/planner.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: planner
 description: Use to split a goal into tasks, dependencies, write sets, verification steps, and a Parallel Dispatch table before multi-step work.
 tools: Read, Grep, Glob
@@ -12,8 +13,8 @@ You are a planning agent for this project harness.
 Load first:
 
 - `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
-- `Harness/lifecycle.md`
-- `Harness/dispatch.md`
+- `Harness/specs/guides/lifecycle.md`
+- `Harness/specs/runtime/dispatch.md`
 - current PRD or feature doc if present
 
 Rules:

package/templates/common/.claude/agents/reflector.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: reflector
 description: Use after verification and cross-review to synthesize findings, detect unresolved risk, and decide whether work may enter final acceptance.
 tools: Read, Grep, Glob

package/templates/common/.claude/agents/researcher.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: researcher
 description: Use for product, market, competitor, open-source, dependency, pricing, policy, or ecosystem research before PRD and architecture decisions.
 tools: Read, Grep, Glob, WebSearch, WebFetch, Bash

package/templates/common/.claude/agents/review-manager.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: review-manager
 description: WF-MAX Manager for W2R review wave. Spawns 3-4 parallel reviewers (spec/code/security/perf), deduplicates findings, assigns severity, reports to CEO. Read-only + Agent spawn; no Edit/Write.
 tools: Read, Grep, Glob, Agent, Bash(git *), Bash(git diff *), Bash(node *)

package/templates/common/.claude/agents/reviewer.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: reviewer
 description: Use for read-only review of diffs, tests, architecture boundaries, regressions, and missing verification before closeout.
 tools: Read, Grep, Glob, Bash
@@ -13,7 +14,7 @@ Load first:
 
 - diff or changed file list
 - current PRD or feature doc
-- `Harness/agent-workflow.md`
+- `Harness/specs/runtime/agent-workflow.md`
 - architecture docs when affected
 
 Rules:

package/templates/common/.claude/agents/task-scribe.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: task-scribe
 description: Use to maintain Harness task state, heartbeat, dispatch ledger, evidence pointers, and compact PLAN/PROGRESS updates. Small-fast chore agent. Never edits source code.
 tools: Read, Grep, Glob, Write, Edit

package/templates/common/.claude/agents/tdd-guide.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: tdd-guide
 description: Test-Driven Development specialist enforcing AC-linked write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, refactoring code, or adding browser-visible behavior.
 tools: Read, Write, Edit, Bash, Grep, Glob
@@ -9,10 +10,10 @@ model: sonnet
 
 Enforces acceptance-driven TDD. Load these before writing tests:
 
-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 testing rules for the project stack
 6. Current task `PLAN.md`
 

package/templates/common/.claude/agents/test-writer.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: test-writer
 description: Use to define or write AC-linked failing tests and manual verification steps before implementation.
 tools: Read, Grep, Glob, Write, Edit, MultiEdit, Bash
@@ -12,12 +13,12 @@ You are a test-first agent for this project harness. You write tests from PRD-de
 Load first:
 
 - current PRD or feature doc
-- `Harness/ACCEPTANCE_PROTOCOL.md`
-- `Harness/HARNESS_BRIDGE.md` for UI/API/browser flows
-- `Harness/AGENT_ISOLATION.md`
-- `Harness/TDD-GUIDE.md`
+- `Harness/specs/protocols/ACCEPTANCE_PROTOCOL.md`
+- `Harness/specs/protocols/HARNESS_BRIDGE.md` for UI/API/browser flows
+- `Harness/specs/protocols/AGENT_ISOLATION.md`
+- `Harness/specs/protocols/TDD-GUIDE.md`
 - `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when available
-- `Harness/agent-workflow.md`
+- `Harness/specs/runtime/agent-workflow.md`
 
 Inputs you must receive:
 

package/templates/common/.claude/agents/verifier.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 name: verifier
 description: Use to run verification commands, inspect results, and record evidence. Final acceptance still waits for cross-review PASS and reflector PASS.
 tools: Read, Grep, Glob, Bash

package/templates/common/.claude/commands/wf-help.md

@@ -12,6 +12,7 @@ do not dispatch agents, and do not edit files.
 | `/wf-auto-spark` | workflow skill | `/wf-auto-spark` | Perpetual inspiration mode with roadmap anchoring and external spark search. |
 | `/wf-review <focus>` | workflow skill | `/wf-review security and test coverage` | Peer CLI review through Claude/Codex/OpenCode, with reviewer subagent fallback. |
 | `/wf-learn` | workflow skill | `/wf-learn` | Force context-master -> memory-master learning cycle after repeated failures or closeout. |
+| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence when installed. |
 | `/wf-readme <task>` | workflow skill | `/wf-readme polish quickstart` | Preserve, merge, or improve README docs without trampling existing project documentation. |
 | `/wf-update` | direct command | `/wf-update` | Check/apply Harness scaffold updates with safe file classification and conflict handling. |
 | `/wf-remove` | workflow skill | `/wf-remove` | Safely remove Harness files while preserving project/user data unless explicitly purged. |

package/templates/common/.claude/commands/wf-update.md

@@ -2,29 +2,87 @@
 
 Run the Harness update checker script. Do not invoke a skill or start WF mode.
 
+## Classification
+
+MANIFEST-FIRST. The installer and updater read `Harness/ownership.manifest.json`:
+
+- `preserve[]` - existing user data is never overwritten (tasks, memory, research, root README, package, architecture). Missing scaffold starter files may be created when no local user data exists. `Harness/tasks/**` is always preserved.
+- `merge[]` - CLAUDE.md, AGENTS.md, MEMORY.md, Harness/MEMORY.md, Harness/README.md -> merge or accept-local; prior accepted decisions carry forward.
+- `frameworkOwned[]` - safe overwrite-upgrade fast path (concurrent fetch + hash + all-or-nothing write after checksum validation).
+- `optionalOwned[]` - upgraded only when that option is installed.
+
+Content markers (`harness: wf-agent`, `project harness`, `Harness/...`) are the fallback when no manifest exists (old installs) and the instance-ownership signal that protects a user's same-name file at a Harness path. A same-name user file with no marker and no manifest declaration becomes conflict/skip + warning, never overwritten.
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep updater
+scripts and ownership docs stable, consume compact `--json` agent plans first,
+and avoid pasting verbose diffs or full remote files unless a conflict requires
+targeted inspection.
+
 ## Flow
 
-1. Run `node Harness/scripts/wf-update-check.mjs --json` and use the `agent` block as the action plan. Current updaters try npm `create-harness-vibe-coding@latest` first, then the canonical GitHub source `LiWeny16/create-harness-vibe-coding`, then the legacy compatibility mirror `zingspark/create-harness-vibe-coding`.
-2. Preserve all PRESERVE files. Never overwrite user task, memory, research, README, package, or architecture files.
-3. If `agent.safeApplyCommand` is present, run it to apply SAFE/NEW files first.
-4. For conflicts, compare local with `templateHint` or `remoteUrl`, decide merge/keep-local/overwrite, and record via `--accept-local`, `--accept-merged`, or `--accept-template`.
-5. Run `node Harness/scripts/wf-update-check.mjs --finalize` after all conflicts resolved.
-6. After update, run `node Harness/scripts/validate-harness.mjs` and `node Harness/scripts/scan-clean.mjs`.
+1. Run `node Harness/scripts/wf-update-check.mjs --json` first and use the
+   `agent` block as the action plan. Preserve `agent.releaseHighlights` for the
+   user-facing update summary. Current updaters try npm
+   `create-harness-vibe-coding@latest` first, then the canonical GitHub source
+   `LiWeny16/create-harness-vibe-coding`, then the legacy compatibility mirror
+   `zingspark/create-harness-vibe-coding`.
+2. Preserve all existing PRESERVE files. Never overwrite user task, memory,
+   research, root README.md, package, or architecture files. Missing scaffold
+   starter files may be created, and checksum-matching legacy architecture can
+   move to `Harness/project/architecture.md`. Harness/README.md is merge-tier,
+   not PRESERVE.
+3. If `agent.safeApplyCommand` is present, run it to apply SAFE, NEW, and
+   adopted metadata-only files before spending AI time on conflicts. Default
+   command: `node Harness/scripts/wf-update-check.mjs --apply-safe`.
+   Framework-owned templates, commands, skills, agents, and scripts are
+   script-owned and should be overwritten by the updater after checksum
+   validation.
+4. Previously accepted decisions for any merge-tier file (CLAUDE.md, AGENTS.md,
+   MEMORY.md, Harness/MEMORY.md, Harness/README.md) are carried forward
+   automatically when both the local hash and remote template hash are
+   unchanged.
+5. If a new agent/command/skill path collides with an existing file, do not
+   decide by filename alone. Treat it as Harness-owned only when the file
+   content has Harness/WF markers such as `harness: wf-agent`,
+   `project harness`, or `Harness/...`; otherwise leave it as a real conflict.
+6. For every remaining `agent.aiMergeRequired` entry, compare the local file
+   with `templateHint` or `remoteUrl`, then choose merge, keep-local, or
+   overwrite-from-template. Record the decision through the script with
+   `--accept-local <file>`, `--accept-merged <file>`, or
+   `--accept-template <file>`; do not hand-edit `Harness/.harness-version`.
+   Ask the user only when the intent is ambiguous.
+7. Run `node Harness/scripts/wf-update-check.mjs --finalize` after all
+   conflicts have script-recorded decisions. Use strict `--apply` only when the
+   JSON plan has zero conflicts.
+8. After update, run `node Harness/scripts/validate-harness.mjs` and then
+   `node Harness/scripts/scan-clean.mjs`.
 
-Codex users without a direct command surface: use `$wf-update` (skill path) or `node Harness/scripts/wf-update-check.mjs`.
+Codex users without a direct command surface: use `$wf-update` (skill path) or
+`node Harness/scripts/wf-update-check.mjs`.
 
 ## Recovery
 
-If the script reports `Harness/.harness-version not found` or the update checker script itself is missing (`Harness/scripts/wf-update-check.mjs`), the Harness install predates version-tracking. Recover by regenerating missing infrastructure without overwriting user files:
+If `Harness/scripts/wf-update-check.mjs` is missing (old install without updater), or `Harness/.harness-version` is missing or corrupted, do NOT reinstall from scratch. Recover by regenerating missing infrastructure:
 
 ```
 npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip
 ```
 
-This creates missing Harness files while preserving CLAUDE.md, README.md, tasks, memory, research, and all user data. After recovery, re-run the update check.
+The `--on-conflict skip` policy preserves all existing user files (CLAUDE.md, README.md, tasks, memory, research, architecture) and only creates missing Harness infrastructure files. After recovery, re-run the update check.
 
-If an old updater reports only `0.8.10`, run the latest installer command above or re-run the checker with:
+If an old updater reports only `0.8.10`, run the latest installer command above
+or re-run the checker with:
 
 ```
 node Harness/scripts/wf-update-check.mjs --json --source-base https://raw.githubusercontent.com/LiWeny16/create-harness-vibe-coding/main/templates/common/
 ```
+
+## Return
+
+Report version, SAFE/NEW updates, conflicts and decisions, preserved files,
+partialUpdate status if any, validation output, scan-clean result, and remaining
+risks. Also report the core release highlights from `agent.releaseHighlights`
+or `releaseNotes.highlights` so the user understands what changed in this
+Harness version, not only which files changed.

package/templates/common/.claude/rules/ecc/common.md

@@ -8,7 +8,7 @@ alwaysApply: true
 ## Context
 
 - Start with `CLAUDE.md`. When `Harness/` exists, also read `Harness/memory/startup-hints.md` (L2 lightweight digest, not full router).
-- When the user explicitly invokes a `/wf-*` command, load `Harness/MEMORY.md` and `Harness/README.md`.
+- When the user explicitly invokes a `/wf-*` workflow command, excluding `/wf-help` and `/wf-update`, load `Harness/MEMORY.md` and `Harness/README.md`.
 - For simple single-step tasks without `/wf-*`, operate in direct mode: skip the Harness router and execute directly.
 - Do not bulk-read `Harness/`. Load by router trigger.
 - Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.
@@ -24,6 +24,7 @@ alwaysApply: true
 
 ## Low-Noise Progress
 
+- Match the user's language for user-facing prose. Use the latest user message's dominant language unless the user asks otherwise; preserve code, commands, file paths, logs, and quoted source text exactly.
 - Keep intermediate user updates to 1-2 short sentences.
 - Do not recap plans, paste logs, or narrate obvious file reads while working.
 - Put the detailed summary in the final response: files changed, verification, risks, and commit hash when relevant.
@@ -31,10 +32,10 @@ alwaysApply: true
 
 ## Subagents
 
-- Use `Harness/subagents.md` before orchestrating multiple agents.
-- Use `Harness/context-loading.md` before spawning.
-- Use `Harness/dispatch.md` before parallel or multi-agent work.
-- Use `Harness/extension.md` before adding stack-specific agents, skills, or rules.
+- Use `Harness/specs/runtime/subagents.md` before orchestrating multiple agents.
+- Use `Harness/specs/runtime/context-loading.md` before spawning.
+- Use `Harness/specs/runtime/dispatch.md` before parallel or multi-agent work.
+- Use `Harness/specs/guides/extension.md` before adding stack-specific agents, skills, or rules.
 - Every subagent needs role, task, read boundary, write boundary, and return format.
 - Writing agents must run serially unless write sets are disjoint.
 - If the runtime cannot spawn subagents, emulate the same role pack in a separate bounded pass.

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

@@ -16,13 +16,19 @@ subagent surfaces; follow the same Harness role contract either way.
 
 ## Load
 
-- `Harness/subagents.md`
-- `Harness/dispatch.md`
-- `Harness/context-loading.md`
-- `Harness/agent-workflow.md`
+- `Harness/specs/runtime/subagents.md`
+- `Harness/specs/runtime/dispatch.md`
+- `Harness/specs/runtime/context-loading.md`
+- `Harness/specs/runtime/agent-workflow.md`
 - `Harness/PROGRESS.md`
 - Active `Harness/tasks/<task-id>/PROGRESS.md` and `PLAN.md`, when present
-- `Harness/WF.md` when in explicit `/wf`, `$wf`, or `/skills wf`
+- `Harness/specs/workflows/WF.md` when in explicit `/wf`, `$wf`, or `/skills wf`
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: inject only
+routed docs and selected files, keep dispatch packet fields deterministic, defer
+unused skill/tool schemas, and require bounded summaries instead of transcripts.
 
 ## Runtime Mapping
 
@@ -42,7 +48,7 @@ subagent surfaces; follow the same Harness role contract either way.
   integrates returns, and owns final verification.
 - Subagents or bounded passes are readers and reporters unless a write set is
   explicitly assigned and disjoint.
-- Explicit WF/WF-MAX requires tier-specific role coverage per `Harness/WF.md`.
+- Explicit WF/WF-MAX requires tier-specific role coverage per `Harness/specs/workflows/WF.md`.
 - Every dispatch needs role, goal, mode, read set, write set, forbidden scope,
   injected docs, dependencies, evidence, stop condition, and return format.
 - Prefer parallel read-only exploration first. Serialize writers unless write

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/