The agents that work your board

Every flow the board starts is run by a named agent. Configuration → Agents draws all of them as a grid of characters, and selecting one opens its page: its rule, what it remembers, its settings, and — for one you added — its own instructions.

There are two kinds.

Roles are the agents the board's own flows are run by. You do not add or remove one, and three of them can be switched off:

• Planner — plans and refines cards. It runs create, refine, resolve, revise, the release plan, the changelog, archive and reject. On a marketing board it runs four of those: a topic carries no questions to refine or resolve, and ships to channels rather than to a version, so refine, resolve, the release plan and the changelog are not on that board at all.
• Builder — builds cards and lands them: implement, conflict, run. On a marketing board a Writer takes its place, and also runs akb channel.
• Reviewer — checks what was built.
• Gater — judges whether a card that reached ready is clear enough to build unwatched. Off by default. Product boards only.
• Decider — answers the questions on a card that are waiting on you. Off by default. Product boards only: a topic carries no questions.
• Proposer — reads a card the board has just finished and proposes the work that should follow it. Off by default. Product boards only.

The Gater, the Decider and the Proposer are the three roles you can switch off. None of them does a flow's work: each spends a run you never asked for, so each has its own switch and its own connector, and each reads the whole board — the goal, and every module's decisions.md and rejected.md — on top of the card.

Specialists fill one part of a card's spec and fill only that part. Each one runs on its own, while a card is being planned — never while it is being built — writes one named section of that card, and changes nothing else. The board ships two, and akb spec lists them:

• ui-designer — draws the screen a card needs as one layout by default, with alternatives only when you ask for them, and nothing written under the drawing. Its mockup is either a rendered screen or a plain-text drawing depending on the board's Mockup style setting (Configuration → Agents). See "Mockups on a card" in kanban-ui/README.md.
• tech-stack-advisor — picks the library, tool, or service a card leans on. Its answer is one table — a row per candidate, with what it is, its pros and its cons — and one line naming the pick. Keeping what the project already uses and writing it yourself are rows too, so a card doesn't come back with something new to install by default.

A specialist's run is a run like any other, with three things that make it different: it starts clean, given the card and a short note but never the conversation that asked for it; it writes one named section — ## By `ui-designer` agent — and nothing else, rewritten rather than doubled on a second run; and nothing waits for it, so a planning flow carries on and the section arrives when it is done. When the answer is a pick only you can make, it leaves an open question instead of choosing.

