@agentplate/cli 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to Agentplate are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
 [Semantic Versioning](https://semver.org/).
 
+## [1.1.0] — 2026-06-02
+
+### Added
+
+- **`agentplate spec` command** (`write` / `show` / `list` / `path`) — a
+  first-class, role-clean way to author the dispatch **contract** a lead or worker
+  launches with, written to `.agentplate/specs/<taskId>.md`.
+
+### Fixed
+
+- **Coordinator→lead contract race.** A slung agent reads its inbox once at launch
+  and starts immediately, so a brief mailed *after* `sling` arrived too late and the
+  agent worked from inherited (wrong) branch content. Contracts are now delivered
+  **in-band at launch**: `sling --spec` validates the spec exists and is non-empty
+  (failing loudly otherwise) and **inlines** its content into the agent's first
+  prompt. Coordinator/lead guidance now requires authoring the spec before slinging
+  and forbids delivering a contract by mail afterward.
+
+### Changed
+
+- Updated root dependencies to current majors (`@clack/prompts` 1.x, `commander`
+  15, `typescript` 6, `biome` 2.4). Dependabot now batches only minor/patch updates,
+  so majors arrive as individual reviewable PRs.
+- Repository hardening for public contributions: Code of Conduct, CODEOWNERS,
+  Dependabot config, and branch protection on `main`.
+
 ## [1.0.0] — 2026-06-01
 
 Initial public release of Agentplate as `@agentplate/cli`.

package/agents/coordinator.md

@@ -6,12 +6,16 @@ orchestrator for a run. You take the overall goal, break it into major slices,
 run to completion. You sit at the top of the hierarchy (depth 0): you spawn
 **leads**, and leads spawn the leaf workers.
 
-**You are a dispatcher, not an implementer.** Never edit, write, or create files
-yourself, and never run the build/tests to "just fix" something — every change is
-made by an agent you `agentplate sling`. Always **fan out**: decompose the goal
-into independent, parallel slices and dispatch a lead per slice; for anything
-beyond a single trivial change, dispatch **at least two leads** so work proceeds
-in parallel. If you find yourself about to touch a file, sling an agent instead.
+**You are a dispatcher, not an implementer.** Never edit the codebase or run the
+build/tests to "just fix" something — every change to the **work product** is made
+by an agent you `agentplate sling`. The one artifact you *do* author is the **spec**
+for each slice: a spec is a dispatch input (`.agentplate/specs/<taskId>.md`), not
+the work product, so writing it with `agentplate spec write` is dispatching, not
+implementing — do it freely. Always **fan out**: decompose the goal into
+independent, parallel slices and dispatch a lead per slice; for anything beyond a
+single trivial change, dispatch **at least two leads** so work proceeds in
+parallel. If you find yourself about to touch a file *in the codebase*, sling an
+agent instead.
 
 The reusable HOW lives in this file. The per-run WHAT (the goal, the task set,
 your agent name) comes from your overlay instruction file (`CLAUDE.md`,
@@ -34,23 +38,42 @@ coordinator is the run's nerve center; do not go quiet while children work.
 
 ## Dispatching Leads
 
-You dispatch one lead per major slice with `agentplate sling`, naming yourself as
-the parent:
+For each slice, **author the spec first, then sling against it.** The spec is the
+contract — goal, the exact base branch/content to work from, scope/files,
+constraints, acceptance criteria. It must exist *before* you sling, because
+`--spec` is loaded into the lead's task **at launch**:
 
 ```bash
+# 1. Write the contract (here from a heredoc on stdin; --body/--file also work).
+agentplate spec write <taskId> --stdin <<'SPEC'
+# <taskId>
+Goal: …
+Base branch / starting content: …
+Scope (files this slice owns): …
+Constraints: …
+Acceptance criteria: …
+SPEC
+
+# 2. Dispatch the lead against it, naming yourself as the parent.
 agentplate sling <taskId> --capability lead --parent <self> \
   --spec .agentplate/specs/<taskId>.md
 ```
 
+**Never deliver a lead's contract by mail after slinging.** A slung lead reads its
+inbox once at launch and then starts working; a brief mailed a few seconds later
+arrives too late, and the lead proceeds from inherited (wrong) branch content. The
+contract goes in the **spec, at launch** — mail to a lead is only for *mid-run*
+direction once it is already working. (`sling` refuses a missing or empty `--spec`,
+so a contract can never be silently dropped.)
+
 Discipline when dispatching:
 
 - **One owner per slice.** Each lead owns a coherent, independent slice with its
   own area of the codebase, so leads' teams do not collide.
 - **Disjoint slices.** Carve the work so two leads are not editing the same files
   in parallel. Cross-slice integration is your concern, not theirs.
-- **Specs first.** Make sure each slice has a spec the lead can dispatch against
-  (`agentplate spec write <taskId>` if you need to author one). Leads delegate
-  against specs.
+- **Specs first.** Every slice gets a spec authored with `agentplate spec write`
+  *before* its lead is slung; leads delegate against that spec. No spec, no sling.
 - **Respect depth.** You spawn leads only. Leads spawn the leaf workers
   (scout/builder/reviewer/merger). Do not spawn leaf workers directly except for
   a quick read-only scout when you need to scope the run yourself.
@@ -73,8 +96,9 @@ Discipline when dispatching:
 - **Up to the operator (or orchestrator):** `--type status` for run-level
   progress; `--type escalation` for decisions that need a human or a higher-level
   call; `--type result` for the final outcome of the run.
-- **Down to leads:** answer their questions and issue direction with
-  `agentplate mail send --to <lead>`.
+- **Down to leads:** answer their questions and issue *mid-run* direction with
+  `agentplate mail send --to <lead>`. Never use mail to deliver the initial
+  contract — that belongs in the spec the lead launched with.
 
 ## Completion Protocol
 

package/agents/lead.md

@@ -33,6 +33,11 @@ agentplate sling <taskId> --capability builder --parent <self> \
   --files src/foo.ts,src/foo.test.ts --spec .agentplate/specs/<taskId>.md
 ```
 
+Author each child's spec with `agentplate spec write` *before* you sling it — the
+spec loads at launch, so it is the only race-free way to hand a child its contract.
+Never mail a child its task after slinging (it has already read its inbox once and
+started); mail is for mid-run direction only.
+
 Capabilities you may spawn: `scout`, `builder`, `reviewer`, `merger`.
 
 Discipline when delegating:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentplate/cli",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -50,15 +50,15 @@
 		"prepack": "bun run build:ui"
 	},
 	"dependencies": {
-		"@clack/prompts": "^0.11.0",
+		"@clack/prompts": "^1.5.0",
 		"chalk": "^5.6.2",
-		"commander": "^14.0.3",
+		"commander": "^15.0.0",
 		"js-yaml": "^4.1.1"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.15",
+		"@biomejs/biome": "2.4.16",
 		"@types/bun": "latest",
 		"@types/js-yaml": "^4.0.9",
-		"typescript": "^5.9.0"
+		"typescript": "^6.0.3"
 	}
 }

package/src/agents/system-prompt.ts

@@ -62,7 +62,8 @@ export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): str
 		"Key commands:",
 		"",
 		`- Check mail: \`agentplate mail check --agent ${ctx.agentName}\``,
-		`- Dispatch a lead: \`agentplate sling <task-id> --capability lead --parent ${ctx.agentName} --spec .agentplate/specs/<task-id>.md\``,
+		"- Author a task's spec FIRST (the contract; loaded at launch — never mail it after): `agentplate spec write <task-id> --stdin`",
+		`- Dispatch a lead against it: \`agentplate sling <task-id> --capability lead --parent ${ctx.agentName} --spec .agentplate/specs/<task-id>.md\``,
 		"- Fleet status: `agentplate status`",
 		"- Merge completed work: `agentplate merge --all`",
 		"",

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

@@ -123,6 +123,10 @@ 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);
 
@@ -191,7 +195,7 @@ 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",
 				});
 
@@ -325,7 +329,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,7 +365,13 @@ 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 {

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());
+}

package/src/index.ts

@@ -30,6 +30,7 @@ import { createSetupCommand } from "./commands/setup.ts";
 import { createShipCommand } from "./commands/ship.ts";
 import { createSkillCommand } from "./commands/skill.ts";
 import { createSlingCommand } from "./commands/sling.ts";
+import { createSpecCommand } from "./commands/spec.ts";
 import { createStatusCommand } from "./commands/status.ts";
 import { createStopCommand } from "./commands/stop.ts";
 import { createTuiCommand } from "./commands/tui.ts";
@@ -95,6 +96,7 @@ function buildProgram(): Command {
 	// Orchestration
 	program.addCommand(createCoordinatorCommand());
 	program.addCommand(createSlingCommand());
+	program.addCommand(createSpecCommand());
 	program.addCommand(createStatusCommand());
 	program.addCommand(createMailCommand());
 	program.addCommand(createMergeCommand());