@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/core/xdg.ts

@@ -0,0 +1,177 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Resolve per-platform config/data/state/cache directories for Clio.
+ *
+ * This is the single resolution order, documented once:
+ *   1. Platform defaults.
+ *      Linux: XDG Base Directory spec (XDG_CONFIG_HOME, XDG_DATA_HOME,
+ *      XDG_STATE_HOME, XDG_CACHE_HOME).
+ *      macOS: ~/Library/Application Support/clio-coder/{config,data,state} and
+ *      ~/Library/Caches/clio-coder.
+ *      Windows: %APPDATA%/clio-coder/{config,data} and %LOCALAPPDATA%/clio-coder/{state,cache}.
+ *      Every root is distinct on every platform; no root nests inside another.
+ *   2. CLIO_CODER_HOME replaces all four roots symmetrically with
+ *      CLIO_CODER_HOME/{config,data,state,cache}.
+ *   3. CLIO_CODER_CONFIG_DIR / CLIO_CODER_DATA_DIR / CLIO_CODER_STATE_DIR / CLIO_CODER_CACHE_DIR each
+ *      override their one root and beat CLIO_CODER_HOME (most specific wins).
+ *
+ * Role contents: config holds user-authored files (settings, credentials,
+ * agents, skills, prompts, extensions, runtimes); data holds durable artifacts
+ * (memory, evidence, evals); state holds machine-produced session state
+ * (sessions, audit, receipts, runs.json, recent-models.json, install.json,
+ * interviews, scratch); cache holds disposable derived files.
+ */
+
+export interface ClioDirs {
+	config: string;
+	data: string;
+	state: string;
+	cache: string;
+}
+
+let cachedConfigDir: string | undefined;
+let cachedDataDir: string | undefined;
+let cachedStateDir: string | undefined;
+let cachedCacheDir: string | undefined;
+
+function envOrNull(key: string): string | null {
+	const v = process.env[key]?.trim();
+	return v && v.length > 0 ? v : null;
+}
+
+function platformDefaults(): ClioDirs {
+	const p = platform();
+	const h = homedir();
+	if (p === "win32") {
+		const appData = process.env.APPDATA ?? join(h, "AppData", "Roaming");
+		const localAppData = process.env.LOCALAPPDATA ?? join(h, "AppData", "Local");
+		return {
+			config: join(appData, "clio-coder", "config"),
+			data: join(appData, "clio-coder", "data"),
+			state: join(localAppData, "clio-coder", "state"),
+			cache: join(localAppData, "clio-coder", "cache"),
+		};
+	}
+	if (p === "darwin") {
+		const base = join(h, "Library", "Application Support", "clio-coder");
+		return {
+			config: join(base, "config"),
+			data: join(base, "data"),
+			state: join(base, "state"),
+			cache: join(h, "Library", "Caches", "clio-coder"),
+		};
+	}
+	const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(h, ".config");
+	const xdgData = process.env.XDG_DATA_HOME ?? join(h, ".local", "share");
+	const xdgState = process.env.XDG_STATE_HOME ?? join(h, ".local", "state");
+	const xdgCache = process.env.XDG_CACHE_HOME ?? join(h, ".cache");
+	return {
+		config: join(xdgConfig, "clio-coder"),
+		data: join(xdgData, "clio-coder"),
+		state: join(xdgState, "clio-coder"),
+		cache: join(xdgCache, "clio-coder"),
+	};
+}
+
+function ensureDir(dir: string): string {
+	try {
+		mkdirSync(dir, { recursive: true });
+	} catch (err) {
+		const e = err as NodeJS.ErrnoException;
+		if (e.code !== "EEXIST") throw err;
+	}
+	const s = statSync(dir);
+	if (!s.isDirectory()) throw new Error(`Expected directory at ${dir}`);
+	return dir;
+}
+
+function clioHomeOrNull(): string | null {
+	return envOrNull("CLIO_CODER_HOME");
+}
+
+function resolveRole(specificVar: string, role: keyof ClioDirs, defaults: ClioDirs): string {
+	const specific = envOrNull(specificVar);
+	if (specific) return specific;
+	const home = clioHomeOrNull();
+	if (home) return join(home, role);
+	return defaults[role];
+}
+
+export function resolveClioDirs(): ClioDirs {
+	const defaults = platformDefaults();
+	return {
+		config: resolveRole("CLIO_CODER_CONFIG_DIR", "config", defaults),
+		data: resolveRole("CLIO_CODER_DATA_DIR", "data", defaults),
+		state: resolveRole("CLIO_CODER_STATE_DIR", "state", defaults),
+		cache: resolveRole("CLIO_CODER_CACHE_DIR", "cache", defaults),
+	};
+}
+
+export function clioConfigDir(): string {
+	if (cachedConfigDir) return cachedConfigDir;
+	cachedConfigDir = ensureDir(resolveClioDirs().config);
+	return cachedConfigDir;
+}
+
+export function clioDataDir(): string {
+	if (cachedDataDir) return cachedDataDir;
+	cachedDataDir = ensureDir(resolveClioDirs().data);
+	return cachedDataDir;
+}
+
+export function clioStateDir(): string {
+	if (cachedStateDir) return cachedStateDir;
+	cachedStateDir = ensureDir(resolveClioDirs().state);
+	return cachedStateDir;
+}
+
+export function clioCacheDir(): string {
+	if (cachedCacheDir) return cachedCacheDir;
+	cachedCacheDir = ensureDir(resolveClioDirs().cache);
+	return cachedCacheDir;
+}
+
+export function clioStatePath(): string {
+	return cachedStateDir ?? resolveClioDirs().state;
+}
+
+/**
+ * True when the state root this process resolved is no longer on disk.
+ *
+ * `clio-coder uninstall` removes the whole root while processes holding session
+ * writers, ledgers and audit files are still running, and every writer under
+ * the root mkdirs its parent back: `safeResourceWrite` does it before the temp
+ * file, the state file lock does it before the critical section, the audit
+ * writer does it before opening the day's file. A write landing after the
+ * removal therefore recreated the state home, so an uninstall that reported
+ * success left one behind and the next `clio-coder` start read state from a home that
+ * was supposed to be gone. The live case was the shutdown checkpoint, roughly
+ * two minutes late, rebuilding the root around a meta.json and tree.json that
+ * announced `lastCheckpointReason: shutdown`.
+ *
+ * "Removed" and "never created" are not the same thing, and only the first is a
+ * reason to refuse a write. With no cached root this process has not resolved
+ * one yet, so a writer creating it is an ordinary first run; the audit writer
+ * reaches its first row before anything else has called `clioStateDir()`, and
+ * treating that as an uninstall silently disabled audit on a fresh install.
+ * Reads the cache directly rather than `clioStateDir()` because the latter
+ * creates the directory it is being asked about.
+ *
+ * Every writer under the state root calls this before it touches disk, and
+ * again inside whatever lock it holds, because the removal can land while the
+ * call waits for a sibling process to leave its critical section.
+ */
+export function stateRootRemoved(): boolean {
+	if (cachedStateDir === undefined) return false;
+	return !existsSync(cachedStateDir);
+}
+
+export function resetXdgCache(): void {
+	cachedConfigDir = undefined;
+	cachedDataDir = undefined;
+	cachedStateDir = undefined;
+	cachedCacheDir = undefined;
+}

