create-harness-vibe-coding 0.8.13 → 0.8.16

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

@@ -18,7 +18,7 @@ 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.
 
@@ -26,6 +26,11 @@ WF-MAX is **explicit only**. Enter ONLY when the user explicitly types `/wf-max`
 
 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 +50,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 +62,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
 

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

@@ -11,6 +11,11 @@ Purpose: persist resumable workflow state across compaction, new Claude Code win
 | `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
 
 ### phase

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/optional/skills/browser-e2e/.claude/skills/browser-e2e/SKILL.md

@@ -39,4 +39,4 @@ Update `Harness/tasks/<task-id>/PLAN.md` only when executing a tracked plan item
 
 ## dispatch.md Usage
 
-Use `Harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.
+Use `Harness/specs/runtime/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

package/templates/optional/skills/browser-e2e/.claude/skills/wf-browser/SKILL.md

@@ -11,6 +11,13 @@ Load:
 - Official `browser-use` skill at `~/.claude/skills/browser-use/SKILL.md` (auto-installed if missing)
 - `Harness/PROGRESS.md` when work is active
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep workflow
+docs stable, use CLI state/screenshot paths as dynamic evidence, and avoid
+replaying full browser logs or screenshots in prompts unless a failed AC needs
+targeted inspection.
+
 ## Modes
 
 Choose based on task complexity:

package/templates/optional/skills/browser-e2e/.opencode/commands/wf-browser.md

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

@@ -20,7 +20,7 @@ Browser evidence in this project follows the contract:
 
 ### Harness Bridge
 
-For frontend-backend flows, use `Harness/HARNESS_BRIDGE.md` to validate UI
+For frontend-backend flows, use `Harness/specs/protocols/HARNESS_BRIDGE.md` to validate UI
 selectors, API payloads, seeded data, runtime state probes, and CDP/network
 traces. Browser validation must produce an AC-by-AC result matrix when the task
 has acceptance criteria.
@@ -97,12 +97,12 @@ If `browser-use` is not installed, fall back to:
 
 1. Playwright/Puppeteer MCP server (if configured)
 2. Chrome DevTools Protocol (CDP) manual inspection
-3. `Harness/WF.md#Browser And API Evidence` manual check contract
+3. `Harness/specs/workflows/WF.md#Browser And API Evidence` manual check contract
 
 ## Integration Points
 
-- **WF mode**: when browser-visible changes are made, follow the evidence contract in `Harness/WF.md#Browser And API Evidence`
-- **Harness Bridge**: use `Harness/HARNESS_BRIDGE.md` for UI contract, API contract, seeded test data, runtime state probes, and network trace collection.
+- **WF mode**: when browser-visible changes are made, follow the evidence contract in `Harness/specs/workflows/WF.md#Browser And API Evidence`
+- **Harness Bridge**: use `Harness/specs/protocols/HARNESS_BRIDGE.md` for UI contract, API contract, seeded test data, runtime state probes, and network trace collection.
 - **wf-browser**: Claude Code uses `.claude/skills/wf-browser/SKILL.md`; Codex uses `.agents/skills/wf-browser/SKILL.md`. Both load this workflow.
 - **MEMORY.md**: registered as optional workflow skill
 - **README.md**: routing table row "Browser E2E testing or automation" -> browser-e2e

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.