kanbot 0.4.1 → 0.5.1

package/README.md

@@ -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/09-project-memory.md)
+- **Copilot review.** Optionally add GitHub Copilot as a cloud reviewer. [More](./docs/13-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)
+- `.agents/skills/`: skills shared by agents. Fill in [`project-conventions`](./docs/08-project-conventions.md) first.
+- `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/14-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.1",
+	"version": "0.5.1",
 	"description": "Run an autonomous dev team (Claude Code or Codex) from a GitHub Project board",
 	"type": "module",
 	"license": "MIT",

package/src/cli.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env bun
 import { runCommand, runMain } from "citty";
 import { formatError } from "./errors.ts";
+import { log } from "./log.ts";
 import { main } from "./main.ts";
+import { versionNotice } from "./templates.ts";
 
 const args = process.argv.slice(2);
 const usage =
@@ -13,6 +15,11 @@ const usage =
 if (usage) {
 	await runMain(main);
 } else {
+	// These set the version themselves, report it, or print shell code.
+	if (!["init", "upgrade", "doctor", "completion"].includes(args[0] ?? "")) {
+		const notice = await versionNotice(process.cwd());
+		if (notice) log.warn(notice);
+	}
 	try {
 		await runCommand(main, { rawArgs: args });
 	} catch (e) {

package/src/commands/doctor.ts

@@ -21,7 +21,13 @@ import {
 	type McpServer,
 	readMcpServers,
 } from "../providers/mcp.ts";
-import { NEW_SUFFIX, pendingMerges, planUpgrade } from "../templates.ts";
+import {
+	FILL_IN,
+	NEW_SUFFIX,
+	pendingMerges,
+	planUpgrade,
+	unfilledTemplates,
+} from "../templates.ts";
 import { REPO_LABELS } from "./board.ts";
 
 type Check = {
@@ -323,6 +329,31 @@ export default defineCommand({
 			fix: `merge each into the file next to it and delete it (kanbot-admin skill can help)`,
 		});
 
+		const unfilled = await unfilledTemplates(root);
+		for (const path of FILL_IN) {
+			const u = unfilled.find((x) => x.path === path);
+			const conventions = path.includes("project-conventions");
+			add({
+				name: `${path} filled in`,
+				ok: true,
+				warn: !!u,
+				detail: u?.detail,
+				why: u
+					? conventions
+						? "Every agent reads it first for commands and conventions. Until it's filled in, they guess."
+						: "Agents fix failing CI, so it should run your real install, lint and test commands."
+					: undefined,
+				fix: u
+					? conventions
+						? "replace each <placeholder> and delete the TEMPLATE note (kanbot-guide skill can help)"
+						: "replace the starter steps with your stack's commands"
+					: undefined,
+				docs: conventions
+					? "project-conventions#fill-it-in"
+					: "getting-started#set-up-a-repository",
+			});
+		}
+
 		section(`Pushed to origin/${config.baseBranch}`);
 		await git(root, "fetch", "origin", config.baseBranch).catch(() => {});
 		const tree = await git(

package/src/commands/init.ts

@@ -5,7 +5,7 @@ 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 { DOCS_URL, UserError } from "../errors.ts";
 import { run } from "../github/gh.ts";
 import { log } from "../log.ts";
 import { applyUpgrade, NEW_SUFFIX, planUpgrade } from "../templates.ts";
@@ -111,6 +111,7 @@ export default defineCommand({
 		console.log(`
 Next steps:
   1. Review AGENTS.md and fill in .agents/skills/project-conventions/SKILL.md
