Your first story | kanman documentation

Your team is set up. Now pick one real piece of work and let kanman finish it. This page shows both ways in, what happens on the way, and what to do when kanman stops to ask.

Pick a good first story

The first story should build trust, not test limits. Good candidates:

small (size S), in an area your team knows well
with an outcome a person can see or call: a new API field, a filter, a validation message, a CSV column
not touching infrastructure, migrations of production data, or security settings

Avoid broad refactors and anything that needs a decision from someone who is not in the room. kanman would stop and ask, which is correct but slow for a first run.

Way 1: Start from a requirement (intake)

On the team page, open the Intake tab or click New intake.
Paste the requirement as you would write it to a colleague: a sentence, a paragraph from a spec, or a Slack thread copied as text. Click Send (or press Ctrl+Enter).
kanman first decides what the message is. Only a work request becomes stories; a status question gets an answer in place, and an operational request (pause or resume the team, cancel a run, expedite or deprioritize a story) is carried out. Pausing and resuming need a workspace admin. If the requirement is too vague, kanman asks up to three questions first; answer them and click Draft again.
For a work request, kanman drafts one or more stories, each with:
- acceptance criteria in Given/When/Then
- a Demonstrate block: concrete steps that show the outcome
- a test plan, a size (S, M, L), the affected areas and open questions
- a readiness score from 0 to 100
Edit what is wrong, answer open questions, Reject what you do not want and Approve the rest. Only stories that pass every readiness check can be approved.
Click Write N stories to tracker.

Approved stories are written to your tracker in one batch and carry the pickup label (kanman by default). They land in the Backlog column.

Screenshot coming soon Intake review with three drafted stories, each showing acceptance criteria, a Demonstrate block and a readiness score

Way 2: Start from an existing issue

If the issue is already written:

Add the pickup label (kanman by default) to the issue in GitHub, GitLab or Jira.
kanman mirrors the issue onto the team board, in the column of its status. The story page (/teams/<team>/stories/<KEY>) shows its readiness and lets you add missing acceptance criteria and a Demonstrate block.

A story needs a Demonstrate block before kanman can write its acceptance spec. See Stories and acceptance criteria.

Move the story to Ready

Drag the card to the Ready column in kanman (or use Move to on the card), or move the issue to the matching status in your tracker. The card first waits in Refining with the note “Checking the acceptance spec”. What happens next depends on whether your repository has an acceptance manifest:

Repository	What kanman does before it builds
With `.kanman/acceptance.json`	Writes an acceptance spec from the Demonstrate block to `.kanman/acceptance/<KEY>/`, runs it, and requires it to fail. The story page shows Spec: red (expected). Then the run starts.
Without a manifest, on Trial	Moves the story to Ready and starts the run. The evidence pack will say plainly that no outcome proof exists.
Without a manifest, other presets	Keeps the story in Refining with the reason “The repository has no .kanman/acceptance.json”.

Approve the plan

With plan approval set to always (the default), kanman posts its plan to Decisions before writing code: the approach, the files it expects to touch, and how it will demonstrate the result. Click Approve plan, or choose Request changes with a note: kanman revises the plan and asks again. Reject ends the run and moves the story back to the Backlog.

Follow the run

The run page (/teams/<team>/runs/<run-key>) shows the stages Planning, Implementing, Verifying, Review and Done, with live progress lines, the attempts and the cost against the run budget. You can Stop the run at any time and Retry it later.

When kanman stops and asks

kanman never guesses on things that need a person. Typical stops, all in Decisions:

You see	What it means	Typical answer
Plan approval	kanman wants your OK before coding	Approve plan
Question	kanman needs a product or technical decision and offers 2 to 4 answers	Pick an answer; kanman’s recommendation is marked
Policy exception	The work would touch a denied path	Allow once, or Reject with a note
Budget stop	The run reached its budget	Raise to the offered amount, or Abandon
Verification failed	The gate failed again after the automatic rework	Retry once more, or Abandon the run

Each decision explains the situation and kanman’s recommendation. Your answer, your name and the time are recorded in the audit log.

Review and merge

When the run reaches Review, the pull request carries the evidence pack: the plan, each acceptance criterion with its result and file references, the gate results with artifacts (Playwright trace, screenshots), tests, CI, policy decisions, cost and duration. Review the code as usual. Merging moves the story to Done.

After the first story

Let two or three more stories through before you change settings.
Look at the run cost and duration in the evidence packs to calibrate the run budget.
When the team trusts the flow, consider a different preset: Choose and tune a preset.