You rarely ask for one yourself — the flow working the card asks when the card needs it, after a card is added, after a refine or revise that moved the screen or the library, and never from a release plan (each card's own refine asks instead). A card that needs neither a screen nor a library goes through all of those without a spec run, and nothing tells you it did.

When you do want one: "put the ui-designer agent on #4", or akb spec ui-designer 4. Pausing one and setting what it produces are both on its page in Configuration → Agents; a role is always on except the Gater, the Decider and the Proposer, because a board without a planner plans nothing.

Let the Decider answer for you

A card that reaches the end of its planning with nothing but [user] questions on it stops and waits for you. So does a delivery a review sends back with a question. Decider is the switch that removes both waits: it answers those questions in your place and the card carries on.

Switch it on in Configuration → Agents, in the Optional group. It asks once before it goes on, because it is the most expensive switch on the board:

While this is on, nothing stops for you. An idea runs all the way to landed without asking you — a wrong direction included. What it chose, you read afterwards on the card.

It answers from the project's goal, each of the card's modules' decisions.md, and the recommendation each question carries — in that order. When none of those settles a question it takes the recommendation anyway: every recommended option on a multi-choice question, the first option when nothing is recommended, and its own answer on a question with no options. It never hands a card back.

What it chose stays on the card, in a decided: list — the question, the option it took, and the file it went on. The board marks such a card and What Decider chose for you on the card page lists them one by one, with the ones it took blind called out. None of it becomes a lasting decision: your memory/<module>/decisions.md files are answers you gave, and the Decider writes to none of them.

Switching it off puts every card still carrying questions back to waiting on you. A card it already answered and the board already built does not come back. Switching it on changes nothing that is already stopped — those cards move on their next refine, or when you type akb card decide <id>, which runs it on one card whether or not the switch is on.

Let the Proposer look back

Nothing on the board looks at finished work. A follow-up surfaces only when a builder or a planner notices one mid-task, and Triage reads outside sources — never your own history.

Proposer is the switch that closes that gap. Switch it on in Configuration → Agents, in the Optional group. From then on, every card that reaches the archive starts one reflection over that card alone: it reads what shipped, judges what work follows from it against your goal and your module memory, and puts each survivor in Triage.

• Archiving is the only trigger. A card completing is what starts a reflection. Nothing sweeps the cards you finished last week, and there is no command that asks for one.
• One run per completion. That is what it costs while it is on, and the whole of what it costs.
• It proposes into Triage, never onto the board. A proposal is triaged like anything else that arrives there, so a weak one costs you a dismissal rather than a card in your backlog.
• It grounds every proposal. Anything already planned, already in Triage, or in a rejected.md is skipped. Finding nothing worth proposing is a normal result, and the common one.

Each item it writes carries a short rationale and the card that prompted it, so you can read what the proposal came from before deciding. Switching the Proposer off leaves nothing behind — items already in Triage stay there, like any other.

Give an agent a rule

A rule is one paragraph, in your own words, added to the end of every run that agent does, after everything the board writes into it. Write it in the box on the agent's page; it saves when you leave the box.

• It is plain words, not a command the board runs. What it actually causes is up to the agent reading it. On the Reviewer, a check your rule asks for is one of the repository's checks.
• It belongs to the agent, not to one flow. One rule on the Builder reaches implement, conflict and run alike, so a convention you write once is followed everywhere that agent works.
• It lives in your board, at docs/kanban/rules/<agent>.md, tracked in git — so a team shares it and a run started from a terminal reads the same words. Clearing the box deletes the file.
• A delivery freezes the rules it starts with, so editing one changes the next delivery and never one in flight.
• Every session that agent starts reads it, so a long rule makes every card slower.

From a terminal: akb raw rule <agent> --file <path>, or --text "" to clear it.

Give an agent memory

Some agents remember — the taste they were corrected on, and the choices you made. The agent's page lists the files it owns, read-only:

• A role remembers in the files its own flows already write: the Planner in decisions.md, rejected.md and goal.md, the Builder in readme.md, redesign.md and modules.md.
• A specialist that declares memory: project owns docs/kanban/memory/agents/<name>/, two files: redesign.md, the mistakes it was corrected on, and decisions.md, the choices you made. ui-designer declares a memory; tech-stack-advisor does not.
• How the product looks is not memory. Colours, dimensions and component detail are read from the app's own design.md, so memory says which doc to read rather than repeating it.
• The runs write these themselves — the flow that hears your answer records what was taken or sent back, and the agent curates the files on its own runs. Nothing on the pane edits one.

Add one of your own

Add a specialist in Configuration → Agents asks for a name, writes the folder and file, and opens the new agent's page with its instructions box focused, so you write the prompt without leaving the dialog. A name a role or a bundled agent already answers to is refused in place.

docs/kanban/agents/api-contract/AGENT.md
docs/kanban/agents/api-contract/references/openapi.md   # optional

The whole file is the box on that page, frontmatter included, and a save the board would refuse keeps your text and says what is wrong rather than leaving an agent it cannot read. Writing the file by hand in an editor works exactly the same way — the pane and the file are one thing.

AGENT.md opens with frontmatter carrying the agent's name, the description a planning session picks it by, and an akb: block saying which hook it plugs into and what part of a card's spec it owns:

---
name: api-contract
description: Use when a card changes an endpoint other software calls.
akb:
  kind: spec
  owns: the request and response shape a card changes
  settings:
    - key: style
      label: Contract style
      default: openapi
      choices:
        - value: openapi
          label: OpenAPI
          cost: a schema fragment per endpoint — precise, and longer to read
          reference: references/openapi.md
        - value: prose
          label: Prose
          cost: a paragraph per endpoint — quick to read, easy to argue with
          reference: references/prose.md
---

Everything under the frontmatter is the agent's instructions. kind: spec is the hook it plugs into; kind: write joins the writer on a marketing board and is refused anywhere else. A settings entry becomes a control on that agent's page, and only the chosen choice's reference is loaded into the run — the instructions for the option nobody picked are never read. akb spec lists the agents this board can use and, under them, anything wrong with one it found.

Delete on an agent's page removes it and everything the board kept for it — the folder, the instructions you wrote for it, what it remembered, and its switch. Only an agent this project added: the roles and the two the command ships are not yours to remove, and have no Delete.

Say it in your own language

description, owns and the words its settings are drawn by are read by people, not only by the board, so an agent can carry them in another language under akb.i18n:

akb:
  kind: spec
  owns: the request and response shape a card changes
  i18n:
    zh:
      description: 当卡片改动其他软件会调用的接口时使用。
      owns: 卡片改动的请求与响应结构
      settings:
        style:
          label: 契约格式
          choices:
            openapi:
              label: OpenAPI
              cost: 每个接口一段 schema——精确，但读起来长

Say only what you want translated: anything you leave out keeps the English the agent declares. Whichever language your machine is set to is what the Agents pane draws. Every run is handed the English lines whatever you add here, so a translation can never change what an agent is asked to do. The roles the board ships — Planner, Builder, Writer, Reviewer, Gater, Decider, Proposer — are translated with the rest of the product and carry no block of their own.

Agents used to live in docs/kanban/skills/<name>/SKILL.md. That folder still works for one release, and every agent found there is listed with a line telling you to move it.