bmod-method

어떤 스킬인가요?

Required bmod metadata. Never invoke this skill.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

[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-po",
  "bmad-agent-ux-designer",
  "bmad-architecture",
  "bmad-build",
  "bmad-build-auto",
  "bmad-code-review",
  "bmad-prd",
  "bmad-prfaq",
  "bmad-product-brief",
  "bmad-project-context",
  "bmad-qa-generate-e2e-tests",
  "bmad-retrospective",
  "bmad-ux",
  "bmad-walkthrough",
]
required_skills = [{ skill = "bmad", version = "6.13.0", source = "github:bmad-code-org/BMAD-METHOD/skills" }]
pre_install_message = ""
post_install_message = ""

category,method,name,description,key_questions
owasp-top-10,a01-broken-access-control,A01:2025 Broken Access Control,Users act outside their intended permissions; includes server-side request forgery.,"Where is each authorization decision enforced, and is it on the server?|Can a user reach another user's records by changing an id in a request?|Which endpoints or admin functions have no role check?|Can the server be made to fetch a URL an attacker chooses?|Is access denied by default?"
owasp-top-10,a02-security-misconfiguration,A02:2025 Security Misconfiguration,"Insecure defaults, unneeded features, verbose errors or missing hardening in any layer.","Which default accounts, ports, sample apps or debug features are still enabled?|How is configuration kept consistent across environments, and who can change it?|Are security headers and cloud storage permissions set on purpose?|Do error responses reveal stack traces or versions?"
owasp-top-10,a03-software-supply-chain-failures,A03:2025 Software Supply Chain Failures,"Compromise through dependencies, build systems or distribution channels.","Is there an inventory of every direct and transitive dependency with its version?|How are new dependencies vetted and updates applied?|Who can change the build pipeline, and are its outputs signed?|What happens when a dependency is reported vulnerable?|Are packages and images pulled only from trusted sources?"
owasp-top-10,a04-cryptographic-failures,A04:2025 Cryptographic Failures,"Sensitive data exposed through missing, weak or misused cryptography.","Which data is sensitive, and is it encrypted in transit and at rest?|Which algorithms, key lengths and modes are in use?|Where are keys stored, who can read them, and how are they rotated?|How are passwords hashed?|Do tokens and secrets come from a cryptographically secure random source?"
owasp-top-10,a05-injection,A05:2025 Injection,"Untrusted input interpreted as code or commands: SQL, NoSQL, OS commands, LDAP, cross-site scripting.","Where does untrusted input reach an interpreter, query or shell?|Are queries parameterized everywhere, including reports and admin tools?|Is output encoded for the context it lands in?|Is input validated on the server against what is allowed?|Does any prompt or template mix user input with instructions?"
owasp-top-10,a06-insecure-design,A06:2025 Insecure Design,"Controls missing or ineffective at the design level, which no implementation can fix.","Which threats were considered when the design was made?|Which business flows can be abused by repetition, automation or steps out of order?|Where are rate limits and resource quotas?|Are tenants and trust levels separated by design?|Which security requirements have tests?"
owasp-top-10,a07-authentication-failures,A07:2025 Authentication Failures,Weaknesses in confirming identity and managing sessions.,"Where is multi-factor authentication offered or required?|What stops credential stuffing and brute force?|How are sessions created, expired and invalidated on logout or password change?|How does account recovery prove identity?|Are default and known-breached passwords rejected?"
owasp-top-10,a08-software-or-data-integrity-failures,A08:2025 Software or Data Integrity Failures,"Code or data trusted without checking it was not altered: unsigned updates, insecure deserialization, untrusted pipeline inputs.",How are updates and plugins verified before they run?|Is untrusted data ever deserialized into objects?|Which data crossing a trust boundary is checked for tampering?|Can a pull request or other outside input change what the pipeline deploys?
owasp-top-10,a09-security-logging-and-alerting-failures,A09:2025 Security Logging & Alerting Failures,"Attacks go unnoticed because events are not logged, watched or alerted on.","Which security events are logged: logins, access failures, high-value transactions?|Can logs be altered, and do they contain sensitive data?|Who receives an alert, and how fast?|Has the incident response plan been exercised?|Could an attacker's actions be reconstructed from the logs?"
owasp-top-10,a10-mishandling-of-exceptional-conditions,A10:2025 Mishandling of Exceptional Conditions,"Errors, edge cases and abnormal states handled so the system fails open, leaks data or loses consistency.","When a dependency times out or errors, does the system fail closed?|Can a partial failure leave a transaction half done?|What does an unhandled exception show the user?|How does the system behave under resource exhaustion or malformed input?|Are error paths tested?"
stride,spoofing,Spoofing,"Pretending to be another user, service or component; threatens authentication.","How does each component prove its identity to the others?|Which entry points accept a claimed identity without verifying it?|How are service credentials and tokens issued, stored and revoked?|Can a captured token be replayed?"
stride,tampering,Tampering,Changing data or code without authorization; threatens integrity.,"Which data in transit or at rest could be changed by someone who should not?|Where is integrity checked: signatures, hashes, database constraints?|Can a client alter values the server trusts, such as prices or roles?|Who can change code, configuration or the build?"
stride,repudiation,Repudiation,Denying an action when the system cannot prove who did it; threatens non-repudiation.,"Which actions could a user deny that the system must be able to prove?|Does the audit trail record who, what and when for those actions?|Are audit logs protected from the people they record?|Do timestamps come from a trusted clock?"
stride,information-disclosure,Information Disclosure,Exposing data to someone not allowed to see it; threatens confidentiality.,"Which data would cause harm if exposed, and who may see it?|Where could it leak: logs, errors, caches, backups, side channels?|Do responses and stores hold only the data they need?|What crosses a trust boundary unencrypted?"
stride,denial-of-service,Denial of Service,Making the system unavailable or degraded for legitimate users; threatens availability.,"Which resources can an unauthenticated caller exhaust?|Where are rate limits, timeouts and quotas?|Which single component's failure takes the system down?|What is the most expensive request an attacker can send?"
stride,elevation-of-privilege,Elevation of Privilege,Gaining capabilities beyond those granted; threatens authorization.,Where does a lower-trust caller reach higher-trust code?|Can a normal user reach admin functions or another tenant's data?|Does each component run with only the privileges it needs?|Which inputs could lead to code execution?

---
title: ""
template: brd
version: 1.0.0
description: "What the business requires and signs for, when the builder is a separate party."
not_for: "Product work inside one organization (`opportunity`, `prd`); a funding decision (`business-case`); what the system shall do, line by line (`srs`)."
agents: [bmad-agent-pm, bmad-agent-analyst]
rubric: rubric-planning
status: draft
created: ""
updated: ""
---

<!-- purpose: A baseline of what the business requires, signed by its sponsor, that a separate builder, vendor or delivery team plans and is held to. -->

<!-- stance: Stakes are usually contracted or regulated. Stay on the business side of the line: once a statement names a screen, a field or an API it has started designing, so move it to `prd` or `srs`. Push for an owner and a source on every requirement and rule. -->

<!-- inputs: The sponsor, the process being changed, and any business case, charter, contract or policy behind it. Only the user knows who signs, which rules are binding and what is out. -->

<!-- writing: About 3,000 words. Requirements are outcomes the business needs, not system behavior. Ids (BR-N, RULE-N) are global and never reused. A rule is stated once, in Business rules, and cited everywhere else. Objectives and cost point at the business case or charter where one exists instead of repeating it. -->

<!-- done when: Every BR-N has an owner, a source, a priority and a way to verify it; every rule has an id and an owner; nothing in the document names a screen, a field or an API; and the approval block names who signs. -->

<!-- next: `status: final` does not record a signature; the approval block does. After sign-off, `prd` or `srs` picks up the BR-N and RULE-N ids and fills the traceability table's empty columns. -->

# {title}

## Table of Contents

## Summary
<!-- required. What the business wants changed, for whom, and why now, in a short paragraph. -->

## Objectives
<!-- required. The measurable outcomes this serves, short, citing the business case or charter when one exists. -->

## Stakeholders
<!-- required. Who asks, who owns the outcome, who approves, who is affected. -->

## Scope
<!-- required. In and out, each explicit. -->

## Current and future process
<!-- required. How the work runs today and how it should run after, in business terms. diagram: flowchart -->

## Business requirements
<!-- required. A table: BR-N, the requirement as an outcome, owner, source, priority, how it will be verified. When everything comes back as a must, ask what the business would give up first, and rank from that answer. -->

## Business rules
<!-- required. RULE-N, kept apart from requirements: each rule states what must hold or how a term is defined, with its owner and source. Use a decision table where the logic is dense. -->

## Constraints and assumptions
<!-- optional. Limits the business sets on budget, dates, policy or suppliers, and what is assumed true. -->

## Cost and benefit
<!-- include when: no business case exists. Rough cost, expected benefit and who bears each. -->

## Traceability
<!-- required. A table: BR-N, then empty columns for the `prd` or `srs` line, the test and the ticket, which later documents fill in. -->

## Open questions
<!-- required. Each with an owner and what it blocks. -->

## Approval
<!-- required. A table of names, roles, decision and date. The user supplies each name; a blank row means not yet approved. -->

---
title: ""
template: decision-record
version: 1.0.0
description: "Recording any decision: context, options, choice and consequences."
not_for: "Asking someone to approve the choice (`proposal`)."
rubric: rubric-planning
status: draft
created: ""
updated: ""
---

<!-- purpose: Record one decision so a later reader knows what was chosen, what else was on the table, why this won, and what it costs. -->

<!-- stance: Keep it short; most records fit on a page whatever the stakes. Press on the options and the drivers. -->

<!-- inputs: The choice, who decides, by when, and the forces at play. Only the user knows which drivers weighed most, what was ruled out in conversation, and who was consulted. -->

<!-- writing:
  - Context states facts and forces without arguing for the outcome.
  - The decision is one active sentence: "We will ...".
  - A changed decision gets a new record that supersedes this one; this one is not rewritten beyond its status.
-->

<!-- done when: A reader who was not there can say what was chosen, what the alternatives were, why this one won, and what the team accepted in exchange. -->

# {title}

## Status
<!-- required. The user must pick exactly one of: proposed, accepted, rejected, deprecated, superseded. Superseded names the record that replaces this one. Then who decided and when. -->

## Context
<!-- required. The situation and the forces that make a decision necessary now. -->

## Decision drivers
<!-- optional. The criteria that separated the options, most important first. -->

## Options considered
<!-- required. Each real option, including doing nothing, with its main pros and cons against the drivers. If only one option is named, ask what else was considered and what tipped it. -->

## Decision
<!-- required. The chosen option and the reason it won. -->

## Consequences
<!-- required. What becomes easier, what becomes harder, what it costs, and the follow-up work it creates. If only upsides come back, ask what the team gives up. -->

## Confirmation
<!-- include when: the decision can be checked later. The review, test, metric or date that shows whether it held. -->

## Links
<!-- optional. Related or superseded records and the sources the context relies on. -->

