How a story flows | kanman documentation

Every piece of work in kanman takes the same path. This page follows one example through all five stages: a customer request to export invoices as CSV.

Describe You describe a goal or a story, in the chat, on the board or in Slack.
Plan kanman reads the code and the board, splits the work, picks the order.
Work Helpers write the code, each in its own sandbox, on its own branch.
Check Your CI, then an independent reviewer that did not write it. A problem CI or the reviewer finds is fixed and checked again.
Merge kanman merges and shows every step live and in the activity log.
Waits on people only what kanman cannot find out, asked once, in one place.

How work flows through kanman

1. Describe: a goal or a story

It starts with what you want, in whatever shape it arrives: a few sentences to kanman in the conversation, a story on the board, an issue in your tracker or a Slack thread that mentions kanman.

Customers need to export their invoices as CSV, filtered by date range.

A larger request becomes a goal with several stories; a small one becomes a single story. Each story gets a title, a short description for the board card and acceptance criteria that say when it is done. You can edit any of it, and kanman reads your edits the next time it looks at the board. More in Stories and acceptance criteria.

A story that sits in Ready and is not assigned to a person is kanman’s to work. A story assigned to a colleague stays with that colleague (see Working with kanman).

2. Plan: kanman looks at the whole board

kanman does not work one story at a time in isolation. Whenever something changes (a story is created or moved, someone writes a note, answers a question, or a pipeline finishes) and at least once an hour, kanman looks at the team’s whole board:

what is in Ready, what is in progress and what waits on someone
what the code and the repository’s history say about the request
what people wrote in the notes since it last looked

It then decides what to do next and in which order: which stories can run side by side, which must wait for another one, and which need something only a person has. It writes each decision with its reason into the team’s activity log, so you can always see why.

3. Work: helpers in their own sandboxes

kanman hands each piece of work to a helper. A helper is a Claude Code session with one clear brief. Each helper:

works in its own copy of the repository, in its own sandbox
commits on its own branch, named after the story
has no access to your code host token or model keys

When the helper is done, kanman publishes the branch and opens a merge request. Before anything leaves the sandbox, the change is scanned for credentials.

You see the helpers at work: the line above the message box says how much is running, for example Working on 3 things, and lists what each one is doing right now.

4. Check: your CI and an independent review

kanman checks every change in two independent ways:

Your repository’s CI runs on the merge request, exactly as it does for your colleagues. If a job fails, kanman reads its log, has the change fixed and waits for the next pipeline. If a job also fails on your main branch for a reason that has nothing to do with the change, kanman says which job and why in the log.
An independent reviewer, a helper that did not write the change, reads the diff against the story’s acceptance criteria. It looks for missing criteria, weakened or dropped tests and claims that do not hold. If it finds a problem, the change goes back to be fixed and is checked again.

Changes to test expectations are decided by the reviewer too, and its reason is written into the activity log. More in How kanman checks its work.

5. Merge: shown as it happens

When CI is green and the reviewer approved the change at its latest commit, kanman merges it. This rule is enforced outside the model: there is no other way for kanman to merge. Your protected branches and your code host’s merge rules apply on top, so if your team requires a person’s approval, kanman waits for it.

The story moves to Done, and the log records the merge with links to the merge request, the pipeline and the review. Your conversation shows it on the story’s live line.

Where kanman asks you

kanman finds out facts on its own: what CI says, what the code does, whether a test already failed before the change. It asks a person only about what nobody else can settle, such as intent, a decision between two good options, or access it does not have.

Its questions go into one place: they are pinned at the bottom of your chat, over the message box. The story’s page says who it waits on. Answer in the chat, or from Slack or Microsoft Teams. kanman asks each question once; when you answer, it continues right away. See Questions from kanman.

Every step, question, answer, review and merge ends up in the team’s activity log with who, what, when and why.

Try it

The quickstart runs this kind of story on a public sample repository, from request to merged change.