create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/Harness/{subagents.md → specs/runtime/subagents.md}

@@ -4,10 +4,15 @@ Purpose: coordinate subagents for speed without losing control of scope, evidenc
 
 Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or explicit `/wf` / `/wf-max` invocation.
 
+Cache-first discipline: subagent context packs follow
+`Harness/specs/runtime/context-loading.md#Cache-First Context Contract`. Inject only routed
+docs and selected files, keep dispatch fields in deterministic order, defer
+unused skill/tool schemas, and return bounded summaries instead of transcripts.
+
 project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
-Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](AGENT_ISOLATION.md)
-for role/context isolation and [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md)
+Subagent work is acceptance-driven. Use [AGENT_ISOLATION.md](../protocols/AGENT_ISOLATION.md)
+for role/context isolation and [ACCEPTANCE_PROTOCOL.md](../protocols/ACCEPTANCE_PROTOCOL.md)
 for PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, and
 REVIEW-GATE.
 
@@ -82,7 +87,7 @@ Hard rule: implementer may not be the independent validator for the same AC ID.
 
 ## WF Default Fan-Out
 
-Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/WF.md`.
+Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/specs/workflows/WF.md`.
 WF-Light: planner + test-writer + implementer + verifier.
 WF-Standard: adds research/docs + one review lens.
 WF-Full: complete role-chain coverage from `.claude/agents/` before closeout: plan,
@@ -106,7 +111,7 @@ Then add phase-specific agents:
 - `context-master` before closeout for knowledge extraction
 - `memory-master` after repeated failures and during closeout for consolidation
 
-Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
+Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/specs/workflows/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
 
 ## Efficiency Ladder
 
@@ -125,11 +130,15 @@ Max parallelism removes the Harness default cap, not the runtime's physical or
 account cap. For WF-MAX, record the current runtime budget, use native
 subagents first, close completed agents before declaring the pool exhausted,
 then overflow to a peer CLI (`claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`) with explicit
-dispatch packets. Generated Harness Codex config defaults to
-`agents.max_threads = 12` and `agents.max_depth = 1`; if that becomes the
-bottleneck, ask the user before raising `agents.max_threads` and keep
-`max_depth = 1` unless recursive delegation is explicitly approved. Do not rely
-on undocumented fork/derive bypasses as stable capacity.
+dispatch packets. WF-MAX must attempt native subagent fan-out and record
+`fanoutAttempted: true` before any solo fallback. Do not scaffold Codex scalar
+`[agents]` capacity fields into `.codex/config.toml`; codex-cli 0.144.x can
+reject them during TUI `skills/list`. Probe the installed runtime first and
+manage Codex WF-MAX caps through the dispatch ledger unless the installed
+version accepts the config shape. Generated OpenCode config defaults to
+`subagent_depth = 2` so manager subagents can invoke worker subagents; manager
+agents also need `permission.task` allowlists. Do not rely on undocumented
+fork/derive bypasses as stable capacity.
 
 Default for explicit WF invocation: tier-based. WF-Light: planner + test-writer + implementer + verifier (bounded passes acceptable). WF-Standard: adds research/docs + one independent review lens. WF-Full: complete role chain, use bounded role passes as the recorded fallback when subagents are unavailable.
 
@@ -168,7 +177,7 @@ controller intake
 
 ## Dispatch Pack
 
-Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](WF-STATE.md) to resume the dispatch ledger and ready queue.
+Use the canonical dispatch input and handoff format in `Harness/specs/runtime/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/specs/runtime/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](../workflows/WF-STATE.md) to resume the dispatch ledger and ready queue.
 
 ## Parallelism Rules
 

package/templates/common/Harness/{WF-AUTO-SPARK.md → specs/workflows/WF-AUTO-SPARK.md}

@@ -22,7 +22,7 @@ But perpetual search without direction = drift. The **Roadmap** is the anchor.
 
 WF-AUTO-SPARK is a `/wf` variant layered on WF-AUTO: it inherits the WF-KERNEL contract via WF-AUTO and WF constraints, and does not define an independent heavy process. External spark search replaces discovery only; it does not replace acceptance, implementation, review, verification, reflection, or evidence.
 
-Accepted spark candidates re-enter the standard W2-W5 gates per [WF-KERNEL.md](WF-KERNEL.md): implementer (one file_claim, ≤3 files, ≤50 lines), verifier, reviewer(s), reflector. Spark searchers are read-only. Any implementation must use the dispatch packet from `Harness/dispatch.md` with explicit write set, forbidden truth files, AC IDs, and verification commands. A candidate with no verifier evidence or no reflector PASS is not accepted, even if the idea is valuable.
+Accepted spark candidates re-enter the standard W2-W5 gates per [WF-KERNEL.md](WF-KERNEL.md): implementer (one file_claim, ≤3 files, ≤50 lines), verifier, reviewer(s), reflector. Spark searchers are read-only. Any implementation must use the dispatch packet from `Harness/specs/runtime/dispatch.md` with explicit write set, forbidden truth files, AC IDs, and verification commands. A candidate with no verifier evidence or no reflector PASS is not accepted, even if the idea is valuable.
 
 For task-state writes, CEO provides concise bullets and decisions; task-scribe formats task-state writes for roadmap, cycle PLAN, heartbeat, evidence pointers, and closeout. If task-scribe is unavailable, CEO may write the smallest durable checkpoint and must record that degradation in `PROGRESS.md`. This keeps the high-reasoning controller focused on decisions instead of spending tokens formatting process files.
 
@@ -313,7 +313,7 @@ This replaces the broken `/wf-auto` auto-continue. No silent drift across sessio
 
 | File | Purpose |
 |------|---------|
-| `Harness/WF-AUTO-SPARK.md` | This spec |
+| `Harness/specs/workflows/WF-AUTO-SPARK.md` | This spec |
 | `Harness/tasks/auto/SPARK-ROADMAP.md` | Active roadmap (created at startup) |
 | `Harness/tasks/auto/PLAN.md` | Per-cycle change spec |
 | `Harness/tasks/auto/PROGRESS.md` | Cycle log, heartbeat, evidence ledger |

package/templates/common/Harness/{WF-AUTO.md → specs/workflows/WF-AUTO.md}

@@ -296,11 +296,16 @@ Every cycle writes one entry to `Harness/tasks/auto/PROGRESS.md`:
 
 IMMEDIATELY return to W0. No pause between cycles — the only breaks are the adaptive Intent Checkpoint and the A-GATE.
 
-### WF-AUTO Hook Exception
+### Runtime Hook Boundaries
 
-Runtime hooks are disabled by default across the Harness scaffold. The only
-allowed exception is an explicitly enabled `/wf-auto` tick hook for long-running
-auto-optimization.
+Execution-control hooks are disabled by default across the Harness scaffold.
+Startup update-check hooks are not execution-control hooks. Only an explicitly
+enabled `/wf-auto` tick hook may drive long-running auto-optimization.
+
+Manual or benchmark-driven single-cycle `/wf-auto` runs use the same bounded
+tick contract: they may stop because the caller explicitly requested one tick,
+but they still MUST create or update `Harness/tasks/auto/PLAN.md` and
+`Harness/tasks/auto/PROGRESS.md` before returning.
 
 The hook is not a role-enforcement mechanism, not a memory injection mechanism,
 and not WF-MAX state. It is only a bounded tick trigger:
@@ -316,8 +321,8 @@ wf-auto hook event
 
 Hard boundaries:
 
-- no hook is installed or registered by default
-- only `/wf-auto` may use a runtime hook
+- no execution-control hook is installed or registered by default
+- only `/wf-auto` may use a runtime hook to drive auto-optimization
 - the hook must run one bounded tick, not an unbounded process
 - the hook must respect `Harness/tasks/auto/STOP`, `state=paused`, user stop,
   and the Adaptive Coverage Exhaustion Gate
@@ -368,7 +373,7 @@ Spark is NOT a separate optimization engine. It is a **candidate provider** plug
 - User explicitly requests `/wf-auto-spark` → full perpetual inspiration mode (see `WF-AUTO-SPARK.md`)
 - User says "I don't know" at an Intent Checkpoint
 
-**`/wf-auto-spark` is a standalone perpetual mode** (spec: `Harness/WF-AUTO-SPARK.md`). Unlike vanilla spark which is a candidate provider inside `/wf-auto`, the standalone mode:
+**`/wf-auto-spark` is a standalone perpetual mode** (spec: `Harness/specs/workflows/WF-AUTO-SPARK.md`). Unlike vanilla spark which is a candidate provider inside `/wf-auto`, the standalone mode:
 - Never auto-stops — only user can stop it
 - Requires a roadmap (North Star + staged milestones) declared at startup
 - Enforces ≤50% deviation guard against North Star

package/templates/common/Harness/{WF-KERNEL.md → specs/workflows/WF-KERNEL.md}

@@ -2,6 +2,16 @@
 
 The WF Kernel is the shared engine for `/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, and `/wf-browser`. Variants extend the kernel; they do not duplicate the orchestration logic.
 
