@agentworkforce/cli 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -17,6 +17,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Persona source config supports `defaultCreateTarget` for the implicit create target.
 - `--version`/`-v` now prints the CLI package version.
 
+## [0.13.0] - 2026-05-08
+
+### Released
+
+- v0.13.0
+
+## [0.12.0] - 2026-05-08
+
+### Released
+
+- v0.12.0
+
 ## [0.11.0] - 2026-05-08
 
 ### Released

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { type Harness, type PersonaMount, type PersonaSelection, type SidecarMdMode } from '@agentworkforce/workload-router';
+import { type PickCandidate } from './persona-picker.js';
 export declare const CLI_VERSION: string;
 export declare const CREATE_SELECTOR = "persona-maker@best";
 /**
@@ -124,10 +125,12 @@ export declare function buildSidecarBody(sidecar: ResolvedSidecar, realCwdDir: s
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
  *
- * - Claude / opencode: mount engages by default. Hides CLAUDE.md / .claude
- *   / .mcp.json (claude) and routes `npx prpm install` / `npx skills add`
- *   writes (both) into the sandbox. Disengage with `--install-in-repo`.
- * - Codex: no sandbox mount support, always runs against the real cwd.
+ * All three harnesses (claude, codex, opencode) default to the mount.
+ * The mount hides CLAUDE.md / .claude / .mcp.json (claude) or the
+ * skill-install patterns + AGENTS.md (codex / opencode) so persona-supplied
+ * sidecars and any per-session writes stay sandboxed and don't leak into
+ * the user's real repo. `--install-in-repo` is the single opt-out that
+ * disengages the mount across all harnesses.
  *
  * Pure — no side effects, trivially testable.
  */
@@ -140,6 +143,25 @@ export interface PersonaInstallArgs {
     overwrite: boolean;
 }
 export declare function parseInstallArgs(args: readonly string[]): PersonaInstallArgs;
