@agentplate/cli 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.2.0] — 2026-06-02
+
+### Added
+
+- **Auto-merge** (`merge.autoMerge`: `off` / `on-gates-pass` / `on-complete`,
+  default `off`). When enabled, a completed worker's branch lands on the canonical
+  branch automatically (queue + lock + tiered resolve), reporting `merged` /
+  `merge_failed` mail. Configured in `ap setup`.
+- **`agentplate turn <agent>`** — runs the next turn for an idle agent, **resuming**
+  the runtime session (warm start) instead of cold-starting. The shared `driveTurn`
+  core backs both the first turn (`sling`) and follow-ups.
+- **Per-capability model tiering** — `providers[id].models` lets a faster/cheaper
+  model drive read-only roles (scout, reviewer) while the strong model handles the
+  rest. Optional prompt in `ap setup`.
+- **Quality-gates prompt in `ap setup`** — detected from `package.json` scripts.
+
+### Changed
+
+- **Quality gates run concurrently** (was sequential); the outcome is reused for
+  both skill distillation and auto-merge.
+- **Orchestration limits are now enforced.** `agents.maxConcurrent`,
+  `maxAgentsPerLead`, and `maxDepth` were validated but ignored; `sling` now
+  refuses a spawn that would exceed them with a typed `CapacityError`.
+
+## [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.
@@ -67,14 +90,21 @@ Discipline when dispatching:
   if integration itself is non-trivial.
 - Re-dispatch on failure: if a lead escalates something it cannot finish, decide
   whether to re-scope and re-dispatch, or escalate to the operator.
+- Auto-merge (when `merge.autoMerge` is enabled in config): a worker's branch
+  lands on the canonical branch automatically when it finishes, and you receive a
+  `merged` or `merge_failed` mail per landing. You do **not** run `agentplate merge`
+  for those slices — just act on `merge_failed` (re-dispatch a merger or resolve),
+  and still own cross-slice integration. When auto-merge is `off` (the default),
+  you drive merges yourself as below.
 
 ## Communication Protocol
 
 - **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:
@@ -45,7 +50,9 @@ Discipline when delegating:
   merge — unless your overlay says `--skip-review`.
 - **Respect the budget.** Do not exceed your `max-agents` ceiling or the
   configured depth limit. You are an internal node; your children are leaves and
-  cannot spawn further.
+  cannot spawn further. These limits are now **enforced**: a `sling` that would
+  exceed `agents.maxConcurrent`, `agents.maxAgentsPerLead`, or `agents.maxDepth`
+  is refused with a capacity error — wait for a child to finish, then retry.
 
 ## Coordinating Children
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentplate/cli",
-	"version": "1.0.0",
+	"version": "1.2.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/capacity.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for assertCapacity — the spawn-time orchestration limit gate.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CapacityError } from "../errors.ts";
+import { assertCapacity, type CapacityCheck } from "./capacity.ts";
+
+const base: CapacityCheck = {
+	depth: 1,
+	active: 0,
+	parentAgent: "lead-1",
+	parentActiveChildren: 0,
+	limits: { maxDepth: 2, maxConcurrent: 10, maxAgentsPerLead: 5 },
+};
+
+describe("assertCapacity", () => {
+	test("passes when under every limit", () => {
+		expect(() => assertCapacity(base)).not.toThrow();
+	});
+
+	test("refuses when depth exceeds maxDepth", () => {
+		expect(() => assertCapacity({ ...base, depth: 3 })).toThrow(CapacityError);
+	});
+
+	test("allows depth exactly at maxDepth", () => {
+		expect(() => assertCapacity({ ...base, depth: 2 })).not.toThrow();
+	});
+
+	test("refuses when active is at maxConcurrent", () => {
+		expect(() => assertCapacity({ ...base, active: 10 })).toThrow(CapacityError);
+		// one below the cap is still allowed
+		expect(() => assertCapacity({ ...base, active: 9 })).not.toThrow();
+	});
+
+	test("refuses when the parent is at maxAgentsPerLead", () => {
+		expect(() => assertCapacity({ ...base, parentActiveChildren: 5 })).toThrow(CapacityError);
+	});
+
+	test("ignores the per-lead cap for a top-level spawn (no parent)", () => {
+		expect(() =>
+			assertCapacity({ ...base, parentAgent: null, parentActiveChildren: 99 }),
+		).not.toThrow();
+	});
+
+	test("the error is a CapacityError with the CAPACITY_EXCEEDED code", () => {
+		try {
+			assertCapacity({ ...base, active: 10 });
+			throw new Error("expected to throw");
+		} catch (e) {
+			expect(e).toBeInstanceOf(CapacityError);
+			expect((e as CapacityError).code).toBe("CAPACITY_EXCEEDED");
+		}
+	});
+});

