How a story flows

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

1. Intake: from requirement to stories

It starts with a requirement, in whatever shape it arrives: a paragraph written on the team’s intake page or a Slack thread that mentions kanman.

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

kanman first decides what kind of message this is. Only work requests become stories; a status question gets an answer in the chat, and a reply to an open question goes to that decision. Then kanman drafts small stories. Each one has:

• acceptance criteria in Given/When/Then form
• a Demonstrate block: a concrete way to show the result, for example “open /invoices, pick March, click Download CSV, the file has the columns date, number, amount”
• a test plan, a size (S, M or L), the affected areas of the code and any open questions

You edit, reject or approve each draft. Approved stories are written to your tracker in one batch, labelled for kanman. More in Stories and acceptance criteria.

Before Ready: a spec that fails

If the repository has an acceptance manifest, kanman turns the Demonstrate block into an executable acceptance spec under .kanman/acceptance/<KEY>/ and runs it. The story may only move to Ready when the spec runs and fails, because the feature does not exist yet. A spec that already passes, or one that mocks the very thing it should test, keeps the story in Refining with a plain explanation.

2. Dispatch: the policy check

When a story sits in the Ready column and carries the pickup label (kanman by default), kanman picks it up and checks the team’s policy:

• Is the team active, not paused?
• Is the team inside its working hours and below its limit of parallel runs?
• Is there daily and monthly budget left?

If everything passes, a run starts. If not, the story waits in Ready until it can start. During the run, kanman checks the repository and branch, denied paths and the size of the change, and asks for plan approval if the policy requires it. Those questions land in the decision inbox.

3. Execute: the coding agent at work

kanman starts Claude Code or Codex in an isolated sandbox with a clone of the repository, a branch of its own and only the access the policy allows. The agent talks back to kanman through a small set of tools: it reads the story, reports progress that you see live on the run page, checks the policy before it touches a path, and asks a human when it is unsure. Questions land in the decision inbox and pause the run until someone answers.

The run page shows the stages Planning, Implementing, Verifying, Review and Done, with live progress lines and a cost meter against the run budget. See Runs.

4. Verify: the outcome gate

The coding agent never declares its own work done. kanman runs the gates and moves the story itself:

• the acceptance spec must pass against a freshly provisioned environment
• no commit from the agent may change the acceptance spec, and denied paths and size limits are checked again on the final diff
• then the story moves to Review, where the spec must pass again on a clean checkout, CI must be green, and proof artifacts are stored
• an independent reviewer, on a model from another vendor than the one that wrote the code, checks every acceptance criterion against the diff with file and line references

If a gate fails, kanman gives the agent one rework attempt with the gate output and the reviewer’s findings. If that fails too, the story goes to the decision inbox instead of looping. See The outcome gate and evidence.

5. Handoff: a pull request with proof

The pull request is opened on the run’s branch while the story is in progress. When the Review checks pass, kanman posts the evidence pack as one comment on the pull request and one on the tracker issue, and sets the pull request’s kanman/outcome-gate status to passed:

• the plan and any approaches considered
• each acceptance criterion with passed or failed and the code it refers to
• gate results with links to artifacts such as Playwright traces and screenshots
• test counts and the CI link
• cost, duration and the number of attempts

A human reviews and merges, and the story moves to Done. If your policy allows it, small verified changes merge automatically.

Where kanman stops and asks

kanman acts on its own only where your policy says it may. Three levels decide what happens:

Every decision, approval and state change ends up in the audit log with who, what and when. See Policies, presets and authority levels.

Try it

The quickstart runs exactly this invoice story on a public sample repository, from requirement to verified pull request.