create-harness-vibe-coding 0.8.12 → 0.8.16

package/templates/common/.claude/skills/wf-agents-docs/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: wf-agents-docs
+description: Source-backed CLI invocation guide for Claude Code, Codex, and OpenCode automation. Use when invoking peer CLIs, writing batch tests, collecting cache telemetry, debugging command-line flags, or documenting cross-runtime agent usage for Harness workflows.
+---
+
+# WF Agents Docs
+
+Use this skill before shelling out to `claude`, `codex`, or `opencode` from Harness workflows, peer review, cache tests, or automation scripts.
+
+## Source Order
+
+1. Prefer installed help: `claude --help`, `codex exec --help`, `opencode run --help`.
+2. Check official docs for flags that affect cost, auth, JSON, resume, tools/MCP, or telemetry.
+3. When adding automation, record command, source, stdout/stderr shape, and failed patterns.
+
+## Claude Code CLI
+
+- Interactive: `claude`.
+- Non-interactive JSON: pipe ASCII or UTF-8-safe stdin into `claude -p --output-format json`.
+- Stream JSON requires verbose mode: `claude -p --output-format stream-json --verbose`.
+- Continue/resume: `claude -c -p "..."` or `claude -p --resume <session-id> "..."`; for PowerShell automation, prefer stdin and validate non-empty JSON before parsing.
+- Use `--max-budget-usd <amount>` in scripted probes.
+- Use `--strict-mcp-config` without `--mcp-config` to ignore configured MCP servers for a run. Use `--safe-mode` only to disable project customizations. Use `--bare` only for minimal CLI probes, not for Harness/cache attribution, because it skips `CLAUDE.md`, skills, plugins, MCP, hooks, and auto memory.
+- Use `--tools "Read,Grep,Glob"` or explicit `--allowedTools`/`--disallowedTools` for read-only probes.
+- Prompt-cache telemetry appears in JSON `usage.cache_read_input_tokens` / `usage.cache_creation_input_tokens`, and in statusline `context_window.current_usage.*`.
+
+## Codex CLI
+
+- Interactive: `codex`.
+- Non-interactive: `codex exec "task"`.
+- Read stdin as the full prompt: `cat prompt.txt | codex exec -`.
+- Prompt plus stdin context: `some-command | codex exec "summarize this output"`.
+- Machine output: `codex exec --json "task"` emits JSONL events; parse `turn.completed.usage`, including `cached_input_tokens` when present.
+- Resume: `codex exec resume --last "..."` or `codex exec resume <SESSION_ID> "..."`.
+- Permissions: default is read-only; set `--sandbox workspace-write` only when edits are required. Use `--ignore-user-config` / `--ignore-rules` for controlled automation.
+
+## OpenCode CLI
+
+- Interactive: `opencode`.
+- Non-interactive: `opencode run [message..]`.
+- JSON events: `opencode run --format json "task"`.
+- Resume: `opencode run --continue "..."` or `opencode run --session <id> "..."`.
+- Peer role: `opencode run --agent reviewer --dir . "review prompt"`.
+- Reuse a server to avoid MCP cold boot: `opencode serve`, then `opencode run --attach http://localhost:4096 "task"`.
+- On Windows, first verify `opencode` exists before writing automation around it.
+
+## PowerShell Automation Rules
+
+- Prefer stdin over trailing prompt args for `claude -p` in PowerShell.
+- Use ASCII prompts or explicitly UTF-8-safe input for automated probes.
+- Do not trust exit code alone. Fail on empty/non-JSON stdout or error/budget terminal fields.
+- Avoid naming function parameters `$Args`; PowerShell treats `$Args` specially.
+- Store telemetry outside the repo, e.g. `$HOME/.claude/cache-telemetry/*.json`, so git status does not perturb prefixes.
+
+## Evidence-Packet Review Pattern
+
+For peer review, route smokes, cache analysis, and audits, gather evidence
+first; the peer judges only the bounded packet.
+
+- Gather paths, line snippets, command names, exits, and invariants with `rg`,
+  `node` scripts, validators, or small reads.
+- Send only that packet. Exclude full docs, raw logs, timestamps, session IDs,
+  and screenshots unless they are the evidence.
+- Prefer no tools for judgment-only review; otherwise allow only read-only
+  tools and name the exact read set.
+- Controller accepts, rejects, or escalates findings. Peers do not own scope.
+
+## No Scratch-File Rule
+
+- Do not write CLI probe output under `%TEMP%`, `$env:TEMP`, `/tmp`, or other
+  system temp directories.
+- Prefer stdout, JSON/JSONL streaming, or in-memory parsing.
+- Persistent repo evidence goes under `Harness/tasks/<task-id>/evidence/`.
+- Cache telemetry may live under `$HOME/.claude/cache-telemetry/` to avoid repo
+  prompt-cache churn.
+- Do not create prompt temp files. Use stdin.
+
+## Subagent Output Contract
+
+Require bounded structured returns:
+
+```text
+Agent: <claude|codex|opencode|role name>
+Probe: <what was tested or reviewed>
+Mode: <read-only|review|telemetry|implementation>
+Files examined: <exact paths or none>
+Evidence: <commands, exit codes, paths, line refs>
+Passes: <confirmed invariants>
+Findings: <severity, file/path, reason, suggested fix>
+Risks: <residual uncertainty or none>
+Tool/CLI issues: <auth, timeout, budget, JSON parse, MCP, or none>
+Verdict: PASS | FAIL | BLOCKED
+Next: <smallest next controller action>
+```
+
+For JSON, use the same keys. Do not return transcripts, full file bodies, decorative logs, or speculation.
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: stable instructions first, volatile output in the dynamic suffix, and no provider cache claims without telemetry. Claude Code L2 uses `cache_read_input_tokens`; Codex JSONL may emit `cached_input_tokens`.
+
+## Batch-Test Pattern
+
+1. Probe command availability with `Get-Command claude,codex,opencode -ErrorAction SilentlyContinue`.
+2. Build a compact evidence packet before invoking peer agents; use the peer
+   only for judgment unless the test explicitly requires live agent discovery.
+3. Run a cold turn and capture session id.
+4. Resume that session for two warm turns.
+5. For each turn record input, cache creation, cache read, ratio, cost, model/session id, and exact flags.
+6. Compare against a control mode. Do not attribute a provider-wide cache feature to Harness unless the Harness-shaped run improves or stabilizes cache behavior against a comparable baseline.
+
+## Official References
+
+- Claude Code CLI reference: https://code.claude.com/docs/en/cli-reference
+- Claude Code prompt caching: https://code.claude.com/docs/en/prompt-caching
+- Claude Code status line schema: https://code.claude.com/docs/en/statusline
+- Codex CLI: https://developers.openai.com/codex/cli
+- Codex non-interactive mode: https://learn.chatgpt.com/docs/non-interactive-mode
+- OpenCode CLI: https://opencode.ai/docs/cli/