package/src/agents/capacity.ts

@@ -0,0 +1,50 @@
+/**
+ * Orchestration capacity limits — enforced at spawn time.
+ *
+ * `agents.maxConcurrent`, `agents.maxAgentsPerLead`, and `agents.maxDepth` are
+ * configured (and validated) but were previously decorative — nothing consulted
+ * them. {@link assertCapacity} is the single gate `sling` calls before creating a
+ * worktree, so a runaway fan-out is refused with a typed {@link CapacityError}
+ * rather than spawning unbounded agents.
+ *
+ * Pure (counts are passed in) so it is unit-tested without a session store.
+ */
+
+import { CapacityError } from "../errors.ts";
+
+export interface CapacityLimits {
+	maxDepth: number;
+	maxConcurrent: number;
+	maxAgentsPerLead: number;
+}
+
+export interface CapacityCheck {
+	/** Depth the new agent would occupy. */
+	depth: number;
+	/** Active agents in the run right now (excluding the one being spawned). */
+	active: number;
+	/** Spawning parent, or null for a top-level spawn. */
+	parentAgent: string | null;
+	/** Active children the parent already has (ignored when parentAgent is null). */
+	parentActiveChildren: number;
+	limits: CapacityLimits;
+}
+
+/** Throw {@link CapacityError} if spawning would exceed any configured limit. */
+export function assertCapacity(c: CapacityCheck): void {
+	if (c.depth > c.limits.maxDepth) {
+		throw new CapacityError(
+			`Cannot spawn at depth ${c.depth}: exceeds agents.maxDepth (${c.limits.maxDepth}).`,
+		);
+	}
+	if (c.active >= c.limits.maxConcurrent) {
+		throw new CapacityError(
+			`Cannot spawn: ${c.active} agent(s) already active, at agents.maxConcurrent (${c.limits.maxConcurrent}). Wait for some to finish.`,
+		);
+	}
+	if (c.parentAgent && c.parentActiveChildren >= c.limits.maxAgentsPerLead) {
+		throw new CapacityError(
+			`Cannot spawn: ${c.parentAgent} already has ${c.parentActiveChildren} active child(ren), at agents.maxAgentsPerLead (${c.limits.maxAgentsPerLead}).`,
+		);
+	}
+}

