@agentplate/cli 1.0.0 → 1.2.0

package/src/commands/sling.test.ts

@@ -0,0 +1,84 @@
+/**
+ * `agentplate sling` — unit tests for the spec-contract path.
+ *
+ * These cover the two pure pieces that fix the launch/mail race without spinning
+ * up a full spawn: `readSpecContract` (the --spec guard) and `dispatchBody` (which
+ * inlines the contract into the agent's first prompt). Real temp files, no mocks.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import type { OverlayConfig } from "../types.ts";
+import { dispatchBody, readSpecContract } from "./sling.ts";
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "agentplate-sling-spec-"));
+});
+
+afterEach(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("readSpecContract", () => {
+	test("returns empty string when no --spec is given (spec is optional)", () => {
+		expect(readSpecContract(undefined, "task-1")).toBe("");
+	});
+
+	test("returns the file content when the spec exists and is non-empty", () => {
+		const f = join(dir, "task-1.md");
+		writeFileSync(f, "Goal: build the thing\n", "utf8");
+		expect(readSpecContract(f, "task-1")).toBe("Goal: build the thing\n");
+	});
+
+	test("throws when the --spec file is missing (points at `spec write`)", () => {
+		const missing = join(dir, "absent.md");
+		expect(() => readSpecContract(missing, "task-1")).toThrow(ValidationError);
+		try {
+			readSpecContract(missing, "task-1");
+		} catch (e) {
+			expect((e as Error).message).toContain("agentplate spec write task-1");
+		}
+	});
+
+	test("throws when the --spec file is empty/whitespace (blank contract)", () => {
+		const f = join(dir, "blank.md");
+		writeFileSync(f, "   \n\t\n", "utf8");
+		expect(() => readSpecContract(f, "task-1")).toThrow(ValidationError);
+	});
+});
+
+const baseCfg: OverlayConfig = {
+	agentName: "lead-task-1",
+	capability: "lead",
+	taskId: "task-1",
+	specPath: ".agentplate/specs/task-1.md",
+	branchName: "agentplate/lead-task-1",
+	worktreePath: "/tmp/wt",
+	parentAgent: "coordinator",
+	depth: 1,
+	fileScope: [],
+	baseDefinition: "",
+	canSpawn: true,
+	qualityGates: [],
+	constraints: [],
+};
+
+describe("dispatchBody", () => {
+	test("inlines the spec contract into the dispatch when present", () => {
+		const body = dispatchBody("task-1", "lead", baseCfg, "Goal: build the thing");
+		expect(body).toContain("=== SPEC");
+		expect(body).toContain("Goal: build the thing");
+		expect(body).toContain("Task: task-1");
+	});
+
+	test("omits the SPEC block when there is no spec body", () => {
+		const body = dispatchBody("task-1", "lead", baseCfg, "");
+		expect(body).not.toContain("=== SPEC");
+		expect(body).toContain("Task: task-1");
+	});
+});

package/src/commands/sling.ts

@@ -6,28 +6,27 @@
  * the agent identity + session row → dispatch the task over mail → run the first
  * headless turn → observe the agent's terminal mail to transition the session.
  *
- * Headless spawn-per-turn: this runs the FIRST turn. Subsequent turns are driven
- * by new mail (a later refinement); the basic core proves the single-turn loop.
+ * Headless spawn-per-turn: this runs the FIRST turn (a fresh runtime session).
+ * Follow-up turns are run by `agentplate turn <agent>`, which resumes the same
+ * session (warm start). Both share the {@link driveTurn} core.
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { Command } from "commander";
-import { createIdentity, updateIdentity } from "../agents/identity.ts";
+import { assertCapacity } from "../agents/capacity.ts";
+import { driveTurn } from "../agents/drive.ts";
+import { createIdentity } from "../agents/identity.ts";
 import { buildDefaultManifest, getDefinition, loadManifest } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
-import { runTurn } from "../agents/turn-runner.ts";
 import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
-import { runQualityGates } from "../insights/quality-gates.ts";
 import { jsonOutput } from "../json.ts";
 import { brand, muted, printHint, printInfo, printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
-import { createMailStore } from "../mail/store.ts";
 import {
 	currentRunPath,
 	eventsDbPath,
-	mailDbPath,
 	manifestFilePath,
 	packageAgentDefPath,
 	sessionsDbPath,
@@ -35,7 +34,7 @@ import {
 import { getRuntime } from "../runtimes/registry.ts";
 import { resolveModel } from "../runtimes/resolve.ts";
 import { createSessionStore } from "../sessions/store.ts";
-import { retrieveSkillsForSpawn, runSkillFeedbackAndDistill } from "../skills/lifecycle.ts";
+import { retrieveSkillsForSpawn } from "../skills/lifecycle.ts";
 import type { AgentManifest, AgentSession, Capability, OverlayConfig } from "../types.ts";
 import { SUPPORTED_CAPABILITIES } from "../types.ts";
 import { createWorktree } from "../worktree/manager.ts";
@@ -123,9 +122,24 @@ export function createSlingCommand(): Command {
 			const mail = createMailClient(root);
 			const events = createEventStore(eventsDbPath(root));
 			try {
+				// Validate + load the spec contract up front (fails loudly on a missing or
+				// empty --spec rather than launching the agent contract-less).
+				const specBody = readSpecContract(opts.spec, taskId);
+
 				// Resolve the run this agent belongs to.
 				const runId = resolveRun(store, root, opts);
 
+				// Enforce orchestration capacity BEFORE any worktree/session is created,
+				// so a runaway fan-out is refused cleanly instead of spawning unbounded.
+				const parentAgent = opts.parent ?? null;
+				assertCapacity({
+					depth: Number(opts.depth ?? "0"),
+					active: store.countActive(runId),
+					parentAgent,
+					parentActiveChildren: parentAgent ? store.countActiveByParent(parentAgent, runId) : 0,
+					limits: config.agents,
+				});
+
 				const name = uniqueName(store, opts.name ?? `${capability}-${taskId}`);
 				const branchName = `agentplate/${name}`;
 
@@ -191,94 +205,25 @@ export function createSlingCommand(): Command {
 					from: opts.parent ?? "operator",
 					to: name,
 					subject: `Dispatch: ${taskId}`,
-					body: dispatchBody(taskId, capability, overlayConfig),
+					body: dispatchBody(taskId, capability, overlayConfig, specBody),
 					type: "dispatch",
 				});
 
-				// 5. Run the first headless turn.
-				const resolved = resolveModel(config, root, def.model);
-				store.updateSessionState(session.id, "working");
+				// 5. Run the first turn. Follow-up turns warm-start (resume) via
+				//    `agentplate turn`; driveTurn owns state + skills + auto-merge.
+				const resolved = resolveModel(config, root, def.model, capability);
 				const prompt = buildInitialPrompt(mail.checkInject(name), runtime.instructionPath);
-				let sawError = false;
-				const turn = await runTurn({
+				const { finalState, exitCode } = await driveTurn({
+					root,
+					config,
 					runtime,
-					worktreePath: worktree.path,
-					model: resolved.model,
+					store,
+					events,
+					mail,
+					session,
+					model: resolved,
 					prompt,
-					env: resolved.env,
-					onEvent: (event) => {
-						if (event.error || event.type === "error") sawError = true;
-						// Prefer the error message (so a failed agent's reason is visible in
-						// the feed/logs), else the token/cost JSON the Costs page aggregates.
-						const detail = event.error
-							? event.error
-							: event.usage
-								? JSON.stringify({ tokens: event.usage.tokens, cost: event.usage.costUsd })
-								: null;
-						events.record({
-							agentName: name,
-							runId,
-							type: event.type,
-							tool: event.tool ?? null,
-							detail,
-						});
-						// Bump last_activity on every streamed event so a long but active
-						// turn keeps itself fresh and is never reaped as "idle".
-						store.touch(session.id);
-					},
 				});
-				if (turn.runtimeSessionId) store.setRuntimeSessionId(session.id, turn.runtimeSessionId);
-
-				// A non-zero exit with no error event means the runtime failed via stderr
-				// (e.g. Pi's "No API key found for anthropic"). Record that stderr so the
-				// failure reason is visible in the feed/logs instead of a blank "failed".
-				if (turn.exitCode !== 0 && !sawError) {
-					const reason = turn.stderr.trim();
-					if (reason) {
-						events.record({
-							agentName: name,
-							runId,
-							type: "error",
-							tool: null,
-							detail: reason.length > 1000 ? `${reason.slice(0, 1000)}…` : reason,
-						});
-					}
-				}
-
-				// 6. Observe terminal mail to transition the session.
-				const finalState = resolveFinalState(root, name, capability, turn.exitCode);
-				store.updateSessionState(session.id, finalState);
-				store.touch(session.id);
-				updateIdentity(root, name, {
-					taskId,
-					summary: `${capability} ran a turn for ${taskId} → ${finalState}`,
-				});
-
-				// 7. Self-improving loop: score quality gates, append outcomes to
-				//    applied skills, and distill a skill when the work passed. Only
-				//    runs for a completed task; best-effort (never fails the spawn).
-				if (finalState === "completed" && config.skills.enabled) {
-					try {
-						const gateOutcome = await runQualityGates(
-							config.project.qualityGates ?? [],
-							worktree.path,
-						);
-						await runSkillFeedbackAndDistill({
-							root,
-							agentName: name,
-							capability,
-							taskId,
-							worktreePath: worktree.path,
-							baseRef: config.project.canonicalBranch,
-							runtime,
-							outcomeStatus: gateOutcome?.status ?? null,
-							skills: config.skills,
-							model: resolved.model,
-						});
-					} catch {
-						// Skill loop is advisory; a failure here must not fail the spawn.
-					}
-				}
 
 				if (useJson) {
 					jsonOutput({
@@ -289,7 +234,7 @@ export function createSlingCommand(): Command {
 						branchName,
 						worktreePath: worktree.path,
 						state: finalState,
-						exitCode: turn.exitCode,
+						exitCode: exitCode,
 					});
 					return;
 				}
@@ -297,8 +242,8 @@ export function createSlingCommand(): Command {
 				printInfo(`  task:    ${taskId}`);
 				printInfo(`  branch:  ${branchName}`);
 				printInfo(`  worktree:${muted(` ${worktree.path}`)}`);
-				if (turn.exitCode !== 0) {
-					printHint(`  turn exited ${turn.exitCode}; see \`agentplate mail list --from ${name}\``);
+				if (exitCode !== 0) {
+					printHint(`  turn exited ${exitCode}; see \`agentplate mail list --from ${name}\``);
 				}
 			} finally {
 				events.close();
@@ -325,7 +270,35 @@ function resolveRun(
 	return run.id;
 }
 
-function dispatchBody(taskId: string, capability: Capability, cfg: OverlayConfig): string {
+/**
+ * Resolve the contract a `--spec` points to, or "" when no spec was given.
+ *
+ * `--spec` is the race-free channel for an agent's contract: its content is
+ * inlined into the dispatch and loaded at launch, unlike a brief mailed *after*
+ * `sling` (which lands only after the agent has read its inbox once and started).
+ * A missing or empty spec is therefore a hard error — launching an agent with a
+ * blank contract makes it fall back to inherited (wrong) branch content.
+ */
+export function readSpecContract(specPath: string | undefined, taskId: string): string {
+	if (!specPath) return "";
+	if (!existsSync(specPath)) {
+		throw new ValidationError(
+			`--spec file not found: ${specPath}. Author it first with \`agentplate spec write ${taskId}\`.`,
+		);
+	}
+	const body = readFileSync(specPath, "utf8");
+	if (body.trim().length === 0) {
+		throw new ValidationError(`--spec file is empty: ${specPath}. The contract would be blank.`);
+	}
+	return body;
+}
+
+export function dispatchBody(
+	taskId: string,
+	capability: Capability,
+	cfg: OverlayConfig,
+	specBody: string,
+): string {
 	const lines = [
 		`You are ${cfg.agentName}, a ${capability} agent.`,
 		`Task: ${taskId}`,
@@ -333,33 +306,16 @@ function dispatchBody(taskId: string, capability: Capability, cfg: OverlayConfig
 		cfg.fileScope.length ? `File scope: ${cfg.fileScope.join(", ")}` : undefined,
 		`Your full instructions are in ${cfg.worktreePath}.`,
 	];
-	return lines.filter(Boolean).join("\n");
+	let body = lines.filter(Boolean).join("\n");
+	// Inline the spec contract so it is in the agent's first prompt — not merely a
+	// path it has to open. This is the in-band contract; do not rely on a later mail.
+	if (specBody.trim()) {
+		body += `\n\n=== SPEC (your contract — work from this, not inherited branch content) ===\n${specBody.trim()}\n=== END SPEC ===`;
+	}
+	return body;
 }
 
 function buildInitialPrompt(injected: string, instructionPath: string): string {
 	const header = `Read your instructions at ${instructionPath}, then begin your task.`;
 	return injected ? `${injected}\n\n${header}` : header;
 }
-
-/** Terminal mail types that mark a capability's work complete. */
-function terminalTypesFor(capability: Capability): string[] {
-	return capability === "merger" ? ["merged", "merge_failed"] : ["worker_done"];
-}
-
-function resolveFinalState(
-	root: string,
-	name: string,
-	capability: Capability,
-	exitCode: number,
-): AgentSession["state"] {
-	const terminal = terminalTypesFor(capability);
-	const store = createMailStore(mailDbPath(root));
-	try {
-		const sent = store.list({ from: name });
-		if (sent.some((m) => terminal.includes(m.type))) return "completed";
-	} finally {
-		store.close();
-	}
-	if (exitCode === 0) return "idle";
-	return "failed";
-}

package/src/commands/spec.test.ts

@@ -0,0 +1,142 @@
+/**
+ * `agentplate spec` command tests.
+ *
+ * Real temp `.agentplate/` tree (no mocks): a real `config.yaml` so
+ * `isInitialized` passes, real filesystem reads/writes. The action functions
+ * resolve the project root via `findProjectRoot()`, which honors
+ * `setProjectRootOverride`, so each test points Agentplate at its own temp root
+ * and drives the exported `run*` functions directly. `resolveSpecBody` takes an
+ * injected stdin reader so the `--stdin` path needs no real pipe.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENTPLATE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CONFIG,
+	serializeConfig,
+	setProjectRootOverride,
+} from "../config.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import { specPath } from "../paths.ts";
+import { resolveSpecBody, runList, runShow, runWrite } from "./spec.ts";
+
+let root: string;
+
+function initRoot(): string {
+	const dir = mkdtempSync(join(tmpdir(), "agentplate-spec-cmd-"));
+	mkdirSync(join(dir, AGENTPLATE_DIR), { recursive: true });
+	writeFileSync(join(dir, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(DEFAULT_CONFIG), "utf8");
+	return dir;
+}
+
+/** Capture everything written to stdout while `fn` runs (awaits async `fn`). */
+async function captureStdout(fn: () => void | Promise<void>): Promise<string> {
+	const original = process.stdout.write.bind(process.stdout);
+	let out = "";
+	process.stdout.write = (chunk: string | Uint8Array): boolean => {
+		out += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		return true;
+	};
+	try {
+		await fn();
+	} finally {
+		process.stdout.write = original;
+	}
+	return out;
+}
+
+/** Run `fn`, capture its stdout, and parse the single JSON envelope it prints. */
+async function captureJson(fn: () => void | Promise<void>): Promise<{ data: unknown }> {
+	return JSON.parse((await captureStdout(fn)).trim());
+}
+
+beforeEach(() => {
+	root = initRoot();
+	setProjectRootOverride(root);
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+});
+
+describe("resolveSpecBody", () => {
+	test("throws when no body source is given", async () => {
+		await expect(resolveSpecBody({})).rejects.toBeInstanceOf(ValidationError);
+	});
+
+	test("throws when more than one source is given", async () => {
+		await expect(resolveSpecBody({ body: "x", stdin: true })).rejects.toBeInstanceOf(
+			ValidationError,
+		);
+	});
+
+	test("returns the inline --body", async () => {
+		expect(await resolveSpecBody({ body: "Goal: ship it" })).toBe("Goal: ship it");
+	});
+
+	test("reads --stdin via the injected reader", async () => {
+		expect(await resolveSpecBody({ stdin: true }, async () => "from stdin")).toBe("from stdin");
+	});
+
+	test("reads --file from disk", async () => {
+		const f = join(root, "contract.md");
+		writeFileSync(f, "Goal: from file", "utf8");
+		expect(await resolveSpecBody({ file: f })).toBe("Goal: from file");
+	});
+
+	test("throws when --file does not exist", async () => {
+		await expect(resolveSpecBody({ file: join(root, "nope.md") })).rejects.toBeInstanceOf(
+			ValidationError,
+		);
+	});
+
+	test("refuses a blank body", async () => {
+		await expect(resolveSpecBody({ body: "   \n  " })).rejects.toBeInstanceOf(ValidationError);
+	});
+});
+
+describe("spec write", () => {
+	test("writes the spec to the canonical path with a trailing newline", async () => {
+		await runWrite("task-a", { body: "Goal: A" }, false);
+		const path = specPath(root, "task-a");
+		expect(existsSync(path)).toBe(true);
+		expect(readFileSync(path, "utf8")).toBe("Goal: A\n");
+	});
+
+	test("reports created then updated, and overwrites content", async () => {
+		const created = await captureJson(() => runWrite("task-b", { body: "v1" }, true));
+		expect((created.data as { action: string }).action).toBe("created");
+		const updated = await captureJson(() => runWrite("task-b", { body: "v2" }, true));
+		expect((updated.data as { action: string }).action).toBe("updated");
+		expect(readFileSync(specPath(root, "task-b"), "utf8")).toBe("v2\n");
+	});
+
+	test("refuses an empty body (never writes a blank contract)", async () => {
+		await expect(runWrite("task-c", { body: "  " }, false)).rejects.toBeInstanceOf(ValidationError);
+		expect(existsSync(specPath(root, "task-c"))).toBe(false);
+	});
+});
+
+describe("spec show / list", () => {
+	test("show throws NotFoundError when the spec is absent", () => {
+		expect(() => runShow("ghost", false)).toThrow(NotFoundError);
+	});
+
+	test("show prints the stored body", async () => {
+		await runWrite("task-d", { body: "Goal: D" }, false);
+		expect(await captureStdout(() => runShow("task-d", false))).toContain("Goal: D");
+	});
+
+	test("list returns every task id that has a spec (json, sorted)", async () => {
+		await runWrite("beta", { body: "b" }, false);
+		await runWrite("alpha", { body: "a" }, false);
+		const out = await captureJson(() => runList(true));
+		const ids = (out.data as Array<{ taskId: string }>).map((r) => r.taskId);
+		expect(ids).toEqual(["alpha", "beta"]);
+	});
+});

package/src/commands/spec.ts

@@ -0,0 +1,192 @@
+/**
+ * `agentplate spec` — author and read the task specs that drive dispatch.
+ *
+ * A spec is the **contract** a dispatcher hands a lead/worker: the per-task WHAT
+ * (goal, scope, constraints, acceptance criteria, the branch to work from, …).
+ * It lives as markdown at `.agentplate/specs/<taskId>.md` and is loaded into the
+ * agent's task **at launch** via `agentplate sling --spec`. This is the only
+ * race-free channel for a contract: mailing a brief after `sling` arrives after
+ * the agent has already read its inbox once and started.
+ *
+ * Authoring a spec is a **dispatch action**, not implementation — it writes a
+ * dispatch input under `.agentplate/specs/`, never the codebase. The coordinator
+ * (which must not touch the work product) uses this freely.
+ *
+ *   write <taskId>   — write/overwrite the spec (body from --stdin | --body | --file)
+ *   show  <taskId>   — print a spec (NotFoundError if absent)
+ *   list             — list task ids that have a spec
+ *   path  <taskId>   — print the resolved spec path (for scripting / --spec)
+ *
+ * `--json` is read via `command.optsWithGlobals().json === true`, matching the
+ * house pattern in `skill.ts` / `mail.ts`.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { Command } from "commander";
+import { findProjectRoot, isInitialized } from "../config.ts";
+import { NotFoundError, ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, muted, printSuccess } from "../logging/color.ts";
+import { specPath, specsDir } from "../paths.ts";
+
+/** Resolve the project root, throwing if Agentplate is not initialized there. */
+function requireInit(): string {
+	const root = findProjectRoot();
+	if (!isInitialized(root)) {
+		throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+	}
+	return root;
+}
+
+/** Read the `--json` global flag off the action's trailing Command instance. */
+function wantsJson(command: Command): boolean {
+	return command.optsWithGlobals().json === true;
+}
+
+interface WriteOptions {
+	stdin?: boolean;
+	body?: string;
+	file?: string;
+	json?: boolean;
+}
+
+/**
+ * Resolve the spec body from exactly one source. Exported for direct unit tests
+ * (so we don't need a real stdin to assert the precedence + validation rules).
+ */
+export async function resolveSpecBody(
+	opts: Pick<WriteOptions, "stdin" | "body" | "file">,
+	readStdin: () => Promise<string> = () => Bun.stdin.text(),
+): Promise<string> {
+	const provided = [opts.stdin === true, opts.body != null, opts.file != null].filter(
+		Boolean,
+	).length;
+	if (provided === 0) {
+		throw new ValidationError(
+			"spec write needs a body: pass one of --stdin, --body <text>, or --file <path>.",
+		);
+	}
+	if (provided > 1) {
+		throw new ValidationError("spec write takes exactly one of --stdin, --body, or --file.");
+	}
+
+	let body: string;
+	if (opts.stdin) body = await readStdin();
+	else if (opts.body != null) body = opts.body;
+	else {
+		const file = opts.file as string;
+		if (!existsSync(file)) throw new ValidationError(`Spec source file not found: ${file}`);
+		body = readFileSync(file, "utf8");
+	}
+
+	if (body.trim().length === 0) {
+		throw new ValidationError("Refusing to write an empty spec — the contract would be blank.");
+	}
+	return body;
+}
+
+export async function runWrite(
+	taskId: string,
+	opts: WriteOptions,
+	useJson: boolean,
+): Promise<void> {
+	const root = requireInit();
+	const body = await resolveSpecBody(opts);
+	const dir = specsDir(root);
+	mkdirSync(dir, { recursive: true });
+	const path = specPath(root, taskId);
+	const existed = existsSync(path);
+	const normalized = body.endsWith("\n") ? body : `${body}\n`;
+	writeFileSync(path, normalized, "utf8");
+
+	if (useJson) jsonOutput({ taskId, path, action: existed ? "updated" : "created" });
+	else printSuccess(`Spec ${existed ? "updated" : "created"}: ${muted(path)}`);
+}
+
+export function runShow(taskId: string, useJson: boolean): void {
+	const root = requireInit();
+	const path = specPath(root, taskId);
+	if (!existsSync(path)) {
+		throw new NotFoundError(`No spec for "${taskId}" (expected ${path}).`);
+	}
+	const body = readFileSync(path, "utf8");
+	if (useJson) jsonOutput({ taskId, path, body });
+	else process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+}
+
+export function runList(useJson: boolean): void {
+	const root = requireInit();
+	const dir = specsDir(root);
+	const taskIds = existsSync(dir)
+		? readdirSync(dir)
+				.filter((f) => f.endsWith(".md"))
+				.map((f) => f.slice(0, -3))
+				.sort()
+		: [];
+	if (useJson) {
+		jsonOutput(taskIds.map((taskId) => ({ taskId, path: specPath(root, taskId) })));
+		return;
+	}
+	if (taskIds.length === 0) {
+		process.stdout.write(`${muted("No specs yet.")}\n`);
+		return;
+	}
+	for (const taskId of taskIds) process.stdout.write(`${brand(taskId)}\n`);
+}
+
+export function runPath(taskId: string, useJson: boolean): void {
+	const root = requireInit();
+	const path = specPath(root, taskId);
+	if (useJson) jsonOutput({ taskId, path });
+	else process.stdout.write(`${path}\n`);
+}
+
+function writeCommand(): Command {
+	return new Command("write")
+		.description("Write (or overwrite) a task spec — the dispatch contract")
+		.argument("<task-id>", "task identifier")
+		.option("--stdin", "read the spec body from stdin")
+		.option("--body <text>", "spec body as an inline string")
+		.option("--file <path>", "read the spec body from a file")
+		.option("--json", "output JSON")
+		.action((taskId: string, opts: WriteOptions, command: Command) =>
+			runWrite(taskId, opts, wantsJson(command)),
+		);
+}
+
+function showCommand(): Command {
+	return new Command("show")
+		.description("Print a task spec")
+		.argument("<task-id>", "task identifier")
+		.option("--json", "output JSON")
+		.action((taskId: string, _opts: { json?: boolean }, command: Command) =>
+			runShow(taskId, wantsJson(command)),
+		);
+}
+
+function listCommand(): Command {
+	return new Command("list")
+		.description("List task ids that have a spec")
+		.option("--json", "output JSON")
+		.action((_opts: { json?: boolean }, command: Command) => runList(wantsJson(command)));
+}
+
+function pathCommand(): Command {
+	return new Command("path")
+		.description("Print the resolved spec path for a task id")
+		.argument("<task-id>", "task identifier")
+		.option("--json", "output JSON")
+		.action((taskId: string, _opts: { json?: boolean }, command: Command) =>
+			runPath(taskId, wantsJson(command)),
+		);
+}
+
+/** Build the `agentplate spec` command tree. */
+export function createSpecCommand(): Command {
+	return new Command("spec")
+		.description("Author and read task specs (the dispatch contract)")
+		.addCommand(writeCommand())
+		.addCommand(showCommand())
+		.addCommand(listCommand())
+		.addCommand(pathCommand());
+}