package/src/domains/agents/builtins/architect.md

@@ -4,7 +4,7 @@ name: Architect
 description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
 tools:
   required: [artifact, context]
-  optional: [read, grep, find, ls, code_nav, git]
+  optional: [read, grep, find, ls, code_nav, git, ledger]
 skills: [cut-it]
 audience: base
 category: plan
@@ -12,7 +12,7 @@ capabilityClass: artifact-write
 latencyClass: deep
 projectContextTier: bounded
 budget: {toolCalls: 32, readReserve: 5, synthesis: true}
-resultContract: {kind: architect-plan, path: PLAN.md}
+resultContract: {kind: architect-plan, path: .clio-coder/artifacts/PLAN.md}
 tags: [architecture, boundaries, migration]
 ---
 
@@ -27,7 +27,7 @@ Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely
 Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
 Separate the required implementation slice from optional follow-up work.
 Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.
-Use `artifact` (kind="plan") only when the result should become a reviewable `PLAN.md`.
+Use `artifact` (kind="plan") only when the result should become a reviewable plan document.
 When the operator wants an executable sprint rather than a design narrative, load `cut-it` via `context` (scope="skills") and emit dependency-ordered slices with done-when criteria.
 Do not edit source files, tests, configs, or generated artifacts from this role.
-Write the plan with `artifact` (kind="plan") at `PLAN.md`. The integrity-recorded `PLAN.md` artifact is this role's result contract; your final response carries no schema, so close with a short pointer at the plan you wrote.
+Write the plan with `artifact` (kind="plan") and no path argument, which lands it at `.clio-coder/artifacts/PLAN.md`. That integrity-recorded artifact is this role's result contract; your final response carries no schema, so close with a short pointer at the plan you wrote.

