@claude-flow/cli 3.28.0 → 3.29.0

package/plugins/ruflo-metaharness/skills/harness-gepa/SKILL.md

@@ -1,65 +1,65 @@
----
-name: harness-gepa
-description: Inspect and audit GEPA genomes via the `@metaharness/darwin/gepa` library entry (darwin 0.8.0) — load/validate a genome (default: the shipped cand-6 promotion), render the system prompt a genome compiles to, or classify failure modes in a run transcript. The `gepaOptimize` loop itself is library-only (bring your own evaluator) and not surfaced here — use `harness-evolve` for sandbox-scored evolution. Degrades gracefully when @metaharness/darwin is absent.
-argument-hint: "--op genome|validate|render|analyze [--path <genome.json>] [--transcript <t.json>] [--alert-on-invalid]"
-allowed-tools: Bash
----
-
-Surfaces the GEPA (genetic-evolution prompt-adaptation) *library* exports
-from `@metaharness/darwin/gepa`. Unlike the other skills in this plugin
-there is no CLI binary behind this — the script dynamic-imports the library
-(local resolution first, versioned cache install as fallback) and calls the
-subprocess-safe subset.
-
-## When to use
-
-- **Adopting an evolved policy**: `--op render` shows the actual system
-  prompt a genome compiles to — read THAT, not the raw JSON, before
-  wiring a genome into a harness.
-- **Auditing a promotion**: `--op genome` loads + validates the shipped
-  cand-6 genome (first holdout-confirmed cheap-tier promotion; provenance
-  ships in the package) or any genome file you point at.
-- **CI gate on genome edits**: `--op validate --alert-on-invalid` exits 1
-  on structural errors.
-- **Debugging a bad run**: `--op analyze --transcript run.json` classifies
-  failure modes (GEPA's failure-class taxonomy) from a transcript array.
-
-## What is deliberately NOT here
-
-`gepaOptimize` — the optimization loop takes an in-process
-`evaluate(candidate)` callback ("bring your own evaluator") that cannot
-cross a subprocess boundary. Two supported paths instead:
-
-1. **Library consumers**: `import { gepaOptimize, loadCand6Genome } from '@metaharness/darwin/gepa'`
-2. **Sandbox-scored evolution**: `harness-evolve` (darwin CLI `evolve`),
-   which pairs GEPA with its own sandbox evaluators.
-
-## Algorithm
-
-Implementation: [`scripts/gepa.mjs`](../../scripts/gepa.mjs).
-
-1. `import('@metaharness/darwin/gepa')`; on MODULE_NOT_FOUND fall back to a
-   one-time `npm install --prefix ~/.ruflo/darwin-cache-0.8.0` and import
-   the cached `dist/gepa/index.js` (versioned dir → pin bumps invalidate).
-2. Dispatch `--op`:
-   - `genome`  → `loadGenome(fs, path)` or `loadCand6Genome()` + `validateGenome`
-   - `validate` → `validateGenome(rawJson)` (raw parse so broken files reach
-     the validator instead of throwing in the loader)
-   - `render`  → `buildSystemFromGenome(genome, ext?, glob?)`
-   - `analyze` → `analyzeTranscript(entries)`
-3. Emit one JSON object; exit 0 (or 1 under `--alert-on-invalid`, 2 on bad input).
-
-## Examples
-
-```bash
-node scripts/gepa.mjs --op genome                          # cand-6 + validation
-node scripts/gepa.mjs --op render | jq -r .system         # what does cand-6 SAY?
-node scripts/gepa.mjs --op validate --path my-genome.json --alert-on-invalid
-node scripts/gepa.mjs --op analyze --transcript run.json
-```
-
-## Exit codes
-
-- `0` — op completed (or degraded — darwin not installable)
-- `1` — `--alert-on-invalid` and validation found errors
-- `2` — config error (unknown op, missing/broken input file)
+---
+name: harness-gepa
+description: Inspect and audit GEPA genomes via the `@metaharness/darwin/gepa` library entry (darwin 0.8.0) — load/validate a genome (default: the shipped cand-6 promotion), render the system prompt a genome compiles to, or classify failure modes in a run transcript. The `gepaOptimize` loop itself is library-only (bring your own evaluator) and not surfaced here — use `harness-evolve` for sandbox-scored evolution. Degrades gracefully when @metaharness/darwin is absent.
+argument-hint: "--op genome|validate|render|analyze [--path <genome.json>] [--transcript <t.json>] [--alert-on-invalid]"
+allowed-tools: Bash
+---
+
+Surfaces the GEPA (genetic-evolution prompt-adaptation) *library* exports
+from `@metaharness/darwin/gepa`. Unlike the other skills in this plugin
+there is no CLI binary behind this — the script dynamic-imports the library
+(local resolution first, versioned cache install as fallback) and calls the
+subprocess-safe subset.
+
+## When to use
+
+- **Adopting an evolved policy**: `--op render` shows the actual system
+  prompt a genome compiles to — read THAT, not the raw JSON, before
+  wiring a genome into a harness.
+- **Auditing a promotion**: `--op genome` loads + validates the shipped
+  cand-6 genome (first holdout-confirmed cheap-tier promotion; provenance
+  ships in the package) or any genome file you point at.
+- **CI gate on genome edits**: `--op validate --alert-on-invalid` exits 1
+  on structural errors.
+- **Debugging a bad run**: `--op analyze --transcript run.json` classifies
+  failure modes (GEPA's failure-class taxonomy) from a transcript array.
+
+## What is deliberately NOT here
+
+`gepaOptimize` — the optimization loop takes an in-process
+`evaluate(candidate)` callback ("bring your own evaluator") that cannot
+cross a subprocess boundary. Two supported paths instead:
+
+1. **Library consumers**: `import { gepaOptimize, loadCand6Genome } from '@metaharness/darwin/gepa'`
+2. **Sandbox-scored evolution**: `harness-evolve` (darwin CLI `evolve`),
+   which pairs GEPA with its own sandbox evaluators.
+
+## Algorithm
+
+Implementation: [`scripts/gepa.mjs`](../../scripts/gepa.mjs).
+
+1. `import('@metaharness/darwin/gepa')`; on MODULE_NOT_FOUND fall back to a
+   one-time `npm install --prefix ~/.ruflo/darwin-cache-0.8.0` and import
+   the cached `dist/gepa/index.js` (versioned dir → pin bumps invalidate).
+2. Dispatch `--op`:
+   - `genome`  → `loadGenome(fs, path)` or `loadCand6Genome()` + `validateGenome`
+   - `validate` → `validateGenome(rawJson)` (raw parse so broken files reach
+     the validator instead of throwing in the loader)
+   - `render`  → `buildSystemFromGenome(genome, ext?, glob?)`
+   - `analyze` → `analyzeTranscript(entries)`
+3. Emit one JSON object; exit 0 (or 1 under `--alert-on-invalid`, 2 on bad input).
+
+## Examples
+
+```bash
+node scripts/gepa.mjs --op genome                          # cand-6 + validation
+node scripts/gepa.mjs --op render | jq -r .system         # what does cand-6 SAY?
+node scripts/gepa.mjs --op validate --path my-genome.json --alert-on-invalid
+node scripts/gepa.mjs --op analyze --transcript run.json
+```
+
+## Exit codes
+
+- `0` — op completed (or degraded — darwin not installable)
+- `1` — `--alert-on-invalid` and validation found errors
+- `2` — config error (unknown op, missing/broken input file)

package/plugins/ruflo-metaharness/skills/harness-learn/SKILL.md

@@ -1,65 +1,65 @@
----
-name: harness-learn
-description: Run a GEPA learning cycle via `metaharness learn` (upstream ADR-235, metaharness@0.3.0) — optimizes a harness genome against a SWE-bench-style slice manifest. $0 dry-run by default; `--run` is the explicit spend opt-in. Requires a metaharness repo checkout (`--repo` or $METAHARNESS_REPO) — without one it reports `checkout-required` with clone instructions. Degrades gracefully when metaharness is absent.
-argument-hint: "--host <h> --model <m> --slice <manifest> [--repo <checkout>] [--run] [--alert-on-fail]"
-allowed-tools: Bash
----
-
-Surfaces `metaharness learn` — the upstream GEPA learning harness that
-evolves harness policy genomes against a scored task corpus instead of
-hand-editing prompts. Candidates are scored on held-out slices and only
-measured winners promote (the shipped cand-6 genome is the first such
-promotion: holdout gold 2/12 → 3/12, zero regressions).
-
-## When to use
-
-- A harness's policy prompt underperforms on a task family and you want a
-  measured improvement loop rather than manual prompt iteration.
-- Pricing a learning run before committing spend — the default dry-run
-  resolves the slice manifest and reports cost without any model calls.
-- After a learn run promotes a genome: pair with `harness-gepa --op render`
-  to inspect what the promoted policy actually says.
-
-## Preconditions (upstream design)
-
-The learning harness (GEPA + SWE-bench + Docker) is too heavy for the npm
-package, so `learn` needs a local clone:
-
-```bash
-git clone https://github.com/ruvnet/metaharness.git
-node scripts/learn.mjs --repo ./metaharness --host claude-code --model haiku --slice slices/lite.json
-```
-
-Without a checkout the script emits `{status: "checkout-required"}` and
-exits 0 — a precondition report, not an error (distinct from
-`degraded: true`, which means the npm package itself is absent). The
-managed-service path (gateway-side learn jobs, no checkout) is upstream's
-ADR-235 follow-up and not available yet.
-
-## Algorithm
-
-Implementation: [`scripts/learn.mjs`](../../scripts/learn.mjs).
-
-1. Validate `--repo` exists when given; export it as `$METAHARNESS_REPO`.
-2. Invoke the pinned `metaharness` binary (`metaharness@~0.3.0`, local install
-   or one-time versioned cache — never `@latest`): `metaharness learn --host <h>
-   --model <m> --slice <s> [--run]` via `_harness.mjs` (graceful degradation,
-   hard timeout).
-3. Default timeouts: 120s dry-run, 600s with `--run` — real runs on larger
-   slices need an explicit `--timeout-ms` matched to slice size × model cost.
-4. Detect the checkout-required message → structured payload, exit 0.
-5. Parse the trailing JSON report when upstream emits one; otherwise return
-   the raw report text under `rawReport`.
-
-## Cost note
-
-`--run` is the ONLY path that spends. Everything else — dry-run, checkout
-probe, degraded path — is $0. The MCP tool (`metaharness_learn`) has a 120s
-subprocess budget; run real learning cycles from a terminal via
-`ruflo metaharness learn ... --run --timeout-ms <big>`.
-
-## Exit codes
-
-- `0` — report produced (or dry-run, checkout-required, degraded)
-- `1` — `--alert-on-fail` and the learn run reported failure
-- `2` — config error (bad `--repo` path)
+---
+name: harness-learn
+description: Run a GEPA learning cycle via `metaharness learn` (upstream ADR-235, metaharness@0.3.0) — optimizes a harness genome against a SWE-bench-style slice manifest. $0 dry-run by default; `--run` is the explicit spend opt-in. Requires a metaharness repo checkout (`--repo` or $METAHARNESS_REPO) — without one it reports `checkout-required` with clone instructions. Degrades gracefully when metaharness is absent.
+argument-hint: "--host <h> --model <m> --slice <manifest> [--repo <checkout>] [--run] [--alert-on-fail]"
+allowed-tools: Bash
+---
+
+Surfaces `metaharness learn` — the upstream GEPA learning harness that
+evolves harness policy genomes against a scored task corpus instead of
+hand-editing prompts. Candidates are scored on held-out slices and only
+measured winners promote (the shipped cand-6 genome is the first such
+promotion: holdout gold 2/12 → 3/12, zero regressions).
+
+## When to use
+
+- A harness's policy prompt underperforms on a task family and you want a
+  measured improvement loop rather than manual prompt iteration.
+- Pricing a learning run before committing spend — the default dry-run
+  resolves the slice manifest and reports cost without any model calls.
+- After a learn run promotes a genome: pair with `harness-gepa --op render`
+  to inspect what the promoted policy actually says.
+
+## Preconditions (upstream design)
+
+The learning harness (GEPA + SWE-bench + Docker) is too heavy for the npm
+package, so `learn` needs a local clone:
+
+```bash
+git clone https://github.com/ruvnet/metaharness.git
+node scripts/learn.mjs --repo ./metaharness --host claude-code --model haiku --slice slices/lite.json
+```
+
+Without a checkout the script emits `{status: "checkout-required"}` and
+exits 0 — a precondition report, not an error (distinct from
+`degraded: true`, which means the npm package itself is absent). The
+managed-service path (gateway-side learn jobs, no checkout) is upstream's
+ADR-235 follow-up and not available yet.
+
+## Algorithm
+
+Implementation: [`scripts/learn.mjs`](../../scripts/learn.mjs).
+
+1. Validate `--repo` exists when given; export it as `$METAHARNESS_REPO`.
+2. Invoke the pinned `metaharness` binary (`metaharness@~0.3.0`, local install
+   or one-time versioned cache — never `@latest`): `metaharness learn --host <h>
+   --model <m> --slice <s> [--run]` via `_harness.mjs` (graceful degradation,
+   hard timeout).
+3. Default timeouts: 120s dry-run, 600s with `--run` — real runs on larger
+   slices need an explicit `--timeout-ms` matched to slice size × model cost.
+4. Detect the checkout-required message → structured payload, exit 0.
+5. Parse the trailing JSON report when upstream emits one; otherwise return
+   the raw report text under `rawReport`.
+
+## Cost note
+
+`--run` is the ONLY path that spends. Everything else — dry-run, checkout
+probe, degraded path — is $0. The MCP tool (`metaharness_learn`) has a 120s
+subprocess budget; run real learning cycles from a terminal via
+`ruflo metaharness learn ... --run --timeout-ms <big>`.
+
+## Exit codes
+
+- `0` — report produced (or dry-run, checkout-required, degraded)
+- `1` — `--alert-on-fail` and the learn run reported failure
+- `2` — config error (bad `--repo` path)

package/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md

@@ -1,49 +1,49 @@
----
-name: harness-mcp-scan
-description: Static security scan of a harness's declared MCP surface via `harness mcp-scan <path>`. Reads `.mcp/servers.json` + `.harness/claims.json`. Pure-read, no dispatch. Exits 1 on findings at or above `--fail-on` severity.
-argument-hint: "[--path .] [--fail-on low|medium|high] [--format table|json]"
-allowed-tools: Bash
----
-
-Calls `harness mcp-scan` to enumerate every declared MCP server + tool
-and flag policy / permission / dependency issues. Never executes any
-tool; pure static analysis.
-
-## Algorithm
-
-Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
-
-1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
-   local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
-   never `@latest`): `harness mcp-scan <path> --json`.
-2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
-3. `--fail-on <severity>`: exit 1 when any finding is at or above that
-   level. Default `high`.
-4. Output JSON (default) or markdown table.
-
-## Severity rank
-
-| Severity | Rank |
-|---|---:|
-| low | 1 |
-| medium | 2 |
-| high | 3 |
-
-`--fail-on high` (default) only fails on HIGH; `--fail-on medium` also
-fails on MEDIUM; `--fail-on low` fails on any finding.
-
-## CI integration
-
-```yaml
-- name: MCP static scan
-  run: node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --fail-on high
-```
-
-The exit code is the only thing CI watches; the JSON output goes to
-artifacts for human review.
-
-## Graceful degradation
-
-When `harness` binary is unavailable (no network, blocked registry),
-emits structured `{ degraded: true, reason: 'metaharness-not-available' }`
-and exits 0. Ruflo continues — ADR-150 architectural constraint.
+---
+name: harness-mcp-scan
+description: Static security scan of a harness's declared MCP surface via `harness mcp-scan <path>`. Reads `.mcp/servers.json` + `.harness/claims.json`. Pure-read, no dispatch. Exits 1 on findings at or above `--fail-on` severity.
+argument-hint: "[--path .] [--fail-on low|medium|high] [--format table|json]"
+allowed-tools: Bash
+---
+
+Calls `harness mcp-scan` to enumerate every declared MCP server + tool
+and flag policy / permission / dependency issues. Never executes any
+tool; pure static analysis.
+
+## Algorithm
+
+Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
+
+1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
+   local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
+   never `@latest`): `harness mcp-scan <path> --json`.
+2. Parse `findings[]` with `{ severity, id, server, tool, message }`.
+3. `--fail-on <severity>`: exit 1 when any finding is at or above that
+   level. Default `high`.
+4. Output JSON (default) or markdown table.
+
+## Severity rank
+
+| Severity | Rank |
+|---|---:|
+| low | 1 |
+| medium | 2 |
+| high | 3 |
+
+`--fail-on high` (default) only fails on HIGH; `--fail-on medium` also
+fails on MEDIUM; `--fail-on low` fails on any finding.
+
+## CI integration
+
+```yaml
+- name: MCP static scan
+  run: node plugins/ruflo-metaharness/scripts/mcp-scan.mjs --fail-on high
+```
+
+The exit code is the only thing CI watches; the JSON output goes to
+artifacts for human review.
+
+## Graceful degradation
+
+When `harness` binary is unavailable (no network, blocked registry),
+emits structured `{ degraded: true, reason: 'metaharness-not-available' }`
+and exits 0. Ruflo continues — ADR-150 architectural constraint.

