Skip to content

Reference

The Ticket Tree

These are the exact rules for the ticket tree that Sofia, the Product Owner (bmad-agent-po), keeps. For the tasks, see Write and Slice the Initiative, Plan an Epic’s Stories, and Build and Verify.

The tree is the folder active_initiative names under output_folder (_bmad-output by default). Each initiative and epic keeps its own file, other skills’ run folders, and its retrospective at the top of its folder. Its breakdown goes in a tickets/ folder inside it.

_bmad-output/
initiative-<slug>/
initiative-<slug>.md
prd-<slug>/ ux-<slug>/ architecture-<slug>/
tickets/
tickets.toml # the epics, in build order
epic-<slug>/
epic-<slug>.md
epic-<slug>-retrospective.md
tickets/
tickets.toml # the entries, in build order
story-<slug>.md # only when refined or published
story-<slug>-plan.md # written by the build
backlog/ # tickets with no epic, and their plans

A parent initiative’s tickets.toml lists child initiatives, each an ordinary initiative folder beside it, instead of epics. tickets.py refuses a tree in the earlier layout, with tickets.toml beside the container’s own file: run bmad migrate method.

An initiative or epic file is the spec at its level.

SectionHoldsWritten by
Description, OutcomeWhat the work is, and what is true when it is doneSofia
RequirementsOne line per requirement, with a stable R<n> id naming its source: R1 (FR-1), or on an epic R1 (parent R3)Sofia only
ConstraintsRules the work must keep, each citing its source id; no R<n> of their ownSofia only
Done whenThree to six checks that show the work is finished, judged at closure and by the retrospectiveSofia
BoundariesWhat is out of scope, and units the work only touchesSofia
ReferencesDocuments a build reads beside the ticket, such as UX files and the spineSofia, when she adopts them
NotesAssumption:, Open question:, dated Decision:, and Dropped: linesSofia

The frontmatter names sources:, the documents the requirements were derived from, and companions:, the files downstream skills read beside the ticket. Only Sofia re-reads the sources, when she updates the ticket. An epic carries refined: false until it is refined; an epic file with no refined key counts as refined.

A story file uses the same template at story level: Description, a Verify: line or numbered criteria, Boundaries when it has criteria, References, and Notes. A bug adds Reproduction, Cause Hypothesis, and Acceptance Criteria, plus severity P0 to P3; a spike has Approach and Acceptance Criteria and defaults to hitl: true.

Each [[entry]] table in an epic’s tickets.toml is one story, spike, or bug. Table order is build order.

KeyMeaning
idNever reused in its folder; move gives the entry a new id in its new folder. A story is named by its epic’s id and its own, such as 2.1
typestory, spike, or bug
title, descriptionWhat it delivers
verifyHow it is checked
coversThe epic’s requirement ids it delivers
afterReal prerequisites only: a sibling’s id, "<epic id>.<entry id>" in another epic, or "epic-<slug>" for a whole epic
hitltrue when a person does part of the work
risklow, medium, or high: the business impact if the change is wrong
unknownA question that blocks the entry until it is answered and removed
refinetrue to write full acceptance criteria before it starts
plan_checkpointA person reviews the ticket or plan before the run. Honored by whoever starts the runs, not the build
done_checkpointPause after the run until a person says continue. Honored by whoever starts the runs, not the build

Optional keys also include estimate, references, and notes. A build that leaves work for a later story in the same epic adds a line to that story’s notes, or to its file’s ## Notes, with tickets.py note, as long as no build has started it. An entry needs no file to be built. Once a story’s file exists, the file is the source of truth: a build reads the file, and Sofia keeps the entry’s id, type, title, after, and hitl equal to it. tickets.py status reports drift only for after and hitl.

An initiative’s tickets.toml holds one [[epic]] table per epic, in build order. A parent initiative holds [[initiative]] tables with the same keys, and an initiative with no epics holds [[entry]] tables; a file holds one kind of table.