package/src/agents/drive.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for driveTurn — the shared turn core. Real stores + a real (mock) runtime
+ * subprocess. A SpyRuntime records the DirectSpawnOpts so we can prove the warm
+ * start: a follow-up turn threads `resumeSessionId` through to the runtime.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "../config.ts";
+import { createEventStore, type EventStore } from "../events/store.ts";
+import { createMailClient, type MailClient } from "../mail/client.ts";
+import { eventsDbPath, sessionsDbPath } from "../paths.ts";
+import { MockRuntime } from "../runtimes/mock.ts";
+import type { DirectSpawnOpts } from "../runtimes/types.ts";
+import { createSessionStore, type SessionStore } from "../sessions/store.ts";
+import type { AgentplateConfig, AgentSession } from "../types.ts";
+import { driveTurn } from "./drive.ts";
+
+/** Mock runtime that records the spawn opts (so we can assert the resume id). */
+class SpyRuntime extends MockRuntime {
+	lastOpts: DirectSpawnOpts | null = null;
+	override buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		this.lastOpts = opts;
+		return super.buildDirectSpawn(opts);
+	}
+}
+
+let root: string;
+let worktree: string;
+let store: SessionStore;
+let events: EventStore;
+let mail: MailClient;
+
+function cfg(): AgentplateConfig {
+	const c = structuredClone(DEFAULT_CONFIG);
+	c.project.root = root;
+	c.project.canonicalBranch = "main";
+	return c;
+}
+
+function makeSession(over: Partial<AgentSession> = {}): AgentSession {
+	const now = new Date().toISOString();
+	return {
+		id: `session-${crypto.randomUUID()}`,
+		agentName: "builder-1",
+		capability: "builder",
+		taskId: "task-1",
+		runId: "run-1",
+		worktreePath: worktree,
+		branchName: "agentplate/builder-1",
+		state: "idle",
+		parentAgent: "lead-1",
+		depth: 1,
+		pid: null,
+		runtimeSessionId: null,
+		startedAt: now,
+		lastActivity: now,
+		...over,
+	};
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-drive-"));
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+	worktree = mkdtempSync(join(tmpdir(), "agentplate-drive-wt-"));
+	store = createSessionStore(sessionsDbPath(root));
+	events = createEventStore(eventsDbPath(root));
+	mail = createMailClient(root);
+	process.env.AGENTPLATE_MOCK_CMD = "true"; // no-op turn, exits 0
+});
+
+afterEach(() => {
+	store.close();
+	events.close();
+	mail.close();
+	rmSync(root, { recursive: true, force: true });
+	rmSync(worktree, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("driveTurn — warm start", () => {
+	test("threads resumeSessionId through to the runtime spawn (follow-up turn)", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		const runtime = new SpyRuntime();
+
+		const out = await driveTurn({
+			root,
+			config: cfg(),
+			runtime,
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "continue",
+			resumeSessionId: "sess-abc",
+		});
+
+		expect(runtime.lastOpts?.resumeSessionId).toBe("sess-abc"); // warm start
+		expect(out.finalState).toBe("idle"); // no terminal mail emitted → paused
+		expect(store.getSession(session.id)?.state).toBe("idle");
+	});
+
+	test("omits resume on the first turn (cold start)", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		const runtime = new SpyRuntime();
+		await driveTurn({
+			root,
+			config: cfg(),
+			runtime,
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "begin",
+		});
+		expect(runtime.lastOpts?.resumeSessionId).toBeUndefined();
+	});
+});
+
+describe("driveTurn — state transition", () => {
+	test("becomes 'completed' when the agent has emitted its terminal mail", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		// The agent's own worker_done mail marks the task complete.
+		mail.send({
+			from: session.agentName,
+			to: "lead-1",
+			subject: "done",
+			body: "",
+			type: "worker_done",
+		});
+
+		const config = cfg();
+		config.skills.enabled = false; // keep the completed path free of distillation work
+		const out = await driveTurn({
+			root,
+			config,
+			runtime: new SpyRuntime(),
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "finish",
+		});
+		expect(out.finalState).toBe("completed");
+		expect(store.getSession(session.id)?.state).toBe("completed");
+	});
+});

package/src/agents/drive.ts

