create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/Harness/MEMORY.md

@@ -29,16 +29,19 @@ Stack-specific agents can be added after the product shape is known.
 
 ## Skills (Workflows)
 
-- [WF Mode](WF.md) - WF-KERNEL tiered orchestration: WF-Light (minimal roles), WF-Standard (adds review), WF-Full (complete role chain incl. reflector and cross-review).
+- [WF Mode](specs/workflows/WF.md) - WF-KERNEL tiered orchestration: WF-Light (minimal roles), WF-Standard (adds review), WF-Full (complete role chain incl. reflector and cross-review).
 - [wf](../.claude/skills/wf/SKILL.md) - Claude Code WF skill command; mirrored for Codex at `../.agents/skills/wf/SKILL.md`.
 - [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) - controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
 - [wf-readme](../.claude/skills/wf-readme/SKILL.md) - README preservation, append-only development sections, structured tables, and approved architecture diagrams.
+- [wf-agents-docs](../.claude/skills/wf-agents-docs/SKILL.md) - source-backed Claude/Codex/OpenCode CLI invocation, JSON output, resume, telemetry, and automation gotchas.
 - [wf-review](../.claude/skills/wf-review/SKILL.md) - peer review: prefer another agent CLI (Claude/Codex/OpenCode); otherwise use the installed reviewer role as an independent subagent context. Controller decides.
+- [wf-help](../.claude/skills/wf-help/SKILL.md) - Codex compatibility shim for `$wf-help` / `/skills wf-help`; returns the direct command table without entering WF.
 - [wf-update](../.claude/skills/wf-update/SKILL.md) - GitHub-based incremental harness update, checksum comparison, and safe in-place updates.
 - [wf-learn](../.claude/skills/wf-learn/SKILL.md) - force memory learning cycle: context-master -> memory-master -> project + global memory.
 - [wf-max](../.claude/skills/wf-max/SKILL.md) - WF kernel + maximum safe fan-out: WF-Max-Useful by default (fan out only where independent), WF-Max-Strict only on explicit strict request; current runtime subagents first, peer-CLI overflow when available.
 - [wf-auto](../.claude/skills/wf-auto/SKILL.md) - perpetual adaptive auto-optimization: evidence-selected probes, dynamic obligations, intent checkpoints, evidence ledger.
 - [wf-auto-spark](../.claude/skills/wf-auto-spark/SKILL.md) - perpetual inspiration mode: external spark search, long-term roadmap with staged milestones, <=50% deviation guard.
+- [wf-browser](../.claude/skills/wf-browser/SKILL.md) - built-in browser automation/E2E workflow with controllable UI contracts, Browser Use, Playwright, CDP/network evidence, screenshots, traces, and validation matrix.
 - [tdd](../.claude/skills/tdd/SKILL.md) - acceptance-driven TDD: AC-linked RED tests, real UI clicks for browser-visible behavior, Playwright/CDP evidence, and configured coverage gate.
 - [wf-remove](../.claude/skills/wf-remove/SKILL.md) - safely remove Harness framework files (SAFE/MODIFIED/USER classes), auto-prune empty directories, backup option.
 
@@ -46,12 +49,11 @@ Codex repo-skill mirrors live under `../.agents/skills/` with the same skill nam
 
 ## Direct Commands
 
-- [wf-help](../.claude/commands/wf-help.md) - direct `/wf-help` command that returns a WF command table without invoking a skill.
+- [wf-help](../.claude/commands/wf-help.md) - direct `/wf-help` command that returns a WF command table; Codex mirror skill supports `$wf-help` without entering WF.
+- [wf-update](../.claude/commands/wf-update.md) - direct `/wf-update` command for script-driven update checks, safe apply, conflict handling, and release highlights.
 
 Stack-specific skills can be added after the product shape is known.
 
-- [browser-e2e](workflows/browser-e2e.md)
-
 ## Rules (Harness Constraints)
 
 Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
