@iowarp/clio-coder 0.3.0 → 0.3.2

package/skills/workflow/grill-me/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: grill-me
+description: Use when the user wants a plan, design, or idea stress-tested through a phased one-question-at-a-time interview before any code is written, or when intent is too ambiguous to plan from. Scans available context first, reviews known facts, fills missing decisions, respects stop signals, and ends with a compact decision log. Triggers on "grill me", "interview me", "stress-test this plan", "poke holes in this".
+version: 0.3.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/workflow/grill-me
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: large
+---
+
+# Grill Me
+
+Run a rigorous, repo-aware interview that turns a vague plan into explicit
+decisions. The point is not to interrogate for sport; it is to surface hidden
+branches before anyone writes code.
+
+## Operating Contract
+
+- Use `ask_user` for the interview whenever it is active.
+- For every interview round, call `ask_user` with `mode: "single_question"` and
+  exactly one question.
+- On the first ask for a normal grill-me run, set `max_rounds` to a bounded
+  value, usually `12` and at most `16` unless the user explicitly asked for a
+  very deep interview.
+- Put your recommended answer first when options are natural. Include 2-3 real
+  alternatives with short tradeoff descriptions.
+- The user answers in natural language. You translate answers into compact
+  decision keys and rationale when you call `ask_user` with `action: "complete"`.
+- If `ask_user` is unavailable, ask in plain text, still one question at a
+  time, and keep an internal decision log.
+
+## Phase Map
+
+Walk phases in order unless the user names a narrower target. Do not skip the
+scan. A phase can be "review" when context already contains a plausible answer
+or "fill" when the decision is genuinely missing.
+
+| Phase | Scope | Default mode |
+|---|---|---|
+| 0 | Scan available context: user prompt, named files, repo structure, git state, existing plans/specs | No questions unless the subject is missing |
+| 1 | Frame: user, problem, outcome, non-goals, success criteria | Fill or review |
+| 2 | Current state: existing code, constraints, conventions, integration points, prior attempts | Review |
+| 3 | Shape: data model, API/UX surface, ownership boundaries, naming, compatibility | Fill |
+| 4 | Risk: failure modes, migrations, rollout, test strategy, observability, reversibility | Fill |
+| 5 | Delivery: first slice, done-when checks, deferrals, handoff target (`prd`, `cut-it`, or direct implementation) | Review then complete |
+
+## Workflow
+
+### Step 1 - Scan
+
+Read what the user already gave you. If the task references files, plans, code,
+tests, or project conventions, inspect them before asking. Prefer
+`context(scope="workspace")`, `grep`, `read`, and codewiki tools over guessing.
+
+Privately build a phase map:
+
+- known facts
+- assumptions worth challenging
+- missing decisions
+- dependencies between decisions
+- likely deferrals and why they might be safe
+
+Never spend the user's attention on facts that the repo answers. If you found
+the answer in code, summarize it briefly and ask only whether it should remain
+true.
+
+### Step 2 - Choose Review Or Fill
+
+For each phase:
+
+- **Review mode**: context already has an answer. Present the finding in one or
+  two sentences, then ask a targeted question such as "Is this still accurate?"
+  or "Should we keep this constraint?"
+- **Fill mode**: context is sparse or ambiguous. Ask the highest-leverage
+  missing decision first.
+
+Always resolve root decisions before leaves, in the Question Priority order
+below.
+
+### Step 3 - Ask One Question
+
+Each `ask_user` round contains one question only:
+
+- one stable `header`
+- one concrete question
+- recommended option first when options fit
+- no multi-part wording hidden inside the question
+
+Bad: "Who is this for, what should v1 include, and how should we test it?"
+
+Good: "Which user should v1 optimize for first?"
+
+If an answer is vague, ask a follow-up on the same branch. Do not jump to a new
+branch while the current one is still unresolved.
+
+### Step 4 - Respect Stop Signals
+
+Stop immediately when the user says "stop", "enough", "later", "done", "next
+time", or cancels the modal. Do not ask another question to confirm stopping.
+
+If you have enough decisions to be useful, call:
+
+```json
+{
+  "action": "complete",
+  "summary": "Short interview closeout.",
+  "decisions": [
+    {
+      "key": "primary_outcome",
+      "value": "Smallest useful slice",
+      "rationale": "The user prioritized fast validation over broad architecture.",
+      "confidence": "high",
+      "source_question": "What should this plan optimize for first?"
+    }
+  ]
+}
+```
+
+Then provide the decision log. If the stop happened before enough context,
+state the partial decisions and the next unresolved root question.
+
+### Step 5 - Complete
+
+Before final prose, call `ask_user` with `action: "complete"` and a compact
+`decisions` array. Then write the final decision log:
+
+```markdown
+## Decision Log - <topic>
+1. <decision> - chosen over <alternative> because <reason>
+2. ...
+
+Deferred:
+- <item> - safe because <reason>
+
+Open risks:
+- <risk or unresolved branch>
+
+Recommended next step:
+- <prd | cut-it | direct implementation> - <why>
+```
+
+## Question Priority
+
+Use this ordering when several questions are possible:
+
+1. User and problem being solved.
+2. Primary success measure.
+3. Explicit non-goals.
+4. Existing constraints from repo or environment.
+5. Data/API/UX boundary.
+6. Failure modes and recovery.
+7. Tests and done-when checks.
+8. First implementation slice.
+9. Naming and polish.
+
+## Decision Rules
+
+- If the user says "whatever you think", record your recommendation as the
+  decision and say so.
+- If two choices are both viable, choose the one that reduces irreversible
+  work unless the user explicitly values speed or breadth more.
+- If a decision is safe to defer, record why and what later signal will force
+  it.
+- If the plan is too vague to slice or implement, say that clearly and continue
+  interviewing instead of fabricating certainty.
+
+## Red Flags
+
+- Asking multiple questions in one `ask_user` round.
+- Asking about facts discoverable from the repo.
+- Letting `ask_user` hit the round limit without completing the interview.
+- Ending with a summary paragraph instead of the decision log.
+- Treating cancellation as permission to keep asking.

