dev-harness-cli 1.0.0

package/adapters/hermes/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: "dev-harness"
+description: "Hermes adapter for the dev-harness CLI — phase-based development pipeline with scaffold, stack detection, gate validation, inner/outer loops, sprint contracts, git worktree management, and rollback/checkpoint. Load this skill when working inside a harness-scaffolded project."
+license: MIT
+category: software-development
+risk: high
+source: self
+date_added: "2026-06-20"
+metadata:
+  version: 1.1.0
+  paradigm: "Phase-based agentic development pipeline"
+  changelog:
+    - "1.1.0 — Moved to adapters/hermes/ (tool-agnostic adapter structure)."
+    - "1.0.0 — Hermes skill wrapper for dev-harness CLI. Wraps init, phase, and validate commands."
+---
+
+# Dev Harness — Hermes Skill Wrapper
+
+Triggers on: "harness-dev", "harness init", "harness scaffold", "new project", "phase pipeline"
+
+## Prerequisites
+
+- Node.js >= 18
+- `harness-dev` CLI accessible via `node cli/harness-dev.mjs` from the project root
+- A git repository (for worktree, rollback, and checkpoint commands)
+
+## Actions
+
+### `harness-dev init [--stack <name>] [--target <dir>] [--force]`
+
+Scaffold harness in current project. If stack not specified, auto-detects from target directory.
+
+```bash
+node cli/harness-dev.mjs init --stack python --target my-project
+```
+
+### `harness-dev status [--json] [--target <dir>]`
+
+Show current project state — phase, mode, gate status, recent lessons.
+
+### `harness-dev phase <name>`
+
+Run a phase: `define` → `plan` → `build` → `verify` → `simplify` → `review` → `ship`
+
+### `harness-dev validate [--json] [--phase <name>] [--feature <id>] [--task <id>]`
+
+Run gate checks for current or specified phase.
+
+### `harness-dev set-mode copilot|autopilot`
+
+Switch between one-phase-at-a-time (copilot) and auto-advance (autopilot).
+
+### `harness-dev learn <message>`
+
+Append a lesson to progress.md.
+
+### `harness-dev config get <key>` / `harness-dev config set <key> <value>`
+
+Read/write harness-config.json via dot-notation.
+
+### `harness-dev contract propose|review|status|escalate`
+
+Sprint contract negotiation workflow.
+
+### `harness-dev worktree create|list|prune|remove <name>`
+
+Git worktree management with harness scaffold.
+
+### `harness-dev rollback list|to|branch`
+
+Checkpoint recovery with tag-based state restoration.
+
+### `harness-dev checkpoint create <label>`
+
+Manual checkpoint tagging.
+
+## Scripts
+
+Thin wrapper scripts are provided under `scripts/` that resolve the CLI relative to the project root:
+
+- `scripts/init.mjs` — wrapper for `harness-dev init`
+- `scripts/phase.mjs` — wrapper for `harness-dev phase`
+- `scripts/validate.mjs` — wrapper for `harness-dev validate`
+
+Use these when you want to invoke harness commands from other Hermes skill scripts or automation.
+
+## Templates
+
+The `templates/` directory is a symlink to `../../../templates` (the project's main templates directory). Template files use `{{VAR}}` substitution for stack-aware scaffolding.

package/adapters/hermes/scripts/init.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Hermes skill wrapper — harness-dev init
+ *
+ * Thin wrapper that resolves the CLI relative to this skill's location
+ * and forwards arguments to the init command.
+ *
+ * Usage: node hermes/skill/dev-harness/scripts/init.mjs [--stack <name>] [--target <dir>] [--force] [--no-git] [--json]
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..', '..', '..', '..');
+const cliPath = resolve(projectRoot, 'cli/harness-dev.mjs');
+
+const args = process.argv.slice(2);
+
+const result = spawnSync('node', [cliPath, 'init', ...args], {
+  stdio: 'inherit',
+  cwd: projectRoot,
+  env: { ...process.env },
+});
+
+process.exit(result.status ?? 1);

package/adapters/hermes/scripts/phase.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Hermes skill wrapper — harness-dev phase
+ *
+ * Thin wrapper that resolves the CLI relative to this skill's location
+ * and forwards arguments to the phase command.
+ *
+ * Usage: node hermes/skill/dev-harness/scripts/phase.mjs <phase-name> [--json] [--target <dir>]
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..', '..', '..', '..');
+const cliPath = resolve(projectRoot, 'cli/harness-dev.mjs');
+
+const args = process.argv.slice(2);
+
+const result = spawnSync('node', [cliPath, 'phase', ...args], {
+  stdio: 'inherit',
+  cwd: projectRoot,
+  env: { ...process.env },
+});
+
+process.exit(result.status ?? 1);

package/adapters/hermes/scripts/validate.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Hermes skill wrapper — harness-dev validate
+ *
+ * Thin wrapper that resolves the CLI relative to this skill's location
+ * and forwards arguments to the validate command.
+ *
+ * Usage: node hermes/skill/dev-harness/scripts/validate.mjs [--json] [--phase <name>] [--feature <id>] [--task <id>] [--target <dir>]
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '..', '..', '..', '..');
+const cliPath = resolve(projectRoot, 'cli/harness-dev.mjs');
+
+const args = process.argv.slice(2);
+
+const result = spawnSync('node', [cliPath, 'validate', ...args], {
+  stdio: 'inherit',
+  cwd: projectRoot,
+  env: { ...process.env },
+});
+
+process.exit(result.status ?? 1);