@@ -62,26 +64,27 @@ Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
 ## Harness (Runtime)
 
 - [Docs router](README.md)
-- [Acceptance protocol](ACCEPTANCE_PROTOCOL.md)
-- [Agent isolation protocol](AGENT_ISOLATION.md)
-- [Harness Bridge](HARNESS_BRIDGE.md)
-- [Debug protocol](DEBUG_PROTOCOL.md)
-- [Memory protocol](MEMORY_PROTOCOL.md)
-- [WF mode](WF.md)
-- [WF Max mode](WF-MAX.md)
-- [WF kernel contract](WF-KERNEL.md)
-- [WF state machine / resume](WF-STATE.md)
-- [Task archive mechanism](TASK_ARCHIVE.md)
-- [0-1 lifecycle](lifecycle.md)
+- [Acceptance protocol](specs/protocols/ACCEPTANCE_PROTOCOL.md)
+- [Agent isolation protocol](specs/protocols/AGENT_ISOLATION.md)
+- [Harness Bridge](specs/protocols/HARNESS_BRIDGE.md)
+- [Debug protocol](specs/protocols/DEBUG_PROTOCOL.md)
+- [Memory protocol](specs/protocols/MEMORY_PROTOCOL.md)
+- [WF mode](specs/workflows/WF.md)
+- [WF Max mode](specs/workflows/WF-MAX.md)
+- [WF kernel contract](specs/workflows/WF-KERNEL.md)
+- [WF state machine / resume](specs/workflows/WF-STATE.md)
+- [Task archive mechanism](specs/protocols/TASK_ARCHIVE.md)
+- [0-1 lifecycle](specs/guides/lifecycle.md)
 - [Research protocol](research/README.md)
-- [Context loading protocol](context-loading.md)
-- [Dispatch protocol](dispatch.md)
-- [Subagent orchestration](subagents.md)
-- [Extension contract](extension.md)
-- [Architecture docs](architecture.md)
-- [Agent workflow](agent-workflow.md)
+- [Context loading protocol](specs/runtime/context-loading.md)
+- [Dispatch protocol](specs/runtime/dispatch.md)
+- [Subagent orchestration](specs/runtime/subagents.md)
+- [Extension contract](specs/guides/extension.md)
+- [Architecture docs](project/architecture.md)
+- [Agent workflow](specs/runtime/agent-workflow.md)
 - [Acceptance templates](templates/)
 - [Harness validator](scripts/validate-harness.mjs)
+- [Settings](settings.json)
 - [Version file](.harness-version)
 
 ## Memory Folder

package/templates/common/Harness/README.md

@@ -4,7 +4,7 @@ Purpose: route humans and agents to the smallest useful context. `CLAUDE.md` is
 
 Default load: `CLAUDE.md`. For workflow commands (`/wf`, `/wf-max`, `/wf-auto`, `/wf-review`, `/wf-learn`, `/wf-readme`, `/wf-remove`, `/wf-browser`, `/wf-auto-spark`), also load `Harness/MEMORY.md` (index only per Memory Preflight), this file, and `Harness/PROGRESS.md` when work is active.
 
-`/wf-help` and `/wf-update` are **direct commands**: skip the router, do NOT load `Harness/MEMORY.md`, do NOT enter WF, execute immediately.
+`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update` are **direct/compat commands**: skip the router, do NOT load `Harness/MEMORY.md`, do NOT enter WF. Claude Code and OpenCode execute direct command files; Codex uses the matching compatibility skill shim.
 
 Do not read the whole `Harness/` tree.
 
@@ -25,19 +25,19 @@ On session start (new window, reopen, resume):
 4. Do NOT discover context by reading all task directories. Use the active pointer.
 5. 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 and enums.
+See `Harness/specs/workflows/WF-STATE.md` for the full state machine contract and enums.
 
 ## Direct Mode (Degradation Path)
 
