bmod-method

[bmod]
code = "method"
version = "6.13.0-next"
update_source = "github:bmad-code-org/BMAD-METHOD/skills"
skills = [
  "bmad-agent-analyst",
  "bmad-agent-architect",
  "bmad-agent-dev",
  "bmad-agent-pm",
  "bmad-agent-ux-designer",
  "bmad-architecture",
  "bmad-build",
  "bmad-build-auto",
  "bmad-code-review",
  "bmad-correct-course",
  "bmad-create-epics-and-stories",
  "bmad-prd",
  "bmad-preview-ticketing",
  "bmad-prfaq",
  "bmad-product-brief",
  "bmad-project-context",
  "bmad-qa-generate-e2e-tests",
  "bmad-retrospective",
  "bmad-spec",
  "bmad-sprint-planning",
  "bmad-ux",
  "bmad-walkthrough",
]
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]

# Analysis skills in detail

Read this when the question is about `bmad-product-brief` or `bmad-prfaq`: what each gives, when to pick it, when not to, and how the two relate. Both exist to give `bmad-spec` better input.

**`bmad-product-brief`** — describes a product the user already believes in. The light way to give `bmad-spec` good input: more than a hand-written intent file, much less than a full PRD.
- Gives: a 1-2 page brief (problem, solution, who it serves, what is different, success criteria, scope, vision) that is the user's own, plus an addendum holding detail meant for later documents.
- Pick when: the user knows what they want and needs it written down, would otherwise hand-write an intent file and wants it sharper, does not need the rigor of a PRD, needs a pitch or alignment document, has material to distill, is short on time (its fast path drafts everything with `[ASSUMPTION]` tags), or has a brief to update or pressure-test.
- Not when: the user doubts the idea itself → `bmad-prfaq`. The brief never asks whether the product should exist. Requirements need ids, journeys, and metrics, or compliance and many stakeholders are involved → `bmad-prd`.
- Writes: `{planning_artifacts}/briefs/brief-{project_name}-{date}/brief.md`.

**`bmad-prfaq`** — tests whether a concept survives scrutiny, using Amazon's Working Backwards.
- Gives: a press release for the finished product, hard customer and internal FAQs, and a verdict on what is solid, what needs work, and what could sink it. "Go deeper first" is a good outcome. All market claims are researched.
- Pick when: the user is unsure the idea is worth building, leads with a technology or a solution instead of a customer problem, is about to commit real money or people, or asks to be challenged.
- Not when: they cannot name a customer or problem after a few exchanges → `bmad-forge-idea` or `bmad-brainstorming`. They only need a write-up → `bmad-product-brief`.
- With the brief: most projects need one of the two. Pick by what the user lacks, a clear description or confidence in the idea. A brief after a PRFAQ is reasonable when stakeholders need a short read.
- Writes: `{planning_artifacts}/prfaq-{project_name}.md`, plus `-distillate.md` beside it when finished.

# How long to keep planning and implementation artifacts

Use this when the user asks whether to keep PRDs, specs, stories, and build records after the work is done, where they should live, or how to stop old plans from confusing agents. There is no hard rule. This is BMad's suggestion, and the user may reasonably choose otherwise.

## The principle

A PRD, a spec, or a user story is a snapshot in time. Once the work ships, the code moves on and the document does not, so it starts to mislead: it describes decisions that were later changed and features that were later reworked. An agent that reads it may trust it over the code. Version control already holds the history.

So: archive finished planning and implementation artifacts, and keep only the small documentation needed to maintain the system going forward (`help/preparing-a-repo-for-agents.md`).

## Stories and the end of an epic

- Keep every completed story file in the folder of the epic being worked on. Later stories and the retrospective read them.
- Before closing the epic, run `bmad-retrospective`, decide what to do about its findings, then close the epic out.
- After that, it is a good idea not to keep the story files in the repository or locally. They are already in git history.

## If the user prefers to keep everything

That is a fair choice, and it matters less when the artifacts live in their own repository apart from the code. It has a cost to manage:

- Add a rule to `AGENTS.md` telling agents not to read completed epics' stories, only the epic in progress.
- Even with the rule, old content can still reach an agent and degrade its work on later epics. The more that is kept, the more likely that is.

## Other planning artifacts

Briefs, PRDs, UX files, architecture documents, and specs for finished work are also generally not worth keeping live once the work is complete. Archive them the same way.

When the output folder holds more than one body of work, organize it by initiative, one folder each. This will be the norm in v7. Then add a rule to `AGENTS.md` telling agents to ignore everything in that folder except what is under the active initiative.

## Where the artifacts live

BMad recommends making the output folder (`_bmad-output` by default) its own git repository, with commits as planning progresses. Planning gets a history of its own, archiving is a commit that removes files, and anything archived can be recovered. In a poly repo workspace that folder already sits outside the project repositories (`help/monorepo-and-polyrepo.md`).

# Using the method on an existing codebase

The method works on an inherited or long-lived codebase with no up-front documentation pass. `bmad-build` investigates the repository on every run, writes down what to reuse and what not to change, and follows that. Too little planning costs one build run, so start small and add planning only when the work calls for it.

BMad is installed per project. The existing repository needs its own install and its own `bmad setup`.

## Suggested order

1. **`bmad-project-context`**, recommended. A good initial `AGENTS.md` is worth having: it records a small, verified set of rules for agents. Skipping it does not fail a build; the cost is the same mistake every session until someone writes the rule down. When the repo already has a maintained `AGENTS.md` or `CLAUDE.md`, it adopts that file instead of starting over. It does not produce a repo overview or a stack list, so it will not teach the user the app.
2. **`bmad-walkthrough`**, when the user does not know the code. It guides them through a file, directory, commit, or PR at their own pace: intent first, then broad strokes, then detail.
3. **`bmad-architecture`**, only when needed. It can start from the codebase and ratify the conventions worth keeping in a short decisions list. Skip it when the codebase is well documented or the changes are small.
4. **`bmad-build`** for the first change. Pick something one session can finish. A change that follows established patterns, such as a new route in a layered API, needs no planning skill: a short intent file or a few sentences is enough input.
5. **`bmad-spec`**, then one `bmad-build` per story, when a change is bigger than one session.
6. **`bmad-qa-generate-e2e-tests`**, when the inherited app has little test coverage. It generates API and end-to-end tests for features that already exist.

If the codebase is inconsistent or has few tests, cleanup first pays back in every later session (`help/preparing-a-repo-for-agents.md`).

## What pushes a change up a tier

Size alone does not. A change needs more than `bmad-build` when it forces a decision the existing patterns do not cover: a new boundary between components, a schema migration strategy, new authorization rules. The user can also state such a decision in the intent, and `bmad-build` will raise it while clarifying.

# BMad Method knowledge

This document covers the skills of the `method` module: what each one gives the user, when to recommend it, and what to offer next.

## How the method works

The method turns an intent of any size into working software. Recommend the smallest path that safely fits the work; never march the user through every skill. A project may hold only some of these skills: recommend from what is installed, and say plainly when a step has no installed skill rather than inventing a substitute.

**`bmad-spec` is the hub.** It condenses any input, at any altitude, into a spec folder: `SPEC.md` plus companion files, the contract every build reads. A user can talk to it directly. Every analysis and planning skill exists to give the user better material to feed into a spec, and they can run in any order, before or after the spec exists, because the spec is re-derived from a running log and never hand-merged. After any of them finishes, the usual next step is to fold its result into the spec with `bmad-spec`.

The four phases are analysis (ideation, research, is it worth building), planning (what exactly, and in what slices), implementation (build it), and validation (is it right). They describe what kind of help a skill gives. They are not a mandatory sequence to complete.

Project size decides how many build sessions the work needs. Stakes decide how heavy the planning gets. A large hobby project keeps planning light; a small change to a regulated system may not.

## More detail

This document should be enough to route the user and say what to do next. Each topic file below sits in this folder and goes deeper on one subject. Read one only when the question is about that subject, using the path the knowledge script lists for it.

| Topic file | Read when the user asks about |
|---|---|
| `help/analysis-skills.md` | `bmad-product-brief` or `bmad-prfaq` in depth: what each gives, when to pick it, when not to, how they relate. |
| `help/planning-skills.md` | `bmad-spec`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, `bmad-create-epics-and-stories`, `bmad-sprint-planning`, or `bmad-preview-ticketing` in depth. |
| `help/implementation-skills.md` | `bmad-build`, `bmad-build-auto`, or `bmad-correct-course` in depth. |
| `help/validation-skills.md` | `bmad-code-review`, `bmad-walkthrough`, `bmad-qa-generate-e2e-tests`, or `bmad-retrospective` in depth. |
| `help/prototyping.md` | Prototyping or vibe coding first, what a prototype is good for (worth doing, feasibility, complexity, unknowns), non-engineers prototyping, what to do with a prototype afterwards, whether planning still matters after a good first version. |
| `help/existing-codebase.md` | Using BMad on an inherited, brownfield, or long-lived codebase. |
| `help/preparing-a-repo-for-agents.md` | Getting a codebase ready for agentic coding, inconsistent agent output, how much documentation to keep (small ADRs, not heavy docs), regular refactoring, holding quality over time. |
| `help/artifact-lifetime.md` | Whether to keep PRDs, specs, stories, and build records after the work is done, archiving, closing out an epic, keeping old plans from misleading agents. |
| `help/monorepo-and-polyrepo.md` | Where to install BMad and keep planning when work spans one repository or several; the workspace layout for a poly repo. |
| `help/working-in-an-organization.md` | A team or enterprise: an existing PRD, Jira or another tracker, approvals and sign-off, document owners, several engineers in parallel, requirements changing mid-flight. |
| `help/ticketing-and-epics.md` | How `bmad-preview-ticketing` works (initiatives, epic inception, the breakdown, pull and refine), why it differs from epics plus sprint planning, and which to pick. |
| `help/ticketing-setup.md` | Setting up and driving `bmad-preview-ticketing`: the store, several repos, trackers, the phrases to say, the hand-off to `bmad-build`. |
| `help/unattended-builds.md` | `bmad-build-auto`, building stories with no human present, a blocked run and how to retry, what to check after a run. |
| `help/review-choices.md` | Review depth, skipping review, another review pass, when to stop, slow reviews, customizing review. |
| `help/project-context.md` | `bmad-project-context` in depth: what belongs in `AGENTS.md`, why the block is small, its intents, removing a rule. |

## Start here

- Can one session understand, build, review, and finish it?
  - Obvious and low-risk (typo, formatting, config): just make the edit. No skill.
  - Yes → `bmad-build`. No planning skill first.
- Bigger than one session: does the user already have enough to say or paste (an idea they can explain in detail, notes, intent.md, single ticket, a transcript, a brief, a PRD)?
  - Yes → `bmad-spec`, then `bmad-preview-ticketing` with the spec folder to plan the stories. Then pull each story, and one `bmad-build` per story.
  - No → find what is missing, run the skill that supplies it, then `bmad-spec`:
    - They cannot name a customer or a problem → `bmad-forge-idea` or `bmad-brainstorming` (core tools), if installed.
    - Unsure the idea is worth building → `bmad-prfaq`.
    - Sure of the idea, but it is not written down or not shareable → `bmad-product-brief`. It is also the lighter choice when a full PRD is more than the work needs.
    - Requirements need real detail, or many stakeholders, compliance, or integrations are involved → `bmad-prd`.
    - The look and feel matter, or the user thinks best in screens and flows → `bmad-ux`. Starting with UX is a normal way in.
    - Separate people, agents, or sessions could build parts that do not fit together → `bmad-architecture`.