+     (ask your agent to draft it; see ${DOCS_URL}/project-conventions)
   2. Adjust .github/workflows/ci.yml to your stack (agents fix failing CI)
   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

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",
@@ -17,10 +18,15 @@
 	],
 	".agents/skills/kanbot-guide/SKILL.md": [
 		"1251194ba34a8b6eae8508037b0a76c60d7a26b8",
+		"1329454d5b81912e856591caa036c93f88ef8c69",
 		"2c6c77a225c5b880eff023d4b3c1305bfc91bfb3",
 		"2ccb86b12e5af121b79ef9f53c2a35dbbdb2ddeb",
+		"53c73b1be4a1e8d863a52043eae4ca911c8be71b",
 		"a24c0a655d6485e65bd5dea2a71f3afe67f04404",
-		"cf3e95d137a5a58a273262bca6ba25fbc95fa037"
+		"b5a2d074ea61f2552890ca1d78bf8a043d7b73b3",
+		"bde0364d60525598bbb28f1648d06d1407c62a73",
+		"cf3e95d137a5a58a273262bca6ba25fbc95fa037",
+		"f9b76db4afbad14ad9d14dff805c71703099bdeb"
 	],
 	".agents/skills/kanbot-idea/SKILL.md": [
 		"8ab28cec8d3f30250ffe080106d0de8e3c2eaa8a",
@@ -104,6 +110,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/src/templates.ts

@@ -54,6 +54,18 @@ export async function readManifest(root: string): Promise<Manifest | null> {
 	return (await file.exists()) ? ((await file.json()) as Manifest) : null;
 }
 
+/** Warning when this repo's templates and the running kanbot differ in version. */
+export async function versionNotice(root: string, current = pkg.version) {
+	const installed = (await readManifest(root).catch(() => null))?.version;
+	if (!installed) return null;
+	const order = Bun.semver.order(installed, current);
+	if (order < 0)
+		return `kanbot ${current} is out, this repo has ${installed}. Run \`kanbot upgrade\` to get the new agents, skills and workflows.`;
+	if (order > 0)
+		return `This repo uses kanbot ${installed}, but you run ${current}. Use \`bunx kanbot@latest\`.`;
+	return null;
+}
+
 async function writeManifest(root: string, files: Record<string, string>) {
 	const sorted = Object.fromEntries(
 		Object.entries(files).sort(([a], [b]) => a.localeCompare(b)),
@@ -191,3 +203,54 @@ export async function pendingMerges(root: string, dir = TEMPLATES) {
 	const paths = [...(await listTemplates(dir)).keys()];
 	return paths.filter((p) => existsSync(join(root, `${p}${NEW_SUFFIX}`)));
 }
+
+/** User templates you are meant to fill in after install. */
+export const FILL_IN = [
+	".agents/skills/project-conventions/SKILL.md",
+	".github/workflows/ci.yml",
+];
+
+const clip = (s: string) => (s.length > 72 ? `${s.slice(0, 71)}…` : s);
+
+export type Unfilled = { path: string; detail: string };
+
+/**
+ * Fill-in templates still unedited, or still holding the template's
+ * `<placeholder>`s. Missing files are left to other checks.
+ */
+export async function unfilledTemplates(
+	root: string,
+	opts: Pick<Options, "templates" | "known"> = {},
+): Promise<Unfilled[]> {
+	const templates = await listTemplates(opts.templates);
+	const known: Record<string, string[]> = opts.known ?? knownHashes;
+	const out: Unfilled[] = [];
+	for (const path of FILL_IN) {
+		const tpl = templates.get(path);
+		const file = Bun.file(join(root, path));
+		if (!tpl || !(await file.exists())) continue;
+		const bytes = await file.bytes();
+		const current = hash(bytes);
+		if (current === hash(tpl) || (known[path] ?? []).includes(current)) {
+			out.push({ path, detail: "unchanged from the template" });
+			continue;
+		}
+		const placeholders = new Set(
+			new TextDecoder().decode(tpl).match(/<[^<>`\n]+>/g) ?? [],
+		);
+		const left = new TextDecoder()
+			.decode(bytes)
+			.split("\n")
+			.flatMap((line, i) =>
+				[...placeholders].some((p) => line.includes(p))
+					? [`line ${i + 1}: ${clip(line.trim())}`]
+					: [],
+			);
+		if (left.length)
+			out.push({
+				path,
+				detail: `${left.length} line(s) with placeholders left:\n${left.slice(0, 5).join("\n")}${left.length > 5 ? "\n…" : ""}`,
+			});
+	}
+	return out;
+}

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

@@ -12,27 +12,29 @@ Explain in plain words. Ask before choosing for them; give a recommendation with
 
 ## Docs
 
-| Question                                      | Slug                |
-| --------------------------------------------- | ------------------- |
-| How do I install and set up a repo?           | `getting-started`   |
-| How does a card move across the board?        | `workflow`          |
-| 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`            |
-| Claude or Codex?                              | `providers`         |
-| Every config field, labels, notifications     | `configuration`     |
-| Using our own skills and agents for the work  | `capabilities`      |
-| Copilot as an extra reviewer                  | `copilot-review`    |
-| Bot or user identity, merge by approving      | `identity`          |
-| Upgrading and `.kanbot-new` files             | `upgrading`         |
-| Every command and flag                        | `usage`             |
+| Question                                      | Slug                  |
+| --------------------------------------------- | --------------------- |
+| How do I install and set up a repo?           | `getting-started`     |
+| How does a card move across the board?        | `workflow`            |
+| How do I add or file ideas?                   | `capturing-ideas`     |
+| My own PRs, local sessions, direct commits?   | `outside-the-board`   |
+| Which agents are there, how do I change them? | `agents`              |
+| Skills?                                       | `skills`              |
+| Filling in stack, commands and rules          | `project-conventions` |
+| 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`        |
+| Copilot as an extra reviewer                  | `copilot-review`      |
+| Bot or user identity, merge by approving      | `identity`            |
+| Upgrading and `.kanbot-new` files             | `upgrading`           |
+| Every command and flag                        | `usage`               |
 
 ## Board flow
 
 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.
 
@@ -42,7 +44,7 @@ Go step by step. Run each command, check its output, then go on. If `.kanbot/con
 
 1. **Requirements.** Bun 1.3+, `gh` logged in, `claude` or `codex` logged in with a subscription (not an API key). Run `gh auth refresh -s project`.
 2. **Provider.** Ask which subscription they have, then `bunx kanbot init --provider claude|codex` in the repo root.
-3. **Conventions.** Fill in `.agents/skills/project-conventions/SKILL.md` with them: stack, commands to test, lint and typecheck. Adjust `.github/workflows/ci.yml` to run the same. Every agent reads this first.
+3. **Conventions.** Fill in `.agents/skills/project-conventions/SKILL.md` with them: stack, commands to test, lint and typecheck. Adjust `.github/workflows/ci.yml` to run the same. Every agent reads this first. Draft it from manifests and CI, ask what you can't find, and have them run each command. Link `project-conventions`.
 4. **Capabilities.** kanbot runs the process; the repo's own skills and agents do the work. Ask which skills they have for proving acceptance criteria (`verify`), technical review (`review`) and something a human can try (`preview`), and map them under `capabilities` in `.kanbot/config.yml`. See [Capabilities](#capabilities).
 5. **Board.** `kanbot board create`, or `kanbot board link --owner <login> --number <n>` for an existing project. Have them enable the four built-in project workflows it prints; they can't be set through the API.
 6. **Options.** Go through [Choose options](#choose-options). For app mode, run `kanbot app create` and have them install the app on the repo.
@@ -102,9 +104,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.