package/src/domains/agents/builtins/coder.md

@@ -4,8 +4,8 @@ name: Coder
 description: Implements bounded code changes, repairs, and behavior-preserving refactors.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
-  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash]
-skills: [commit-crafting, review-changes]
+  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
+skills: [fix-issue, ship]
 audience: base
 category: implement
 capabilityClass: workspace-edit
@@ -29,3 +29,4 @@ Run the narrowest useful validation first, then broaden when risk or shared beha
 Use `git` (op=diff) before finishing to verify the diff matches the task.
 If a requested simplification would change behavior, stop and report the boundary.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.
+`validations` is never empty and never a list of strings. Each entry is one check you actually made, shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, with no other keys. When the task changed nothing, the read or command you did run is still the validation: name it and quote what it showed.

package/src/domains/agents/builtins/debugger.md

@@ -4,7 +4,7 @@ name: Debugger
 description: Diagnoses failing code, tests, receipts, or runtime behavior without making edits.
 tools:
   required: [verify]
-  optional: [read, grep, find, ls, git, code_nav]
+  optional: [read, grep, find, ls, git, code_nav, ledger]
 skills: []
 audience: base
 category: quality

package/src/domains/agents/builtins/documenter.md

@@ -4,7 +4,7 @@ name: Documenter
 description: Updates developer-facing docs, examples, and concise operational runbooks.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, git, verify, code_nav, context]
+  optional: [grep, find, ls, git, verify, code_nav, context, ledger]
 skills: []
 audience: base
 category: implement

package/src/domains/agents/builtins/git-master.md

@@ -4,8 +4,8 @@ name: Git Master
 description: Executes bounded git operations end-to-end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
 tools:
   required: [read, {anyOf: [write, edit]}, context, git]
-  optional: [bash, grep, find, ls, code_nav]
-skills: [commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge]
+  optional: [bash, grep, find, ls, code_nav, ledger]
+skills: [fix-issue, ship, worktree-create, worktree-merge]
 audience: base
 category: implement
 capabilityClass: workspace-edit
@@ -21,7 +21,7 @@ tags: [git, commit, worktree, merge, pr, history]
 You are Git Master, the base agent for repository state operations.
 Start by restating the assigned git task and the exact end state it must produce.
 Inspect before mutating: `git` (op=status) and op=diff before any add, commit, merge, or worktree change; read `git log` before any history claim.
-Load the bound skill that matches the task (commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge) and follow its steps instead of improvising the workflow.
+Load the bound skill that matches the task (fix-issue, ship, worktree-create, worktree-merge) and follow its steps instead of improvising the workflow.
 Local operations only, unless the task explicitly orders otherwise: never push, open a PR, tag, publish, or alter remotes on your own judgment; when a task stops at a boundary, report the boundary.
 Never run destructive history commands (`reset --hard`, `push --force`, `clean -fd`, branch -D on unmerged work) unless the task names the exact command and target.
 Stage files by explicit path after reviewing the untracked list; never blind `git add -A` past unreviewed or secret-shaped files.

package/src/domains/agents/builtins/provenance.md

@@ -4,7 +4,7 @@ name: Provenance
 description: Shadow evidence, receipt, diff, and telemetry reader for source-backed handoffs.
 tools:
   required: [read]
