kanbot 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Brevik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+<img src="docs/public/logo.svg#gh-light-mode-only" alt="kanbot logo" width="96">
+<img src="docs/public/logo-dark.svg#gh-dark-mode-only" alt="kanbot logo" width="96">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 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.
+
+```mermaid
+flowchart LR
+  Ideas["Ideas<br/><i>you write</i>"] --> Planning["Planning<br/><i>agent plans, you comment</i>"]
+  Planning --> Ready["Ready<br/><i>you approve</i>"]
+  Ready --> InProgress["In Progress<br/><i>agents build</i>"]
+  InProgress --> Review["Review<br/><i>agents review, you comment</i>"]
+  Review --> Done["Done<br/><i>you merge</i>"]
+```
+
+Full docs: [docs/](./docs/00-index.md). Demo video: [docs/assets/demo.mp4](./docs/assets/demo.mp4).
+
+## How it works
+
+| Column          | What happens                                                                                                                                     |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Ideas**       | Backlog of ideas and tasks. Not touched by any agents.                                                                                           |
+| **Planning**    | An agent writes a plan into the issue. Comment to revise it.                                                                                     |
+| **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.                                                                                                                                       |
+
+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.
+
+## Setup
+
+Requires [Bun](https://bun.sh) ≥ 1.3, `gh` logged in, and `claude` or `codex` logged in.
+
+```sh
+gh auth refresh -s project
+cd your-repo
+bunx kanbot init --provider claude   # or codex
+kanbot board create                  # then enable the built-in workflows it prints
+git add -A && git commit -m "chore: add kanbot" && git push
+kanbot doctor
+kanbot run
+```
+
+Use `kanbot run --once --dry-run` to see what it would do. Run one daemon per repo.
+
+## Labels
+
+| Label                                 | Meaning                                           |
+| ------------------------------------- | ------------------------------------------------- |
+| `technical`                           | Plan as a technical goal, not a user story        |
+| `type:frontend\|backend\|docs\|infra` | Picks the implementer agent (the planner sets it) |
+| `explore:2..4`                        | Build N alternative approaches as N PRs           |
+| `agent-reviewed`                      | Passed agent review; ready for you                |
+| `needs-human`                         | Agents gave up. Remove it to retry.               |
+| `kanbot-review`                       | Agent review for your own PR, without a card      |
+
+## Beyond the board
+
+- **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)
+
+## 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.
+
+## 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).
+
+## Shell completion
+
+```sh
+echo 'source <(kanbot completion)' >> ~/.zshrc     # or ~/.bashrc
+kanbot completion --shell fish > ~/.config/fish/completions/kanbot.fish
+```
+
+The shell is detected from `$SHELL`; pass `--shell zsh|bash|fish` to override. For zsh, `compinit` must run first.
+
+## Operating
+
+- `kanbot status` shows the board, daemon and failures.
+- `.kanbot/logs/*.jsonl` has every agent transcript.
+
+## Limitations
+
+- Ready-column order is the project's manual item order, not a view's sort.
+- Workers run as your user. `gh` and `git push` are blocked by command patterns, not missing credentials, so a determined prompt injection could get around them.
+
+## Development
+
+```sh
+pnpm install
+bun test
+pnpm check
+pnpm typecheck
+```
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org). A `commit-msg` hook and CI lint them.
+
+### Releasing
+
+1. Merge or push conventional commits to `main`.
+2. A draft release updates with the next version and notes. `feat` bumps minor, `fix` patch. On 0.x, breaking changes bump minor.
+3. Publish the draft on GitHub. This tags the commit, publishes to npm with provenance, and commits the version to `package.json` on `main`.
+
+Preview the next release with `pnpm release:preview`. Mark the draft as a pre-release to publish under the `next` tag.

package/package.json

@@ -1,6 +1,76 @@
 {
-  "name": "kanbot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "kanbot",
+	"version": "0.2.0",
+	"description": "Run an autonomous dev team (Claude Code or Codex) from a GitHub Project board",
+	"type": "module",
+	"license": "MIT",
+	"author": "Mikael Brevik",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/mikaelbr/kanbot.git"
+	},
+	"homepage": "https://github.com/mikaelbr/kanbot#readme",
+	"bugs": "https://github.com/mikaelbr/kanbot/issues",
+	"keywords": [
+		"github",
+		"kanban",
+		"agents",
+		"claude-code",
+		"codex",
+		"automation",
+		"cli"
+	],
+	"bin": {
+		"kanbot": "src/cli.ts"
+	},
+	"files": [
+		"src",
+		"templates",
+		"schema"
+	],
+	"engines": {
+		"bun": ">=1.3"
+	},
+	"scripts": {
+		"kanbot": "bun src/cli.ts",
+		"test": "bun test",
+		"check": "biome check .",
+		"fix": "biome check --write .",
+		"typecheck": "tsc --noEmit",
+		"schema": "bun -e \"await Bun.write('schema/config.schema.json', (await import('./src/config.ts')).renderConfigSchema())\"",
+		"docs:dev": "pnpm --dir site dev",
+		"docs:build": "pnpm --dir site build",
+		"hashes": "bun scripts/known-hashes.ts",
+		"prepublishOnly": "bun run check && bun run typecheck && bun test",
+		"prepare": "lefthook install",
+		"release:preview": "git-cliff --unreleased --bump --strip all && git-cliff --bumped-version"
+	},
+	"dependencies": {
+		"citty": "^0.2.2",
+		"node-notifier": "^12.1.0",
+		"yaml": "^2.9.1",
+		"zod": "^4.6.7"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.6.4",
+		"@commitlint/cli": "^21.2.4",
+		"@commitlint/config-conventional": "^21.2.4",
+		"@types/bun": "^1.4.4",
+		"git-cliff": "^2.14.2",
+		"lefthook": "^2.2.2",
+		"typescript": "^7.0.2"
+	},
+	"commitlint": {
+		"extends": [
+			"@commitlint/config-conventional"
+		],
+		"rules": {
+			"body-max-line-length": [
+				0
+			],
+			"footer-max-line-length": [
+				0
+			]
+		}
+	}
+}