- Wants to prototype first, or is unsure the work is worth doing, feasible, or how complex it is → encourage a prototype. It suits enterprise work as much as hobby work, greenfield or existing code, and non-engineers can build one. A throwaway needs no skill. Afterwards the user decides to throw it away or keep it, and either way what it taught them goes into `bmad-spec` (`help/prototyping.md`).
- Risk, unclear requirements, architectural reach, or coordination between people push work up a tier even when it is small.

## Match the situation

Situations the tree above does not settle.

| The user says or has | Recommend | Because |
|---|---|---|
| "I want to start from the design" | `bmad-ux` | UX may lead. Feed its files to `bmad-prd` when requirements still need drawing out, to `bmad-product-brief` for a lighter write-up, or straight to `bmad-spec` when they say enough. |
| A prototype, and asks what now | Decide: throw away or keep | Thrown away, the notes go to `bmad-spec`. Kept, treat it as an existing codebase (`help/prototyping.md`). |
| Work spans several repositories | Install BMad at a workspace root that holds them all, with planning kept there | One session then reaches the plan and every project (`help/monorepo-and-polyrepo.md`). |
| "How do I get my repo ready for AI agents?", or agents keep producing inconsistent work | Consistent patterns, a good initial `AGENTS.md`, end-to-end tests, and cleanup first when quality is low | Agents copy what they find (`help/preparing-a-repo-for-agents.md`). |
| "Do I keep the PRD, spec, and stories once it is built?" | Archive them and keep only small maintenance documentation | They are snapshots in time and mislead agents later; git keeps the history (`help/artifact-lifetime.md`). |
| An inherited or brownfield codebase | A small `bmad-build` change first; `bmad-project-context` and `bmad-walkthrough` as needed | No up-front documentation pass is required (`help/existing-codebase.md`). |
| "I don't know architecture, stacks, or hosting" | `bmad-architecture`, or the architect agent to talk it through | It coaches, recommends a current starter, and lays out options with reasons for the user to choose. Technical knowledge is not needed to start. |
| "An app for X" and nothing more | `bmad-product-brief`, or `bmad-prd` when the stakes call for full requirements | `bmad-spec` distills and will not coach; the input is too thin for it. The brief is the lighter of the two. |
| A PRD and architecture, several epics, wants tracking | `bmad-create-epics-and-stories` → `bmad-sprint-planning` | The only route with acceptance criteria up front and a status file `bmad-build` keeps current. |
| A team with an existing PRD, a tracker, approvals, or several engineers | The full path only when approvers, parallel teams, or required documents call for it | The existing PRD is input, each document has one owner, and sign-off attaches to skill results (`help/working-in-an-organization.md`). |
| "Can BMad build my stories by itself?" | `bmad-build-auto`, dispatched per story by a loop | It suits settled decisions and well specified stories, with someone reading the results. For work planned with `bmad-preview-ticketing`, give it the pulled ticket file, one run per ticket (`help/unattended-builds.md`). |
| Wants tickets or a tracker (Jira, Linear, GitHub) as the record | `bmad-preview-ticketing` | Tickets are the board. It is a preview; a ticket's `status` belongs to the build, and until `bmad-build` writes it the user marks tickets by hand. |
| "Where are we?" with a `sprint-status.yaml` | `bmad-sprint-planning` status | It reads the file and names the next story. |
| A v6 project (`epics.md`, `sprint-status.yaml`, dated folders under the planning folder) that wants the v7 layout | `bmad migrate method` | The module ships `v6-v7-migration.toml`: the rules for moving the project's artifacts into initiative folders, turning epics and sprint status into a ticket tree, and putting loose work in `inbox/`. The `bmad` skill plans it with the user, then performs it. |
| A PR, a branch, or code `bmad-build` did not write | `bmad-code-review` | Agent lenses over any diff. |
| "Walk me through what changed" | `bmad-walkthrough` | The human is the reviewer. |
| All stories of an epic or spec folder are done | `bmad-retrospective` | It judges the whole against the spec. |
| A big change surfaced mid-build | Spec route: update through `bmad-spec`. Epics route: `bmad-correct-course`. | Correct course needs a PRD and epics and halts without them. |
| Wants an expert to think a phase through with, or is unsure where to begin in it | The agent for that phase (see "The agents") | It guides across turns and runs the phase's skills from its menu. |
| Agents keep making the same mistake in this repo | `bmad-project-context` | It records the rule in `AGENTS.md`. |

## The skills

One line per skill: what it is for and what it writes. The files it writes are how to tell what is already done. Open the phase file for the full picture of a skill: what it gives, when to pick it, when not to.

| Skill | For | Writes |
|---|---|---|
| **Analysis** (`help/analysis-skills.md`) | | |
| `bmad-product-brief` | A 1-2 page brief of a product the user believes in. Lighter than a PRD, sharper than a hand-written intent file. It does not judge the idea. | `{planning_artifacts}/briefs/brief-{project_name}-{date}/brief.md` |
| `bmad-prfaq` | Tests whether a concept survives scrutiny: press release, hard FAQs, researched claims, a verdict. | `{planning_artifacts}/prfaq-{project_name}.md` |
| **Planning** (`help/planning-skills.md`) | | |
| `bmad-spec` | The hub. Distills any input into the contract builds read, and updates it. It does not slice or coach; splitting work into stories is `bmad-preview-ticketing`. | `{output_folder}/specs/spec-{slug}/` with `SPEC.md` and companions |
| `bmad-prd` | Coaches detailed requirements out of the user, sized to the stakes. Also updates and validates a PRD. | `{planning_artifacts}/prds/prd-{project_name}-{date}/prd.md` |
| `bmad-ux` | How the product looks and works. May lead, follow, or stand alone. Can produce mocks and wireframes. | `{planning_artifacts}/ux-designs/ux-{project_name}-{date}/` with `DESIGN.md`, `EXPERIENCE.md` |
| `bmad-architecture` | Settles only the decisions that keep separately built parts consistent. Coaches a user with no architecture knowledge, recommends a current starter, and covers hosting and deployment. | `{planning_artifacts}/architecture/architecture-{project_name}-{date}/ARCHITECTURE-SPINE.md` |
| `bmad-create-epics-and-stories` | Breaks a PRD and architecture into epics and stories with acceptance criteria up front. | `{planning_artifacts}/epics.md` |
| `bmad-sprint-planning` | A readiness verdict, then a status file. Answers "where are we" on the epics route. | `{implementation_artifacts}/sprint-status.yaml` |
| `bmad-preview-ticketing` | Preview. A ticket tree run as a board: initiatives, epics, stories planned in `tickets.toml` and refined when pulled, one-off bugs, optional tracker. | Ticket files under `{output_folder}/{active_initiative}/` and `{output_folder}/backlog/` |
| **Implementation** (`help/implementation-skills.md`) | | |
| `bmad-build` | One session of delivery: clarifies intent, plans, implements, reviews, commits. The default for any real change. Takes free text, a spec folder plus story id, or any file as intent. | `{implementation_artifacts}/spec-{slug}.md`, or `stories/{story_id}-{slug}.md` in the spec folder; `deferred-work.md` |
| `bmad-build-auto` | One unattended build of one story, dispatched by a loop or script. Never for attended work. | The same story files as `bmad-build` |
| `bmad-correct-course` | Assesses a significant midstream change on the epics route. Needs a PRD and epics. | `{planning_artifacts}/sprint-change-proposal-{date}.md` |
| **Validation** (`help/validation-skills.md`) | | |
| `bmad-code-review` | Agent review of any diff, PR, or branch, with triaged findings. Redundant right after a full `bmad-build` review of the same change. | A `Review Findings` section in the story file, or chat |
| `bmad-walkthrough` | The human reviews a change block by block, guided. Also a way to learn unfamiliar code. | A review narrative and log under `{implementation_artifacts}` |
| `bmad-qa-generate-e2e-tests` | API and end-to-end tests for features that already exist. | `{project-root}/tests`, `{implementation_artifacts}/tests/test-summary.md` |
| `bmad-retrospective` | Judges a finished epic or spec folder as a whole against its spec. | `epic-{n}-retro-{date}.md`, or `RETROSPECTIVE.md` in the spec folder |
| **Any time** (`help/project-context.md`) | | |
| `bmad-project-context` | Keeps a small, verified block of rules for agents. Use it when an agent got something wrong in this repo, a repo has no usable `AGENTS.md`, or the stack was just decided. It gives no repo overview. | `{project-root}/AGENTS.md` |

### Slicing and tracking the work

Two ways. Use one per piece of work, never both for the same work. A request to split or break up work goes to the second, also when it starts from a spec.

| | `bmad-create-epics-and-stories` + `bmad-sprint-planning` | `bmad-preview-ticketing` |
|---|---|---|
| Needs | A PRD and an architecture | Any intent; best with a spec |
| Gives | Epics, stories with acceptance criteria, a readiness verdict, a status file | A ticket tree used as a board; optional tracker publishing |
| Status | `bmad-build` updates it | Moved by hand through the skill |
| Effort | High: every story approved one at a time | Sized at intake; a single bug or story is quick |

### Who reviews what

| | Reviewer | Looks at | Fixes |
|---|---|---|---|
| Review inside `bmad-build` | Agents | The change just built | Clear findings, itself |
| `bmad-code-review` | Agents | Any diff, PR, branch, or commit | What the human chooses |
| `bmad-walkthrough` | The human, guided | A commit, PR, file, or directory | Nothing unless asked |
| `bmad-retrospective` | Agents, across stories | A whole epic or spec folder | Nothing; proposes action items |

## The agents

Five named experts, each owning a phase and staying in the conversation across turns. An agent carries its role's judgment, offers a menu of the skills it owns, and helps the user decide what to do and why before and between skill runs. Offer one whenever the user wants an expert to work with rather than a single skill to run, is unsure where to begin in a phase, or likes the experience of interacting with unique personas. In the future these agents will have the ability to retain memory and work autonomously which is why they are still a core part of the project.

| Agent | Phase | Work with them to |
|---|---|---|
| Mary, analyst — `bmad-agent-analyst` | Analysis | Brainstorm, research a market, domain, technology, or competitor, then shape a brief or a PRFAQ. |
| John, product manager — `bmad-agent-pm` | Planning | Turn a vision into a PRD, epics and stories, check readiness, and handle a midstream change. |
| Sally, UX designer — `bmad-agent-ux-designer` | Planning | Work out how the product looks and behaves. |
| Winston, architect — `bmad-agent-architect` | Planning | Settle the technical decisions that keep the parts consistent, and check readiness. |
| Amelia, developer — `bmad-agent-dev` | Implementation and validation | Build stories, generate tests, review code, plan the sprint, and run a retrospective. |

An agent and its skills are two ways into the same work: a skill run directly does the job, and an agent adds a guide who knows the whole phase. `bmad-party-mode` brings the agents together in one discussion and offers the `product-team` room.

## After a skill finishes

