Setting up and driving the ticket tree with Sofia

Use this when a user asks how to set up or drive the ticket tree with Sofia (bmad-agent-po). For the shared ticket-tree design, see help/ticketing-and-epics.md.

Where the store lives

• The ticket tree is the folder active_initiative names under output_folder: an initiative with its epics inside, a single epic, or a backlog folder of epics or one-off stories, as the user wants. Tickets with no epic go in {output_folder}/backlog/. With no active folder, Sofia offers to create one and record it.
• An epic's stories are entries in its tickets.toml; a story gets a markdown file only when it is reviewed, refined, or published. Tickets with no epic are markdown files.
• output_folder is _bmad-output unless changed under [core] in _bmad/custom/config.toml (committed, applies to the team).

Several repos

Install BMad in the workspace folder that holds the repos, put the store there, and start the AI tool from that folder so one session reaches the plan and every repo. Give a new store folder its own git init.

Existing planning documents

Copy a brief, PRD, UX design, or architecture into the initiative folder as <type>-<slug>/<type>-<slug>.md, for example initiative-checkout/prd-checkout/prd-checkout.md. The UX files keep their names, DESIGN.md and EXPERIENCE.md, inside ux-<slug>/. Copy, do not move, so other skills still find their files. Sofia writes the initiative's Requirements from them, each line naming its source id; each epic's lines are cut from those, and the stories cite their epic's R<n> ids.

Trackers

• Tickets are files in the store unless the user connects a tracker: "set up the ticket store", or "reconfigure the ticket store" to change it later. Nothing needs setting up for the repo store.
• The choice goes in _bmad/custom/ticketing-store-config.toml. It holds only what the project sets, such as the tracker's project key; a key added there overrides the skill's default for that tracker.
• Choices: repo (the default; files under version control, no account), GitHub Issues, Jira, Linear, Notion, or Trello. Sofia checks the needed CLI or connection at setup.
• Repo is the most tested. The trackers are lightly tested.
• With a tracker, the markdown files stay the working copy. Nothing syncs on its own: files and tracker line up only when the user asks Sofia. She never pushes.

What the user says

Hand-off to bmad-build

• A planned story needs no file. Run bmad-build on it: "build story 1.2", naming the epic's id and the story's. The builder reads the entry, its epic, the story file when there is one, and the documents their References name, such as a codebase research document. It plans the story's acceptance criteria from the epic's Requirements and Done when, the entry's description, and its Verify: check.
• A story needs no refining before bmad-build; the build refines it. Before an unattended run, talk to Sofia the Product Owner to review the stories. A bug, a ticket with no epic, and an entry the user marked refine = true get full criteria first; "what's next?" lists these under ready to refine.
• The build writes its plan, <type>-<slug>-plan.md, beside tickets.toml. The plan carries the ticket's status, which the build moves as far as built. After reviewing the work, the user says "mark story 1.2 done".

Feedback

Open an issue at github.com/bmad-code-org/BMAD-METHOD with "bmad-agent-po" in the title, or post in the BMad Discord. Useful reports say what was given, asked, produced, and expected.