create-harness-vibe-coding 0.8.13 → 0.8.17

package/src/index.js

@@ -57,7 +57,7 @@ if (showHelp) {
   console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
-  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,browser-e2e');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,ui-ux-review');
   console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
   console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
   console.log('');
@@ -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-auto-spark.md

@@ -0,0 +1,16 @@
+---
+description: Run perpetual inspiration mode via the wf-auto-spark skill
+---
+
+# /wf-auto-spark
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto-spark/SKILL.md` (mirror: `.agents/skills/wf-auto-spark/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO-SPARK.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto-spark/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run perpetual adaptive auto-optimization via the wf-auto skill
+---
+
+# /wf-auto
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto/SKILL.md` (mirror: `.agents/skills/wf-auto/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto/SKILL.md` and follow it in place.

package/templates/{optional/skills/browser-e2e/.opencode → common/.claude}/commands/wf-browser.md

@@ -8,8 +8,9 @@ This is a **workflow command**, not a direct command. Do not execute it as a
 static help or script command.
 
 1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
-2. Execute per the skill adapter `.claude/skills/wf-browser/SKILL.md` (mirror: `.agents/skills/wf-browser/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/workflows/browser-e2e.md` are authoritative.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-browser/SKILL.md` (mirror: `.agents/skills/wf-browser/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/HARNESS_BRIDGE.md` are authoritative.
 
 If this runtime cannot invoke the skill directly, read
 `.claude/skills/wf-browser/SKILL.md` and follow it in place.

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

@@ -3,6 +3,9 @@
 Return this help table directly. Do not invoke a skill, do not start WF mode,
 do not dispatch agents, and do not edit files.
 
+Codex compatibility: `$wf-help` or `/skills wf-help` loads the `wf-help` shim,
+which returns this same table without loading `Harness/MEMORY.md` or entering WF.
+
 | Command | Type | Usage | Purpose |
 | --- | --- | --- | --- |
 | `/wf-help` | direct command | `/wf-help` | Show this command table. |
@@ -12,13 +15,14 @@ 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>` | workflow skill | `/wf-browser verify checkout flow` | Built-in browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |
 | `/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. |
 
 Source of truth: `Harness/README.md#Skill Commands` plus installed skills under
-`.claude/skills/` (Claude Code) or `.agents/skills/` (Codex). In OpenCode the
-same skills load from `.claude/skills/`, `.agents/skills/`, and `.opencode/skills/`.
-In OpenCode, every workflow command above is also visible as a thin command
-wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper only
-routes to the matching skill adapter and does not duplicate the workflow.
+`.claude/skills/` (Claude Code and OpenCode adapters) or `.agents/skills/`
+(Codex). In OpenCode, every workflow command above is visible as a thin command
+wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper routes
+to the matching `.claude/skills/<command>/SKILL.md` adapter and does not
+duplicate the workflow.

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

@@ -0,0 +1,16 @@
+---
+description: Run the context-master -> memory-master learning cycle via the wf-learn skill
+---
+
+# /wf-learn
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-learn/SKILL.md` (mirror: `.agents/skills/wf-learn/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/MEMORY_PROTOCOL.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-learn/SKILL.md` and follow it in place.

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

@@ -0,0 +1,20 @@
+---
+description: Run WF-MAX with mandatory subagent fan-out and recorded degradation
+---
+
+# /wf-max
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Load and follow `.claude/skills/wf-max/SKILL.md` (mirror: `.agents/skills/wf-max/SKILL.md`) and `Harness/specs/workflows/WF-MAX.md`.
+3. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+4. MUST attempt native runtime subagent fan-out before planning is considered complete:
+   - start `task-scribe` when available for task ledger/state;
+   - start W0 exploration through manager/explorer/researcher roles with disjoint read sets;
+   - when running in OpenCode, require project `opencode.json` to have `subagent_depth >= 2` and manager agents to have `permission.task` allowlists for manager -> worker fan-out;
+   - if nested manager fan-out is unavailable, dispatch leaf workers directly from the primary agent with exact WF-MAX dispatch packets.
+5. In every runtime, MUST attempt native subagent fan-out before implementation planning is considered complete; never silently continue as a solo controller.
+6. If native fan-out fails, record `fanoutAttempted: true`, runtime, channel tried, agents requested, failure/degradation reason, and the fallback path in `Harness/tasks/<task-id>/PLAN.md` or `PROGRESS.md`.
+7. Continue with WF-Max-Useful by default or WF-Max-Strict only when the user explicitly requests strict mode.

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

@@ -0,0 +1,16 @@
+---
+description: Run the README preservation and improvement workflow via the wf-readme skill
+---
+
+# /wf-readme
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-readme/SKILL.md` (mirror: `.agents/skills/wf-readme/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the project root \`README.md\` ownership rules are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-readme/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run safe harness removal via the wf-remove skill
+---
+
+# /wf-remove
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-remove/SKILL.md` (mirror: `.agents/skills/wf-remove/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/scripts/wf-remove.mjs` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-remove/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run peer CLI or reviewer-subagent review via the wf-review skill
+---
+
+# /wf-review
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-review/SKILL.md` (mirror: `.agents/skills/wf-review/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the wf-review peer-review contract are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-review/SKILL.md` and follow it in place.

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/commands/wf.md

@@ -0,0 +1,16 @@
+---
+description: Run the tiered WF workflow (WF-Light/Standard/Full) via the wf skill
+---
+
+# /wf
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf/SKILL.md` (mirror: `.agents/skills/wf/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf/SKILL.md` and follow it in place.

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 workflow command (`/wf-*`, `$wf-*`, or `/skills wf-*`), excluding `/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills 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