| Just finished | Offer next |
|---|---|
| `bmad-product-brief`, `bmad-prfaq` | `bmad-spec` with the result as input. `bmad-prd` first when the requirements still need drawing out. After a PRFAQ verdict with serious gaps, address those before anything else. |
| `bmad-prd` | `bmad-spec` to absorb it. `bmad-ux` when the UI matters; `bmad-architecture` when parts must fit together. |
| `bmad-ux` | `bmad-spec` to adopt the files as companions. When UX came first and requirements are still thin, `bmad-prd` or the lighter `bmad-product-brief` with the UX files as input. |
| `bmad-architecture` | `bmad-spec` to adopt the spine as a companion. |
| `bmad-spec` | Its open questions and assumptions, if any. Then `bmad-preview-ticketing` with the spec folder to plan the stories, and `bmad-build` per pulled story, or straight to `bmad-build` when one session can do it. |
| `bmad-create-epics-and-stories` | `bmad-sprint-planning`. |
| `bmad-sprint-planning` | `bmad-build` on the story its status view names. On FAIL, the skill that owns the gap. |
| `bmad-build` | Open a PR, or `bmad-walkthrough` when a person wants to understand the change, then the next story. `bmad-qa-generate-e2e-tests` when end-to-end coverage is wanted. |
| The last story of an epic or spec folder | `bmad-retrospective`, then a refactoring pass over the whole changeset, which is commonly skipped (`help/preparing-a-repo-for-agents.md`). Then close the epic out and archive its story files (`help/artifact-lifetime.md`). |

## Answering "what's next?"

Read the state before recommending: which of the outputs named above exist, and what the codebase, git history, and the user say is done. A file's presence, or a story file with `status: done`, is evidence the skill ran, not proof the work is finished or current.

- Mid-path, recommend the next unfinished step of the route the user is on, not a restart, and do not move them to a different slicing route mid-work.
- When a significant change surfaces, route it as the table in "Match the situation" says, then resume at the earliest affected step. Do not replay unaffected work.
- The work is complete when the intent is satisfied, its chosen checks pass, and no chosen review leaves material findings open — not when every skill has run.

## When this document is not enough

For a `method` question this document, its topic files, and the installed skills cannot answer, fetch the documentation site at `https://docs.bmad-method.org/` and follow the pages relevant to the question. The source repository it links to is the final authority on how anything actually behaves.

# Implementation skills in detail

Read this when the question is about `bmad-build`, `bmad-build-auto`, or `bmad-correct-course`. For running stories without a human, see `help/unattended-builds.md`.

**`bmad-build`** — one session of delivery: clarifies intent, plans, implements, reviews, and presents a commit.
- Takes: free text however brief, a spec folder plus a story id, a story file to resume, a ticket or any other file as intent, or the recent conversation.
- Pick when: any feature, story, bug fix, or meaningful change. It is the default, and risky or foundational stories belong here because a human approves the plan.
- Not when: typo-level or config edits, or edits the user is directing line by line.
- Size: one session is one goal, roughly 500 changed lines, not counting tests, in a handful of files. Start it in a fresh chat.
- Its review: built in and done by agents. By default a small change gets a quick review with one lens and a full change gets a thorough review with four independent lenses. The user can say `none`, `quick`, or `thorough` in the request. It fixes clear findings itself and returns to the human when intent is in doubt. It commits and never pushes.
- Writes: `{implementation_artifacts}/spec-{slug}.md` with a `status` line, or `stories/{story_id}-{slug}.md` inside the spec folder; deferred goals in `{implementation_artifacts}/deferred-work.md`.

**`bmad-build-auto`** — one unattended build of one story, for a loop or script that dispatches it.
- Do not offer it for attended work. It never asks: anything unclear halts it as `blocked` with a named reason written into the story file. It needs subagents. For work planned with `bmad-preview-ticketing`, its input is the pulled ticket file, one run per ticket. For a spec folder that already has `stories.yaml`, its input is the folder plus a story id, and the folder also needs `SPEC.md`. Where version control is present it also needs a clean working tree on a branch that fits the work.
- Fits when: decisions and patterns are stable and the stories are well specified.
- Writes: the same story files as `bmad-build`.

**`bmad-correct-course`** — assesses a significant midstream change on the epics route.
- Gives: a change proposal covering impact across PRD, epics, architecture, and UX; a recommended path (adjust, roll back, or cut scope); and proposed edits. It drafts the edits to the PRD, epics, architecture, and UX and does not apply them: the user applies those through the owning skills. After approval it updates `sprint-status.yaml` itself for added, removed, or renumbered epics and stories.
- Pick when: a story exposes something that reaches across artifacts, such as a technical limit, a new or misread requirement, a pivot, or a failed approach.
- Not when: there is no PRD or no epics (it halts). On the spec route → update the spec with `bmad-spec`. On the ticketing route → re-slice in `bmad-preview-ticketing`.
- Writes: `{planning_artifacts}/sprint-change-proposal-{date}.md`.

# Monorepo and poly repo

Use this when the user asks where to install BMad and keep planning when the work spans one repository or several.

## Monorepo

Install BMad once at the repository root. `_bmad` and the output folder sit at the root, and one session reaches every package. Planning for any part of the repo goes in the same output folder.

## Poly repo

Work from a workspace folder that holds every project checked out side by side.

- Install BMad at the workspace root, not inside each project. There is one `_bmad` for the whole workspace, and the user starts their AI tool from the workspace root so one session reaches the plan and every project.
- The output folder also sits at the workspace root, outside the individual repositories. All planning goes there, because a brief, a PRD, an architecture, or a spec usually spans several of the projects. The folder is `_bmad-output` by default and can be renamed through the `output_folder` setting.
- Make the output folder its own git repository and commit as planning progresses, so the planning has history apart from any one project. This is recommended for a monorepo too. For what to keep in it over time, see `help/artifact-lifetime.md`.
- For each project, recommend a bare repository with worktrees: one bare clone per project, and a worktree per branch beside it. Several branches of one project can then be open at once, and agents working in parallel do not collide in one checkout.
- A spec or story names the projects it touches. `bmad-build` runs from the workspace root and works in the project, or the worktree, the story belongs to.
- `bmad-project-context` rules belong to each project's own `AGENTS.md`, because each repository has its own conventions. Rules that hold across all of them go in an `AGENTS.md` at the workspace root.

## Coming in v7

A setting will name the active initiative, and all planning and implementation artifacts will be grouped under it. `bmad-preview-ticketing` already works this way (`help/ticketing-setup.md`). Until then the output folder is shared by everything in the workspace, so clear names for spec folders matter. A v6 project moves to that layout with `bmad migrate method`, which asks at plan time whether the store should be its own repository, sit in a workspace, and use worktrees, and makes those repository changes before it moves any artifact.

# Planning skills in detail

Read this when the question is about `bmad-spec`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, or the skills that slice and track work: what each gives, when to pick it, when not to, and what it writes.

**`bmad-spec`** — the hub. Condenses any input into the contract builds read.
- Gives: a spec folder with `SPEC.md` (why, capabilities with stable ids, constraints, non-goals, success signal) and companions. It adopts UX files and an architecture spine as companions and absorbs a PRD or brief as a source. On request it hands the spec folder to `bmad-preview-ticketing` to be planned into stories. It also updates and validates an existing spec.
- Pick when: the user has anything to distill, or can explain the idea in detail; after any other analysis or planning skill finishes; when requirements change on the spec route (it appends to its log, re-derives the spec, and names the tickets that no longer match).
- Not when: the input is a bare idea. It distills and does not coach → `bmad-product-brief` first, or `bmad-prd` when full requirements are needed.
- Splitting into stories is not this skill: send the user to `bmad-preview-ticketing` with the spec folder, which plans one epic whose stories cite the spec's `CAP-N` ids. After writing a spec that reads as several slices, `bmad-spec` offers that hand-off once.
- Writes: `{output_folder}/specs/spec-{slug}/` holding `SPEC.md` and companions.

**`bmad-prd`** — coaches detailed requirements out of the user.
- Gives: a PRD sized to the stakes (about 2 pages for a hobby project, longer for a launch): features, requirements with stable ids, user journeys, non-goals, MVP scope, metrics. Fast path or coaching path. Also updates and validates an existing PRD.
- Pick when: the idea is too thin for `bmad-spec`; a consumer or multi-stakeholder product; compliance, integration, or SLA concerns; an existing PRD needs editing or critique.
- Not when: scope is one or two stories → `bmad-build`. A lighter document will do → `bmad-product-brief`, then `bmad-spec`. A brief is an optional input, never a prerequisite.
- Writes: `{planning_artifacts}/prds/prd-{project_name}-{date}/prd.md`.

**`bmad-ux`** — captures how the product looks and how it works. It may lead, follow, or stand alone.
- Gives: `DESIGN.md` (visual tokens and rules) and `EXPERIENCE.md` (structure, states, interactions, accessibility, key flows), optionally mockups and wireframes. It captures the user's vision and never imposes one. A design-handoff mode builds a prompt for an external design tool.
- Pick when: the UI is a significant part of the work; the user wants to design first and derive requirements from the design; the user has design assets to fold in; design will happen in an outside tool but a contract is still needed.
- Not when: there is no meaningful UI.
- UX first: its files are good input to `bmad-prd` when requirements still need drawing out, to `bmad-product-brief` when a lighter write-up will do, or straight to `bmad-spec` when the design already says enough.
- In the spec: both files are adopted as companions. Change them with `bmad-ux` update, not through the spec.
- Writes: `{planning_artifacts}/ux-designs/ux-{project_name}-{date}/`.

**`bmad-architecture`** — fixes only the decisions that keep separately built parts consistent.
- For a user new to architecture: it coaches by default, so the user needs no architecture knowledge to start. When the stack is open it recommends a well-known current starter, checked on the web first, because a good starter settles a coherent set of decisions for free. For each big call (paradigm, stack or starter, major boundaries, and where and how it is deployed and hosted) it lays out the realistic options and why it leans one way, then the user chooses. Its fast path drafts everything with `[ASSUMPTION]` tags to correct.
- Gives: a terse `ARCHITECTURE-SPINE.md` of decisions with stable ids, plus a list of what it deliberately leaves open. Not a full architecture document unless the user asks for one. Works at initiative, feature, or epic altitude, and can start from a spec, a raw idea, an existing codebase, or a sprawling document to distill.
- Pick when: two units built independently could choose incompatibly; an initiative has been cut into epics and more than one epic must adopt the same contract, format, or value list; the stack is open; the user does not know what stack, starter, or hosting to choose; a brownfield codebase has conventions worth ratifying; a feature touches an existing system.
- Not when: the input is too thin → `bmad-spec` first. One session builds all of it → skip.
- Next: it offers to have `bmad-spec` adopt the spine as a companion. Recommend that first.
- Writes: `{planning_artifacts}/architecture/architecture-{project_name}-{date}/ARCHITECTURE-SPINE.md`.

## Slicing and tracking the work

Two ways. Use one per piece of work, never both for the same work. A request to split or break up work goes to the second, also when it starts from a spec.

| | `bmad-create-epics-and-stories` + `bmad-sprint-planning` | `bmad-preview-ticketing` |
|---|---|---|
| Needs | A PRD and an architecture | Any intent; best with a spec |
| Gives | Epics, stories with acceptance criteria, a readiness verdict, a status file | A ticket tree used as a board; optional tracker publishing |
| Status | `bmad-build` updates it | Moved by hand through the skill |
| Effort | High: every story approved one at a time | Sized at intake; a single bug or story is quick |

For how the ticketing route works and why, see `help/ticketing-and-epics.md`. For setting it up and driving it, see `help/ticketing-setup.md`.

**`bmad-create-epics-and-stories`** — breaks a PRD and architecture into user-value epics and stories.
- Gives: `epics.md` with a requirements inventory, a map proving every requirement is covered, and Given/When/Then criteria per story.
- Pick when: a PRD and architecture exist, the work spans several epics, and the user wants traceability and criteria up front.
- Not when: there is only a spec, or the user wants to build now → `bmad-spec`, then `bmad-preview-ticketing` with the spec folder. It needs a PRD to extract requirements from.
- Writes: one file, `{planning_artifacts}/epics.md`. A spec can be added as extra input when it asks, but a PRD and an architecture are still required.

