Skip to content

Plan

Set Up the Ticket Tree

Sofia, the Product Owner (bmad-agent-po), is how BMad plans and tracks work: she writes each ticket’s requirements and breaks work into epics and stories in the shared ticket tree. Build, Build Auto, code review, and retrospective consume that tree.

With BMad installed and tickets kept in the repository, the default, there is nothing to set up: go to Write and Slice the Initiative. Read on to install only Sofia’s skills, keep the store somewhere else or across several repos, or track tickets in a tracker.

Install with the skills CLI. Run this in your project:

Terminal window
npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-core-tools --skill bmod-method --skill bmad-agent-po

Add --skill bmad-build and any other skill you want in the same command. Then open your AI tool in the project, ask the bmad skill to run bmad setup, and check that the tool lists bmad-agent-po. Update later by asking bmad to run bmad setup again.

The initiative store is the folder where planning lives: one folder per initiative, plus a backlog/ folder for standalone tickets. An initiative is one body of work, such as a product, a major feature, or a migration. Its planning documents and its tickets sit together in its folder.

The store is your BMad output folder, _bmad-output by default. You can configure it to be any folder; the example below uses _bmad-initiative-store instead, and step 2 shows the setting. In a single repo, the default inside the project works fine.

When the work spans several repos, install BMad in the workspace folder that holds them and put the store there too. Start your AI tool from that workspace folder, so one session can reach the plan and every repo it touches. Give the store its own git init, which keeps planning history apart from each repo’s code history.

rooms-workspace/ # start your AI tool here; not a repo itself
├── _bmad/ # BMad install and configuration
├── _bmad-initiative-store/ # the store — its own git repo
│ ├── initiative-check-in/
│ │ ├── initiative-check-in.md
│ │ ├── prd-check-in/
│ │ │ └── prd-check-in.md
│ │ └── tickets/ # the initiative's breakdown
│ │ ├── tickets.toml # the epics in build order
│ │ └── epic-door-check-in/
│ │ ├── epic-door-check-in.md
│ │ ├── ux-door-check-in/ # a bmad-ux run on this epic
│ │ └── tickets/ # the epic's breakdown
│ │ ├── tickets.toml # every planned story, in build order
│ │ ├── story-show-each-room-on-its-door-tablet-plan.md # the build's plan and the story's status
│ │ └── story-check-in-at-the-door.md # a story's file, only when refined or published
│ ├── initiative-room-analytics/
│ └── backlog/
│ └── bug-recurring-booking-shows-twice.md
├── rooms-api/ # code repo
├── rooms-web/ # code repo
└── door-tablet/ # code repo

Skip this step when you keep the default. Otherwise set output_folder in _bmad/custom/config.toml, which is committed and applies to the whole team:

[core]
output_folder = "{project-root}/_bmad-initiative-store"

{project-root} is the folder that holds _bmad/. In the layout above, that is rooms-workspace/.

Set the initiative you are working on in _bmad/custom/config.user.toml, which is personal and not committed:

[core]
active_initiative = "initiative-check-in"

The value is the initiative’s folder name in the store. When it is unset, Sofia offers to create the folder and record the setting for you. You can also ask the bmad skill to show, switch, create, or clear the active initiative at any time.

The planning skills write into the active initiative’s folder, each document as <type>-<slug>/<type>-<slug>.md. If you have a project from an earlier BMad version, ask the bmad skill to run bmad migrate method: it plans the move for the planning documents, epics.md, sprint-status.yaml, and the stories, shows you the plan, and applies it. The same command moves an earlier tree, with tickets.toml and epic folders directly in the initiative folder, into the tickets/ folders. To move only a few planning documents by hand, copy them in the same way:

_bmad-output/planning-artifacts/brief.md → initiative-check-in/brief-check-in/brief-check-in.md
_bmad-output/planning-artifacts/prd.md → initiative-check-in/prd-check-in/prd-check-in.md
_bmad-output/planning-artifacts/DESIGN.md → initiative-check-in/ux-check-in/DESIGN.md
_bmad-output/planning-artifacts/EXPERIENCE.md → initiative-check-in/ux-check-in/EXPERIENCE.md
_bmad-output/planning-artifacts/architecture.md → initiative-check-in/architecture-check-in/architecture-check-in.md

UX is the exception to the naming: bmad-ux writes two peer documents, DESIGN.md and EXPERIENCE.md, which keep their names inside the ux-<slug> folder beside a short ux-<slug>.md that names them. Your source paths will differ.

Out of the box, tickets are markdown files in the store, and there is nothing to set up. To use a tracker, ask Sofia:

/bmad-agent-po set up the ticket store

Sofia writes your choice to _bmad/custom/ticketing-store-config.toml. That file holds only what your project sets, such as the tracker’s project key. Anything you add to it overrides the skill’s default for that tracker, and your edits survive skill updates.

ChoiceWhat it means
RepoThe default. Tickets are markdown files in the store. No account needed.
GitHub IssuesTickets publish as issues, with sub-issues and blocked-by relations.
JiraTickets publish as Jira issues.
LinearTickets publish as Linear issues.
NotionTickets publish as rows in a Notion database.
TrelloTickets publish as cards.

With a tracker, the markdown files remain the working copy and the tracker is where the team sees them. Setup offers to connect the tool, create the labels or fields it needs, and prove the connection with a test ticket. Map Your Tracker to the Ticket Tree shows what each level and status becomes in each tracker, and what has no counterpart. To change it later:

/bmad-agent-po reconfigure the ticket store

With the store set, talk to Sofia to write and slice the work, and to see what is ready. Write and Slice the Initiative and Plan an Epic’s Stories walk through the steps, Build and Verify hands a story to the build, and The Ticket Tree has the exact layout, fields, and statuses.

With a tracker, start the story with Sofia before you build, so the ticket publishes if it has not and its card moves to in progress:

/bmad-agent-po start story 1.2

The tracker’s status is read into the story’s file as tracker_status, so moving a card on the board never makes a build skip planning.

Feedback helps improve Sofia and her tracker integrations. The most useful reports say what you gave her, what you asked for, what she produced, and what you expected instead. Open a GitHub issue with “bmad-agent-po” in the title, or post in Discord.