Skip to content

Reference

Map Your Tracker to the Ticket Tree

Sofia keeps the ticket tree as files and, once you connect a tracker, publishes it there. The files stay the working copy; the tracker is where the team sees the work. This page lists what each level becomes in each tracker, what your tracker has that the tree doesn’t, and how to map levels whose names don’t line up.

Tracker level names don’t match BMad’s. Linear has no Epic object, and in SAFe the Epic sits above the Feature. Match each level of your hierarchy to the BMad level that does the same job:

What the level does hereBMad level
Groups several product efforts, such as a programParent initiative
One outcome with its own requirementsInitiative
One increment that closes once its Done when holdsEpic
One change that fits a single build sessionStory, bug, spike

These are the defaults Sofia’s tracker setup starts from.

BMadJiraLinearGitHub IssuesNotionTrello
InitiativeNot published, unless you map it to your site’s level above Epic (Premium or Enterprise)Not published. Mapping it to Linear initiatives needs initiative tools in Linear’s MCP server, and can’t round-trip: they nest and allow several parentsMilestoneRow of type initiativeCard in the Initiatives list
EpicEpicParent issue labelled epicParent issue labelled epicRow of type epicCard in the Epics list
Story, bug, spikeStory, Bug, or Task labelled spikeSub-issue of the epic, labelled with its typeSub-issue labelled with its typeRow linked to its epic by ParentCard labelled with its type
afterA Blocks linkA blocking relationA blocked-by relationThe Blocked by relationThe blocker’s link in the card’s description
hitl, riskLabelsLabelsLabelsPropertiesLabels

A level that isn’t published leaves its children attached to the nearest published level: with the Jira defaults, epics publish as top-level Epics. The Jira store works with Jira Cloud through acli, Atlassian’s command line.

Statuses map the same way:

BMad stateJiraLinearGitHub IssuesNotionTrello
backlogTo DoBacklogbacklog labelBacklogBacklog
in-progressIn ProgressIn Progressin-progress labelIn ProgressIn Progress
reviewIn ReviewIn Reviewreview labelReviewReview
doneDoneDoneClosedDoneDone
droppedDone, resolution Won’t DoCanceledClosed as not plannedDroppedArchived
Your tracker hasThe ticket tree
Sprints or cyclesNo time boxes; work flows in build order. Keep running sprints in the tracker; Sofia doesn’t read or set them.
Fix versions or releasesNo release grouping, and none is synced. Keep releases in the tracker.
A backlog of all unstarted workbacklog/ holds only work that belongs to no epic. An unstarted story stays in its epic, as backlog, and publishes as To Do.
Epics that grow as long as the feature lastsAn epic gets a retrospective, then closes only after Sofia checks its Done when. Work it doesn’t need moves to another epic, so it can close.
Linear projectsNot tied to a ticket-tree level by default: epics are parent issues and initiatives stay local. The store can still set an issue’s project.
GitHub milestones used for releasesBMad uses milestones for initiatives. If yours mean releases, leave initiatives unpublished.

Nothing syncs on its own: Sofia publishes and reads the tracker during the board steps you run with her.

  • By default, she offers to publish the whole agreed breakdown once it’s validated. To publish each ticket only when it starts, set publication = "on_start" under [workflow] in _bmad/custom/bmad-agent-po.toml.
  • When she next syncs, status, assignee, and blocking links come back into the files. A story someone adds in the tracker under a published epic comes back as a new entry. When a description differs between the tracker and the file, she shows both and asks which to keep.
  • Tracker status doesn’t make a build skip work, and Sofia doesn’t push your files to Git.

Sofia publishes the tree she holds. There’s no step for adopting an epic that already exists in the tracker: plan the work with Sofia and let her publish it.

Your choices live in _bmad/custom/ticketing-store-config.toml, which Sofia writes during setup and which survives skill updates. Each key overrides the tracker’s default. For a Jira site with an Initiative level above Epic:

[tickets]
store = "jira"
key = "ROOM"
site = "your-company.atlassian.net"
[tickets.types]
initiative = "Initiative"

Use the name your site gives that level. Statuses go under [tickets.status] the same way; a BMad state with no tracker status takes the previous state’s. To change the mapping, ask:

/bmad-agent-po reconfigure the ticket store