kanbot 0.3.0 → 0.4.0

package/README.md

@@ -52,14 +52,13 @@ For a guided setup, run `bunx kanbot skills install` and ask your agent "help me
 
 ## Labels
 
-| Label                                 | Meaning                                           |
-| ------------------------------------- | ------------------------------------------------- |
-| `technical`                           | Plan as a technical goal, not a user story        |
-| `type:frontend\|backend\|docs\|infra` | Picks the implementer agent (the planner sets it) |
-| `explore:2..4`                        | Build N alternative approaches as N PRs           |
-| `agent-reviewed`                      | Passed agent review; ready for you                |
-| `needs-human`                         | Agents gave up. Remove it to retry.               |
-| `kanbot-review`                       | Agent review for your own PR, without a card      |
+| Label            | Meaning                                      |
+| ---------------- | -------------------------------------------- |
+| `technical`      | Plan as a technical goal, not a user story   |
+| `explore:2..4`   | Build N alternative approaches as N PRs      |
+| `agent-reviewed` | Passed agent review; ready for you           |
+| `needs-human`    | Agents gave up. Remove it to retry.          |
+| `kanbot-review`  | Agent review for your own PR, without a card |
 
 ## Beyond the board
 
@@ -73,6 +72,7 @@ For a guided setup, run `bunx kanbot skills install` and ask your agent "help me
 - `.kanbot/config.yml`: concurrency, timeouts, notifications, column names.
 - `.kanbot/agents/*.md`: agent definitions. Run `kanbot sync` after editing; don't edit the generated `.claude/` or `.codex/` files.
 - `.agents/skills/`: skills shared by agents. Fill in `project-conventions` first.
+- `capabilities` in config: your own skills and agents for building, testing and reviewing. [More](./docs/13-capabilities.md)
 
 ## Upgrading
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kanbot",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Run an autonomous dev team (Claude Code or Codex) from a GitHub Project board",
 	"type": "module",
 	"license": "MIT",

package/schema/config.schema.json

@@ -126,14 +126,7 @@
 			}
 		},
 		"implementers": {
-			"default": {
-				"frontend": "implementer-frontend",
-				"backend": "implementer-backend",
-				"docs": "implementer-docs",
-				"infra": "implementer-technical",
-				"default": "implementer-backend"
-			},
-			"description": "Maps a type:<key> label to an agent. `default` is the fallback.",
+			"description": "Deprecated: implement always uses `implementer`. While set, maps a type:<key> label to an agent, with `default` as the fallback. Use capabilities instead.",
 			"type": "object",
 			"propertyNames": {
 				"type": "string"
@@ -142,6 +135,43 @@
 				"type": "string"
 			}
 		},
