create-harness-vibe-coding 0.8.16 → 0.8.18

package/src/index.js

@@ -4,7 +4,7 @@ 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 { askConflictPolicy, askInstallScope, 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']);
@@ -45,6 +45,9 @@ if (showHelp) {
   console.log('    --without <id,id>            Remove optional workflow skills selected by --preset or --with');
   console.log('    --recommend <id,id>          Record recommendation-only external capabilities');
   console.log('    --preset <name>              Add a built-in optional workflow preset');
+  console.log('    --install-scope <scope>      project or global (default: project)');
+  console.log('    --global-dir <dir>           Global Harness runtime directory for --install-scope global');
+  console.log('    --host-global-dir <dir>      Base directory for Claude/Codex/OpenCode global copies');
   console.log('    --list-options               Print optional workflow skills and presets');
   console.log('    --json                       Output machine-readable JSON (use with --dry-run for planning)');
   console.log('');
@@ -57,9 +60,10 @@ if (showHelp) {
   console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
-  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,browser-e2e');
-  console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
-  console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,ui-ux-review');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
+  console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
+  console.log('    npx create-harness-vibe-coding@latest app ./app -y --install-scope global');
   console.log('');
   process.exit(0);
 }
@@ -80,6 +84,9 @@ const generationOptions = {
   withoutOptions: parsed.flags.without || [],
   externalOptions: parsed.flags.recommend || [],
   preset: parsed.flags.preset,
+  installScope: parsed.flags.installScope || 'project',
+  globalDir: parsed.flags.globalDir,
+  hostGlobalDir: parsed.flags.hostGlobalDir,
   json: Boolean(parsed.flags.json),
 };
 
@@ -137,9 +144,19 @@ if (argName || skipPrompts) {
   }
 
   console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  Project     ${pc.green(projectName)}`);
+  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/, .opencode/, opencode.json, tests/')}`);
+  console.log(`  Scope       ${pc.green(generationOptions.installScope)}`);
+  if (generationOptions.globalDir) {
+    console.log(`  Global dir  ${pc.green(generationOptions.globalDir)}`);
+  }
+  if (generationOptions.hostGlobalDir) {
+    console.log(`  Host dir    ${pc.green(generationOptions.hostGlobalDir)}`);
+  }
+  const creates = generationOptions.installScope === 'global'
+    ? 'project bridge/state/settings + global runtime + Claude/Codex/OpenCode host copies'
+    : 'CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/';
+  console.log(`  Creates     ${pc.cyan(creates)}`);
   if (generationOptions.dryRun) {
     console.log(`  Mode        ${pc.yellow('dry-run')}`);
   }
@@ -176,8 +193,15 @@ if (argName || skipPrompts) {
   try {
     targetDir = await askTargetDir(projectName);
   } catch {
-    targetDir = `./${projectName}`;
-    console.log(pc.dim(`  Directory: ${targetDir} (default)`));
+    targetDir = `./${projectName}`;
+    console.log(pc.dim(`  Directory: ${targetDir} (default)`));
+  }
+
+  try {
+    generationOptions.installScope = await askInstallScope();
+  } catch {
+    generationOptions.installScope = 'project';
+    console.log(pc.dim('  Scope: project (default)'));
   }
 
   const scan = scanTarget(targetDir);
@@ -219,9 +243,19 @@ if (argName || skipPrompts) {
 
   console.log('');
   console.log(pc.dim('────────────────────────────────────────────'));
-  console.log(`  Project     ${pc.green(projectName)}`);
+  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/, .opencode/, opencode.json, tests/')}`);
+  console.log(`  Scope       ${pc.green(generationOptions.installScope)}`);
+  if (generationOptions.globalDir) {
+    console.log(`  Global dir  ${pc.green(generationOptions.globalDir)}`);
+  }
+  if (generationOptions.hostGlobalDir) {
+    console.log(`  Host dir    ${pc.green(generationOptions.hostGlobalDir)}`);
+  }
+  const creates = generationOptions.installScope === 'global'
+    ? 'project bridge/state + global runtime + Claude/Codex/OpenCode host copies'
+    : 'CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/';
+  console.log(`  Creates     ${pc.cyan(creates)}`);
   console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   if (generationOptions.withOptions.length > 0) {
     console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
@@ -237,11 +271,19 @@ if (argName || skipPrompts) {
     printResult(preview, targetDir);
   }
 
-  console.log(pc.yellow('Planned changes: no files have been written yet.'));
-  printSummary(preview.summary);
-  printPlan(preview.plan);
-  printWarnings(preview);
-  console.log('');
+  console.log(pc.yellow('Planned changes: no files have been written yet.'));
+  console.log(pc.bold('Project plan:'));
+  printSummary(preview.summary);
+  printPlan(preview.plan);
+  if (preview.globalPlan) {
+    console.log(pc.bold('\nGlobal runtime plan:'));
+    console.log(`  Directory   ${pc.cyan(preview.globalDir)}`);
+    printSummary(preview.globalSummary);
+    printPlan(preview.globalPlan);
+  }
+  printHostPlans(preview.hostPlans, preview.hostSummary);
+  printWarnings(preview);
+  console.log('');
 
   if (generationOptions.dryRun) {
     process.exit(0);
@@ -270,11 +312,19 @@ if (argName || skipPrompts) {
 
 function printResult(result, targetDir) {
   if (result.success) {
-    if (result.dryRun) {
-      console.log(pc.yellow('\nDry run: no files or directories were written.'));
-      printSummary(result.summary);
-      printPlan(result.plan);
-      if (result.warnings.length > 0) {
+    if (result.dryRun) {
+      console.log(pc.yellow('\nDry run: no files or directories were written.'));
+      console.log(pc.bold('Project plan:'));
+      printSummary(result.summary);
+      printPlan(result.plan);
+      if (result.globalPlan) {
+        console.log(pc.bold('\nGlobal runtime plan:'));
+        console.log(`  Directory   ${pc.cyan(result.globalDir)}`);
+        printSummary(result.globalSummary);
+        printPlan(result.globalPlan);
+      }
+      printHostPlans(result.hostPlans, result.hostSummary);
+      if (result.warnings.length > 0) {
         console.log(pc.yellow('\nWarning(s):'));
         for (const warning of result.warnings) {
           console.log(pc.yellow(`  - ${warning}`));
@@ -283,11 +333,18 @@ function printResult(result, targetDir) {
       console.log('');
       return;
     }
-
-    console.log(pc.green('\nGeneration complete.\n'));
-    printSummary(result.summary);
-
-    printWarnings(result);
+
+    console.log(pc.green('\nGeneration complete.\n'));
+    console.log(pc.bold('Project install:'));
+    printSummary(result.summary);
+    if (result.globalSummary) {
+      console.log(pc.bold('Global runtime:'));
+      console.log(`  Directory   ${pc.cyan(result.globalDir)}`);
+      printSummary(result.globalSummary);
+    }
+    printHostPlans(result.hostPlans, result.hostSummary, { summaryOnly: true });
+
+    printWarnings(result);
 
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
@@ -384,13 +441,31 @@ function parseArgs(args) {
         flags.recommend.push(value);
       }
     } else if (arg === '--preset') {
-      const parsedValue = readValue('--preset', i);
-      flags.preset = parsedValue.value;
-      i = parsedValue.nextIndex;
-    } else if (arg.startsWith('--preset=')) {
-      flags.preset = readEqualsValue('--preset', arg.slice('--preset='.length));
-    } else if (arg.startsWith('-')) {
-      errors.push(`Unknown flag "${arg}"`);
+      const parsedValue = readValue('--preset', i);
+      flags.preset = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--preset=')) {
+      flags.preset = readEqualsValue('--preset', arg.slice('--preset='.length));
+    } else if (arg === '--install-scope') {
+      const parsedValue = readValue('--install-scope', i);
+      flags.installScope = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--install-scope=')) {
+      flags.installScope = readEqualsValue('--install-scope', arg.slice('--install-scope='.length));
+    } else if (arg === '--global-dir') {
+      const parsedValue = readValue('--global-dir', i);
+      flags.globalDir = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--global-dir=')) {
+      flags.globalDir = readEqualsValue('--global-dir', arg.slice('--global-dir='.length));
+    } else if (arg === '--host-global-dir') {
+      const parsedValue = readValue('--host-global-dir', i);
+      flags.hostGlobalDir = parsedValue.value;
+      i = parsedValue.nextIndex;
+    } else if (arg.startsWith('--host-global-dir=')) {
+      flags.hostGlobalDir = readEqualsValue('--host-global-dir', arg.slice('--host-global-dir='.length));
+    } else if (arg.startsWith('-')) {
+      errors.push(`Unknown flag "${arg}"`);
     } else {
       positionals.push(arg);
     }
@@ -434,17 +509,30 @@ function printSummary(summary) {
   console.log('');
 }
 
-function printPlan(plan) {
-  for (const [label, files] of Object.entries(plan)) {
-    if (!files.length) continue;
+function printPlan(plan) {
+  for (const [label, files] of Object.entries(plan)) {
+    if (!files.length) continue;
     console.log(`  ${label}:`);
     for (const file of files) {
       console.log(`    - ${file}`);
     }
-  }
-}
-
-function printWarnings(result) {
+  }
+}
+
+function printHostPlans(hostPlans = [], hostSummary = [], { summaryOnly = false } = {}) {
+  if (!hostPlans?.length) return;
+
+  const summariesByHost = new Map((hostSummary || []).map(item => [item.host, item.summary]));
+  console.log(pc.bold('\nHost-global copies:'));
+  for (const hostPlan of hostPlans) {
+    console.log(`  ${hostPlan.host}   ${pc.cyan(hostPlan.root)}`);
+    const summary = summariesByHost.get(hostPlan.host);
+    if (summary) printSummary(summary);
+    if (!summaryOnly) printPlan(hostPlan.plan);
+  }
+}
+
+function printWarnings(result) {
   if (!result.warnings.length) return;
 
   console.log(pc.yellow('\nWarning(s):'));
@@ -455,7 +543,7 @@ function printWarnings(result) {
 
 function printJsonResult(result) {
   // Remove `created` array from output — it is already in the plan, avoid duplication
-  const { created, ...rest } = result;
+  const { created, globalCreated, hostCreated, ...rest } = result;
   console.log(JSON.stringify(rest, null, 2));
   if (!result.success) {
     process.exit(1);
@@ -703,12 +791,44 @@ function createJsonScan(scan) {
 }
 
 function createAgentGuidance(result, { projectName, targetDir, options, scan }) {
-  const attentionFiles = [...new Set([
+  const projectAttentionFiles = [...new Set([
     ...(result.plan?.conflict || []),
     ...(result.plan?.skip || []),
   ])].sort();
-  const aiMergeRequired = attentionFiles.map(file => createFileGuidance(file));
-  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0;
+  const globalAttentionFiles = [...new Set([
+    ...(result.globalPlan?.conflict || []),
+    ...(result.globalPlan?.skip || []),
+  ])].sort();
+  const hostAttentionFiles = (result.hostPlans || []).flatMap(hostPlan => (
+    [...new Set([
+      ...(hostPlan.plan?.conflict || []),
+      ...(hostPlan.plan?.skip || []),
+    ])].sort().map(file => ({ host: hostPlan.host, root: hostPlan.root, file }))
+  ));
+  const aiMergeRequired = [
+    ...projectAttentionFiles.map(file => createFileGuidance(file)),
+    ...globalAttentionFiles.map(file => {
+      const guidance = createFileGuidance(file);
+      return {
+        ...guidance,
+        file: `global:${guidance.file}`,
+        scope: 'global-runtime',
+        reason: `Global runtime file in ${result.globalDir || 'the selected global directory'} needs review. ${guidance.reason}`,
+      };
+    }),
+    ...hostAttentionFiles.map(({ host, root, file }) => {
+      const guidance = createFileGuidance(file);
+      return {
+        ...guidance,
+        file: `host:${host}:${guidance.file}`,
+        scope: `host-global:${host}`,
+        reason: `Host-global ${host} file in ${root} needs review. ${guidance.reason}`,
+      };
+    }),
+  ];
+  const hasBlockingConflicts = (result.plan?.conflict || []).length > 0
+    || (result.globalPlan?.conflict || []).length > 0
+    || (result.hostPlans || []).some(hostPlan => (hostPlan.plan?.conflict || []).length > 0);
   const safeMergeCommand = commandFor(projectName, targetDir, {
     ...options,
     dryRun: false,
@@ -769,6 +889,14 @@ function createAgentGuidance(result, { projectName, targetDir, options, scan })
       mkdir: result.plan?.mkdir?.length || 0,
       backup: result.plan?.backup?.length || 0,
       overwrite: result.plan?.overwrite?.length || 0,
+      globalCreate: result.globalPlan?.create?.length || 0,
+      globalMkdir: result.globalPlan?.mkdir?.length || 0,
+      globalBackup: result.globalPlan?.backup?.length || 0,
+      globalOverwrite: result.globalPlan?.overwrite?.length || 0,
+      hostCreate: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.create?.length || 0), 0),
+      hostMkdir: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.mkdir?.length || 0), 0),
+      hostBackup: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.backup?.length || 0), 0),
+      hostOverwrite: (result.hostPlans || []).reduce((sum, hostPlan) => sum + (hostPlan.plan?.overwrite?.length || 0), 0),
     },
     aiMergeRequired,
     next,
@@ -839,6 +967,9 @@ function commandFor(projectName, targetDir, options) {
   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.installScope && options.installScope !== 'project') args.push('--install-scope', options.installScope);
+  if (options.globalDir) args.push('--global-dir', options.globalDir);
+  if (options.hostGlobalDir) args.push('--host-global-dir', options.hostGlobalDir);
   if (options.json) args.push('--json');
 
   return args.map(shellQuoteArg).join(' ');

package/src/prompts.js

@@ -40,6 +40,24 @@ export async function askTargetDir(projectName) {
   return dir.trim();
 }
 
+export async function askInstallScope() {
+  const scope = await p.select({
+    message: 'Harness install scope?',
+    initialValue: 'project',
+    options: [
+      { value: 'project', label: 'Project-local', hint: 'full Harness scaffold in this project' },
+      { value: 'global', label: 'Global + project state', hint: 'shared runtime plus project-local tasks/memory' },
+    ],
+  });
+
+  if (p.isCancel(scope)) {
+    p.cancel('Cancelled');
+    process.exit(0);
+  }
+
+  return scope;
+}
+
 export async function askConflictPolicy(scan) {
   const reason = scan.hasHarness
     ? 'Target already has Harness/. Choose how to handle existing files.'

package/templates/common/.claude/commands/wf-auto-spark.md

@@ -0,0 +1,16 @@
+---
+description: Run perpetual inspiration mode via the wf-auto-spark skill
+---
+
+# /wf-auto-spark
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto-spark/SKILL.md` (mirror: `.agents/skills/wf-auto-spark/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO-SPARK.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto-spark/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run perpetual adaptive auto-optimization via the wf-auto skill
+---
+
+# /wf-auto
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto/SKILL.md` (mirror: `.agents/skills/wf-auto/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto/SKILL.md` and follow it in place.

package/templates/{optional/skills/browser-e2e/.opencode → common/.claude}/commands/wf-browser.md

@@ -10,7 +10,7 @@ static help or script command.
 1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
 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.
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/HARNESS_BRIDGE.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/common/.claude/commands/wf-command-create.md

@@ -0,0 +1,58 @@
+# /wf-command-create
+
+Create or modify a Harness wf-* command surface atomically. Do not invoke a skill or start WF mode.
+
+## Classification
+
+DIRECT command. It is a Harness maintenance command: it must create or resume a task capsule, then update every command surface declared by `Harness/specs/runtime/command-surface.json`. Never loads `Harness/MEMORY.md` as part of command routing.
+
+## Usage
+
+/wf-command-create <wf-command-id> [--direct|--workflow] [--task <task-id>]
+
+- Command id must be `wf` or `wf-*` kebab-case.
+- Use an existing task capsule when `--task` is supplied or when the active task clearly matches.
+- Otherwise create a `task-<verb>-<noun>[-detail]` capsule with `node Harness/scripts/task-state.mjs record <task-id> --create --apply --json`.
+- Record the command id, classification, and validation evidence in the task capsule.
+
+## Required Surface Checklist
+
+Update all applicable files before returning:
+
+- `Harness/specs/runtime/command-surface.json`
+- `.claude/commands/<id>.md`
+- `.opencode/commands/<id>.md`
+- `.claude/skills/<id>/SKILL.md` when Codex compatibility or workflow routing is needed
+- `.agents/skills/<id>/SKILL.md` mirror when a Claude skill exists
+- Matching `templates/common/...` files
+- `CLAUDE.md` and `templates/common/CLAUDE.md`
+- `.claude/rules/ecc/common.md` and template mirror
+- `.claude/commands/wf-help.md`, `.opencode/commands/wf-help.md`, and template mirrors
+- `Harness/README.md`, `Harness/MEMORY.md`, and template mirrors
+- `Harness/scripts/validate-harness.mjs` and template mirror
+- `Harness/scripts/wf-remove.mjs` and template mirror
+- `tests/generator.test.js`, `tests/anti-drift.test.js`, and `tests/validate-harness.test.js`
+- `Harness/.harness-version`, `templates/common/.harness-version`, and ownership manifests via `node scripts/build-version.mjs`
+
+## Validation
+
+Run, at minimum:
+
+```bash
+npm test
+node Harness/scripts/validate-harness.mjs
+node templates/common/Harness/scripts/validate-harness.mjs
+node Harness/scripts/context-budget.mjs --json
+node scripts/build-version.mjs --check
+npm run check:mirrors
+git diff --check
+```
+
+If a check is blocked by an existing unrelated repository issue, record the command, failure, and reason in the task capsule.
+
+## Return
+
+- Command id and classification.
+- Task capsule path.
+- Files changed by surface category.
+- Verification results.

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

@@ -3,6 +3,9 @@
 Return this help table directly. Do not invoke a skill, do not start WF mode,
 do not dispatch agents, and do not edit files.
 
+Codex compatibility: `$wf-help` or `/skills wf-help` loads the `wf-help` shim,
+which returns this same table without loading `Harness/MEMORY.md` or entering WF.
+
 | Command | Type | Usage | Purpose |
 | --- | --- | --- | --- |
 | `/wf-help` | direct command | `/wf-help` | Show this command table. |
@@ -12,14 +15,18 @@ do not dispatch agents, and do not edit files.
 | `/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` | Peer CLI review through Claude/Codex/OpenCode, with reviewer subagent fallback. |
 | `/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-browser <task>` | workflow skill | `/wf-browser verify checkout flow` | Built-in browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |
 | `/wf-readme <task>` | workflow skill | `/wf-readme polish quickstart` | Preserve, merge, or improve README docs without trampling existing project documentation. |
 | `/wf-update` | direct command | `/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. |
+| `/wf-task-record <task-id>` | direct command | `/wf-task-record my-feature --create` | Record user intent into a task capsule (wraps task-state.mjs). |
+| `/wf-task-list` | direct command | `/wf-task-list` | List all task capsules with status, phase, and dependencies. |
+| `/wf-task-archive [--apply]` | direct command | `/wf-task-archive --apply` | Archive completed task capsules (dry-run by default). |
+| `/wf-command-create <wf-command-id>` | direct command | `/wf-command-create wf-report --direct` | Create or modify wf-* command surfaces atomically from the command registry. |
 
 Source of truth: `Harness/README.md#Skill Commands` plus installed skills under
-`.claude/skills/` (Claude Code) or `.agents/skills/` (Codex). In OpenCode the
-same skills load from `.claude/skills/`, `.agents/skills/`, and `.opencode/skills/`.
-In OpenCode, every workflow command above is also visible as a thin command
-wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper only
-routes to the matching skill adapter and does not duplicate the workflow.
+`.claude/skills/` (Claude Code and OpenCode adapters) or `.agents/skills/`
+(Codex). In OpenCode, every workflow command above is visible as a thin command
+wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper routes
+to the matching `.claude/skills/<command>/SKILL.md` adapter and does not
+duplicate the workflow.

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

@@ -0,0 +1,16 @@
+---
+description: Run the context-master -> memory-master learning cycle via the wf-learn skill
+---
+
+# /wf-learn
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-learn/SKILL.md` (mirror: `.agents/skills/wf-learn/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/MEMORY_PROTOCOL.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-learn/SKILL.md` and follow it in place.

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

@@ -0,0 +1,20 @@
+---
+description: Run WF-MAX with mandatory subagent fan-out and recorded degradation
+---
+
+# /wf-max
+
+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. Load and follow `.claude/skills/wf-max/SKILL.md` (mirror: `.agents/skills/wf-max/SKILL.md`) and `Harness/specs/workflows/WF-MAX.md`.
+3. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+4. MUST attempt native runtime subagent fan-out before planning is considered complete:
+   - start `task-scribe` when available for task ledger/state;
+   - start W0 exploration through manager/explorer/researcher roles with disjoint read sets;
+   - when running in OpenCode, require project `opencode.json` to have `subagent_depth >= 2` and manager agents to have `permission.task` allowlists for manager -> worker fan-out;
+   - if nested manager fan-out is unavailable, dispatch leaf workers directly from the primary agent with exact WF-MAX dispatch packets.
+5. In every runtime, MUST attempt native subagent fan-out before implementation planning is considered complete; never silently continue as a solo controller.
+6. If native fan-out fails, record `fanoutAttempted: true`, runtime, channel tried, agents requested, failure/degradation reason, and the fallback path in `Harness/tasks/<task-id>/PLAN.md` or `PROGRESS.md`.
+7. Continue with WF-Max-Useful by default or WF-Max-Strict only when the user explicitly requests strict mode.

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

@@ -0,0 +1,16 @@
+---
+description: Run the README preservation and improvement workflow via the wf-readme skill
+---
+
+# /wf-readme
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-readme/SKILL.md` (mirror: `.agents/skills/wf-readme/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the project root \`README.md\` ownership rules are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-readme/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run safe harness removal via the wf-remove skill
+---
+
+# /wf-remove
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-remove/SKILL.md` (mirror: `.agents/skills/wf-remove/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/scripts/wf-remove.mjs` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-remove/SKILL.md` and follow it in place.

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

@@ -0,0 +1,16 @@
+---
+description: Run peer CLI or reviewer-subagent review via the wf-review skill
+---
+
+# /wf-review
+
+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. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-review/SKILL.md` (mirror: `.agents/skills/wf-review/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the wf-review peer-review contract are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-review/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-task-archive.md

@@ -0,0 +1,26 @@
+# /wf-task-archive
+
+Archive completed/obsolete task capsules to `Harness/tasks/_archive/`. Do not invoke a skill or start WF mode.
+
+## Classification
+
+DIRECT command. Wraps `node Harness/scripts/task-state.mjs archive`. Never loads Harness/MEMORY.md.
+
+## Usage
+
+/wf-task-archive [--dry-run] [--apply] [--task <id>] [--keep <n>]
+
+- Defaults to dry-run (`--dry-run`) without `--apply`.
+- With `--apply`: moves eligible task directories into yearly subdirectories under `_archive/`.
+- With `--task <id>`: targets a specific task for archive eligibility check.
+- With `--keep <n>`: keeps N most recent non-archived task capsules (default 5).
+- Tasks with active, blocked, in_progress, running, pending, or needs-user-decision status are never auto-archived.
+
+## Execution
+
+Run: `node Harness/scripts/task-state.mjs archive [--dry-run] [--apply] [--task <id>] [--keep <n>] [--json]`
+
+## Return
+
+- JSON output with archive plan: scanned, archiveable, toArchive, kept, skipped counts and per-task results.
+- If the command fails, report the error and do not retry.

package/templates/common/.claude/commands/wf-task-list.md

@@ -0,0 +1,24 @@
+# /wf-task-list
+
+List Harness task capsules with state, phase, status, and dependency info. Do not invoke a skill or start WF mode.
+
+## Classification
+
+DIRECT command. Wraps `node Harness/scripts/task-state.mjs list --json`. Never loads Harness/MEMORY.md.
+
+## Usage
+
+/wf-task-list [--json]
+
+- By default, returns a human-readable listing of all task capsules.
+- With --json, returns structured JSON output.
+- Shows active, open, blocked, verified tasks with dependency info.
+
+## Execution
+
+Run: `node Harness/scripts/task-state.mjs list --json`
+
+## Return
+
+- JSON output of all task capsules with status, phase, dependencies, and archive eligibility.
+- If the command fails, report the error and do not retry.