**`bmad-sprint-planning`** — judges whether the plan is buildable, then tracks it.
- Gives: a PASS / CONCERNS / FAIL readiness verdict and `sprint-status.yaml` covering every epic, story, and retrospective. Its status action answers "where are we" and names the next story. It can also validate or repair the file.
- Pick when: `epics.md` exists and building is about to start; any time the user asks where things stand; after epics change (refresh never downgrades a status).
- Not when: the work is on the spec route or the ticketing route. It reads only `epics.md` headings, never `stories.yaml` or tickets.
- Writes: `{implementation_artifacts}/sprint-status.yaml`.

**`bmad-preview-ticketing`** — preview of the ticket tree that will replace the two skills above.
- Gives: an initiative sliced into epics, each planned into stories and bugs as entries in `tickets.toml`, in build order, each with an `id`, its prerequisites (`after`), and a verify line; a spike is added when the user asks for one. An entry becomes a ticket file when pulled. Run as a board, optionally published to a tracker.
- Pick when: tickets or a tracker are the record; one-off bugs and stories with no PRD; work across repos; the user accepts a prerelease skill.
- Tell the user: a ticket file's `status` belongs to the build, and `bmad-build` does not write it yet, so they tell this skill to start and close a ticket by hand. They hand the pulled ticket file to `bmad-build` with its epic. A story needs no refining first; a bug, a ticket with no epic, or an entry the user marked `refine = true` gets full criteria first. Before an unattended run, recommend a review of the stories. Trackers other than the repo store are lightly tested.
- Writes: ticket files under `{output_folder}/{active_initiative}/` and `{output_folder}/backlog/`, named `epic-<slug>/`, `story-<slug>.md`, `spike-<slug>.md`, `bug-<slug>.md`, and a `tickets.toml` beside each initiative and epic file.

# Preparing and keeping a repository fit for agents

Use this when the user asks how to get an existing codebase ready for agentic coding, why agents produce inconsistent work in their repo, how much documentation to keep, or how to hold quality over time. For the order of skills on an existing codebase, see `help/existing-codebase.md`.

## What makes a repository work well with agents

- **Consistency.** An agent copies the patterns it finds. When the project does the same thing several different ways, the agent cannot be consistent either, and each session may pick a different way.
- **A good initial `AGENTS.md`.** A short, verified set of rules is worth having from the start: the policies, commands, and conventions the code cannot show. `bmad-project-context` sets it up and keeps it small.
- **Good end-to-end tests.** They let an agent change code and know it still works, and they make refactoring safe. `bmad-qa-generate-e2e-tests` adds them for features that already exist.
- **Clean structure.** Very large files and tangled modules cost every session tokens and accuracy.

## Improve before building, when quality is low

If the codebase is inconsistent or untested, some refactoring and test work first goes a long way, and it pays back in every later session. Agents can help assess the code and carry out the improvements: ask for an assessment of inconsistent patterns, then make each cleanup its own `bmad-build` change with tests in place first. A skill dedicated to this is planned. A codebase of decent quality needs none of this: start with a small change.

## Documentation: keep it small

Earlier BMad guidance produced heavy documentation of a codebase. That is no longer suggested. Those documents were bloated, hard to maintain, and went stale quickly. A new documentation skill for codebases is planned.

- The code is the best documentation for an agent. During coding, an agent should need few documents.
- Documents should hold only what the code cannot explain: why a decision was made, a constraint from outside the code, a rule that spans components.
- Recommend small numbered decision records (ADRs), written consistently, only for what is needed, in the repository's `docs` folder or similar.
- `AGENTS.md` should make agents aware the records exist and when to consult them, without copying their content.

## Refactor regularly

After several stories, at the end of an epic, and every so often otherwise, do a refactoring pass toward cleaner code. This step is commonly skipped, and agent-built code drifts without it: duplication, near-copies of helpers, and patterns that diverged between sessions.

- The end of an epic is a good moment because the whole changeset can be looked at together. `bmad-retrospective` reports duplication and drift across the epic's stories, and its findings are a ready list of refactoring work.
- Run each refactoring as its own `bmad-build` change, separate from feature work.
- Refactoring is safest with a good test suite in place. Without one, add tests first.

# Project context and what belongs in AGENTS.md

Use this when a user asks which `bmad-project-context` intent to run, why its block is small and has no repo overview, or what to do when agents repeat a mistake.

## What it produces

A small, verified block of rules in `AGENTS.md` at the repo root, between the `<!-- bmad:context -->` and `<!-- /bmad:context -->` markers. The run is a conversation, and the user approves every write.

## Intents

| Intent | Recommend when |
|---|---|
| setup | No instruction file has meaningful content. |
| adopt | The user already wrote an `AGENTS.md` or `CLAUDE.md`. The user sees what happens to each instruction. |
| refresh | A block exists and the code changed a lot. It does not re-ask what was settled. |
| record | An agent just got something wrong. A recurring or costly mistake earns a line. |
| audit | The block feels stale or bloated. It ends smaller or equal. |

## What earns a line

- Policy the code cannot express: branch rules, frozen paths, generated files, security.
- What a config file cannot say about running the project: integration tests need a service up first.
- Conventions that differ from ecosystem defaults, including a command whose obvious form is wrong.
- Pitfalls someone has observed. A scan finding alone becomes a question to the user.
- Rules that must hold across components, required tool versions, and entry points.

## What stays out

Repo overviews, directory trees, stack lists, commands the obvious guess gets right, pasted code, history, and plans. For a style rule a linter, hook, or CI check can enforce, the skill proposes the check. Product intent belongs in a spec, and a contested design decision in `bmad-architecture`. To learn the code, recommend `bmad-walkthrough` (`help/existing-codebase.md`).

## Why the block is small

- Every line loads in every session, and agents follow instructions less well as the loaded set grows.
- Agents read code better than prose about code, and a stored copy goes stale.
- Instruction files that restate what the repo already shows cost tokens every session and do not make agents more successful.
- Agents often skip context they must choose to fetch, so rules that must hold stay in the block.

## Where it writes

- Only between the markers. Text outside them changes only with the user's approval.
- For a tool that reads another file, it proposes a one-line `@AGENTS.md` import.
- It never commits. The user reviews and commits the change.
- Personal preferences and rules shared by all of a user's projects belong in their global agent config.

## How a rule gets removed

A policy or pitfall goes only when the thing it guards is gone or the user retires it. No recent failures is not a reason. An instruction a human wrote is deleted only when it is stale or wrong, enforced by a hook or check, contradictory, or approved for deletion as its own item.

## An old project-context.md

The older `bmad-generate-project-context` and `bmad-document-project` skills were removed; this skill replaces both. It reads an existing `project-context.md`, offers to absorb its content, and does not delete the file without the user's agreement.

# Prototyping with the method

Prototypes are underused, in hobby work and in the enterprise alike. Recommend one readily. The method has no prototype phase and needs none: a prototype is a fast, cheap way to learn, and what it teaches is some of the best input `bmad-spec` can get. Current models can produce an impressive first version from one prompt.

## What a prototype is good for

- **Is it worth doing?** Putting something real in front of users or stakeholders gets feedback within days, without the overhead of planning first.
- **Is it feasible?** It proves out a risky technique, integration, or performance question before anyone commits to it.
- **How complex is it really?** Building a slice shows where the effort is.
- **What don't we know?** Unknowns surface when something runs. They rarely surface in a document.
- **Was the idea any good?** Finding out that a good-sounding idea is a bad one is a successful prototype. It saved the cost of building it.

## Who can prototype

Anyone, not only engineers. A product manager, designer, product owner, or analyst can mock up or prove out an idea with an agent and bring the result to the team. When a non-engineer asks whether they can, the answer is yes, and a throwaway prototype needs no setup or planning skill first.

## Greenfield and existing codebases

Both work. In an existing codebase, a prototype on a branch shows how a change sits against the real system and what it touches. Treat it as a throwaway unless the team decides otherwise: prototype code written to learn fast seldom meets the codebase's standards.

## Ways to prototype

| The user wants | Recommend | Because |
|---|---|---|
| Something running fast, expected to be thrown away | Prompt it directly, no skill | For a throwaway, the smallest path is no path. |
| A fast first version with a plan to approve, a review, and a commit | `bmad-build` with a one-line prompt | It accepts free text however brief. In an existing codebase it investigates the code first, so the prototype fits what is there. |
| To see the screens and flows before any code | `bmad-ux` | It can produce HTML mocks of key screens and Excalidraw wireframes alongside its two design files. |
| A technical unknown answered from outside sources instead of by building | `bmad-deep-recon` (core tools), if installed | Some feasibility questions are research, not code. |

## After the prototype: throw it away or keep it

Ask the user to decide this on purpose. The outcome to avoid is a prototype that becomes the real product with nobody deciding it should, and with no spec.

- **Throw it away.** The prototype was research. Have the user note what it taught them: what worked, what surprised them, what users said, what they would do differently. Feed those notes, and the prototype itself if useful, to `bmad-spec`, or to `bmad-product-brief` first when the picture is still loose. Then build cleanly, one story at a time. This is the usual choice in an enterprise codebase and whenever a non-engineer built the prototype.
- **Keep it.** Treat it as an existing codebase (see `help/existing-codebase.md`): `bmad-project-context` to record the rules agents must follow, `bmad-architecture` to ratify the decisions worth keeping and name what is still open, then `bmad-spec` for the rest of the work.
- **Drop the idea.** The prototype showed it is not worth doing. Nothing more is needed.

## Why plan at all after a good prototype

A first version is rarely where a project goes wrong. Trouble starts several sessions later, when each new session does not know why earlier choices were made and the parts stop fitting together. The spec and the architecture decisions exist to prevent that. For work that one or two sessions will finish, the prototype may be all the user needs.

## A prototype and the analysis skills

A prototype answers questions by building. `bmad-prfaq` answers them by arguing the concept and researching the market claims. They complement each other: a prototype shows whether people want the thing and whether it can be built, and the PRFAQ tests whether the business case holds. When the stakes are high, the prototype's findings make the PRFAQ, the brief, or the PRD sharper.

# Review choices

Use this when the user asks how much review to run, how to get another pass, when to stop, why review is slow, or how to change review.

## Review depth in `bmad-build`

- `none`: no reviewers. Reasonable for a throwaway prototype.
- `quick`: one reviewer checks acceptance criteria, the repo's agent rules, and bugs.
- `thorough`: four independent lenses covering the bare diff, edge cases, test gaps, and intent alignment.
- Default: a change of about 100 lines or fewer gets `quick`, a larger one `thorough`. The user picks by saying "quick", "thorough", or "skip review" when invoking.
- It fixes clear findings itself, asks the user when the intent cannot settle one, and logs pre-existing issues to `deferred-work.md`.

## Another pass, and when to stop

- After `bmad-build`: run `bmad-code-review` with the story file. Handing `bmad-build` a `done` story file does not repeat the review.
- After `bmad-build-auto`: dispatch the `done` record again.
- Worth it when review was skipped or `quick`, after material fixes, or when an unattended run set `followup_review_recommended`. After a `thorough` build review it only repeats the same lenses.
- Stop when findings are mostly minor notes about unlikely corner cases.
- Real findings on a third pass point outside the change: a weak spec or unclear repo rules. Tell the user to fix that.

## `bmad-code-review`

- Target: a PR, commit, branch, commit range, uncommitted changes, a pasted diff, or files.
- Tell the user to supply the intent: a spec, story file, or plain description. Without it the reviewers can only judge the diff against itself.
- Defaults to `thorough`; "quick" uses one reviewer. Above about 3000 diff lines it offers to review in file groups.
- Triage checks every finding against the code and rejects disproved ones, plus low ones whose fix would add complexity.
- Survivors become patch (a clear fix), defer (pre-existing or unverified), or decision needed (only when a spec was given).
- The user chooses: apply all patches, walk through each, or leave them as action items in the story file.