+/**
+ * Enumerate persona candidates for the picker. Local overrides win over the
+ * built-in catalog when ids collide; the picker only needs the projection
+ * fields ({@link PickCandidate}), not full specs.
+ */
+export declare function buildPickCandidates(): PickCandidate[];
+/**
+ * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
+ * empty input or non-y answer. Used by `pick` when the picker reports
+ * no-match in an interactive session.
+ *
+ * Test seam: callers can inject `read` so the prompt path is exercisable
+ * without a real TTY.
+ */
+export declare function promptYesNoSync(question: string, opts?: {
+    isTTY?: boolean;
+    write?: (chunk: string) => void;
+    read?: () => string | undefined;
+}): boolean;
 export declare function main(): Promise<void>;
 export interface AgentFlags {
     installInRepo: boolean;

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAQL,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAIrB,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AAwJzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAmDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AAyJD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,gFAUzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,2JAiBjC,CAAC;AAEX,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GAAG,sBAAsB,CAqBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,GAC1B;IAAE,OAAO,CAAC,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqDjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,MAAM,GACjB,MAAM,CAkBR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAipBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAqmBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CA4BA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CAgEA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -12,6 +12,7 @@ import ora from 'ora';
 import { startLaunchMetadataRecording } from './launch-metadata.js';
 import { buildPersonaSourceDirectories, defaultCwdPersonaDir, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
 import { installPersonas } from './persona-install.js';
+import { pickPersona } from './persona-picker.js';
 const USAGE = `Usage: agentworkforce <command> [args...]
 
 Commands:
@@ -92,6 +93,13 @@ Commands:
                       1-based configurable position.
   harness check       Probe which harnesses (claude, codex, opencode) are
                       installed and runnable on this machine.
+  pick "<task>"       Pick the best-fit persona for a free-text task description
+                      using a cheap LLM call (Claude Haiku via the local
+                      \`claude\` CLI). Prints the matched persona id to stdout
+                      on success. On low confidence, prompts (TTY) to launch
+                      persona-maker with the task as input, or exits non-zero
+                      (non-TTY) with a hint.
+                      Exit codes: 0 match, 2 no match, 3 picker unavailable.
 
 Options:
   -h, --help          Show this help text.
@@ -116,6 +124,8 @@ Examples:
   agentworkforce sources list
   agentworkforce sources add ../my-personas --position 1
   agentworkforce harness check
+  agentworkforce pick "review this PR for security issues"
+  agentworkforce agent "$(agentworkforce pick "fix the flaky test in foo.test.ts")"
 `;
 function die(msg, withUsage = true) {
     process.stderr.write(`${msg}\n`);
@@ -526,7 +536,7 @@ export function configureGitForMount(mountDir, patterns) {
  */
 export function loadSidecarForSelection(selection) {
     const harness = selection.runtime.harness;
-    if (harness !== 'claude' && harness !== 'opencode')
+    if (harness !== 'claude' && harness !== 'opencode' && harness !== 'codex')
         return {};
     if (harness === 'claude') {
         if (selection.claudeMdContent) {
@@ -555,6 +565,10 @@ export function loadSidecarForSelection(selection) {
         }
         return {};
     }
+    // opencode and codex both read AGENTS.md from cwd. For codex, the mount
+    // only engages when a sidecar is declared (see decideCleanMode); without
+    // a mount the materialization warning fires. The resolution rule is
+    // identical for both harnesses here.
     if (selection.agentsMdContent) {
         return {
             sidecar: {
@@ -610,15 +624,17 @@ export function buildSidecarBody(sidecar, realCwdDir) {
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
  *
- * - Claude / opencode: mount engages by default. Hides CLAUDE.md / .claude
- *   / .mcp.json (claude) and routes `npx prpm install` / `npx skills add`
- *   writes (both) into the sandbox. Disengage with `--install-in-repo`.
- * - Codex: no sandbox mount support, always runs against the real cwd.
+ * All three harnesses (claude, codex, opencode) default to the mount.
+ * The mount hides CLAUDE.md / .claude / .mcp.json (claude) or the
+ * skill-install patterns + AGENTS.md (codex / opencode) so persona-supplied
+ * sidecars and any per-session writes stay sandboxed and don't leak into
+ * the user's real repo. `--install-in-repo` is the single opt-out that
+ * disengages the mount across all harnesses.
  *
  * Pure — no side effects, trivially testable.
  */
 export function decideCleanMode(harness, installInRepo = false) {
-    if (harness === 'claude' || harness === 'opencode') {
+    if (harness === 'claude' || harness === 'opencode' || harness === 'codex') {
         return { useClean: !installInRepo };
     }
     return { useClean: false };
@@ -626,12 +642,25 @@ export function decideCleanMode(harness, installInRepo = false) {
 async function runInteractive(selection, options) {
     const inputResolution = resolvePersonaInputs(selection.inputs, selection.inputValues, process.env);
     const renderedSystemPrompt = renderPersonaInputs(selection.runtime.systemPrompt, inputResolution.values);
+    // Render input placeholders ($TARGET_DIR, ${CREATE_MODE}, …) inside the
+    // sidecar Content fields too. Personas that move heavy authoring guidance
+    // out of the systemPrompt and into AGENTS.md / CLAUDE.md still want
+    // their declared inputs interpolated; without this the materialized
+    // sidecar would carry literal `$TARGET_DIR` strings.
+    const renderedClaudeContent = selection.claudeMdContent !== undefined
+        ? renderPersonaInputs(selection.claudeMdContent, inputResolution.values)
+        : undefined;
+    const renderedAgentsContent = selection.agentsMdContent !== undefined
+        ? renderPersonaInputs(selection.agentsMdContent, inputResolution.values)
+        : undefined;
     const effectiveSelection = {
         ...selection,
         runtime: {
             ...selection.runtime,
             systemPrompt: renderedSystemPrompt
-        }
+        },
+        ...(renderedClaudeContent !== undefined ? { claudeMdContent: renderedClaudeContent } : {}),
+        ...(renderedAgentsContent !== undefined ? { agentsMdContent: renderedAgentsContent } : {})
     };
     const { runtime, personaId, tier } = effectiveSelection;
     // `installRoot` (out-of-repo skill staging via `--plugin-dir`) is currently
@@ -642,19 +671,17 @@ async function runInteractive(selection, options) {
     // across the board.
     const useClean = decideCleanMode(runtime.harness, options.installInRepo === true).useClean;
     // Per-persona CLAUDE.md / AGENTS.md: load the author content if any. The
-    // file is materialized into the mount inside onBeforeLaunch (claude/
-    // opencode default). Without a mount (codex, --install-in-repo) we
-    // skip-and-warn — writing into the real cwd would pollute the user's
-    // repo and is explicitly out of scope.
+    // file is materialized into the mount inside onBeforeLaunch. Without a
+    // mount (--install-in-repo) we skip-and-warn — writing into the real cwd
+    // would pollute the user's repo and is explicitly out of scope.
     const sidecarLookup = loadSidecarForSelection(effectiveSelection);
     if (sidecarLookup.warning) {
         process.stderr.write(`warning: ${sidecarLookup.warning}\n`);
     }
     const resolvedSidecar = useClean ? sidecarLookup.sidecar : undefined;
     if (sidecarLookup.sidecar && !useClean) {
-        process.stderr.write(`warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available (` +
-            `${runtime.harness === 'codex' ? 'codex harness has no mount' : '--install-in-repo disengages the mount'})` +
-            `; skipping sidecar materialization to avoid writing into your repo.\n`);
+        process.stderr.write(`warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available ` +
+            `(--install-in-repo disengages the mount); skipping sidecar materialization to avoid writing into your repo.\n`);
     }
     // A session dir is needed whenever we either (a) stage skills out-of-repo
     // via claude's installRoot, or (b) open a mount. Both engage for claude/
@@ -1779,6 +1806,129 @@ async function runAgentSelector(selector, flags, inputValues) {
     });
     process.exit(code);
 }
+/**
+ * Enumerate persona candidates for the picker. Local overrides win over the
+ * built-in catalog when ids collide; the picker only needs the projection
+ * fields ({@link PickCandidate}), not full specs.
+ */
+export function buildPickCandidates() {
+    const byId = new Map();
+    for (const spec of Object.values(personaCatalog)) {
+        byId.set(spec.id, {
+            id: spec.id,
+            intent: spec.intent,
+            tags: [...spec.tags],
+            description: spec.description
+        });
+    }
+    for (const [id, spec] of local.byId.entries()) {
+        byId.set(id, {
+            id,
+            intent: spec.intent,
+            tags: [...spec.tags],
+            description: spec.description
+        });
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Synchronous y/n prompt over /dev/tty-equivalent stdin. Default is "no" on
+ * empty input or non-y answer. Used by `pick` when the picker reports
+ * no-match in an interactive session.
+ *
+ * Test seam: callers can inject `read` so the prompt path is exercisable
+ * without a real TTY.
+ */
+export function promptYesNoSync(question, opts = {}) {
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY && process.stdin.isTTY);
+    if (!isTTY)
+        return false;
+    const write = opts.write ?? ((chunk) => {
+        process.stderr.write(chunk);
+    });
+    write(question);
+    const answer = opts.read ? opts.read() : readLineFromStdinSync();
+    if (!answer)
+        return false;
+    const normalized = answer.trim().toLowerCase();
+    return normalized === 'y' || normalized === 'yes';
+}
+function readLineFromStdinSync() {
+    const buf = Buffer.alloc(256);
+    let line = '';
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            return line || undefined;
+        }
+        if (n <= 0)
+            return line || undefined;
+        const chunk = buf.subarray(0, n).toString('utf8');
+        const newlineIdx = chunk.indexOf('\n');
+        if (newlineIdx === -1) {
+            line += chunk;
+            continue;
+        }
+        line += chunk.slice(0, newlineIdx);
+        return line;
+    }
+}
+async function runPick(args) {
+    const positional = [];
+    for (const arg of args) {
+        if (arg === '-h' || arg === '--help') {
+            process.stdout.write('Usage: agentworkforce pick "<task description>"\n' +
+                '  Prints the best-fit persona id to stdout. On low confidence, prompts to\n' +
+                '  open persona-maker (TTY) or exits 2 (non-TTY). Exits 3 if `claude` is\n' +
+                '  not installed.\n');
+            process.exit(0);
+        }
+        positional.push(arg);
+    }
+    if (positional.length === 0) {
+        die('pick: missing task description. Usage: agentworkforce pick "<task>"');
+    }
+    if (positional.length > 1) {
+        die(`pick: expected a single quoted task description, got ${positional.length} arguments. ` +
+            `Did you forget to quote the task? Try: agentworkforce pick "${positional.join(' ')}"`);
+    }
+    const task = positional[0].trim();
+    if (!task) {
+        die('pick: task description is empty.');
+    }
+    const candidates = buildPickCandidates();
+    const result = pickPersona(task, candidates);
+    if (result.kind === 'match') {
+        process.stderr.write(`• picked ${result.personaId} (${result.confidence}): ${result.reason}\n`);
+        process.stdout.write(`${result.personaId}\n`);
+        process.exit(0);
+    }
+    if (result.kind === 'picker-unavailable') {
+        process.stderr.write(`pick: ${result.message}\n`);
+        process.exit(3);
+    }
+    // no-match
+    process.stderr.write(`pick: no close persona match — ${result.reason}\n`);
+    const wantsCreate = promptYesNoSync('Open persona-maker to scaffold a new persona for this task? [y/N] ');
+    if (!wantsCreate) {
+        process.stderr.write('Try: agentworkforce list   # to browse existing personas\n' +
+            '     agentworkforce create  # to author a new persona\n');
+        process.exit(2);
+    }
+    const target = resolveCreateTarget(undefined);
+    ensureCreateTargetDir(target);
+    const inputValues = {
+        ...buildCreateInputValues(target),
+        TASK_DESCRIPTION: task
+    };
+    await runAgentSelector(CREATE_SELECTOR, { installInRepo: false, noLaunchMetadata: false }, inputValues);
+    // runAgentSelector terminates via process.exit; this satisfies TS's
+    // reachable-end-point check for the `Promise<never>` return type.
+    process.exit(0);
+}
 export async function main() {
     const argv = process.argv.slice(2);
     const [subcommand, ...rest] = argv;
@@ -1819,6 +1969,9 @@ export async function main() {
         const { flags, selector, inputValues } = parseCreateArgs(rest);
         await runAgentSelector(selector, flags, inputValues);
     }
+    if (subcommand === 'pick') {
+        await runPick(rest);
+    }
     if (subcommand !== 'agent') {
         die(`Unknown subcommand "${subcommand}".`);
     }