-When the user does NOT explicitly invoke `/wf-*`, `$wf-*`, `/skills wf`, `/skills wf-max`, or say `wf` / `wf-max`, the request is handled in **direct mode**. Skip the router entirely. Execute the task. Do not load `Harness/MEMORY.md`, `Harness/README.md`, or `Harness/PROGRESS.md`.
+When the user does NOT explicitly invoke `/wf-*`, `$wf-*`, `/skills wf-*`, or say `wf` / `wf-max`, the request is handled in **direct mode**. Skip the router entirely. Execute the task. Do not load `Harness/MEMORY.md`, `Harness/README.md`, or `Harness/PROGRESS.md`.
 
 Complex work may use direct planning, task capsules, tests, and subagents without entering WF.
 
 Escalate to the router (next section) only when:
 - User explicitly invokes `/wf`, `/wf-max`, `$wf`, `$wf-max`, `/skills wf`, `/skills wf-max`, or says `wf` / `wf-max`
-- User invokes another workflow `/wf-*` command (NOT `/wf-help` or `/wf-update` — those are direct commands)
+- User invokes another workflow `/wf-*`, `$wf-*`, or `/skills wf-*` command, excluding `/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update`
 
-`/wf-help` and `/wf-update` are direct commands executed immediately without router load.
+`/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update` are direct/compat commands executed immediately without router load.
 
 ## 0-1 Flow
 
@@ -45,7 +45,7 @@ Escalate to the router (next section) only when:
 Idea -> Research -> Mini PRD -> Acceptance Criteria -> Contracts -> Tests -> Build -> Independent Validation -> Debug -> Memory
 ```
 
-For the full phase contract, load [lifecycle.md](lifecycle.md).
+For the full phase contract, load [lifecycle.md](specs/guides/lifecycle.md).
 
 ## Development Contract
 
@@ -56,18 +56,18 @@ For the full phase contract, load [lifecycle.md](lifecycle.md).
 - Task records are compact by default: PLAN holds goal, decisions, scope, risks; PROGRESS holds status/next, changes, verification. Do not paste command logs, full transcripts, or broad PRDs when a link or one-line evidence entry is enough.
 - Build commands, git conventions, and release notes belong in root `README.md`, not `CLAUDE.md`.
 - README rewrites are optional project-doc work. Use `wf-readme` and preserve existing public docs unless the user approves a broader restructure.
-- Code architecture belongs in [architecture.md](architecture.md) or the current feature doc, not `CLAUDE.md`.
+- Code architecture belongs in [architecture.md](project/architecture.md) or the current feature doc, not `CLAUDE.md`.
 - Core rules live in `CLAUDE.md` and `.claude/rules/ecc/common.md`.
-- WF mode rules live in [WF.md](WF.md).
-- Phase rules live in [lifecycle.md](lifecycle.md).
-- Build, review, test, and subagent rules live in [agent-workflow.md](agent-workflow.md); AC-linked TDD rules live in [TDD-GUIDE.md](TDD-GUIDE.md).
-- Acceptance-driven gates live in [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md). PRD-derived Acceptance Criteria are the source of truth for implementation, tests, review, validation, debug, and memory.
-- Role/context isolation rules live in [AGENT_ISOLATION.md](AGENT_ISOLATION.md).
-- Frontend-backend test harness and CDP/network evidence rules live in [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md).
-- Parallel dispatch rules live in [dispatch.md](dispatch.md).
-- Subagent orchestration methodology lives in [subagents.md](subagents.md).
-- Extension rules live in [extension.md](extension.md).
-- Context-loading rules live in [context-loading.md](context-loading.md).
+- WF mode rules live in [WF.md](specs/workflows/WF.md).
+- Phase rules live in [lifecycle.md](specs/guides/lifecycle.md).
+- Build, review, test, and subagent rules live in [agent-workflow.md](specs/runtime/agent-workflow.md); AC-linked TDD rules live in [TDD-GUIDE.md](specs/protocols/TDD-GUIDE.md).
+- Acceptance-driven gates live in [ACCEPTANCE_PROTOCOL.md](specs/protocols/ACCEPTANCE_PROTOCOL.md). PRD-derived Acceptance Criteria are the source of truth for implementation, tests, review, validation, debug, and memory.
+- Role/context isolation rules live in [AGENT_ISOLATION.md](specs/protocols/AGENT_ISOLATION.md).
+- Frontend-backend test harness and CDP/network evidence rules live in [HARNESS_BRIDGE.md](specs/protocols/HARNESS_BRIDGE.md).
+- Parallel dispatch rules live in [dispatch.md](specs/runtime/dispatch.md).
+- Subagent orchestration methodology lives in [subagents.md](specs/runtime/subagents.md).
+- Extension rules live in [extension.md](specs/guides/extension.md).
+- Context-loading rules live in [context-loading.md](specs/runtime/context-loading.md).
 - Progress lives in `Harness/PROGRESS.md`, `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, and the current feature doc.
 
 ## Keyword Routing