+		"capabilities": {
+			"description": "Needs mapped to the repo's own skills or agents. Reserved: verify (prove acceptance criteria), review (technical review), preview (something a human can try). Other names are yours.",
+			"type": "object",
+			"propertyNames": {
+				"type": "string",
+				"pattern": "^[a-z][a-z0-9-]*$"
+			},
+			"additionalProperties": {
+				"anyOf": [
+					{
+						"type": "string",
+						"minLength": 1,
+						"description": "Skill or agent name, short for `{ use: <name> }`."
+					},
+					{
+						"type": "object",
+						"properties": {
+							"use": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Skill in .agents/skills or agent in .kanbot/agents that does the work."
+							},
+							"when": {
+								"description": "When it applies, e.g. `Changes to UI users see`.",
+								"type": "string"
+							},
+							"required": {
+								"default": false,
+								"description": "A miss when it applies blocks acceptance review.",
+								"type": "boolean"
+							}
+						},
+						"required": ["use"]
+					}
+				]
+			}
+		},
 		"review": {
 			"default": {},
 			"type": "object",

package/src/agents/load.ts

@@ -63,6 +63,17 @@ export async function loadAgents(root: string): Promise<AgentDef[]> {
 	return agents;
 }
 
+/** `agent: skill` for each skill an agent lists that has no .agents/skills/<skill>/SKILL.md. */
+export function missingSkills(root: string, agents: AgentDef[]): string[] {
+	return agents.flatMap((a) =>
+		a.skills
+			.filter(
+				(s) => !existsSync(join(root, ".agents", "skills", s, "SKILL.md")),
+			)
+			.map((s) => `${a.name}: ${s}`),
+	);
+}
+
 function validate(agents: AgentDef[]) {
 	const names = new Set(agents.map((a) => a.name));
 	if (names.size !== agents.length) {

package/src/agents/sync.ts

@@ -42,7 +42,7 @@ export const CLAUDE_ATTRIBUTION = {
 export function claudeTools(agent: AgentDef): string[] {
 	const tools = agent.tools.flatMap((t) => CLAUDE_TOOLS[t] ?? []);
 	if (agent.skills.length) tools.push("Skill");
-	if (agent.subagents.length) tools.push("Task");
+	if (agent.subagents.length) tools.push("Agent");
 	return [...new Set(tools)];
 }
 
@@ -118,14 +118,14 @@ export type SyncFile = { path: string; content: string };
 const COPILOT_INSTRUCTIONS = join(".github", "copilot-instructions.md");
 
 /** Points Copilot code review at the same rules the kanbot reviewers use. */
-export const renderCopilotInstructions =
-	() => `<!-- generated by kanbot from review.copilot in .kanbot/config.yml -->
+export const renderCopilotInstructions = (review?: string) =>
+	`<!-- generated by kanbot from review.copilot in .kanbot/config.yml -->
 
 # Code review
 
 AI agents write most changes in this repo, from a plan in the linked issue. When you review a pull request:
 
-- Use the checklist and severity rubric in \`.agents/skills/code-review/SKILL.md\`.
+- Use the severity rubric and finding format in \`.agents/skills/review-findings/SKILL.md\`.${review ? `\n- Review the way the repo's \`review\` capability does: \`${review}\` in \`.agents/skills/\` or \`.kanbot/agents/\`.` : ""}
 - Check the change against the plan in the linked issue and the PR description.
 - Hold it to \`AGENTS.md\`, \`.agents/skills/project-conventions/SKILL.md\` and the facts in \`.agents/skills/project-memory/\`.
 - Comment on real problems: bugs, missing tests, security, broken conventions. Leave style to the linter.
@@ -155,12 +155,12 @@ export async function sync(
 	{ check = false } = {},
 ): Promise<string[]> {
 	const files = renderAll(agents);
-	const copilot =
-		existsSync(configPath(root)) && (await loadConfig(root)).review.copilot;
-	if (copilot)
+	const config = existsSync(configPath(root)) ? await loadConfig(root) : null;
+	const copilot = config?.review.copilot ?? false;
+	if (config && copilot)
 		files.push({
 			path: COPILOT_INSTRUCTIONS,
-			content: renderCopilotInstructions(),
+			content: renderCopilotInstructions(config.capabilities.review?.use),
 		});
 	const changed: string[] = [];
 	for (const f of files) {

package/src/capabilities.ts

@@ -0,0 +1,157 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { AgentDef } from "./agents/load.ts";
+import type { Config, RESERVED_CAPABILITIES } from "./config.ts";
+import { TEMPLATES } from "./templates.ts";
+
+export type Capabilities = Config["capabilities"];
+
+/** Where a capability's `use` lives. `claude`/`codex` agents work on one provider only. */
+export type CapabilitySource = "skill" | "agent" | "claude" | "codex";
+
+export function findCapability(
+	root: string,
+	agents: AgentDef[],
+	use: string,
+): CapabilitySource | null {
+	if (existsSync(join(root, ".agents", "skills", use, "SKILL.md")))
+		return "skill";
+	if (agents.some((a) => a.name === use)) return "agent";
+	if (existsSync(join(root, ".claude", "agents", `${use}.md`))) return "claude";
+	if (existsSync(join(root, ".codex", "agents", `${use}.toml`))) return "codex";
+	return null;
+}
+
+/** Prompt section listing the repo's capabilities. Empty when none are mapped. */
+export function capabilitiesSection(caps: Capabilities, extra = ""): string {
+	const rows = Object.entries(caps);
+	if (!rows.length) return "";
+	const cell = (s: string) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+	return [
+		"## Capabilities",
+		`The repo maps these needs to its own skills or agents. Use one when its "when" fits the task. Required ones must be used when they apply. For needs not listed, decide yourself.${extra ? ` ${extra}` : ""}`,
+		"",
+		"| Name | When | Use | Required |",
+		"| --- | --- | --- | --- |",
+		...rows.map(
+			([name, c]) =>
+				`| ${name} | ${cell(c.when ?? "When it fits the task")} | \`${c.use}\` | ${c.required ? "yes" : "no"} |`,
+		),
+	].join("\n");
+}
+
+/** Craft skills earlier kanbot versions installed, and the capability each maps to. */
+const LEGACY: [name: string, use: string, when?: string][] = [
+	["verify", "verify-ui", "Changes to UI users see"],
+	["review", "code-review"],
+	["tdd", "tdd", "Writing or changing behaviour"],
+	["ui-design", "frontend-design", "Building or restyling UI"],
+	["accessibility", "accessibility", "Changes to UI users see"],
+];
+
+/**
+ * A capabilities block for craft skills an earlier kanbot installed, so
+ * upgrades keep using them. Null when config already maps capabilities or
+ * none of them are present.
+ */
+export function legacyCapabilities(
+	root: string,
+	current: Capabilities,
+): Capabilities | null {
+	if (Object.keys(current).length) return null;
+	const found = LEGACY.filter(([, use]) =>
+		existsSync(join(root, ".agents", "skills", use, "SKILL.md")),
+	);
+	if (!found.length) return null;
+	return Object.fromEntries(
+		found.map(([name, use, when]) => [
+			name,
+			{ use, ...(when ? { when } : {}), required: false },
+		]),
+	);
+}
+
+export const RESERVED: Record<(typeof RESERVED_CAPABILITIES)[number], string> =
+	{
+		verify: "prove acceptance criteria",
+		review: "technical review",
+		preview: "something a human can try",
+	};
+
+/** Skills and agents in the repo that kanbot didn't ship. */
+export async function ownWorkers(root: string): Promise<string[]> {
+	const list = async (dir: string, ext?: string) =>
+		existsSync(dir)
+			? (await readdir(dir, { withFileTypes: true }))
+					.filter((e) => (ext ? e.name.endsWith(ext) : e.isDirectory()))
+					.map((e) => (ext ? e.name.slice(0, -ext.length) : e.name))
+			: [];
+	const shipped = new Set([
+		...(await list(join(TEMPLATES, ".agents", "skills"))),
+		...(await list(join(TEMPLATES, ".kanbot", "agents"), ".md")),
+	]);
+	const all = [
+		...(await list(join(root, ".agents", "skills"))),
+		...(await list(join(root, ".kanbot", "agents"), ".md")),
+	];
+	return [...new Set(all)].filter((n) => !shipped.has(n)).sort();
+}
+
+/**
+ * Asks which of the repo's own skills or agents fill each reserved need.
+ * `ask` returns the answer, or null/empty to skip.
+ */
+export function askCapabilities(
+	workers: string[],
+	ask: (question: string) => string | null,
+	say: (line: string) => void = console.log,
+): Capabilities {
+	const caps: Capabilities = {};
+	if (!workers.length) return caps;
+	say(
+		`Your skills and agents:\n${workers.map((w, i) => `  ${i + 1}. ${w}`).join("\n")}`,
+	);
+	const yes = ask("Map them to kanbot capabilities now? [y/N]");
+	if (!/^y/i.test(yes?.trim() ?? "")) return caps;
+	for (const [name, what] of Object.entries(RESERVED)) {
+		const answer = ask(
+			`${name} (${what}): number or name, Enter to skip`,
+		)?.trim();
+		if (!answer) continue;
+		const use = workers[Number(answer) - 1] ?? answer;
+		if (workers.includes(use)) caps[name] = { use, required: false };
+		else say(`  "${answer}" not found, skipped ${name}.`);
+	}
+	return caps;
+}
+
+/** One line: what is mapped, and which reserved needs aren't. */
+export function capabilitySummary(caps: Capabilities): string {
+	const mapped = Object.entries(caps).map(([n, c]) => `${n} → ${c.use}`);
+	const missing = Object.keys(RESERVED).filter((n) => !caps[n]);
+	return [
+		mapped.join(", ") || "none mapped",
+		missing.length
+			? `could add ${missing.join(", ")} (kanbot-guide can help)`
+			: "",
+	]
+		.filter(Boolean)
+		.join("; ");
+}
+
+/** Capabilities as written to config: a bare name when that says it all. */
+export function compact(caps: Capabilities) {
+	return Object.fromEntries(
+		Object.entries(caps).map(([name, c]) => [
+			name,
+			!c.when && !c.required
+				? c.use
+				: {
+						use: c.use,
+						...(c.when ? { when: c.when } : {}),
+						...(c.required ? { required: true } : {}),
+					},
+		]),
+	);
+}

package/src/commands/board.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { LABELS, loadConfig, saveConfig } from "../config.ts";
+import { UserError } from "../errors.ts";
 import { ensureCopilotRuleset, ensureLabel } from "../github/api.ts";
 import { Gh } from "../github/gh.ts";
 import { createBoard, loadBoard, missingColumns } from "../github/project.ts";
@@ -12,10 +13,6 @@ export const REPO_LABELS: [name: string, color: string, description: string][] =
 			"5319e7",
 			"Technical work; planned as a technical goal instead of a user story",
 		],