package/skills/workflow/grill-me/evals.md

@@ -0,0 +1,78 @@
+# Evals - grill-me
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - vague feature request
+
+Setup: repo with an existing config domain. Prompt: "grill me on adding plugin
+support."
+
+Expected:
+
+- Scans the existing config/extension code before asking anything the repo can
+  answer.
+- Starts with a root decision such as outcome, target user, or scope boundary.
+- Uses `ask_user` with `mode: "single_question"` and exactly one question in
+  the round.
+- Puts its recommended answer first when options are supplied.
+- Ends by calling `ask_user` with `action: "complete"` and then writes a
+  decision log, not a summary paragraph.
+
+## S2 - answerable-from-repo question
+
+Setup: plan mentions "the test runner". The repo's package.json defines it.
+
+Expected:
+
+- Does NOT ask the user which test runner is used; reads package.json instead.
+- States what it found and asks only whether that constraint should remain
+  true.
+- Treats the area as review mode, not fill mode.
+
+## S3 - user defers
+
+Setup: mid-interview, user answers "whatever you think is best."
+
+Expected:
+
+- Records its own recommendation as the decision and says so explicitly.
+- Does not silently skip the branch.
+- Continues only if another root decision remains.
+
+## S4 - long phased interview
+
+Setup: prompt asks for a deep stress test of a large design.
+
+Expected:
+
+- First `ask_user` call sets a bounded `max_rounds` value such as 12 or 16.
+- Still asks one question per round.
+- Completes before the limit when decisions are sufficient.
+- If the limit is near, closes with current decisions and open risks instead
+  of continuing to ask.
+
+## S5 - stop signal
+
+Setup: mid-interview, user says "stop", "enough", "later", or cancels the
+modal.
+
+Expected:
+
+- Stops immediately and does not ask a confirmation question.
+- Calls `ask_user` complete when possible with partial decisions.
+- Final response includes partial decisions and the next unresolved root
+  question.
+
+## Baseline failure modes to watch for (RED)
+
+- Question batching: more than one question in an `ask_user` round.
+- Interview starts cold without reading repo facts that are clearly relevant.
+- Interview ends when the user gets tired, with no decision log.
+- Asks about facts discoverable via grep/read.
+- Hits the round limit without a useful closeout.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS (smoke). Skill loaded and interviewed; judge emitted nothing (truncation).

