@agentworkforce/cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to `@agentworkforce/cli` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]

package/README.md

@@ -6,11 +6,17 @@ built-in one from `/personas/`, or a user-local one that extends a built-in.
 
 ```
 agent-workforce agent <persona>[@<tier>] [task...]
+agent-workforce list [flags]
+agent-workforce harness check
 ```
 
-- No `task` → drops you into an interactive session with the harness.
-- `task...` given → runs one-shot (via `usePersona().sendMessage()`) and streams
-  output to stdout/stderr.
+- `agent` — no `task` drops you into an interactive session with the harness;
+  a `task...` argument runs one-shot (via `usePersona().sendMessage()`) and
+  streams output to stdout/stderr.
+- `list` — print the persona catalog as a table (or JSON). See
+  [`## List`](#list) below for every flag.
+- `harness check` — probe which harnesses (`claude`, `codex`, `opencode`)
+  are installed. See [`## Harness check`](#harness-check) below.
 
 ## Install
 
@@ -53,6 +59,67 @@ agent-workforce agent posthog@best
 agent-workforce agent my-posthog@best
 ```
 
+## List
+
+```
+agent-workforce list [flags]
+```
+
+Prints the merged persona catalog — everything the `agent` subcommand would
+accept as a selector — including cascade source (`library`, `home`, `pwd`),
+harness, model, description, and tier ("rating"). One row per persona-tier
+combination; by default only the **recommended tier per intent** is shown
+(as declared in
+`packages/workload-router/routing-profiles/default.json`).
+
+### Flags
+
+| Flag | Default | Effect |
+| --- | --- | --- |
+| `--all` | off | Show every tier of every persona. Alias: `--no-recommended`. |
+| `--recommended` | on | Only show the recommended tier per intent. Implicit default; mostly useful for undoing `--all` earlier in a wrapper script. |
+| `--filter-rating <tier>` | — | Restrict to a single tier (`best` \| `best-value` \| `minimum`). **Implicitly turns off the recommended-only default**, so filtering by `best` shows every persona's `best` row even when that's not the recommended tier. |
+| `--filter-harness <harness>` | — | Restrict to a single harness (`claude` \| `codex` \| `opencode`). Composable with `--filter-rating` and `--all`. |
+| `--no-display-description` | off | Hide the `DESCRIPTION` column. `--display-description` re-enables it. |
+| `--json` | off | Emit `{ "personas": [...] }` with one object per row. Same field set as the table, useful for scripting. |
+| `-h`, `--help` | — | Print a one-line usage string and exit. |
+
+Invalid values for `--filter-rating` / `--filter-harness` fail fast and list
+the allowed values.
+
+### Examples
+
+```sh
+# Default: one row per persona, recommended tier only
+agent-workforce list
+
+# See every tier
+agent-workforce list --all
+
+# Only the top tier across the catalog — independent of recommendations
+agent-workforce list --filter-rating best
+
+# All claude-harness personas (any tier)
+agent-workforce list --all --filter-harness claude
+
+# Compact table for a narrow terminal
+agent-workforce list --no-display-description
+
+# Machine-readable
+agent-workforce list --json --filter-harness claude
+```
+
+## Harness check
+
+```
+agent-workforce harness check
+```
+
+Probes your PATH for each supported harness binary (`claude`, `codex`,
+`opencode`) and prints a table with status (`ok` / `missing`), resolved
+version, and the resolved path (or the error, for missing ones). Exit
+code is always `0` — this command is diagnostic, not a gate.
+
 ## Personas
 
 A persona is a JSON object describing *what harness runs, which model, with
@@ -313,22 +380,34 @@ persona session, add it to the persona's `mcpServers` block.
 ### Interactive
 
 ```sh
-agent-workforce agent <persona>[@<tier>]
+agent-workforce agent [--install-in-repo] [--clean] <persona>[@<tier>]
 ```
 
+`--install-in-repo` and `--clean` are mutually exclusive — see
+[**Clean mode**](#clean-mode) below.
+
 1. Resolves the persona, walks the cascade, resolves `$VAR` refs.
-2. Runs skill install (`prpm install …`) if the persona declares any skills.
-3. Execs the harness binary with stdio inherited:
+2. **Stages skills outside the repo by default** (claude interactive only —
+   see **Skill staging** below). For codex / opencode, or when
+   `--install-in-repo` is passed, falls back to the legacy repo-relative
+   install path (`.claude/skills/`, `.agents/skills/`, `.skills/`).
+3. Runs skill install (`prpm install …`) if the persona declares any skills,
+   using the computed target (stage dir or repo).
+4. Execs the harness binary with stdio inherited:
    - `claude`: `claude --model <model> --append-system-prompt <prompt>
-     --mcp-config '<json>' --strict-mcp-config`. Both flags are always passed
-     so the session only sees the persona's declared MCP servers — see
-     **MCP isolation** above.
+     --mcp-config '<json>' --strict-mcp-config [--plugin-dir <stage>]`. The
+     `--plugin-dir` flag is appended when the session uses out-of-repo
+     staging so Claude Code loads exactly the staged skills — and nothing
+     the repo happens to carry. Both MCP flags are always passed so the
+     session only sees the persona's declared MCP servers (see **MCP
+     isolation** above).
    - `codex`: `codex -m <model>` with the system prompt as the initial
      positional `[PROMPT]`. (codex has no `--system-prompt` flag today.)
    - `opencode`: `opencode --model <model>` with the system prompt as the
      initial argument.
-4. Runs the skill cleanup command on exit, regardless of exit status.
-5. Propagates the harness's exit code.
+5. Runs the skill cleanup command on exit, regardless of exit status. In
+   stage-dir mode this is a single `rm -rf <stage-dir>`.
+6. Propagates the harness's exit code.
 
 Signals (SIGINT, SIGTERM) are forwarded to the child.
 
@@ -347,6 +426,154 @@ Env from the persona is passed through via `ExecuteOptions.env`. `mcpServers`
 is currently **ignored with a warning** in one-shot mode — the SDK workflow
 path doesn't thread MCP config yet.
 
+One-shot mode still installs into the repo regardless of `--install-in-repo`;
+out-of-repo staging only applies to the interactive path today because the
+agent-relay workflow SDK doesn't yet thread `--plugin-dir` into the claude
+agent adapter. `--install-in-repo` passed to a one-shot run prints a `note:`
+and is a no-op.
+
+## Skill staging
+
+By default, interactive `claude` sessions stage skills under the user's home
+directory instead of the current repo. Nothing gets written to `.claude/` in
+the working tree, and the session only sees the skills the persona declares
+— never whatever skills the repo happens to carry on disk.
+
+**Layout:**
+
+```
+~/.agent-workforce/
+└── sessions/<personaId>-<timestamp>-<rand>/
+    └── claude/
+        └── plugin/                                ← passed as --plugin-dir
+            ├── .claude-plugin/plugin.json         ← generated scaffold
+            ├── skills → .claude/skills            ← relative symlink
+            └── .claude/skills/<name>/SKILL.md     ← prpm install output
+```
+
+- **Stage dir** — `~/.agent-workforce/sessions/<id>/claude/plugin/`.
+  `<id>` is `<personaId>-<base36-timestamp>-<hex-random>` so parallel
+  sessions never collide.
+- **Plugin wrapper** — the CLI writes a minimal `.claude-plugin/plugin.json`
+  (`{"name":"agent-workforce-session","version":"0.0.0",…}`) and a relative
+  symlink `skills → .claude/skills` so Claude Code's plugin layout
+  (`skills/<name>/SKILL.md`) resolves to prpm's actual output
+  (`.claude/skills/<name>/SKILL.md`) without moving any files.
+- **prpm install** — still runs `npx -y prpm install <ref> --as claude`,
+  but inside `cd <stage-dir>` so the harness-conventional `.claude/skills/`
+  lands in the stage dir, not the repo.
+- **Cleanup** — on exit, two cleanup scopes run. The workload-router removes
+  `<stage-dir>` (e.g. `.../sessions/<id>/claude/plugin/`) via its generated
+  `rm -rf` command. The CLI additionally removes the enclosing session root
+  (`.../sessions/<id>/`) so the mount dir and any empty parents don't
+  accumulate under `~/.agent-workforce/sessions/`. The provider lockfile
+  (`prpm.lock`) is inside the stage dir and goes with it — no repeat-run
+  resolution cache today. Restart cost is one prpm install per session.
+
+**Opt-out — `--install-in-repo`:**
+
+Pass `--install-in-repo` to fall back to the legacy behavior (skills land in
+the repo's `.claude/skills/` directory, cleaned on exit):
+
+```sh
+agent-workforce agent --install-in-repo code-reviewer@best
+```
+
+Useful when you want to inspect the installed skills on disk, or when the
+stage dir conflicts with something else (network filesystem, read-only
+`$HOME`, etc.).
+
+**Caveats for V1:**
+
+- **Claude harness only.** codex and opencode continue to install into their
+  conventional repo-relative directories. The SDK throws if `installRoot` is
+  passed with a non-claude harness.
+- **No cache layer yet.** Every interactive session runs a fresh prpm install
+  into a new stage dir. A `~/.agent-workforce/cache/` content-addressed cache
+  is planned but not wired up.
+- **One-shot path unchanged.** See the paragraph under "One-shot" above.
+
+## Clean mode
+
+`--clean` launches an interactive claude session inside a
+[`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
+symlink mount that hides the repo's Claude Code configuration from the
+session — so the model sees persona context + user-level context, and
+nothing the repo itself declares.
+
+```sh
+agent-workforce agent --clean <persona>[@<tier>]
+```
+
+**What's hidden (gitignore semantics, at any depth):**
+
+| Pattern | Rationale |
+| --- | --- |
+| `CLAUDE.md` | Repo-level project memory |
+| `CLAUDE.local.md` | Developer-local project memory |
+| `.claude` | Repo Claude Code config dir (settings, agents, skills, commands) |
+| `.mcp.json` | Repo-declared MCP servers |
+
+**What's preserved:**
+
+- **User-level context** under `~/.claude/` — `CLAUDE.md`, skills, etc.
+  still load. `--clean` scrubs the *project*, not the user. To exclude
+  user-level context too, launch under a scratch `$HOME`.
+- **Persona skills.** The `--plugin-dir` passed to claude resolves to an
+  absolute path *outside* the mount, so staged skills from
+  `~/.agent-workforce/sessions/<id>/claude/plugin/` load normally.
+- **Keychain auth.** `--clean` does NOT pass `--bare`; it only hides
+  files via the mount. Claude Code's macOS keychain login stays active.
+- **Persona `mcpServers`.** Still passed via `--mcp-config` — unaffected
+  by the mount. The repo's `.mcp.json` is hidden regardless.
+
+### Session layout
+
+Both the skill install root and the clean mount live under a single
+session directory. The session id (`<personaId>-<base36-timestamp>-<hex>`)
+is generated once and both paths are derived from it:
+
+```
+~/.agent-workforce/
+└── sessions/<personaId>-<timestamp>-<rand>/
+    ├── claude/
+    │   └── plugin/                                ← passed as --plugin-dir
+    │       ├── .claude-plugin/plugin.json
+    │       ├── skills → .claude/skills
+    │       └── .claude/skills/<name>/SKILL.md
+    └── mount/                                     ← --clean: claude's cwd
+        └── <mirrored project tree, minus the hidden patterns>
+```
+
+`@relayfile/local-mount` handles mount creation, process spawn,
+SIGINT/SIGTERM forwarding, write syncback, and cleanup on exit. The
+agent-workforce CLI just wires the paths and passes the persona's argv.
+
+### Interactions with other flags
+
+- **`--clean` + `--install-in-repo` is rejected** — they ask for
+  incompatible things. `--install-in-repo` stages skills into the real
+  repo's `.claude/skills/`; `--clean` hides the real repo. Pick one.
+- **`--clean` on codex/opencode is a warning no-op.** Only the claude
+  harness gets the mount (it's the only one whose native surface includes
+  the hidden patterns).
+- **`--clean` on a one-shot run is a warning no-op.** The agent-relay
+  workflow SDK doesn't thread mount integration today; matches how
+  `--install-in-repo` behaves in one-shot mode.
+
+### Example
+
+```sh
+# Interactive PostHog session with the repo's CLAUDE.md, .claude/, and
+# .mcp.json hidden — session sees the persona's staged skills plus your
+# user-level ~/.claude/CLAUDE.md, nothing else from this repo.
+export POSTHOG_API_KEY=phx_…
+agent-workforce agent --clean posthog@best
+```
+
+On exit: mount is synced back to the real repo, then torn down; skill
+stage dir is cleaned up by the existing `rm -rf` cleanup command.
+
 ## Selecting a harness per tier
 
 A persona's three tiers can use different harnesses. The built-in

package/dist/cli.d.ts

@@ -1,3 +1,26 @@
 #!/usr/bin/env node
-export {};
+import { type Harness } from '@agentworkforce/workload-router';
+/** Patterns hidden from an interactive claude session when `--clean` is set.
+ * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
+ * match at any depth in the project tree (e.g. `.claude` hides both
+ * `./.claude/` and `./packages/foo/.claude/`). */
+export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.local.md", ".claude", ".mcp.json"];
+/**
+ * Decide whether `--clean` should engage for this run. Returns a warning
+ * string when the flag was requested but cannot apply (e.g. non-claude
+ * harness); callers emit the warning to stderr and proceed with
+ * `useClean: false`. Pure — no side effects, trivially testable.
+ */
+export declare function decideCleanMode(harness: Harness, clean: boolean): {
+    useClean: boolean;
+    warning?: string;
+};
+export interface AgentFlags {
+    installInRepo: boolean;
+    clean: boolean;
+}
+export declare function parseAgentArgs(args: readonly string[]): {
+    flags: AgentFlags;
+    positional: string[];
+};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAOA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA8OzC;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,GACb;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CASzC;AAidD,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAmCA"}