## Why review is slow

- It is thorough on purpose and can take half an hour or more. Offer `quick`.
- `AGENTS.md` has too many rules, or source files are very large. Reviewers read both.
- The platform has no subagents or runs them one at a time.

## `bmad-walkthrough`: the human reviews

Recommend it when a person must understand and accept a change: after a build, or on someone else's PR. It walks the change in blocks, intent first, and stays on a block until the user says it is done. It gives no severity and no verdict. Moves the user can pick:

- **Thoughts**: the agent's own read. **Second opinion**: a fresh subagent's read.
- **Formal review**: runs `bmad-code-review` when installed.
- **Test**: helps test the part. **Drive**: starts the app and says what to click.
- **Wrap-up**: proposes the follow-through, such as merging, and waits for a yes.

For specs and docs, `bmad-review` (core tools), if installed, reports findings and fixes nothing.

## What `bmad-customize` can change

- The default depth, separately for `bmad-build`, `bmad-build-auto`, and `bmad-code-review`.
- The lenses: add, replace, disable, or run one on another model.
- `bmad-walkthrough`: instructions at start, per block, and at wrap-up.

# Ticketing compared with epics and sprint planning

`bmad-preview-ticketing` is a preview of the route that will replace `bmad-create-epics-and-stories` plus `bmad-sprint-planning`. Use this when a user asks how the two differ, which to pick, or why the ticketing route is designed the way it is.

## How the ticketing route works

