create-harness-vibe-coding 0.8.13 → 0.8.17

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to isolate a failing command, reproduce the smallest failing path, and propose the narrowest fix.
 mode: subagent
 permission:

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to verify official documentation, APIs, SDK behavior, config options, version changes, limits, error semantics, and examples before implementation.
 mode: subagent
 permission:
@@ -13,7 +14,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/.opencode/agents/explore-manager.md

@@ -1,11 +1,21 @@
 ---
+harness: wf-agent
 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.
 mode: subagent
 permission:
+  task:
+    "*": deny
+    "codebase-explorer": allow
+    "researcher": allow
+    "docs-researcher": allow
+    "explore": allow
+    "scout": allow
   edit: deny
   bash:
     "*": deny
-    "git *": allow
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
     "ls *": allow
     "dir *": allow
     "tree *": allow

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

@@ -1,13 +1,16 @@
 ---
+harness: wf-agent
 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.
 mode: subagent
 permission:
+  task:
+    "*": deny
+    "implementer": allow
   edit: deny
   bash:
     "*": deny
-    "git *": allow
-    "node *": allow
-    "npm *": allow
+    "git status*": allow
+    "git diff*": allow
   websearch: deny
   webfetch: deny
 ---

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to implement the smallest change inside a declared write set after tests or manual checks are defined.
 mode: subagent
 permission:

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 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.
 mode: subagent
 permission:
@@ -15,7 +16,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/.opencode/agents/planner.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to split a goal into tasks, dependencies, write sets, verification steps, and a Parallel Dispatch table before multi-step work.
 mode: subagent
 permission:
@@ -16,8 +17,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/.opencode/agents/reflector.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use after verification and cross-review to synthesize findings, detect unresolved risk, and decide whether work may enter final acceptance.
 mode: subagent
 permission:

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use for product, market, competitor, open-source, dependency, pricing, policy, or ecosystem research before PRD and architecture decisions.
 mode: subagent
 permission:

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

@@ -1,13 +1,17 @@
 ---
+harness: wf-agent
 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.
 mode: subagent
 permission:
+  task:
+    "*": deny
+    "reviewer": allow
   edit: deny
   bash:
     "*": deny
-    "git *": allow
+    "git status*": allow
     "git diff *": allow
-    "node *": allow
+    "git diff*": allow
   websearch: deny
   webfetch: deny
 ---

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use for read-only review of diffs, tests, architecture boundaries, regressions, and missing verification before closeout.
 mode: subagent
 permission:
@@ -16,7 +17,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/.opencode/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.
 mode: subagent

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

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 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.
 mode: subagent
 permission:
@@ -11,10 +12,10 @@ permission:
 
 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/.opencode/agents/test-writer.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to define or write AC-linked failing tests and manual verification steps before implementation.
 mode: subagent
 permission:
@@ -14,12 +15,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/.opencode/agents/verifier.md

@@ -1,4 +1,5 @@
 ---
+harness: wf-agent
 description: Use to run verification commands, inspect results, and record evidence. Final acceptance still waits for cross-review PASS and reflector PASS.
 mode: subagent
 permission:

package/templates/common/.opencode/commands/wf-auto-spark.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-auto-spark/SKILL.md` (mirror: `.agents/skills/wf-auto-spark/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/WF-AUTO-SPARK.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-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/.opencode/commands/wf-auto.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-auto/SKILL.md` (mirror: `.agents/skills/wf-auto/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/WF-AUTO.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-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/common/.opencode/commands/wf-browser.md

@@ -0,0 +1,16 @@
+---
+description: Run AI-driven browser automation and E2E testing via the wf-browser skill
+---
+
+# /wf-browser
+
+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-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/.opencode/commands/wf-help.md

@@ -6,6 +6,9 @@ description: Show the Harness WF command table
 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. |
@@ -15,13 +18,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/.opencode/commands/wf-learn.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-learn/SKILL.md` (mirror: `.agents/skills/wf-learn/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/MEMORY_PROTOCOL.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-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/.opencode/commands/wf-max.md

@@ -1,5 +1,6 @@
 ---
-description: Run the WF-MAX maximum-safe-parallelism workflow via the wf-max skill
+description: Run WF-MAX with mandatory subagent fan-out and recorded degradation
+agent: build
 ---
 
 # /wf-max
