create-harness-vibe-coding 0.8.6 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

package/src/generator.js

@@ -350,8 +350,9 @@ function nextBackupPath(destPath) {
 }
 
 function registerOptionalContent(file, content, selectedSkills) {
-  if (!selectedSkills.length) return content;
-
+  if (!selectedSkills.length) return content;
+  const hasBrowserE2e = selectedSkills.some(skill => skill.id === 'browser-e2e');
+
   if (file === 'Harness/MEMORY.md') {
     const lines = selectedSkills.map(skill => (
       `- [${skill.id}](../.claude/skills/${skill.id}/SKILL.md) - ${skill.description} Codex mirror: [${skill.id}](../.agents/skills/${skill.id}/SKILL.md). Workflow: [workflows/${skill.id}.md](workflows/${skill.id}.md)`
@@ -360,15 +361,33 @@ function registerOptionalContent(file, content, selectedSkills) {
       'Stack-specific skills can be added after the product shape is known.',
       `Installed optional skills:\n\n${lines.join('\n')}\n\nStack-specific skills can be added after the product shape is known.`,
     );
-  }
-
-  if (file === 'Harness/README.md') {
-    const lines = selectedSkills.map(skill => (
-      `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
-    ));
-    return `${content.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
-  }
-
+  }
+
+  if (file === 'Harness/README.md') {
+    const lines = selectedSkills.map(skill => (
+      `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
+    ));
+    let next = content;
+    if (hasBrowserE2e) {
+      next = next.replace(
+        '| Optional workflow installed |',
+        '| Browser E2E testing or automation | /wf-browser, $wf-browser, browser, e2e, web automation, screenshot verify, page test, browser test, Playwright, CDP | [workflows/browser-e2e.md](workflows/browser-e2e.md), [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) | UI/API contract, CLI commands, screenshots, traces, validation matrix |\n| Optional workflow installed |',
+      );
+      next = next.replace(
+        '| `/wf-readme [task]` |',
+        '| `/wf-browser [task]` | `$wf-browser [task]` | Optional browser automation/E2E workflow when `browser-e2e` is installed |\n| `/wf-readme [task]` |',
+      );
+    }
+    return `${next.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
+  }
+
+  if (file === '.claude/commands/wf-help.md' && hasBrowserE2e) {
+    return content.replace(
+      '| `/wf-readme <task>` |',
+      '| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |\n| `/wf-readme <task>` |',
+    );
+  }
+
   return content;
 }
 

package/src/index.js

@@ -2,9 +2,13 @@
 import * as p from '@clack/prompts';
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import pc from 'picocolors';
 import { askConflictPolicy, askOptionalSelections, askProjectName, askTargetDir } from './prompts.js';
 import { generate, getOptionalCatalog } from './generator.js';
+
+const UPDATE_SUCCESS_STATUSES = new Set(['up-to-date', 'update-available', 'partial-update']);
+const UPDATE_FAILURE_STATUSES = new Set(['error', 'offline', 'template-remote', 'downgrade-refused']);
 
 // ── CLI flags ──────────────────────────────────────────────
 const raw = process.argv.slice(2);
@@ -85,6 +89,10 @@ if (generationOptions.json) {
   const projectName = argName || DEFAULT_NAME;
   const targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
+  if (scan.hasHarness) {
+    printJsonResult(createUpdateSwitchResult(scan, { json: true }));
+    process.exit(0);
+  }
   const result = generate({ projectName, targetDir, ...generationOptions });
   result.scan = createJsonScan(scan);
   result.agent = createAgentGuidance(result, {
@@ -108,11 +116,16 @@ console.log('');
 let projectName, targetDir;
 
 // Non-interactive: positionals provided OR -y/--yes flag set
-if (argName || skipPrompts) {
-  projectName = argName || DEFAULT_NAME;
-  targetDir = argDir || `./${projectName}`;
-
-  console.log(pc.dim('────────────────────────────────────────────'));
+if (argName || skipPrompts) {
+  projectName = argName || DEFAULT_NAME;
+  targetDir = argDir || `./${projectName}`;
+  const scan = scanTarget(targetDir);
+
+  if (scan.hasHarness) {
+    process.exit(runUpdateSwitch(scan, { json: false }));
+  }
+
+  console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
   console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, tests/')}`);
@@ -159,6 +172,10 @@ if (argName || skipPrompts) {
   const scan = scanTarget(targetDir);
   printScan(scan);
 
+  if (scan.hasHarness) {
+    process.exit(runUpdateSwitch(scan, { json: false }));
+  }
+
   if (!generationOptions.dryRun && !conflictPolicyProvided && scan.needsConflictPolicy) {
     try {
       generationOptions.onConflict = await askConflictPolicy(scan);
@@ -429,6 +446,113 @@ function printJsonResult(result) {
   }
 }
 
+function runUpdateSwitch(scan, { json }) {
+  const updateResult = createUpdateSwitchResult(scan, { json });
+  if (json) {
+    printJsonResult(updateResult);
+    return updateResult.success ? 0 : 1;
+  }
+
+  console.log('');
+  console.log(pc.yellow('Existing Harness detected. Switching to wf-update check.'));
+  console.log(pc.dim(`Directory   ${scan.resolvedDir}`));
+  console.log(pc.dim('Command     node Harness/scripts/wf-update-check.mjs'));
+  console.log('');
+
+  if (!updateResult.success && updateResult.error) {
+    console.error(pc.red(updateResult.error));
+    return 1;
+  }
+
+  if (updateResult.stdout) process.stdout.write(updateResult.stdout);
+  if (updateResult.stderr) process.stderr.write(updateResult.stderr);
+  return updateResult.exitCode ?? 0;
+}
+
+function getUpdateStatusError(update) {
+  if (!update || typeof update !== 'object' || typeof update.status !== 'string') {
+    return 'Update checker did not return a machine-readable status.';
+  }
+  if (UPDATE_FAILURE_STATUSES.has(update.status)) {
+    return `Update checker reported ${update.status}${update.message ? `: ${update.message}` : ''}`;
+  }
+  if (!UPDATE_SUCCESS_STATUSES.has(update.status)) {
+    return `Update checker returned unrecognized status: ${update.status}`;
+  }
+  return null;
+}
+
+function createUpdateSwitchResult(scan, { json }) {
+  const args = ['Harness/scripts/wf-update-check.mjs'];
+  if (json) args.push('--json');
+
+  const scriptPath = path.join(scan.resolvedDir, 'Harness', 'scripts', 'wf-update-check.mjs');
+  const command = `node ${args.join(' ')}`;
+  const base = {
+    success: false,
+    mode: 'update',
+    scan: createJsonScan(scan),
+    agent: {
+      sourceOfTruth: 'Existing Harness detected; install automatically switched to the target update checker. Do not continue install writes.',
+      updateCommand: json
+        ? 'node Harness/scripts/wf-update-check.mjs --json'
+        : 'node Harness/scripts/wf-update-check.mjs',
+      next: [
+        {
+          action: 'update',
+          command: json
+            ? 'node Harness/scripts/wf-update-check.mjs --json'
+            : 'node Harness/scripts/wf-update-check.mjs',
+          reason: 'Harness already exists, so updates must use the installed Harness update flow.',
+        },
+      ],
+    },
+  };
+
+  if (!fs.existsSync(scriptPath)) {
+    return {
+      ...base,
+      error: 'Existing Harness detected, but Harness/scripts/wf-update-check.mjs was not found. Install writes were skipped; inspect the existing Harness before updating manually.',
+      errors: ['Harness/scripts/wf-update-check.mjs not found'],
+    };
+  }
+
+  const result = spawnSync(process.execPath, args, {
+    cwd: scan.resolvedDir,
+    encoding: 'utf8',
+  });
+  const stdout = result.stdout || '';
+  const stderr = result.stderr || '';
+  const status = result.status ?? 1;
+
+  let update = undefined;
+  if (json && stdout.trim()) {
+    try {
+      update = JSON.parse(stdout.trim());
+    } catch {
+      update = { rawOutput: stdout };
+    }
+  }
+
+  const errors = [];
+  if (status !== 0) errors.push(`Update checker exited with status ${status}`);
+  if (json) {
+    const statusError = getUpdateStatusError(update);
+    if (statusError) errors.push(statusError);
+  }
+
+  return {
+    ...base,
+    success: errors.length === 0,
+    exitCode: status,
+    command,
+    stdout,
+    stderr,
+    ...(json ? { update } : {}),
+    ...(errors.length === 0 ? {} : { error: errors[0], errors }),
+  };
+}
+
 function scanTarget(targetDir) {
   const resolvedDir = path.resolve(process.cwd(), targetDir);
   const exists = fs.existsSync(resolvedDir);

package/templates/common/.claude/agents/reflector.md

@@ -0,0 +1,35 @@
+---
+name: reflector
+description: Use after verification and cross-review to synthesize findings, detect unresolved risk, and decide whether work may enter final acceptance.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Reflector
+
+You are the final reflection agent for the Harness workflow.
+
+Load first:
+
+- current task `PLAN.md` and `PROGRESS.md`
+- acceptance criteria and contracts
+- verifier evidence
+- reviewer findings
+- relevant diff or changed file list
+
+Rules:
+
+- Do not write files.
+- Do not rerun implementation or verification.
+- Check whether spec review and code/architecture/test review both passed.
+- Treat contradictory reviewer or verifier output as unresolved until the controller resolves it.
+- Reject closeout if evidence is missing, tests are only syntax-level for UI/API behavior, or critical/high findings remain.
+- Prefer a short verdict over a long essay.
+
+Return:
+
+- verdict: PASS, RETURN_TO_DEBUG, or BLOCKED
+- unresolved risks
+- missing evidence
+- whether final acceptance may proceed
+- one-line memory candidate if a durable lesson was found

package/templates/common/.claude/agents/verifier.md

@@ -1,6 +1,6 @@
 ---
 name: verifier
-description: Use to run verification commands, inspect results, and record evidence before marking work Done or Verified.
+description: Use to run verification commands, inspect results, and record evidence. Final acceptance still waits for cross-review PASS and reflector PASS.
 tools: Read, Grep, Glob, Bash
 model: sonnet
 ---
@@ -20,8 +20,10 @@ Rules:
 - Do not write code.
 - Run only declared verification commands unless asked to expand coverage.
 - If a command is unavailable, record why and suggest a manual check.
-- Mark results as pass, fail, or not run with notes.
-- Do not mark work verified without evidence.
+- Mark results as pass, fail, or not run with notes.
+- Do not mark work verified without evidence.
+- Do not claim final acceptance. Verification evidence is necessary but final
+  acceptance waits for cross-review PASS and reflector PASS.
 
 Return:
 

package/templates/common/.claude/commands/wf-help.md

@@ -7,12 +7,11 @@ do not dispatch agents, and do not edit files.
 | --- | --- | --- | --- |
 | `/wf-help` | direct command | `/wf-help` | Show this command table. |
 | `/wf <task>` | workflow skill | `/wf fix failing login flow` | Standard acceptance-driven workflow for long, uncertain, multi-file, browser/API, or recovery work. |
-| `/wf-max <task>` | workflow skill | `/wf-max refactor auth module` | Maximum-parallelism workflow with CEO -> Manager -> Worker dispatch, write-set coloring, independent review, and validation. |
+| `/wf-max <task>` | workflow skill | `/wf-max refactor auth module` | WF strict superset: complete role chain plus maximum fan-out, CEO -> Manager -> Worker dispatch, cross-CLI overflow when the current runtime agent pool is exhausted. |
 | `/wf-auto` | workflow skill | `/wf-auto` | Perpetual auto-optimization loop using bounded cycles, 8-angle exhaustion, evidence ledger, and optional wf-auto-only tick hook. |
 | `/wf-auto-spark` | workflow skill | `/wf-auto-spark` | Perpetual inspiration mode with roadmap anchoring and external spark search. |
 | `/wf-review <focus>` | workflow skill | `/wf-review security and test coverage` | Cross-model peer review through the other CLI; use for second opinions and risk checks. |
 | `/wf-learn` | workflow skill | `/wf-learn` | Force context-master -> memory-master learning cycle after repeated failures or closeout. |
-| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence when installed. |
 | `/wf-readme <task>` | workflow skill | `/wf-readme polish quickstart` | Preserve, merge, or improve README docs without trampling existing project documentation. |
 | `/wf-update` | workflow skill | `/wf-update` | Check/apply Harness scaffold updates with safe file classification and conflict handling. |
 | `/wf-remove` | workflow skill | `/wf-remove` | Safely remove Harness files while preserving project/user data unless explicitly purged. |

package/templates/common/.claude/skills/subagent-orchestrator/SKILL.md

@@ -24,6 +24,10 @@ subagent surfaces; follow the same Harness role contract either way.
   subagent/task tool.
 - Codex: use the available subagent tool or role mechanism in the current
   surface. If unavailable, emulate the same roles as separate bounded passes.
+- WF-MAX cross-CLI overflow: prefer the current runtime's subagents first; if that pool
+  is exhausted, overflow to the other CLI with explicit dispatch packets
+  (Codex -> `claude -p`, Claude -> available Codex CLI such as `codex exec`)
+  before bounded-pass fallback.
 - In every runtime, record fallback and role coverage in the task plan.
 
 ## Rules
@@ -32,14 +36,16 @@ subagent surfaces; follow the same Harness role contract either way.
   integrates returns, and owns final verification.
 - Subagents or bounded passes are readers and reporters unless a write set is
   explicitly assigned and disjoint.
-- Explicit WF/WK mode requires at least three distinct role passes before the
-  second plan.
+- Explicit WF/WK mode requires complete role-chain coverage from intake through
+  final acceptance: plan, research/docs research as needed, architecture, test,
+  implement, independent validation, cross-review, reflector, and accept.
 - Every dispatch needs role, goal, mode, read set, write set, forbidden scope,
   injected docs, dependencies, evidence, stop condition, and return format.
 - Prefer parallel read-only exploration first. Serialize writers unless write
   sets are disjoint and isolated.
-- After implementation, run a spec review gate and a code/architecture review
-  gate before final verification.
+- After implementation, run independent spec/AC and code/architecture/test
+  review gates. Final acceptance is blocked until cross-review passes and the
+  reflector returns PASS.
 
 ## Return
 

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

@@ -29,8 +29,12 @@ This skill is a thin tool adapter. The authoritative workflow lives in
 - Create or update a task capsule under `Harness/tasks/<task-id>/`.
 - Run the WF loop from `Harness/WF.md`: intake, bounded exploration, second
   plan, implementation, review, verification, recovery, and closeout.
-- For explicit WF invocation, use at least three distinct role passes before
-  the second plan. Use real subagents when the runtime supports them; otherwise
-  record a bounded-pass fallback in the task plan.
+- For explicit WF invocation, schedule the complete role chain at intake:
+  plan, research/docs research as needed, architecture, test, implement,
+  independent validation, cross-review, reflector, and final acceptance. Use
+  real subagents when the runtime supports them; otherwise record bounded-pass
+  fallback coverage in the task plan.
+- Do not mark accepted until cross-review passes and the reflector returns
+  PASS.
 - Keep `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` current before long
   commands, after failures, and at closeout.

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

@@ -1,107 +1,59 @@
----
-name: wf-auto
-description: Perpetual auto-optimization mode. Never stops — continuously improves code until 8-angle exhaustion. Adaptive checkpoints, external spark search, evidence ledger. Use for Claude /wf-auto, Codex $wf-auto, auto mode, or when the user wants unbounded self-directed optimization.
----
-
-# WF Auto — Perpetual Auto-Optimization
-
-## Load (authoritative specs)
-
-- `Harness/WF-AUTO.md` — full spec: perpetual loop, state machine, 8-angle exhaustion gate, cross-model oracle, spark candidate provider, Value Gate scoring, evidence ledger, Intent Checkpoints, anti-patterns, safety controls
-- `Harness/subagents.md` — agent roster, controller role, efficiency ladder
-- `Harness/dispatch.md` — handoff format, File claim, Concurrency group fields
-- `Harness/agent-workflow.md` — build/review/test loop, cohesion rule, completion gate
-- `.claude/skills/wf-review/SKILL.md` — cross-model invocation pattern (used by the oracle step)
-
-## Trigger & When NOT to Use
-
-- **Trigger**: Claude `/wf-auto`, Codex `$wf-auto`, `wf auto`, `auto mode`, or user wants continuous self-directed improvement
-- **Do NOT use**: user has a specific bounded task (use `/wf`), task needs maximum parallelism (use `/wf-max`), production hotfix needed urgently, codebase <100 lines
-
-## State Machine
-
-```
-auto.internal → auto.spark → auto.checkpoint → auto.exhausted → paused
-```
-
-CEO tracks state in `Harness/tasks/auto/PROGRESS.md`. Transitions are CEO-owned.
-
-## Hard Constraints
-
-1. **NEVER STOP except A-GATE.** No "task complete" early exit. The Angle Exhaustion Gate (internal + oracle + spark all empty, 3 confirm rounds) is the ONLY permitted stop.
-2. **CEO never writes production code.** CEO uses Task, Read, Grep/Glob. No Edit/Write/Bash on source files. Exception: CEO MAY write to `Harness/tasks/auto/PROGRESS.md` and `Harness/tasks/auto/PLAN.md`.
-3. **ALL sources in ONE message per cycle.** 8 angles + oracle + spark searchers. Batching is mandatory.
-4. **ONE finding per cycle.** One change, ≤3 files, ≤50 lines diff. Big ideas (>50 lines) escalate to /wf or /wf-max then return.
-5. **Two-gate review every cycle.** Spec review before code-quality review. No skipping.
-6. **A-GATE has 3 tiers.** All 8 exhausted → Cross-Model Oracle → Spark search → 2 confirmation rounds → STOP.
-7. **Value Gate is scored, not binary.** 5 dimensions (Impact, Evidence, Fit, Timing, Cost/Risk), 1-5 each. Pass: ≥18/25 AND no dimension <3.
-8. **Intent Checkpoint is adaptive.** 2→5→10 cycles. Exactly 2 questions: "Still aligned?" + "What should change?" Early on drift signals.
-9. **Evidence ledger per cycle.** Source, evidence type, expected impact, verification method, measured result, verdict. Track weak spark count.
-
-## The 8 Angles (quick reference)
-
-| # | Angle | Finds |
-|---|-------|-------|
-| 1 | Correctness | Bugs, edge cases, null safety, race conditions |
-| 2 | Performance | Slow paths, memory, algorithmic complexity |
-| 3 | Security | Injection, auth, secrets, dependency CVEs |
-| 4 | Maintainability | Clarity, DRY, coupling, naming, dead code |
-| 5 | Test Coverage | Missing tests, weak assertions, flaky tests |
-| 6 | Architecture | Boundaries, dependency direction, layer discipline |
-| 7 | UX / DX | Error messages, API ergonomics, documentation |
-| 8 | Robustness | Resilience, retry, observability, recovery |
-
-## Spark Sources (when internal + oracle empty)
-
-| # | Source | Evidence Weight |
-|---|--------|-----------------|
-| 1 | Official Docs & Advisories | HIGH |
-| 2 | Ecosystem Pulse | MEDIUM |
-| 3 | GitHub Trending (same stack) | LOW-MEDIUM |
-| 4 | Best Practices (latest) | MEDIUM |
-| 5 | Competitor/Peer Projects | LOW |
-| 6 | Real-world Issues | MEDIUM |
-| 7 | Architecture Trends | LOW |
-| 8 | Performance Benchmarks | MEDIUM |
-
-Source-quality: official docs > blog posts. Trending ≠ correct. Competitor behavior is hypothesis only. Every spark MUST cite source with URL and date.
-
-## Perpetual Loop
-
-```
-W0: SENSE (8 angles + oracle + 8 spark sources, all parallel)
-A-GATE [findings? → W1 | all empty? → oracle → spark → confirm ×2 → STOP]
-CHECKPOINT [every 2→5→10 cycles, 2 questions]
-W1: PRIORITIZE (across internal + oracle + spark)
-W2: IMPLEMENT → W3: REVIEW → W4: DEBUG → W5: VERIFY
-RECORD + EVIDENCE LEDGER → LOOP W0
-```
-
-## Cycle Recording
-
-Every cycle writes to `Harness/tasks/auto/PROGRESS.md`:
-- Cycle number, timestamp, state
-- Source (internal/oracle/spark-*), source citation
-- Finding, change description, files changed
-- Value Gate scores (if spark candidate)
-- Review result, verification evidence
-- Evidence Ledger: evidence type, expected impact, verification method, measured result, verdict
-
-## Safety
-
-- ≤3 files, ≤50 lines per cycle
-- Big ideas (>50 lines) escalate to /wf or /wf-max, then return to auto
-- Destructive changes flagged with rollback plan
-- IDLE alarm after 5 empty cycles → re-scope → A-GATE candidate
-- Spark stop: 5 failed Value Gates OR 3 weak measured impacts OR 2 repeated source families empty
-- User can interrupt at any time
-
-## Return Format
-
-- Total cycles run
-- Findings addressed per source (internal / oracle / spark)
-- Evidence ledger with measured impacts
-- Exhaustion evidence (3-round confirmation)
-- Weak spark count
-- Final codebase state
-- Residual risk assessment
+---
+name: wf-auto
+description: Perpetual auto-optimization mode. Never stops until 8-angle exhaustion. Inherits WF acceptance gates and subagent orchestration per cycle. Use for Claude /wf-auto, Codex $wf-auto, auto mode, or unbounded self-directed optimization.
+---
+
+# WF Auto - Perpetual Auto-Optimization
+
+## Load
+
+- `Harness/WF-AUTO.md`
+- `Harness/subagents.md`
+- `Harness/dispatch.md`
+- `Harness/agent-workflow.md`
+- `.claude/skills/wf-review/SKILL.md`
+
+## Trigger
+
+- Claude `/wf-auto`
+- Codex `$wf-auto`
+- `wf auto`, `auto mode`, or a request for continuous self-directed improvement
+
+Do not use when the user gives a bounded task, requests maximum parallelism
+(`/wf-max`), needs an urgent production hotfix, or the codebase is tiny enough
+that auto scanning costs more than it helps.
+
+## Hard Rules
+
+1. Never stop except the A-GATE: all 8 angles empty, oracle empty, spark empty,
+   and 2 confirmation rounds.
+2. CEO never edits production source. CEO may write only
+   `Harness/tasks/auto/PLAN.md` and `Harness/tasks/auto/PROGRESS.md`.
+3. Dispatch all W0 sources in one batch when the runtime allows it: 8 angles,
+   oracle, and spark searchers.
+4. One accepted finding per cycle: <=3 files and <=50 changed lines. Larger
+   ideas escalate to `/wf` or `/wf-max`, then return to auto.
+5. Every accepted cycle inherits the full WF chain:
+   `Mini PRD -> AC IDs -> test/validation plan -> implementer -> verifier ->
+   cross-review -> reflector PASS -> evidence ledger -> next W0`.
+6. Review is mandatory: spec review, code-quality review, then reflector.
+7. Value Gate is scored for spark candidates: pass is >=18/25 and no dimension
+   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.
+
+## Loop
+
+```text
+W0: SENSE (8 angles + oracle + spark sources)
+A-GATE: continue, oracle, spark, confirm, or stop
+W1: PRIORITIZE one finding
+W2-W5: Mini PRD -> AC -> test/validation plan -> implementer -> verifier -> cross-review -> reflector PASS
+RECORD: evidence ledger
+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.

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

@@ -1,17 +1,17 @@
 ---
 name: wf-auto-spark
-description: Use for /wf-auto-spark in Claude Code, $wf-auto-spark or /skills wf-auto-spark in Codex, or perpetual inspiration mode that never stops — external spark search, long-term roadmap with staged milestones, ≤50% deviation guard.
+description: Perpetual inspiration mode for /wf-auto-spark or $wf-auto-spark. Inherits WF-AUTO/WF execution gates while using external spark search, roadmap anchoring, and <=50% deviation guard.
 ---
 
 # WF-AUTO-SPARK Adapter
 
-This skill is a thin tool adapter. The authoritative workflow lives in
-`Harness/WF-AUTO-SPARK.md`; do not duplicate or override it here.
+The authoritative workflow lives in `Harness/WF-AUTO-SPARK.md`; this adapter
+only routes and summarizes hard constraints.
 
 ## Invocation
 
-- Claude Code: use `/wf-auto-spark` or select the `wf-auto-spark` skill.
-- Codex CLI or IDE: use `$wf-auto-spark` or `/skills` then choose `wf-auto-spark`.
+- Claude Code: `/wf-auto-spark`
+- Codex: `$wf-auto-spark` or `/skills` then choose `wf-auto-spark`
 
 ## Load
 
@@ -25,15 +25,17 @@ This skill is a thin tool adapter. The authoritative workflow lives in
 
 ## Rules
 
-WF-AUTO-SPARK is perpetual inspiration mode with roadmap anchoring:
-1. **Roadmap first**: Declare North Star + staged milestones before any spark cycle.
-2. **Never auto-stop**: Only user can stop. "No sparks found" → expand search.
-3. **Deviation guard (≤50%)**: Every spark checked against North Star. Cumulative 10-cycle average ≥65%. Below → force Re-Anchor Gate.
-4. **Milestones flexible within 50%**: Can reorder/split/merge/replace, but North Star changes need user confirmation.
-5. **Value reflection every cycle**: CEO writes what was done, why it matters, deviation score, milestone progress.
-6. **Re-Anchor Gate every 10 cycles**: User confirms direction or adjusts roadmap.
-
-## Roadmap Location
-
-Active roadmap lives at `Harness/tasks/auto/SPARK-ROADMAP.md`. Created at startup.
-Per-cycle evidence at `Harness/tasks/auto/PROGRESS.md`.
+1. Roadmap first: declare North Star and staged milestones before spark cycles.
+2. Never auto-stop: only the user can stop; "no sparks found" expands search.
+3. Spark replaces discovery only. Accepted candidates still run:
+   `Mini PRD -> AC IDs -> test/validation plan -> implementer -> verifier ->
+   cross-review -> reflector PASS -> evidence ledger`.
+4. Spark searchers are read-only. Implementation requires explicit dispatch
+   packet, write set, forbidden truth files, AC IDs, and verification commands.
+5. Deviation guard: each spark must align >=50% with North Star; rolling
+   10-cycle average below 65% forces Re-Anchor Gate.
+6. Value reflection is required every cycle: source, why it matters, deviation,
+   evidence, and milestone progress.
+
+Active roadmap: `Harness/tasks/auto/SPARK-ROADMAP.md`.
+Per-cycle evidence: `Harness/tasks/auto/PROGRESS.md`.