package/schema/config.schema.json

@@ -0,0 +1,206 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"properties": {
+		"provider": {
+			"default": "claude",
+			"description": "Agent CLI that runs workers.",
+			"type": "string",
+			"enum": ["claude", "codex"]
+		},
+		"repo": {
+			"type": "string",
+			"pattern": "^[^/]+\\/[^/]+$",
+			"description": "GitHub repo as owner/name."
+		},
+		"baseBranch": {
+			"default": "main",
+			"description": "Branch agents work from.",
+			"type": "string"
+		},
+		"project": {
+			"default": null,
+			"description": "GitHub Project board. Set by `kanbot board create`.",
+			"anyOf": [
+				{
+					"type": "object",
+					"properties": {
+						"owner": {
+							"type": "string"
+						},
+						"number": {
+							"type": "integer",
+							"minimum": -9007199254740991,
+							"maximum": 9007199254740991
+						}
+					},
+					"required": ["owner", "number"]
+				},
+				{
+					"type": "null"
+				}
+			]
+		},
+		"columns": {
+			"description": "Names of the board's Status options.",
+			"default": {},
+			"type": "object",
+			"properties": {
+				"ideas": {
+					"default": "Ideas",
+					"type": "string"
+				},
+				"planning": {
+					"default": "Planning",
+					"type": "string"
+				},
+				"ready": {
+					"default": "Ready",
+					"type": "string"
+				},
+				"inProgress": {
+					"default": "In Progress",
+					"type": "string"
+				},
+				"review": {
+					"default": "Review",
+					"type": "string"
+				},
+				"done": {
+					"default": "Done",
+					"type": "string"
+				}
+			}
+		},
+		"concurrency": {
+			"default": 3,
+			"description": "Max concurrent agent workers. Each exploratory variant is one worker.",
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 9007199254740991
+		},
+		"pollSeconds": {
+			"default": 60,
+			"description": "Seconds between board polls.",
+			"type": "integer",
+			"minimum": 10,
+			"maximum": 9007199254740991
+		},
+		"priority": {
+			"default": ["fix", "review", "plan", "implement"],
+			"description": "Order in which waiting jobs get free slots.",
+			"type": "array",
+			"items": {
+				"type": "string",
+				"enum": ["fix", "review", "plan", "implement"]
+			}
+		},
+		"maxAttempts": {
+			"default": 2,
+			"description": "Attempts per job before the issue is labeled needs-human.",
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 9007199254740991
+		},
+		"timeoutMinutes": {
+			"description": "Per-job timeout in minutes.",
+			"default": {},
+			"type": "object",
+			"properties": {
+				"plan": {
+					"default": 20,
+					"type": "number"
+				},
+				"implement": {
+					"default": 90,
+					"type": "number"
+				},
+				"review": {
+					"default": 30,
+					"type": "number"
+				},
+				"fix": {
+					"default": 45,
+					"type": "number"
+				}
+			}
+		},
+		"implementers": {
+			"default": {
+				"frontend": "implementer-frontend",
+				"backend": "implementer-backend",
+				"docs": "implementer-docs",
+				"infra": "implementer-technical",
+				"default": "implementer-backend"
+			},
+			"description": "Maps a type:<key> label to an agent. `default` is the fallback.",
+			"type": "object",
+			"propertyNames": {
+				"type": "string"
+			},
+			"additionalProperties": {
+				"type": "string"
+			}
+		},
+		"review": {
+			"default": {},
+			"type": "object",
+			"properties": {
+				"copilot": {
+					"default": false,
+					"description": "Wait for GitHub Copilot's code review and have the fixer address its comments. Needs a paid Copilot plan; each review uses credits.",
+					"type": "boolean"
+				},
+				"copilotOnPush": {
+					"default": false,
+					"description": "Have Copilot review again after every push. One review per push.",
+					"type": "boolean"
+				},
+				"copilotWaitMinutes": {
+					"default": 15,
+					"description": "Minutes to wait for Copilot's review before going on without it.",
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 9007199254740991
+				}
+			}
+		},
+		"codex": {
+			"default": {},
+			"type": "object",
+			"properties": {
+				"networkAccess": {
+					"default": false,
+					"description": "Let codex workers reach the network (package installs).",
+					"type": "boolean"
+				}
+			}
+		},
+		"notify": {
+			"default": {},
+			"type": "object",
+			"properties": {
+				"desktop": {
+					"default": true,
+					"description": "Show desktop notifications.",
+					"type": "boolean"
+				},
+				"webhook": {
+					"default": null,
+					"description": "POSTs {title, message, url} as JSON, e.g. an ntfy.sh topic URL.",
+					"anyOf": [
+						{
+							"type": "string",
+							"format": "uri"
+						},
+						{
+							"type": "null"
+						}
+					]
+				}
+			}
+		}
+	},
+	"required": ["repo"],
+	"title": "kanbot config"
+}