@@ -95,27 +95,29 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 | When to Read | Keywords | Load | Output |
 | --- | --- | --- | --- |
 | **Direct mode (default)** | simple, single-step, low-risk, commit, push, one-line, read, question, status, no /wf-* command | Nothing beyond CLAUDE.md | Direct execution; no router load |
-| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
+| Raw idea or vague product request | idea, vague, clarify, goal, non-goal, lifecycle | [lifecycle.md](specs/guides/lifecycle.md), [research/PRD.md](research/PRD.md) | clarified goal, non-goals, first questions |
 | Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
-| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | Mini PRD with AC IDs and verifiable acceptance criteria |
-| Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](architecture.md) | layer map, ports, constraints |
-| Need WF command help | /wf-help, wf help, command list, list wf commands | `.claude/commands/wf-help.md` | direct command table; no skill invocation |
-| Need WF mode (explicit only) | /wf, $wf, /skills wf (explicit user token only) | [WF.md](WF.md), [WF-KERNEL.md](WF-KERNEL.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | dynamic ready-queue orchestration, tier-gated acceptance |
-| Need perpetual auto-optimization | /wf-auto, $wf-auto, /skills wf-auto (explicit user token only) | [WF-AUTO.md](WF-AUTO.md), [WF-AUTO-ANGLES.md](WF-AUTO-ANGLES.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | perpetual loop, adaptive probe selection, dynamic risk obligations, spark search, intent checkpoint, evidence ledger; CEO never writes code |
-| Need perpetual inspiration mode | /wf-auto-spark, $wf-auto-spark, /skills wf-auto-spark (explicit user token only) | [WF-AUTO-SPARK.md](WF-AUTO-SPARK.md), [WF-AUTO.md](WF-AUTO.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | roadmap-anchored: North Star + milestones; external spark search; <=50% deviation guard; never auto-stops |
-| Need WF-MAX mode (explicit only) | /wf-max, $wf-max, /skills wf-max (explicit user token only) | [WF-MAX.md](WF-MAX.md), [WF-KERNEL.md](WF-KERNEL.md), [subagents.md](subagents.md), [dispatch.md](dispatch.md) | /wf kernel + max safe fan-out (WF-Max-Useful default, WF-Max-Strict override) |
+| Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md), [ACCEPTANCE_PROTOCOL.md](specs/protocols/ACCEPTANCE_PROTOCOL.md) | Mini PRD with AC IDs and verifiable acceptance criteria |
+| Need architecture or boundaries | architecture, boundary, layer, port, adapter, dependency | [architecture.md](project/architecture.md) | layer map, ports, constraints |
+| Need WF command help | /wf-help, $wf-help, /skills wf-help, wf help, command list, list wf commands | `.claude/commands/wf-help.md`, `.opencode/commands/wf-help.md`, `.claude/skills/wf-help/SKILL.md`, `.agents/skills/wf-help/SKILL.md` | static command table; Codex shim may invoke a minimal skill, but no WF/router load |
+| Need WF mode (explicit only) | /wf, $wf, /skills wf (explicit user token only) | [WF.md](specs/workflows/WF.md), [WF-KERNEL.md](specs/workflows/WF-KERNEL.md), [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` | dynamic ready-queue orchestration, tier-gated acceptance |
+| Need perpetual auto-optimization | /wf-auto, $wf-auto, /skills wf-auto (explicit user token only) | [WF-AUTO.md](specs/workflows/WF-AUTO.md), [WF-AUTO-ANGLES.md](specs/workflows/WF-AUTO-ANGLES.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | perpetual loop, adaptive probe selection, dynamic risk obligations, spark search, intent checkpoint, evidence ledger; CEO never writes code |
+| Need perpetual inspiration mode | /wf-auto-spark, $wf-auto-spark, /skills wf-auto-spark (explicit user token only) | [WF-AUTO-SPARK.md](specs/workflows/WF-AUTO-SPARK.md), [WF-AUTO.md](specs/workflows/WF-AUTO.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | roadmap-anchored: North Star + milestones; external spark search; <=50% deviation guard; never auto-stops |
+| Need WF-MAX mode (explicit only) | /wf-max, $wf-max, /skills wf-max (explicit user token only) | [WF-MAX.md](specs/workflows/WF-MAX.md), [WF-KERNEL.md](specs/workflows/WF-KERNEL.md), [subagents.md](specs/runtime/subagents.md), [dispatch.md](specs/runtime/dispatch.md) | /wf kernel + max safe fan-out (WF-Max-Useful default, WF-Max-Strict override) |
 | Need peer review | /wf-review, $wf-review, peer review, second opinion, cross-check, stuck | `.claude/skills/wf-review/SKILL.md`, `.agents/skills/wf-review/SKILL.md`, `Harness/README.md`, `.opencode/commands/wf-review.md` | peer CLI when available; otherwise installed `reviewer` role subagent; controller decides |
-| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
-| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
-| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](agent-workflow.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | tasks, AC IDs, write set, verification commands |
-| Browser E2E testing or automation | /wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use, CDP | browser-e2e workflow, [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md), wf-browser skill, Browser Use skill | UI/API contract, CLI commands, screenshots, traces, validation matrix |
-| Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](extension.md) | workflow-specific evidence, commands, fallback path |
-| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection, scenario memory | [MEMORY.md](MEMORY.md), [MEMORY_PROTOCOL.md](MEMORY_PROTOCOL.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry, scenario memory hint, or no-op rationale |
-| Need subagents | subagent, role pack, context, inject, return format, orchestrator, isolation | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md), [AGENT_ISOLATION.md](AGENT_ISOLATION.md) | controller plan, role-specific context pack, isolation-aware dispatch pack |
-| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md), [TDD-GUIDE.md](TDD-GUIDE.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | task plan, AC-linked RED tests, implementation loop |
-| Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
+| Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](specs/guides/extension.md), [PROGRESS.md](PROGRESS.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
+| README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/wf-readme/SKILL.md`, [PROGRESS.md](PROGRESS.md), [architecture.md](project/architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
+| Need implementation plan | plan, task, write set, verify, milestone, progress | [PROGRESS.md](PROGRESS.md), the current task `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md`, [agent-workflow.md](specs/runtime/agent-workflow.md), [ACCEPTANCE_PROTOCOL.md](specs/protocols/ACCEPTANCE_PROTOCOL.md) | tasks, AC IDs, write set, verification commands |
+| Browser E2E testing or automation | /wf-browser, $wf-browser, /skills wf-browser, browser, e2e, web automation, form fill, screenshot verify, page test, browser test, Playwright AI, Browser Use, CDP | `.claude/skills/wf-browser/SKILL.md`, `.agents/skills/wf-browser/SKILL.md`, [HARNESS_BRIDGE.md](specs/protocols/HARNESS_BRIDGE.md), Browser Use skill | controllable UI contract, Browser Use/Playwright/CDP commands, screenshots, traces, validation matrix |
+| Optional workflow installed | workflow, optional, ui-ux-review, github-pr-review, python-backend, ts-react-frontend | matching `workflows/*.md` (if installed), [extension.md](specs/guides/extension.md) | workflow-specific evidence, commands, fallback path |
+| Need durable memory or reflection | memory, remember, preference, correction, tool failure, lesson, reflection, scenario memory | [MEMORY.md](MEMORY.md), [MEMORY_PROTOCOL.md](specs/protocols/MEMORY_PROTOCOL.md), `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` | concise newest-first memory entry, scenario memory hint, or no-op rationale |
+| Need context/cache/token efficiency | cache, token, context, prompt cache, tool search, cache hit | [context-loading.md](specs/runtime/context-loading.md), [WF-KERNEL.md](specs/workflows/WF-KERNEL.md), [dispatch.md](specs/runtime/dispatch.md), `scripts/l2-cache-telemetry.mjs` | cache-first context layout, deferred skills/tools, bounded summaries, L2 telemetry plan |
+| Need peer CLI automation docs | claude -p, codex exec, opencode run, peer CLI, CLI automation, telemetry | `.claude/skills/wf-agents-docs/SKILL.md`, [context-loading.md](specs/runtime/context-loading.md) | source-backed invocation flags, JSON/telemetry parsing, cache attribution guardrails |
+| Need subagents | subagent, role pack, context, inject, return format, orchestrator, isolation | [subagents.md](specs/runtime/subagents.md), [context-loading.md](specs/runtime/context-loading.md), [dispatch.md](specs/runtime/dispatch.md), [AGENT_ISOLATION.md](specs/protocols/AGENT_ISOLATION.md) | controller plan, role-specific context pack, isolation-aware dispatch pack |
+| Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](specs/runtime/agent-workflow.md), [TDD-GUIDE.md](specs/protocols/TDD-GUIDE.md), [ACCEPTANCE_PROTOCOL.md](specs/protocols/ACCEPTANCE_PROTOCOL.md) | task plan, AC-linked RED tests, implementation loop |
+| Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](specs/runtime/agent-workflow.md), current feature doc | findings, verification evidence |
 | Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | structural install check; strict bootstrap/release placeholder check |
-| Need harness update | /wf-update, $wf-update, update, check for updates, harness version | `.claude/commands/wf-update.md`, `.opencode/commands/wf-update.md`, `Harness/.harness-version`, `Harness/scripts/wf-update-check.mjs`; Codex fallback: `.claude/skills/wf-update/SKILL.md` | script-driven comparison, SAFE/CONFLICT/PRESERVE classification, user decides conflicts |
+| Need harness update | /wf-update, $wf-update, update, check for updates, harness version | `.claude/commands/wf-update.md`, `.opencode/commands/wf-update.md`, `Harness/.harness-version`, `Harness/scripts/wf-update-check.mjs`; Codex fallback: `.claude/skills/wf-update/SKILL.md` | script-driven comparison, SAFE/CONFLICT/PRESERVE classification, changelog release highlights, user decides conflicts |
 | Need harness removal | /wf-remove, $wf-remove, wf remove, remove harness, uninstall harness | `.claude/skills/wf-remove/SKILL.md`, `.agents/skills/wf-remove/SKILL.md`, `Harness/scripts/wf-remove.mjs` | safe removal plan: auto-remove SAFE, confirm MODIFIED, never touch USER DATA |
 
 ## Gates
@@ -125,12 +127,12 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 - Use `/wf-auto` for perpetual self-directed optimization. It selects probes from project evidence and stops only after dynamic risk obligations and two different empty confirmation passes are recorded.
 - **WF-MAX Role Contract**: Three-layer architecture: global mode (`wf-max`), agent role (`ceo|manager|worker|verifier|reviewer|reflector`), dispatch permission (`writeSet`, `forbidden`, `verification`). CEO never writes source code. Workers edit only dispatch.writeSet. Compliance is checked through dispatch packets, independent review, validation evidence, and task capsules. See `CLAUDE.md#1a`.
 - **WF-REVIEW Independence**: Prefer a peer CLI (`claude`, `codex`, or `opencode`) that is not the current runtime. If none exists, dispatch the installed `reviewer` role as a separate subagent context. Same-runtime fallback is independent-context review, not cross-model review; the main agent owns final decisions.
-- WF-MAX has no runtime hook state. The durable state is the task capsule, dispatch table, review findings, and validation evidence. The only runtime hook exception in Harness is the optional `/wf-auto` bounded tick hook described in `WF-AUTO.md`.
+- WF-MAX role enforcement has no runtime hook state. Durable WF state remains the task capsule, dispatch table, review findings, and validation evidence. Startup update-check hooks do not enforce roles, write sets, or agent identity. The `/wf-auto` bounded tick hook is described in `WF-AUTO.md`.
 - Do not code before PRD-GATE, AC-GATE, CONTRACT-GATE, and TEST-GATE are satisfied or explicitly compressed into a documented fast lane.
 - PRD-derived Acceptance Criteria are the source of truth. Code, tests, reviews, validation, debug, and memory must trace to AC IDs.
 - No acceptance criteria, no tests. No acceptance criteria, no code.
 - No `data-testid` or stable accessible selector, no UI acceptance. No API contract, no backend integration acceptance.
-- Unsure whether to open a task? Read [agent-workflow.md](agent-workflow.md) Section 1.
+- Unsure whether to open a task? Read [agent-workflow.md](specs/runtime/agent-workflow.md) Section 1.
 - Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
 - Do not run writing agents in parallel unless write sets are disjoint.
 - Before coordinating multiple agents, fill `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch` and follow `subagents.md` plus `dispatch.md`; if the work also matches WF triggers, enter WF mode first.
@@ -149,24 +151,25 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 |----------|-------|
 | **Router + Index** | `README.md`, `MEMORY.md`, `PROGRESS.md` |
 | **Task Capsule** | `tasks/<id>/PROGRESS.md`, `tasks/<id>/PLAN.md`, `tasks/<id>/STATE.json`, `tasks/_template/` |
-| **Workflows** | `WF.md`, `WF-KERNEL.md`, `WF-STATE.md`, `WF-MAX.md`, `WF-AUTO.md`, `WF-AUTO-SPARK.md` |
-| **Protocols** | `ACCEPTANCE_PROTOCOL.md`, `AGENT_ISOLATION.md`, `HARNESS_BRIDGE.md`, `DEBUG_PROTOCOL.md`, `MEMORY_PROTOCOL.md` |
-| **Guides** | `ECC-GUIDE.md`, `TDD-GUIDE.md`, `lifecycle.md`, `architecture.md`, `TASK_ARCHIVE.md` |
-| **Orchestration** | `subagents.md`, `context-loading.md`, `dispatch.md`, `agent-workflow.md`, `extension.md`, `WF-STATE.md` |
+| **Workflows** | `specs/workflows/WF.md`, `specs/workflows/WF-KERNEL.md`, `specs/workflows/WF-STATE.md`, `specs/workflows/WF-MAX.md`, `specs/workflows/WF-AUTO.md`, `specs/workflows/WF-AUTO-SPARK.md` |
+| **Protocols** | `specs/protocols/ACCEPTANCE_PROTOCOL.md`, `specs/protocols/AGENT_ISOLATION.md`, `specs/protocols/HARNESS_BRIDGE.md`, `specs/protocols/DEBUG_PROTOCOL.md`, `specs/protocols/MEMORY_PROTOCOL.md` |
+| **Guides** | `specs/guides/ECC-GUIDE.md`, `specs/guides/lifecycle.md`, `specs/guides/extension.md`, `project/architecture.md`, `specs/protocols/TDD-GUIDE.md`, `specs/protocols/TASK_ARCHIVE.md` |
+| **Orchestration** | `specs/runtime/subagents.md`, `specs/runtime/context-loading.md`, `specs/runtime/dispatch.md`, `specs/runtime/agent-workflow.md`, `specs/workflows/WF-STATE.md` |
 | **Research** | `research/README.md`, `research/PRD.md`, `research/research-results.md` |
 | **Acceptance Templates** | `templates/PRD.template.md`, `templates/ACCEPTANCE.template.md`, `templates/UI_CONTRACT.template.md`, `templates/API_CONTRACT.template.md`, `templates/TEST_PLAN.template.md`, `templates/PLAYWRIGHT_SPEC.template.ts`, `templates/VALIDATION_REPORT.template.md` |
 | **Memory** | `memory/tool-usage-reflections.md`, `memory/user-corrections-preferences.md`, `memory/agent-lessons-patterns.md` |
-| **Scripts** | `scripts/validate-harness.mjs`, `scripts/wf-update-check.mjs`, `scripts/wf-remove.mjs`, `scripts/archive-tasks.mjs` |
-| **Runtime** | `.harness-version` |
+| **Scripts** | `scripts/validate-harness.mjs`, `scripts/context-budget.mjs`, `scripts/l2-cache-telemetry.mjs`, `scripts/wf-update-check.mjs`, `scripts/wf-remove.mjs`, `scripts/task-state.mjs`, `scripts/archive-tasks.mjs` |
+| **Runtime + Config** | `.harness-version`, `ownership.manifest.json`, `settings.json` |
 | **Agents + Skills** | `.claude/agents/*`, `.claude/skills/*`, `.agents/skills/*` |
 | **Direct Commands** | `.claude/commands/wf-help.md`, `.claude/commands/wf-update.md`, `.opencode/commands/wf-help.md`, `.opencode/commands/wf-update.md` |
+| **Workflow Command Wrappers** | `.claude/commands/wf*.md`, `.opencode/commands/wf*.md` |
 
 ## Direct Commands
 
 | Command | Purpose |
 |---|---|
-| `/wf-help` | Directly returns a table of all Harness WF commands, usage, and purpose. It does not invoke a skill or start a workflow. |
-| `/wf-update` | Script-driven harness update: fetch + compare + apply. Direct command for Claude Code and OpenCode; skill path available for Codex compatibility. |
+| `/wf-help`, `$wf-help` | Returns a table of all Harness WF commands, usage, and purpose. Claude Code/OpenCode use direct command files; Codex uses the minimal `wf-help` skill shim. It never starts WF. |
+| `/wf-update`, `$wf-update` | Script-driven harness update: fetch + compare + apply + report release highlights. Direct command for Claude Code and OpenCode; skill path available for Codex compatibility. |
 
 ## Skill Commands
 
@@ -178,7 +181,7 @@ Routing priority: **direct mode is the default** when no explicit WF token is pr
 | `/wf-auto-spark` | `$wf-auto-spark` | Perpetual inspiration: spark search, roadmap-anchored, <=50% deviation guard, never auto-stops |
 | `/wf-review [focus]` | `$wf-review [focus]` | Peer CLI review via Claude/Codex/OpenCode, or installed reviewer subagent fallback |
 | `/wf-learn` | `$wf-learn` | Force learning cycle: context-master -> memory-master |
-| `/wf-browser [task]` | `$wf-browser [task]` | AI-driven browser automation for E2E testing |
+| `/wf-browser [task]` | `$wf-browser [task]` | Built-in AI-driven browser automation for E2E testing |
 | `/wf-readme [task]` | `$wf-readme [task]` | README preservation, merge, and documentation improvement workflow |
-| `/wf-update` | `$wf-update` | Script-driven harness update: fetch + compare + apply |
+| `/wf-update` | `$wf-update` | Script-driven harness update: fetch + compare + apply + report release highlights |
 | `/wf-remove` | `$wf-remove` | Safe harness removal: auto-delete SAFE, confirm MODIFIED, preserve USER DATA |