---
title: ""
template: postmortem
version: 1.0.0
description: "Causes and actions after something went wrong, written blamelessly."
not_for: "Judging a person's performance."
rubric: rubric-planning
status: draft
created: ""
updated: ""
---

<!-- purpose: Learn from something that went wrong: what happened, why, and what changes so it does not recur. -->

<!-- stance:
  - Blameless: assume people acted sensibly on what they knew, and fix systems and processes, not people.
  - Facts before causes: settle the timeline, then analyze.
-->

<!-- inputs: Timestamped logs, chat, tickets, alerts and emails, asked for before reconstructing anything, because records beat memory; an event placed from memory alone is tagged `[ASSUMPTION]`. Only the user knows what people saw and believed at each moment, where the team got lucky, and which actions it will commit to. -->

<!-- writing:
  - Roles, not names, wherever cause is discussed.
  - Prefer action items that change a system over "be more careful".
  - One time zone, stated once.
-->

<!-- companions: When customers were told or still need telling, also write `{id}-{slug}-customer-notice.md`: what happened, who was affected and what changed, in plain words, with no internal names or system details. -->

<!-- done when: A reader who was not involved can follow the timeline and see how each factor contributed, and every factor has an action or a stated reason it has none. -->

# {title}

## Table of Contents

## Summary
<!-- required. What happened, the impact, and where things stand, in two or three sentences. -->

## Impact
<!-- required. Who or what was affected, how much, for how long. -->

## Timeline
<!-- required. From the earliest trigger through detection, response and resolution, with times. diagram: timeline -->

## Detection and response
<!-- optional. How it was noticed, how long it went unnoticed, what sped or slowed the response. -->

## Contributing factors
<!-- required. The conditions and decisions that combined to cause it, the trigger separated from what let it do harm. When an answer names a person as the cause or stops at human error, ask what let the mistake happen. diagram: flowchart -->

## Lessons
<!-- optional. What went well, what went poorly, where the team got lucky. -->

## Action items
<!-- required. Owner, due date, the factor addressed, and whether it prevents, detects or mitigates. -->

## Communication
<!-- include when: customers, funders or the public were told or still need telling. What was said and what remains. -->

---
title: ""
template: security-review
version: 1.0.0
description: "Reviewing a system against a standard such as the OWASP Top 10 or STRIDE."
not_for: "An incident that has happened (`postmortem`)."
rubric: rubric-planning
methods: methods-security.csv
status: draft
created: ""
updated: ""
---

<!-- purpose: Record how one system holds up against a security standard, with a finding per item reviewed and a plan for what fails. -->

<!-- stance: A reviewer walking the standard with the system's owner: take the catalog rows the user picks, or every row of the standard they name, a row at a time, and ask how this system handles each and where that is enforced. "The framework handles it" is not an answer until they say where. On the fast path, ask once for the evidence the user already has and mark every other row `unverified`. -->

<!-- inputs: The system, its scope and data flows; the standard or rows to cover; existing controls, test and scan results, known issues and accepted risks, which only the user can give. -->

<!-- writing: One finding per row reviewed, with the evidence the user gave. Record no test result, CVE, scan output or compliance statement the user did not supply. -->

<!-- done when: Every chosen row has a finding, every gap has a severity and either a remediation owner or a recorded acceptance, and each open question names who can answer it. -->

# {title}

## Table of Contents

## Scope and system
<!-- required. What is reviewed and what is not, the standard and rows covered, what the system does, who uses it and the data it holds. The user must pick the standard from the method catalog's `category` values; a standard not listed needs its rows added to the catalog first. -->

## Architecture and data flows
<!-- required. Components, where data enters, moves and rests, and the trust boundaries it crosses. diagram: flowchart -->

## Key request flows
<!-- include when: authentication, payment or a multi-party exchange carries the risk. The steps across components and boundaries. diagram: sequence -->

## Findings
<!-- required. A subsection per category reviewed; per row: item, status, evidence, severity for gaps. Status must be exactly one of: pass, gap, unverified (nobody knows yet; the check to run is the action), not applicable. Severity must be exactly one of: critical, high, medium, low. -->

## Risk decisions
<!-- include when: a gap will not be fixed now. The risk, who accepted it, why, and when it is revisited. -->

## Remediation plan
<!-- required. Each gap to fix: action, owner, priority, target date or milestone. -->

## Open questions
<!-- required. What could not be checked, and who can answer. -->

# 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 Sofia (`bmad-agent-po`) better input for a ticket's requirements.

**`bmad-product-brief`** — describes a product the user already believes in. The light way to give Sofia good input: more than a hand-written intent file, much less than a full PRD. Kept for comparison with John's brief (`bmad-agent-pm`) and will be retired; recommend John for a new brief.
- 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 → John the Product Manager (`bmad-agent-pm`).
- Writes: `{output_folder}/{active_initiative}/brief-<slug>/brief-<slug>.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 → a brief from John the Product Manager.
- 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: `{output_folder}/{active_initiative}/prfaq-<slug>/prfaq-<slug>.md`, plus `-distillate.md` beside it when finished.

# Keep ticket state and evidence

Joined plans are live ticket state, including after work is done. Keep them beside their entries or backlog leaves. They preserve status, baseline revisions, implementation evidence, and review findings for later work and retrospective.

Before closing an epic, run `bmad-retrospective`, decide how to handle its findings, and talk to Sofia the Product Owner (`bmad-agent-po`) to close the epic. Keep the epic, entries, plans, existing leaf files, and retrospective together. Deleting plans can turn completed entries back into planned work.

Scope ordinary agent reads to the active initiative and current epic in `AGENTS.md`. Historical plans are evidence, not a replacement for the current code. Superseded planning documents can be archived once their references and requirement sources remain accessible. Never remove live plans as part of that cleanup.

The output folder can be its own git repository, with commits as planning progresses. See `help/monorepo-and-polyrepo.md` for workspace layouts.

# 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` reads its ticket in full when one exists, then 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. `bmad-deep-recon` writes a cited account of how the code works and why, from the code and git history, and `bmad-build`'s plan step reads it as evidence; the walkthrough is for learning the code interactively.
3. **`bmad-architecture`**, only when needed and once a ticket file exists for it to read. It ratifies the conventions the codebase already shows in a short decisions list, adopted into the ticket. 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. Talk to **Sofia the Product Owner** (`bmad-agent-po`) to write the ticket's requirements and slice the stories, 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.

**The ticket is the spec.** The initiative, epic or story file is the spec at its level. Every skill that works on a ticket reads it first and in full and trusts it; its `sources:` are re-read only by Sofia when she updates it, and a `companions:` file only where the ticket points. Talk to Sofia the Product Owner (`bmad-agent-po`) to fill its Requirements from whatever the user has (a PRD, a brief, notes, a transcript), keep it in step with its sources, and slice from it.

A transcript, a chat or email thread, or a voice memo goes through `bmad-ingest` first when it is installed, and the note it returns is the input. A sharded document is given to any skill as its main file, named after its folder, which links to every shard. The method adds note templates for `standup`, `retrospective` (the meeting, not `bmad-retrospective`'s epic review), `sprint-review`, `discovery-workshop` and `user-interview`.

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-agent-po` (Sofia), `bmad-agent-pm` (John) and his planning documents, `bmad-ux`, `bmad-architecture` in depth, and customizing John's templates. |
| `help/implementation-skills.md` | `bmad-build` or `bmad-build-auto` 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 Sofia's ticket tree works (initiatives, planning an epic's stories, the breakdown, building from an entry, refining), plan status, review, and retrospective. |
| `help/ticketing-setup.md` | Setting up and driving the ticket tree with Sofia: 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. |

## Routing

Every "what next" is answered by the state of the spec at its altitude: the initiative file, then each epic file. Upstream skills exist to feed it.

```mermaid
flowchart TD
    A(["Request"]) --> B{"One session can understand, build, review and finish it?"}
    B -->|obvious, low-risk edit| B1(["Just edit. No skill"])
    B -->|yes| B2(["bmad-build"])
    B -->|no| C{"Initiative file exists?<br/>an active initiative may be set with none written yet"}

    C -->|no| D{"Work the idea out before it becomes the spec?<br/>the user wants to, or cannot yet say what it is"}
    D -->|no| S1["Talk to Sofia the Product Owner to write the initiative from what exists: a PRD, UX, a brief, notes, an idea explained<br/>sources (what the Requirements derive from) and companions (what downstream reads beside the ticket) go in the frontmatter"]
    D -->|cannot name a customer or problem| E1["bmad-forge-idea, bmad-brainstorming"]
    D -->|unsure it is worth building| E2["bmad-prfaq, or a prototype"]
    D -->|wants it written down, shareable| E3["Talk to John the Product Manager for a brief"]
    D -->|needs real detail, stakeholders, compliance, integrations| E4["Talk to John the Product Manager to create the PRD"]
    D -->|thinks in screens and flows| E5["bmad-ux"]
    E1 & E2 & E3 & E4 & E5 --> S1
    S1 --> F

    C -->|yes| F{"State of the initiative file"}
    F -->|open questions or assumptions| F1["Talk to Sofia the Product Owner to resolve them<br/>answers go to the source, the ticket, or both"]
    F -->|a new or changed input: UX added, PRD edited, an architecture| F2["Talk to Sofia the Product Owner to update the initiative<br/>the input becomes a source or companion; each disagreement with the spec goes to the user: fix or ignore"]
    F -->|not sliced| S2["Talk to Sofia the Product Owner to slice into epics, or into entries directly when the user asks<br/>each epic is written thin, refined: false"]
    S2 --> G{"Would separately built epics have to share decisions?<br/>stack, contracts, formats, hosting"}
    G -->|yes| G1["bmad-architecture reads the initiative<br/>then talk to Sofia the Product Owner to adopt it as a companion the epics cite"]
    G -->|no| H
    G1 --> H
    F1 & F2 --> F
    F -->|sliced, epics remain| H

    H{"State of each epic file"} -->|refined: false| S7["Talk to Sofia the Product Owner to refine the epic, scaled to the initiative<br/>each open point settled now, spiked, or left to the stories; the user may add a PRD from John, or a bmad-ux, bmad-architecture or bmad-deep-recon run on the epic"]
    H -->|refined, no entries| S3["Talk to Sofia the Product Owner to plan the epic's stories: entries in tickets.toml"]
    H -->|an entry needs criteria first: a bug, refine = true| S5["Talk to Sofia the Product Owner to refine it"]
    H -->|entries ready| I["bmad-build per entry<br/>bmad-build-auto when no one is present"]
    H -->|blocked| S6["Talk to Sofia the Product Owner to settle it as a dated Decision, or spike it"]
    H -->|a change surfaced mid-build| S4["Talk to Sofia the Product Owner to replan: she updates, re-slices or drops, and records the Decision"]
    S3 & S4 & S5 & S6 & S7 --> H
    I --> J["Review: inside bmad-build, bmad-code-review, or bmad-walkthrough<br/>the user marks the ticket done"]
    J --> H
    H -->|every ticket built, done or dropped| K["bmad-retrospective<br/>then talk to Sofia the Product Owner to close the epic"]
    K --> F
    F -->|every epic done| L(["Initiative done. Plans stay as evidence"])
```

Rules the diagram leans on:

- The shaping skills feed each other before they feed the spec: a brief or PRFAQ before a PRD when the requirements still need drawing out; `bmad-ux` before or after a PRD, and it may lead on its own; a PRFAQ verdict with serious gaps is addressed before anything else. Sofia the Product Owner takes more than one input.
- A prototype fits anywhere before the initiative file, and suits enterprise work, hobby work, and non-engineers; a throwaway needs no skill. Thrown away, talk to Sofia the Product Owner to write the initiative from its notes; kept, it is an existing codebase (`help/prototyping.md`).
- Risk, unclear requirements, architectural reach, or several people push work up from one session even when it is small.
- An epic file with no `refined` key counts as refined.
- Mid-path, recommend the next unfinished step of the route the user is on, not a restart. After a change, work resumes at the earliest affected step; unaffected work is not replayed.
- After `bmad-build`: open a PR, or `bmad-qa-generate-e2e-tests` when end-to-end coverage is wanted. 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.

## Match the situation

Situations the diagram does not settle.

| The user says or has | Recommend | Because |
|---|---|---|
| "Create a spec", "write the initiative", "distill this PRD", "slice this", "tickets", "what's ready", "where are we", "this changed, what now", "ask Sofia", "the product owner" | Talk to Sofia the Product Owner (`bmad-agent-po`) to do what the phrase says | Each phrase dispatches to one of her capabilities (SPEC, TICKETS, REFINE, BOARD, VALIDATE, REPLAN, STORE); no menu is shown. |
| "Create a PRD", "write the PRD", "update the PRD", "validate this PRD", "review my PRD", "write a product brief", "write the business case", "draft the program charter", "shape a pitch", "plan the launch", "ask John", "the PM", "the product manager" | Talk to John the Product Manager (`bmad-agent-pm`) to do what the phrase says | Each phrase dispatches to one of his capabilities (CREATE, VALIDATE); he picks the document from the altitude. |
| One bug or story to track, with no epic to hold it | Talk to Sofia the Product Owner to write it as a `backlog/` ticket, or an entry in the epic the user names | Standalone leaves live in `backlog/`, are refined first, and build like any entry. |
| The work is more than one initiative's worth | Talk to Sofia the Product Owner to propose a parent initiative | The parent is an ordinary initiative whose breakdown lists child initiatives in build order; each child keeps initiative, epic and story. Set the active initiative to the child being worked, or to the parent to see the whole. |
| 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`). |
| 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`). |
| 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`). |
| Wants tickets or a tracker (Jira, Linear, GitHub) as the record | Talk to Sofia the Product Owner to connect it | Tickets are the board. |
| A v6 project (`epics.md`, `sprint-status.yaml`, dated folders under the planning folder) that wants the v7 layout | `bmad migrate method`, before anything else | The module ships `migration-1.toml`: the rules for turning the planning folder into an initiative, moving document folders into it whole, and turning epics and sprint status into a ticket tree. Unrecognized files outside the planning folder stay where they are. The `bmad` skill plans it with the user, then performs it. |
| `tickets.py` stops with an error naming `bmad migrate`, or `tickets.toml` or epic folders sit directly in an initiative folder | `bmad migrate method` | The module ships `migration-2.toml`: it moves each initiative's and epic's breakdown into a `tickets/` folder inside it and rewrites the paths that pointed at the moved files. |