@@ -8,8 +9,13 @@ 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-max/SKILL.md` (mirror: `.agents/skills/wf-max/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/WF-MAX.md` are authoritative.
-
-If this runtime cannot invoke the skill directly, read
-`.claude/skills/wf-max/SKILL.md` and follow it in place.
+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/.opencode/commands/wf-readme.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-readme/SKILL.md` (mirror: `.agents/skills/wf-readme/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and the project root \`README.md\` ownership rules 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-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/.opencode/commands/wf-remove.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-remove/SKILL.md` (mirror: `.agents/skills/wf-remove/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/scripts/wf-remove.mjs` 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-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/.opencode/commands/wf-review.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-review/SKILL.md` (mirror: `.agents/skills/wf-review/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and the wf-review peer-review contract 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-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/.opencode/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/.opencode/commands/wf.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/SKILL.md` (mirror: `.agents/skills/wf/SKILL.md`).
-3. Do not duplicate the workflow here. The skill adapter and `Harness/WF.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/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.md

@@ -6,17 +6,17 @@ This repository dogfoods the generated Harness scaffold. Scaffold source files l
 
 If `Harness/` exists, this repository is governed by the Harness contract.
 
-At session start, after loading `CLAUDE.md`, read `Harness/memory/startup-hints.md` (L2 lightweight digest, 5-10 hints). This is NOT loading `Harness/MEMORY.md`, `Harness/README.md`, or PROGRESS — it is a minimal startup hint file only.
+Default installed-project startup is thin: after loading `CLAUDE.md`, read `Harness/memory/startup-hints.md` (L2 lightweight digest, 5-10 hints). This is NOT loading `Harness/MEMORY.md`, `Harness/README.md`, or PROGRESS — it is a minimal startup hint file only.
 
 Use **direct mode** for simple, single-step, low-risk requests: commit, push, one-line fix, file read, code question, git log, git status, or similar small operations.
 
 In direct mode, do not load the full Harness router. Inspect only the files needed for the task and execute directly.
 
-Complex work may use direct planning, task capsules, tests, and subagents without entering WF. WF mode is explicit only: the user must type `/wf`, `$wf`, `/skills wf`, `/wf-max`, `$wf-max`, `/skills wf-max`, `/wf-auto`, `$wf-auto`, `/skills wf-auto`, `/wf-auto-spark`, `$wf-auto-spark`, or `/skills wf-auto-spark` to enter WF. No other phrasing, complexity heuristic, or inferred intent triggers WF.
+Complex work may use direct planning, task capsules, tests, and subagents without entering WF. WF execution modes are explicit only: the user must type `/wf`, `$wf`, `/skills wf`, `/wf-max`, `$wf-max`, `/skills wf-max`, `/wf-auto`, `$wf-auto`, `/skills wf-auto`, `/wf-auto-spark`, `$wf-auto-spark`, or `/skills wf-auto-spark` to enter the WF kernel. No other phrasing, complexity heuristic, or inferred intent triggers WF.
 
-`/wf-help` and `/wf-update` are **direct commands** — do NOT load `Harness/MEMORY.md`, do NOT enter WF, do NOT invoke a skill. Execute them immediately as static help / script commands respectively.
+`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update` are **direct/compat commands** — do NOT load `Harness/MEMORY.md`, do NOT enter WF. Claude Code and OpenCode execute the direct command files; Codex may invoke the matching compatibility skill shim, which returns the static help/update instructions without entering WF.
 
-For actual workflow commands (`/wf`, `/wf-max`, `/wf-auto`, `/wf-review`, `/wf-learn`, `/wf-readme`, `/wf-remove`, `/wf-browser`, `/wf-auto-spark`), load `Harness/MEMORY.md` first, then `Harness/README.md`.
+For non-direct workflow commands (`/wf`, `/wf-max`, `/wf-auto`, `/wf-review`, `/wf-learn`, `/wf-readme`, `/wf-remove`, `/wf-browser`, `/wf-auto-spark`, and matching `$wf-*` or `/skills wf-*` forms except the direct/compat commands above), load `Harness/MEMORY.md` first, then `Harness/README.md`.
 
 ### Active Task Resume
 
@@ -30,11 +30,9 @@ If the user says "continue", "resume", "last task", "current task", "status", "w
 6. Do NOT bulk-read `Harness/tasks/` to find context. Use the active pointer.
 7. Direct simple tasks may skip STATE/PLAN/PROGRESS unless the user says "continue"/"resume".
 
-See `Harness/WF-STATE.md` for the full state machine contract. Completed/abandoned tasks are archived to `Harness/tasks/_archive/` per `Harness/TASK_ARCHIVE.md`.
+See `Harness/specs/workflows/WF-STATE.md` for the full state machine contract. Completed/abandoned tasks are archived to `Harness/tasks/_archive/` per `Harness/specs/protocols/TASK_ARCHIVE.md`.
 
-Use **/wf** for multi-step work that needs structured coordination. Use **/wf-max** for maximum-parallelism with CEO/Manager/Worker decomposition. See `Harness/WF.md` for tier selection (WF-Light, WF-Standard, WF-Full) and `Harness/WF-MAX.md` for fan-out rules (WF-Max-Useful, WF-Max-Strict).
-
-`Harness/SETUP.md` is a bootstrap-only document: it exists only while the harness install is not yet finalized. If it exists, finish the bootstrap it describes once, then delete or archive it. Installed projects must not keep `Harness/SETUP.md` in the startup path, and normal sessions must not route through it.
+Use **/wf** for multi-step work that needs structured coordination. Use **/wf-max** for maximum-parallelism with CEO/Manager/Worker decomposition. See `Harness/specs/workflows/WF.md` for tier selection (WF-Light, WF-Standard, WF-Full) and `Harness/specs/workflows/WF-MAX.md` for fan-out rules (WF-Max-Useful, WF-Max-Strict).
 
 ### 1a. WF-MAX Role Contract
 
@@ -48,7 +46,11 @@ Each Worker dispatch must define: role, objective, allowed writeSet, forbidden f
 
 Workers may edit only inside their assigned writeSet. Reviewers and verifiers must be independent from the Worker whose output they evaluate.
 
-Detailed WF-MAX role rules live in `Harness/WF-KERNEL.md`, `Harness/WF-MAX.md`, and `Harness/subagents.md`.
+Detailed WF-MAX role rules live in `Harness/specs/workflows/WF-KERNEL.md`, `Harness/specs/workflows/WF-MAX.md`, and `Harness/specs/runtime/subagents.md`.
+
+### 1b. User-Facing Language
+
+Match the user's language for all user-facing prose. Use the dominant language of the latest user message unless the user explicitly asks for another language; preserve code, identifiers, file paths, commands, logs, and quoted source text exactly.
 
 ## 2. Think Before Coding
 
@@ -85,8 +87,8 @@ Detailed WF-MAX role rules live in `Harness/WF-KERNEL.md`, `Harness/WF-MAX.md`,
 - Every task needs a test, build check, validator run, or recorded manual check.
 - Do not claim web/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
 - Do not place project build scripts, git conventions, run commands, or release process in this file. Put them in `README.md`.
-- Do not place code architecture here. Put architecture in `Harness/architecture.md` or the current feature doc.
-- If this file has accumulated unrelated project notes, pause and propose moving them to the right place: `README.md` for development operations, `Harness/architecture.md` for architecture, `Harness/WF.md` or `Harness/workflows/` for workflow rules.
+- Do not place code architecture here. Put architecture in `Harness/project/architecture.md` or the current feature doc.
+- If this file has accumulated unrelated project notes, pause and propose moving them to the right place: `README.md` for development operations, `Harness/project/architecture.md` for architecture, `Harness/specs/workflows/WF.md` or `Harness/workflows/` for workflow rules.
 
 ## 5a. Low-Noise Progress
 
@@ -107,9 +109,9 @@ Never record secrets, credentials, tokens, or private data in memory.
 
 ## 7. Mode Constraints
 
-- Never call `EnterPlanMode`. Delegate planning to `planner` subagents (see `Harness/WF.md`).
+- Never call `EnterPlanMode`. Delegate planning to `planner` subagents (see `Harness/specs/workflows/WF.md`).
 - In `/wf` or `/wf-max`, follow the selected workflow role contract instead of improvising execution flow.
 - In `/wf-max`, the CEO must not edit source files directly. Implementation must be delegated to Workers with explicit writeSet boundaries.
 - If a Worker dispatch is missing role, objective, writeSet, forbidden scope, or verification requirements, the controller must not proceed with source edits.
 
-Keep CLAUDE.md as a thin routing and global-behavior file. Put detailed workflows in `Harness/WF.md` or `Harness/workflows/`, subagent rules in `Harness/subagents.md`, architecture in `Harness/architecture.md`, and project operations in `README.md`.
+Keep CLAUDE.md as a thin routing and global-behavior file. Put detailed workflows in `Harness/specs/workflows/WF.md` or `Harness/workflows/`, subagent rules in `Harness/specs/runtime/subagents.md`, architecture in `Harness/project/architecture.md`, and project operations in `README.md`.