+## Cache-First Context Contract
+
+All WF variants preserve prompt-cache shape: stable workflow instructions and
+deterministic dispatch schema first; task-specific state, current runtime facts,
+and latest tool outputs last. Use
+`Harness/specs/runtime/context-loading.md#Cache-First Context Contract` for load ordering.
+Dispatch packets keep canonical field order, load only selected skills/tools,
+and return bounded summaries through `MaxReturnTokens` and `ReturnSchema`
+instead of transcripts.
+
 ## Role / Model Matrix
 
 The orchestrator dispatches agents by role, model tier, and task type. No single agent type handles all work.
@@ -121,7 +131,7 @@ ReturnSchema:
 
 | Task Type | Primary Agents | Skills |
 |---|---|---|
-| UI/browser behavior | test-writer, implementer, verifier, reviewer | browser-e2e, wf-browser |
+| UI/browser behavior | test-writer, implementer, verifier, reviewer | wf-browser |
 | API/backend | docs-researcher, test-writer, implementer, verifier, reviewer (security) | tdd |
 | Architecture/migration | architect, codebase-explorer, planner, reviewer | — |
 | Docs/README | wf-readme, reviewer, task-scribe | wf-readme |

package/templates/common/Harness/{WF-MAX.md → specs/workflows/WF-MAX.md}

@@ -18,14 +18,37 @@ WF-MAX is **explicit only**. Enter ONLY when the user explicitly types `/wf-max`
 
 ## Fan-Out Modes
 
-**WF-Max-Useful** (default): fan-out only where writeSets or review lenses are meaningfully independent. Overhead > 0.30 degrades a wave to flat role pass. CEO uses D-GATE but Manager/Worker fan-out is gated by actual independence.
+**WF-Max-Useful** (default): fan-out only where writeSets or review lenses are meaningfully independent. Overhead > 0.30 degrades a wave to flat role pass. This does not authorize CEO source edits: source implementation still goes through an implementer/Worker role, or the run records an honest downgrade before editing.
 
 **WF-Max-Strict** (explicit `--strict`, `strict wf-max`, or `strict mode`): unconditional fan-out per span formula. Every file gets a Worker.
 
+## Mandatory Fan-Out Contract
+
+`/wf-max` MUST attempt native subagent fan-out before implementation planning is considered complete. A solo controller path is allowed only after an explicit degradation record.
+
+Minimum W0 attempt:
+
+- Start `task-scribe` when available to maintain task state and the dispatch ledger.
+- Start at least one independent read-only planning/exploration/review lane. For real multi-domain tasks, prefer `explore-manager` plus scoped researchers or codebase explorers.
+- Record `fanoutAttempted: true`, runtime, channel tried, agents requested, configured/runtime limit facts, result, and degradation reason in the task PLAN or PROGRESS.
+
+Mode interaction:
+
+- WF-Max-Useful may shrink the fan-out after the first native attempt when write sets or review lenses are not meaningfully independent. It may not silently skip the attempt.
+- WF-Max-Strict continues through the span formula until the Harness caps, runtime caps, user budget, or safety gates stop dispatch.
+- If native manager fan-out is unavailable, the controller dispatches leaf agents directly with exact WF-MAX dispatch packets; if no independent channel exists, stop honestly and ask the user.
+
+OpenCode-specific requirement: project `opencode.json` must set `subagent_depth >= 2` for manager -> worker nesting, and WF-MAX manager agents must expose `permission.task` allowlists for their child agents. Without those two settings, OpenCode may accept `/wf-max` but fail to fan out from manager subagents.
+
 ## CEO Contract
 
 CEO reads, plans, dispatches, synthesizes, and writes task state only.
 - **CEO never writes production source code.** All source edits are delegated to Workers.
+- Any new task capsule uses `task-<verb>-<noun>[-detail]` under
+  `Harness/tasks/<task-id>/`; never use bare `fix-*` task ids.
+- When updating `Harness/PROGRESS.md`, preserve required headings such as
+  `## Active Task`, `## Task Index`, and `## Cross-Task Decisions`; append or
+  update rows instead of replacing the file skeleton.
 - CEO spawns task-scribe (haiku) by default to maintain dispatch ledger, heartbeat, and evidence pointers; if unavailable, CEO records the degradation and writes only the smallest durable checkpoint.
 - CEO may spawn codebase-explorer(s) (haiku) for scoped source discovery.
 
