Agents

Agents are defined in .kanbot/agents/<name>.md. This is the only place to edit them. kanbot sync renders them into each provider's format:

• Claude: .claude/agents/<name>.md and .claude/settings.json
• Codex: .codex/agents/<name>.toml

The generated files also let you use the same agents in normal Claude Code or Codex sessions.

Tiers

• Column agents (tier: column) are started by the daemon for a board job. They must declare an output schema.
• Subagents (tier: sub) are called by column agents for focused work.

Default team

Agent	Tier	Role
planner	column	Writes and revises the plan.
implementer-frontend	column	Builds UI work.
implementer-backend	column	Builds server, API and data work.
implementer-docs	column	Writes docs.
implementer-technical	column	Refactors, infra, tooling and CI.
reviewer-code	column	Review pass 1: correctness and code quality.
reviewer-spec	column	Review pass 2: acceptance criteria and UX.
fixer	column	Fixes findings, your comments and failing CI.
explorer	sub	Maps the codebase for a change.
plan-critic	sub	Critiques a draft plan.
approach-designer	sub	Designs N approaches for explore:N.
test-writer	sub	Writes failing tests first.
ui-verifier	sub	Takes screenshots with Playwright.

planner, reviewer-code, reviewer-spec and fixer are required. Implementers are picked through implementers in config.

File format

YAML frontmatter, then markdown instructions:

---

name: implementer-backend
tier: column
description: Implements an approved plan for server, API and data work.
models: { claude: sonnet, codex: default }
effort: high
tools: [read, edit, bash]
skills: [project-conventions, tdd, pr-description]
subagents: [explorer, test-writer]
output: implement-result
---

You are the backend implementer. ...

Frontmatter

Field	Required	Description
name	yes	Lowercase, dashes. Must match the filename.
tier	yes	column or sub.
description	yes	When to use the agent. Callers read this.
models	no	Model per provider: { claude: opus, codex: default }.
effort	no	low, medium, high, xhigh or max.
tools	no	Any of read, edit, bash, web. Default [read].
skills	no	Skill names from .agents/skills/.
subagents	no	Names of tier: sub agents it may call.
output	column	plan-result, implement-result, review-result or fix-result.

Tools map to provider tools:

Tool	Claude	Codex
read	Read, Grep, Glob	read-only sandbox
edit	Edit, Write, NotebookEdit	workspace-write sandbox
bash	Bash	workspace-write sandbox
web	WebFetch, WebSearch	—

Output schemas

Column agents answer with JSON. The daemon turns it into comments, PRs and labels.

Output	Used by	Main fields
plan-result	planner	plan, summary, replies, newIssues, labels, questions
implement-result	implementers	status, prTitle, prBody, testsRun, screenshots, risks
review-result	reviewers	verdict, summary, findings
fix-result	fixer	addressed, summary, prBody

Schemas are defined in src/schemas/results.ts and can't be changed per repo. Agents must match the one they declare.

Common changes

Change a model. Edit models and run kanbot sync.

Change behaviour. Edit the markdown body. Keep it about how to work; the daemon's prompt carries the task.

Add an implementer. Copy an implementer file, rename it, then map a label to it:

# .kanbot/config.yml
implementers:
  frontend: implementer-frontend
  backend: implementer-backend
  docs: implementer-docs
  infra: implementer-technical
  mobile: implementer-mobile # used for type:mobile
  default: implementer-backend

Create the type:mobile label in GitHub too.

Add a subagent. Create a tier: sub file and add its name to a column agent's subagents.

Apply changes

kanbot sync
git add -A && git commit -m "chore: update agents" && git push

The daemon refuses to start if generated files are stale. Never edit files in .claude/agents/ or .codex/agents/; sync overwrites them and removes ones whose source was deleted.