kanbot 0.3.0 → 0.4.1

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.1",
 	"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/color.ts

@@ -0,0 +1,16 @@
+// ANSI colors for TTY output. Off when piped or NO_COLOR is set; FORCE_COLOR turns them on.
+const on =
+	!process.env.NO_COLOR &&
+	(!!process.env.FORCE_COLOR || !!process.stdout.isTTY);
+
+const wrap = (open: number, close: number) => (s: string) =>
+	on ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+
+export const color = {
+	bold: wrap(1, 22),
+	dim: wrap(2, 22),
+	red: wrap(31, 39),
+	green: wrap(32, 39),
+	yellow: wrap(33, 39),
+	cyan: wrap(36, 39),
+};

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);