@@ -45,7 +68,7 @@ WF-MAX Workers MUST execute as **independent agent contexts** — never as in-pr
 
 When delegating source edits to a Worker, try channels in order; descend on failure; when all independent channels are unavailable, stop honestly and ask the user — do NOT fall back to an in-process MCP tool:
 
-0. **Probe first** — before dispatching any Worker, run `node Harness/scripts/probe-worker-channels.mjs` and read the live matrix (`Harness/tasks/auto/CHANNEL-MATRIX.md`). Degrade based on facts, not assumptions. Start the chain at the highest-priority channel the probe reports `available`.
+0. **Use proven channels only** — prefer the current runtime's native subagent channel when it has already returned successfully in this session. If a peer CLI is needed, follow `.claude/skills/wf-agents-docs/SKILL.md`, keep output on stdout, and return an Evidence-Packet instead of scratch files.
 1. native subagent (preferred — independent context, bounded writeSet)
 2. `claude -p` peer CLI (independent process)
 3. `codex exec` peer CLI (independent process)
@@ -57,11 +80,11 @@ When delegating source edits to a Worker, try channels in order; descend on fail
 
 ### Timeout & Retry
 
-Every channel probe is bounded to ≤15s via `Promise.race` (see `probe-worker-channels.mjs`). A Worker dispatch that returns `unavailable-timeout` or `unavailable-error` (transient) is retried **once**; a second failure descends to the next channel in the chain. WF-MAX MUST NEVER hang on an unresponsive channel (historical failure: a 300s Codex read-only query hang, `tasks/task-framework-metrics-and-entry-contract/PLAN.md`). Bounded probes + single retry + honest descent replace silent hangs.
+Every Worker dispatch or peer-CLI call must be bounded by the controller's command timeout. A Worker dispatch that returns `unavailable-timeout` or `unavailable-error` (transient) is retried **once**; a second failure descends to the next channel in the chain. WF-MAX MUST NEVER hang on an unresponsive channel (historical failure: a 300s Codex read-only query hang, `tasks/task-framework-metrics-and-entry-contract/PLAN.md`). Bounded calls + single retry + honest descent replace silent hangs.
 
-### Probe the current environment
+### Capability Evidence
 
-Run `node Harness/scripts/probe-worker-channels.mjs` to get the live availability + independence matrix (see `tasks/auto/CHANNEL-MATRIX.md`). Degrade based on facts, not assumptions.
+Record the channel actually used, command/tool form, timeout, exit status, and a <=250 token Evidence-Packet in the task capsule. Do not create ad hoc probe scripts or write peer-CLI output to `%TEMP%`; persistent evidence belongs only under the current task's `evidence/` directory when it is intentionally part of the task record.
 
 ## Parallelism Priority
 
@@ -99,11 +122,21 @@ WF-MAX fan-out is bounded. Unbounded worker dispatch is forbidden.
 - **Overflow discipline**: Cross-CLI overflow (Codex → Claude, Claude → Codex) is allowed only after native subagent pool is genuinely exhausted (not just busy). Each overflow dispatch costs context; prefer closing completed agents first.
 - **Idle workers**: Close completed agents before declaring the pool exhausted. Do not spawn new workers while idle capacity is available.
 
+## Runtime Capacity Map
+
+Harness treats vendor/runtime limits as outer ceilings, not as permission to exceed the WF-MAX caps above.
+
+| Runtime | Native limit/config surface | Harness rule |
+| --- | --- | --- |
+| Claude Code | Official docs describe subagent caps for session total `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` (default 200), concurrency `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (default 20), and spawn depth `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` (default 3); use current Claude Code agent/subagent settings when available. | Record the detected limit/source when known; Harness WF-MAX caps still apply unless the user approves a task-local override. Do not raise environment limits without user approval. |
+| Codex | Official manual documents `[agents].max_concurrent_threads_per_session`; `agents.max_threads` is a legacy alias. Local codex-cli 0.144.x can reject scalar `[agents]` caps from project `.codex/config.toml` during TUI `skills/list`. | Do not scaffold Codex scalar agent caps into `.codex/config.toml`. Probe the installed runtime first; Harness manages a conservative task-local cap through the dispatch ledger unless `codex --strict-config doctor` verifies the config shape. |
+| OpenCode | Official config uses `subagent_depth`; default `1` permits primary -> subagent but blocks subagent -> subagent. `0` disables subagent launches; `2` permits one nested manager -> worker level. No official concurrent-count cap was found in the current docs. | Generated config sets `subagent_depth = 2`; Harness manages total/per-wave counts through WF-MAX caps and manager `permission.task` allowlists. |
+
 ## Organization Model
 
 ```
 CEO(1) -> Manager_1(span) -> Worker_1..n
