create-harness-vibe-coding 0.8.1 → 0.8.3

package/README-CN.md

@@ -59,13 +59,15 @@ Claude Code 和 Codex 共用同一套核心 Harness 文档，但发现入口不
 ## 已有项目安全合并
 
 ```bash
-# 先预览，不写文件
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
+# 先用机器可读预览，不写文件
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
 
 # 只补缺失文件，不覆盖已有文件
-npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip --json
 ```
 
+JSON 输出就是 agent 的安装报告：`scan` 代替手写根目录探测，`plan.create` 交给脚本处理，只有 `agent.aiMergeRequired` 里的文件需要 AI 语义比较和用户监督合并。除非这个列表里出现冲突文件，否则不要读取包源码或模板。
+
 `npx` 是安装和安全补缺入口，不是已安装 Harness 的同步更新器。项目里已经有 `Harness/` 后，Claude Code 用 `/wf-update`，Codex 用 `$wf-update`，或者直接运行：
 
 ```bash
@@ -107,14 +109,13 @@ npx create-harness-vibe-coding@latest my-app -y --recommend superpowers,codegrap
 
 ## Agent-link 安装前置问题
 
-Agent 必须先扫描根目录，再最多问 3 个阻塞问题。扫描要覆盖：
+Agent 应先拿机器可读安装报告，再最多问 3 个阻塞问题：
 
-- `CLAUDE.md`、`AGENTS.md`
-- `.claude/`、`.agents/`、`.codex/`
-- `Harness/`
-- `README.md`
-- package 文件、CI 文件、已有文档目录、应用入口、测试/构建命令
-- 已安装的 skills/plugins/rules
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+```
+
+使用 `scan.markers`，不要手写一串根目录探测命令。`plan.create` 由脚本处理；只有 `agent.aiMergeRequired` 里的文件需要 AI 比较并由用户监督合并。
 
 只在影响写入时提问：
 
@@ -127,8 +128,11 @@ Agent 必须先扫描根目录，再最多问 3 个阻塞问题。扫描要覆
 ## 验证
 
 ```bash
+# 当前脚手架仓库
 npm test
-node Harness/scripts/validate-harness.mjs
+
+# 生成后的项目完成 bootstrap 后
+node Harness/scripts/validate-harness.mjs --strict
 ```
 
 ## 项目结构

package/README.md

@@ -120,13 +120,15 @@ Root scan must include top-level files, `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.
 ### Existing project — safe merge
 
 ```bash
-# Preview first. Always.
-npx create-harness-vibe-coding@latest my-app . -y --dry-run
-
+# Machine-readable preview first. Always.
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+
 # Add only what's missing. Never overwrite.
-npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip --json
 ```
 
+The JSON output is the agent's install report: `scan` replaces hand-written root probes, `plan.create` is script-owned, and `agent.aiMergeRequired` is the only list that needs semantic AI review. Do not read package source or templates unless `agent.aiMergeRequired` names a conflicting file.
+
 `npx` is an install and safe-merge entry, not an update engine for an already installed Harness. Once `Harness/` exists, use `/wf-update` in Claude Code, `$wf-update` in Codex, or `node Harness/scripts/wf-update-check.mjs`; root entry conflicts such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, and local Harness docs need agent-mediated merge decisions.
 
 | Flag | Does |
@@ -172,9 +174,13 @@ These are links for the user's agent to evaluate. The scaffold does not maintain
 
 ### Agent-link intake
 
-When your agent reads the one-sentence prompt above, it must first scan the project root, then ask **at most 3 blocking questions** before touching files.
+When your agent reads the one-sentence prompt above, it should get the machine-readable install report before asking broad questions:
 
-Root scan checklist: list top-level files, detect `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `Harness/`, package files, CI files, docs folders, obvious app entry points, test/build commands, and installed skills/plugins/rules.
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
+```
+
+Use `scan.markers` instead of manual top-level probes. Ask **at most 3 blocking questions** before touching files. Files in `plan.create` are handled by the script; only files in `agent.aiMergeRequired` need AI comparison and user-supervised merge decisions.
 
 Ask these only when they affect writes:
 
@@ -193,12 +199,15 @@ Harness docs always live in root `Harness/`; do not route Harness files through
 "/wf-update" or "$wf-update"           # pull latest harness improvements
 ```
 
