kanbot 0.4.0 → 0.5.0

package/README.md

@@ -26,11 +26,11 @@ Full docs: [docs/](./docs/00-index.md). Demo video: [docs/assets/demo.mp4](./doc
 | **Ready**       | Moving a card here approves the plan. Cards are picked top-down.                                                                                 |
 | **In Progress** | An agent implements it in its own worktree and opens a PR.                                                                                       |
 | **Review**      | Two agent reviews, with fixes. Then you're notified. Comment on the PR and an agent addresses it. CI failures and merge conflicts are fixed too. |
-| **Done**        | You merge, or approve and kanbot merges ([`merge.onApproval`](./docs/12-identity.md#merge-on-approval)).                                         |
+| **Done**        | You merge, or approve and kanbot merges ([`merge.onApproval`](./docs/11-identity.md#merge-on-approval)).                                         |
 
 A Bun daemon polls the board and runs one `claude -p` / `codex exec` process per job. GitHub is the only state, so you can restart it any time. Agents never get a GitHub token; the daemon makes every comment, push and PR. Only collaborators with write access can steer agents.
 
-kanbot talks as you by default. Run `kanbot app create` to have it talk as its own bot instead, so you can tell its messages apart and approve its PRs. Commits stay yours. With `merge.onApproval`, approving a PR merges it. [More](./docs/12-identity.md)
+kanbot talks as you by default. Run `kanbot app create` to have it talk as its own bot instead, so you can tell its messages apart and approve its PRs. Commits stay yours. With `merge.onApproval`, approving a PR merges it. [More](./docs/11-identity.md)
 
 ## Setup
 
@@ -64,19 +64,19 @@ For a guided setup, run `bunx kanbot skills install` and ask your agent "help me
 
 - **Capture ideas by chatting.** Ask your agent to file an idea; the `kanbot-idea` skill shapes it and puts it in Ideas. [More](./docs/03-capturing-ideas.md)
 - **Your own PRs.** Label a PR `kanbot-review` for agent review without a card. Commits to `main` that break kanbot PRs get merged in and fixed. [More](./docs/04-outside-the-board.md)
-- **Project memory.** Corrections you give on PRs become facts agents read on every job. [More](./docs/06-skills.md#project-memory)
-- **Copilot review.** Optionally add GitHub Copilot as a cloud reviewer. [More](./docs/09-copilot-review.md)
+- **Project memory.** Corrections you give on PRs become facts agents read on every job. [More](./docs/08-project-memory.md)
+- **Copilot review.** Optionally add GitHub Copilot as a cloud reviewer. [More](./docs/12-copilot-review.md)
 
 ## Customizing
 
 - `.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)
+- `capabilities` in config: your own skills and agents for building, testing and reviewing. [More](./docs/05-capabilities.md)
 
 ## Upgrading
 
-`bunx kanbot@latest upgrade` updates agents and skills you haven't edited. For edited ones, it writes the new version next to yours as `<file>.kanbot-new` to merge. See [Upgrading](./docs/10-upgrading.md).
+`bunx kanbot@latest upgrade` updates agents and skills you haven't edited. For edited ones, it writes the new version next to yours as `<file>.kanbot-new` to merge. See [Upgrading](./docs/13-upgrading.md).
 
 ## Shell completion
 
@@ -89,7 +89,7 @@ The shell is detected from `$SHELL`; pass `--shell zsh|bash|fish` to override. F
 
 ## Operating
 
-- `kanbot status` shows the board, daemon and failures.
+- `kanbot status` shows the board, what waits on you, daemon and failures.
 - `.kanbot/logs/*.jsonl` has every agent transcript.
 
 ## Limitations

package/package.json

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

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/doctor.ts

@@ -4,9 +4,10 @@ import { defineCommand } from "citty";
 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";
@@ -29,7 +30,11 @@ type Check = {
 	/** 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[]) {
@@ -45,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",
@@ -62,19 +123,32 @@ export default defineCommand({
 		const checks: Check[] = [];
 		const add = (c: Check) => {
 			checks.push(c);
-			console.log(
-				`${c.warn ? "!" : 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);
@@ -85,27 +159,34 @@ 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",
@@ -115,6 +196,7 @@ export default defineCommand({
 			});
 		}
 
+		section("Agents and skills");
 		try {
 			const agents = await loadAgents(root);
 			add({
@@ -137,6 +219,7 @@ 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)
@@ -153,6 +236,7 @@ export default defineCommand({
 				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({
@@ -171,6 +255,9 @@ export default defineCommand({
 					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",
 				});
 			}
@@ -179,12 +266,15 @@ export default defineCommand({
 				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) });
@@ -208,6 +298,7 @@ export default defineCommand({
 				.join("; "),
 		});
 
+		section("Templates");
 		const plan = await planUpgrade(root);
 		const behind = plan.changes.filter((c) =>
 			["add", "update", "conflict"].includes(c.action),
@@ -218,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,
@@ -245,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);
@@ -264,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);
@@ -276,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`,
 				});
 			}
@@ -307,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) {
@@ -325,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)) {
@@ -346,6 +456,7 @@ export default defineCommand({
 		}
 
 		if (config.review.copilot) {
+			section("Copilot review");
 			const rule = await copilotReviewRule(gh, config.baseBranch).catch(
 				() => null,
 			);
@@ -356,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/status.ts

@@ -1,15 +1,27 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { defineCommand } from "citty";
-import { COLUMN_KEYS, LABELS, loadConfig } from "../config.ts";
+import { COLUMN_KEYS, loadConfig } from "../config.ts";
+import { waitingOnHuman } from "../daemon/derive.ts";
+import { takeSnapshot } from "../daemon/snapshot.ts";
 import { State } from "../daemon/state.ts";
-import { Gh, run } from "../github/gh.ts";
+import { Gh } from "../github/gh.ts";
 import { listItems, loadBoard } from "../github/project.ts";
+import { Trust } from "../github/trust.ts";
+
+/** Short age like `5m`, `3h` or `2d`. */
+export function age(since: string, now = Date.now()) {
+	const m = Math.max(0, Math.floor((now - Date.parse(since)) / 60_000));
+	if (m < 60) return `${m}m`;
+	if (m < 60 * 24) return `${Math.floor(m / 60)}h`;
+	return `${Math.floor(m / (60 * 24))}d`;
+}
 
 export default defineCommand({
 	meta: {
 		name: "status",
-		description: "Show board columns, daemon state and failures",
+		description:
+			"Show board columns, what waits on you, daemon state and failures",
 	},
 	async run() {
 		const root = process.cwd();
@@ -37,22 +49,14 @@ export default defineCommand({
 			console.log(`${config.columns[key].padEnd(12)} ${shown}`);
 		}
 
-		const needsHuman = JSON.parse(
-			await run([
-				"issue",
-				"list",
-				"--repo",
-				config.repo,
-				"--label",
-				LABELS.needsHuman,
-				"--json",
-				"number,title",
-			]),
-		) as { number: number; title: string }[];
-		if (needsHuman.length) {
-			console.log(
-				`\nneeds-human:\n${needsHuman.map((i) => `  #${i.number} ${i.title}`).join("\n")}`,
-			);
+		const snapshot = await takeSnapshot(gh, board, new Trust(gh), items);
+		const waiting = waitingOnHuman(snapshot, config);
+		if (waiting.length) {
+			const rows = waiting.map(({ item, why, url, since }) => {
+				const ago = since ? age(since) : "?";
+				return `  ${ago.padStart(4)}  #${item.issue.number} ${why} · ${item.issue.title}\n        ${url}`;
+			});
+			console.log(`\nwaiting on you:\n${rows.join("\n")}`);
 		}
 
 		const state = await new State(root).load();

package/src/daemon/derive.ts

@@ -77,6 +77,7 @@ export type Action =
 	| { kind: "compare"; item: Item; prs: PR[] }
 	| { kind: "needsHuman"; number: number; why: string }
 	| { kind: "openQuestions"; item: Item; questions: string[] }
+	| { kind: "waiting"; item: Item; blockers: string[] }
 	| { kind: "resetFailures"; prefix: string }
 	| { kind: "cleanup"; number: number };
 
@@ -199,6 +200,22 @@ export function openQuestions(plan: string | null): string[] {
 		.filter((q): q is string => Boolean(q));
 }
 
+/** Open "blocked by" issues, as `#12` or `owner/repo#12`. */
+export function openBlockers(issue: Issue): string[] {
+	return issue.blockedBy
+		.filter((b) => b.state === "OPEN")
+		.map((b) => `${b.repo ?? ""}#${b.number}`);
+}
+
+/** Was the waiting comment already posted for these blockers? */
+function waitingPosted(comments: Comment[], blockers: string[]) {
+	for (let i = comments.length - 1; i >= 0; i--) {
+		const [last] = markerValues((comments[i] as Comment).body, "waiting");
+		if (last) return last === blockers.join(",");
+	}
+	return false;
+}
+
 /** Was the open-questions gate already posted for the latest plan? */
 function gatePosted(comments: Comment[]) {
 	for (let i = comments.length - 1; i >= 0; i--) {
@@ -269,6 +286,16 @@ export function derive(snapshot: Snapshot, ctx: DeriveContext) {
 						actions.push({ kind: "openQuestions", item, questions });
 					break;
 				}
+				// Open blockers keep it waiting; the next Ready card is picked.
+				const blockers =
+					item.column === "ready" && !issue.prs.length
+						? openBlockers(issue)
+						: [];
+				if (blockers.length) {
+					if (!waitingPosted(issue.comments, blockers))
+						actions.push({ kind: "waiting", item, blockers });
+					break;
+				}
 				const n = exploreCount(issue.labels);
 				const variants =
 					n === null ? [null] : Array.from({ length: n }, (_, i) => i + 1);
@@ -489,3 +516,108 @@ export function schedule(
 		.sort((a, b) => rank(a) - rank(b))
 		.slice(0, Math.max(0, freeSlots));
 }
+
+/** A card that needs a human before it can move on. */
+export type Waiting = {
+	item: Item;
+	why: string;
+	/** Link to act on: the PR, or the issue. */
+	url: string;
+	/** When it started waiting, if known. */
+	since: string | null;
+};
+
+/** Does the body carry `<!-- kanbot:<kind> -->` or `<!-- kanbot:<kind>:x -->`? */
+const markedAs = (body: string, kind: string) =>
+	body.includes(`<!-- kanbot:${kind} -->`) ||
+	body.includes(`<!-- kanbot:${kind}:`);
+
+const lastMarked = (comments: Comment[], ...kinds: string[]) =>
+	comments.findLast((c) => kinds.some((k) => markedAs(c.body, k)));
+
+/** First line of a kanbot comment, without bold. */
+const headline = (c: Comment | undefined) =>
+	c?.body.split("\n")[0]?.replaceAll("**", "").trim() || null;
+
+/** Cards waiting on a human, oldest first. Pure, like `derive`. */
+export function waitingOnHuman(snapshot: Snapshot, config: Config): Waiting[] {
+	const { trusted } = snapshot;
+	const out: Waiting[] = [];
+
+	for (const item of snapshot.items) {
+		const { issue } = item;
+		if (issue.state === "CLOSED" || item.column === "done") continue;
+		const add = (why: string, c?: Comment, url = issue.url) =>
+			out.push({ item, why, url, since: c?.createdAt ?? null });
+
+		if (issue.labels.includes(LABELS.needsHuman)) {
+			const c = lastMarked(
+				[...issue.comments, ...issue.prs.flatMap((p) => p.comments)].sort(
+					(a, b) => a.createdAt.localeCompare(b.createdAt),
+				),
+				"needs-human",
+				"blocked",
+			);
+			add(headline(c) ?? LABELS.needsHuman, c);
+			continue;
+		}
+
+		switch (item.column) {
+			case "planning": {
+				const plan = extractPlan(issue.body);
+				if (plan === null || pendingComments(issue.comments, trusted).length)
+					break;
+				const c = lastMarked(issue.comments, "plan");
+				add(
+					openQuestions(plan).length
+						? "answer the plan's questions"
+						: "approve the plan",
+					c,
+				);
+				break;
+			}
+
+			case "ready": {
+				if (issue.prs.length || !gatePosted(issue.comments)) break;
+				if (!openQuestions(extractPlan(issue.body)).length) break;
+				add("answer open questions", lastMarked(issue.comments, "questions"));
+				break;
+			}
+
+			case "review": {
+				const open = issue.prs.filter(
+					(p) =>
+						p.state === "OPEN" &&
+						(issue.prOnly || p.headRefName.startsWith("kanbot/")),
+				);
+				const compare = lastMarked(issue.comments, "compare");
+				if (exploreCount(issue.labels) !== null && compare) {
+					add("pick an approach", compare);
+					break;
+				}
+				for (const pr of open) {
+					if (!pr.labels.includes(LABELS.agentReviewed)) continue;
+					const feedback = openFeedback(pr, trusted);
+					if (feedback.threads.length || feedback.comments.length) continue;
+					const approved = approvedBy(pr, trusted) !== null;
+					// Approved kanbot PRs are merged by the daemon.
+					const autoMerge =
+						config.merge.onApproval && pr.headRefName.startsWith("kanbot/");
+					if (approved && autoMerge) continue;
+					const c = lastMarked(pr.comments, "ready");
+					out.push({
+						item,
+						why: `${approved ? "merge" : "review"} PR #${pr.number}`,
+						url: pr.url,
+						since: c?.createdAt ?? pr.createdAt,
+					});
+				}
+				break;
+			}
+		}
+	}
+
+	// Oldest first; unknown age last.
+	const key = (w: Waiting) => w.since ?? "\uffff";
+	return out.sort((a, b) => key(a).localeCompare(key(b)));
+}

package/src/daemon/loop.ts

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

package/src/daemon/snapshot.ts

@@ -18,8 +18,10 @@ export async function takeSnapshot(
 	gh: Gh,
 	board: Board,
 	trust: Trust,
+	/** Board items already listed, to save a query. */
+	listed?: Awaited<ReturnType<typeof listItems>>,
 ): Promise<Snapshot> {
-	const raw = await listItems(gh, board);
+	const raw = listed ?? (await listItems(gh, board));
 	const items = await mapLimit(
 		raw,
 		4,
@@ -50,6 +52,7 @@ export async function takeSnapshot(
 					labels: [],
 					comments: [],
 					prs: [],
+					blockedBy: [],
 				},
 			};
 		},
@@ -86,6 +89,7 @@ export function prItem(pr: PR, position: number): Item {
 			labels: pr.labels,
 			comments: [],
 			prs: [pr],
+			blockedBy: [],
 			prOnly: true,
 		},
 	};

package/src/daemon/types.ts

@@ -61,6 +61,13 @@ export type PR = {
 	mergeable: "MERGEABLE" | "CONFLICTING" | "UNKNOWN";
 };
 
+/** An issue this one links to. `repo` is null for the same repo. */
+export type IssueRef = {
+	number: number;
+	repo: string | null;
+	state: "OPEN" | "CLOSED";
+};
+
 export type Issue = {
 	id: string;
 	number: number;
@@ -71,6 +78,8 @@ export type Issue = {
 	labels: string[];
 	comments: Comment[];
 	prs: PR[];
+	/** GitHub "blocked by" links. */
+	blockedBy: IssueRef[];
 	/** A PR labeled `kanbot-review`, reviewed without a card. Fields mirror the PR. */
 	prOnly?: boolean;
 };

package/src/github/api.ts

@@ -1,4 +1,4 @@
-import type { Checks, Comment, Issue, PR } from "../daemon/types.ts";
+import type { Checks, Comment, Issue, IssueRef, PR } from "../daemon/types.ts";
 import type { Gh } from "./gh.ts";
 
 const COMMENT = "id databaseId author { login } body createdAt";
@@ -24,6 +24,7 @@ query($owner: String!, $name: String!, $number: Int!) {
 			id number url title body state
 			labels(first: 50) { nodes { name } }
 			comments(last: 100) { nodes { ${COMMENT} } }
+			blockedBy(first: 20) { nodes { number state repository { nameWithOwner } } }
 			closedByPullRequestsReferences(first: 10, includeClosedPrs: true) {
 				nodes { ${PR_FIELDS} }
 			}
@@ -69,6 +70,15 @@ export async function fetchIssue(gh: Gh, number: number): Promise<Issue> {
 		labels: names(i.labels),
 		comments: i.comments.nodes.map(comment),
 		prs: i.closedByPullRequestsReferences.nodes.map(mapPR),
+		// biome-ignore lint/suspicious/noExplicitAny: raw GraphQL shape
+		blockedBy: i.blockedBy.nodes.map((b: any): IssueRef => {
+			const repo = b.repository.nameWithOwner;
+			return {
+				number: b.number,
+				repo: repo === gh.repo ? null : repo,
+				state: b.state,
+			};
+		}),
 	};
 }
 
@@ -205,6 +215,14 @@ export function addSubIssue(gh: Gh, parentId: string, childId: string) {
 	);
 }
 
+export function addBlockedBy(gh: Gh, issueId: string, blockerId: string) {
+	return gh.mutate(
+		"add blocked-by",
+		`mutation($i: ID!, $b: ID!) { addBlockedBy(input: { issueId: $i, blockingIssueId: $b }) { issue { id } } }`,
+		{ i: issueId, b: blockerId },
+	);
+}
+
 export function createPR(
 	gh: Gh,
 	pr: {

package/src/jobs/run.ts

@@ -19,6 +19,7 @@ import type { Worktrees } from "../daemon/git.ts";
 import type { Notifier } from "../daemon/notify.ts";
 import type { State } from "../daemon/state.ts";
 import {
+	addBlockedBy,
 	addLabels,
 	addSubIssue,
 	createIssue,
@@ -152,6 +153,25 @@ export function runJob(job: Job, deps: JobDeps): Promise<void> {
 
 // ---- plan -------------------------------------------------------------------
 
+/**
+ * [issue, blocker] node id pairs for the planner's `blockedBy` indexes.
+ * `ids[0]` is the planned issue, `ids[n]` the nth new issue (undefined if not
+ * created). Bad indexes and self-links are dropped.
+ */
+export function blockedByLinks(
+	newIssues: { blockedBy: number[] }[],
+	ids: (string | undefined)[],
+): [string, string][] {
+	return newIssues.flatMap((ni, i) => {
+		const id = ids[i + 1];
+		if (!id) return [];
+		return ni.blockedBy
+			.map((b) => ids[b])
+			.filter((b): b is string => !!b && b !== id)
+			.map((b): [string, string] => [id, b]);
+	});
+}
+
 async function plan(job: PlanJob, deps: JobDeps) {
 	const { gh, bot } = deps;
 	const { issue } = job.item;
@@ -183,17 +203,25 @@ async function plan(job: PlanJob, deps: JobDeps) {
 	);
 
 	const created: string[] = [];
+	// Node ids by blockedBy index: 0 is this issue, n the nth new issue.
+	const ids: (string | undefined)[] = [issue.id];
 	for (const ni of result.newIssues) {
 		const res = await createIssue(
 			bot,
 			ni.title,
 			`${ni.body}\n\n_Split from #${issue.number} by kanbot._\n${marker("created", issue.number)}`,
 		);
+		ids.push(res?.node_id);
 		if (!res) continue;
 		if (ni.subIssue) await addSubIssue(bot, issue.id, res.node_id);
 		await addToBoard(gh, deps.board, res.node_id, ni.column);
 		created.push(`#${res.number}`);
 	}
+	for (const [id, blocker] of blockedByLinks(result.newIssues, ids)) {
+		await addBlockedBy(bot, id, blocker).catch((e) =>
+			log.warn(`blocked-by link: ${e}`),
+		);
+	}
 
 	const lines = [
 		`**Plan ${job.initial ? "drafted" : "updated"}.** ${result.summary}`,
@@ -590,6 +618,12 @@ export async function applyAction(action: Action, deps: JobDeps) {
 				action.item.issue.number,
 				`**Not started: the plan has open questions.**\n\n${action.questions.map((q) => `- ${q}`).join("\n")}\n\nMove the card to **Planning** and answer them, or remove them from the plan. Then move it back to **Ready**.\n${marker("questions")}`,
 			);
+		case "waiting":
+			return postComment(
+				bot,
+				action.item.issue.number,
+				`**Waiting: blocked by ${action.blockers.join(", ")}.** kanbot starts it when they close.\n${marker("waiting", action.blockers.join(","))}`,
+			);
 		case "merge": {
 			const { pr } = action;
 			log.info(`merging #${pr.number}, approved by ${action.by}`);

package/src/known-hashes.json

@@ -4,7 +4,8 @@
 		"d932ed30a58cb32dd91ec03ddd2b1c6c59f77714"
 	],
 	".agents/skills/issue-splitting/SKILL.md": [
-		"01625372d68a81347bf401e8603084420922d04e"
+		"01625372d68a81347bf401e8603084420922d04e",
+		"8d8651621721c530522d83edb9530b622df275df"
 	],
 	".agents/skills/kanbot-admin/SKILL.md": [
 		"3789c559be9fb6a78f82708ae9857395a5556f6b",
@@ -19,7 +20,10 @@
 		"1251194ba34a8b6eae8508037b0a76c60d7a26b8",
 		"2c6c77a225c5b880eff023d4b3c1305bfc91bfb3",
 		"2ccb86b12e5af121b79ef9f53c2a35dbbdb2ddeb",
+		"53c73b1be4a1e8d863a52043eae4ca911c8be71b",
 		"a24c0a655d6485e65bd5dea2a71f3afe67f04404",
+		"b5a2d074ea61f2552890ca1d78bf8a043d7b73b3",
+		"bde0364d60525598bbb28f1648d06d1407c62a73",
 		"cf3e95d137a5a58a273262bca6ba25fbc95fa037"
 	],
 	".agents/skills/kanbot-idea/SKILL.md": [
@@ -104,6 +108,7 @@
 	".kanbot/agents/planner.md": [
 		"2283cf8bf6d27b8bbf721f97bb45cd40eaa6d39d",
 		"6500bea6691685d2b74ea73095f11643e0fcc937",
+		"6def83eade7a3e8ca3bde6a3458c3b4921b3b3ac",
 		"a4a65d240ab4b23737f4d68d8765cca89cf08864",
 		"bdb111213cced70583157edad658247972dcbe45",
 		"dc50d048164ade2926b58dee48c3919c6b7d9558"

package/src/schemas/results.ts

@@ -30,6 +30,11 @@ export const PlanResult = z.strictObject({
 					.boolean()
 					.describe("true when it is split out of this issue"),
 				column: z.enum(["ideas", "planning"]),
+				blockedBy: z
+					.array(z.number().int().min(0))
+					.describe(
+						"What must merge first: 0 is this issue, n is the nth entry in newIssues (1-based). Empty when independent.",
+					),
 			}),
 		)
 		.describe("Issues to create, e.g. when the human asks to split work."),

package/templates/.agents/skills/issue-splitting/SKILL.md

@@ -21,7 +21,7 @@ Split when any of these hold:
 
 ## INVEST check for each slice
 
-- **Independent**: can merge in any order relative to sibling slices, or the order is explicit.
+- **Independent**: can merge in any order relative to sibling slices, or the order is explicit in `blockedBy`.
 - **Negotiable**: describes the need, leaves room in how.
 - **Valuable**: a user or operator notices something, even if small.
 - **Estimable**: no unbounded unknowns; otherwise spike first.
@@ -61,6 +61,10 @@ Ask: what is the least we could ship that someone would use or that teaches us s
 - **Idea** (`subIssue: false`, column `ideas`): related but a different need, a nice-to-have you noticed, or tech debt discovered along the way.
 - **Neither**: things that are just part of doing this slice well. Keep them in the plan.
 
+## Order
+
+kanbot won't start a Ready card while its `blockedBy` issues are open. Set `blockedBy` on each slice to what must merge first; usually the previous slice. Leave it empty only when the slice truly stands alone.
+
 When splitting, this issue keeps the first slice. Rewrite its plan to cover only that slice and list the other slices under `## Out of scope` with a note that they were proposed as new issues.
 
 ## Body for each new slice

package/templates/.agents/skills/kanbot-guide/SKILL.md

@@ -19,7 +19,8 @@ Explain in plain words. Ask before choosing for them; give a recommendation with
 | How do I file ideas by chatting?              | `capturing-ideas`   |
 | My own PRs, local sessions, direct commits?   | `outside-the-board` |
 | Which agents are there, how do I change them? | `agents`            |
-| Skills and project memory?                    | `skills`            |
+| Skills?                                       | `skills`            |
+| Project memory, facts from corrections        | `project-memory`    |
 | Claude or Codex?                              | `providers`         |
 | Every config field, labels, notifications     | `configuration`     |
 | Using our own skills and agents for the work  | `capabilities`      |
@@ -32,7 +33,7 @@ Explain in plain words. Ask before choosing for them; give a recommendation with
 
 Ideas (you write) → Planning (agent plans, you comment) → Ready (you approve by moving the card) → In Progress (agent builds, opens a PR) → Review (technical, then acceptance review, with fixes; you comment) → Done (you merge, or approve and kanbot merges).
 
-kanbot runs the process; the repo's own skills and agents do the work on code, through capabilities. Plans list assumptions about user need; open questions keep a card from starting in Ready.
+kanbot runs the process; the repo's own skills and agents do the work on code, through capabilities. Plans list assumptions about user need; open questions and open "blocked by" issues keep a card from starting in Ready.
 
 Agents never get a GitHub token. The daemon does every comment, push and PR. Only collaborators with write access can steer agents. Workers see only what's committed, including MCP servers in `.mcp.json`; never the user's own plugins or servers.
 
@@ -102,9 +103,9 @@ Warn: never enable the branch rule "Require approval of the most recent reviewab
 ## Troubleshoot
 
 1. `kanbot doctor`: prints a fix for each failed check.
-2. `kanbot status`: board by column, daemon, failures, rate-limit pause.
+2. `kanbot status`: board by column, what waits on the user (oldest first), daemon, failures, rate-limit pause.
 3. `.kanbot/logs/*.jsonl`: full agent transcripts.
 4. `needs-human` label: the issue has a comment saying why. Fix the cause, then remove the label to retry.
 5. Nothing happens: is the daemon running, are kanbot files pushed to the base branch, is the card in an active column?
-6. Card stays in Ready: the plan has open questions. kanbot commented on the issue. Answer them in Planning, or remove them from the plan.
+6. Card stays in Ready: the plan has open questions, or the issue is blocked by open issues. kanbot commented why. Answer questions in Planning; blocked cards start when the blockers close.
 7. Agent didn't use a skill: is it mapped under `capabilities`, does its `when` fit, and is it committed?

package/templates/.kanbot/agents/planner.md

@@ -48,6 +48,6 @@ Return the structured result; it is your only channel to GitHub.
 - `plan`: the complete plan markdown. It replaces the previous plan entirely, so include unchanged sections too.
 - `summary`: one sentence to the human on what changed this round.
 - `replies`: exactly one entry per input human comment, keyed by its `commentId`. Answer the question or say what you changed in the plan. One or two sentences; disagreeing is fine if you give the reason.
-- `newIssues`: slices split from this issue (`subIssue: true`, `column: planning` when ready to plan next, `ideas` otherwise) and unrelated ideas you noticed (`subIssue: false`, `column: ideas`). Each body is a user story, a one-line need and draft acceptance criteria. Empty when there is nothing to split.
+- `newIssues`: slices split from this issue (`subIssue: true`, `column: planning` when ready to plan next, `ideas` otherwise) and unrelated ideas you noticed (`subIssue: false`, `column: ideas`). Each body is a user story, a one-line need and draft acceptance criteria. Empty when there is nothing to split. `blockedBy` says what must merge first: `0` is this issue, `n` the nth new issue. Slices default to the previous one (slice 2: `[0]`, slice 3: `[1]`); use `[]` only when a slice can truly merge in any order. Ideas get `[]`.
 - `labels`: `technical` when it is not a user-facing story; otherwise empty. Keep any `explore:N` label that is present.
 - `questions`: questions only the human can answer, each answerable in one line. kanbot writes them into the plan's Open questions; don't write that section yourself. Empty if none.