package/templates/common/.claude/skills/wf-auto/SKILL.md

@@ -5,15 +5,32 @@ description: Perpetual adaptive auto-optimization mode. Selects probes from proj
 
 # WF Auto - Perpetual Auto-Optimization
 
+## Memory Preflight
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` index only, then `Harness/README.md`
+   before planning, dispatch, edits, validation, or review.
+2. Load detailed `Harness/memory/*` files only when `MEMORY_PROTOCOL.md`
+   scenario hints match; otherwise record "memory hints: none".
+
 ## Load
 
-- `Harness/WF-AUTO.md`
-- `Harness/WF-AUTO-ANGLES.md`
-- `Harness/subagents.md`
-- `Harness/dispatch.md`
-- `Harness/agent-workflow.md`
+- `CLAUDE.md`
+- `Harness/MEMORY.md` (index only per Memory Preflight)
+- `Harness/README.md`
+- `Harness/specs/workflows/WF-AUTO.md`
+- `Harness/specs/workflows/WF-AUTO-ANGLES.md`
+- `Harness/specs/runtime/subagents.md`
+- `Harness/specs/runtime/dispatch.md`
+- `Harness/specs/runtime/agent-workflow.md`
 - `.claude/skills/wf-review/SKILL.md`
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+auto-mode docs in listed order, run selected probes only, append fresh probe
+outputs last, and record compact evidence instead of carrying full logs between
+cycles.
+
 ## Trigger
 
 - Claude `/wf-auto`
@@ -44,6 +61,9 @@ that auto scanning costs more than it helps.
    below 3.
 8. Intent Checkpoint is adaptive: 2 -> 5 -> 10 cycles, exactly two questions.
 9. Record compact evidence per cycle; do not paste full logs or transcripts.
+10. A bounded test tick still creates or updates `Harness/tasks/auto/PLAN.md`
+    and `Harness/tasks/auto/PROGRESS.md`; missing auto capsule evidence is a
+    failed cycle record.
 
 ## Loop
 
@@ -58,5 +78,5 @@ LOOP: next W0
 
 ## Return
 
-Report cycles run, findings addressed by source, evidence ledger, exhaustion
-evidence if any, weak spark count, final state, and residual risks.
+Report cycles run, findings addressed by source, evidence ledger path/summary,
+exhaustion evidence if any, weak spark count, final state, and residual risks.

package/templates/common/.claude/skills/wf-auto-spark/SKILL.md

@@ -5,7 +5,7 @@ description: Perpetual inspiration mode for /wf-auto-spark or $wf-auto-spark. In
 
 # WF-AUTO-SPARK Adapter
 
-The authoritative workflow lives in `Harness/WF-AUTO-SPARK.md`; this adapter
+The authoritative workflow lives in `Harness/specs/workflows/WF-AUTO-SPARK.md`; this adapter
 only routes and summarizes hard constraints.
 
 ## Invocation
@@ -18,10 +18,17 @@ only routes and summarizes hard constraints.
 1. `CLAUDE.md`
 2. `Harness/MEMORY.md`
 3. `Harness/README.md`
-4. `Harness/WF-AUTO-SPARK.md`
-5. `Harness/WF-AUTO.md`
-6. `Harness/subagents.md`
-7. `Harness/dispatch.md`
+4. `Harness/specs/workflows/WF-AUTO-SPARK.md`
+5. `Harness/specs/workflows/WF-AUTO.md`
+6. `Harness/specs/runtime/subagents.md`
+7. `Harness/specs/runtime/dispatch.md`
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep roadmap
+and workflow docs stable, put fresh spark search results in the dynamic suffix,
+defer unused tools/skills, and let task-scribe write compact state instead of
+replaying search transcripts.
 
 ## Rules
 

package/templates/common/.claude/skills/wf-learn/SKILL.md

@@ -22,6 +22,12 @@ fallback.
 - `Harness/memory/agent-lessons-patterns.md`
 - Current `Harness/PROGRESS.md` and active task capsule, if any
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: load memory
+indexes first, then only the routed detailed memory files; summarize durable
+patterns by file path and signal instead of pasting session transcripts.
+
 ## Flow
 
 1. Analyze the session for repeated failures, durable user corrections, and

package/templates/common/.claude/skills/wf-max/SKILL.md

@@ -5,7 +5,7 @@ description: Use for /wf-max in Claude Code, $wf-max or /skills wf-max in Codex.
 
 # WF-MAX Adapter
 
-The authoritative workflow lives in `Harness/WF-MAX.md`; this adapter only
+The authoritative workflow lives in `Harness/specs/workflows/WF-MAX.md`; this adapter only
 routes and summarizes hard constraints.
 
 ## Invocation
@@ -24,35 +24,50 @@ routes and summarizes hard constraints.
 1. `CLAUDE.md`
 2. `Harness/MEMORY.md` (index only per Memory Preflight)
 3. `Harness/README.md`
-4. `Harness/WF-MAX.md`
-5. `Harness/subagents.md`
-6. `Harness/dispatch.md`
-7. `Harness/agent-workflow.md`
+4. `Harness/specs/workflows/WF-MAX.md`
+5. `Harness/specs/runtime/subagents.md`
+6. `Harness/specs/runtime/dispatch.md`
+7. `Harness/specs/runtime/agent-workflow.md`
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep the
+listed loads in order, defer unused skill/tool schemas, append volatile task
+state and runtime facts last, and bound Worker returns through dispatch
+`MaxReturnTokens`/`ReturnSchema`.
 
 ## Rules
 
 WF-MAX inherits the selected WF tier and the shared WF-KERNEL gates
-(`Harness/WF-KERNEL.md`), then expands safe parallelism. WF-Max-Useful is
+(`Harness/specs/workflows/WF-KERNEL.md`), then expands safe parallelism. WF-Max-Useful is
 default; WF-Max-Strict only on explicit strict request. Execution expands
 through:
 
+- New task state directories MUST use task ids matching
+  `task-<verb>-<noun>[-detail]` under `Harness/tasks/<task-id>/`; never
+  create bare `fix-*` task ids.
 1. Global mode: `wf-max`
 2. Agent role: `ceo | manager | worker | reviewer | verifier | reflector`
 3. Dispatch permission: `writeSet`, `forbidden`, `verification`
 
 WF-Max-Useful (default): `/wf-max` fans out only where write sets or review
 lenses are meaningfully independent. Overhead > 0.30 degrades the wave.
+Degrading fan-out 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 override): user says `--strict`, `strict wf-max`, or
 `strict mode`. Unconditional fan-out per the original span formula.
 
 - CEO reads, plans, dispatches, synthesizes, and writes task state only. CEO
   never edits production source.
+- Task-state updates must preserve required `Harness/PROGRESS.md` headings:
+  `## Active Task`, `## Task Index`, and `## Cross-Task Decisions`.
 - Workers edit only the dispatch `writeSet`; outside write set is blocked.
 - Managers coordinate and synthesize. Reviewers read/report only.
 - D-GATE is mandatory before implementation waves: dispatch table, AC IDs,
   disjoint file claims, self-audit, and reviewer plan.
-- Final acceptance is tier-aware per `Harness/WF-KERNEL.md`:
+- Final acceptance is tier-aware per `Harness/specs/workflows/WF-KERNEL.md`:
   - WF-Light + `/wf-max`: verification + state evidence suffices unless risk
     triggers review/reflector.
   - WF-Standard + `/wf-max`: verifier evidence + one independent review PASS.

package/templates/common/.claude/skills/wf-readme/SKILL.md

@@ -14,7 +14,13 @@ Improve `README.md` without breaking project-owned public docs.
 - CI files when present
 - `Harness/PROGRESS.md`
 - `Harness/tasks/<task-id>/PLAN.md` when available
-- `Harness/architecture.md` only when an architecture summary or diagram is requested
+- `Harness/project/architecture.md` only when an architecture summary or diagram is requested
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: load project
+facts in the listed order, inspect only relevant README/package/CI sections, and
+keep unknowns or command output in the dynamic suffix.
 
 ## Mode
 
@@ -34,7 +40,7 @@ If unanswered, use Preserve + append.
 - Do not invent features, benchmarks, roadmap, support policy, badges, install commands, or CI status.
 - Use tables for command matrices, environment variables, endpoints, and deployment notes when facts are known.
 - Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
-- Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
+- Keep detailed architecture in `Harness/project/architecture.md`; README may link to it or show a short overview.
 - Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
 - Record the chosen mode and any skipped README improvements in `Harness/tasks/<task-id>/PLAN.md` when available.
 

package/templates/common/.claude/skills/wf-remove/SKILL.md

@@ -18,6 +18,12 @@ description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove
 - `Harness/.harness-version`
 - `Harness/scripts/wf-remove.mjs`
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: use the
+script's compact JSON plan as the dynamic suffix, avoid manual directory dumps,
+and keep user decisions in task progress rather than chat transcript.
+
 ## Flow
 
 1. On plain `/wf-remove`, run `node Harness/scripts/wf-remove.mjs --json` for

package/templates/common/.claude/skills/wf-review/SKILL.md

@@ -22,6 +22,13 @@ The main agent is the controller. It owns final decisions, accepted/rejected
 findings, fixes, release claims, and user-facing recommendations. Review
 agents only provide evidence-backed suggestions.
 
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: build review
+context from changed-file lists, ACs, validation evidence, and targeted diffs;
+avoid pasting unrelated history, full transcripts, or unused tool schemas into
+the review prompt.
+
 ## Runtime Selection
 
 1. Build one review prompt containing the relevant diff, task acceptance
@@ -66,8 +73,8 @@ AgentName: reviewer
 Mode: read-only
 Objective: review the current diff for correctness, security, architecture,
 performance, tests, and spec/AC compliance
-Read set: changed files, tests, task PLAN/PROGRESS, Harness/agent-workflow.md,
-Harness/subagents.md, Harness/dispatch.md, architecture docs when affected
+Read set: changed files, tests, task PLAN/PROGRESS, Harness/specs/runtime/agent-workflow.md,
+Harness/specs/runtime/subagents.md, Harness/specs/runtime/dispatch.md, architecture docs when affected
 Write set: none
 Forbidden: file edits, git mutations, formatting-only advice, ungrounded claims
 ReturnSchema: findings by severity, file/line refs, missing verification,
@@ -80,6 +87,6 @@ deduplicate reviewer output and decide what to accept.
 
 ## Context
 
-Include the relevant diff, `Harness/architecture.md` when architecture is in
+Include the relevant diff, `Harness/project/architecture.md` when architecture is in
 scope, and any task acceptance criteria. If the diff is too large, ask for a
 narrower scope before invoking a peer CLI or reviewer subagent.

package/templates/common/.claude/skills/wf-update/SKILL.md

@@ -20,25 +20,65 @@ This skill is a Codex compatibility shim plus script-flow reference. Claude Code
 - `Harness/scripts/scan-clean.mjs`
 - `Harness/scripts/validate-harness.mjs`
 
+## 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.
+
+## Classification
+
+MANIFEST-FIRST. The installer and updater read
+`Harness/ownership.manifest.json`:
+
+- `preserve[]` — never touched (tasks, memory, research, root README,
+  package, architecture). `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 → conflict/skip + warning, never overwritten.
+
 ## Flow
 
 1. Run `node Harness/scripts/wf-update-check.mjs --json` first and use the
-   `agent` block as the action plan.
+   `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.
+   root README.md, package, or architecture files. 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`.
-4. For every `agent.aiMergeRequired` entry, compare the local file with
+   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.
-5. Run `node Harness/scripts/wf-update-check.mjs --finalize` after all
+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.
-6. After update, run the validator and then scan-clean.
+8. After update, run the validator and then scan-clean.
 
 ## Recovery
 
@@ -50,6 +90,13 @@ npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip
 
 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:
+
+```
+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,