-		["type:frontend", "1d76db", "User-facing UI work"],
-		["type:backend", "0e8a16", "Server, data or API work"],
-		["type:docs", "c5def5", "Documentation"],
-		["type:infra", "bfd4f2", "Tooling, CI, infrastructure"],
 		[
 			"explore:2",
 			"fbca04",
@@ -62,7 +59,7 @@ const create = defineCommand({
 	meta: {
 		name: "create",
 		description:
-			"Create a GitHub Project board for this repo with the kanbot columns",
+			"Create a GitHub Project board for this repo with the kanbot columns and labels",
 	},
 	args: {
 		title: {
@@ -109,7 +106,11 @@ ${board.url}`);
 });
 
 const link = defineCommand({
-	meta: { name: "link", description: "Use an existing project board" },
+	meta: {
+		name: "link",
+		description:
+			"Use an existing project board, e.g. github.com/users/<owner>/projects/<number>",
+	},
 	args: {
 		owner: {
 			type: "string",
@@ -120,8 +121,14 @@ const link = defineCommand({
 	},
 	async run({ args }) {
 		const root = process.cwd();
+		const number = Number(args.number);
+		if (!Number.isInteger(number))
+			throw new UserError("--number must be a number.", {
+				why: "It's the number at the end of the project URL.",
+				docs: "getting-started#create-the-board",
+			});
 		await saveConfig(root, {
-			project: { owner: args.owner, number: Number(args.number) },
+			project: { owner: args.owner, number },
 		});
 		const config = await loadConfig(root);
 		const board = await loadBoard(new Gh(config.repo), config);

package/src/commands/doctor.ts

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { defineCommand } from "citty";
-import { loadAgents } from "../agents/load.ts";
+import { loadAgents, missingSkills } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
+import { capabilitySummary, findCapability } from "../capabilities.ts";
 import { loadConfig, writeConfigSchema } from "../config.ts";
 import { git } from "../daemon/git.ts";
 import { describeError } from "../errors.ts";
@@ -14,10 +15,22 @@ import {
 	loadBoard,
 	missingColumns,
 } from "../github/project.ts";
+import {
+	codexSupports,
+	type McpServer,
+	readMcpServers,
+} from "../providers/mcp.ts";
 import { NEW_SUFFIX, pendingMerges, planUpgrade } from "../templates.ts";
 import { REPO_LABELS } from "./board.ts";
 
-type Check = { name: string; ok: boolean; detail?: string; fix?: string };
+type Check = {
+	name: string;
+	ok: boolean;
+	/** Shown with a warning mark; never fails doctor. */
+	warn?: boolean;
+	detail?: string;
+	fix?: string;
+};
 
 async function cmd(args: string[]) {
 	const p = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
@@ -50,7 +63,7 @@ export default defineCommand({
 		const add = (c: Check) => {
 			checks.push(c);
 			console.log(
-				`${c.ok ? "✔" : "✖"} ${c.name}${c.detail ? ` — ${c.detail}` : ""}${!c.ok && c.fix ? `\n    fix: ${c.fix}` : ""}`,
+				`${c.warn ? "!" : c.ok ? "✔" : "✖"} ${c.name}${c.detail ? ` — ${c.detail}` : ""}${!c.ok && c.fix ? `\n    fix: ${c.fix}` : ""}`,
 			);
 		};
 
@@ -94,6 +107,12 @@ export default defineCommand({
 				detail: s.out.split("\n")[0],
 				fix: "codex login",
 			});
+			add({
+				name: "codex workers ignore ~/.codex/config.toml",
+				ok: true,
+				detail:
+					"models come from agent frontmatter, MCP servers from .mcp.json",
+			});
 		}
 
 		try {
@@ -105,10 +124,11 @@ export default defineCommand({
 			});
 			const needed = [
 				"planner",
-				"reviewer-code",
-				"reviewer-spec",
+				"reviewer",
+				"acceptance-reviewer",
 				"fixer",
-				...Object.values(config.implementers),
+				"implementer",
+				...Object.values(config.implementers ?? {}),
 			];
 			const missing = [...new Set(needed)].filter(
 				(n) => !agents.some((a) => a.name === n),
@@ -117,7 +137,43 @@ export default defineCommand({
 				name: "agents referenced by config exist",
 				ok: !missing.length,
 				detail: missing.join(", ") || undefined,
+				fix: "kanbot upgrade",
 			});
+			if (config.implementers)
+				add({
+					name: "implementers is deprecated",
+					ok: true,
+					warn: true,
+					detail:
+						"implement uses `implementer`; map craft with capabilities instead",
+					fix: "remove implementers from .kanbot/config.yml",
+				});
+			const noSkill = missingSkills(root, agents);
+			add({
+				name: "skills referenced by agents exist",
+				ok: !noSkill.length,
+				detail: noSkill.join(", ") || undefined,
+				fix: "add them to .agents/skills or remove them from the agent's `skills`",
+			});
+			add({
+				name: "capabilities",
+				ok: true,
+				detail: capabilitySummary(config.capabilities),
+			});
+			// Only problems get their own line.
+			for (const [name, c] of Object.entries(config.capabilities)) {
+				const found = findCapability(root, agents, c.use);
+				if (found === "skill" || found === "agent") continue;
+				add({
+					name: `capability ${name} → ${c.use}`,
+					ok: found !== null,
+					warn: found !== null,
+					detail: found
+						? `${found} agent, works on ${found} only`
+						: "not found",
+					fix: "add the skill to .agents/skills or the agent to .kanbot/agents",
+				});
+			}
 			const stale = await sync(root, agents, { check: true });
 			add({
 				name: "generated agent files up to date",
@@ -134,6 +190,24 @@ export default defineCommand({
 			add({ name: "agents", ok: false, ...explain(e) });
 		}
 
+		const servers = await readMcpServers(root);
+		const names = Object.keys(servers);
+		const skipped =
+			config.provider === "codex"
+				? names.filter((n) => !codexSupports(servers[n] as McpServer))
+				: [];
+		add({
+			name: "MCP servers for workers (.mcp.json)",
+			ok: true,
+			warn: skipped.length > 0,
+			detail: [
+				names.join(", ") || "none",
+				skipped.length ? `codex can't run: ${skipped.join(", ")}` : "",
+			]
+				.filter(Boolean)
+				.join("; "),
+		});
+
 		const plan = await planUpgrade(root);
 		const behind = plan.changes.filter((c) =>
 			["add", "update", "conflict"].includes(c.action),

package/src/commands/init.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { defineCommand } from "citty";
 import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
+import { askCapabilities, compact, ownWorkers } from "../capabilities.ts";
 import { configPath, saveConfig, writeConfigSchema } from "../config.ts";
 import { UserError } from "../errors.ts";
 import { run } from "../github/gh.ts";
@@ -79,6 +80,16 @@ export default defineCommand({
 			log.info(
 				`+ .kanbot/config.yml (${repo.nameWithOwner}, base ${repo.defaultBranchRef.name})`,
 			);
+			// Only ask when someone can answer.
+			if (process.stdin.isTTY) {
+				const caps = askCapabilities(await ownWorkers(root), prompt);
+				if (Object.keys(caps).length) {
+					await saveConfig(root, { capabilities: compact(caps) } as never);
+					log.info(
+						`~ .kanbot/config.yml (capabilities: ${Object.keys(caps).join(", ")})`,
+					);
+				}
+			}
 		}
 
 		const codeowners = join(root, ".github", "CODEOWNERS");
@@ -101,10 +112,11 @@ export default defineCommand({
 Next steps:
   1. Review AGENTS.md and fill in .agents/skills/project-conventions/SKILL.md
   2. Adjust .github/workflows/ci.yml to your stack (agents fix failing CI)
-  3. kanbot board create        # creates the project board and labels
-  4. kanbot doctor              # checks auth, board, generated files
+  3. Map your own skills under capabilities in .kanbot/config.yml (kanbot-guide can help)
+  4. kanbot board create        # board and labels; enable the workflows it prints
   5. Commit and push these files to the default branch (agents work from it)
-  6. kanbot run                 # start the loop (or kanbot run --once --dry-run)`);
+  6. kanbot doctor              # checks auth, board, generated files
+  7. kanbot run                 # start the loop (or kanbot run --once --dry-run)`);
 	},
 });
 

package/src/commands/sync.ts

@@ -8,7 +8,7 @@ export default defineCommand({
 	meta: {
 		name: "sync",
 		description:
-			"Generate .claude/agents, .codex/agents, permissions and the config schema",
+			"Generate .claude/agents, .codex/agents, permissions and the config schema from .kanbot/agents",
 	},
 	args: {
 		check: {

package/src/commands/upgrade.ts

@@ -1,8 +1,15 @@
+import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import pkg from "../../package.json" with { type: "json" };
 import { loadAgents } from "../agents/load.ts";
 import { sync } from "../agents/sync.ts";
-import { writeConfigSchema } from "../config.ts";
+import { compact, legacyCapabilities } from "../capabilities.ts";
+import {
+	configPath,
+	loadConfig,
+	saveConfig,
+	writeConfigSchema,
+} from "../config.ts";
 import { log } from "../log.ts";
 import {
 	applyUpgrade,
@@ -48,9 +55,21 @@ export default defineCommand({
 				);
 		}
 		if (!plan.changes.length) log.info("Templates are up to date.");
+		const caps = existsSync(configPath(root))
+			? legacyCapabilities(root, (await loadConfig(root)).capabilities)
+			: null;
+		if (caps)
+			console.log(
+				`\nMapped skills you have to capabilities in .kanbot/config.yml:\n${Object.entries(
+					caps,
+				)
+					.map(([n, c]) => `  ${n}: ${c.use}`)
+					.join("\n")}`,
+			);
 		if (args["dry-run"]) return;
 
 		await applyUpgrade(root, plan);
+		if (caps) await saveConfig(root, { capabilities: compact(caps) } as never);
 		const generated = await sync(root, await loadAgents(root));
 		if (await writeConfigSchema(root))
 			generated.push(".kanbot/config.schema.json");

package/src/config.ts

@@ -17,6 +17,36 @@ export type ColumnKey = (typeof COLUMN_KEYS)[number];
 export const JOB_KINDS = ["fix", "review", "plan", "implement"] as const;
 export type JobKind = (typeof JOB_KINDS)[number];
 
+export const RESERVED_CAPABILITIES = ["verify", "review", "preview"] as const;
+
+const CapabilityObject = z.object({
+	use: z
+		.string()
+		.min(1)
+		.describe(
+			"Skill in .agents/skills or agent in .kanbot/agents that does the work.",
+		),
+	when: z
+		.string()
+		.optional()
+		.describe("When it applies, e.g. `Changes to UI users see`."),
+	required: z
+		.boolean()
+		.default(false)
+		.describe("A miss when it applies blocks acceptance review."),
+});
+
+/** `verify: verify-ui` is short for `verify: { use: verify-ui }`. */
+export const Capability = z.union([
+	z
+		.string()
+		.min(1)
+		.describe("Skill or agent name, short for `{ use: <name> }`.")
+		.transform((use) => CapabilityObject.parse({ use })),
+	CapabilityObject,
+]);
+export type Capability = z.output<typeof Capability>;
+
 export const ConfigSchema = z.object({
 	provider: z
 		.enum(["claude", "codex"])
@@ -78,15 +108,15 @@ export const ConfigSchema = z.object({
 		.describe("Per-job timeout in minutes."),
 	implementers: z
 		.record(z.string(), z.string())
-		.default({
-			frontend: "implementer-frontend",
-			backend: "implementer-backend",
-			docs: "implementer-docs",
-			infra: "implementer-technical",
-			default: "implementer-backend",
-		})
+		.optional()
+		.describe(
+			"Deprecated: implement always uses `implementer`. While set, maps a type:<key> label to an agent, with `default` as the fallback. Use capabilities instead.",
+		),
+	capabilities: z
+		.record(z.string().regex(/^[a-z][a-z0-9-]*$/), Capability)
+		.default({})
 		.describe(
-			"Maps a type:<key> label to an agent. `default` is the fallback.",
+			"Needs mapped to the repo's own skills or agents. Reserved: verify (prove acceptance criteria), review (technical review), preview (something a human can try). Other names are yours.",
 		),
 	review: z
 		.object({