## The skills

One line per skill: what it is for and what it writes. Paths are in the active initiative's folder, `{output_folder}/{active_initiative}/`, or in `{output_folder}/` when none is active; each document is a `<type>-<slug>/` folder holding `<type>-<slug>.md`. A document from John, or a `bmad-ux` or `bmad-architecture` run, on an epic lands in the epic's folder instead, and Sofia adopts it as the epic's companion. Each initiative's and epic's breakdown sits in a `tickets/` folder inside it. With no active initiative, `bmad-agent-po` offers to create one; the other planning skills hand off to the `bmad` skill to set one. Showing, switching, creating, or clearing the active initiative is a `bmad` request. `planning_artifacts` and `implementation_artifacts` are no longer read.

| 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. Kept for comparison with John's brief and will be retired. | `brief-<slug>/brief-<slug>.md` |
| `bmad-prfaq` | Tests whether a concept survives scrutiny: press release, hard FAQs, researched claims, a verdict. | `prfaq-<slug>/prfaq-<slug>.md`, plus `-distillate.md` beside it |
| **Planning** (`help/planning-skills.md`) | | |
| `bmad-agent-po` | Sofia the Product Owner. Writes a ticket's Requirements and Constraints from any input, with a stable `R<n>` id per line naming its source, naming the gaps and walking them with the user, or recording each as an Open question line, when the input is sparse, and updates them when the input changes. Slices initiatives into thin epics and epics into stories, refines an epic or a story, runs the board (start, block, close, drop), validates, replans a change mid-flight, and connects a tracker. Stories are entries in `tickets.toml`; a file is written only when one is reviewed, refined, or published. A bug is a `backlog/` file or an entry in its epic. | The ticket file, with `.memlog.md` and companions beside it; the ticket tree under `{output_folder}/{active_initiative}/`, plus `{output_folder}/backlog/` |
| `bmad-agent-pm` | John the Product Manager coaches a planning document out of the user, picked by altitude and sized to the stakes: a brief, PRD, light PRD, prototype plan, experiment card, spec for a coding agent, opportunity assessment, business case, program charter, strategy narrative, Shape Up pitch, business requirements document, requirements specification or launch plan. He also updates and validates them. `bmad-prd` is kept for comparison with him and will be retired. | `<id>-<slug>/<id>-<slug>.md`, such as `prd-<slug>/prd-<slug>.md` |
| `bmad-ux` | How the product looks and works. May lead, follow, or stand alone. Can produce mocks and wireframes. | `ux-<slug>/` with `DESIGN.md`, `EXPERIENCE.md`, and `ux-<slug>.md` naming them |
| `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. | `architecture-<slug>/architecture-<slug>.md` |
| **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 ticket from the tree (nothing means the next ready one), or any file as intent. Reads a ticket in full with its epic. | A ticket's plan beside `tickets.toml`, or `plan-<slug>.md`; `deferred-work.md` |
| `bmad-build-auto` | One unattended build of one ticket, dispatched by a loop or script. Never for attended work. | The same plans as `bmad-build` |
| **Validation** (`help/validation-skills.md`) | | |
| `bmad-code-review` | Agent review of any diff, PR, or branch, with triaged findings; with no argument it offers the tickets in review. Redundant right after a thorough `bmad-build` review of the same change. | A dated block in the plan's `## Code Review` section, or chat |
| `bmad-walkthrough` | The human reviews a change block by block, guided. Also a way to learn unfamiliar code. | `walkthrough-<slug>/` with the narrative and a `-log.md` |
| `bmad-qa-generate-e2e-tests` | API and end-to-end tests for features that already exist. | Tests where the project keeps its end-to-end tests; the report is in chat |
| `bmad-retrospective` | Judges a finished epic folder in the ticket tree as a whole against its Done when. | `epic-<slug>-retrospective.md` in the epic folder, plus each approved `adr-<decision-slug>.md` beside the code it governs, or in the decisions folder when system-wide |
| **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` |

### 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 tickets | A whole epic folder | Nothing; proposes action items |

## The agents

Six 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, or write a business requirements document. |
| John, product manager — `bmad-agent-pm` | Planning | Turn a vision into a brief, a PRD or another planning document, and check readiness. |
| Sofia, product owner — `bmad-agent-po` | Planning | Write a ticket's requirements from whatever exists, slice it into epics and stories, run the board, and replan a change mid-flight. No menu: say what you want. |
| 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, 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.

## 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` or `bmad-build-auto`. 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 ticket from the tree, named by a ref such as `1.2`, its file, or its title; nothing, for the next ready ticket of the active initiative; a plan to resume; any other file as intent; or the recent conversation. With a ticket it reads the entry, its epic file and any story file in full, and opens a companion only where the ticket points; the PRD and UX are not build input.
- 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 it runs a quick review with one lens; a thorough review runs four independent lenses. The user can say `none`, `quick`, or `thorough` in the request; `thorough` suits a change that is unusually risky or makes many design decisions. It fixes clear findings itself and returns to the human when intent is in doubt. It commits and never pushes.
- Writes: a ticket's plan beside `tickets.toml`, or in `backlog/` for a backlog ticket, at the path `tickets.py find` returns, with `ticket` and a `status` it moves as far as `built`; the user marks the ticket done. Other work gets `{output_folder}/{active_initiative}/plan-<slug>.md`. Deferred goals go in `{output_folder}/{active_initiative}/deferred-work.md`. With no initiative active, both go in `{output_folder}/`.

**`bmad-build-auto`** — one unattended build of one ticket, 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 plan. It needs subagents. Its input is a ticket from the tree, one run per ticket; free text or an intent file also work. 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 tickets are well specified.
- Writes: the same plans as `bmad-build`.

A significant midstream change, such as a technical limit, a new or misread requirement, a pivot, or a failed approach, means talking to Sofia the Product Owner (`bmad-agent-po`, `help/planning-skills.md`) to replan: "this changed, what now". She reads the ticket tree, proposes the path (adjust, roll back, or cut scope), updates the ticket's Requirements when what is required changed, re-slices or drops the affected entries, and records the reason as a dated Decision line.

# 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 an initiative 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 ticket 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.

## The active initiative

In the method, the active initiative's folder is its part of the ticket store: its planning documents, epics, entries, and joined plans stay together; standalone tickets live in a backlog. See `help/ticketing-setup.md`. 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 Sofia (`bmad-agent-po`), John (`bmad-agent-pm`), `bmad-ux`, or `bmad-architecture`: what each gives, when to pick it, when not to, and what it writes.

