Runs | kanman documentation

A run starts when a ready story is picked up and ends when the story is done, or when it stops for good. On the way it may pause to ask you. Everything about it is on the run page: the stages, the live progress, the attempts, the cost against the budget, the evidence and the decisions it raised.

Open a run from the story card on the team page, from the team’s Runs tab, or directly at app.kanman.ai/<workspace>/teams/<team>/runs/<run-key>. Run keys are short, for example run-7f3k.

Screenshot coming soon Run page with the stage timeline, live progress lines, cost meter against the run budget and the evidence pack

Stages

Every run moves through the same stages:

Stage	What happens
Planning	kanman classifies the story and plans. If the policy requires plan approval, the executor plans read-only and the plan goes to the decision inbox first
Implementing	The executor (Claude Code or Codex) changes the code on its own branch in a sandbox
Verifying	kanman runs the first gates: the acceptance spec in a freshly provisioned environment, the diff guard and the policy limits on the diff
Review	The pull request is open. CI, the reviewer run and the clean-room check run; when they pass, kanman posts the evidence pack and the pull request becomes mergeable
Done	Merged, by a person or automatically if the policy allows it

The executor reports progress while it works. These lines appear live on the run page, for example “Reading the invoices module”. The run page only lists the stages a run has reached; the next ones are shown as upcoming.

Status

Cards and the run page show one status per run:

Status	Meaning
Queued	Waiting for a free slot, for working hours or for budget
Planning, Implementing, Verifying, Review, Done	The stage the run is in
Waiting for a decision	Stopped until someone answers a decision
Blocked by policy	Stopped by the policy, for example a denied path; a decision is waiting
Stopped: budget reached	The run used its budget; a decision is waiting
Parked	Paused after a transient failure or a repeated gate failure
Failed	Stopped for good, the reason is on the run page
Stopped	Stopped by a person

Attempts and rework

A run can have more than one attempt. All attempts share the same run key. If verification fails, kanman starts one automatic rework attempt and gives the executor the gate output and the reviewer’s findings. The run page then shows, for example, Attempt 1: criterion 2 failed.

If the rework attempt fails too, or a gate keeps failing, the run does not loop. It goes to the decision inbox as Verification failed or Repeated gate failure. How many rework attempts and gate failures are allowed is set in the policy (rework_attempts, gate_failure_budget).

Complexity routing

When a run starts, kanman classifies the story as trivial, routine or complex. The class picks the model tier, the turn budget and the ceremony:

Class	Model tier	Turn budget	Ceremony
trivial	small	60	none
routine	mid	120	plan and self-review
complex	flagship	200	several scored approaches, then a plan

This is the main cost lever: small changes do not pay for the most expensive model. You can change the tier and turn budget per class in the policy (routing); Settings > Executor shows the resulting model for each class.

The reviewer run that checks the acceptance criteria uses a model from the other vendor (a Codex model for Claude Code and the other way round), so the code is never checked by the model that wrote it.

The run scratchpad

Each run keeps an append-only scratchpad with these sections:

Classification
Approaches
Plan
Implementation notes
Self-review
Review verdict
Retrospective
Decisions

The plan and the scored approaches appear in the evidence pack. The retrospective and the reviewer’s objections feed the team’s conventions, and your notes on decisions reach the next attempt from here.

Cost

The cost meter on the run page shows the cost of the run against the run budget (2.00 EUR by default). When a run would exceed its budget, it stops with Stopped: budget reached, no pull request is created, and the decision inbox asks Raise budget for this run?. See Budgets and cost.

Actions on a run

Action	Effect
Stop	Cancels the run after a confirmation. The story stays where it is and keeps its history
Retry	Queues a new attempt under the same run key
Open decision	Jumps to the open decision of this run

Every state change of a run is written to the audit log as run_state_changed, with the person who clicked as the actor.

Transient failures heal quietly

Network errors, an overloaded model API or a crashed executor are not your problem. kanman parks the run and retries it after 1, 5 and 15 minutes. These failures never reach the decision inbox. The run page shows Recovered after a transient error once it continues. After three failed retries the run ends as Failed with the reason on the run page.

If your git host or tracker does not answer, kanman holds new runs and parks running ones until the service is back, for at most three hours.

The health check

kanman regularly checks the team’s runs between attempts (every 15 minutes) and the team’s main branch (every 5 minutes):

A run whose gates keep failing (the gate_failure_budget is used up, or the story failed twice as often across runs) is parked, and a Repeated gate failure decision offers Retry with my guidance, Retry as is or Stop this run.
A run whose spend reached its budget is parked, and a Budget stop decision offers to raise the budget or stop.
If CI on your main branch turns red, kanman holds its automatic merges and opens a Main branch is red decision. When a merged pull request from a kanman run is the likely cause, kanman opens a revert pull request on GitHub and asks before it is merged. On GitLab the decision opens without a revert pull request.

The team page shows the result as a health line, for example 1 run parked for repeated gate failure or Main is red, merges on hold.