package/src/agents/load.ts

@@ -0,0 +1,105 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+import { UserError } from "../errors.ts";
+import { RESULT_SCHEMAS } from "../schemas/results.ts";
+
+export const TOOL_CAPABILITIES = ["read", "edit", "bash", "web"] as const;
+
+const Frontmatter = z.object({
+	name: z.string().regex(/^[a-z][a-z0-9-]*$/),
+	tier: z.enum(["column", "sub"]),
+	description: z.string(),
+	models: z
+		.object({ claude: z.string().optional(), codex: z.string().optional() })
+		.default({}),
+	effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
+	tools: z.array(z.enum(TOOL_CAPABILITIES)).default(["read"]),
+	skills: z.array(z.string()).default([]),
+	subagents: z.array(z.string()).default([]),
+	output: z
+		.enum(Object.keys(RESULT_SCHEMAS) as [keyof typeof RESULT_SCHEMAS])
+		.optional(),
+});
+
+export type AgentDef = z.infer<typeof Frontmatter> & {
+	/** Markdown instructions after the frontmatter. */
+	body: string;
+	file: string;
+};
+
+export function agentsDir(root: string) {
+	return join(root, ".kanbot", "agents");
+}
+
+export function parseAgent(text: string, file: string): AgentDef {
+	const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+	if (!m) throw invalid(file, "Missing YAML frontmatter between `---` lines.");
+	const fm = Frontmatter.safeParse(parse(m[1] as string));
+	if (!fm.success) {
+		throw invalid(file, z.prettifyError(fm.error));
+	}
+	return { ...fm.data, body: (m[2] as string).trim(), file };
+}
+
+export async function loadAgents(root: string): Promise<AgentDef[]> {
+	const dir = agentsDir(root);
+	if (!existsSync(dir)) {
+		throw new UserError("kanbot agents are missing.", {
+			why: "No .kanbot/agents directory in this repo.",
+			fix: "kanbot init (or kanbot upgrade to restore missing files)",
+			docs: "getting-started#set-up-a-repository",
+		});
+	}
+	const files = (await readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+	const agents = await Promise.all(
+		files.map(async (f) =>
+			parseAgent(await Bun.file(join(dir, f)).text(), join(dir, f)),
+		),
+	);
+	validate(agents);
+	return agents;
+}
+
+function validate(agents: AgentDef[]) {
+	const names = new Set(agents.map((a) => a.name));
+	if (names.size !== agents.length) {
+		throw new UserError("Duplicate agent names in .kanbot/agents.", {
+			why: "Two agent files declare the same `name`.",
+			fix: "Give each agent a unique name matching its filename.",
+			docs: "agents#frontmatter",
+		});
+	}
+	for (const a of agents) {
+		if (!a.file.endsWith(`${a.name}.md`)) {
+			throw invalid(a.file, `name "${a.name}" must match the filename.`);
+		}
+		if (a.tier === "column" && !a.output) {
+			throw invalid(a.file, "Column agents must declare an `output` schema.");
+		}
+		for (const s of a.subagents) {
+			const sub = agents.find((x) => x.name === s);
+			if (!sub)
+				throw invalid(a.file, `Unknown subagent "${s}" in \`subagents\`.`);
+			if (sub.tier !== "sub") {
+				throw invalid(a.file, `Subagent "${s}" must have \`tier: sub\`.`);
+			}
+		}
+	}
+}
+
+function invalid(file: string, why: string) {
+	return new UserError(`Invalid agent file ${file}`, {
+		why,
+		fix: "Fix the file, then run `kanbot sync`.",
+		docs: "agents#frontmatter",
+	});
+}
+
+export function getAgent(agents: AgentDef[], name: string): AgentDef {
+	const a = agents.find((x) => x.name === name);
+	if (!a) throw new Error(`No agent named "${name}" in .kanbot/agents`);
+	return a;
+}