package/adapters/kilo-code/README.md

@@ -0,0 +1,23 @@
+# Kilo Code Adapter
+
+Kilo Code reads .kilocoderules.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool kilo-code --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.kilocoderules` — Kilo Code-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "kilo-code"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .kilocoderules) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/openclaw/README.md

@@ -0,0 +1,22 @@
+# OpenClaw Adapter
+
+OpenClaw — assumed to read AGENTS.md.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool openclaw --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `harness-config.json` — with `agentTool: "openclaw"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. AGENTS.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/pi/README.md

@@ -0,0 +1,22 @@
+# Pi Adapter
+
+Pi — assumed to read AGENTS.md.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool pi --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `harness-config.json` — with `agentTool: "pi"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. AGENTS.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/roo/README.md

@@ -0,0 +1,23 @@
+# Roo Code Adapter
+
+Roo Code reads .roorules.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool roo --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.roorules` — Roo Code-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "roo"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .roorules) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/windsurf/README.md

@@ -0,0 +1,23 @@
+# Windsurf Adapter
+
+Windsurf (Codeium) reads .windsurfrules as system context.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool windsurf --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.windsurfrules` — Windsurf-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "windsurf"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .windsurfrules) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/cli/commands/checkpoint.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * checkpoint — Manual checkpoint tagging (create).
+ *
+ * T18 implementation:
+ *   create <label> — git tag -a manual/<label> -m "checkpoint: <label>"
+ *
+ * This complements the rollback system. Manual checkpoints let users
+ * save named recovery points (e.g. "before-refactor") that appear
+ * in `rollback list` and can be used with `rollback to/branch`.
+ *
+ * Usage: harness-dev checkpoint create <label>
+ */
+import { die, CliError, EXIT } from '../lib/errors.mjs';
+import { execGit, getGitRoot, gitTagExists, createGitTag } from '../lib/git.mjs';
+import { parseCommandArgs } from '../lib/command-helpers.mjs';
+
+export default async function checkpointCommand(args) {
+  const { json, targetDir, force } = parseCommandArgs(args);
+  const sub = args.subcommand;
+  const label = args.positionals[0];
+
+  if (sub !== 'create' || !label) {
+    die(new CliError('Usage: harness-dev checkpoint create <label> [--force]', EXIT.USAGE_ERROR), json);
+    return;
+  }
+
+  const gitRoot = getGitRoot(targetDir);
+  if (!gitRoot) {
+    const msg = 'Not inside a git repository. Checkpoints require git tags.';
+    if (json) {
+      process.stdout.write(JSON.stringify({ command: 'checkpoint', subcommand: 'create', label, status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    return;
+  }
+
+  // Verify working tree is clean (encourage checkpointing at known states).
+  // --force skips this check for users who intentionally checkpoint dirty states.
+  const cleanCheck = execGit('git status --porcelain', gitRoot);
+  if (!force && cleanCheck.ok && cleanCheck.stdout.length > 0) {
+    if (json) {
+      process.stdout.write(JSON.stringify({ command: 'checkpoint', subcommand: 'create', label, status: 'error', message: 'Working tree is not clean. Commit or stash changes, or use --force to checkpoint anyway.' }) + '\n');
+    } else {
+      process.stderr.write('Error: Working tree is not clean. Commit or stash changes, or use --force to checkpoint anyway.\n');
+    }
+    return;
+  }
+
+  const tagName = `manual/${label}`;
+
+  // Check tag doesn't already exist
+  if (gitTagExists(tagName, gitRoot)) {
+    const msg = `Tag "${tagName}" already exists. Use a different label.`;
+    if (json) {
+      process.stdout.write(JSON.stringify({ command: 'checkpoint', subcommand: 'create', label, tag: tagName, status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    return;
+  }
+
+  // Create the annotated tag
+  const created = createGitTag(tagName, `checkpoint: ${label}`, gitRoot);
+
+  if (!created) {
+    const msg = `Failed to create checkpoint tag: ${tagName}`;
+    if (json) {
+      process.stdout.write(JSON.stringify({ command: 'checkpoint', subcommand: 'create', label, tag: tagName, status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    return;
+  }
+
+  // Get the hash the tag points to
+  const hashR = execGit(`git rev-parse --short "${tagName}"`, gitRoot);
+  const hash = hashR.ok ? hashR.stdout : '—';
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      command: 'checkpoint',
+      subcommand: 'create',
+      label,
+      tag: tagName,
+      hash,
+      status: 'ok',
+      message: `Checkpoint "${tagName}" created (${hash})`,
+    }) + '\n');
+  } else {
+    process.stdout.write(`✓ Checkpoint "${tagName}" created (${hash})\n`);
+  }
+}

package/cli/commands/config.mjs

@@ -0,0 +1,268 @@
+/**
+ * config — Get/set/list harness-config.json values.
+ *
+ * Uses state.mjs for dot-notation read/write with persistence.
+ *
+ * Usage:
+ *   harness-dev config list              — list all parameters with descriptions
+ *   harness-dev config get [key]         — get a value or all config
+ *   harness-dev config set <key> <value> — set a value
+ *
+ * Examples:
+ *   harness-dev config list
+ *   harness-dev config list --json
+ *   harness-dev config get gates.enabled
+ *   harness-dev config set gates.enabled true
+ *   harness-dev config set maxRetries 5
+ */
+import { resolve } from 'node:path';
+import { die, CliError, EXIT } from '../lib/errors.mjs';
+import { get as stateGet, set as stateSet, loadConfig } from '../lib/state.mjs';
+import { CONFIG_PARAMS, getGroups, getParamsByGroup, getParamMeta } from '../lib/config-registry.mjs';
+
+export default async function configCommand(args) {
+  const json = !!(args.json || args.flags?.json);
+  const sub = args.subcommand; // 'get', 'set', or 'list'
+  const pos = args.positionals; // key[, value] for set
+  const rawTarget = args.flags?.target;
+  const targetDir = (typeof rawTarget === 'string') ? resolve(rawTarget) : process.cwd();
+
+  if (!sub || (sub !== 'get' && sub !== 'set' && sub !== 'list')) {
+    die(new CliError(
+      'Usage: harness-dev config list | config get [key] | config set <key> <value>',
+      EXIT.USAGE_ERROR,
+    ), json);
+    return;
+  }
+
+  // ── list ─────────────────────────────────────────────────────────────────
+  if (sub === 'list') {
+    const { config, ok } = loadConfig(targetDir);
+
+    // Helper to resolve current value from config via dot-notation
+    function resolveValue(key) {
+      if (!ok) { return null; }
+      const parts = key.split('.');
+      let val = config;
+      for (const p of parts) {
+        val = val?.[p];
+      }
+      return val ?? null;
+    }
+
+    if (json) {
+      const params = CONFIG_PARAMS.map(p => ({
+        key: p.key,
+        group: p.group,
+        label: p.label,
+        type: p.type,
+        description: p.description,
+        default: p.default,
+        options: p.options || null,
+        editable: p.editable,
+        value: resolveValue(p.key),
+      }));
+      process.stdout.write(JSON.stringify({
+        command: 'config',
+        subcommand: 'list',
+        status: 'ok',
+        message: `${params.length} configuration parameters`,
+        params,
+      }, null, 2) + '\n');
+      return;
+    }
+
+    // Human output — grouped table
+    process.stdout.write('═══ Harness Configuration ═══\n\n');
+    if (!ok) {
+      process.stdout.write('  No harness-config.json found. Run: harness-dev init\n\n');
+      return;
+    }
+
+    for (const group of getGroups()) {
+      const params = getParamsByGroup(group);
+      const readOnly = params[0]?.editable === false;
+      process.stdout.write(`── ${group}${readOnly ? ' (read-only)' : ''} ──\n`);
+
+      // Calculate column widths
+      const maxKey = Math.max(...params.map(p => p.key.length), 10);
+      const maxVal = Math.max(...params.map(p => {
+        const v = resolveValue(p.key);
+        return JSON.stringify(v)?.length ?? 4;
+      }), 7);
+
+      for (const p of params) {
+        const val = resolveValue(p.key);
+        const valStr = JSON.stringify(val) ?? 'null';
+        const opts = p.options ? `[${p.options.filter(o => o !== null).slice(0, 4).join('|')}${p.options.length > 4 ? '|...' : ''}]` : `[${p.type}]`;
+        const padKey = p.key.padEnd(maxKey);
+        const padVal = valStr.padEnd(Math.min(maxVal, 20));
+        process.stdout.write(`  ${padKey}  ${padVal}  ${opts.padEnd(16)} ${p.description.slice(0, 60)}\n`);
+      }
+      process.stdout.write('\n');
+    }
+
+    process.stdout.write('Edit with: harness-dev config set <key> <value>\n');
+    process.stdout.write('Full docs: docs/CONFIGURATION.md\n');
+    return;
+  }
+
+  // ── get ──────────────────────────────────────────────────────────────────
+  if (sub === 'get') {
+    const key = pos[0] || null;
+    const { value, ok, error } = stateGet(targetDir, key);
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'config',
+        subcommand: 'get',
+        key,
+        value: ok ? value : null,
+        status: ok ? 'ok' : 'error',
+        message: ok ? null : (error || 'Unknown error'),
+      }) + '\n');
+      return;
+    }
+
+    // Human output
+    if (!ok) {
+      process.stdout.write(`Config not available: ${error}\n`);
+      return;
+    }
+    if (key === null) {
+      process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+    } else {
+      process.stdout.write(`${key} = ${JSON.stringify(value)}\n`);
+    }
+    return;
+  }
+
+  // ── set ──────────────────────────────────────────────────────────────────
+  if (sub === 'set') {
+    if (pos.length < 2) {
+      die(new CliError(
+        'Usage: harness-dev config set <key> <value>\n' +
+        '  String values: config set mode copilot\n' +
+        '  Boolean values: config set gates.enabled true\n' +
+        '  Numeric values: config set maxRetries 5',
+        EXIT.USAGE_ERROR,
+      ), json);
+      return;
+    }
+
+    const key = pos[0];
+    const rawValue = pos.slice(1).join(' '); // support multi-word values
+
+    // Get parameter metadata for type-aware coercion
+    const meta = getParamMeta(key);
+
+    // Type coercion: try JSON for arrays/objects, then numbers and booleans
+    let parsedValue;
+    if (meta && (meta.type === 'array' || meta.type === 'object')) {
+      // Array/object types: parse as JSON
+      try {
+        parsedValue = JSON.parse(rawValue);
+      } catch {
+        // If JSON parse fails, keep as string (let type check below catch it)
+        parsedValue = rawValue;
+      }
+    } else if (rawValue === 'true') {
+      parsedValue = true;
+    } else if (rawValue === 'false') {
+      parsedValue = false;
+    } else if (/^-?\d+(\.\d+)?$/.test(rawValue)) {
+      parsedValue = Number(rawValue);
+    } else if (rawValue === 'null') {
+      parsedValue = null;
+    } else {
+      parsedValue = rawValue;
+    }
+
+    // Validate against config-registry if parameter is known
+    if (meta) {
+      // Check editability
+      if (!meta.editable) {
+        const msg = `"${key}" is read-only (managed by harness). Cannot set manually.`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+      // Check enum options
+      if (meta.options && !meta.options.includes(parsedValue)) {
+        const opts = meta.options.map(o => o === null ? 'null' : `"${o}"`).join(', ');
+        const msg = `Invalid value for "${key}". Allowed: ${opts}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, value: parsedValue, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+      // Check type for integers
+      if (meta.type === 'integer' && typeof parsedValue !== 'number') {
+        const msg = `"${key}" expects an integer, got ${typeof parsedValue}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, value: parsedValue, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+      // Check type for booleans
+      if (meta.type === 'boolean' && typeof parsedValue !== 'boolean') {
+        const msg = `"${key}" expects a boolean (true/false), got ${typeof parsedValue}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, value: parsedValue, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+      // Check type for arrays
+      if (meta.type === 'array' && !Array.isArray(parsedValue)) {
+        const msg = `"${key}" expects a JSON array, got ${typeof parsedValue}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, value: parsedValue, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+      // Check type for objects
+      if (meta.type === 'object' && (typeof parsedValue !== 'object' || Array.isArray(parsedValue) || parsedValue === null)) {
+        const msg = `"${key}" expects a JSON object, got ${Array.isArray(parsedValue) ? 'array' : typeof parsedValue}`;
+        if (json) {
+          process.stdout.write(JSON.stringify({ command: 'config', subcommand: 'set', key, value: parsedValue, status: 'error', message: msg }) + '\n');
+        } else {
+          process.stderr.write(`✗ ${msg}\n`);
+        }
+        return;
+      }
+    }
+
+    const result = stateSet(targetDir, key, parsedValue);
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'config',
+        subcommand: 'set',
+        key,
+        value: parsedValue,
+        status: result.ok ? 'ok' : 'error',
+        message: result.ok
+          ? `Set ${key} = ${JSON.stringify(parsedValue)}`
+          : (result.error || 'Unknown error'),
+      }) + '\n');
+      return;
+    }
+
+    if (result.ok) {
+      process.stdout.write(`✓ ${key} = ${JSON.stringify(parsedValue)}\n`);
+    } else {
+      process.stderr.write(`✗ ${result.error}\n`);
+    }
+  }
+}