-### Verify
-
-```bash
-npm test
-node Harness/scripts/validate-harness.mjs
-```
+### Verify
+
+```bash
+# In this package repo
+npm test
+
+# In a generated project after bootstrap
+node Harness/scripts/validate-harness.mjs --strict
+```
 
 ---
 

package/package.json

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

package/src/index.js

@@ -81,11 +81,19 @@ const generationOptions = {
 const DEFAULT_NAME = 'my-vibe-project';
 
 // --json: machine-readable output, no prompts, no decorative output
-if (generationOptions.json) {
-  const projectName = argName || DEFAULT_NAME;
-  const targetDir = argDir || `./${projectName}`;
-  const result = generate({ projectName, targetDir, ...generationOptions });
-  printJsonResult(result);
+if (generationOptions.json) {
+  const projectName = argName || DEFAULT_NAME;
+  const targetDir = argDir || `./${projectName}`;
+  const scan = scanTarget(targetDir);
+  const result = generate({ projectName, targetDir, ...generationOptions });
+  result.scan = createJsonScan(scan);
+  result.agent = createAgentGuidance(result, {
+    projectName,
+    targetDir,
+    options: generationOptions,
+    scan,
+  });
+  printJsonResult(result);
   // printJsonResult exits with 1 on failure; we only reach here on success
   process.exit(0);
 }
@@ -429,6 +437,17 @@ function scanTarget(targetDir) {
     ? fs.readdirSync(resolvedDir)
     : [];
   const hasHarness = isDirectory && fs.existsSync(path.join(resolvedDir, 'Harness'));
+  const hasClaude = isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md'));
+  const hasAgents = isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md'));
+  const hasAgentSkills = isDirectory && fs.existsSync(path.join(resolvedDir, '.agents'));
+  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
+  const hasDocs = isDirectory && fs.existsSync(path.join(resolvedDir, 'docs'));
+  const hasReadme = isDirectory && fs.existsSync(path.join(resolvedDir, 'README.md'));
+  const hasPackageJson = isDirectory && fs.existsSync(path.join(resolvedDir, 'package.json'));
+  const hasPyproject = isDirectory && fs.existsSync(path.join(resolvedDir, 'pyproject.toml'));
+  const hasGoMod = isDirectory && fs.existsSync(path.join(resolvedDir, 'go.mod'));
+  const hasGithub = isDirectory && fs.existsSync(path.join(resolvedDir, '.github'));
+  const hasGitignore = isDirectory && fs.existsSync(path.join(resolvedDir, '.gitignore'));
 
   return {
     resolvedDir,
@@ -436,15 +455,196 @@ function scanTarget(targetDir) {
     isDirectory,
     entries,
     hasHarness,
-    hasClaude: isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md')),
-    hasAgents: isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md')),
-    hasAgentSkills: isDirectory && fs.existsSync(path.join(resolvedDir, '.agents')),
-    hasCodex: isDirectory && fs.existsSync(path.join(resolvedDir, '.codex')),
-    hasDocs: isDirectory && fs.existsSync(path.join(resolvedDir, 'docs')),
+    hasClaude,
+    hasAgents,
+    hasAgentSkills,
+    hasCodex,
+    hasDocs,
+    hasReadme,
+    hasPackageJson,
+    hasPyproject,
+    hasGoMod,
+    hasGithub,
+    hasGitignore,
     needsConflictPolicy: exists && (!isDirectory || entries.length > 0 || hasHarness),
   };
 }
 
+function createJsonScan(scan) {
+  const topLevelEntries = scan.entries.slice(0, 50);
+
+  return {
+    resolvedDir: scan.resolvedDir,
+    exists: scan.exists,
+    isDirectory: scan.isDirectory,
+    entryCount: scan.entries.length,
+    topLevelEntries,
+    topLevelEntriesTruncated: scan.entries.length > topLevelEntries.length,
+    needsConflictPolicy: scan.needsConflictPolicy,
+    markers: {
+      hasHarness: scan.hasHarness,
+      hasClaude: scan.hasClaude,
+      hasAgents: scan.hasAgents,
+      hasAgentSkills: scan.hasAgentSkills,
+      hasCodex: scan.hasCodex,
+      hasDocs: scan.hasDocs,
+      hasReadme: scan.hasReadme,
+      hasPackageJson: scan.hasPackageJson,
+      hasPyproject: scan.hasPyproject,
+      hasGoMod: scan.hasGoMod,
+      hasGithub: scan.hasGithub,
+      hasGitignore: scan.hasGitignore,
+    },
+  };
+}
+
+function createAgentGuidance(result, { projectName, targetDir, options, scan }) {
+  const attentionFiles = [...new Set([
+    ...(result.plan?.conflict || []),
+    ...(result.plan?.skip || []),
+  ])].sort();
+  const aiMergeRequired = attentionFiles.map(file => createFileGuidance(file));
+  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0;
+  const safeMergeCommand = commandFor(projectName, targetDir, {
+    ...options,
+    dryRun: false,
+    onConflict: 'skip',
+    json: true,
+  });
+  const previewCommand = commandFor(projectName, targetDir, {
+    ...options,
+    dryRun: true,
+    json: true,
+  });
+  const next = [];
+
+  if (scan.hasHarness) {
+    next.push({
+      action: 'stop',
+      reason: 'Harness already exists; use wf-update or Harness/scripts/wf-update-check.mjs instead of reinstalling blindly.',
+    });
+  } else if (result.dryRun && !hasBlockingConflicts) {
+    next.push({
+      action: 'install',
+      command: safeMergeCommand,
+      reason: 'Dry-run has no blocking conflicts; let the script create missing files.',
+    });
+  } else if (result.dryRun && hasBlockingConflicts) {
+    next.push({
+      action: 'safe-merge',
+      command: safeMergeCommand,
+      reason: 'Default dry-run found existing files; rerun with --on-conflict skip so the script creates missing files and preserves existing ones.',
+    });
+  } else if (result.success) {
+    next.push({
+      action: 'bootstrap',
+      command: 'Read Harness/SETUP.md and use this JSON plan before opening any package templates.',
+      reason: 'Scaffold files were written; bootstrap project facts from local evidence.',
+    });
+  } else {
+    next.push({
+      action: 'inspect-errors',
+      reason: 'Generation failed before safe scaffold output was available.',
+    });
+  }
+
+  if (aiMergeRequired.length > 0) {
+    next.push({
+      action: 'ai-merge',
+      files: aiMergeRequired.map(item => item.file),
+      reason: 'Only these existing/conflicting files need semantic review. Files in plan.create are script-owned.',
+    });
+  }
+
+  return {
+    sourceOfTruth: 'Use this JSON scan/plan first. Do not read package source or templates unless aiMergeRequired lists a file.',
+    previewCommand,
+    safeMergeCommand,
+    scriptHandled: {
+      create: result.plan?.create?.length || 0,
+      mkdir: result.plan?.mkdir?.length || 0,
+      backup: result.plan?.backup?.length || 0,
+      overwrite: result.plan?.overwrite?.length || 0,
+    },
+    aiMergeRequired,
+    next,
+  };
+}
+
+function createFileGuidance(file) {
+  const normalized = file.replace(/\\/g, '/');
+  const guidance = {
+    file: normalized,
+    templateHint: templateHintFor(normalized),
+    requiresUserConsent: false,
+    defaultAction: 'preserve',
+    reason: 'Existing file or path needs semantic review before any merge.',
+  };
+
+  if (normalized.endsWith('/')) {
+    return {
+      ...guidance,
+      templateHint: null,
+      defaultAction: 'stop',
+      reason: 'A file blocks a required scaffold directory. Stop and ask before moving or replacing it.',
+    };
+  }
+
+  if (normalized === 'CLAUDE.md' || normalized === 'AGENTS.md') {
+    return {
+      ...guidance,
+      requiresUserConsent: true,
+      reason: 'Root agent entry contract. Preserve project rules and ask before merging Harness startup guidance.',
+    };
+  }
+
+  if (normalized === 'README.md') {
+    return {
+      ...guidance,
+      reason: 'Project-owned public/development documentation. Preserve by default; append development notes only after review.',
+    };
+  }
+
+  if (normalized === 'Harness/README.md' || normalized === 'Harness/MEMORY.md') {
+    return {
+      ...guidance,
+      reason: 'Harness router/registry conflict. Merge only missing routing or registration entries.',
+    };
+  }
+
+  return guidance;
+}
+
+function templateHintFor(file) {
+  if (file === 'Harness/SETUP.md') return 'templates/common/SETUP.md';
+  return `templates/common/${file}`;
+}
+
+function commandFor(projectName, targetDir, options) {
+  const args = [
+    'npx',
+    'create-harness-vibe-coding@latest',
+    projectName,
+    targetDir,
+    '-y',
+  ];
+
+  if (options.dryRun) args.push('--dry-run');
+  if (options.onConflict) args.push('--on-conflict', options.onConflict);
+  if (options.withOptions?.length) args.push('--with', options.withOptions.join(','));
+  if (options.withoutOptions?.length) args.push('--without', options.withoutOptions.join(','));
+  if (options.externalOptions?.length) args.push('--recommend', options.externalOptions.join(','));
+  if (options.preset) args.push('--preset', options.preset);
+  if (options.json) args.push('--json');
+
+  return args.map(shellQuoteArg).join(' ');
+}
+
+function shellQuoteArg(arg) {
+  if (/^[A-Za-z0-9@._/\\:-]+$/.test(arg)) return arg;
+  return JSON.stringify(arg);
+}
+
 function printScan(scan) {
   if (!scan.exists) return;
 

package/templates/common/.claude/agents/tdd-guide.md

@@ -0,0 +1,55 @@
+---
+name: tdd-guide
+description: Test-Driven Development specialist enforcing write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+# TDD Guide Agent
+
+Enforces TDD workflow. Load `Harness/TDD-GUIDE.md` first, then ECC testing rules for the project stack.
+
+## Inputs Required
+
+- Task description and acceptance criteria from PLAN.md
+- Current test coverage status
+- Stack-specific testing tools (Jest, Pytest, Go test, etc.)
+
+## Workflow
+
+1. READ acceptance criteria
+2. WRITE failing test (RED)
+3. VERIFY test fails for expected reason
+4. Report test file path and expected failure to Implementer
+
+Do NOT write implementation code. Only tests.
+
+## Allowed Write Set
+
+- Test files only (`*.test.ts`, `*.test.tsx`, `test_*.py`, `*_test.go`, etc.)
+- Test fixtures and mocks
+- Test configuration files
+
+## Forbidden
+
+- Production/source code changes
+- Loosening existing test assertions
+- Deleting existing tests without explicit approval
+
+## Verification
+
+- Test MUST fail before handing off to Implementer
+- Test MUST cover acceptance criteria + error paths
+- Run `node Harness/scripts/validate-harness.mjs` after significant test additions
+
+## Return Format
+
+```text
+Agent: tdd-guide
+Task: <task-id>
+Tests written: <file paths>
+Coverage before: X%
+Expected coverage after: Y%
+Failing tests: <list of test names and expected failure reasons>
+Next: Dispatch Implementer to make tests pass
+```

package/templates/common/.claude/settings.json

@@ -63,6 +63,28 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -0,0 +1,30 @@
+---
+name: tdd
+description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
+---
+
+# TDD Adapter
+
+Thin tool adapter. Authoritative guide: `Harness/TDD-GUIDE.md`.
+
+## Invocation
+
+- Claude Code: use `/tdd` or select the `tdd` skill.
+- Codex CLI or IDE: use `$tdd` or `/skills` then choose `tdd`.
+
+## Load
+
+1. `Harness/TDD-GUIDE.md`
+2. ECC stack-specific testing rules (e.g., `typescript/testing.md`, `python/testing.md`)
+3. Current task `PLAN.md`
+
+## Rules
+
+1. **RED first**: Write failing test before ANY implementation code.
+2. **GREEN minimal**: Write only enough code to pass the test.
+3. **REFACTOR safe**: Improve code while keeping all tests green.
+4. **Coverage gate**: ≥80% before marking task complete.
+5. **Test names**: Describe behavior — `test('returns X when Y')`.
+6. **AAA structure**: Arrange → Act → Assert.
+7. **Error paths**: Test failure cases, not just happy path.
+8. **WF-MAX**: Test Writer agent dispatched BEFORE Implementer in every wave.

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

@@ -0,0 +1,107 @@
+---
+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

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

@@ -0,0 +1,39 @@
+---
+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.
+---
+
+# 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.
+
+## 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`.
+
+## Load
+
+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`
+
+## 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`.

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

@@ -26,8 +26,16 @@ This skill is a thin tool adapter. The authoritative workflow lives in
 
 ## Rules
 
-- Treat yourself as CEO, not implementer.
-- Do not edit production/source files directly while WF-MAX is active.
+WF-MAX is a three-layer architecture:
+1. Global mode (`wf-max`)
+2. Agent role (`ceo` | `manager` | `worker` | `reviewer`)
+3. Dispatch permission (`writeSet`, `forbidden`, `verification`)
+
+- Top-level orchestrator is CEO (reads, plans, dispatches). Delegated Workers follow dispatch packet with explicit writeSet. Global mode ≠ every agent is CEO.
+- CEO: never edit source files directly. Spawn Workers with writeSet.
+- Worker: edit only files in dispatch writeSet. Outside writeSet → blocked.
+- Manager: scope, review, coordinate. No source edits by default.
+- Reviewer: read and report only. No edits.
 - Use the D-GATE in `Harness/WF-MAX.md` before any implementation wave:
   dispatch table, self-audit, disjoint file claims, and reviewer plan.
 - Use real subagents when the runtime supports them; otherwise record a

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

@@ -17,14 +17,21 @@ description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove
 
 ## Flow
 
-1. Run `node Harness/scripts/wf-remove.mjs` for a dry-run plan.
+1. Run `node Harness/scripts/wf-remove.mjs --json` for the machine-readable
+   plan.
 2. Auto-remove only SAFE files that still match stored checksums.
 3. Ask the user before every MODIFIED or uncertain file.
-4. Never remove USER DATA files.
-5. Run `node Harness/scripts/wf-remove.mjs --apply` only after the plan is
-   understood and modified-file decisions are clear.
+4. Preserve USER DATA by default. For an explicit thorough uninstall, use
+   `--purge-user-data` (alias `--purge`); add `--keep-tasks` when the user wants task records
+   retained while project-fact Harness docs are removed.
+5. Run the script, not manual deletes:
+   - safe default: `node Harness/scripts/wf-remove.mjs --apply --yes`
+   - thorough but keep tasks: `node Harness/scripts/wf-remove.mjs --apply --yes --purge-user-data --keep-tasks`
+   - exact modified decisions: add `--delete-modified <path>` for each
+     user-approved MODIFIED file.
 
 ## Return
 
 Report SAFE removals, MODIFIED keep/delete decisions, preserved USER DATA,
-directory cleanup, CLAUDE/AGENTS status, and `git status` guidance.
+PURGE removals, directory cleanup, CLAUDE/AGENTS status, `.harness-version`
+status, and `git status` guidance.