kanbot 0.3.0 → 0.4.1

package/src/commands/doctor.ts

@@ -1,11 +1,13 @@
 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 { color } from "../color.ts";
 import { loadConfig, writeConfigSchema } from "../config.ts";
 import { git } from "../daemon/git.ts";
-import { describeError } from "../errors.ts";
+import { DOCS_URL, describeError } from "../errors.ts";
 import { copilotReviewRule } from "../github/api.ts";
 import { appKeyPath, appTokens } from "../github/app.ts";
 import { Gh, run } from "../github/gh.ts";
@@ -14,10 +16,26 @@ 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;
+	/** Why it matters. Shown only when the check fails or warns. */
+	why?: string;
+	fix?: string;
+	/** Docs page and anchor, e.g. "configuration#config-file". */
+	docs?: string;
+};
 
 async function cmd(args: string[]) {
 	const p = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
@@ -32,13 +50,69 @@ async function cmd(args: string[]) {
 /** Failure detail and fix for a check, from a thrown error. */
 function explain(e: unknown, fallback?: string) {
 	const d = describeError(e);
-	const detail = [d.message, d.why].filter(Boolean).join("\n");
 	return {
-		detail: detail.replace(/\n/g, "\n    "),
+		detail: d.message,
+		why: d.why,
 		fix: d.fix ?? fallback,
+		docs: d.docs,
 	};
 }
 
+const indent = (s: string, pad: string) => s.replace(/^(?=.)/gm, pad);
+
+function print(c: Check) {
+	const state = c.warn ? "warn" : c.ok ? "ok" : "fail";
+	const mark = {
+		ok: color.green("✔"),
+		warn: color.yellow("!"),
+		fail: color.red("✖"),
+	}[state];
+	if (state === "ok") {
+		const detail = c.detail ? color.dim(` — ${c.detail}`) : "";
+		console.log(`  ${mark} ${c.name}${detail}`);
+		return;
+	}
+	const paint = state === "warn" ? color.yellow : color.red;
+	const lines = [`  ${mark} ${paint(c.name)}`];
+	if (c.detail) lines.push(indent(c.detail, "      "));
+	if (c.why) lines.push(color.dim(indent(c.why, "      ")));
+	if (c.fix) lines.push(`      ${color.bold("Fix:")}  ${color.cyan(c.fix)}`);
+	if (c.docs)
+		lines.push(
+			`      ${color.bold("Docs:")} ${color.dim(`${DOCS_URL}/${c.docs}`)}`,
+		);
+	console.log(lines.join("\n"));
+}
+
+function section(title: string) {
+	console.log(`\n${color.bold(title)}`);
+}
+
+/** Print totals and next step, then exit 1 if anything failed. */
+function summary(checks: Check[]) {
+	const failed = checks.filter((c) => !c.ok).length;
+	const warned = checks.filter((c) => c.ok && c.warn).length;
+	const passed = checks.length - failed - warned;
+	const parts = [color.green(`${passed} passed`)];
+	if (warned)
+		parts.push(
+			color.yellow(`${warned} ${warned === 1 ? "warning" : "warnings"}`),
+		);
+	if (failed) parts.push(color.red(`${failed} failed`));
+	console.log(`\n${parts.join(color.dim(" · "))}`);
+	if (failed) {
+		console.log(
+			`Fix the ${color.red("✖")} items above, top to bottom, then run ${color.cyan("kanbot doctor")} again.`,
+		);
+		process.exit(1);
+	}
+	if (warned)
+		console.log(
+			`Ready to run. The ${color.yellow("!")} items are worth a look, but won't stop kanbot.`,
+		);
+	else console.log(`All set. Start kanbot with ${color.cyan("kanbot run")}.`);
+}
+
 export default defineCommand({
 	meta: {
 		name: "doctor",
@@ -49,19 +123,32 @@ export default defineCommand({
 		const checks: Check[] = [];
 		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}` : ""}`,
-			);
+			print(c);
 		};
 
+		console.log(
+			`${color.bold("kanbot doctor")} ${color.dim("checks that everything kanbot needs is in place.")}`,
+		);
+
+		section("GitHub CLI");
 		const auth = await cmd(["gh", "auth", "status"]);
-		add({ name: "gh logged in", ok: auth.ok, fix: "gh auth login" });
+		add({
+			name: "gh logged in",
+			ok: auth.ok,
+			why: "kanbot talks to GitHub through gh.",
+			fix: "gh auth login",
+			docs: "getting-started#requirements",
+		});
 		add({
 			name: "gh token has project scope",
 			ok: /'project'/.test(auth.out),
+			why: "Needed to read and move cards on the project board.",
 			fix: "gh auth refresh -s project",
+			docs: "getting-started#requirements",
 		});
 
+		section("Config");
+
 		let config: Awaited<ReturnType<typeof loadConfig>>;
 		try {
 			config = await loadConfig(root);
@@ -72,30 +159,44 @@ export default defineCommand({
 			});
 		} catch (e) {
 			add({ name: "config", ok: false, ...explain(e, "kanbot init") });
-			return process.exit(1);
+			console.log(
+				color.dim("\n  The other checks need a config, so doctor stops here."),
+			);
+			return summary(checks);
 		}
 
 		if (config.provider === "claude") {
+			section("Claude Code");
 			const s = await cmd(["claude", "auth", "status"]);
 			const sub = /"authMethod":\s*"claude\.ai"/.test(s.out);
 			add({
 				name: "claude CLI logged in with a subscription",
 				ok: s.ok && sub,
-				detail: sub
-					? undefined
-					: "not using a claude.ai login (would bill API usage)",
+				detail: sub ? undefined : "Not using a claude.ai login.",
+				why: "Workers run `claude`. An API key login bills per token instead of your plan.",
 				fix: "claude auth login",
+				docs: "providers#claude-code",
 			});
 		} else {
+			section("Codex");
 			const s = await cmd(["codex", "login", "status"]);
 			add({
 				name: "codex CLI logged in with ChatGPT",
 				ok: s.ok && /ChatGPT/i.test(s.out),
 				detail: s.out.split("\n")[0],
+				why: "Workers run `codex` on your ChatGPT plan.",
 				fix: "codex login",
+				docs: "providers#codex",
+			});
+			add({
+				name: "codex workers ignore ~/.codex/config.toml",
+				ok: true,
+				detail:
+					"models come from agent frontmatter, MCP servers from .mcp.json",
 			});
 		}
 
+		section("Agents and skills");
 		try {
 			const agents = await loadAgents(root);
 			add({
@@ -105,10 +206,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,23 +219,86 @@ export default defineCommand({
 				name: "agents referenced by config exist",
 				ok: !missing.length,
 				detail: missing.join(", ") || undefined,
+				why: "Columns hand work to these agents, but .kanbot/agents has no file for them.",
+				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,
+				why: "Agents list these skills, but .agents/skills has none by that name.",
+				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",
+					why: found
+						? undefined
+						: "Jobs that need this capability can't load it.",
+					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",
 				ok: !stale.length,
 				detail: stale.join(", ") || undefined,
+				why: "Workers read .claude/agents and .codex/agents, which are generated from .kanbot/agents.",
 				fix: "kanbot sync",
 			});
 			add({
 				name: "config schema up to date",
 				ok: !(await writeConfigSchema(root, { check: true })),
+				why: "Editors use it for autocomplete and errors in config.yml.",
 				fix: "kanbot sync",
+				docs: "configuration",
 			});
 		} catch (e) {
 			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("; "),
+		});
+
+		section("Templates");
 		const plan = await planUpgrade(root);
 		const behind = plan.changes.filter((c) =>
 			["add", "update", "conflict"].includes(c.action),
@@ -144,16 +309,21 @@ export default defineCommand({
 			detail: behind.length
 				? `${behind.length} file(s) differ from this kanbot version`
 				: undefined,
+			why: "You get fixes to agents, skills and workflows by upgrading.",
 			fix: "kanbot upgrade",
+			docs: "upgrading",
 		});
 		const merges = await pendingMerges(root);
 		add({
 			name: `no unmerged ${NEW_SUFFIX} files`,
 			ok: !merges.length,
 			detail: merges.join(", ") || undefined,
+			why: "upgrade put the new version next to files you changed.",
+			docs: "upgrading",
 			fix: `merge each into the file next to it and delete it (kanbot-admin skill can help)`,
 		});
 
+		section(`Pushed to origin/${config.baseBranch}`);
 		await git(root, "fetch", "origin", config.baseBranch).catch(() => {});
 		const tree = await git(
 			root,
@@ -171,15 +341,18 @@ export default defineCommand({
 			add({
 				name: `${path} committed on origin/${config.baseBranch}`,
 				ok: tree.split("\n").some((f) => f.startsWith(path)),
-				detail: "worktrees are created from the base branch",
+				why: "Workers run in worktrees made from the base branch, so they only see what is pushed.",
 				fix: "commit and push the kanbot files",
 			});
 		}
 		add({
 			name: ".github/workflows/kanbot-merged.yml",
 			ok: existsSync(join(root, ".github/workflows/kanbot-merged.yml")),
+			why: "Closes the other approaches' PRs when one is merged.",
+			fix: "kanbot upgrade",
 		});
 
+		section("Project board");
 		const gh = new Gh(config.repo);
 		try {
 			const board = await loadBoard(gh, config);
@@ -190,7 +363,11 @@ export default defineCommand({
 				detail: missing.length
 					? `missing columns: ${missing.join(", ")}`
 					: board.url,
+				why: missing.length
+					? "kanbot moves cards by the column names in config.yml."
+					: undefined,
 				fix: "kanbot board create",
+				docs: "getting-started#create-the-board",
 			});
 			// Moving cards to Done on close/merge and adding new issues are left to GitHub.
 			const workflows = await boardWorkflows(gh, board);
@@ -202,6 +379,7 @@ export default defineCommand({
 				add({
 					name: `board workflow "${name}" enabled`,
 					ok: workflows.some((w) => w.name === name && w.enabled),
+					why: "kanbot leaves adding new issues and moving closed ones to Done to GitHub.",
 					fix: `enable it in ${board.url} → ⋯ → Workflows`,
 				});
 			}
@@ -233,16 +411,21 @@ export default defineCommand({
 		add({
 			name: "labels",
 			ok: !missingLabels.length,
-			detail: missingLabels.join(", ") || undefined,
+			detail: missingLabels.length
+				? `missing: ${missingLabels.join(", ")}`
+				: undefined,
+			why: "kanbot tags issues and PRs with these labels.",
 			fix: "kanbot board create",
 		});
 
 		const { mode, app } = config.identity;
 		if (mode === "app") {
+			section("GitHub App");
 			add({
 				name: "kanbot app set",
 				ok: app !== null,
 				detail: app ? `${app.slug} (id ${app.id})` : undefined,
+				why: "identity.mode is app, so kanbot acts as a GitHub App.",
 				fix: "kanbot app create",
 			});
 			if (app) {
@@ -251,6 +434,7 @@ export default defineCommand({
 					name: "kanbot app private key",
 					ok: existsSync(key),
 					detail: key,
+					why: "kanbot signs in as the app with this key.",
 					fix: "kanbot app create, or copy the key from the machine that created the app",
 				});
 				if (existsSync(key)) {
@@ -272,6 +456,7 @@ export default defineCommand({
 		}
 
 		if (config.review.copilot) {
+			section("Copilot review");
 			const rule = await copilotReviewRule(gh, config.baseBranch).catch(
 				() => null,
 			);
@@ -282,14 +467,16 @@ export default defineCommand({
 					? `re-review on push: ${rule.parameters?.review_on_push ? "on" : "off"}`
 					: "review.copilot is on, but no ruleset requests Copilot review",
 				fix: "kanbot board create",
+				docs: "copilot-review",
 			});
 			add({
 				name: ".github/copilot-instructions.md committed",
+				why: "Copilot reads it to review the way your team wants.",
 				ok: tree.split("\n").includes(".github/copilot-instructions.md"),
 				fix: "kanbot sync, then commit and push",
 			});
 		}
 
-		if (checks.some((c) => !c.ok)) process.exit(1);
+		summary(checks);
 	},
 });

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({

package/src/daemon/derive.ts

@@ -76,6 +76,7 @@ export type Action =
 	| { kind: "merge"; item: Item; pr: PR; by: string }
 	| { kind: "compare"; item: Item; prs: PR[] }
 	| { kind: "needsHuman"; number: number; why: string }
+	| { kind: "openQuestions"; item: Item; questions: string[] }
 	| { kind: "resetFailures"; prefix: string }
 	| { kind: "cleanup"; number: number };
 
@@ -178,6 +179,36 @@ export function approvedBy(
 	);
 }
 
+const OPEN_QUESTIONS = /^##\s+Open questions\s*$[\s\S]*?(?=^##\s|(?![\s\S]))/im;
+
+/** The plan with its "## Open questions" section set to `questions`, last. */
+export function withOpenQuestions(plan: string, questions: string[]): string {
+	const rest = plan.replace(OPEN_QUESTIONS, "").trimEnd();
+	if (!questions.length) return rest;
+	return `${rest}\n\n## Open questions\n\n${questions.map((q) => `- ${q}`).join("\n")}`;
+}
+
+/** Bullets under the plan's "## Open questions". */
+export function openQuestions(plan: string | null): string[] {
+	const m = plan?.match(OPEN_QUESTIONS);
+	if (!m) return [];
+	return m[0]
+		.split("\n")
+		.slice(1)
+		.map((l) => l.match(/^\s*[-*]\s+(.+)$/)?.[1]?.trim())
+		.filter((q): q is string => Boolean(q));
+}
+
+/** Was the open-questions gate already posted for the latest plan? */
+function gatePosted(comments: Comment[]) {
+	for (let i = comments.length - 1; i >= 0; i--) {
+		const body = (comments[i] as Comment).body;
+		if (hasMarker(body, "questions")) return true;
+		if (hasMarker(body, "plan")) return false;
+	}
+	return false;
+}
+
 const fixCount = (pr: PR, kind: "ci" | "conflict") =>
 	pr.comments.reduce((n, c) => n + markerValues(c.body, kind).length, 0);
 
@@ -228,6 +259,16 @@ export function derive(snapshot: Snapshot, ctx: DeriveContext) {
 
 			case "ready":
 			case "inProgress": {
+				// Open questions keep a plan out of Ready. Once started, it runs on.
+				const questions =
+					item.column === "ready" && !issue.prs.length
+						? openQuestions(extractPlan(issue.body))
+						: [];
+				if (questions.length) {
+					if (!gatePosted(issue.comments))
+						actions.push({ kind: "openQuestions", item, questions });
+					break;
+				}
 				const n = exploreCount(issue.labels);
 				const variants =
 					n === null ? [null] : Array.from({ length: n }, (_, i) => i + 1);

package/src/daemon/loop.ts

@@ -211,6 +211,8 @@ function describeAction(a: Action) {
 			return `post comparison on #${a.item.issue.number}`;
 		case "needsHuman":
 			return `needs-human #${a.number}`;
+		case "openQuestions":
+			return `open questions on #${a.item.issue.number}`;
 		case "resetFailures":
 			return `reset failures ${a.prefix}`;
 		case "cleanup":