create-harness-vibe-coding 0.8.17 → 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('');
@@ -58,8 +61,9 @@ if (showHelp) {
   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,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 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-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

@@ -19,6 +19,10 @@ which returns this same table without loading `Harness/MEMORY.md` or entering WF
 | `/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 and OpenCode adapters) or `.agents/skills/`

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.

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

@@ -0,0 +1,24 @@
+# /wf-task-record
+
+Record a task into a Harness task capsule. Do not invoke a skill or start WF mode.
+
+## Classification
+
+DIRECT command. Wraps `node Harness/scripts/task-state.mjs record`. Never loads Harness/MEMORY.md.
+
+## Usage
+
+/wf-task-record [<task-id>] [--title <slug>] [--note <text>] [--context <text>] [--new] [--create] [--status <status>] [--mode <mode>] [--text "description"]
+
+- With <task-id>: record to that task (existing semantics).
+- Without <task-id>: --title/--note/--context required. Deterministically matches open tasks; updates if unique match found; creates new if no match; fails if ambiguous unless --new.
+- Never uses LLM or embeddings — slug + keyword overlap only.
+
+## Execution
+
+Run: `node Harness/scripts/task-state.mjs record [<task-id>] [--title <slug>] [--note <text>] [--context <text>] [--new] [--create] [--apply] [--text "..."] [--status <status>] [--mode <mode>] [--json]`
+
+## Return
+
+- Output of `node Harness/scripts/task-state.mjs record ... --json`
+- If the command fails, report the error and do not retry.

package/templates/common/.claude/rules/ecc/common.md

@@ -8,7 +8,7 @@ alwaysApply: true
 ## Context
 
 - Start with `CLAUDE.md`. When `Harness/` exists, also read `Harness/memory/startup-hints.md` (L2 lightweight digest, not full router).
-- When the user explicitly invokes a workflow command (`/wf-*`, `$wf-*`, or `/skills wf-*`), excluding `/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update`, load `Harness/MEMORY.md` and `Harness/README.md`.
+- When the user explicitly invokes a workflow command (`/wf-*`, `$wf-*`, or `/skills wf-*`), excluding `/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, `/skills wf-update`, `/wf-task-record`, `$wf-task-record`, `/skills wf-task-record`, `/wf-task-list`, `$wf-task-list`, `/skills wf-task-list`, `/wf-task-archive`, `$wf-task-archive`, `/skills wf-task-archive`, `/wf-command-create`, `$wf-command-create`, and `/skills wf-command-create`, load `Harness/MEMORY.md` and `Harness/README.md`.
 - For simple single-step tasks without `/wf-*`, operate in direct mode: skip the Harness router and execute directly.
 - Do not bulk-read `Harness/`. Load by router trigger.
 - Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.

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

@@ -9,13 +9,10 @@ Use this skill before shelling out to `claude`, `codex`, or `opencode` from Harn
 
 ## 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.
+Prefer installed help (`claude --help`, `codex exec --help`, `opencode run --help`), then official docs for cost/auth/JSON/resume/tools/telemetry; record command, source, stdout/stderr shape, and failures.
 
 ## 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.
@@ -26,19 +23,15 @@ Use this skill before shelling out to `claude`, `codex`, or `opencode` from Harn
 
 ## 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"`.
+- Stdin modes: `cat prompt.txt | codex exec -`; `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"`.
+- 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"`.
@@ -48,31 +41,27 @@ Use this skill before shelling out to `claude`, `codex`, or `opencode` from Harn
 
 - 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.
+- Do not trust exit code alone. Fail on empty/non-JSON stdout, error/budget/fallback terminal fields, or missing final model text.
 - 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.
+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.
+- 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.
+- Fail on empty/non-JSON stdout, explicit error events, budget errors, fallback warnings, or missing final model text.
+- For `claude -p --output-format json`, check `is_error`, `subtype`, and `result` fields before treating output as review evidence.
+- For `opencode run --format json`, extract `text` from JSONL events; the stream is not a single review result.
 
 ## 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.
+- 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.
+- 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
@@ -102,8 +91,7 @@ Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`:
 ## 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.
+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.
@@ -111,9 +99,6 @@ Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`:
 
 ## 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
+- Claude Code CLI/cache/statusline: https://code.claude.com/docs/en/cli-reference
 - 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-command-create/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: wf-command-create
+description: Create or modify Harness wf-* commands atomically. Use for $wf-command-create or /skills wf-command-create in Codex, and for /wf-command-create in Claude Code/OpenCode. Direct/compat maintenance command; creates or resumes a task capsule but does not enter WF mode.
+---
+
+# WF Command Create Adapter
+
+This skill is a Codex compatibility shim for the direct `/wf-command-create`
+maintenance command. It does not start WF mode or load `Harness/MEMORY.md`.
+
+## Invocation
+
+- Codex: `$wf-command-create` or `/skills` then choose `wf-command-create`.
+- Claude Code: `/wf-command-create` direct command from `.claude/commands/wf-command-create.md`.
+- OpenCode: `/wf-command-create` direct command from `.opencode/commands/wf-command-create.md`.
+
+## Load
+
+- `.claude/commands/wf-command-create.md`
+- `Harness/specs/runtime/command-surface.json`
+
+## Rules
+
+Execute the command instructions from `.claude/commands/wf-command-create.md`.
+
+- Create or resume the task capsule first.
+- Update `command-surface.json` before creating command files.
+- Keep `.agents/skills/<id>/SKILL.md` byte-identical to `.claude/skills/<id>/SKILL.md`.
+- Keep `.opencode/commands/<id>.md` body-identical to `.claude/commands/<id>.md`.
+- Run the validation list from the command file or record why a check could not complete.
+
+## Return
+
+- Task capsule path
+- Command classification
+- Changed surface checklist
+- Verification results