- **Initiative.** One body of work, such as a product, a major feature, or a migration. Its planning documents and tickets live together in one folder.
- **Slicing.** The skill proposes how to split the initiative into epics from the user's source material. The user decides the split. The agreed epics, in build order, are recorded in `tickets.toml` beside the initiative file. Each epic gets its own folder holding the epic's ticket file, its own `tickets.toml`, its spec if it has one, and its stories. Epics not yet selected stay as short envelopes: outcome, done-when checks, boundary.
- **Epic boundaries.** An epic is one capability delivered to production by one owner. A module, service, or bounded context is an epic boundary when it is also the ownership or deployment boundary. A unit the work only consumes or configures gets no epic: it is a touch point, named in the initiative's Boundaries with the epic that owns the work there. A team's own rule for cutting epics can be saved to `_bmad/custom/bmad-preview-ticketing.toml`.
- **Decisions several epics share.** A contract, a data format, or a shared value list that more than one epic must adopt goes to `bmad-architecture` (the spine), or becomes a story in the opening epic that the others list in `after`. It is never a spike inside one epic. One repo or one unit needs no architecture pass; the second unit that must adopt a decision does.
- **Epic inception.** Planning one selected epic as a whole: every anticipated story and bug in build order, with what each delivers, its prerequisites, how it will be verified, and what is still uncertain. Each is an entry in the epic's `tickets.toml`, with an `id` that names it under its epic for good; the table order is the build order. An entry has no file, no status, and no acceptance criteria. An unknown that must be settled before implementation is put to the user: answer it, record it as the entry's `unknown`, or add a spike when the user asks for one. By default the breakdown ends with a "Refactor sweep" story.
- **Pull, then build.** Pulling an entry writes its ticket file (`<type>-<slug>.md`, carrying the entry's `id` in frontmatter); a script does it, with no conversation. The file ends with an empty `## Plan` section for the coding agent; from then on the file is truth and the entry keeps only the id, type, title, and prerequisites. The pulled file goes to `bmad-build` with its epic, and the builder plans the story's acceptance criteria from the epic's Requirements and Done when, the entry's description, and its `Verify:` check. After completed work changes the picture, the remaining breakdown is revisited.
- **Refining is optional.** With `bmad-build`, a story is refined during the build: the builder questions the user and writes the criteria itself. Refining in ticketing pulls the story's file if it has none, then reviews the file with the user — description, check, references, notes, order, prerequisites — and writes no Given/When/Then. Recommend that review when the epic will run unattended (`bmad-build-auto`, a loop, a factory), because nobody answers questions during the build. Full acceptance criteria are written in ticketing only for a ticket with no epic, a bug, or when the user asks.
- **Source conflicts.** When the source contradicts the code, the skill records a `Source conflict:` line in the container's Notes and tells the user. When the source is a BMad spec, it offers to pass the correction to `bmad-spec`.
- **The board.** "What's next?" shows what is ready to pull, ready to refine (only the tickets that need it), ready to start, in progress, or blocked (waiting on a person or an answer). Asked about the initiative, it covers every epic. A prerequisite in `after` can be a story in the same epic, a story in another epic, or a whole epic.
- **Status.** A ticket file's `status` belongs to the build, not to ticketing. On a tracker store the tracker's status sits beside it as `tracker_status`, so a card moved on the board never makes the build skip planning. Ticketing writes `status` only when the user asks: a dropped ticket, or one a person is working by hand.
- **Other abilities.** A one-off bug or story goes straight into `backlog/` with no epic. Tickets can be published to a tracker such as Jira, Linear, or GitHub; the markdown file stays the working copy.

## Why it is designed this way

- **Detail is written when it is needed.** The epics route writes Given/When/Then criteria for every story up front, and the user approves each story one at a time. Criteria written weeks early go stale as building teaches the team things. Ticketing plans the whole epic at low cost. The builder writes each story's criteria at build time from the epic and the entry, using what earlier stories taught. Ticketing writes full criteria only for bugs, tickets with no epic, and on request.
- **A lower bar to start.** The epics route needs a PRD and an architecture. Ticketing takes any intent, works best with a spec, and handles a single bug.
- **One skill, one place.** Slicing, stories, status, and the board are together. The epics route splits them between `epics.md` and `sprint-status.yaml`.
- **One file per story.** A story file is easy to hand to `bmad-build`, to publish to a tracker, and to use across repositories.
- **It matches how teams track work.** When a tracker is the record, the epics route has nothing to offer.

## What the epics route still does better today

While ticketing is in preview, `bmad-create-epics-and-stories` with `bmad-sprint-planning` remains the supported route and works as before.

- **Automatic status.** `bmad-build` keeps `sprint-status.yaml` current. It does not write a ticket file's `status` yet: the user tells the ticketing skill to mark a ticket started or done.
- **The retrospective and unattended loops.** `bmad-retrospective` and bmad-loop read `sprint-status.yaml` or an existing `stories.yaml`. Neither reads `tickets.toml` yet.
- **A readiness verdict.** `bmad-sprint-planning` gives PASS / CONCERNS / FAIL before building starts.
- **Requirement coverage up front.** `epics.md` carries a map proving every PRD requirement is covered by a story.
- **Maturity.** Ticketing is a prerelease. Trackers other than the repo store are lightly tested, and nothing syncs on its own.

## Which to recommend

- Has a spec and wants stories from it → `bmad-preview-ticketing` with the spec folder, which plans it as one epic.
- Wants a board, uses a tracker, has bugs and one-off stories, or wants to help test the v7 direction → `bmad-preview-ticketing`.
- Has a PRD and an architecture, and wants criteria written up front for every story and status that updates itself → the epics route.
- The routes do not mix. Use one per piece of work.

# Setting up and using the ticketing preview

Use this when a user asks how to set up or drive `bmad-preview-ticketing`. For the design and the comparison with the epics route, see `help/ticketing-and-epics.md`.

## Where the store lives

- Tickets are markdown files under `root` in `_bmad/custom/ticketing-store-config.toml`. `root` defaults to `{output_folder}`, which is `_bmad-output` unless changed.
- To move the store, set `output_folder` under `[core]` in `_bmad/custom/config.toml` (committed, applies to the team), or edit `root` in the store config.
- `active_initiative` under `[modules.bmm]` in `_bmad/custom/config.user.toml` (personal, not committed) names the initiative folder in use. Unset, the skill offers to create and record it. Change it to switch initiatives.

## 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. The best input is a `bmad-spec` output with its source documents. `bmad-spec` offers to hand its spec folder to this skill, which does the story breakdown; the stories cite the spec's `CAP-N` ids.

## Trackers

- First use asks where tickets are tracked and copies a starter to the store config. "Reconfigure the ticket store" changes it later.
- Choices: repo (the default; files under version control, no account), GitHub Issues, Jira, Linear, Notion, or Trello. The skill 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 runs the skill. The skill never pushes.

## What the user says

| Say | Result |
|---|---|
| "Split this initiative into epics" | Proposes epic boundaries and records the agreed order in the initiative's `tickets.toml`. |
| "Incept the first epic" | Plans the whole epic into entries in the epic's `tickets.toml`, in build order, each with an `id` that names it under the epic. No story file is written yet. |
| "Pull the next story" | Writes the story file from its entry, ending with an empty `## Plan` for the coding agent. A script does it, with no conversation. |
| "Refine story 2", "review the stories" | Pulls the story's file if it has none, then reviews and improves it with the user. Full acceptance criteria are written only for a bug, a ticket with no epic, or when the user asks. |
| "File a bug: ..." | One ticket straight into `backlog/`, with no epic. |
| "What's ready?", "what's next?" | Lists what is ready to pull, ready to refine, ready to start, in progress, and blocked, for one epic or the whole initiative. |
| "Start story 2", "mark story 2 done" | Writes the ticket file's `status` by hand, for a ticket a person works or until `bmad-build` writes it. |
| "Publish the tickets" | Sends tickets to the tracker. By default, with a tracker the whole breakdown publishes at inception; on the repo store each ticket publishes when pulled. |

## Hand-off to bmad-build

- A planned story has no file until it is pulled.
- Give the pulled file to `bmad-build` with its epic: "build story-cart-ui-shell.md". The builder 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, review the stories with this skill. 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.
- A ticket file's `status` belongs to the build, and `bmad-build` does not write it yet. Until it does, the user says "start story 2" before and "mark story 2 done" after.
- `bmad-sprint-planning` does not read these stories.

## Feedback

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

# Unattended builds

Use this when the user asks about `bmad-build-auto`, building stories with no human present, a blocked run, or what to check after a run.

## What one run does

- One invocation plans, implements, and reviews one story, then writes a final status to the story record. It never asks a question.
- It does not pick the next story. Something else runs the loop: the user, a script, an AI coding session starting one worker per story, or the optional bmad-loop orchestrator, which runs `stories.yaml` in list order, so prerequisites must come first.
- It needs subagents and, under version control, a clean working tree on a fitting branch.

## Accepted inputs

- Free text, a ticket or story id, or a path to an intent file.
- A story record an earlier run wrote.
- A pulled ticket file, for work planned with `bmad-preview-ticketing`: one run per ticket, with the file as the intent. Dispatch straight from `tickets.toml` is not available yet.
- A spec folder that already has `stories.yaml`, plus a story id. The folder also needs `SPEC.md`. The record lands at `stories/<id>-<slug>.md`.
- "Halt after planning" stops the run at `ready-for-dev`. The next dispatch implements it.

## Resume follows the record's status

- `draft`: plans.
- `ready-for-dev`, `in-progress`: implements.
- `in-review`: reviews.
- `done`: runs a fresh follow-up review.
- `blocked`: halts at once.

## Blocked runs

`blocked` means continuing without a human was unsafe. The reason is in the record under `Auto Run Result`, or in a `bmad-build-auto-result-*.md` file under `{implementation_artifacts}` when no record exists yet. Common reasons:

- `unclear intent`, `intent gap`: the input cannot answer a question the run hit.
- `no subagents`.
- `implementation verification failed`.
- `review repair loop exceeded 5 iterations`: review kept sending the work back.
- `no stories.yaml found`, `story id not found in stories.yaml`, `no epic spec found`: the spec folder is incomplete.
- `story already blocked`, `blocked spec supplied`: the record is still marked blocked.
- A dirty working tree or a mismatched branch.

To retry, fix the cause, delete the blocked story record, and dispatch again. A blocked record halts every later dispatch, even after the cause is fixed.

## The saved patch on an intent-gap halt

When review halts on `intent gap`, the run saves the attempted change as a patch file in `{implementation_artifacts}`, names the path in the record, and reverts the code. If the patch reads the intent correctly, the user runs `git apply` on it, sets the record's status to `in-review`, and dispatches again. If it was wrong, they fix the intent and start fresh.

## What to read afterwards

- `status` in the record's frontmatter. Chat output is not proof of success.
- `followup_review_recommended`: true when review fixed a high finding or two or more medium ones. It is a suggestion; dispatching the `done` record again gives another pass.
- `deferred` in the frontmatter: real findings that were not this story's problem. Nothing files them; the user decides whether to make tickets.
- `Auto Run Result`: summary, review findings, verification, residual risks.
- The run commits locally and never pushes.
- After the last story, recommend `bmad-retrospective`.

## When it fits

- Fits: decisions and patterns are settled, stories are well specified, and someone reads the results.
- Use `bmad-build` instead for risky or foundational stories, thin intent, or whenever a human should approve the plan. Do not offer `bmad-build-auto` to a user who is present.

# Validation skills in detail

Read this when the question is about `bmad-code-review`, `bmad-walkthrough`, `bmad-qa-generate-e2e-tests`, or `bmad-retrospective`. For choosing review depth, getting another pass, and slow reviews, see `help/review-choices.md`.

| | Reviewer | Looks at | Fixes |
|---|---|---|---|
| Review inside `bmad-build` | Agents | The change just built | Clear findings, itself |
| `bmad-code-review` | Agents | Any diff, PR, branch, or commit | What the human chooses |
| `bmad-walkthrough` | The human, guided | A commit, PR, file, or directory | Nothing unless asked |
| `bmad-retrospective` | Agents, across stories | A whole epic or spec folder | Nothing; proposes action items |

**`bmad-code-review`** — agent review of any diff, with verified and triaged findings.
- Pick when: the code did not come from `bmad-build`; a PR or branch needs review; a build ran with review skipped or on the quick setting; after material fixes. `bmad-build` does not re-review a finished change: handed a `done` record it treats it as context for new work. After an unattended run that sets `followup_review_recommended`, re-dispatch `bmad-build-auto` on the same `done` story instead; it goes straight to a fresh review pass.
- Not when: `bmad-build` just ran its full review on the same change. It is the same four lenses again. A run can take half an hour or more, and more than two rounds on one change usually points to a problem outside the change, such as weak planning or a messy codebase.
- Writes: a `Review Findings` section in the story file when there is one; otherwise findings stay in the chat.

**`bmad-walkthrough`** — the human reviews a change block by block, at their own pace, with the agent as guide.
- Pick when: a person needs to understand and accept a change, after a build or for someone else's PR. It orders attention: intent first, then the broad strokes, then details.
- Not when: the user wants an automated bug hunt → `bmad-code-review`.
- Writes: a review narrative and a review log under `{implementation_artifacts}`.

**`bmad-qa-generate-e2e-tests`** — generates API and end-to-end tests for features that already exist.
- Pick when: the project has a UI or API with little end-to-end coverage. It covers the happy path plus one or two error cases and runs the tests until they pass.
- Not when: the user wants unit tests for work in flight (`bmad-build` writes and runs tests for the edge cases its plan lists; ask for more in the build request), a review, or a test strategy (the Test Architect module covers that).
- Writes: tests under `{project-root}/tests`, summary at `{implementation_artifacts}/tests/test-summary.md`.

**`bmad-retrospective`** — judges a finished epic, or a finished spec folder's stories, as a whole against its spec.
- Gives: sourced findings no single session could see (architecture drift, duplication, spec versus built), owned action items, and a verdict: accepted, accepted with open items, or rejected.
- Pick when: every story of the epic or spec folder is done, and especially after unattended runs. An unfinished story forces a rejected verdict.
- Not when: one story or one diff is in question → `bmad-code-review` or `bmad-walkthrough`.
- Writes: `{implementation_artifacts}/epic-{n}-retro-{date}.md` on the epics route, `RETROSPECTIVE.md` inside the spec folder on the spec route.

# Working in an organization

Use this when the work belongs to a team or enterprise: a PRD already exists, a tracker such as Jira is the record, people must approve, several engineers build in parallel, or requirements change mid-flight.

## When the full path is warranted

A single builder, or a small team that already agrees, goes straight to `bmad-spec` and needs no PRD. Recommend the full path (PRD, architecture, one spec per epic, tracking) only when one of these is true:

- People who did not do the thinking must approve what the product is.
- Several epics, teams, or agents build against the same decisions and must not diverge.
- A regulator, steering committee, or company process requires named documents.

Before any of this, a product manager, designer, or analyst can prototype the idea (`help/prototyping.md`).

## An existing PRD is input

- Point `bmad-prd` at the existing PRD. Validate gives a findings report and changes nothing. Create rewrites the same requirements in the shape later skills read, with `[ASSUMPTION]` tags on what it filled in.
- When the source PRD changes, run `bmad-prd` update. Tell the user never to hand-edit `prd.md`.
- `bmad-ux` and `bmad-architecture` start from the existing design system, architecture document, or codebase.

## One owner per document

Each document has one skill that writes it, so give it one owner. One person can hold several roles.

| Role | Runs | Owns |
|---|---|---|
| Product manager | `bmad-prd` | `prd.md` and its updates |
| Designer | `bmad-ux` | `DESIGN.md`, `EXPERIENCE.md` |
| Tech lead | `bmad-architecture` | The architecture spine |
| One engineer per epic | `bmad-spec`, `bmad-build`, `bmad-retrospective` | That epic's spec, stories, verdict |
| Whoever tracks the whole | `bmad-sprint-planning` | `sprint-status.yaml` |

Several engineers can each take an epic at once. An epic-level spine inherits the parent spine's decisions as binding.

## Where sign-off happens

Each moment produces a written result an approval can attach to. Advise placing existing approvals here.

| Moment | What it holds back |
|---|---|
| `bmad-prfaq` verdict | Writing the PRD |
| `bmad-prd` validate | Design and architecture work |
| Architecture spine review | Writing epic specs |
| `bmad-sprint-planning` readiness gate | Generating tracking; a FAIL stops it |
| `bmad-retrospective` verdict | Starting the next epic |

`bmad-prfaq` and `bmad-retrospective` accept `-H` to run without a conversation.

## When requirements change

Reviewers ask for changes in whichever document they are reading. Apply the change to the document that owns it, then re-run the later skills.

1. `bmad-prd` update. It surfaces conflicts with earlier decisions before applying anything.
2. `bmad-architecture` update when a decision shared across epics changes.
3. `bmad-spec` for each affected epic. Capability ids stay stable, and it says which stories no longer match.
4. Story breakdown or `bmad-sprint-planning` again. A refresh never downgrades a status.

For a change that threatens the plan itself, run `bmad-correct-course` first. It needs a PRD and epics.

## Tracker integration

- Nothing syncs with Jira or any tracker automatically, in either direction.
- The epics route reads and writes only `sprint-status.yaml`. The user updates it when the tracker changes.
- `bmad-preview-ticketing` can publish tickets to Jira, Linear, or GitHub. It is a preview. When the skill runs, the tracker's status is read into the ticket file as `tracker_status`, beside the build's own `status`, and never drives the build (`help/ticketing-and-epics.md`).

# The `method` module's roster: the people it offers and the groups they form.
# It sits beside `bmod.toml` and is found by its name, so it is installed once,
# with the module record. `_bmad/scripts/roster.py` reads it for bmad-party-mode
# and any other skill that casts personas. The fields are the ones party mode
# uses for its own members and groups.
#
# A member with `skill` is an installed agent: it joins the default room only when
# that skill is installed, and its name, title and icon follow the skill's
# customization. A member without `skill` is a guest who exists only in groups.

[[members]]
code = "bmad-agent-analyst"
skill = "bmad-agent-analyst"
name = "Mary"
icon = "📊"
title = "Business Analyst"
persona = "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."

[[members]]
code = "bmad-agent-pm"
skill = "bmad-agent-pm"
name = "John"
icon = "📋"
title = "Product Manager"
persona = "Drives Jobs-to-be-Done over template filling, user value first, technical feasibility is a constraint not the driver. Speaks like a detective interrogating a cold case: short questions, sharper follow-ups, every 'why?' tightening the net."

[[members]]
code = "bmad-agent-ux-designer"
skill = "bmad-agent-ux-designer"
name = "Sally"
icon = "🎨"
title = "UX Designer"
persona = "Balances empathy with edge-case rigor, starts simple and evolves through feedback, every decision serves a genuine user need. Speaks like a filmmaker pitching the scene before the code exists, painting user stories that make you feel the problem."

[[members]]
code = "bmad-agent-architect"
skill = "bmad-agent-architect"
name = "Winston"
icon = "🏗️"
title = "System Architect"
persona = "Favors boring technology for stability, developer productivity as architecture, ties every decision to business value. Speaks like a seasoned engineer at the whiteboard: measured, always laying out trade-offs rather than verdicts."

[[members]]
code = "bmad-agent-dev"
skill = "bmad-agent-dev"
name = "Amelia"
icon = "💻"
title = "Senior Software Engineer"
persona = "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."

[[groups]]
id = "product-team"
name = "The Product Team"
scene = "A product team in a planning room with the whiteboard half full. Mary wants evidence, John wants the user's job stated in one sentence, Sally wants to see the screen, Winston wants to know what breaks at scale, and Amelia wants acceptance criteria she can test. They like each other and they do not let a weak argument pass."
members = [
  "bmad-agent-analyst",
  "bmad-agent-pm",
  "bmad-agent-ux-designer",
  "bmad-agent-architect",
  "bmad-agent-dev",
]
memory = true

---
name: bmod-method
description: Required bmod metadata. Never invoke this skill.
---
This folder is the BMad Method module's record, not something to run. Invoke the `bmad` skill with `setup method`; it sets the module up if it never was, and otherwise reports its state. If there is no `bmad` skill, say so and offer `npx skills add bmad-code-org/BMAD-METHOD --skill bmad`.

# The method module's v6 to v7 migration. It sits beside `bmod.toml` and is found by its `[migration]` table.
# The `bmad` skill (`bmad migrate`) finds every migration file an installed module ships, offers this
# one when its `detect` signals are present, and follows `guide` to perform it. The file carries the
# rules; the agent reading it plans the conversion for the project in front of it, gets the plan
# approved, and then moves and converts the user's artifacts. It never edits `_bmad/` beyond the
# `_bmad/custom/` overrides named under Configuration and the move of `_bmad/` whole to a workspace
# root under `workspace`: the rest is `bmad setup`. It removes files only in the per-epic archive of
# step 7, under version control and at the user's choice. It never pushes.

[migration]
module = "method"
from = "6"
to = "7"
title = "Move v6 planning and implementation artifacts into the v7 initiative layout"
summary = "v6 kept planning documents in one folder and build records in another, with the plan in epics.md and progress in sprint-status.yaml. v7 keeps everything for one body of work in one initiative folder, as a ticket tree the ticketing skill and the builder read, with an inbox for work that has no home yet. This migration moves the project's artifacts into that layout, turns epics and sprint status into tickets.toml and ticket files, sets the config that names the active initiative, and, when the user wants it, puts the store in its own repository or a workspace."

# Read-only signals. Any one of them makes this migration worth offering; the first two are v6 for certain.
detect = """
- `epics.md` under the folder `modules.bmm.planning_artifacts` names, or `sprint-status.yaml` under `modules.bmm.implementation_artifacts`.
- Story files in the implementation folder named `<epic>-<story>-<slug>.md` or `spec-<epic>-<story>-<slug>.md` whose frontmatter has `route:` and `status:` (the v6 build spec shape).
- Dated artifact folders under the planning folder: `prds/prd-<name>-<date>/prd.md`, `briefs/brief-<name>-<date>/brief.md`, `ux-designs/ux-<name>-<date>/DESIGN.md`, `architecture/architecture-<name>-<date>/ARCHITECTURE-SPINE.md`.
- `specs/spec-<slug>/SPEC.md` under `core.output_folder`, with or without `stories.yaml` and a `stories/` folder.
It applies only while there is no `active_initiative` under `[modules.bmm]` in `_bmad/custom/config.user.toml` and no `initiative-*/` folder holding a same-named file under the output folder. A project that already has those, with `tickets.toml` and a ticketing store config, is on v7; say so and stop unless the user names v6 leftovers to bring in.
"""

# The layout every rule below moves toward. `<root>` is `tickets.root` from the ticketing store config,
# `{output_folder}` by default. Nothing below names a fixed folder; read the config.
target = """
<root>/
  initiative-<slug>/
    initiative-<slug>.md            # the envelope: type initiative, title, status, created, Outcome, Done when, Notes
    intent.md                       # the intent the work grew from, when there was one; the preferred first read
    tickets.toml                    # one [[epic]] per epic, in build order
    prd-<slug>/prd-<slug>.md        # every planning document, one folder each, main file named after the folder
    brief-<slug>/brief-<slug>.md
    ux-<slug>/ux-<slug>.md          # a router: what DESIGN.md and EXPERIENCE.md beside it are
    architecture-<slug>/architecture-<slug>.md
    spec-<slug>/spec-<slug>.md      # plus its companions, unchanged
    epic-<slug>/
      epic-<slug>.md                # the epic envelope
      tickets.toml                  # one [[entry]] per story, in build order
      story-<slug>.md               # only for a story that had a file in v6, or that the user asked to keep with its criteria
      story-<slug>-plan.md          # the v6 story file, which was the build record
      retro-<slug>/retro-<slug>.md  # the epic's retrospective, when one was written
    archive-v6/                     # epics.md, sprint-status.yaml, and epic-N-context.md caches, unchanged
    migration-v6-v7/migration-v6-v7.md  # the plan, its answers, and the verification record
  backlog/                          # loose tickets with no epic, flat: story-, spike-, bug-<slug>.md
  inbox/                            # work with no home yet: the default space when no initiative is active
    space.md                        # its identity; nothing else is required
    intent-<slug>.md                # a loose intent, until it becomes a ticket, an epic, or an initiative
    brainstorming-<slug>/           # a new artifact folder, in the usual shape
    brainstorming/                  # an unrelated v6 folder moved here as it was; the user tidies it if they care
    archive-v6/                     # dead scraps with nothing beside them: a half-run, a stray memlog
Every entry at the root says what it is: an `initiative-` or `epic-` folder, `backlog/` (or `backlog-<slug>/` when there are several), or a space with its identity file. Anything else at the root is unrecognized: the plan offers it inbox, and declined it is left alone, never broken. Inside a folder the migration creates, every folder holds a file with exactly its name, the main file or a router naming the files beside it, with `type`, `title`, `created`, and `status` where the ticketing rules give one (a container has none until work starts) in frontmatter. No file or folder name the migration writes carries a number or a date, apart from its own two: `migration-v6-v7/` and `archive-v6/`, which name the versions and are not artifact folders; a date lives in `created`. A ticket's identity is its `id` in frontmatter and its entry in the parent's `tickets.toml`.
"""

# Asked together at the plan step, after the inventory and before anything is written. Only a question the
# inventory leaves open is asked. Each comes with the module's recommended default, so "all defaults" is an
# answer. Every answer and its reason is recorded in the plan file.
questions = """
| Ask | Skip when | Answer decides |
|---|---|---|
| Back up the output folder first? Default yes: a copy beside it as `<output folder>-bak`, deleted by the user when they are done | The user says they have a backup; a clean, committed folder under version control counts, and every move is a `git mv` either way | Whether the copy is made, and nothing moves until it exists |
| Will you work on more than one initiative here over time, and maybe several at once? | The output folder already holds several bodies of work, which answers it | Nothing in the layout, which holds many either way; whether to say now that `active_initiative` is how the user switches |
| Will those initiatives touch other repositories than this one? | `_bmad/` already sits in a workspace folder above several repos | Store inside this repo, or beside it as its own repository in a workspace that holds the repos (`workspace`) |
| Do you want the plan's history apart from the code, so the store is its own git repository? Default yes | The output folder is already its own repository | `git init` and untracking from the project repo, or leaving it tracked where it is (`workspace`) |
| Do you want to work several branches of a project at once, agents in parallel? Default no | The project is already a bare repository with worktrees | Whether the checkout becomes bare plus worktrees (`workspace`) |
| Is the work here one initiative, or several, and what are they called? Default one, named after `core.project_name` | The folder holds one PRD or one epics file | The initiative split; what joins each |
| Keep the v6 acceptance criteria as refined story files, or let the builder write criteria at build time from the entry? Default the builder | Every story in `epics.md` already has a file | Entries only, or entries plus files |
| Finish, pause, or migrate through the builds in flight? Default finish first | No story is in-progress or in-review | Whether the migration waits |
"""

# Before anything moves.
precautions = """
- Read `_bmad/config.toml` and the `_bmad/custom/` overrides for `core.output_folder`, `modules.bmm.planning_artifacts`, `modules.bmm.implementation_artifacts`. Those are the source folders; a user may have renamed any of them.
- Inventory every file under the source folders, recursively, before planning. The plan accounts for each one in four lists: joins an initiative, with the evidence; moves to inbox; stays where it is; archived. Nothing is deleted.
- Read only what the migration rewrites: `epics.md`, `sprint-status.yaml`, and the story files, in full. Everything else is classified from its path, its frontmatter, and its first heading, and moved unchanged; a PRD, a brief, a design, a brainstorm is not read through. Rewriting paths is a search for the old paths across the store, not a read of every document. A file or folder that path, frontmatter, and first heading do not explain: ask the user what it is, in the plan, with the others.
- Nothing changes before the plan is approved. The inventory and the questions are read-only; the only writes before approval are the plan file itself and the backup, and the first move comes after approval.
- Commit before moving. The output folder under git: commit its current state first, and do every move with `git mv` so history follows the file. Tracked by the project repo: same, in that repo. Under no git at all: the backup and git questions in `questions` decide what comes first.
- Skills that still read the v6 paths after the move: `bmad-sprint-planning`, `bmad-correct-course`, `bmad-retrospective` in sprint mode. Say once that those stop finding the moved files and that the ticketing skill and `bmad-build` take over; do not offer to keep both layouts.
"""

# The conversion rules. Each names the v6 source, the v7 destination, and what changes on the way.
guide = """
## What joins the initiative

A file joins an initiative only on evidence: it is named in the PRD's or `epics.md`'s `inputDocuments`, cited as a spec companion, referenced by a story, or the user says so. Everything else in the output folder is not the initiative's, however long it has sat beside it. The plan shows four lists, each file once: joins the initiative, with the evidence; moves to inbox; stays where it is; archived. The user corrects the lists once. No per-file questions.

Unattributed remnants go to `inbox/`, default yes, asked once in the plan: a `brainstorming/` folder of unrelated sessions, a `specs/` folder of specs nothing consumed, a loose idea file. Each moves as it is, folder and contents unchanged, not renamed and not given frontmatter; inbox is the pile, and its shape is the user's to tidy. Declined, they stay where they are: at the root they are unrecognized and left alone. A half-run or a stray memlog with nothing else beside it goes to `inbox/archive-v6/`. The user can move anything anywhere later, including out of the store.

An idea or intent file the initiative grew from becomes `initiative-<slug>/intent.md` when it is the one intent, else `idea-<slug>/idea-<slug>.md` inside the initiative. An intent for work not started, and any idea with no initiative, becomes `inbox/intent-<slug>.md`, flat, where the ticketing skill later turns it into a ticket, an epic, or an initiative. `inbox/` is created with its `space.md` the first time something goes there, and not otherwise.

## Planning documents

For documents that join the initiative. Move, never copy: v6 skills that wrote them are not run again on this project. Each document gets its own folder in the initiative, `<type>-<slug>/`, with the main file renamed to `<type>-<slug>.md`. The slug is the v6 name with the date and the type prefix removed. Frontmatter is added or completed: `type`, `title`, `status` (the document's own status when it has one, else `done`), `created` (the date from the old folder name, else the file's first commit date, else today), `skill` (the v6 skill that wrote it).

| v6 | v7 |
|---|---|
| `prds/prd-<name>-<date>/prd.md` | `prd-<name>/prd-<name>.md` |
| `briefs/brief-<name>-<date>/brief.md` | `brief-<name>/brief-<name>.md` |
| `prfaq-<name>.md` | `prfaq-<name>/prfaq-<name>.md` |
| `ux-designs/ux-<name>-<date>/DESIGN.md`, `EXPERIENCE.md`, mocks | `ux-<name>/` keeps every file as is, plus `ux-<name>.md`: frontmatter and a short list saying what each file is |
| `architecture/architecture-<name>-<date>/ARCHITECTURE-SPINE.md` and siblings | `architecture-<name>/architecture-<name>.md`; siblings keep their names, the main file lists them |
| `specs/spec-<slug>/SPEC.md` and companions | `spec-<slug>/spec-<slug>.md`; companions unchanged; every `companions:` path and every cross-reference rewritten to the new locations |
| `brainstorming/brainstorming-<topic>-<date>.md` the PRD or brief names as input | `brainstorming-<topic>/brainstorming-<topic>.md` |
| `sprint-change-proposal-<date>.md` | `change-<slug>/change-<slug>.md`, slug from its title |
| Any other file a skill wrote | `<type>-<slug>/<type>-<slug>.md`, the type from its frontmatter or its name; when neither says, ask |
| A sharded document (`<name>/index.md` plus sections) | `<type>-<name>/<type>-<name>.md` is the old `index.md`, sections unchanged beside it |

A document that belongs to one epic (a retrospective, a spec that only that epic used) goes in that epic's folder under the same rule. Rewrite every path that pointed at a moved file: `companions:`, References sections, `inputDocuments:` frontmatter, links in prose.

## epics.md and sprint-status.yaml become the ticket tree

Read `epics.md`, `sprint-status.yaml`, and every story file in the implementation folder before writing anything. The ticketing skill's templates (`bmad-preview-ticketing/assets/`) are the shapes to write; open them.

Initiative envelope: `initiative-<slug>/initiative-<slug>.md` from the initiative template. Title from the project name; Description and Outcome from the PRD's summary; Done when from the PRD's goals; References naming the moved PRD, architecture, and UX; `covers` the PRD's requirement ids. The initiative's `tickets.toml` gets one `[[epic]]` per `## Epic N:` in `epics.md`, in that order, `id = N`, `slug = "epic-<slug>"`, `title`, `covers` the FR ids the coverage map assigns to that epic. `after = [{ epic = <id>, needs = "..." }]` only where `epics.md` states what one epic needs from another; that line records the need, and the gate is `after: [epic-<slug>]` in the dependent epic's own file, which holds every ticket under it until the named epic is done. Write both.

Each epic: `epic-<slug>/epic-<slug>.md` from the epic template. The slug is the epic title, kebab-case, without its number. Description and Outcome from the epic goal; Requirements from the FR lines the coverage map assigns to it, each keeping its id; Done when written from those requirements and confirmed with the user; `parent` the initiative folder; `status` from `sprint-status.yaml`: `in-progress` and `done` as they are, and `backlog` means no `status` line at all, since a container carries none until work starts. An `epic-N-retrospective: done` line becomes a `Retrospective:` line in the epic's Notes naming the moved retro file.

Each `### Story N.M:` becomes an `[[entry]]` in that epic's `tickets.toml`, in the order written: `id = M`, `type = "story"`, `title`, `description` (the "I want" sentence, restated as what exists when it is done), `verify` (one line distilled from its acceptance criteria), `covers` (the FR ids its criteria trace to, from the coverage map), `after = []` unless `epics.md` states that the story needs another, `hitl = false`, `risk = "low"` unless the text says otherwise, and `v6_key = "N-M-<slug>"`, the v6 sprint-status key, which the script ignores and the user can search.

Stories that had no file in v6 (`backlog` in `sprint-status.yaml`) stay entries: an entry with no file is the planned state, and the builder writes each story's criteria at build time from the epic's Requirements and the entry. When the criteria question in `questions` was answered keep, every such story is also pulled to `story-<slug>.md` with `status: draft`, `refined: true`, and its criteria copied into Acceptance Criteria.

Stories that had a file in v6 (`<N>-<M>-<slug>.md` or `spec-<N>-<M>-<slug>.md` in the implementation folder): the v6 story file is the build record, so it moves beside its ticket as `epic-<slug>/story-<slug>-plan.md`, content unchanged. A new `story-<slug>.md` is written from the story template with the entry's fields, `parent` the epic folder, `refined: true`, and the acceptance criteria from `epics.md`. Its `status` is the v6 status mapped:

| v6 (`sprint-status.yaml`, story file) | v7 |
|---|---|
| `backlog` | no file; entry only. A story file exists anyway: `draft`, and the file is kept |
| `ready-for-dev` | `ready-for-dev` |
| `in-progress` | `in-progress` |
| `review`, `in-review` | `in-review` |
| `done` | `done` |
| `drafted`, `contexted` (older v6) | `ready-for-dev` |

When the story file and `sprint-status.yaml` disagree, the more advanced status wins and the plan says so. A story file with no matching `### Story` in `epics.md` gets an entry written from the file's own intent, with the next unused `id`, and the plan flags it.

`action_items` in `sprint-status.yaml`: each `open` or `in-progress` item becomes an `Action item:` line in the initiative's Notes with its owner and epic; `done` items are dropped. Then `sprint-status.yaml`, `epics.md`, and any `epic-<N>-context.md` cache are moved to `initiative-<slug>/archive-v6/` unchanged, so nothing is lost while the tree is checked against them.

## A spec folder with stories.yaml

A `spec-<slug>/` that holds `stories.yaml` and `stories/` was an epic in all but name. When its work is the initiative's: create `epic-<slug>/` with the spec folder inside it as its requirement source (`spec-<slug>/spec-<slug>.md`); the epic's `covers` and each entry's `covers` cite the spec's `CAP-N` ids. Each `stories.yaml` entry becomes an `[[entry]]` in list order with its `id`, `title`, `description`; each `stories/<id>-<slug>.md` moves as `story-<slug>-plan.md` beside a new `story-<slug>.md`, status mapped as above. `RETROSPECTIVE.md` in the folder becomes `retro-<slug>/retro-<slug>.md` in the epic. Add the epic to the initiative's `tickets.toml`; the epic's `status` is `done` when every story is. A spec folder with no stories that the initiative cites moves as a planning document; one nothing cites goes to inbox with the other remnants.

## Loose implementation files

`spec-<slug>.md` files in the implementation folder with no epic and no story number were single `bmad-build` runs. Each becomes `backlog/story-<slug>.md` with `status` mapped and the v6 file beside it as `story-<slug>-plan.md`, or, when the user says it belonged to an epic, goes into that epic as above. `deferred-work.md` moves to the initiative folder as `deferred-work/deferred-work.md`. Walkthrough logs, test summaries, and anything else that the initiative's work produced follow the planning-document rule: `<type>-<slug>/<type>-<slug>.md` in the epic they concern, else the initiative.

## Configuration

Record `active_initiative = "initiative-<slug>"` under `[modules.bmm]` in `_bmad/custom/config.user.toml`, creating the file if needed. When the store moved (`workspace`), set `output_folder` under `[core]` in `_bmad/custom/config.toml`, the committed team override, never in the installer-managed `_bmad/config.toml`. Leave `planning_artifacts` and `implementation_artifacts` alone; `bmad setup` owns the rest of `_bmad/`. Then run the ticketing skill's store setup (`bmad-preview-ticketing/references/store-setup.md`) so `_bmad/custom/ticketing-store-config.toml` exists; the repo store is the match for a migrated tree, and its root is the one the plan already settled, not a new recommendation. Empty v6 folders left behind are removed; git never held them.

## Order of work

1. Inventory the source folders and read the config. Show the user what was found and which signals matched.
2. Write the plan as `<output folder>/migration-v6-v7/migration-v6-v7.md`, frontmatter `type: migration`, `title`, `status: draft`, `created`; it moves into the initiative folder at step 4 and its `status` becomes `done` at the end. It holds the four lists (joins, inbox, stays, archived), the epic and story mapping with each story's v7 status, the questions from `questions` that the inventory leaves open with a default each, and the config and repository changes their answers imply. Ask the questions together; wait for the answers, then for approval of the plan. The user reviews the plan before anything moves or changes; approval of the answers is not approval of the plan.
3. Make the backup: copy the output folder to `<output folder>-bak` beside it unless the user declined or git was accepted as the backup, and confirm it is there. Tell the user it is theirs to delete once they are happy.
4. In a repository that existed before the migration, commit the current state first. Then execute in this order: repository changes from `workspace`, when any; initiative folder and envelope; planning documents; epics, entries, tickets, plans; loose files and inbox; archive of `epics.md` and `sprint-status.yaml`; path rewrites; config; store setup. In a repository that existed before the migration, commit after each group, one commit each, messages naming the group. In a repository the migration created, commit nothing yet.
5. Verify with `checklist`. Record each item's result in the plan file. A failed item is fixed and rechecked, or reported with what is wrong; it is never skipped.
6. When the migration created the store's repository, offer its initial commit now, after verification, with everything the migration wrote and the plan file in it. Declined, say the tree is uncommitted and stop there; never push either way.
7. Once the tree is committed, for each epic whose status is `done`, a converted spec-epic included, offer to archive its story files: the `story-<slug>.md` and `story-<slug>-plan.md` files are removed in one commit per epic, and git keeps them; the epic envelope, its `tickets.toml`, and its retrospective stay. The user chooses per epic, default keep; the reasons are in `help/artifact-lifetime.md`. Nothing is archived in a tree that is not under version control.
8. Report: the tree as it now stands (`tickets.py status <initiative folder>`), what was archived, including any done epics' story files, what was left in place, and what the user does next: `bmad-preview-ticketing` to pull a story, `bmad-build` on a pulled ticket, and `bmad-project-context` for a root `AGENTS.md` that says where the plan lives, which initiative is active, that agents read only the active initiative, and, in a workspace, how worktrees are made.
"""

# What the repository answers in `questions` mean in files. Each is shown as a target tree in the plan and done
# before the artifact moves, so history follows the files into their final home. Skipped entirely when every
# answer keeps things as they are.
workspace = """
The store as its own repository, inside this project: `git init` in the output folder, then in the project repo `git rm -r --cached <output folder>` and add the folder to the project's `.gitignore`, so the two repositories do not track the same files. The project's history keeps the old copies; the store's history starts at the migration.

The store beside the project, in a workspace: create the workspace folder, move the project checkout into it as `<project>/`, move `_bmad/` and the output folder up to the workspace root, and `git init` the output folder. Then `bmad setup` at the workspace root, which is where every session starts from now on: one `_bmad`, one store, every repo reachable. A second project joining later brings its own v6 artifacts through this migration into the same store as its own initiative; its own `_bmad/` is left for `bmad setup` to report.

Bare repository plus worktrees, per project: no re-clone, and the old checkout stays whole until the new layout is proven. Commit or stash uncommitted work first and note the checked-out branch, `<base>` (`main`, `master`, `dev`, whatever the project uses). Then, beside the checkout: `git clone --bare <project> <project>.new/.bare`, write `<project>.new/.git` as the one line `gitdir: ./.bare`, `git -C <project>.new worktree add <base> <base>`, and check that `git -C <project>.new/<base> status` is clean and `git -C <project>.new/<base> log -1` matches the old checkout. Only then move the old checkout aside as `<project>.old`, rename `<project>.new` to `<project>`, set the bare repository's `remote.origin.fetch` to `+refs/heads/*:refs/remotes/origin/*` so fetches work, and remove `<project>.old` once the user confirms nothing uncommitted was in it. Work happens in a worktree per branch beside `<base>/`; flat branch names. Sessions run from the workspace root, and paths include the worktree (`<project>/<base>/src/...`).

The root `AGENTS.md` for any of these is step 8's `bmad-project-context` run. The rules and the reasons are in `help/monorepo-and-polyrepo.md`.
"""

# Verification. Every item is checked and its result recorded; an item that cannot be checked is reported as such.
checklist = [
  "Every file that was under the v6 planning and implementation folders is now under an initiative, `backlog/`, `inbox/`, or `archive-v6/`, or is listed in the plan as left in place.",
  "Every folder the migration created, apart from `archive-v6/`, holds a file named exactly after it, with `type`, `title`, `created`, and `status` where the ticketing rules give one, in frontmatter; and no name it wrote carries a number or a date, apart from `migration-v6-v7/` and `archive-v6/`.",
  "Every entry at the store root is an `initiative-` or `epic-` folder, `backlog/` or `backlog-<slug>/`, a space with its identity file, or a remnant the plan lists as left alone.",
  "`uv run <ticketing skill>/scripts/tickets.py --project-root <project-root> status <initiative folder>` exits 0 for every initiative, and its story counts, grouped the way `status` groups them, equal the story counts in the archived `sprint-status.yaml` after mapping, with the `epic-N` and `epic-N-retrospective` keys left out.",
  "Every `### Story N.M` in the archived `epics.md` is one `[[entry]]` with `id = M` under the epic with `id = N`, and every v6 story file is one `story-<slug>-plan.md` beside a `story-<slug>.md`.",
  "Every ticket file's `status` is one of draft, ready-for-dev, in-progress, in-review, done.",
  "Every `covers` id on an epic exists in the initiative's requirement source, every `covers` id on an entry exists in its epic's Requirements, and every requirement in the PRD's coverage map is covered by at least one entry.",
  "Every path in `companions:`, `inputDocuments:`, References sections, and prose links resolves to a file.",
  "`_bmad/custom/config.user.toml` names the active initiative under `[modules.bmm]`, `core.output_folder` resolves to the store, and `_bmad/custom/ticketing-store-config.toml` exists.",
  "The store is under git as the user answered, no file is tracked by two repositories, and when a workspace was made `bmad status` at its root reports the installation current.",
  "The plan file records every question asked, the answer, the backup made or the reason none was, every file the user was asked to identify, and the result of each item above.",
]