-       -> Manager_2(span) -> Sub-Manager(span) -> Worker_1..n
+       -> Manager_2(span) -> Worker_1..n
 ```
 
 ## D-GATE
@@ -116,7 +149,7 @@ D-GATE is mandatory before implementation waves per [WF-KERNEL.md](WF-KERNEL.md)
 2. Close completed agents; fill idle slots immediately.
 3. Cross-CLI overflow: use an available peer CLI with explicit dispatch packets: `claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`.
 4. Bounded-pass fallback only when subagents and overflow are exhausted.
-5. Generated Codex config defaults to `agents.max_threads = 12` and `agents.max_depth = 1`. Ask the user before raising `agents.max_threads` above that default. Keep `max_depth = 1` unless recursive delegation is explicitly approved.
+5. Codex compatibility guard: do not write scalar `[agents]` capacity fields into project `.codex/config.toml` by default. Probe the installed version first; local codex-cli 0.144.x has been observed to reject those fields during TUI `skills/list`. Harness manages Codex WF-MAX concurrency through the dispatch ledger and asks the user before any project/global Codex config change.
 6. Do not rely on Codex++, undocumented config, environment variables, forked/derived conversations, or third-party forks as stable capacity.
 
 ## Anti-Patterns and Sizing

package/templates/common/Harness/specs/workflows/WF-STATE.md

@@ -0,0 +1,141 @@
+# WF-STATE - Lightweight Resumable State Machine
+
+Purpose: persist resumable workflow state across compaction, new Claude Code
+windows, new terminals, and project reopen. It is NOT a scheduler, daemon, lock
+manager, async runtime, or graph framework.
+
+## State Files
+
+| File | Role |
+|------|------|
+| `Harness/PROGRESS.md` | Derived global active pointer and Task Index |
+| `Harness/tasks/<task-id>/STATE.json` | Canonical machine-readable resume truth |
+| `Harness/tasks/<task-id>/PROGRESS.md` | Human-readable summary |
+| `Harness/tasks/<task-id>/PLAN.md` | Plan, decisions, scope context |
+
+Task id convention: new task capsules MUST use
+`task-<verb>-<noun>[-detail]` (kebab-case, 2-5 words after the prefix), for
+example `task-fix-login-flow`. Do not create bare task names such as
+`fix-login-flow`.
+
+## Enums
+
+### status
+
+`active`, `blocked`, `in_progress`, `running`, `pending`,
+`needs-user-decision`, `complete`, `verified`, `archived`, `abandoned`,
+`obsolete`, `done`, `closed`, `closeout`, `skipped`, `failed`
+
+### phase
+
+`intake`, `clarify`, `requirements`, `prd`, `acceptance`, `plan`, `explore`,
+`implement`, `verify`, `review`, `fix`, `reflect`, `closeout`, `blocked`,
+`verified`, `archived`
+
+Legacy aliases such as `Implementation`, `Validation`, and
+`Verified/Complete` are normalized by `task-state.mjs`.
+
+### item status (queues)
+
+`pending`, `ready`, `running`, `done`, `blocked`, `skipped`, `failed`
+
+### mode
+
+`direct`, `wf`, `wf-max`, `wf-auto`, `wf-auto-spark`, `wf-review`,
+`wf-browser`
+
+### tier
+
+`none`, `light`, `standard`, `full`, `max-useful`, `max-strict`
+
+## Rules
+
+1. **STATE.json is machine-readable resume truth.** On session start, the agent
+   reads it to know where it left off.
+2. **PROGRESS.md is human-readable summary.** It mirrors key state but is
+   secondary for machine reasoning and may be rewritten from state.
+3. **PLAN.md is plan/decision context.** Load only when decisions or scope need
+   review.
+4. **On every phase transition, dispatch return, blocker, verification result,
+   review finding, or closeout, update STATE.json through
+   `Harness/scripts/task-state.mjs` when the command covers the change.**
+   task-scribe or controller writes; production agents never write task state.
+5. **Long logs/transcripts never go into STATE.json.** Store paths only.
+6. **task-scribe may update STATE.json and task summaries; production agents may
+   not.**
+7. **If STATE.json conflicts with PLAN/PROGRESS, controller stops and reconciles
+   before continuing.**
+
+## CLI Contract
+
+Use `Harness/scripts/task-state.mjs` as the deterministic state writer:
+
+- `node Harness/scripts/task-state.mjs list --json`
+- `node Harness/scripts/task-state.mjs validate --json`
+- `node Harness/scripts/task-state.mjs reconcile --dry-run --json`
+- `node Harness/scripts/task-state.mjs reconcile --apply`
+- `node Harness/scripts/task-state.mjs set-active <task-id>`
+- `node Harness/scripts/task-state.mjs transition <task-id> --status <status> --phase <phase>`
+- `node Harness/scripts/task-state.mjs archive --keep 5 --dry-run --json`
+- `node Harness/scripts/task-state.mjs archive --keep 5 --apply`
+
+Do not rely on prompt instructions alone to keep active task, task `STATE.json`,
+task `PROGRESS.md`, and root `Harness/PROGRESS.md` synchronized.
+
+## Resume Protocol
+
+New window / session start:
+
+1. Read `CLAUDE.md`.
+2. If user says "continue", "resume", "last task", "current task", "status",
+   or the work is not a simple direct task:
+   - Read `Harness/PROGRESS.md` and find Active Task.
+   - If Active Task exists, read `Harness/tasks/<active-task>/STATE.json`.
+   - Read `Harness/tasks/<active-task>/PROGRESS.md`.
+   - Read `Harness/tasks/<active-task>/PLAN.md` only if decisions/scope need review.
+3. From STATE.json, determine:
+   - Current phase, gate, tier.
+   - activeQuestion (needs user answer before proceeding).
+   - Queues: ready (can dispatch immediately), running (awaiting results),
+     blocked (needs resolution), done.
+   - nextAction (what to do next).
+4. Do NOT bulk-read `Harness/tasks/` to find context. Use the active pointer.
+5. Direct simple tasks may skip STATE/PLAN/PROGRESS unless the user says
+   "continue"/"resume".
+
+## State Transitions
+
+```text
+intake -> clarify -> requirements -> prd -> acceptance -> plan
+-> explore -> implement -> verify -> review
+-> (fix -> verify -> review loop)
+-> reflect -> closeout
+```
+
+Any phase may transition to `blocked` if a dependency, user decision, or external
+input is required.
+
+## Dispatch Ledger
+
+Every dispatch packet MUST have an `id`. On return, controller or task-scribe
+updates the ledger item:
+
+- `id`, `agent`, `role`, `phase`, `status` (`pending`, `ready`, `running`,
+  `done`, `blocked`, `skipped`, `failed`), `evidence`
+
+See [WF-KERNEL.md](WF-KERNEL.md) for the dispatch packet format.
+
+## Integration with /wf and /wf-max
+
+- `/wf` uses the STATE ready queue for dynamic orchestration.
+- `/wf-max` uses the SAME STATE ready queue for maximum safe fan-out.
+- When a subagent returns or goes idle, controller immediately dispatches the
+  next ready item.
+- task-scribe is the exception for task-state writes.
+- Production source agents do not write STATE/PLAN/PROGRESS unless explicitly
+  dispatched as task-scribe.
+
+## Template
+
+See `Harness/tasks/_template/STATE.json` for the canonical template. On task
+creation, copy and populate from the template.

package/templates/common/Harness/{WF.md → specs/workflows/WF.md}

@@ -17,6 +17,10 @@ All WF variants (`/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, `
 
 Resumable state follows [WF-STATE.md](WF-STATE.md): STATE.json is the machine-readable resume truth; the ready queue is persisted there across sessions.
 
+New task capsules MUST use task ids matching `task-<verb>-<noun>[-detail]`
+and live under `Harness/tasks/<task-id>/`; never create bare task directories
+like `fix-login`.
+
 This file defines the `/wf` user contract, tiers, and the standard orchestration loop.
 
 ## Trigger
@@ -34,6 +38,13 @@ These are NOT WF triggers:
 2. Load `Harness/memory/*` only when `MEMORY_PROTOCOL.md` scenario hints match.
 3. Record `Memory preflight: done` and `Memory hints: none | <file/path + reason>`.
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+listed router/workflow loads in stable order, load only routed skills/tools, and
+append task state, current runtime facts, and latest tool output after the
+stable docs. Do not bulk-load skill bodies, tool schemas, or `Harness/`.
+
 ## Standard Orchestration Loop
 
 The `/wf` kernel follows a dependency-driven ready-queue, NOT a fixed serial phase list.
@@ -126,7 +137,7 @@ Second wave — after synthesis:
 
 ## Browser and API Evidence
 
-See [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) and [WF-KERNEL.md](WF-KERNEL.md) Task Type Routing for UI/browser and API/backend task types.
+See [HARNESS_BRIDGE.md](../protocols/HARNESS_BRIDGE.md) and [WF-KERNEL.md](WF-KERNEL.md) Task Type Routing for UI/browser and API/backend task types.
 
 Agents live under `.claude/agents/` and `.opencode/agents/`. Task state lives under `Harness/tasks/<task-id>/`.
 

package/templates/common/README.md

@@ -26,21 +26,23 @@ Replace the examples with the real commands discovered from this project. If a c
 
 - Keep branch, commit, pull request, CI, and release conventions in this README.
 - Do not place build scripts, git policy, or project maintenance instructions in `CLAUDE.md`.
-- Keep code architecture notes in `Harness/architecture.md` or feature docs.
+- Keep code architecture notes in `Harness/project/architecture.md` or feature docs.
 - For README improvements, use `.claude/skills/wf-readme/SKILL.md`; preserve public docs unless a rewrite is approved.
 
 ## Harness
 
 The agentic engineering harness lives in `Harness/`.
 
-- Follow `Harness/SETUP.md` before normal work while it exists.
-- Start at `Harness/README.md`.
-- Load memory and resource registrations from `Harness/MEMORY.md`.
+- Normal agent sessions start from `CLAUDE.md`.
+- Use `Harness/specs/guides/SETUP.md` only for install/bootstrap guidance, migration, upgrade decisions, or explicit setup requests.
+- Use `Harness/README.md` as the Harness workflow router when a routed task needs it.
+- Load memory and resource registrations from `Harness/MEMORY.md` only when routed.
 - Track active work in `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md`.
-- Use `Harness/WF.md` only when the user explicitly invokes a WF command such as `/wf` or `/wf-max`; complex work may still use direct planning, tests, and subagents without entering WF.
+- Use `/wf-update` or `$wf-update` for Harness upgrades; the agent should report version, changed files, validation results, and release highlights from update metadata.
+- Use `Harness/specs/workflows/WF.md` only when the user explicitly invokes a WF command such as `/wf` or `/wf-max`; complex work may still use direct planning, tests, and subagents without entering WF.
   - Claude Code: invoke the `wf` skill with `/wf`.
   - Codex: invoke the `wf` skill with `$wf` or `/skills`.
-- Use `Harness/subagents.md` when coordinating multiple agents.
+- Use `Harness/specs/runtime/subagents.md` when coordinating multiple agents.
 
 Tool discovery files stay at the repository root:
 

package/templates/common/memory/startup-hints.md

@@ -1,32 +1,34 @@
 # Startup Hints (L2 Memory Digest)
 
-> L2 = 启动极简 memory digest。每次 Harness 会话启动可读此文件，但不要加载完整 Harness/MEMORY.md 或 Harness/README.md。
+> L2 = lightweight startup memory digest. New Harness sessions may read this
+> file after `CLAUDE.md`, but must not load full `Harness/MEMORY.md`,
+> `Harness/README.md`, or `Harness/PROGRESS.md` during thin startup.
 
 ## Core Principles
 
-- Memory 是短场景规则，不是 task log。
-- 时间戳默认不要写；只有 superseded / conflict / time-sensitive 才写。
-- Broad runtime hooks 禁止；只有 `/wf-auto` bounded tick hook 例外。
-- Direct mode 不加载完整 Harness router，但 startup-hints 是允许的轻量启动提示。
-- 详细 memory 仍按 `MEMORY_PROTOCOL.md` 场景命中后再读。
+- Memory is short scenario guidance, not a task log.
+- Do not write timestamps by default; write only durable, reusable guidance.
+- Broad runtime hooks are forbidden. The only Harness exception is the bounded `/wf-auto` tick hook.
+- Direct mode must not load the full Harness router. `startup-hints.md` is the lightweight startup allowance.
+- Detailed memory still loads only when routed through `MEMORY_PROTOCOL.md`.
 
 ## Memory Candidate Detection
 
-用户说以下触发词时，识别为 memory candidate：
+Treat these as memory candidates:
 
-**英文**: remember, next time, don't, do not, never, always, I prefer, I want you to
-**中文**: 记住, 下次, 以后, 不要再, 总是, 永远不要, 我偏好, 我希望你以后
+- English: remember, next time, don't, do not, never, always, I prefer, I want you to
+- Chinese: 记住, 下次, 以后, 不要再, 总是, 永远不要, 我偏好, 我希望你以后
 
 ## When to Write Memory
 
-- **Explicit user preference**: 清晰、安全、场景明确时，可立即写入 L3，不必等 `/wf-learn`。
-- **Repeated implicit correction**: 同一假设/模式被纠正 2+ 次。
-- **Tool/command failure**: 同类工具/命令失败 3+ 次。
-- **Review/debug lesson**: 只有可复用、能防回归时才写。
+- Explicit user preference: write immediately only when clear, safe, and reusable.
+- Repeated implicit correction: same assumption or pattern corrected 2+ times.
+- Tool/command failure: same tool or command pattern fails 3+ times.
+- Review/debug lesson: write only when it is reusable and can prevent regressions.
 
 ## What NOT to Write
 
-- Task log、过程总结、一次性情绪
-- Raw logs、transcripts
-- Secrets, tokens, credentials, private data
-- 临时偏好、无复用价值的笔记
+- Task logs, process summaries, or one-off emotions.
+- Raw logs or transcripts.
+- Secrets, tokens, credentials, or private data.
+- Temporary preferences or notes with no reusable value.

package/templates/common/opencode.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "instructions": [".claude/rules/ecc/common.md"],
+  "subagent_depth": 2,
   "permission": {
     "bash": {
       "*": "ask",

package/templates/optional/catalog.json

@@ -1,12 +1,5 @@
 {
   "skills": [
-    {
-      "id": "browser-e2e",
-      "title": "Browser E2E",
-      "description": "Mandatory real-browser smoke workflow using Playwright, Chrome DevTools/CDP, or documented manual evidence.",
-      "files": ["skills/browser-e2e"],
-      "tags": ["e2e", "browser", "playwright", "cdp"]
-    },
     {
       "id": "ui-ux-review",
       "title": "UI/UX Review",
@@ -37,8 +30,8 @@
     }
   ],
   "presets": {
-    "web-app": ["ts-react-frontend", "browser-e2e", "ui-ux-review"],
-    "fullstack": ["ts-react-frontend", "python-backend", "browser-e2e", "github-pr-review"]
+    "web-app": ["ts-react-frontend", "ui-ux-review"],
+    "fullstack": ["ts-react-frontend", "python-backend", "github-pr-review"]
   },
   "externalRecommendations": [
     {

package/templates/optional/skills/github-pr-review/.claude/skills/github-pr-review/SKILL.md

@@ -37,4 +37,4 @@ Update `Harness/tasks/<task-id>/PLAN.md` only when the PR review is part of a tr
 
 ## dispatch.md Usage
 
-Use `Harness/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.
+Use `Harness/specs/runtime/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.

package/templates/optional/skills/python-backend/.claude/skills/python-backend/SKILL.md

@@ -37,4 +37,4 @@ Update `Harness/tasks/<task-id>/PLAN.md` only when executing a tracked plan item
 
 ## dispatch.md Usage
 
-Use `Harness/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.
+Use `Harness/specs/runtime/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.

package/templates/optional/skills/ts-react-frontend/.claude/skills/ts-react-frontend/SKILL.md

@@ -40,4 +40,4 @@ Update `Harness/tasks/<task-id>/PLAN.md` only when executing a tracked task or r
 
 ## dispatch.md Usage
 
-Use `Harness/dispatch.md` when independent frontend tasks can run in parallel, such as components, tests, and browser checks.
+Use `Harness/specs/runtime/dispatch.md` when independent frontend tasks can run in parallel, such as components, tests, and browser checks.

package/templates/optional/skills/ui-ux-review/.claude/skills/ui-ux-review/SKILL.md

@@ -37,4 +37,4 @@ Update current task `tasks/<id>/PLAN.md` only for tracked review tasks or when r
 
 ## dispatch.md Usage
 
-Use `Harness/dispatch.md` only for independent review streams such as separate routes or breakpoints.
+Use `Harness/specs/runtime/dispatch.md` only for independent review streams such as separate routes or breakpoints.