The daily loop

Everything you say below goes to a coding agent, which needs the skill in the repo — akb skill install, or Configuration → General in the board app. A board arrives without it. Every one of those asks is also a button in the app and a command you can type, so nothing here is closed to a board that has no skill.

This page is the rhythm. Two references sit beside it and are not repeated here: akb --help for the commands (akb <noun> lists that noun's verbs), and kanban-ui/README.md in the repository for what every column, panel, button and setting does.

Two ways the work gets done

In the conversation you're in. You ask your coding agent for a board action — "refine #4", "#4 is done" — and it does the job itself, right there. It already has your code in context, nothing extra is billed, and "not that one" is your next message when it takes a wrong turn. Under the hood it asks the CLI for the steps with --print, and follows what comes back for your board.

Sent off as a run. You press a button on the local board, or type akb card refine 4, and a second agent starts on its own. It keeps working when you close the terminal, it shows in the runs panel with its own log, and you can stop it. Nothing you say reaches it while it goes, so a correction costs the whole run.

Send it off for work you want happening while you do something else, or for the long read-heavy jobs — proposing across the repo, planning a release, refining round after round. Otherwise just ask, in the session you're already in. A run never starts another run: an agent inside one that's asked for a board action gets the steps printed and does them itself.

Pick what to work on

Two asks, two answers.

"What's next?" — a pick from the cards you already have. The skill takes the ones that are ready to build and unblocked, ranks them by priority, then ROI, then which release ships first, and names up to three: id, title, and one line on why each won. Priority outranks the release, so the pick can be work the release you're shipping doesn't contain. Nothing is written, so "not that one" costs you nothing. When nothing qualifies it says what's in the way — "4 cards wait on another card, 12 still need refining" — rather than an empty answer.

"What are we missing?" — new tasks, found for you. The skill mines your planning sources — the ones in docs/kanban/config.md — exactly as it mines an article you paste in: it pulls out the concrete gaps, checks each against the board, your published docs, readme.md and rejected.md so it won't repeat work, and writes the survivors as cards. Strong signal only, so "nothing new" is a real answer. You approve, tweak, or drop each card.

Every card it writes is judged against memory/goal.md — the direction in your own words. The file starts empty and stays optional: nothing on the board waits on it, and the skill never writes the goal for you. It only marks how clear the goal looks in that file's reviewed: field:

• strong / good — clear enough to plan from.
• pending — you just wrote or edited the goal and nothing has read it yet. Written by the board itself when the goal is saved, so it never asks you for work you just did.
• weak — missing, empty, or too vague to plan from.

The board never asks you for a goal. Write one whenever you like, from the star in the top row — with one, the cards it writes are judged against your direction; without one, they are judged against the repository.

Not every answer is a job. To think out loud instead — what a card means, whether two cards are the same card — open a chat.

Add a task

Say "add a task: <idea>". Before writing, the skill reviews the idea (business value, feasibility, duplication) and checks redesign.md so it doesn't repeat a known design mistake. Then it creates one indexed card with akb raw create, fills its body in plain language split into checkable todos, and adds it to todo/README.md.

Turn a source into tasks

Say "read this article and create tasks", or give the skill research, an analysis, or user feedback. It treats the material as evidence rather than a ready-made task list: it extracts concrete user problems, finds the modules that could improve them, and validates each idea against the goal, code, docs, module memory, and open cards. Ideas that are already supported, already planned, previously rejected, outside the project's control, or too weak are skipped, and a useful detail for existing work updates that card instead of creating a duplicate.

The result can be fewer tasks than the source suggests — including none. Each card that survives is about the product improvement, not about reading the source.

Push a card forward

Say "refine #4". The skill reviews the card (missing steps, missed edge cases, over-complication, actionability), then rewrites it one stage toward concrete — one stage only, stopping before code-level detail. Decisions only you can make land on the card as open questions.

When the skill adds a card, it chooses the next refine's effort. Clear, localized work is settled directly; everything else gets the standard loop, which first checks whether several independently refinable areas include one that remains vague. Each refine loads only its own QA guide. Lightweight uses --print and finishes inline; omit it only for explicitly background work. Standard QA runs in its own session, and a refine started by hand defaults to standard.

A card with open questions can't be refined again. Say "resolve #4" — the skill researches each question, decides the ones the evidence settles, asks you the real judgment calls, and clears the list.

You rarely have to ask. Any run that writes or changes a card is followed by a refine of that card, started on its own once the run ends, so a card you add, revise or resolve comes back refined without a second instruction. What has nothing to refine is skipped — a card still blocked, one already ready, a recurring card, one whose todos are all ticked, one waiting only on your answers, and a group's main card when a subtask finishes. When that was the last subtask the main card leaves the board with it, archived in the same breath.

Parts of a card nobody should plan by guess — the screen it puts in front of the user, the outside library it leans on — go to a spec agent instead, which the refine asks for by itself.

Build a card

Press Implement on the card page, or say "build #4". One click carries the card all the way: an agent builds it, a fresh run reviews what it built against the card as you approved it, corrections fix what the review found, the board lands the work as one commit on the branch you are on, and then it archives the card. Nothing asks you again in between.

What you are approving is the card — what it should achieve, what to weigh, its open questions, and what building it turned up — not the diff. The dialog says the steps in order and names the branch the change will land on.

• A card with open questions can still be built, with a warning. It is built and reviewed, then holds at landing until you answer — taking no landing slot while it waits, so every other card still lands. Resolve, under the card's open questions, is the other way round: answer first, then build.
• A pause has nothing to press. The card's title band says what the delivery is waiting on and what answers it. Answering carries the same delivery on; an answer that changed what the card asks for starts a fresh delivery on the card as it now reads.
• Manual commit mode is the exception. Untick Build this on a branch of its own in the dialog and nothing lands: the agent builds in the folder you are sitting in, the delivery stops after review, and the card is archived when your own commit matches what review passed. Where a worktree is impossible anyway — no git, no commit to fork from, a detached HEAD — the build works this way regardless.
• The review is optional. It is a separate paid run on every delivery, so the Reviewer's switch on Configuration → Agents turns it off for the board. The build then goes straight to landing; your own checks, the open-question hold and Approve diffs before landing still gate it.
• Your own commits on that branch are refused while it lands. A pre-commit hook installed beside the skill names the delivery and stops the commit. Commit on another branch, or git commit --no-verify.

In a terminal it is akb card implement 4, which starts the same delivery and warns about an open question the same way it warns about a blocker.

Let clear cards build themselves

Gater in Configuration → Agents replaces that press. It is off by default. With it on, every card that reaches ready is judged first by that agent: it reads the card against the same standard the board writes cards to — an observable outcome, scope that says what to build, a ## Todo a builder can follow, nothing left open — and either passes it straight into a delivery on the settings above, or sends it back to Not ready carrying the one question that stopped it. Answer that question and the card refines, reaches ready again, and is judged again.

The Gater runs one card at a time, in the order "what's next?" would name them, and it never takes a card that is blocked, recurring, a group's main card, or already in flight. It judges as you would, so it is given the project's goal and every module's decisions.md and rejected.md on top of the card, and it runs on its own tool and model, set on its row in Configuration → Agents — so the judgment can run on a stronger model than the builds it lets through. A run that fails or is stopped changes nothing: the card stays where it is. Turning the switch on does not go back over the cards already sitting at ready — those are still yours to press.

In a terminal it is akb card gate 4, which asks the same question about one card.

Let the board answer your questions too

The Gater removes the press; Decider removes the wait. It is the other role in Configuration → Agents that is off by default, and the only agent whose switch asks before it goes on:

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.

With it on, a card that ends its planning with nothing but questions waiting on you is answered instead of handed back, and so is a delivery a review sent back with one. It answers from the project's goal, every module's decisions.md and rejected.md, and each question's own options and recommendation, and takes the recommendation when none of those settles it. It never hands a card back, and there is no limit on how many rounds it answers on one card.

What it chose stays on that card — the board marks it, and What Decider chose for you on the card page lists every question, the option it took and the file it went on. None of it becomes a lasting decision: a decisions.md records answers you gave.

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 leaves the cards already stopped exactly where they are. A run that fails changes nothing and is not started again by itself — the card is yours again.

In a terminal it is akb card decide 4, which answers one card whether or not the switch is on. See the agents for the rest.

Queue a card that is waiting on another

A card whose blocked_by still names an open card can be built or refined anyway — the board warns, it never stops you. A rough card waits properly by default: when it first becomes blocked the board schedules one refine, then runs it when the last card in its way leaves the board, archived or rejected alike. akb raw schedule 4 --action implement replaces that default with a build.

In the local UI the card reads Scheduled with a cancel control, and pending in place of its stage until it fires. A card holds one schedule at a time, it fires once within a minute of coming free, and a schedule that has gone pointless is dropped rather than run. The mark lives in the card's own frontmatter, so it survives a restart and travels with the card.

The saved refine is the answer to the refine that gets skipped: sharpening a plan whose foundation could still change shape is work you throw away.

Review the board

Say "review the board" (or "review #4"). The skill checks cards for plain language, split todos, duplication, and whether any are already done or no longer worth it. It archives finished ones and flags the rest.

Finish a task

A card built by Implement finishes itself: the board archives it once its delivery has landed, so "#4 is done" is not something you have to say.

For work done outside a delivery — you built it yourself, or an agent built it in the conversation you were in — say "#4 is done". The skill updates the published doc the change touched (via the card's doc todos) and adds one line to readme.md — a link to that doc, or a short plain-words note when no doc covers the behavior yet — then archives the card.

The card file isn't deleted — it moves to docs/kanban/.archive/, which stays in git. So you can still read a finished card, or diff it, long after it left the board.

What the build leaves you to check

A build sometimes ends with something only you can confirm — it needs your machine, your data, or your eye. Those land on the card as verify lines, listed under check by hand on the card page and marked by a clipboard on the board card. They are notes, not questions: a card with them still goes ready, still resolves, still archives, and they travel with the card into the archive.

Your agent writes and clears them with akb raw update-verify.

Reject an idea

Say "reject #4" (rare). The card is dropped. When the rejection carries a lasting reason not to propose the idea again, the skill adds a one-line "why not" to rejected.md and future loops won't re-propose it — a duplicate or a card you have simply moved past leaves no note, so memory stays worth reading. Say "don't record it" and nothing is written either way.

Keep it lean

Over time the memory set — readme.md, decisions.md, rejected.md, and redesign.md — grows. Ask the skill to prune it: it compresses each to planning-useful summaries grouped by topic, so scans stay cheap. The board itself stays small because finished work is a note, not a card.

Where the flows live

The flows themselves — how a card is refined, what goes in memory, how a release is planned — ship with the command rather than with this site: akb guide lists them, akb guide board is how the board works at all. Your project keeps only a short note pointing there, so akb update upgrades every flow at once.