kanbot 0.0.0-stage → 0.1.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,103 @@
-# 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
+```

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "kanbot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "kanbot",
+	"version": "0.1.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"
+	},
+	"dependencies": {
+		"citty": "^0.2.2",
+		"node-notifier": "^12.1.0",
+		"yaml": "^2.9.1",
+		"zod": "^4.6.7"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.6.4",
+		"@types/bun": "^1.4.4",
+		"typescript": "^7.0.2"
+	}
+}

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,83 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { z } from "zod";
+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 new Error(`${file}: missing YAML frontmatter`);
+	const fm = Frontmatter.safeParse(parse(m[1] as string));
+	if (!fm.success) {
+		throw new Error(`${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);
+	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 Error("Duplicate agent names in .kanbot/agents");
+	}
+	for (const a of agents) {
+		if (!a.file.endsWith(`${a.name}.md`)) {
+			throw new Error(`${a.file}: name "${a.name}" must match the filename`);
+		}
+		if (a.tier === "column" && !a.output) {
+			throw new Error(`${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 new Error(`${a.file}: unknown subagent "${s}"`);
+			if (sub.tier !== "sub") {
+				throw new Error(`${a.file}: "${s}" is not a tier: sub agent`);
+			}
+		}
+	}
+}
+
+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;
+}

package/src/agents/sync.ts

@@ -0,0 +1,216 @@
+import { existsSync, lstatSync } from "node:fs";
+import { mkdir, readdir, rm, symlink } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { configPath, loadConfig } from "../config.ts";
+import type { AgentDef } from "./load.ts";
+
+/*
+ * .kanbot/agents/*.md is the single source of truth. This module renders it
+ * into each CLI's native format so agents work both headless (driven by the
+ * daemon) and in interactive sessions:
+ *   Claude: .claude/agents/<name>.md + .claude/settings.json permissions
+ *   Codex:  .codex/agents/<name>.toml
+ * Skills live in .agents/skills (Codex native); .claude/skills symlinks to it.
+ */
+
+export const GENERATED =
+	"generated by kanbot — edit .kanbot/agents/ and run `kanbot sync`";
+
+const CLAUDE_TOOLS: Record<string, string[]> = {
+	read: ["Read", "Grep", "Glob"],
+	edit: ["Edit", "Write", "NotebookEdit"],
+	bash: ["Bash"],
+	web: ["WebFetch", "WebSearch"],
+};
+
+/** Agents never touch GitHub; the daemon owns all remote side effects. */
+export const CLAUDE_DENY = [
+	"Bash(gh *)",
+	"Bash(git push *)",
+	"Bash(git remote *)",
+	"Bash(git config *)",
+];
+
+/** Agents act as the human's account: no Claude co-author trailers or PR footers. */
+export const CLAUDE_ATTRIBUTION = {
+	attribution: { commit: "", pr: "" },
+	includeCoAuthoredBy: false,
+};
+
+export function claudeTools(agent: AgentDef): string[] {
+	const tools = agent.tools.flatMap((t) => CLAUDE_TOOLS[t] ?? []);
+	if (agent.skills.length) tools.push("Skill");
+	if (agent.subagents.length) tools.push("Task");
+	return [...new Set(tools)];
+}
+
+export function renderClaudeAgent(agent: AgentDef): string {
+	const fm: Record<string, unknown> = {
+		name: agent.name,
+		description: agent.description,
+		tools: claudeTools(agent).join(", "),
+	};
+	if (agent.models.claude) fm.model = agent.models.claude;
+	if (agent.effort) fm.effort = agent.effort;
+	if (agent.skills.length) fm.skills = agent.skills;
+	return `---\n${stringify(fm).trim()}\n---\n<!-- ${GENERATED} -->\n\n${agentInstructions(agent)}\n`;
+}
+
+export function renderClaudeSettings(agents: AgentDef[]): string {
+	const allow = [...new Set(agents.flatMap(claudeTools))].sort();
+	return `${JSON.stringify(
+		{
+			$comment: GENERATED,
+			permissions: { allow, deny: CLAUDE_DENY },
+			...CLAUDE_ATTRIBUTION,
+		},
+		null,
+		2,
+	)}\n`;
+}
+
+const tomlString = (s: string) => JSON.stringify(s);
+
+export function renderCodexAgent(agent: AgentDef): string {
+	const lines = [
+		`# ${GENERATED}`,
+		`name = ${tomlString(agent.name)}`,
+		`description = ${tomlString(agent.description)}`,
+	];
+	if (agent.models.codex && agent.models.codex !== "default") {
+		lines.push(`model = ${tomlString(agent.models.codex)}`);
+	}
+	if (agent.effort) {
+		const effort = agent.effort === "max" ? "xhigh" : agent.effort;
+		lines.push(`model_reasoning_effort = ${tomlString(effort)}`);
+	}
+	lines.push(
+		`developer_instructions = ${tomlString(agentInstructions(agent))}`,
+	);
+	return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Body plus the parts of the frontmatter that a CLI can't express natively, so
+ * the agent knows which skills and helpers it is expected to use.
+ */
+export function agentInstructions(agent: AgentDef): string {
+	const extra: string[] = [];
+	if (agent.skills.length) {
+		extra.push(
+			`Skills to load when relevant: ${agent.skills.map((s) => `\`${s}\``).join(", ")}.`,
+		);
+	}
+	if (agent.subagents.length) {
+		extra.push(
+			`Subagents you can delegate to: ${agent.subagents.map((s) => `\`${s}\``).join(", ")}. Delegate focused, independent work to them; keep the final decisions yourself.`,
+		);
+	}
+	return extra.length
+		? `${agent.body}\n\n## Toolbox\n\n${extra.join("\n")}`
+		: agent.body;
+}
+
+export type SyncFile = { path: string; content: string };
+
+const COPILOT_INSTRUCTIONS = join(".github", "copilot-instructions.md");
+
+/** Points Copilot code review at the same rules the kanbot reviewers use. */
+export const renderCopilotInstructions =
+	() => `<!-- generated by kanbot from review.copilot in .kanbot/config.yml -->
+
+# Code review
+
+AI agents write most changes in this repo, from a plan in the linked issue. When you review a pull request:
+
+- Use the checklist and severity rubric in \`.agents/skills/code-review/SKILL.md\`.
+- Check the change against the plan in the linked issue and the PR description.
+- Hold it to \`AGENTS.md\`, \`.agents/skills/project-conventions/SKILL.md\` and the facts in \`.agents/skills/project-memory/\`.
+- Comment on real problems: bugs, missing tests, security, broken conventions. Leave style to the linter.
+`;
+
+export function renderAll(agents: AgentDef[]): SyncFile[] {
+	return [
+		...agents.map((a) => ({
+			path: join(".claude", "agents", `${a.name}.md`),
+			content: renderClaudeAgent(a),
+		})),
+		{
+			path: join(".claude", "settings.json"),
+			content: renderClaudeSettings(agents),
+		},
+		...agents.map((a) => ({
+			path: join(".codex", "agents", `${a.name}.toml`),
+			content: renderCodexAgent(a),
+		})),
+	];
+}
+
+/** Writes generated files. Returns paths whose content changed. */
+export async function sync(
+	root: string,
+	agents: AgentDef[],
+	{ check = false } = {},
+): Promise<string[]> {
+	const files = renderAll(agents);
+	const copilot =
+		existsSync(configPath(root)) && (await loadConfig(root)).review.copilot;
+	if (copilot)
+		files.push({
+			path: COPILOT_INSTRUCTIONS,
+			content: renderCopilotInstructions(),
+		});
+	const changed: string[] = [];
+	for (const f of files) {
+		const abs = join(root, f.path);
+		const existing = existsSync(abs) ? await Bun.file(abs).text() : null;
+		if (existing === f.content) continue;
+		changed.push(f.path);
+		if (!check) await Bun.write(abs, f.content);
+	}
+	// Remove generated agents whose source was deleted.
+	const keep = new Set(files.map((f) => f.path));
+	for (const [dir, ext] of [
+		[join(".claude", "agents"), ".md"],
+		[join(".codex", "agents"), ".toml"],
+	] as const) {
+		const abs = join(root, dir);
+		if (!existsSync(abs)) continue;
+		for (const name of await readdir(abs)) {
+			const rel = join(dir, name);
+			if (!name.endsWith(ext) || keep.has(rel)) continue;
+			const text = await Bun.file(join(abs, name)).text();
+			if (!text.includes(GENERATED)) continue;
+			changed.push(rel);
+			if (!check) await rm(join(abs, name));
+		}
+	}
+	const instructions = join(root, COPILOT_INSTRUCTIONS);
+	if (
+		!copilot &&
+		existsSync(instructions) &&
+		(await Bun.file(instructions).text()).includes("generated by kanbot")
+	) {
+		changed.push(COPILOT_INSTRUCTIONS);
+		if (!check) await rm(instructions);
+	}
+	if (!(await linkSkills(root, check))) changed.push(join(".claude", "skills"));
+	return changed;
+}
+
+/** Ensure .claude/skills -> ../.agents/skills. Returns true when already correct. */
+async function linkSkills(root: string, check: boolean) {
+	const link = join(root, ".claude", "skills");
+	const ok = existsSync(link) && lstatSync(link).isSymbolicLink();
+	if (ok || check) return ok;
+	if (existsSync(link)) {
+		throw new Error(
+			".claude/skills exists and is not a symlink. Move its skills into .agents/skills.",
+		);
+	}
+	await mkdir(join(root, ".agents", "skills"), { recursive: true });
+	await mkdir(join(root, ".claude"), { recursive: true });
+	await symlink(join("..", ".agents", "skills"), link);
+	return false;
+}