kanbot 0.4.1 → 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.1",
+	"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/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.