package/skills/workflow/workflow-distiller/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: workflow-distiller
+description: Use when a workflow that just happened should become reusable, when the user says "make this a skill", "package what we just did", "turn this into a workflow", or when the same multi-step process has been repeated across sessions. Reconstructs the workflow from the session record, interviews, checks overlap with installed skills, gates on approval, then writes the SKILL.md following skill-craft. Not for authoring a skill from scratch with no prior workflow; write the SKILL.md directly following skill-craft. Not for distilling into an agent recipe; propose that as a follow-up when the workflow is dispatch-shaped.
+version: 0.2.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - context
+  - write
+  - ask_user
+requires:
+  - skill:skill-craft
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/workflow/workflow-distiller
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: large
+---
+
+# Workflow Distiller
+
+Turn a workflow that actually ran into a reusable skill. The distiller's
+identity is runtime truth: it reconstructs what happened from the visible
+session record, not from anyone's memory of it. Skip the ceremony when there
+is no prior workflow; a from-scratch skill is a SKILL.md written directly,
+following skill-craft. skill-craft also governs how every skill this
+distiller produces is written: description, body, and pruning rules live
+there, not here.
+
+## Phase 1 - Reconstruct From Evidence
+
+Before asking anything, list the concrete steps that visibly executed in this
+session, in order: tools called, commands run, files touched, dispatches made,
+skills activated. Cite the conversation record for each step. Anything the
+user describes that did not visibly run is tagged `assumption` and becomes an
+interview question. This grounding step is mandatory and comes first; when the
+reconstruction and the user's memory disagree, the reconstruction wins and the
+disagreement is worth a question.
+
+## Phase 2 - Interview
+
+Use `ask_user` with `mode: "single_question"`, one question per round, bounded
+rounds (default 8, max 12), following the grill-me operating contract:
+recommended answer first when options are natural, stop signals ("stop",
+"enough", "later", cancel) respected immediately, answers translated into
+compact decisions. Question bank, roots before leaves:
+
+1. Confirm the reconstruction and resolve tagged assumptions.
+2. Inputs and outputs: what varies between runs, what is fixed.
+3. Recurrence: how often has this actually happened? A workflow that ran once
+   is usually not worth a skill; ask early and offer to stop.
+4. Per-step rigidity: must-match versus any-reasonable-approach.
+5. Failure behavior per step: ask the user, retry an alternative, or fail
+   loudly.
+6. Scope cuts: what the skill should refuse to do.
+7. Name (lowercase-hyphen).
+
+## Phase 3 - Overlap Check
+
+Call `context(scope="skills")` with no name to list installed skills. Judge
+overlap per step, not per workflow: if an installed skill's triggers cover a
+step, that step is referenced by name in the new skill body, never
+reimplemented, with a one-line rationale for the dependency. A different end
+goal does not excuse reimplementing a covered step. Record each reference as
+a `requires: [skill:<name>]` entry in the generated skill's frontmatter in
+Phase 5, so the loader warns when the dependency is missing.
+
+## Phase 4 - Design Gate
+
+Present a compact design summary and wait for explicit approval:
+
+```markdown
+## Skill Design - <name>
+Description draft: <triggers only, third person>
+Steps: <step, rigidity, on-failure> per line
+References: <skill:<name>, why> or none
+Scope: project | user (user only if the workflow crosses repositories)
+Validation scenario: <prompt, expected observable behavior>
+```
+
+No skill file is written before the user approves. "Looks fine, but change X"
+means revise and re-present.
+
+## Phase 5 - Create
+
+Write `SKILL.md` under `.clio-coder/skills/<approved-name>/`, following skill-craft
+for the frontmatter contract, a triggers-only third-person description, and
+the pruning pass, with `requires: [skill:<name>]` for every skill the overlap
+check referenced. Confirm it loads with `clio-coder skills validate`. Scope
+defaults to project; use the user skill store only when the user said the
+workflow crosses repositories. Placeholders replace every session-specific
+path, name, and value; distill the pattern, not the incident. Keep the
+generated skill under 120 lines; reference instead of inlining. If
+the session repeatedly dispatched the same worker pattern, also offer a recipe
+sketch for the agents surface, but do not write recipe files.
+
+## Phase 6 - Validate
+
+Record one RED-GREEN scenario agreed with the user: the prompt, and the
+observable behavior that distinguishes with-skill from without. Run it once if
+cheap (a single small headless run); otherwise record it in the skill body's
+example section as the standing validation obligation.
+
+## Worked Example
+
+Session: the user fetched a CSV export, normalized column names with a small
+script, and verified row counts against the source, three sessions in a row.
+
+1. Reconstruct: `bash curl ...` (ran), `write normalize.py` + `bash python3
+   normalize.py` (ran), `bash wc -l` comparison (ran). User also mentions "and
+   I always spot-check five rows" - not visible this session, tagged
+   assumption.
+2. Interview: confirms reconstruction; spot-check confirmed as a real step;
+   recurrence "weekly"; normalization must-match, fetch any-approach; failure
+   on row-count mismatch must fail loudly; name `csv-ingest`.
+3. Overlap: the `context(scope="skills")` listing shows no fetch or CSV skill
+   installed; no references.
+4. Gate: summary presented; user approves after tightening the description.
+5. Create: write `.clio-coder/skills/csv-ingest/SKILL.md`, placeholders for the
+   export URL and column map; `clio-coder skills validate` passes.
+6. Validate: scenario "ingest this month's export" must show fetch,
+   normalize, count-verify, spot-check in that order; recorded in the body.
+
+## Red Flags
+
+- Writing any skill before the design gate is approved.
+- A reconstruction that lists steps nothing in the session shows.
+- Reimplementing an installed skill's job instead of referencing it.
+- Session-specific paths or values surviving into the generated skill.
+- Batching interview questions or ignoring a stop signal.
+- Distilling a one-off without asking about recurrence.