**`bmad-agent-po`** — Sofia the Product Owner. Talk to her to write a ticket's requirements from any input and slice from them; the ticket file is the spec at its level.
- Gives: the ticket's Requirements and Constraints, one line per requirement with a stable `R<n>` id naming its source (`R1 (FR-2, FR-5)`) or, on an epic, its parent's id (`R1 (parent R3)`), plus its Assumption and Open question lines and companions beside the ticket. She adopts UX files and an architecture spine as References lines and absorbs a PRD or brief as a source. She then slices: an initiative into epics, an epic into entries whose `covers` cite the `R<n>` ids. She also updates and validates the requirements of an existing ticket. The user reaches her by name ("ask Sofia", "the product owner") or by saying what they want ("distill this PRD", "slice this initiative", "what's ready"); no menu is shown.
- Pick when: the user has anything to distill, or an idea to work through with her; after any analysis or planning skill finishes, before architecture; when requirements change (she appends to the ticket's `.memlog.md`, re-derives the lines, and names the tickets that no longer match).
- Not when: the user wants to work a bare idea out first → John the Product Manager, for a brief, or a PRD when full requirements are needed. With sparse input she coaches too, walking the sections with the user.
- Writes: the ticket file, `<type>-<slug>.md` in its own `<type>-<slug>/` folder (the initiative's is `{output_folder}/{active_initiative}/`), with `.memlog.md` and companions beside it. Each container's breakdown sits in a `tickets/` folder inside it: `tickets.toml`, the epic folders under an initiative, the leaf files and plans under an epic.

**`bmad-agent-pm`** — John the Product Manager. Talk to him to coach a planning document out of the user: a product brief, PRD, light PRD, prototype plan, experiment card, spec for a coding agent, opportunity assessment, business case, program charter, strategy narrative, Shape Up pitch, business requirements document, requirements specification, or launch plan.
- Gives: the document that fits the work's altitude, sized to the stakes. A program gets a charter or strategy narrative; an initiative a brief, PRD, opportunity assessment, business case, pitch, requirements specification or launch plan; an epic a PRD or pitch; a feature outside the ticket tree a spec for a coding agent. He offers a prototype plan for a simple hobby project, or to prove out an idea or try the look and feel before committing, and a light PRD with enough technical detail when a very simple project still wants a PRD. Once the user agrees, either can go to `bmad-build-auto`. An experiment card tests one hypothesis by measuring it. A business requirements document (`brd`) fits only when the business and the builder are separate parties or a sponsor must sign a baseline; product work inside one organization skips it, and Mary (`bmad-agent-analyst`) can write one too. Program and initiative documents state outcomes, capabilities and rules with stable ids for Sofia to lift; epic documents state testable requirements. He picks the template, says why, and names close alternatives. Fast path or coaching path. He also updates a document when the product moves, and validates one into review findings without changing it. The user reaches him by name ("ask John", "the PM", "the product manager") or by saying what they want ("create a PRD", "write a product brief", "write the business case", "validate this PRD").
- Pick when: the user would rather work the idea out before it becomes the spec; a consumer or multi-stakeholder product; compliance, integration, or SLA concerns; funding approval or a launch needs a document; an existing planning document needs editing or critique.
- Not when: scope is one or two stories → `bmad-build`. A lighter document will do → a brief from John, then talk to Sofia the Product Owner to write the initiative from it. A brief is an optional input, never a prerequisite.
- Customizing: a team adds, replaces or extends his templates with a file in `_bmad/custom/facilitate-templates/`. Doc standards, reviewers, output, style and the HTML view are set on `bmad-facilitate`, which runs his documents. `bmad-customize` writes those settings.
- `bmad-prd` and `bmad-product-brief` are kept for comparison with John and will be retired; recommend John.
- Writes: `{output_folder}/{active_initiative}/<id>-<slug>/<id>-<slug>.md`, `<id>` the template (`prd`, `brief`, `business-case`, and so on). Run on an epic, the folder goes in the epic's folder, `<slug>` the epic's without `epic-`.

**`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 John the Product Manager, for a PRD when requirements still need drawing out or a brief when a lighter write-up will do, or talk to Sofia the Product Owner to write the initiative from them when the design already says enough.
- In the ticket: both files are adopted as References lines. Change them with `bmad-ux` update, not through the ticket.
- Writes: `{output_folder}/{active_initiative}/ux-<slug>/`: `DESIGN.md`, `EXPERIENCE.md`, and `ux-<slug>.md` naming them. Run on an epic, `ux-<slug>/` goes in the epic's folder, `<slug>` the epic's without `epic-`.

**`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 spine 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, starting from the ticket's requirements; an existing codebase or a sprawling architecture document is input beside it.
- 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: no initiative file exists yet → talk to Sofia the Product Owner to write it first; architecture reads the ticket. One session builds all of it → skip.
- Next: talk to Sofia the Product Owner to adopt the spine as a companion of the ticket; the epics cite it. Recommend that first.
- Writes: `{output_folder}/{active_initiative}/architecture-<slug>/architecture-<slug>.md`. Run on an epic, `architecture-<slug>/` goes in the epic's folder, `<slug>` the epic's without `epic-`.

## Slicing and tracking the work

Sofia the Product Owner plans and tracks work in one ticket tree. An initiative holds epics; each epic's `tickets.toml` holds ordered entries. Build an entry directly without making a story file. Standalone stories and bugs can be direct intent or backlog leaves. Plans own status and remain live after completion. Builds stop at `built`; the user or orchestrator marks `done`. See `help/ticketing-setup.md`.

She slices initiatives into epics, plans each epic's stories as entries, refines when needed, and manages the board and optional tracker publishing. A PRD or described intent is valid input. Requirements stay in the epic and entries cite them with `covers`. A file is needed for refinement or tracker publishing, not to start a build. Tracker stores are lightly tested.

Slicing an initiative agrees with the user what its epics are, split by outcome, deployment and slice size; a team's own rule (`slice_to_epics` in `_bmad/custom/bmad-agent-po.toml`) can change that. Each new epic is written thin, with `refined: false`: Description, Outcome, Boundaries, Done when as far as known, and no Requirements yet.

Refining an epic is its own stage, run on request ("refine the booking epic") or before its stories are planned. In one message scaled to the initiative (on a small one, a single question: does the epic need anything before stories?), Sofia says what the epic, the initiative and their companions already settle for its stories, and names each open point with her pick: settle it with the user now, plan a spike when only code can answer it, or leave it to the stories. She reminds the user they can flesh the epic out further: more intent (their own notes or a PRD from John on the epic), more design (`bmad-ux` or `bmad-architecture` on the epic), or research (`bmad-deep-recon`). A run the user chooses lands in the epic's folder and becomes its companion. The epic then gets its Requirements and `refined: true`. An epic file with no `refined` key counts as refined.

When the work is more than one initiative's worth, Sofia proposes a parent initiative instead of deeper nesting. The parent is an ordinary initiative whose `tickets/tickets.toml` lists its child initiatives in build order, with the prerequisites between them; it holds no epics or stories. Each child is an ordinary initiative folder beside it, naming the parent's file in `sources:`. Set the active initiative to the child being worked, or to the parent to see the whole.

# 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 decision records (ADRs), one per decision, only for what is needed, named `adr-<decision-slug>.md` beside the code it governs, or in the repository's decisions folder (else `docs/decisions/`) for a system-wide one.
- `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 Sofia (`bmad-agent-po`) can get for a ticket's requirements. 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. |
| A short plan that records the goal and the result that would drop the idea, then a build that runs on its own | John the Product Manager (`bmad-agent-pm`) with a prototype plan | He asks only what the prototype needs, then hands the plan to `bmad-build-auto` once the user agrees. The plan's Outcome section records what the run taught. |
| 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, or from the existing code and its history, 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. Talk to Sofia the Product Owner to write the initiative from those notes, and the prototype itself if useful, or ask John the Product Manager for a 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, talk to Sofia the Product Owner to write the initiative from the prototype, then `bmad-architecture` to ratify the decisions worth keeping and name what is still open, adopted into the initiative before she slices 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` and `bmad-build-auto`

- `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: `quick`. `auto` follows the route: `quick` for `oneshot`, `thorough` for `full`. The user picks by saying "quick", "thorough", or "skip review" when invoking.
- `thorough` suits a change that is unusually risky or makes many design decisions.
- 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`: hand `bmad-build` the plan it left at `built`. It goes straight to review and triage, at the depth named in the request, and can be repeated. `bmad-build` does not resume a `done` plan; hand that one to `bmad-code-review`.
- After `bmad-build-auto`: dispatch its `built` plan again.
- Worth it after material fixes, or when an unattended run set `followup_review_recommended`. After a `thorough` build review it only repeats the same lenses.
- The depth a build ran at, skipped included, is the user's choice and no reason for another pass.
- At the end of an epic, `bmad-retrospective` is the thorough pass: it runs the review lenses over the epic's diff and proposes fixes as action items.
- 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 ticket, a plan, or a plain description. A ticket in review brings its plan; both are read in full. 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 (when the right fix depends on what you meant).
- The user chooses: apply all patches, walk through each, or leave them as action items in the plan's `## Code Review` section.

## 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, at the end of an epic, 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. It is the human's review pass: the findings come from the person, not from the agent. `bmad-code-review` and `bmad-retrospective` are the agentic passes over the same change.

For tickets and other documents, `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.

# The ticket tree

Sofia (`bmad-agent-po`) plans and tracks work in one tree. An initiative holds epics; each epic's `tickets.toml` holds ordered entries with ids, coverage, prerequisites, and verification. Build an entry directly. A review, a refinement, or tracker publishing adds a leaf file. Standalone stories and bugs can be direct build intent or backlog leaves.

Each container keeps its own file, `.memlog.md`, other skills' run folders and the retrospective at the top of its folder, and its breakdown in a `tickets/` folder inside it:

```
{output_folder}/initiative-<slug>/
  initiative-<slug>.md
  prd-<slug>/, ux-<slug>/, architecture-<slug>/
  tickets/
    tickets.toml                  # the epics in build order
    epic-<slug>/
      epic-<slug>.md
      ux-<slug>/                  # a run on the epic
      epic-<slug>-retrospective.md
      tickets/
        tickets.toml              # the entries in build order
        story-<slug>-plan.md
{output_folder}/backlog/          # standalone leaves and plans, no tickets/ folder
```

A tree in the earlier layout, with `tickets.toml` and epic folders directly in the initiative folder, makes `tickets.py` stop with an error naming `bmad migrate`: run `bmad migrate method` to move it.

Slicing writes each epic thin, with `refined: false`; refining it is its own stage before its stories are planned (`help/planning-skills.md`). Work bigger than one initiative gets a parent initiative whose breakdown lists child initiatives instead of epics.

Plans own status and baseline evidence and stay local on every store. Build stops at `built`; the user or orchestrator marks `done`. Code review appends dated findings to the plan without changing status. Retrospective writes `epic-<slug>-retrospective.md` directly in the epic, proposing action items without creating tickets or closing it. Keep completed plans as live state and historical evidence.

Use `help/ticketing-setup.md` for setup and `help/unattended-builds.md` for explicit Build Auto dispatch. Tracker stores remain lightly tested.

# Setting up and driving the ticket tree with Sofia

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

## Where the store lives

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

## Several repos

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

## Existing planning documents

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

## Trackers

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

## What the user says

| Say | Result |
|---|---|
| "Split this initiative into epics" | Proposes epic boundaries and records the agreed order in the initiative's `tickets.toml`. Each epic file is written thin, with `refined: false`. |
| "Refine the booking epic" | In one message, scaled to the initiative: what is already settled for its stories, and each open point with her pick (settle it now, spike it, or leave it to the stories). She reminds the user they can add more intent, design or research to the epic. The epic then gets its Requirements and `refined: true`. |
| "Plan the first epic's stories" | 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. |
| "Refine story 1.2", "review the stories" | Pulls the story's file from its entry 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 refine, ready to start, in progress, and blocked, for one epic or the whole initiative. |
| "Start story 1.2" | Checks it is ready to start. On a tracker, publishes it if it is not yet published and moves it to in progress. On the repo store there is nothing to write: run `bmad-build` on it. |
| "Mark story 1.2 done", "I'm working story 1.2" | Writes `status` in the story's plan through `tickets.py mark`, creating the plan when there is none. Done is only ever the user's, or an orchestrator's, to mark. |
| "Publish the tickets" | Sends tickets to the tracker, writing each ticket's file first. By default the whole breakdown publishes once approved; with `publication = "on_start"`, each ticket publishes when it starts. On the repo store, approving the breakdown commits it; nothing is published. |

## Hand-off to bmad-build

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

## Feedback

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

# Unattended builds

Use this when the user asks about `bmad-build-auto`, building tickets 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 ticket, then writes a final status to its plan. It never asks a question.
- Its review is `quick` by default. Passing `thorough` in the invocation suits a ticket that is unusually risky or makes many design decisions.
- It builds only what the invocation names and never picks work itself; given nothing, it halts `unclear intent`. It never moves on to a second ticket. Something else chooses each ticket and runs the loop: the user, a script, an AI coding session starting one worker per ticket, or an orchestrator such as bmad-loop, which does not dispatch from the ticket tree yet.
- It needs subagents and, under version control, a clean working tree on a branch that fits the ticket's epic.

## Accepted inputs

- A ticket from the tree, named as a ticket (`ticket 1.2`, or a ticket's title), or a ticket file. A bare ref or title is not taken as a ticket. It builds from the entry, its epic file, and the entry's story file when it has one, and never writes a ticket file.
- Free text or a path to an intent file.
- A plan an earlier run wrote.
- "Halt after planning" stops the run at `ready-for-dev`. The next dispatch implements it. An orchestrator uses this for the `plan_checkpoint` of an entry that is not refined; the run itself never reads `plan_checkpoint` or `done_checkpoint`.

## Where the plan goes

- A ticket's plan sits beside `tickets.toml`, or in `backlog/` for a backlog ticket, at the path `tickets.py find` returns, with `ticket` and `baseline_revision` in its frontmatter. Other work gets `{output_folder}/{active_initiative}/plan-<slug>.md`, or `{output_folder}/plan-<slug>.md` with no initiative active.
- A successful run ends at `built`, which the board shows as review. Only the user or an orchestrator marks the ticket done, with `tickets.py mark <ref> done`.
- This is the repo store. On a tracker store, `next` and `mark` refuse, so name the ticket and talk to Sofia the Product Owner (`bmad-agent-po`) to move it.

## Resume follows the plan's status

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

## Blocked runs

`blocked` means continuing without a human was unsafe. For a ticket named by ref, file, or title, the run records it with `tickets.py mark`, so `blocked_at` and `blocked_reason` sit in the plan, which is created if the run halted before planning; details are under `Auto Run Result`. Other halts set `status` in the plan and put the reason under `Auto Run Result`, or write a `bmad-build-auto-result-*.md` file in `{output_folder}/{active_initiative}/` (or `{output_folder}/` with no initiative active) when there is no plan yet. `tickets.py status` shows each blocked ticket with its reason. Common reasons:

- `unclear intent`, `intent gap`: the input cannot answer a question the run hit.
- `no subagents`.
- `ticket not resolved`: `find` failing on the reference.
- `implementation verification failed`.
- `review repair loop exceeded 5 iterations`: review kept sending the work back.
- `blocked plan supplied`: the plan is still marked blocked.
- `dropped plan supplied`: the ticket was dropped; the plan stays `dropped` and nothing is built.
- A dirty working tree or a mismatched branch.

A blocked plan halts every later dispatch of its ticket and keeps its first reason. To retry, fix the cause, then run `tickets.py mark <ref> <status>` with the status to resume from, which clears the blocked fields. A plan that holds only frontmatter can be deleted instead, and the next dispatch starts fresh.

## The saved patch on an intent-gap halt

When review halts on `intent gap`, the run saves the attempted change as a patch file beside the plan, names the path in the plan, and reverts the code. If the patch reads the intent correctly, the user runs `git apply` on it, sets the plan'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 plan's frontmatter, or `tickets.py status`. 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 ticket again gives another pass.
- `risk` in the frontmatter: `low`, `medium`, or `high`, the ticket's risk confirmed or raised at planning. `bmad-build` writes it too. A CI process can read it to decide how much review a change gets; BMad ships no such process.
- `deferred` in the frontmatter: real findings that were not this ticket'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 epic's last ticket, recommend `bmad-retrospective`.

## When it fits

- Fits: decisions and patterns are settled, tickets are well specified, and someone reads the results.
- Use `bmad-build` instead for risky or foundational tickets, 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 tickets | A whole epic folder | Nothing; proposes action items |

**`bmad-code-review`** — agent review of any diff, with verified and triaged findings. With no argument it offers the tickets in review, reads the chosen ticket and its plan in full, and diffs from the plan's `baseline_revision`.
- Pick when: the code did not come from `bmad-build`; a PR or branch needs review; after material fixes. For another pass on a `bmad-build` run, hand `bmad-build` its `built` plan; once the user has marked the plan `done`, hand it to `bmad-code-review`. After an unattended run that sets `followup_review_recommended`, dispatch `bmad-build-auto` on the same ticket again; it goes straight to a fresh review pass.
- Not when: `bmad-build` just ran a thorough 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. A finished epic → `bmad-retrospective`, which runs the review lenses over the epic's diff.
- Writes: a dated block in the plan's `## Code Review` section when it reviews a plan; otherwise findings stay in the chat. It never changes the ticket's `status`.

**`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: `{output_folder}/{active_initiative}/walkthrough-<slug>/` holding `walkthrough-<slug>.md` and `walkthrough-<slug>-log.md`. With no initiative active, the folder goes in `{output_folder}/`.

**`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 main path and the errors a user can see, follows the project's existing test setup, and never loosens a test to make it pass: a test that finds a bug is reported and kept as a known failure. Name a ticket and it takes its scenarios from there.
- 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 where the project keeps its end-to-end tests, and nothing else. The report is in chat.

**`bmad-retrospective`** — judges a finished epic folder in the ticket tree as a whole against the epic's Done when and the initiative's requirements.
- Gives: sourced findings no single session could see (architecture drift, duplication, spec versus built), owned action items, proposed decision records, and a verdict: accepted, accepted with open items, or rejected.
- Pick when: every ticket of the epic is `built`, `done`, or `dropped`, and especially after unattended runs. It reads `tickets.toml`, the epic file, and each ticket's plan. An unfinished ticket forces a rejected verdict; tickets still at `built` are listed for the user to mark done.
- Not when: one ticket or one diff is in question → `bmad-code-review` or `bmad-walkthrough`.
- Writes: `epic-<slug>-retrospective.md` in the epic folder, with the verdict in its frontmatter, plus an `adr-<decision-slug>.md` beside the code it governs, or in the decisions folder when system-wide, for each decision record the user approves, and nothing else. It marks nothing done.

# 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, talks to Sofia the Product Owner (`bmad-agent-po`) to write the initiative and needs no PRD. Recommend the full path (PRD, architecture, requirements on every 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 John the Product Manager (`bmad-agent-pm`) 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, ask John to update the PRD. Tell the user never to hand-edit `prd-<slug>.md`.
- `bmad-ux` starts from the existing design system. `bmad-architecture` reads the initiative and takes the existing architecture document or codebase as input beside it.
- When the PRD and a ticket's Requirements disagree, the ticket's Requirements win and the PRD is a source: Sofia surfaces the contradiction and the user decides.

## 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-agent-pm` | `prd-<slug>.md`, any brief, business case or charter, and their updates |
| Designer | `bmad-ux` | `DESIGN.md`, `EXPERIENCE.md` |
| Tech lead | `bmad-architecture` | The architecture spine |
| One engineer per epic | `bmad-agent-po`, `bmad-build`, `bmad-retrospective` | That epic's requirements, stories, verdict |
| Whoever tracks the whole | `bmad-agent-po` | the ticket tree |

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

## Large initiatives

Epics are split by outcome, deployment and slice size, not by who builds them. A team that wants another rule sets `slice_to_epics` in `_bmad/custom/bmad-agent-po.toml`.

Slicing writes each epic thin. Before its stories are planned, talk to Sofia the Product Owner to refine it ("refine the booking epic"): she names what is still open, with her pick for each. On a large initiative, the user may flesh an epic out with a PRD from John, or a `bmad-ux` or `bmad-architecture` run on the epic, or `bmad-deep-recon`. Those runs land in the epic's folder and become its companions.

When the work is more than one initiative's worth, talk to Sofia the Product Owner to propose a parent initiative. It holds the Requirements and decisions its children share and the order between them, and no epics or stories. Each child is an ordinary initiative, planned and built as usual, that names the parent in `sources:`. Set the active initiative to the child being worked, or to the parent to see the whole.

## 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 |
| John's PRD validation | Design and architecture work |
| Architecture spine review | Writing each epic's Requirements |
| `bmad-agent-po` planning approval | Accepting the breakdown and its dependencies |
| `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. Ask John to update the PRD. He surfaces conflicts with earlier decisions before applying anything.
2. Talk to Sofia the Product Owner to update the initiative's Requirements from the PRD. Requirement ids stay stable, and she names the epics and stories that no longer match.
3. `bmad-architecture` update when a decision shared across epics changes; it reads the updated initiative.
4. Talk to Sofia the Product Owner to re-slice them. Existing plans retain status.

For a change that threatens the plan itself, talk to Sofia the Product Owner to replan first: "this changed, what now".

## Tracker integration

- Nothing syncs with Jira or any tracker automatically, in either direction.
- Repo-store status lives in each joined plan. Builds stop at `built`; the user or orchestrator marks `done`.
- Sofia can publish tickets to Jira, Linear, or GitHub. When she runs, the tracker's status is read into the leaf file as `tracker_status`. The build's own `status` stays in its separate joined plan; tracker status never drives the build (`help/ticketing-and-epics.md`).

---
template: discovery-workshop
category: product-discovery
description: "A requirements or scoping session where stakeholders or a client say what should be built. Choose it when the session will feed a brief, a PRD or tickets."
---

<!-- purpose: Give the author of the planning document what stakeholders need, what they will not accept and what they left open, each traceable to who said it. -->

<!-- done when: Every need, constraint and exclusion a stakeholder stated is listed with who stated it, and no ask is shown as agreed scope. -->

# {title}

## Goals

<!-- What the stakeholders want to achieve and why, in their words where possible. -->

## Needs

<!-- Candidate requirements, one per line, each with who stated it. These are asks, not agreed scope. -->

## Constraints

<!-- Budget, dates, technology, regulation and people. -->

## Out of scope

<!-- What stakeholders ruled out. -->

## Risks and concerns

## Decisions

## Open questions

---
template: retrospective
category: agile-team
description: "A sprint or project retrospective, from a transcript or the team's notes. Choose it when the team looked back on how it worked and agreed what to change. Not for a postmortem of one incident."
---

<!-- purpose: Turn the retro into the actions the team agreed and the evidence behind them, so the next retro can check them. -->

<!-- done when: Every agreed action is listed, and no proposal the team did not agree to appears under Actions agreed. -->

# {title}

## Actions agreed

<!-- One line each: the action, then its owner and due date. Proposals the team did not agree to go under Discussed, not agreed. -->

## Last retro's actions

<!-- Optional: when the team reviewed them, each action and what was said about it. -->

## What went well

## What did not go well

<!-- Grouped by the cause the team named, not by who raised it. -->

## Discussed, not agreed

---
template: sprint-review
category: agile-team
description: "A sprint review or demo to stakeholders. Choose it when finished work was shown and stakeholders responded to it."
---

<!-- purpose: Record what stakeholders accepted, sent back and asked for, so the backlog can change. -->

<!-- done when: Every item shown has its outcome, and every new request is listed with who asked. -->

# {title}

## Shown

<!-- Each item demonstrated, with its ticket id. -->

## Feedback

<!-- By item: who said what. -->

## Outcome

<!-- Each item accepted or sent back. -->

## New requests

<!-- Asks not yet in the backlog, with who asked. -->

---
template: standup
category: agile-team
description: "A daily standup or scrum, from a transcript or notes. Choose it when each person reports what they did, what they will do and what blocks them."
---

<!-- purpose: Show the team's progress, and above all the blockers someone has to act on. -->

<!-- done when: Every blocker is listed with who has it and who was asked to help. -->

# {title}

## Blockers

<!-- Each blocker, who has it, and who was asked to help. -->

## By person

<!-- For each person: done, next, blocked. -->

## After the standup

<!-- Optional: topics moved to a follow-up, and who will meet about them. -->

---
template: user-interview
category: product-discovery
description: "An interview where a user or customer describes their own work and problems, or tries a product. Choose it for user research or usability testing. Not for a sales call."
---

<!-- purpose: Keep what the participant said and did apart from what anyone concluded from it, so later readers can draw their own conclusions. -->

<!-- done when: Every pain and goal rests on a quote or behavior recorded above it, and no interpretation sits in the evidence sections. -->

<!-- writing: Name the participant by role when the raw does not name them. Note where an answer followed a leading question. -->

# {title}

## Participant

<!-- Role, context, and what the raw says about how they were chosen. -->

## What they said

<!-- By topic, quoted. -->

## What they do

<!-- Behavior they described or showed: steps, tools, workarounds. -->

## Pains and goals

<!-- Each with the quote or behavior it rests on. -->

## Interpretation

<!-- Optional: conclusions the interviewer stated during the session. -->

# The method module's first migration, v6 to v7. `bmad migrate` runs a module's `migration-<n>.toml` files in `<n>` order.

[migration]
module = "method"
from = "6"
to = "7"
title = "Move v6 planning and implementation artifacts into the v7 initiative layout"
summary = "Turns the v6 planning folder into a v7 initiative with its documents moved as whole folders, turns epics.md and sprint-status.yaml into a ticket tree with joined plans, folds 6.13 pre-release spec folders into their tickets, sets 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.
- `spec-<slug>/spec-<slug>.md` with `.memlog.md` beside it, inside an `initiative-*/` or `epic-*/` folder or at the output folder's root: a 6.13 pre-release spec.
It applies only while there is no `active_initiative` under `[core]` 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, or a pre-release spec folder is present: then make the backup, write the plan and wait for approval, run "Pre-release spec folders", the checklist items on the fold and on live paths, and the report.
"""

# The layout the migration moves toward. `<root>` is `{output_folder}` from the BMad config.
target = """
<project-root>/.v6-v7-migration-backup-<datetime>/   # a full copy of `_bmad/` and the source folders, made first
<root>/
  initiative-<slug>/                # the v6 planning folder, renamed
    initiative-<slug>.md            # the envelope
    prd-<name>-<date>/              # each v6 document folder, moved whole, its name kept
      prd-<name>-<date>.md          # the main file, renamed to match its folder
    tickets/
      tickets.toml                  # one [[epic]] per epic, in build order
      epic-<slug>/
        epic-<slug>.md              # the epic envelope
        epic-<slug>-retrospective.md  # historical retrospectives
        tickets/
          tickets.toml              # one [[entry]] per story, in build order
          story-<slug>-plan.md      # the v6 build record; owns status
    archive-v6/                     # the v6 tracking sources, folded story files, and earlier build records, unchanged
  backlog/                          # loose story-, spike-, bug-<slug>.md with no epic, flat
  archive/                          # older document versions the user chose to archive, unchanged
  migration-v6-v7/migration-v6-v7.md  # the plan and verification record
  party-mode/                       # and anything else the migration does not own, left where it was
A moved document folder keeps its v6 name, dates and sequence numbers included. Names the migration writes from scratch (the envelope, epic folders, plans) follow the v7 ticketing names; `archive-v6/` and `migration-v6-v7/` name versions. `initiative-<slug>/`, `backlog/`, and `archive/` are always created.
"""

# Asked in one round after the inventory, defaults filled in from what was found. Other questions come up in the guide where they apply.
questions = """
| Question | Default |
|---|---|
| Your planning content is `<planning folder>` (a short summary) and your implementation content is `<implementation folder>` (a short summary). Right, and is there any elsewhere? | Yes; none elsewhere |
| Will this work touch other repositories, or should the planning files keep their own git history apart from the code? (`workspace`) | No |
"""

precautions = """
- Nothing changes before the plan is approved. The only writes before approval are the backup and the plan file.
- Nothing is deleted unless the user chose it. The backup is never committed, moved, or edited.
- Read in full only what the migration rewrites: `epics.md`, `sprint-status.yaml`, `stories.yaml`, `SPEC.md`, story files, and retrospectives. Classify everything else from its path, frontmatter, and first heading, and move it unchanged.
- When the files are under git, every move is a `git mv`, so history follows the file.
"""

guide = """
## Sequence

Run these in order. Each names the section that holds its rules.

1. Find the source folders ("Source folders").
2. Make the backup ("Backup").
3. Inventory the source folders ("Inventory").
4. Ask the `questions`.
5. Write the plan and wait for approval ("Plan").
6. Make the repository changes the answers ask for (`workspace`).
7. Create the initiative and move the documents ("Documents").
8. Write the ticket tree and plans ("The ticket tree").
9. Convert spec folders with stories ("Spec folders with stories.yaml").
10. Fold pre-release spec folders ("Pre-release spec folders").
11. Place loose implementation files ("Loose implementation files").
12. List what stays in place ("What stays in place").
13. Rewrite paths ("Path rewrites").
14. Update configuration and clean up ("Configuration and cleanup").
15. Run every `checklist` item and record its result in the plan. Fix and recheck a failure, or report it; never skip one.
16. Report ("Report").

In a repository that already existed, commit the current state before step 6 and after each of steps 6 to 14, the message naming the step; never stage the backup. In a repository the migration creates, commit nothing until the report offers it. Never push.

## Source folders

Read `_bmad/config.toml` and the `_bmad/custom/` overrides for `core.output_folder`, `modules.bmm.planning_artifacts`, and `modules.bmm.implementation_artifacts`. Those are the source folders; a user may have renamed any of them, and the questions confirm them. When `bmad setup` already removed these keys, read them from `_bmad/` in the `.v6-v7-migration-backup-*/` folders, newest first, using the first that has them.

## Backup

Copy `_bmad/` and the whole output folder to `<project-root>/.v6-v7-migration-backup-<datetime>/` (`<datetime>` as `YYYYMMDD-HHMM`), with the planning and implementation folders too when they sit outside it, write a `.gitignore` there holding `*`, and confirm the copy holds every file. When `bmad setup` already made one, copy into that one; its `_bmad/` is already there.

## Inventory

List every file under the source folders, recursively, and which `detect` signals matched; the questions show the user a summary of it. When an answer names another location, inventory it the same way and ask again only the questions it changes.

## Plan

Write `<root>/migration-v6-v7/migration-v6-v7.md` with frontmatter `type: migration`, `title`, `status: draft`, `created`. When stories are in progress or in review, ask whether to finish them in v6 first (the default). The plan holds every answer, including those the sections below ask for, what moves where, each story's v7 entry and status, the files left in place with the reason, and the config and repository changes. Wait for the user to approve it.

## Documents

A file belongs to an initiative when the PRD's or `epics.md`'s `inputDocuments` name it, a story references it, or the user says so.

The planning folder is renamed to `initiative-<slug>/` at the store root, and everything in it goes along, files the migration does not recognize included. When the planning folder is the output folder itself, create `initiative-<slug>/` and move the planning documents into it instead. The initiative is named after `core.project_name`. When the inventory suggests several (two PRDs, two briefs, architectures for different products), recommend a grouping and ask; the planning folder becomes the first, and the others get their document folders moved in.

Inside the initiative, each v6 document moves as a unit: its run folder with every file in it, or a flat file into a folder named after its stem (`prd.md`, a bare type, gets the project name: `prd-<project>/`). A run folder under a grouping folder (`prds/`, `briefs/`) moves up to the initiative's top level, and the emptied grouping folder is removed. The folder keeps its v6 name. The one change inside is that the main file is renamed to match its folder and gains `type`, `title`, and `created` frontmatter when it lacks them; when the folder has no single main file, a router named after the folder lists what each file is. When several folders or files share a name apart from a date or sequence number, ask whether they are all still relevant or the older ones move to `archive/`.

| v6 | Main file | Skill |
|---|---|---|
| `prds/prd-<name>-<date>/`, or flat `prd*.md` | `prd.md` | `bmad-agent-pm` |
| `briefs/brief-<name>-<date>/`, or flat `*brief*.md` | `brief.md` | `bmad-product-brief` |
| `architecture/architecture-<name>-<date>/`, or flat `architecture*.md` | `ARCHITECTURE-SPINE.md` | `bmad-architecture` |
| `ux-designs/ux-<name>-<date>/`, or flat `ux*.md` | router beside `DESIGN.md` and `EXPERIENCE.md` | `bmad-ux` |
| `prfaq-<name>.md` with its `-distillate.md` | `prfaq-<name>.md`; the distillate moves with it | `bmad-prfaq` |
| `research/<type>-<topic>-<date>/`, or flat `research/*-research-<date>.md` | the run's report | `bmad-deep-recon`, v6 research |
| `sprint-change-proposal-<date>.md` | itself | v6 correct course |
| `implementation-readiness*.md` | itself | v6 readiness check |
| A sharded document (`<name>/index.md` plus sections) | `index.md` | any |

From elsewhere in the output folder, a `brainstorming/` session and a `specs/spec-<slug>/` folder without `stories.yaml` move in the same way when they belong to the initiative; the spec's main file is `SPEC.md`.

## The ticket tree

Write from `bmad-agent-po`'s ticket template (`bmad-agent-po/assets/ticket-template.md`), the one template for an initiative, an epic and a story.

Initiative envelope: `initiative-<slug>/initiative-<slug>.md` from the ticket template. Title from the project name; Description and Outcome from the PRD's summary; Requirements one line per PRD requirement, `R<n> (FR-m): <the PRD's line>`, numbered from 1, and no `covers`; Constraints the PRD's constraints; Done when from the PRD's goals; `sources:` the PRD's path and `companions:` the architecture and UX files, with References naming their folders. Its `tickets/tickets.toml` gets one `[[epic]]` per `## Epic N:` in `epics.md`, in that order: `id = N`, `slug = "epic-<slug>"`, `title`, `covers` the initiative's `R` ids whose FR the coverage map assigns to that epic. Where `epics.md` states what one epic needs from another, write `after = [{ epic = <id>, needs = "..." }]` there and `after: [epic-<slug>]` in the dependent epic's file, which holds every ticket under it until the named epic is done.

Each epic: `tickets/epic-<slug>/epic-<slug>.md` in the initiative, from the ticket template. The slug is the epic title, kebab-case, without its number. Description and Outcome from the epic goal; Requirements the initiative lines the coverage map assigns to it, `R<n> (parent R<m>): <the line>`, in the PRD's words; Constraints the initiative's constraints that bind it; 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 no `status` line for `backlog`. An epic's v6 retro reports combine into `epic-<slug>-retrospective.md` in its folder, the name `bmad-retrospective` reads, and an `epic-N-retrospective: done` line becomes a `Retrospective:` line in the epic's Notes naming it.

Each `### Story N.M:` becomes an `[[entry]]` in that epic's `tickets/tickets.toml`, in the order written: `id = M` as v6 wrote it, quoted when it has a letter (`id = "6a"` for Story 2.6a), `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 epic's `R` ids its criteria trace to, through 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 key, kept for search. An epic or story heading with no number gets the next unused number, in the order written. A story file with no matching `### Story` gets an entry written from the file's own intent, with the next unused `id`, and the plan flags it.

### Build records

A v6 story file (`<N>-<M>-<slug>.md` or `spec-<N>-<M>-<slug>.md` in the implementation folder) is a build record. Ask whether to fold unstarted stories' files into their entries (default yes): v7 plans a story when work starts, and a file written early goes stale as earlier stories change the code. When folding, a story whose status, after the file and `sprint-status.yaml` are reconciled, is `backlog`, `ready-for-dev`, `drafted`, or `contexted` gets no plan: its file's intent, criteria, and verification go into its entry, and the file moves to `archive-v6/` unchanged. Any other build record moves into the epic's `tickets/` folder, beside its entry's `tickets.toml`, as `story-<slug>-plan.md`, keeping all criteria, implementation history, and review findings, with the criteria from `epics.md` merged in. Several records for one `<N>-<M>`, whatever their slugs, make one plan: the newest (highest `-<n>` suffix, else latest commit) is the plan, the others' criteria and history go into it under `## Prior builds`, and their files move to `archive-v6/`. Frontmatter: `ticket`, the entry's id (a backlog plan uses its leaf file stem); `status`, mapped below; a build `type` (`feature`, `bugfix`, `refactor`, or `chore`), never `story`; and `baseline_revision` only when the record holds a trustworthy one or a recorded equivalent. Never infer a baseline from today's HEAD; list each missing one in the report.

A story with no build record stays an entry with no plan, its full original criteria kept in the entry's description beside its intent. When tracking shows a status past `backlog` but the record is missing, write a minimal plan with that mapped status, saying the record is missing. Never write epic story files; the builder reads the entry and its epic. Plans stay in the live tree: they own status, baseline evidence, and review history.

| v6 (`sprint-status.yaml`, story file) | v7 |
|---|---|
| `backlog` | entry only without a build record; an existing build record not folded becomes a `draft` plan |
| `ready-for-dev` | `ready-for-dev` |
| `in-progress` | `in-progress` |
| `review`, `in-review` | `in-review` |
| `done` | `done` |
| `drafted`, `contexted` (older v6) | `ready-for-dev` |
| `blocked` | `blocked` |

Map any other value to the closest one above; when it is unclear, ask the user.

### Action items and archive-v6

Each `open` or `in-progress` item in `sprint-status.yaml`'s `action_items` 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 move to `archive-v6/` unchanged.

## Spec folders with stories.yaml

A `spec-<slug>/` holding `stories.yaml` and `stories/` that belongs to the initiative becomes an epic: create `tickets/epic-<slug>/` in the initiative and render `SPEC.md` into `epic-<slug>.md`: each `CAP-N` becomes a Requirements line `R<n> (CAP-N): <its intent and success>`, in order, its constraints become Constraints, its non-goals go to Boundaries, and its companions move beside the epic file, each a References line; each entry's `covers` cites the `R` ids. Each `stories.yaml` entry becomes an `[[entry]]` in list order with its `id`, `title`, `description`, original criteria, and verification. An id with a dash loses it (`3-2` becomes `32`, `CC-2` becomes `CC2`; the next unused number on a clash), and the original goes in `v6_key`. Each declared prerequisite becomes an `after` naming the migrated sibling id, cross-epic entry, or epic slug; report any that do not resolve for correction without dropping them, and never infer one from list order. The build record rules apply to its entries: each `stories/<id>-<slug>.md`, matched by its original id, moves as `story-<slug>-plan.md`, and an entry with no record gets a plan only when tracking shows a later status. `RETROSPECTIVE.md` follows the retrospective rule. Move `stories.yaml` and `SPEC.md` to `archive-v6/` unchanged. Add the epic to the initiative's `tickets.toml`; its `status` is `done` when every story is.

## Pre-release spec folders

A `spec-<slug>/` holding `spec-<slug>.md` and `.memlog.md` is a 6.13 pre-release spec; the initiative, epic or story file is the spec at its level now. Run `uv run <skill-root>/scripts/migrate_v6.py --project-root <project-root> --skill <skill-root> --fold-specs <root>` once. A folder inside a ticket folder folds into that ticket: the capabilities become Requirements lines, `CAP-<n>` mapped to `R<n>` after any `R` lines the ticket has, in the ticket, its `tickets.toml` and its children; the constraints become Constraints, the non-goals Boundaries lines, the assumptions and open questions Notes lines; the memlog entries are appended to the ticket's `.memlog.md` in order, with the why, the success signal and the fold recorded after them; the companions move beside the ticket as References lines; every reference to the folder in the store is rewritten to the new paths; and the folder is removed. A folder at `<root>` becomes `backlog/story-<slug>.md` the same way, its memlog and companions in `backlog/`. The script prints each fold with its id map, the files it rewrote and the companion paths it could not resolve, and `problems` for a folder it left alone (a companion whose name is taken, a folder outside a ticket); fix those by hand and run it again. Record the folds in the plan.

## Loose implementation files

A `spec-<slug>.md` in the implementation folder with no epic and no story number was possibly a single `bmad-build` run. For tracked standalone work, write `backlog/story-<slug>.md` (or `bug-<slug>.md`) with its original intent and criteria, and move the record beside it as `<type>-<slug>-plan.md` under the build record rules. When the user names an existing epic for it, it becomes an entry there instead. It can also stay direct build input outside the tree; never create an epic for it. `deferred-work.md` moves to the initiative folder unchanged. Walkthrough logs, test summaries (`tests/test-summary.md`), and other evidence move unchanged into the epic they concern, else the initiative.

## What stays in place

These stay where they are, listed in the plan and the report with the reason:

- `party-mode/`: v7 party mode reads its memory there.
- `project-context.md`: `bmad-project-context` offers to absorb it.
- `brainstorming/` sessions, `specs/` folders, and `forge/` that belong to no initiative.
- What another installed module claims: a path its config names (TEA's `test-artifacts/`) that lies outside the renamed planning folder, or one its own migration (`knowledge.py` `migrations`) covers. A configured path inside the planning folder moves with the folder; see "Configuration and cleanup".
- Anything else at the store root or in the implementation folder. List it as not recognized, with this note: the migration leaves these alone; moving them is the user's call, and if a BMad module wrote one, that module's migration missed it and is worth an issue.

## Path rewrites

Search the store for each old path and rewrite live references to it: `inputDocuments:`, References sections, prose links. This is a search, not a read of every document. Every moved file outside `archive-v6/` and `archive/` also has its own relative links and paths recomputed from its new folder, so they reach the same target whether it moved or not. Archived files and files left in place stay unchanged.

Then search the rest of the project, outside the store and `_bmad/`, for the old source folder paths. Never edit those files: list each one, with its line, in the plan and the report as a reference the user updates.

## Configuration and cleanup

Record `active_initiative = "initiative-<slug>"` under `[core]` 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`. A `_bmad/custom/` override that names a moved path, such as a `persistent_facts` line, is shown in the plan with its new path and rewritten on approval. So is a module config key whose path lies inside the renamed planning folder (for example `modules.tea.test_artifacts`): the plan names its new location, and on approval the new path is set in `_bmad/custom/config.toml`, which overrides `_bmad/config.toml` (setup owns that file), and also in `_bmad/custom/config.user.toml` when a personal answer holds the old path. A custom file that already sets the key is edited in place. Leave `planning_artifacts` and `implementation_artifacts` alone; `bmad setup` owns the rest of `_bmad/`. Its v6 cleanup (`migrate_v6.py --clean`) drops the customization keys the retired skills read, `initiative_template`, `epic_template`, `story_template`, `spec_template`, `spec_output_path`, `run_folder_pattern` and `on_complete`, from `_bmad/custom/bmad-agent-po.toml` and its `.user` file, and prints a note naming `ticket_template` and `<capability>_after` in their place; run it when setup has not. The repo store needs no store config.

Remove empty v6 folders left behind, and add a `.gitkeep` to any created folder that is empty.

## Report

Set the plan's `status` to `done`. When the migration created the store's repository, offer its initial commit now; declined, say the tree is uncommitted.

Report the tree with `uv run <project-root>/_bmad/method/scripts/tickets.py --project-root <project-root> status <initiative folder>`, the archived sources, the files left in place, and missing baselines. Name the backup folder and say it is the user's to delete once they are satisfied, or now if version control already holds the old state. Say that Sofia, the Product Owner (`bmad-agent-po`), replaces `bmad-sprint-planning`, `bmad-create-epics-and-stories`, `bmad-ticket`, `bmad-spec` and `bmad-correct-course`. Next: `bmad-build` on the next entry, with no story file pulled; `bmad-code-review` on a historical plan, leaving its status; `bmad-retrospective` on the epic; `bmad-project-context` for a root `AGENTS.md` naming the active initiative and any workspace conventions. Standalone intent remains valid build input.
"""

# What the repository answers in `questions` mean in files. Each is shown as a target tree in the plan and done
# before the artifacts move, so history follows the files. Skipped 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 run `bmad setup` at the workspace root, where every session starts from now on. A second project joining later migrates into the same store as its own initiative; `bmad setup` reports its leftover `_bmad/`.

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 from the v6 source folders is under an initiative (its `archive-v6/` included), `backlog/`, or `archive/`, or the plan and report list it as left in place, with the reason.",
  "Every moved document folder kept its v6 name and every file in it, and holds a main file named after the folder or a router. `initiative-<slug>/`, `backlog/`, and `archive/` exist, each with a `.gitkeep` when otherwise empty.",
  "Dated or numbered versions of one document are all present under their own names, unless the user chose to archive the older ones, as the plan records.",
  "`uv run <project-root>/_bmad/method/scripts/tickets.py --project-root <project-root> status <initiative folder>` exits 0 for every initiative; story counts match the archived tracking sources, excluding epic and retrospective keys, with backlog counted separately.",
  "Every classic or spec story is one entry, every story's build records one plan (or, when folded, its entry plus archived files), and no epic story files were written. `find` returns each expected plan, joined by id in an epic and by file stem in backlog.",
  "Every plan has a build type and a mapped status; done stays done, review stays in-review, nothing is relabeled built, supported baselines are kept, and missing ones are disclosed. Retrospectives sit directly in their epic with `epic`, only an evidenced verdict, and no ticket or leaf type.",
  "Every epic `covers` id is a line in the initiative's Requirements, every entry `covers` id one in its epic's Requirements, and every requirement in the PRD's coverage map has at least one entry.",
  "No `spec-<slug>/` folder holding `spec-<slug>.md` remains under the output folder; each ticket it folded into holds the spec's lines in Requirements and Constraints, its companions beside it as References lines, and one `.memlog.md` with the spec's entries in order, and no `CAP-` id remains outside `archive-v6/`, `archive/`, a Requirements line's parentheses or `.memlog.md`.",
  "Every live path in `inputDocuments:`, `sources:`, `companions:`, References sections, and prose links resolves to a file from the folder that holds it now; archived files and files left in place keep their original paths. A path already dead in v6 is listed apart and does not fail the item; one the migration broke does.",
  "`_bmad/custom/config.user.toml` names the active initiative under `[core]`, and `core.output_folder` resolves to the store.",
  "Every module config key whose folder moved with the renamed planning folder names its new location.",
  "The store is under git as the user answered, no file is tracked by two repositories, and in a new workspace `bmad status` at its root reports the installation current.",
  "`.v6-v7-migration-backup-<datetime>/` holds every file the source folders held before the migration, and no commit includes it.",
  "The plan records every question, its answer and reason, the backup's path, every file the user identified, and each item's result.",
]

# The method module's second migration: each initiative's and epic's breakdown moves into a `tickets/` folder inside it. `bmad migrate` runs a module's `migration-<n>.toml` files in `<n>` order.

[migration]
module = "method"
from = "7 preview"
to = "7"
title = "Move each initiative's and epic's breakdown into its tickets/ folder"
summary = "Moves each initiative's `tickets.toml` and epic folders, and each epic's `tickets.toml`, leaf files and plans, into a `tickets/` folder inside it, and rewrites the paths that pointed at them. Ticket files, memlogs, retrospectives, document folders and `backlog/` stay where they are."

# Read-only signals under `core.output_folder`. Either one makes this migration apply.
detect = """
- An `initiative-*/` folder with `tickets.toml`, an `epic-*/` folder, a `story-*.md`, `spike-*.md` or `bug-*.md` leaf file, or a `*-plan.md` plan directly in it.
- An `epic-*/` folder with `tickets.toml`, a `story-*.md`, `spike-*.md` or `bug-*.md` leaf file, or a `*-plan.md` plan directly in it.
"""

# `<root>` is `{output_folder}` from the BMad config.
target = """
<project-root>/.tickets-folder-migration-backup-<datetime>/   # a copy of the output folder and _bmad/custom/, made first
<root>/
  initiative-<slug>/
    initiative-<slug>.md            # stays, with .memlog.md, glossary.md and document folders such as prd-<slug>/
    tickets/
      tickets.toml                  # moved from the initiative folder
      epic-<slug>/                  # moved whole from the initiative folder
        epic-<slug>.md              # stays in the epic folder, with .memlog.md, epic-<slug>-retrospective.md and run folders
        tickets/
          tickets.toml              # moved from the epic folder
          story-<slug>.md           # leaf files and plans, moved from the epic folder
          story-<slug>-plan.md
  backlog/                          # unchanged
An initiative with no epics gets a `tickets/` folder for its `tickets.toml`, leaf files and plans. An epic folder outside an initiative gets one the same way.
"""

precautions = """
- Nothing moves before the user approves the plan. The only write before approval is the backup.
- Nothing is deleted. The backup is never committed, moved, or edited.
- When the store is under git, a tracked file moves with `git mv`, so history follows it; an untracked one moves with `mv`.
- `backlog/` and files outside the output folder are not changed; in `_bmad/`, only the `_bmad/custom/` overrides the approved plan names.
"""

guide = """
## Sequence

1. Make the backup ("Backup").
2. Write the plan and wait for approval ("Plan").
3. Move the breakdowns ("Moves").
4. Rewrite paths ("Path rewrites").
5. Run every `checklist` item and record its result in the report. Fix and recheck a failure, or report it; never skip one.
6. Report ("Report").

When the store is under git, commit the current state before step 3 and after steps 3 and 4, the message naming the step; never stage the backup. Never push.

## Backup

Read `core.output_folder` from `_bmad/config.toml` and the `_bmad/custom/` overrides. Copy the whole output folder and `_bmad/custom/` to `<project-root>/.tickets-folder-migration-backup-<datetime>/` (`<datetime>` as `YYYYMMDD-HHMM`), write a `.gitignore` there holding `*`, and confirm the copy holds every file.

## Plan

List each folder that matched `detect`, what moves out of it, and each file and `_bmad/custom/` override whose references change ("Path rewrites"). Show it to the user and wait for approval.

## Moves

In each matched initiative folder, create `tickets/` and move `tickets.toml`, every `epic-*/` folder whole, every `story-*`, `spike-*` and `bug-*` leaf file and every `*-plan.md` plan into it. Then in each epic folder, wherever it now sits, create `tickets/` and move `tickets.toml`, every leaf file and every plan into it. The initiative or epic file, `.memlog.md`, `glossary.md`, `epic-<slug>-retrospective.md`, other skills' run folders (`prd-*/`, `ux-*/`, `architecture-*/`, `research-*/` and the like) and anything else stay where they are.

## Path rewrites

For each moved file and folder, search the store for its old path, written from the project root or from the output folder, and rewrite each live reference to the new path: `sources:`, `companions:`, `inputDocuments:`, References lines such as a pulled leaf's `parent` line, and prose links. A bare folder name, such as `parent: epic-<slug>` or an `after` slug, stays. Every moved file also has its own relative links recomputed from its new folder, so they reach the same target. This is a search, not a read of every document.

A `_bmad/custom/` override that names a moved path, such as a `persistent_facts` line or glob (`initiative-<slug>/epic-*/epic-*.md`), is shown in the plan with its new path and rewritten on approval. Leave the rest of `_bmad/` alone; `bmad setup` owns it.

Then search the rest of the project, outside the store and `_bmad/`, for the old paths. Never edit those files: list each one, with its line, in the report as a reference the user updates.

## Report

Report each initiative's tree with `uv run <project-root>/_bmad/method/scripts/tickets.py --project-root <project-root> status <initiative folder>`, every checklist result, and the references outside the store. Name the backup folder and say it is the user's to delete once they are satisfied, or now if version control already holds the old state.
"""

# Verification. Every item is checked and its result recorded; an item that cannot be checked is reported as such.
checklist = [
  "No `initiative-*/` folder under the output folder holds `tickets.toml`, an `epic-*/` folder, a leaf file, or a plan directly, and no `epic-*/` folder holds `tickets.toml`, a leaf file, or a plan directly; each sits in its container's `tickets/` folder.",
  "Every output-folder file the backup holds is in the store at its old path or its new one. Initiative and epic files, `.memlog.md`, `glossary.md`, retrospectives, run folders, and `backlog/` are where they were.",
  "`uv run <project-root>/_bmad/method/scripts/tickets.py --project-root <project-root> status <initiative folder>` exits 0 for every initiative and lists every epic and entry its `tickets.toml` files hold.",
  "Every live path in `sources:`, `companions:`, `inputDocuments:`, References sections, prose links, and `_bmad/custom/` overrides that pointed at a moved file resolves to it from the folder that holds it now, and every glob there matches the files it matched before. A path already dead before the migration is listed apart and does not fail the item.",
  "Under git, every moved tracked file kept its history (`git log --follow` reaches its commits from before the move), and no commit includes the backup.",
  "`.tickets-folder-migration-backup-<datetime>/` holds every file the output folder and `_bmad/custom/` held before the migration.",
]

# Skills this module no longer ships. `bmad setup` offers to delete any still installed and moves a renamed
# skill's `_bmad/custom/` files to the new name. A retired name is never reused.
renamed = [
  { from = "bmad-create-ux-design", to = "bmad-ux" },
  { from = "bmad-ticket", to = "bmad-agent-po" },
]
removed = [
  "bmad-agent-sm",
  "bmad-agent-qa",
  "bmad-agent-quick-flow-solo-dev",
  "bmad-create-product-brief",
  "bmad-product-brief-preview",
  "bmad-quick-spec",
  "bmad-quick-flow",
  "bmad-quick-dev-new-preview",
  "bmad-agent-bmm-analyst",
  "bmad-agent-bmm-architect",
  "bmad-agent-bmm-dev",
  "bmad-agent-bmm-pm",
  "bmad-agent-bmm-qa",
  "bmad-agent-bmm-quick-flow-solo-dev",
  "bmad-agent-bmm-sm",
  "bmad-agent-bmm-tech-writer",
  "bmad-agent-bmm-ux-designer",
  "bmad-bmm-check-implementation-readiness",
  "bmad-bmm-code-review",
  "bmad-bmm-correct-course",
  "bmad-bmm-create-architecture",
  "bmad-bmm-create-epics-and-stories",
  "bmad-bmm-create-prd",
  "bmad-bmm-create-product-brief",
  "bmad-bmm-create-story",
  "bmad-bmm-create-ux-design",
  "bmad-bmm-dev-story",
  "bmad-bmm-document-project",
  "bmad-bmm-domain-research",
  "bmad-bmm-edit-prd",
  "bmad-bmm-generate-project-context",
  "bmad-bmm-market-research",
  "bmad-bmm-qa-generate-e2e-tests",
  "bmad-bmm-quick-dev",
  "bmad-bmm-quick-spec",
  "bmad-bmm-retrospective",
  "bmad-bmm-sprint-planning",
  "bmad-bmm-sprint-status",
  "bmad-bmm-technical-research",
  "bmad-bmm-validate-prd",
  "bmad-investigate",
  "bmad-agent-tech-writer",
  "bmad-check-implementation-readiness",
  "bmad-create-epics-and-stories",
  "bmad-sprint-planning",
  "bmad-correct-course",
  "bmad-spec",
  "bmad-preview-ticketing",
]

# 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-po"
skill = "bmad-agent-po"
name = "Sofia"
icon = "🎯"
title = "Product Owner"
persona = "Owns what each ticket requires, how the work is split and ordered, what is accepted as done, and what changes when the plan meets reality; every line on the backlog names where it came from. Speaks plain and short: what is in, what is out, and why — says no early and kindly, with the reason, and asks only what is unsettled, with the answer she would pick."

[[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`.