-  optional: [grep, find, ls, git]
+  optional: [grep, find, ls, git, ledger]
 skills: []
 audience: shadow
 category: operations

package/src/domains/agents/builtins/researcher.md

@@ -4,7 +4,7 @@ name: Researcher
 description: Shadow external-source researcher for coding decisions, official docs, standards, release notes, and academic papers.
 tools:
   required: [read]
-  optional: [web_fetch, context]
+  optional: [web_fetch, context, ledger]
 skills: []
 audience: shadow
 category: research

package/src/domains/agents/builtins/scout.md

@@ -4,7 +4,7 @@ name: Scout
 description: Use for any broad repository reconnaissance, codebase orientation, structure/entry-point mapping, or multi-file symbol hunting; returns cited findings fast without spending main-context tool calls.
 tools:
   required: [read]
-  optional: [grep, find, ls, context, code_nav, git]
+  optional: [grep, find, ls, context, code_nav, git, ledger]
 skills: []
 audience: shadow
 category: explore

package/src/domains/agents/builtins/tester.md

@@ -4,7 +4,7 @@ name: Tester
 description: Adds focused deterministic tests for regressions and missing coverage.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, git, verify, code_nav]
+  optional: [grep, find, ls, git, verify, code_nav, ledger]
 skills: []
 audience: base
 category: quality

package/src/domains/agents/builtins/verifier.md

@@ -4,7 +4,7 @@ name: Verifier
 description: Independently runs and reports test, lint, build, review, and release gates.
 tools:
   required: [verify]
-  optional: [read, grep, find, ls, git, code_nav]
+  optional: [read, grep, find, ls, git, code_nav, ledger]
 skills: []
 audience: base
 category: quality

package/src/domains/agents/builtins/wiki-writer.md

@@ -4,7 +4,7 @@ name: Wiki Writer
 description: Plans one repository wiki, or researches and writes one wiki page, against a supplied plan.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, code_nav, context]
+  optional: [grep, find, ls, code_nav, context, ledger]
 skills: []
 audience: base
 category: implement

package/src/domains/agents/catalog.ts

