kanbot 0.5.0 → 0.5.2

package/README.md

@@ -4,7 +4,7 @@
 # kanbot
 
 Run an autonomous dev team from a GitHub Project board. You define, specify and prioritize work while Claude or Codex agents work as your team.
-Uses subscriptions for Claude or Codex, and does not require API usage. The agents are fully autonomous, but you can comment on their work and steer them as needed.
+It runs on your Claude or Codex subscription, not API keys. Agents work on their own, and you steer them by commenting.
 
 ```mermaid
 flowchart LR
@@ -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/11-identity.md#merge-on-approval)).                                         |
+| **Done**        | You merge, or approve and kanbot merges ([`merge.onApproval`](./docs/12-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/11-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/12-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/08-project-memory.md)
-- **Copilot review.** Optionally add GitHub Copilot as a cloud reviewer. [More](./docs/12-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.
+- `.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/13-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
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kanbot",
-	"version": "0.5.0",
+	"version": "0.5.2",
 	"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/known-hashes.json

@@ -18,13 +18,15 @@
 	],
 	".agents/skills/kanbot-guide/SKILL.md": [
 		"1251194ba34a8b6eae8508037b0a76c60d7a26b8",
+		"1329454d5b81912e856591caa036c93f88ef8c69",
 		"2c6c77a225c5b880eff023d4b3c1305bfc91bfb3",
 		"2ccb86b12e5af121b79ef9f53c2a35dbbdb2ddeb",
 		"53c73b1be4a1e8d863a52043eae4ca911c8be71b",
 		"a24c0a655d6485e65bd5dea2a71f3afe67f04404",
 		"b5a2d074ea61f2552890ca1d78bf8a043d7b73b3",
 		"bde0364d60525598bbb28f1648d06d1407c62a73",
-		"cf3e95d137a5a58a273262bca6ba25fbc95fa037"
+		"cf3e95d137a5a58a273262bca6ba25fbc95fa037",
+		"f9b76db4afbad14ad9d14dff805c71703099bdeb"
 	],
 	".agents/skills/kanbot-idea/SKILL.md": [
 		"8ab28cec8d3f30250ffe080106d0de8e3c2eaa8a",

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/kanbot-guide/SKILL.md

@@ -12,22 +12,23 @@ 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?                                       | `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`      |
-| 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
 
@@ -43,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.