package/skills/workflow/workflow-distiller/evals.md

@@ -0,0 +1,107 @@
+# Evals - workflow-distiller
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - "make what we just did a skill"
+
+Setup: Make what we just did a skill. For the record, this session we ran
+the release-notes workflow end to end: pulled the merged PR titles since
+the last tag with gh, grouped them by conventional-commit type, rewrote
+each group into user-facing bullets, and verified every PR number in the
+draft against the gh list before saving docs/release-notes.md. I also
+mentioned we sometimes ping the release channel afterwards, but we did not
+do that here.
+
+Expected:
+
+- Reconstructs the executed steps from the session record, in order, before
+  asking any question; unobserved steps the user mentions are tagged as
+  assumptions.
+- Interviews via `ask_user` with `mode: "single_question"`, one question per
+  round, bounded rounds.
+- Lists installed skills via `context(scope="skills")` with no name before
+  designing.
+- Presents a compact design summary and waits for explicit approval.
+- Writes the SKILL.md only after approval, with session-specific values
+  replaced by placeholders.
+- Records a RED-GREEN validation scenario.
+
+## S2 - overlap with an installed skill
+
+Setup: the workflow's retrieval step is already covered by an installed skill
+(for example arxiv-literature for paper retrieval).
+
+Expected:
+
+- The overlap check finds the installed skill.
+- The generated skill references it by name instead of reimplementing the
+  step, with a one-line rationale in the body.
+- The generated frontmatter carries `requires: [skill:<name>]` so the loader's
+  unmet-dependency warning arms when the referenced skill is absent.
+
+## S3 - no recurrence
+
+Setup: mid-interview the user admits the workflow has only ever run once and
+may not recur.
+
+Expected:
+
+- Questions whether distillation is worth it and offers to stop.
+- Does not press on to create a skill for a one-off by default.
+
+## S4 - anti-trigger: brand-new skill
+
+Setup: user asks for a new skill for something never done in any session.
+
+Expected:
+
+- Skips the distiller ceremony and points at writing the SKILL.md directly,
+  following skill-craft.
+
+## Baseline failure modes to watch for (RED)
+
+- Writes a vague skill immediately from the user's description, no grounding
+  in what actually ran.
+- No overlap check; reimplements an installed skill's behavior.
+- No approval gate; the skill file appears before the user saw a design.
+- Session-specific paths, URLs, and values baked into the skill body.
+- Multi-question interviewing or an unbounded question stream.
+
+## Observed results
+
+Runs 2026-07-02, headless `clio-coder run --skill`. `ask_user` is not registered in
+headless runs, so interviews were exercised with pre-supplied decisions in the
+prompt; the phases still had to run in order.
+
+- Six-phase walk (CSV header normalization fixture): the workflow visibly ran
+  (write plus execute normalize.py, row-count check), Phase 1 cited exactly
+  those steps, Phase 2 applied the pre-supplied decisions question by
+  question, Phase 3 listed installed skills with no name, Phase 4 presented
+  the summary and stopped for approval even though pre-approval was offered
+  (the strict reading of the gate), and after an explicit approval turn Phase
+  5's skill-creation call landed a loadable project skill that `clio-coder skills
+  inspect` resolves, with placeholders instead of session paths. Phase 6
+  recorded the validation scenario in the body.
+- S2 RED (no distiller, arxiv-literature installed): the baseline created the
+  skill immediately with no overlap check against the installed-skill
+  listing, no gate, and a body that reimplements the fetch step. Gap
+  confirmed.
+- S2 GREEN: with the shipped per-step overlap wording, the design references
+  `arxiv-literature` with a rationale instead of reimplementing retrieval.
+  Two earlier drafts missed this: workflow-level overlap judgment and a
+  fixture prompt that prescribed the fetch mechanism both masked the
+  behavior; the wording now says a different end goal does not excuse
+  reimplementing a covered step. At the time of that run the skill-creation
+  tool could not emit `requires` frontmatter, so the skill handed the user
+  the line to add; `requires: [skill:arxiv-literature]` on the generated
+  skill was verified to produce the loader's "requires skill ... which is not
+  available" warning when the dependency is absent. 2026-07-02: skill
+  creation moved to writing SKILL.md directly (the artifact tool's skill kind
+  was removed); Phase 5 now writes the `requires` entries into the
+  frontmatter itself.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Inline session-trace setup engaged; judge 5/6.

package/src/cli/acp.ts

@@ -0,0 +1,115 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { MAX_TIMER_DELAY_MS } from "../core/timers.js";
+import { runClioCommand } from "./clio.js";
+import { restoreStdout, takeOverStdout, writeRawStdout } from "./output-guard.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder acp [--cwd PATH] [--permission-timeout MS]
+
+Serve Clio Coder as an Agent Client Protocol v1 agent over stdio.
+
+  --cwd PATH               Workspace root the server boots in and opens sessions at.
+  --permission-timeout MS  How long a mediated permission request may wait for the
+                           client before the prompt expires. Defaults to the configured
+                           delegation.defaults.permissionTimeoutMs.
+
+This command is intended for ACP frontends to spawn. Interactive delegation remains
+available through /agents, /delegate, the dispatch board, and receipts.
+`;
+
+interface AcpFlags {
+	cwd?: string;
+	permissionTimeoutMs?: number;
+}
+
+/** Parsed flags, or the message explaining why the invocation is not usable. */
+function parseAcpFlags(args: ReadonlyArray<string>): AcpFlags | string {
+	const flags: AcpFlags = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		const value = args[index + 1];
+		if (arg === "--cwd") {
+			if (value === undefined) return "--cwd needs a directory";
+			flags.cwd = path.resolve(value);
+			index += 1;
+			continue;
+		}
+		if (arg === "--permission-timeout") {
+			const ms = value === undefined ? Number.NaN : Number(value);
+			if (!Number.isInteger(ms) || ms <= 0 || ms > MAX_TIMER_DELAY_MS) {
+				return `--permission-timeout needs a whole number from 1 to ${MAX_TIMER_DELAY_MS} milliseconds`;
+			}
+			flags.permissionTimeoutMs = ms;
+			index += 1;
+			continue;
+		}
+		return `unknown clio-coder acp option: ${arg ?? ""}`;
+	}
+	return flags;
+}
+
+/**
+ * The workspace root the server is pinned to, resolved and then canonicalized
+ * through the filesystem. A symlinked launch path is the reason: `process.cwd()`
+ * reports the physical path after chdir, so a session request carrying the same
+ * string the process was launched with used to be refused as a different
+ * workspace. One canonical form on both sides removes that class of mismatch.
+ * Throws when the path cannot be resolved, which the caller reports as an
+ * unusable `--cwd`.
+ */
+export function resolveAcpCwd(value: string): string {
+	return realpathSync(path.resolve(value));
+}
+
+export async function runAcpCommand(
+	args: ReadonlyArray<string>,
+	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
+): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const flags = parseAcpFlags(args);
+	if (typeof flags === "string") {
+		printError(flags);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	// Boot has to happen in the workspace the sessions will use: settings
+	// resolution, project context, and the session ledger all read process.cwd(),
+	// and the server refuses a session whose cwd is not the one it booted in.
+	// The path is canonicalized before the chdir so the launch root and every
+	// later comparison against process.cwd() speak the same physical path.
+	if (flags.cwd !== undefined) {
+		try {
+			process.chdir(resolveAcpCwd(flags.cwd));
+		} catch {
+			printError(`--cwd is not a directory this process can enter: ${flags.cwd}`);
+			return 2;
+		}
+	}
+	takeOverStdout();
+	try {
+		return await runClioCommand({
+			...(options.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+			...(options.noContextFiles ? { noContextFiles: true } : {}),
+			...(options.noSkills ? { noSkills: true } : {}),
+			...(options.skillPaths && options.skillPaths.length > 0 ? { skillPaths: options.skillPaths } : {}),
+			acp: {
+				// Stdout is JSON-RPC only. An unclassified handler failure answers the
+				// client with fixed host text; the original message, which nothing in
+				// this process authored, goes to the stderr tail.
+				transportOptions: {
+					write: writeRawStdout,
+					diagnostics: (line) => {
+						process.stderr.write(`[clio:acp] ${line}\n`);
+					},
+				},
+				...(flags.permissionTimeoutMs === undefined ? {} : { permissionTimeoutMs: flags.permissionTimeoutMs }),
+			},
+		});
+	} finally {
+		restoreStdout();
+	}
+}

package/src/cli/agents.ts

@@ -0,0 +1,60 @@
+import { loadDomains } from "../core/domain-loader.js";
+import type { AgentsContract } from "../domains/agents/contract.js";
+import { AgentsDomainModule } from "../domains/agents/index.js";
+import { type AgentSpec, isUserVisibleAgent } from "../domains/agents/spec.js";
+import { ConfigDomainModule } from "../domains/config/index.js";
+import { ensureClioState } from "../domains/lifecycle/index.js";
+import { SafetyDomainModule } from "../domains/safety/index.js";
+import { printError } from "./shared.js";
+
+const HELP = `clio-coder agents [--json] [--all]
+
+List user-facing agent specs from built-in, user, and project recipes.
+
+Flags:
+  --json   emit specs as JSON instead of the formatted table
+  --all    include shadow/internal specs reserved for Clio orchestration
+`;
+
+export async function runAgentsCommand(args: ReadonlyArray<string>): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const json = args.includes("--json");
+	const all = args.includes("--all");
+	const unknown = args.find((arg) => arg !== "--json" && arg !== "--all");
+	if (unknown) {
+		printError(`unknown flag: ${unknown}`);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	ensureClioState();
+	const result = await loadDomains([ConfigDomainModule, SafetyDomainModule, AgentsDomainModule]);
+	const agents = result.getContract<AgentsContract>("agents");
+	if (!agents) {
+		process.stderr.write("agents: domain not loaded\n");
+		await result.stop();
+		return 1;
+	}
+	const specs = all ? agents.listSpecs() : agents.listSpecs().filter(isUserVisibleAgent);
+	if (json) {
+		const withoutBody = specs.map(({ body: _body, ...rest }) => rest);
+		process.stdout.write(`${JSON.stringify(withoutBody, null, 2)}\n`);
+	} else {
+		for (const spec of specs) {
+			renderLine(spec);
+		}
+	}
+	await result.stop();
+	return 0;
+}
+
+function renderLine(spec: AgentSpec): void {
+	const shape = `${spec.audience}/${spec.category}/${spec.capabilityClass}/${spec.latencyClass}`;
+	const skills = spec.skills.length > 0 ? ` skills=${spec.skills.join(",")}` : "";
+	const budget = spec.budget
+		? `${spec.budget.toolCalls}/${spec.budget.readReserve}/${spec.budget.synthesis ? "synthesize" : "stop"}`
+		: "operator-default";
+	process.stdout.write(`${spec.id.padEnd(20)} ${shape.padEnd(48)} ${spec.description}${skills} budget=${budget}\n`);
+}