@@ -0,0 +1,172 @@
+import type { AgentRecipe } from "./recipe.js";
+import { type AgentSpec, isUserVisibleAgent, normalizeAgentSpec } from "./spec.js";
+
+const DEFAULT_DISPATCH_AGENT_ID = "coder";
+
+export interface AgentCatalogSections {
+	stable: string;
+	volatile: string;
+}
+
+function renderAgentCatalogSections(recipes: ReadonlyArray<AgentRecipe>): AgentCatalogSections {
+	return renderAgentCatalogSectionsFromSpecs(recipes.map(normalizeAgentSpec));
+}
+
+/** Keeps one roster line short enough that the whole fleet block stays near its token budget. */
+const FLEET_PROMPT_PURPOSE_MAX_CHARS = 64;
+
+/**
+ * The delegation default stated as a rule the model can evaluate against the
+ * task in front of it. The E19 drive found the previous phrasing lost to
+ * inertia every time: an incentive ("dispatch is the cheap path") is not a
+ * test, so a model that had already started reading simply kept reading. A
+ * threshold it can count against is.
+ */
+export const FLEET_DELEGATION_RULE =
+	"Delegate when the task has two or more independent file-scoped subtasks, or any broad exploration. You keep synthesis and validation; a single narrow change stays with you.";
+
+/**
+ * S3 handed two files to a worker, then edited both itself before dispatching,
+ * reverted one, and disclosed neither. The delegation rule above says what to
+ * hand off; this says what handing off costs you.
+ */
+export const FLEET_HANDOFF_RULE =
+	"A file you assigned to a worker is not yours to edit while its dispatch is pending or after it succeeds; if you already changed it, say so in your report.";
+
+/**
+ * R5's admission correctly refused a verifier for mutation work and named the
+ * mismatch, and the final answer to the operator never mentioned it. A refusal
+ * the operator cannot see reads as a silent agent swap.
+ */
+export const FLEET_REFUSAL_DISCLOSURE =
+	"When admission refuses a dispatch, report the refusal and the reason it gave; never substitute another agent without saying why.";
+
+/**
+ * R6 issued five near-identical `tester` dispatches because each differed
+ * textually, so a string-identity rule never fired. The test that catches that
+ * run is about the work, and the model needs somewhere else to go than a sixth
+ * dispatch.
+ */
+export const FLEET_ANTI_CHURN_RULE =
+	"A dispatch with the same target files and the same goal as one you already ran is a repeat however differently you word it: read that run's receipt, or run the check yourself, instead of dispatching again.";
+
+/**
+ * `agent:"auto"` baselines from task text alone and cannot see the shape of a
+ * probe, so the jobs it most often misroutes are named against the roster ids
+ * directly below this line.
+ */
+export const FLEET_SPECIALIST_ROUTING =
+	"Pick by job: receipts, diffs, or telemetry -> provenance; external docs -> researcher; broad recon -> scout; tests -> tester; gates or review -> verifier.";
+
+function fleetPromptPurpose(description: string): string {
+	const trimmed = description.trim().replace(/\s+/gu, " ");
+	if (trimmed.length === 0) return "";
+	// One sentence is the useful unit: recipe descriptions put the agent's job
+	// first and its qualifications after the first period.
+	const stop = trimmed.indexOf(". ");
+	const sentence = stop > 0 ? trimmed.slice(0, stop) : trimmed.replace(/\.$/u, "");
+	if (sentence.length <= FLEET_PROMPT_PURPOSE_MAX_CHARS) return sentence;
+	const cut = sentence.lastIndexOf(" ", FLEET_PROMPT_PURPOSE_MAX_CHARS);
+	return `${sentence.slice(0, cut > 0 ? cut : FLEET_PROMPT_PURPOSE_MAX_CHARS).trimEnd()}...`;
+}
+
+function fleetPromptLine(spec: AgentSpec): string {
+	const budget = spec.budget ? `${spec.budget.toolCalls} calls` : "default budget";
+	const purpose = fleetPromptPurpose(spec.description);
+	return `- ${spec.id} (${spec.capabilityClass}, ${budget})${purpose.length > 0 ? `: ${purpose}` : ""}`;
+}
+
+/**
+ * Compact roster for the compiled session prompt. The full catalog above is a
+ * tool result the model has to ask for; this is the same roster small enough to
+ * live in the prompt, so choosing a specialist never costs a round trip. Shadow
+ * agents are listed because they are dispatchable, marked so the model does not
+ * offer them to the operator as `/run` choices. Byte-stable for a given spec
+ * set: the prompt prefix must not churn between turns.
+ */
+export function renderFleetPromptSection(input: ReadonlyArray<AgentSpec>): string {
+	const specs = input.slice().sort((a, b) => {
+		const category = a.category.localeCompare(b.category);
+		return category === 0 ? a.id.localeCompare(b.id) : category;
+	});
+	const publicSpecs = specs.filter(isUserVisibleAgent);
+	const shadowSpecs = specs.filter((spec) => spec.audience === "shadow");
+	if (publicSpecs.length === 0 && shadowSpecs.length === 0) return "";
+
+	const lines: string[] = [
+		"# Fleet",
+		FLEET_DELEGATION_RULE,
+		FLEET_HANDOFF_RULE,
+		FLEET_ANTI_CHURN_RULE,
+		FLEET_REFUSAL_DISCLOSURE,
+		`Workers you reach with \`dispatch\`, by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}). Capability class is what a worker may do: a read-only worker cannot edit.`,
+		FLEET_SPECIALIST_ROUTING,
+	];
+	if (publicSpecs.length > 0) {
+		lines.push("", "Operator-facing:", ...publicSpecs.map(fleetPromptLine));
+	}
+	if (shadowSpecs.length > 0) {
+		// Dispatchable, but never a `/run` suggestion: they are plumbing.
+		lines.push("", "Internal specialists, dispatch-only:", ...shadowSpecs.map(fleetPromptLine));
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Spec-based roster used when the caller already holds normalized specs.
+ * `AgentsContract.listSpecs()` includes ACP delegation agents synthesized from
+ * settings.delegation.agents[], which never exist as recipe files; rendering
+ * from specs keeps those dispatchable targets discoverable in the fleet block.
+ */
+export function renderAgentCatalogSectionsFromSpecs(input: ReadonlyArray<AgentSpec>): AgentCatalogSections {
+	const specs = input.slice().sort((a, b) => {
+		const category = a.category.localeCompare(b.category);
+		return category === 0 ? a.id.localeCompare(b.id) : category;
+	});
+	const publicSpecs = specs.filter(isUserVisibleAgent);
+	const shadowSpecs = specs.filter((spec) => spec.audience === "shadow");
+
+	const lines: string[] = [
+		"Clio manages a small fleet of coding agents. Recipes are Markdown files; normalized specs carry audience, category, capability, tools, skills, latency, and worker-budget hints.",
+		"Use the `dispatch` tool to invoke one by `agent_id` when delegation helps.",
+		`Default dispatch agent: ${DEFAULT_DISPATCH_AGENT_ID}.`,
+		"User-facing agents are base/custom. Shadow agents are internal helpers for context, research, and provenance; do not recommend them as normal `/run` choices.",
+		"Prefer fast read-only agents for orientation, verification agents for gates, and workspace-edit agents only for bounded coding tasks.",
+		"When a task matches a skill named on an agent line (skills=...), prefer the recipe that binds it; its worker is told to load bound skills for the run.",
+		'After a dispatch succeeds, synthesize from the sealed receipt; the worker\'s prose is an advisory claim until its verification state is verified. Spot-check delegated claims before repeating them: re-read any cited file:line location, and re-run or inspect the named validation before repeating a "tests pass" claim.',
+		FLEET_ANTI_CHURN_RULE,
+	];
+
+	if (publicSpecs.length > 0) {
+		lines.push("", "User-facing agents:");
+		for (const spec of publicSpecs) {
+			const description = spec.description.trim();
+			const suffix = description.length > 0 ? ` - ${description}` : "";
+			lines.push(formatSpecLine(spec, suffix));
+		}
+	}
+	if (shadowSpecs.length > 0) {
+		lines.push("", "Shadow agents for internal orchestration:");
+		for (const spec of shadowSpecs) {
+			const description = spec.description.trim();
+			const suffix = description.length > 0 ? ` - ${description}` : "";
+			lines.push(formatSpecLine(spec, suffix));
+		}
+	}
+
+	return { stable: lines.join("\n"), volatile: "" };
+}
+
+function formatSpecLine(spec: AgentSpec, suffix: string): string {
+	const tags = spec.tags.length > 0 ? `, tags=${spec.tags.join("/")}` : "";
+	const skills = spec.skills.length > 0 ? `, skills=${spec.skills.join("/")}` : "";
+	const budget = spec.budget
+		? `, budget=${spec.budget.toolCalls}/${spec.budget.readReserve}/${spec.budget.synthesis ? "synthesize" : "stop"}`
+		: ", budget=operator-default";
+	return `- ${spec.name} [${spec.id}] (${spec.audience}, ${spec.category}, ${spec.capabilityClass}, ${spec.latencyClass}, ${spec.source}${tags}${skills}${budget})${suffix}`;
+}
+
+export function renderAgentCatalog(recipes: ReadonlyArray<AgentRecipe>): string {
+	const sections = renderAgentCatalogSections(recipes);
+	return [sections.stable, sections.volatile].filter((part) => part.trim().length > 0).join("\n\n");
+}

package/src/domains/agents/contract.ts

@@ -0,0 +1,16 @@
+import type { AgentRecipe } from "./recipe.js";
+import type { AgentRecipeDiagnostic } from "./registry.js";
+import type { AgentSpec } from "./spec.js";
+
+export interface AgentsContract {
+	/** Raw recipes as loaded from Markdown files. */
+	list(): ReadonlyArray<AgentRecipe>;
+	get(id: string): AgentRecipe | null;
+	/** Structured quarantine diagnostics; malformed recipes never appear in list/get. */
+	diagnostics(): ReadonlyArray<AgentRecipeDiagnostic>;
+	/** Normalized, policy-bearing specs for catalog and dispatch consumers. */
+	listSpecs(): ReadonlyArray<AgentSpec>;
+	getSpec(id: string): AgentSpec | null;
+	/** Discover all agents: builtins + user + project. */
+	reload(): void;
+}

package/src/domains/agents/extension.ts

@@ -0,0 +1,110 @@
+import path from "node:path";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { assertAgentIdNamespace } from "../config/agent-namespace.js";
+import type { ConfigContract } from "../config/contract.js";
+import type { AgentsContract } from "./contract.js";
+import type { AgentRecipe } from "./recipe.js";
+import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "./registry.js";
+import { type AgentSpec, normalizeAgentSpec } from "./spec.js";
+
+export function createAgentsBundle(_context: DomainContext): DomainBundle<AgentsContract> {
+	let recipes: ReadonlyArray<AgentRecipe> = [];
+	let specs: ReadonlyArray<AgentSpec> = [];
+	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
+
+	function discover(): void {
+		const builtinDir = path.join(resolvePackageRoot(), "src", "domains", "agents", "builtins");
+		const userDir = path.join(clioConfigDir(), "agents");
+		const projectDir = path.join(process.cwd(), ".clio-coder", "agents");
+		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
+		const builtin = loadRecipesFromDir({ dir: builtinDir, source: "builtin" }, nextDiagnostics);
+		const user = loadRecipesFromDir({ dir: userDir, source: "user" }, nextDiagnostics);
+		const project = loadRecipesFromDir({ dir: projectDir, source: "project" }, nextDiagnostics);
+		const merged = mergeRecipes(builtin, user, project);
+		const config = _context.getContract<ConfigContract>("config");
+		assertAgentIdNamespace(merged, config?.get()?.delegation?.agents ?? []);
+		recipes = merged;
+		specs = recipes.map(normalizeAgentSpec);
+		diagnostics = nextDiagnostics;
+	}
+
+	const extension: DomainExtension = {
+		async start() {
+			discover();
+		},
+		async stop() {},
+	};
+
+	const contract: AgentsContract = {
+		list() {
+			return recipes;
+		},
+		get(id: string): AgentRecipe | null {
+			return recipes.find((r) => r.id === id) ?? null;
+		},
+		diagnostics() {
+			return diagnostics.map((diagnostic) => ({ ...diagnostic }));
+		},
+		listSpecs() {
+			const config = _context.getContract<ConfigContract>("config");
+			const delegationAgents = config?.get()?.delegation?.agents ?? [];
+			const delegationSpecs = delegationAgents.map((agent) => ({
+				version: 1 as const,
+				id: agent.id,
+				name: agent.id,
+				description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+				source: "custom" as const,
+				filepath: "settings.yaml",
+				tools: [],
+				toolRequirements: { required: [], optional: [] },
+				category: "explore" as const,
+				capabilityClass: "orchestration" as const,
+				latencyClass: "deep" as const,
+				projectContextTier: "none" as const,
+				audience: "custom" as const,
+				tags: ["delegation", "acp"],
+				skills: [],
+				resultContract: { kind: "external-delegation" } as const,
+				budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+				body: "External ACP delegation.",
+			}));
+			return [...specs, ...delegationSpecs];
+		},
+		getSpec(id: string): AgentSpec | null {
+			const found = specs.find((r) => r.id === id);
+			if (found) return found;
+			const config = _context.getContract<ConfigContract>("config");
+			const agent = config?.get()?.delegation?.agents?.find((entry) => entry.id === id);
+			if (agent) {
+				return {
+					version: 1 as const,
+					id: agent.id,
+					name: agent.id,
+					description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+					source: "custom" as const,
+					filepath: "settings.yaml",
+					tools: [],
+					toolRequirements: { required: [], optional: [] },
+					category: "explore" as const,
+					capabilityClass: "orchestration" as const,
+					latencyClass: "deep" as const,
+					projectContextTier: "none" as const,
+					audience: "custom" as const,
+					tags: ["delegation", "acp"],
+					skills: [],
+					resultContract: { kind: "external-delegation" } as const,
+					budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+					body: "External ACP delegation.",
+				};
+			}
+			return null;
+		},
+		reload() {
+			discover();
+		},
+	};
+
+	return { extension, contract };
+}