The story page
Everything about one story on one page, from the status card at the top to its Spec, Plan, Tests and Review tabs.
Open any story, from any tab, and you get the same page. On desktop it opens in a panel beside the map; on a phone it opens full screen. The card at the top says where the story is and offers the one thing to do next. The tabs underneath follow the story from spec to approval: Spec, Plan, Tests, Review.
Story keys
Every story has a key: the project's prefix and a number, for example PB-42. The number is given when the story is created and never changes. Use the key to talk about a story with people and with agents: every MCP tool accepts it.
Change the prefix in Project settings → Story keys. Every key changes at once, and the old keys keep working. A story that hasn't been published yet shows the start of its id instead.
When an agent reads a story with get_story, it's given a branch name made from the key and the title, such as pb-42-reset-a-password. With the GitHub App installed, a pull request from that branch is matched to the story. See Connecting a repo.
The status card
The card at the top is tinted like the story's card on the map, so you can see it's the same story. It shows the status word, the title, a line of facts (its build number, priority, effort and key) and the user story as one sentence. Under that is the next step:
| Status | The card says | Next step |
|---|---|---|
| To do | "To do", or that a plan is ready for review | Mark ready for dev, or Review plan → |
| Ready for dev | "Declared ready by" a person | Ready for dev ✓, with Undo |
| In progress | "Agent building", and when it started | See the live run → |
| Dev complete | How many criteria pass, and when it was built | Review it → |
| Needs rework | "Sent back for rework" | See what was asked → |
| Approved | "Approved by" a person, and when | |
| Blocked | "Blocked — the agent needs a decision" | Resolve → |
If something is missing before the story can move on, the card says what and links to it. For example: "It needs acceptance criteria before it can be ready. Add criteria →".
While a story is in progress, the card also names the agent building it and when it was last heard from, for example "Being built by Claude Code · session 1a2b · last heard from 3m ago". If that agent goes quiet for two hours, the card says Stalled, and another agent may take the story over. Whoever administers the project can choose Release claim to free it straight away.
Spec
The user story and its acceptance criteria. Criteria are numbered cards; + Add adds one. Each criterion shows how many tests prove it, or No test. See Acceptance criteria.
On a story that's already built, if the user story or criteria change, the card shows Spec changed since built: what changed, against what it was built to. Choose Send for rework… so the code follows, or No code change needed to accept the new wording as what it's built against. Neither changes the status on its own.
The story's own assistant, the Spec Agent, can reword criteria, add or remove them, and add tests. Every change it proposes is a draft until you publish it. See Working with agents.
Plan
Two parts: what you give the agent, then what it gives back.
- References: links you add yourself, before any agent has run. Paste a Figma, Claude, image or repo-path link and pick its kind.
- The plan: the agent's numbered steps, the files each one touches, the risks it sees and any questions for you. Keep, drop, comment on or edit any step, and answer its questions. Then Request changes, which sends all your notes to the agent together, or Approve → Ready.
If you request changes, the agent replans and answers each of your points. Steps you edited keep your words. If the spec changes after you approved a plan, the approval no longer holds, and the plan needs another look.
From here you can also hand the story to Claude Code in one tap: Send to Claude Code when there's no plan yet, Build in Claude Code when there is. Or copy a prompt for any other agent. See Working with agents.
Tests
Every test saved for the story, each tagged with the criteria it proves, for example AC 02 · pass. The line at the top names any criterion with no test. A red dot on the tab means a test is failing.
With CI reporting on, a test card reads "passed on" the commit CI ran. See Verification.
With no tests yet, the tab offers a prompt that asks your agent to write and save them.
Review
What to decide, then the evidence for it.
- The verdict, first, for example "4 of 5 criteria pass. One needs you." It names only the criteria that need you, each linking to its tests. If the tests are older than the code, it says so.
- The decision. Approve, or Request changes with a note on what to fix; the note is required to send it back. With gaps, the button reads Approve anyway. After approving you can Re-approve or revert it.
- What the agent built: its summary, the pull request, the files and any screenshot.
- The record: who declared it ready, who built it, who approved it, and every status change in order, with when and where it came from.
While an agent is building, Review shows the run, with a way to stop it. Built the story yourself? Choose Built it yourself? Mark it dev complete → and say what you built.
Only people approve. In a workspace, that's the people who approve plans. See Workspaces and teams.