KeyMeaning
idPermanent; never reused
slugThe epic’s folder, inside this tickets/ folder; for a child initiative, its folder beside the parent’s
titleThe epic’s name
descriptionWhat is true when it is done
coversThe initiative’s requirement ids it delivers
afterThe epics it depends on, as [{ epic = 1, needs = "…" }], or initiative = 1 in a parent initiative. It declares the dependency; entries pin it with their own after, or the epic file’s after gates every story until that epic is done

tickets.py status flags unpinned_after, undeclared_after, and order_conflict.

next_id, at the top of the file, is the folder’s id counter, written by tickets.py move.

[[epic]]
id = 2
slug = "epic-free-no-show-rooms"
title = "Free no-show rooms"
description = "A booked room nobody checks in to is freed, and anyone can book it."
covers = ["R1", "R2"]
after = [{ epic = 1, needs = "check-ins recorded by the door tablet" }]

A ticket’s status lives in its build plan, <type>-<slug>-plan.md, beside tickets.toml. The plan stays local on every store; a tracker never receives it.

StatusWritten byBoard state
No plan and no file (an entry only)Nobody yetplanned
A story file with no plan yet; then draft, ready-for-devNobody yet; then the build, as it plansbacklog
in-progressThe buildin progress
blockedbmad-build-auto when it halts, with the reason in the planin progress
in-review, builtThe build; built is the last status it writesreview
doneYou, or a script or AI session you direct: tickets.py mark on the repo store; on a tracker, Sofia moves the card when you say sodone
droppedSofia, when the user says so, with a Dropped: linedropped

The plan’s own frontmatter keys:

KeyHolds
ticketThe entry’s id, or the file’s stem for a backlog ticket
statusOne of the statuses above
baseline_revisionThe commit the work starts from; code review and the retrospective diff from it
typefeature, bugfix, refactor, or chore
routeoneshot or full, set by the build as it plans
riskFrom the entry; the build may raise it. bmad-build-auto never lowers it, and bmad-build lowers it only when you say so
assignee, blocked_at, blocked_reasonWho has it, and when and why it was blocked; written by tickets.py mark
deferred, followup_review_recommendedFindings set aside, and whether another review pass is advised; written by bmad-build-auto

bmad-code-review appends a dated block under ## Code Review in the plan and never changes status. On a tracker store, tickets.py mirror writes the tracker’s state to the leaf file as tracker_status. That state, not the plan’s status, sets the board state and the ready lists, though a plan at blocked, or with a block recorded, still lists an open story as Blocked. The tracker state never makes a build skip planning.

Ask Sofia “what’s next?”, or run tickets.py next. Each open ticket falls in one list. With a tracker store, tickets.py next refuses until you sync ticket status from the tracker and rerun it with --synced.

ListWhen
BlockedIts plan is blocked; a prerequisite is not yet at in-review, built, or done; or a whole epic it waits on is not done. An unknown blocks only when no refinement is pending, and a dropped prerequisite still blocks
In progressIts plan is in-progress, in-review, or built
Ready to refineA bug, a ticket with no epic, or an entry with refine = true, still without approved acceptance criteria. Refining settles its unknown, if it has one
Ready to startAnything else that is not done or dropped

A story at built meets the prerequisites of the stories that wait on it, so builds can follow one another before anyone marks it done.

tickets.py reads the tree and prints one JSON object. Sofia and the build skills run it for you; it is installed at _bmad/method/scripts/tickets.py.

CommandDoes
nextLists what is ready to refine, ready to start, in progress, and blocked
statusEvery ticket, resolved, with problems such as drift between an entry and its file
find <ref>One ticket: its entry, its epic, its file if any, and its plan’s path
pull <dir> <id>Writes an entry’s file in that epic folder
mark <ref> <status>Writes status in the plan, creating it if needed; --assignee <who> records who has it; --blocked <reason> records a block, and a mark without it clears the block
move <from> <ref> <to>Moves an entry, its file, and its plan to another folder under that folder’s next id, and rewrites every after that names it
mirrorRecords tracker ids and statuses in the leaf files

Exit codes: 0 on success, 2 when the store forbids the operation, such as mark on a tracker store, and 1 on any other error, such as a malformed tree or no active initiative.