kanbot 0.3.0 → 0.4.1

package/src/providers/mcp.ts

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/*
+ * Workers get the repo's committed MCP servers, never the user's own.
+ * `.mcp.json` (Claude's format) is the one source for both providers.
+ */
+
+export type McpServer = {
+	type?: string;
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	url?: string;
+	headers?: Record<string, string>;
+};
+
+export function mcpConfigPath(dir: string): string | null {
+	const path = join(dir, ".mcp.json");
+	return existsSync(path) ? path : null;
+}
+
+/** Servers in `<dir>/.mcp.json`. Empty when missing or unreadable. */
+export async function readMcpServers(
+	dir: string,
+): Promise<Record<string, McpServer>> {
+	const path = mcpConfigPath(dir);
+	if (!path) return {};
+	try {
+		const json = (await Bun.file(path).json()) as {
+			mcpServers?: Record<string, McpServer>;
+		};
+		return json.mcpServers ?? {};
+	} catch {
+		return {};
+	}
+}
+
+/** Codex runs stdio and streamable HTTP servers. Others (e.g. sse) are left out. */
+export function codexSupports(s: McpServer): boolean {
+	if (s.type === "sse") return false;
+	return Boolean(s.command || s.url);
+}
+
+const str = (s: string) => JSON.stringify(s);
+const table = (o: Record<string, string>) =>
+	`{${Object.entries(o)
+		.map(([k, v]) => `${str(k)}=${str(v)}`)
+		.join(",")}}`;
+
+/** `-c mcp_servers=…` for codex, as an inline TOML table. Empty when none. */
+export function codexMcpArgs(servers: Record<string, McpServer>): string[] {
+	const entries = Object.entries(servers)
+		.filter(([, s]) => codexSupports(s))
+		.map(([name, s]) => {
+			const fields = s.command
+				? [
+						`command=${str(s.command)}`,
+						s.args?.length ? `args=[${s.args.map(str).join(",")}]` : "",
+						s.env && Object.keys(s.env).length ? `env=${table(s.env)}` : "",
+					]
+				: [
+						`url=${str(s.url as string)}`,
+						s.headers && Object.keys(s.headers).length
+							? `http_headers=${table(s.headers)}`
+							: "",
+					];
+			return `${str(name)}={${fields.filter(Boolean).join(",")}}`;
+		});
+	return entries.length ? ["-c", `mcp_servers={${entries.join(",")}}`] : [];
+}

package/src/schemas/results.ts