@@ -0,0 +1,200 @@
+/**
+ * driveTurn — run ONE headless turn for an agent and handle its aftermath.
+ *
+ * This is the shared core behind both the first turn (`sling`, which opens a
+ * fresh runtime session) and every follow-up turn (`agentplate turn`, which
+ * **resumes** the session via `runtimeSessionId` so turns 2+ do not pay the
+ * runtime's cold-start cost — the "warm start"). Keeping it in one place means
+ * the post-turn handling (state transition, the self-improving skills loop, and
+ * auto-merge) is identical no matter which turn it is.
+ *
+ * Spawn-per-turn is preserved: each call spawns a fresh runtime subprocess
+ * (resumed when `resumeSessionId` is given) — there is no long-lived agent.
+ */
+
+import type { EventStore } from "../events/store.ts";
+import { runQualityGates } from "../insights/quality-gates.ts";
+import type { MailClient } from "../mail/client.ts";
+import { createMailStore } from "../mail/store.ts";
+import { maybeAutoMerge } from "../merge/auto.ts";
+import { mailDbPath } from "../paths.ts";
+import type { AgentRuntime } from "../runtimes/types.ts";
+import type { SessionStore } from "../sessions/store.ts";
+import { runSkillFeedbackAndDistill } from "../skills/lifecycle.ts";
+import type {
+	AgentplateConfig,
+	AgentSession,
+	Capability,
+	OutcomeStatus,
+	ResolvedModel,
+	SessionState,
+} from "../types.ts";
+import { updateIdentity } from "./identity.ts";
+import { runTurn } from "./turn-runner.ts";
+
+/** Terminal mail types whose presence marks a capability's work complete. */
+export function terminalTypesFor(capability: Capability): string[] {
+	return capability === "merger" ? ["merged", "merge_failed"] : ["worker_done"];
+}
+
+/**
+ * Resolve a turn's end state from the agent's own mail + exit code:
+ * - emitted terminal mail → `completed`
+ * - clean exit, no terminal mail → `idle` (paused, awaiting its next turn)
+ * - non-zero exit → `failed`
+ */
+export function resolveFinalState(
+	root: string,
+	name: string,
+	capability: Capability,
+	exitCode: number,
+): SessionState {
+	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();
+	}
+	return exitCode === 0 ? "idle" : "failed";
+}
+
+export interface DriveTurnCtx {
+	root: string;
+	config: AgentplateConfig;
+	runtime: AgentRuntime;
+	store: SessionStore;
+	events: EventStore;
+	mail: MailClient;
+	/** The session this turn runs for (existing or just-created). */
+	session: AgentSession;
+	/** Resolved concrete model + provider env for this capability. */
+	model: ResolvedModel;
+	/** The user-turn text (dispatch / injected mail / nudge). */
+	prompt: string;
+	/** Prior runtime session id to resume — omit on the first turn (warm start). */
+	resumeSessionId?: string;
+}
+
+export interface DriveTurnResult {
+	finalState: SessionState;
+	exitCode: number;
+	gateStatus: OutcomeStatus | null;
+}
+
+/** Run one turn for `ctx.session` and apply the post-turn lifecycle. */
+export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
+	const { root, config, runtime, store, events, mail, session, model } = ctx;
+	const {
+		id: sessionId,
+		agentName: name,
+		capability,
+		taskId,
+		runId,
+		worktreePath,
+		branchName,
+	} = session;
+
+	store.updateSessionState(sessionId, "working");
+
+	let sawError = false;
+	const turn = await runTurn({
+		runtime,
+		worktreePath,
+		model: model.model,
+		prompt: ctx.prompt,
+		env: model.env,
+		resumeSessionId: ctx.resumeSessionId,
+		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(sessionId);
+		},
+	});
+	if (turn.runtimeSessionId) store.setRuntimeSessionId(sessionId, turn.runtimeSessionId);
+
+	// A non-zero exit with no error event means the runtime failed via stderr;
+	// record it so the failure reason is visible 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,
+			});
+		}
+	}
+
+	const finalState = resolveFinalState(root, name, capability, turn.exitCode);
+	store.updateSessionState(sessionId, finalState);
+	store.touch(sessionId);
+	updateIdentity(root, name, {
+		taskId,
+		summary: `${capability} ran a turn for ${taskId} → ${finalState}`,
+	});
+
+	// Quality gates run once when EITHER the self-improving loop or auto-merge
+	// needs them; the outcome feeds both. Best-effort — never fails the turn.
+	const autoMergeWants =
+		config.merge.autoMerge !== "off" && capability !== "scout" && capability !== "merger";
+	let gateStatus: OutcomeStatus | null = null;
+	if (finalState === "completed" && (config.skills.enabled || autoMergeWants)) {
+		try {
+			const gateOutcome = await runQualityGates(config.project.qualityGates ?? [], worktreePath);
+			gateStatus = gateOutcome?.status ?? null;
+			if (config.skills.enabled) {
+				await runSkillFeedbackAndDistill({
+					root,
+					agentName: name,
+					capability,
+					taskId,
+					worktreePath,
+					baseRef: config.project.canonicalBranch,
+					runtime,
+					outcomeStatus: gateStatus,
+					skills: config.skills,
+					model: model.model,
+				});
+			}
+		} catch {
+			// Skill loop is advisory; a failure here must not fail the turn.
+		}
+	}
+
+	// Auto-merge the branch onto the canonical branch when configured (off by
+	// default). Best-effort — a landing must never fail the turn.
+	if (finalState === "completed") {
+		try {
+			await maybeAutoMerge({
+				root,
+				branchName,
+				targetBranch: config.project.canonicalBranch,
+				capability,
+				agentName: name,
+				taskId,
+				parent: session.parentAgent,
+				mode: config.merge.autoMerge,
+				aiResolveEnabled: config.merge.aiResolveEnabled,
+				gateStatus,
+				mail,
+			});
+		} catch {
+			// Auto-merge is best-effort; never fail the turn over a landing.
+		}
+	}
+
+	return { finalState, exitCode: turn.exitCode, gateStatus };
+}

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`",
 		"",