package/plugins/ruflo-metaharness/skills/harness-mint/SKILL.md

@@ -1,72 +1,72 @@
----
-name: harness-mint
-description: Scaffold a custom AI agent harness via `metaharness new <name> --template <id> --host <id>`. Defaults to DRY-RUN (no writes) unless --confirm is passed. Refuses to write to the calling repo root or anywhere inside it. Honors ADR-150 architectural constraint + ruflo's "destructive-action confirmation" pattern.
-argument-hint: "--name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]"
-allowed-tools: Bash
----
-
-The one write-capable skill in the plugin. Every other skill is
-pure-read. This one calls `metaharness new`, which writes a new
-directory tree.
-
-## Safety (load-bearing)
-
-1. **Dry-run by default.** Without `--confirm`, the script prints what
-   it would do and exits 0 without touching disk.
-2. **Refuses project root.** If `--target` resolves to the current
-   working directory OR any path inside it, the script errors out with
-   exit 2. Target must be an absolute path OUTSIDE the calling repo
-   (default is a fresh `/tmp/ruflo-mint-<ts>-<name>/` dir).
-3. **Refuses existing target.** Won't overwrite — must scaffold into a
-   non-existent dir.
-4. **Subprocess + 60s timeout.** No library import, no in-process
-   execution. The mint stays sandboxed from ruflo's runtime.
-
-## Algorithm
-
-Implementation: [`scripts/mint.mjs`](../../scripts/mint.mjs).
-
-1. Validate `--name`, `--template`. Default `--host` to `claude-code`.
-2. Resolve `--target` (default: temp dir).
-3. Run safety checks (no project-root writes; target must not exist).
-4. Without `--confirm`: emit dry-run plan, exit 0.
-5. With `--confirm`: shell `npx metaharness new <name> --template <id>
-   --host <id> --target <abs> --yes`.
-
-## Templates
-
-`minimal`, `vertical:coding`, `vertical:devops`, `vertical:support`,
-`vertical:legal`, `vertical:research`, `vertical:trading`, `vertical:health`,
-`vertical:education`, `vertical:sales`, `vertical:business`,
-`vertical:crm`, `vertical:marketing`, `vertical:advertising`,
-`vertical:ai`, `vertical:agentics`, `vertical:ruview`, `vertical:gaming`,
-`vertical:repo-maintainer`, `vertical:exotic`.
-
-## Hosts
-
-`claude-code`, `codex`, `pi-dev`, `hermes`, `openclaw`, `rvm`,
-`copilot`, `opencode`, `github-actions`.
-
-## Example dry-run
-
-```
-$ node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
-# harness-mint (dry-run)
-
-- action: metaharness new
-- name: my-harness
-- template: vertical:coding
-- host: claude-code
-- target: /tmp/ruflo-mint-1718560000-my-harness
-- confirm: false
-- willWrite: false
-
-Re-run with `--confirm` to actually scaffold.
-```
-
-## Why dry-run by default
-
-Ruflo's behavioral rules say "executing actions with care" — destructive
-or repo-touching actions need confirmation. The dry-run output makes the
-WHAT visible before the WHEN. A human sees `target`, decides, then
-adds `--confirm` if happy.
+---
+name: harness-mint
+description: Scaffold a custom AI agent harness via `metaharness new <name> --template <id> --host <id>`. Defaults to DRY-RUN (no writes) unless --confirm is passed. Refuses to write to the calling repo root or anywhere inside it. Honors ADR-150 architectural constraint + ruflo's "destructive-action confirmation" pattern.
+argument-hint: "--name <id> --template <vertical:coding|minimal|…> [--host claude-code|codex|…] [--target /abs/path] [--confirm] [--format table|json]"
+allowed-tools: Bash
+---
+
+The one write-capable skill in the plugin. Every other skill is
+pure-read. This one calls `metaharness new`, which writes a new
+directory tree.
+
+## Safety (load-bearing)
+
+1. **Dry-run by default.** Without `--confirm`, the script prints what
+   it would do and exits 0 without touching disk.
+2. **Refuses project root.** If `--target` resolves to the current
+   working directory OR any path inside it, the script errors out with
+   exit 2. Target must be an absolute path OUTSIDE the calling repo
+   (default is a fresh `/tmp/ruflo-mint-<ts>-<name>/` dir).
+3. **Refuses existing target.** Won't overwrite — must scaffold into a
+   non-existent dir.
+4. **Subprocess + 60s timeout.** No library import, no in-process
+   execution. The mint stays sandboxed from ruflo's runtime.
+
+## Algorithm
+
+Implementation: [`scripts/mint.mjs`](../../scripts/mint.mjs).
+
+1. Validate `--name`, `--template`. Default `--host` to `claude-code`.
+2. Resolve `--target` (default: temp dir).
+3. Run safety checks (no project-root writes; target must not exist).
+4. Without `--confirm`: emit dry-run plan, exit 0.
+5. With `--confirm`: shell `npx metaharness new <name> --template <id>
+   --host <id> --target <abs> --yes`.
+
+## Templates
+
+`minimal`, `vertical:coding`, `vertical:devops`, `vertical:support`,
+`vertical:legal`, `vertical:research`, `vertical:trading`, `vertical:health`,
+`vertical:education`, `vertical:sales`, `vertical:business`,
+`vertical:crm`, `vertical:marketing`, `vertical:advertising`,
+`vertical:ai`, `vertical:agentics`, `vertical:ruview`, `vertical:gaming`,
+`vertical:repo-maintainer`, `vertical:exotic`.
+
+## Hosts
+
+`claude-code`, `codex`, `pi-dev`, `hermes`, `openclaw`, `rvm`,
+`copilot`, `opencode`, `github-actions`.
+
+## Example dry-run
+
+```
+$ node scripts/mint.mjs --name my-harness --template vertical:coding --host claude-code
+# harness-mint (dry-run)
+
+- action: metaharness new
+- name: my-harness
+- template: vertical:coding
+- host: claude-code
+- target: /tmp/ruflo-mint-1718560000-my-harness
+- confirm: false
+- willWrite: false
+
+Re-run with `--confirm` to actually scaffold.
+```
+
+## Why dry-run by default
+
+Ruflo's behavioral rules say "executing actions with care" — destructive
+or repo-touching actions need confirmation. The dry-run output makes the
+WHAT visible before the WHEN. A human sees `target`, decides, then
+adds `--confirm` if happy.