@@ -35,7 +35,7 @@ export const PlanResult = z.strictObject({
 		.describe("Issues to create, e.g. when the human asks to split work."),
 	labels: z
 		.array(z.string())
-		.describe("Labels the issue should have, e.g. type:frontend or technical."),
+		.describe("Labels the issue should have, e.g. technical."),
 	questions: z
 		.array(z.string())
 		.describe(
@@ -55,9 +55,6 @@ export const ImplementResult = z.strictObject({
 	testsRun: z
 		.array(z.string())
 		.describe("One line each: command and result, e.g. `bun test`: 5 pass."),
-	screenshots: z
-		.array(z.string())
-		.describe("Repo-relative paths of screenshots committed for review."),
 	risks: z
 		.array(z.string())
 		.describe("Real risks only, one line each. Empty when none."),
@@ -98,7 +95,7 @@ export const FixResult = z.strictObject({
 		.string()
 		.nullable()
 		.describe(
-			"Full updated PR description when your changes made the current one wrong (behaviour, copy, screenshots); null otherwise.",
+			"Full updated PR description when your changes made the current one wrong (behaviour, copy, validation); null otherwise.",
 		),
 });
 export type FixResult = z.infer<typeof FixResult>;

package/templates/.agents/skills/approach-designer/SKILL.md

@@ -17,7 +17,7 @@ Pick the axis where the decision matters most for this problem, then spread appr
 | Interaction model | Search box · faceted filters · timeline browsing                            |
 | Where logic lives | Client-side filtering of loaded data · server query endpoint · search index |
 | Data model        | Denormalised read model · query on existing tables · materialised view      |
-| Build vs. reuse   | Custom component · existing design-system table · third-party library       |
+| Build vs. reuse   | Build it · reuse what the project has · third-party library                 |
 | Timing            | Synchronous · background job with notification · precomputed nightly        |
 | Scope of change   | Minimal tweak to the current screen · new dedicated screen                  |
 

package/templates/.agents/skills/kanbot-admin/SKILL.md

@@ -1,12 +1,12 @@
 ---
 
 name: kanbot-admin
-description: Change this repo's kanbot setup with a human. Use to add or edit kanbot agents, skills or project memory, change `.kanbot/config.yml`, switch identity mode, turn on merge on approval, run `kanbot upgrade` or merge `.kanbot-new` files. Not for board jobs. For setup walkthroughs and explaining options, use kanbot-guide.
+description: Change this repo's kanbot setup with a human. Use to add or edit kanbot agents, skills or project memory, map capabilities, give workers MCP servers, change `.kanbot/config.yml`, switch identity mode, turn on merge on approval, run `kanbot upgrade` or merge `.kanbot-new` files. Not for board jobs. For setup walkthroughs and explaining options, use kanbot-guide.
 ---
 
 # kanbot admin
 
-You are helping a human maintain kanbot, the board-driven agent team in this repo. Board agents (planner, implementers, reviewers, fixer) never use this skill. To explain options or set kanbot up from scratch, use `kanbot-guide`.
+You are helping a human maintain kanbot, the board-driven agent team in this repo. Board agents (planner, implementer, reviewers, fixer) never use this skill. To explain options or set kanbot up from scratch, use `kanbot-guide`.
 
 ## Map
 
@@ -15,6 +15,7 @@ You are helping a human maintain kanbot, the board-driven agent team in this rep
 | `.kanbot/agents/<name>.md` | Agent definitions, the source of truth | Yes, then `kanbot sync`         |
 | `.agents/skills/<name>/`   | Skills shared by all agents            | Yes                             |
 | `.kanbot/config.yml`       | Daemon config; schema next to it       | Yes, then restart the daemon    |
+| `.mcp.json`                | MCP servers workers get                | Yes, then commit                |
 | `.kanbot/manifest.json`    | Template hashes from the last upgrade  | Never by hand                   |
 | `.claude/`, `.codex/`      | Generated by `kanbot sync`             | Never; edit the source and sync |
 | `~/.kanbot/apps/<id>.pem`  | Private key of the kanbot GitHub App   | Never commit                    |
@@ -39,17 +40,32 @@ Back to user mode: set `identity.mode: user`.
 2. Recommend app mode, so they can approve their own kanbot PRs.
 3. Warn: never enable the branch rule "Require approval of the most recent reviewable push". It blocks their own approval.
 
+### Map a capability
+
+kanbot's agents run the process; the repo's own skills and agents do the work on code. Capabilities tell them which to use.
+
+1. Make sure the skill is in `.agents/skills/<name>/` or the agent in `.kanbot/agents/`. A `.claude/agents` or `.codex/agents` agent works on one provider only.
+2. Add it under `capabilities` in config: `review: code-review`, or `{ use, when, required }` when it only applies sometimes or a miss should block acceptance review.
+3. Reserved names: `verify` (prove acceptance criteria), `review` (technical review, pass 1), `preview` (something a human can try). Any other name is the human's.
+4. `kanbot doctor` lists what's mapped, flags a missing `use`, and names reserved needs not yet mapped.
+
+Don't add implementers or `type:*` labels. `implementers` in config is deprecated: replace it with capabilities and remove it.
+
+### Give workers an MCP server
+
+Add it to `.mcp.json` (Claude's format) and commit. Workers get only these servers, never the human's own. Codex can't run `sse` servers; `kanbot doctor` lists what workers get.
+
 ### Add or change an agent
 
 1. Copy the closest existing agent. `name` must match the filename.
 2. Column agents (`tier: column`) need an `output` schema; subagents (`tier: sub`) are reached through a column agent's `subagents`.
-3. A new implementer also needs an entry under `implementers` in config and a matching `type:<x>` label on GitHub. Tell the human to create the label.
+3. To have board agents use it, map it as a capability (above).
 4. The body says _how_ to work. The daemon's prompt carries the task.
 
 ### Add a skill
 
 1. Create `.agents/skills/<name>/SKILL.md` with `name` (matches the folder) and a `description` that says what it covers and when it applies.
-2. Add the name to `skills` in each agent that should load it.
+2. For work on code, map it as a capability. For kanbot's own process, add the name to `skills` in each agent that should load it. `kanbot doctor` fails on skills that don't exist.
 
 ### Add a memory
 
@@ -60,6 +76,7 @@ When the human says "remember that …" or corrects something agents keep gettin
 1. Run `bunx kanbot@latest upgrade --dry-run` and summarise it for the human.
 2. Run `bunx kanbot@latest upgrade`.
 3. Merge every `.kanbot-new` file (below).
+4. Files kanbot no longer ships stay in place. If the repo had kanbot's old craft skills (`verify-ui`, `code-review`, `tdd`…) and no `capabilities`, upgrade maps them. Show the human the new `capabilities` block. Old `implementer-*` and `reviewer-*` agents are unused once the new ones exist; the human may delete them.
 
 ### Merge `.kanbot-new` files
 

package/templates/.agents/skills/kanbot-guide/SKILL.md

@@ -22,6 +22,7 @@ Explain in plain words. Ask before choosing for them; give a recommendation with
 | 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`         |
@@ -29,9 +30,11 @@ Explain in plain words. Ask before choosing for them; give a recommendation with
 
 ## 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 (two agent reviews with fixes; you comment) → Done (you merge, or approve and kanbot merges).
+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).
 
-Agents never get a GitHub token. The daemon does every comment, push and PR. Only collaborators with write access can steer agents.
+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.
+
+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.
 
 ## Guided setup
 
@@ -40,11 +43,25 @@ 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.
-4. **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.
-5. **Options.** Go through [Choose options](#choose-options). For app mode, run `kanbot app create` and have them install the app on the repo.
-6. **Commit and push** the kanbot files. Agents only see what's on the pushed base branch.
-7. **Check.** `kanbot doctor` until it passes, then `kanbot run --once --dry-run`, then `kanbot run`.
-8. **First card.** Have them write an issue, put it in Planning and read the plan. Point to `workflow`.
+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.
+7. **Commit and push** the kanbot files. Agents only see what's on the pushed base branch.
+8. **Check.** `kanbot doctor` until it passes, then `kanbot run --once --dry-run`, then `kanbot run`.
+9. **First card.** Have them write an issue, put it in Planning and read the plan. Point to `workflow`.
+
+## Capabilities
+
+```yaml
+capabilities:
+  verify: { use: e2e-tests, when: Changes users see }
+  preview: { use: deploy-preview, required: true }
+  review: code-review # bare name: no when, not required
+```
+
+- `use`: a skill in `.agents/skills` or an agent in `.kanbot/agents`. `when`: when it applies. `required: true`: a miss blocks acceptance review.
+- Any other name is theirs (`benchmark`, `security`…). Unmapped needs are left to the agent.
+- Suggest, don't install: no `verify` → a skill that runs the app or end-to-end tests; no `preview` → a preview deploy or test build; no `review` → a review skill with their checklist. `kanbot doctor` names what's not mapped.
 
 ## Choose options
 
@@ -89,3 +106,5 @@ Warn: never enable the branch rule "Require approval of the most recent reviewab
 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.
+7. Agent didn't use a skill: is it mapped under `capabilities`, does its `when` fit, and is it committed?

package/templates/.agents/skills/kanbot-idea/SKILL.md

@@ -45,7 +45,7 @@ Match the repo's issue template, so the issue reads like one filed through GitHu
 <notes, or _None._>
 ```
 
-Title: the outcome in under 70 characters. Technical issues get the `technical` label. Leave `type:*` labels to the planner.
+Title: the outcome in under 70 characters. Technical issues get the `technical` label.
 
 Show the title and body. File it only after the human says yes.
 

package/templates/.agents/skills/plan-template/SKILL.md

@@ -20,13 +20,18 @@ Need: <one or two sentences: what hurts today and how we'll know it worked.>
 - [ ] Given <context>, when <action>, then <observable result>.
 <!-- 2-6 items. Cover the happy path plus the edge cases that matter. -->
 
+## Assumptions
+
+- <What the plan assumes about the user's need or the business value.> Confirm: <ask, data, or a user test>.
+<!-- 1-4 items. Risky, unconfirmed ones also go in `questions`. -->
+
 ## Out of scope
 
 - <Only what a reader would otherwise expect. Omit the section if nothing.>
 
 ## Design notes
 
-<UI: placement, key copy, states that differ from the obvious. Non-UI: API or data shape. 1-4 lines. Omit if nothing beyond the criteria.>
+<Decisions the criteria don't settle: what users see or call, key copy, data shape. 1-4 lines. Omit if nothing beyond the criteria.>
 
 ## Implementation steps
 
@@ -39,12 +44,14 @@ Need: <one or two sentences: what hurts today and how we'll know it worked.>
 
 ## Open questions
 
-- <Only what blocks the human's approval, with the default you assume. Omit if none.>
+<!-- Don't write this section. kanbot fills it from your `questions` output. Open questions keep the issue out of Ready. -->
 ```
 
 ## Rules
 
 - Required: User story (or Technical goal), Acceptance criteria, Implementation steps. Omit other sections when empty; don't write "None."
+- Assumptions are about user need and business value, not code. Technical unknowns go in `explore:N` or a spike.
+- Ask a question (`questions` output) only if building on a wrong guess would waste the work. kanbot won't start while any are open.
 - One line per bullet. No prose paragraphs, no repeating the issue text.
 - Acceptance criteria are shared by all approaches. Approach-specific steps go inside each `### Approach k`.
 - File paths come from reading the code, not guesses. Mark new files "(new)".
@@ -65,6 +72,11 @@ Need: entries without a project silently drop off invoices; users find out when
 - [ ] Given every entry has a project, when I open the month view, then the list is hidden.
 - [ ] Given loading fails, when I open the month view, then the list shows "Couldn't load entries" and "Try again".
 
+## Assumptions
+
+- Users fix missing projects before invoicing, not after. Confirm: ask two users how they invoice.
+- Most months have under 20 such entries. Confirm: query last quarter's data.
+
 ## Out of scope
 
 - Bulk-assigning projects (new issue).
@@ -78,8 +90,4 @@ List sits above the calendar, collapsed to 5 rows with "Show all (n)". Reuse `Pr
 1. Add `missingProject` filter to `GET /entries`, with tests. Files: `api/entries/routes.ts`
 2. Add `MissingProjectSection` with its states and tests. Files: `web/entries/MissingProjectSection.tsx` (new)
 3. Mount it in the month view and refresh after assignment. Files: `web/month/MonthView.tsx`
-
-## Open questions
-
-- Include earlier months? Default: current month only.
 ```

package/templates/.agents/skills/pr-description/SKILL.md

@@ -27,8 +27,12 @@ Conventional commit, imperative, under 72 characters, naming the user-visible ef
 
 ## Screenshots
 
-![<state, width>](.kanbot/screenshots/<branch>/<name>.png)
-<!-- UI changes only; 1-3 images that show the change. -->
+![<state>](repo-relative path to a committed image)
+<!-- Optional. Only when the change is visible; 1-3 images. -->
+
+## Validation
+
+- <What you used to prove it works (tests, skills, preview) and what it showed. 1-3 bullets.>
 
 ## Notes for reviewer
 
@@ -40,5 +44,5 @@ Conventional commit, imperative, under 72 characters, naming the user-visible ef
 - One line per bullet. No "Why" section; the issue has it.
 - Describe what the code does now, not how you got there.
 - Anything you could not verify goes in `risks`, not the body.
-- Screenshot paths must match the `screenshots` output field.
+- Omit Screenshots when there is nothing to show.
 - Aim for under 20 lines.

package/templates/.agents/skills/project-conventions/SKILL.md

@@ -1,7 +1,7 @@
 ---
 
 name: project-conventions
-description: This project's stack, exact commands (install, test, lint, typecheck, build, dev server), code conventions and recorded decisions. Read first before planning, implementing, reviewing or fixing anything in this repository, and whenever you need to know how to run tests or start the app.
+description: This project's stack, exact commands (install, run, test, lint, typecheck, build), code conventions and recorded decisions. Read first before planning, implementing, reviewing or fixing anything in this repository, and whenever you need to know how to run tests or the project.
 ---
 
 # Project conventions
@@ -18,52 +18,40 @@ description: This project's stack, exact commands (install, test, lint, typechec
 
 - What it is: `<one sentence: what the product does and for whom>`
 - Primary users: `<roles>`
-- Language/locale of the UI: `<e.g. Norwegian bokmål, English>`
+- Language of what users see: `<e.g. Norwegian bokmål, English>`
 
 ## Stack
 
-- Language and runtime: `<e.g. TypeScript 5, Node 22 / Bun 1.x>`
-- Frontend: `<framework, router, styling approach, component library / design system location>`
-- Backend: `<framework, API style (REST/GraphQL/RPC)>`
-- Data: `<database, ORM/query builder, migration tool>`
-- Package manager: `<pnpm | npm | bun | yarn>` (use only this one)
+- Language and runtime: `<e.g. TypeScript 5 on Bun, Swift 6, Python 3.13>`
+- Main parts: `<one line each: app, service, library, site…>`
+- Package manager or build tool: `<use only this one>`
 
 ## Commands
 
-| Task            | Command                                  |
-| --------------- | ---------------------------------------- |
-| Install         | `<pnpm install>`                         |
-| Dev server      | `<pnpm dev>` → `<http://localhost:5173>` |
-| Test (all)      | `<pnpm test>`                            |
-| Test (one file) | `<pnpm vitest run path/to/file.test.ts>` |
-| Test (one name) | `<pnpm vitest run -t "name">`            |
-| E2E             | `<pnpm playwright test>`                 |
-| Lint            | `<pnpm lint>`                            |
-| Format          | `<pnpm format>`                          |
-| Typecheck       | `<pnpm typecheck>`                       |
-| Build           | `<pnpm build>`                           |
-| DB migrate      | `<pnpm db:migrate>`                      |
-| Seed data       | `<pnpm db:seed>`                         |
-
-Environment: `<how to get a working .env for local dev and tests, e.g. cp .env.example .env; which variables have safe defaults>`
+| Task        | Command                         |
+| ----------- | ------------------------------- |
+| Install     | `<install dependencies>`        |
+| Run locally | `<start it, and where to look>` |
+| Test (all)  | `<run all tests>`               |
+| Test (one)  | `<run one file or test>`        |
+| Lint        | `<lint>`                        |
+| Format      | `<format>`                      |
+| Typecheck   | `<typecheck>`                   |
+| Build       | `<build>`                       |
+
+Add rows the project needs (migrations, seed data, end-to-end tests…). Environment: `<how to get a working local setup>`
 
 ## Layout
 
 ```
-<src/            app code>
-<src/components/ shared UI components>
-<src/server/     API handlers>
-<tests/          …>
+<dir/   what lives here>
 ```
 
 ## Code conventions
 
-- Naming: `<files kebab-case, components PascalCase, …>`
-- Error handling: `<e.g. return Result types in domain code; throw HttpError in handlers>`
-- Validation: `<e.g. zod schemas at API boundaries in src/schemas>`
-- State/data fetching: `<e.g. TanStack Query; no fetch in components>`
-- Styling: `<e.g. CSS modules + tokens in src/styles/tokens.css; no inline colors>`
-- Tests: `<framework, location (co-located *.test.ts), factories in tests/factories>`
+- Naming: `<files, types, functions>`
+- Error handling: `<how errors are raised and shown>`
+- Tests: `<framework, where tests live, helpers>`
 - Commits: Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`) with a scope.
 - Do not: `<things that look tempting but are wrong here>`
 
@@ -75,5 +63,5 @@ Record decisions that agents should not relitigate. One line each, newest first.
 
 ## Gotchas
 
-- `<e.g. tests need Docker running for Postgres>`
-- `<e.g. generated files in src/gen/ — never edit, run pnpm codegen>`
+- `<e.g. tests need a local database running>`
+- `<e.g. generated files you must never edit>`

package/templates/.agents/skills/review-findings/SKILL.md

@@ -0,0 +1,47 @@
+---
+
+name: review-findings
+description: Severity rubric, finding format and re-review rounds for kanbot reviews. Use when writing review findings, deciding severity, or judging whether a fixer resolved a finding.
+---
+
+# Review findings
+
+kanbot turns findings into a fix loop. Severity decides what gets fixed, so get it right.
+
+## Severity
+
+| Severity  | Meaning                                                                                              | Triggers a fix |
+| --------- | ---------------------------------------------------------------------------------------------------- | -------------- |
+| `blocker` | Wrong behaviour on a main path, data loss, security hole, failing checks, unmet acceptance criterion | Yes            |
+| `major`   | Bug users will hit, missing test for a criterion, missed required capability, risky scope creep      | Yes            |
+| `minor`   | Real but low impact: unclear naming, small duplication, rare edge case untested                      | Yes            |
+| `nit`     | Preference or polish. At most 3 per review                                                           | No             |
+
+When unsure between two levels, pick the lower one and say the risk.
+
+## Writing a finding
+
+Location, what is wrong, why it matters, the fix. One to three sentences.
+
+> `src/invoices/service.ts:84` — `total` is summed before discounts, so discounted invoices show the full amount (criterion 3). Apply discounts first and add a test with a 10% code.
+
+- One problem per finding. Merge repeats into one finding with all locations.
+- Point at the line in the new version of the file. `path` and `line` null for cross-cutting findings.
+- Show a failure ("a user with no projects gets a 500"), not a principle ("not robust").
+- Only what you checked. If unsure, say what would confirm it.
+
+## Avoid
+
+- More than ~10 findings. Keep the most important; summarise the rest in one.
+- Style a formatter or linter covers.
+- Scope beyond the plan. Suggest a follow-up issue as a `nit` at most.
+- Rewriting a working approach to your taste without a concrete defect.
+- Approving with an open `blocker` or `major`.
+
+## Verdict
+
+`changes` with any `blocker` or `major`; otherwise `approve`. Minor findings and nits may come with an approval.
+
+## Re-review rounds
+
+For each earlier finding: fixed (drop it), not fixed (repeat with the same id and what is still wrong), or the fixer disagreed (accept the reason, or explain once more why it matters). Check that fixes didn't add new problems.

package/templates/.agents/skills/spec-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 
 name: spec-review
-description: "Verify a change against its plan: every acceptance criterion with evidence, fit with the user need, UX states, accessibility, scope creep and docs. Use when doing the spec/product review pass on a PR branch, or when checking whether an implementation actually does what the issue asked."
+description: "Verify a change against its plan: every acceptance criterion with evidence, fit with the user need, scope creep and docs. Use when doing the spec/product review pass on a PR branch, or when checking whether an implementation actually does what the issue asked."
 ---
 
 # Spec review
@@ -12,13 +12,13 @@ You review the change from the outside, as the user and the product owner. The q
 
 For each acceptance criterion in the plan, record:
 
-| #   | Criterion (short)              | Evidence                                                                                    | Verdict          |
-| --- | ------------------------------ | ------------------------------------------------------------------------------------------- | ---------------- |
-| 1   | Missing-project entries listed | `MissingProjectSection.test.tsx` "lists entries newest first"; screenshot `filled-1280.png` | met              |
-| 2   | Count updates after assignment | test asserts count; not visible in screenshots                                              | met              |
-| 3   | Section hidden when none       | no test; no screenshot of empty state                                                       | **not verified** |
+| #   | Criterion (short)              | Evidence                                                      | Verdict          |
+| --- | ------------------------------ | ------------------------------------------------------------- | ---------------- |
+| 1   | Missing-project entries listed | `MissingProjectSection.test.tsx` "lists entries newest first" | met              |
+| 2   | Count updates after assignment | test asserts count                                            | met              |
+| 3   | Section hidden when none       | no test; not observed                                         | **not verified** |
 
-Valid evidence: a test that asserts the behaviour (read it, and check it would fail without the feature), a screenshot of the state, or behaviour you observed by running the app or the command. The PR body's claims alone are not evidence.
+Valid evidence: a test that asserts the behaviour (read it, and check it would fail without the feature), output of the `verify` capability, or behaviour you observed by running the app or the command. The PR body's claims alone are not evidence.
 
 "Not verified" is a finding. "Not met" is a `blocker`.
 
@@ -32,24 +32,7 @@ Re-read the user story and problem. Then walk through the change as that user:
 - Any dead ends: a state with no way forward or back?
 - Does it solve the problem in the plan, or only satisfy the letter of the criteria?
 
-## 3. UX states (UI changes)
-
-Check each state exists and looks right at 390px and 1280px:
-
-- [ ] Loading (no layout jump when content arrives)
-- [ ] Empty (explains why and what to do)
-- [ ] Error (says what went wrong and offers a way to recover)
-- [ ] Success / filled, including long text and many items
-- [ ] Disabled and in-progress controls
-- [ ] No horizontal scroll at 390px; tap targets at least 24x24px (44 preferred)
-
-Use committed screenshots under `.kanbot/screenshots/<branch>/` first. Capture missing states with `verify-ui` into a temp directory outside the repo.
-
-## 4. Accessibility
-
-Run through the `accessibility` checklist for the changed UI. WCAG 2.2 AA failures are `major`; a keyboard trap or an unlabelled primary control is a `blocker`.
-
-## 5. Scope
+## 3. Scope
 
 - Diff against the plan's implementation steps: files changed that no step explains?
 - Features, options or settings nobody asked for?
@@ -58,7 +41,7 @@ Run through the `accessibility` checklist for the changed UI. WCAG 2.2 AA failur
 
 Scope creep is `major` when it adds risk or review burden, `minor` otherwise. Ask for it to be removed or moved to a follow-up issue.
 
-## 6. Docs and communication
+## 4. Docs and communication
 
 - User-facing behaviour changed: are help text, README, changelog or docs updated where the project keeps them?
 - Does the PR body explain how to test, with steps a human can follow?
@@ -68,6 +51,6 @@ Scope creep is `major` when it adds risk or review burden, `minor` otherwise. As
 
 Quote the criterion or plan line, state what you observed and your evidence, and say what would satisfy it:
 
-> Criterion 3 ("Given all entries have a project … the section is not shown") has no test and no screenshot. Add a component test for the empty case and an `empty-390.png` / `empty-1280.png` screenshot.
+> Criterion 3 ("Given all entries have a project … the section is not shown") has no test and no other evidence. Add a test for the empty case.
 
 Lead the summary with the tally ("4/5 criteria met, 1 not verified") so a human can scan it.

package/templates/.agents/skills/user-stories/SKILL.md

@@ -74,7 +74,7 @@ Do not use `technical` to dodge user framing. If users will notice the change, i
 | System as user          | "As the system, I want to cache…"            | Use `technical` with a technical goal, or find the human. |
 | Hollow "so that"        | "so that I can use the feature"              | Ask "why?" until you reach an outcome.                    |
 | Untestable criteria     | "The page is intuitive"                      | Name the observable behaviour.                            |
-| Horizontal slice        | "Build the database tables for X"            | Slice vertically through UI → API → data.                 |
+| Horizontal slice        | "Build the database tables for X"            | Slice vertically through every layer the user touches.    |
 | Epic disguised as story | 10+ criteria, many screens                   | Split with `issue-splitting`.                             |
 
 ## New issues you propose

package/templates/.github/pull_request_template.md

@@ -8,8 +8,14 @@
 
 1.
 
+## Validation
+
+<!-- What proved it works: tests, checks, preview. -->
+
 ## Screenshots
 
+<!-- Optional. Only when the change is visible. -->
+
 ## Risks
 
 Closes #

package/templates/.kanbot/agents/acceptance-reviewer.md

@@ -0,0 +1,43 @@
+---
+
+name: acceptance-reviewer
+tier: column
+description: Second review pass on a PR branch. Checks every acceptance criterion with evidence, the user need, required capabilities and scope. Read-only.
+models: { claude: opus, codex: default }
+effort: high
+tools: [read, bash]
+skills: [project-conventions, project-memory, spec-review, review-findings]
+subagents: [explorer]
+output: review-result
+---
+
+You are the user's advocate. Does this branch do what the plan promised, for the person it is about, and nothing else? The technical review already ran; don't repeat it.
+
+## Inputs you get
+
+- The issue, the approved plan, the PR title and body, the base branch, and the worktree at the PR head.
+- For exploratory variants: which approach k this branch builds. Judge it against `### Approach k` only.
+- The repo's capabilities table, when it has one.
+- On later rounds: your earlier findings and the fixer's reply to each.
+
+## Process
+
+1. Read `project-conventions` and `project-memory`. Load `spec-review` and `review-findings`.
+2. Build the criteria evidence table from `spec-review`. Evidence is a test that asserts the behaviour, or behaviour you observed. The PR body's claims alone are not evidence.
+3. To get evidence, use the `verify` and `preview` capabilities yourself when their "when" fits. Unmapped: run the tests or the app as `project-conventions` says.
+4. Check required capabilities. For each one marked required whose "when" fits this change, the PR body's Validation section must show it was used. A miss is a `blocker`.
+5. Judge the user need, scope and docs per `spec-review`.
+6. On later rounds, follow the re-review rules in `review-findings`.
+
+## Hard rules
+
+- Never call `gh`, `git push`, or anything that talks to GitHub. kanbot posts your review.
+- Read-only. Don't edit or commit repo files. Write scratch output outside the repo.
+- Don't ask for features beyond the plan. If the plan is wrong, say so once in `summary` and review against it as approved.
+
+## Output
+
+Return the structured result; it is your only channel to GitHub.
+- `verdict`: `changes` if any criterion is unmet or any `blocker`/`major` exists; otherwise `approve`.
+- `summary`: start with the tally ("5/6 criteria met"), then the main gap in one sentence.
+- `findings`: per `review-findings`. Unmet criterion or missed required capability = `blocker`. Not verified = `major`.