basic BMAD setup

.agents/skills/bmod-method/help/analysis-skills.md

@@ -0,0 +1,16 @@
+# Analysis skills in detail
+
+Read this when the question is about `bmad-product-brief` or `bmad-prfaq`: what each gives, when to pick it, when not to, and how the two relate. Both exist to give `bmad-spec` better input.
+
+**`bmad-product-brief`** — describes a product the user already believes in. The light way to give `bmad-spec` good input: more than a hand-written intent file, much less than a full PRD.
+- Gives: a 1-2 page brief (problem, solution, who it serves, what is different, success criteria, scope, vision) that is the user's own, plus an addendum holding detail meant for later documents.
+- Pick when: the user knows what they want and needs it written down, would otherwise hand-write an intent file and wants it sharper, does not need the rigor of a PRD, needs a pitch or alignment document, has material to distill, is short on time (its fast path drafts everything with `[ASSUMPTION]` tags), or has a brief to update or pressure-test.
+- Not when: the user doubts the idea itself → `bmad-prfaq`. The brief never asks whether the product should exist. Requirements need ids, journeys, and metrics, or compliance and many stakeholders are involved → `bmad-prd`.
+- Writes: `{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 → `bmad-product-brief`.
+- With the brief: most projects need one of the two. Pick by what the user lacks, a clear description or confidence in the idea. A brief after a PRFAQ is reasonable when stakeholders need a short read.
+- Writes: `{output_folder}/{active_initiative}/prfaq-<slug>/prfaq-<slug>.md`, plus `-distillate.md` beside it when finished.

.agents/skills/bmod-method/help/artifact-lifetime.md

@@ -0,0 +1,9 @@
+# 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 close through `bmad-ticket`. 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.

.agents/skills/bmod-method/help/existing-codebase.md

@@ -0,0 +1,20 @@
+# Using the method on an existing codebase
+
+The method works on an inherited or long-lived codebase with no up-front documentation pass. `bmad-build` investigates the repository on every run, writes down what to reuse and what not to change, and follows that. Too little planning costs one build run, so start small and add planning only when the work calls for it.
+
+BMad is installed per project. The existing repository needs its own install and its own `bmad setup`.
+
+## Suggested order
+
+1. **`bmad-project-context`**, recommended. A good initial `AGENTS.md` is worth having: it records a small, verified set of rules for agents. Skipping it does not fail a build; the cost is the same mistake every session until someone writes the rule down. When the repo already has a maintained `AGENTS.md` or `CLAUDE.md`, it adopts that file instead of starting over. It does not produce a repo overview or a stack list, so it will not teach the user the app.
+2. **`bmad-walkthrough`**, when the user does not know the code. It guides them through a file, directory, commit, or PR at their own pace: intent first, then broad strokes, then detail.
+3. **`bmad-architecture`**, only when needed. It can start from the codebase and ratify the conventions worth keeping in a short decisions list. Skip it when the codebase is well documented or the changes are small.
+4. **`bmad-build`** for the first change. Pick something one session can finish. A change that follows established patterns, such as a new route in a layered API, needs no planning skill: a short intent file or a few sentences is enough input.
+5. **`bmad-spec`**, then one `bmad-build` per story, when a change is bigger than one session.
+6. **`bmad-qa-generate-e2e-tests`**, when the inherited app has little test coverage. It generates API and end-to-end tests for features that already exist.
+
+If the codebase is inconsistent or has few tests, cleanup first pays back in every later session (`help/preparing-a-repo-for-agents.md`).
+
+## What pushes a change up a tier
+
+Size alone does not. A change needs more than `bmad-build` when it forces a decision the existing patterns do not cover: a new boundary between components, a schema migration strategy, new authorization rules. The user can also state such a decision in the intent, and `bmad-build` will raise it while clarifying.

.agents/skills/bmod-method/help/help.md

@@ -0,0 +1,157 @@
+# BMad Method knowledge
+
+This document covers the skills of the `method` module: what each one gives the user, when to recommend it, and what to offer next.
+
+## How the method works
+
+The method turns an intent of any size into working software. Recommend the smallest path that safely fits the work; never march the user through every skill. A project may hold only some of these skills: recommend from what is installed, and say plainly when a step has no installed skill rather than inventing a substitute.
+
+**`bmad-spec` is the hub.** It condenses any input, at any altitude, into a spec folder: `spec-<slug>.md` plus companion files, the contract every build reads. A user can talk to it directly. Every analysis and planning skill exists to give the user better material to feed into a spec, and they can run in any order, before or after the spec exists, because the spec is re-derived from a running log and never hand-merged. After any of them finishes, the usual next step is to fold its result into the spec with `bmad-spec`.
+
+The four phases are analysis (ideation, research, is it worth building), planning (what exactly, and in what slices), implementation (build it), and validation (is it right). They describe what kind of help a skill gives. They are not a mandatory sequence to complete.
+
+Project size decides how many build sessions the work needs. Stakes decide how heavy the planning gets. A large hobby project keeps planning light; a small change to a regulated system may not.
+
+## More detail
+
+This document should be enough to route the user and say what to do next. Each topic file below sits in this folder and goes deeper on one subject. Read one only when the question is about that subject, using the path the knowledge script lists for it.
+
+| Topic file | Read when the user asks about |
+|---|---|
+| `help/analysis-skills.md` | `bmad-product-brief` or `bmad-prfaq` in depth: what each gives, when to pick it, when not to, how they relate. |
+| `help/planning-skills.md` | `bmad-spec`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, `bmad-ticket` in depth. |
+| `help/implementation-skills.md` | `bmad-build`, `bmad-build-auto`, or `bmad-correct-course` in depth. |
+| `help/validation-skills.md` | `bmad-code-review`, `bmad-walkthrough`, `bmad-qa-generate-e2e-tests`, or `bmad-retrospective` in depth. |
+| `help/prototyping.md` | Prototyping or vibe coding first, what a prototype is good for (worth doing, feasibility, complexity, unknowns), non-engineers prototyping, what to do with a prototype afterwards, whether planning still matters after a good first version. |
+| `help/existing-codebase.md` | Using BMad on an inherited, brownfield, or long-lived codebase. |
+| `help/preparing-a-repo-for-agents.md` | Getting a codebase ready for agentic coding, inconsistent agent output, how much documentation to keep (small ADRs, not heavy docs), regular refactoring, holding quality over time. |
+| `help/artifact-lifetime.md` | Whether to keep PRDs, specs, stories, and build records after the work is done, archiving, closing out an epic, keeping old plans from misleading agents. |
+| `help/monorepo-and-polyrepo.md` | Where to install BMad and keep planning when work spans one repository or several; the workspace layout for a poly repo. |
+| `help/working-in-an-organization.md` | A team or enterprise: an existing PRD, Jira or another tracker, approvals and sign-off, document owners, several engineers in parallel, requirements changing mid-flight. |
+| `help/ticketing-and-epics.md` | How `bmad-ticket` works (initiatives, epic inception, the breakdown, building from an entry, refining), plan status, review, and retrospective. |
+| `help/ticketing-setup.md` | Setting up and driving `bmad-ticket`: the store, several repos, trackers, the phrases to say, the hand-off to `bmad-build`. |
+| `help/unattended-builds.md` | `bmad-build-auto`, building stories with no human present, a blocked run and how to retry, what to check after a run. |
+| `help/review-choices.md` | Review depth, skipping review, another review pass, when to stop, slow reviews, customizing review. |
+| `help/project-context.md` | `bmad-project-context` in depth: what belongs in `AGENTS.md`, why the block is small, its intents, removing a rule. |
+
+## Start here
+
+- Can one session understand, build, review, and finish it?
+  - Obvious and low-risk (typo, formatting, config): just make the edit. No skill.
+  - Yes → `bmad-build`. No planning skill first.
+- Bigger than one session: does the user already have enough to say or paste (an idea they can explain in detail, notes, intent.md, single ticket, a transcript, a brief, a PRD)?
+  - Yes → `bmad-spec`, then `bmad-ticket` with the spec folder to plan the stories. Then one `bmad-build` per story.
+  - No → find what is missing, run the skill that supplies it, then `bmad-spec`:
+    - They cannot name a customer or a problem → `bmad-forge-idea` or `bmad-brainstorming` (core tools), if installed.
+    - Unsure the idea is worth building → `bmad-prfaq`.
+    - Sure of the idea, but it is not written down or not shareable → `bmad-product-brief`. It is also the lighter choice when a full PRD is more than the work needs.
+    - Requirements need real detail, or many stakeholders, compliance, or integrations are involved → `bmad-prd`.
+    - The look and feel matter, or the user thinks best in screens and flows → `bmad-ux`. Starting with UX is a normal way in.
+    - Separate people, agents, or sessions could build parts that do not fit together → `bmad-architecture`.
+- Wants to prototype first, or is unsure the work is worth doing, feasible, or how complex it is → encourage a prototype. It suits enterprise work as much as hobby work, greenfield or existing code, and non-engineers can build one. A throwaway needs no skill. Afterwards the user decides to throw it away or keep it, and either way what it taught them goes into `bmad-spec` (`help/prototyping.md`).
+- Risk, unclear requirements, architectural reach, or coordination between people push work up a tier even when it is small.
+
+## Match the situation
+
+Situations the tree above does not settle.
+
+| The user says or has | Recommend | Because |
+|---|---|---|
+| "I want to start from the design" | `bmad-ux` | UX may lead. Feed its files to `bmad-prd` when requirements still need drawing out, to `bmad-product-brief` for a lighter write-up, or straight to `bmad-spec` when they say enough. |
+| A prototype, and asks what now | Decide: throw away or keep | Thrown away, the notes go to `bmad-spec`. Kept, treat it as an existing codebase (`help/prototyping.md`). |
+| Work spans several repositories | Install BMad at a workspace root that holds them all, with planning kept there | One session then reaches the plan and every project (`help/monorepo-and-polyrepo.md`). |
+| "How do I get my repo ready for AI agents?", or agents keep producing inconsistent work | Consistent patterns, a good initial `AGENTS.md`, end-to-end tests, and cleanup first when quality is low | Agents copy what they find (`help/preparing-a-repo-for-agents.md`). |
+| "Do I keep the PRD, spec, and stories once it is built?" | Keep joined plans and their evidence | Plans own live ticket state; scope routine reads to the active initiative (`help/artifact-lifetime.md`). |
+| An inherited or brownfield codebase | A small `bmad-build` change first; `bmad-project-context` and `bmad-walkthrough` as needed | No up-front documentation pass is required (`help/existing-codebase.md`). |
+| "I don't know architecture, stacks, or hosting" | `bmad-architecture`, or the architect agent to talk it through | It coaches, recommends a current starter, and lays out options with reasons for the user to choose. Technical knowledge is not needed to start. |
+| "An app for X" and nothing more | `bmad-product-brief`, or `bmad-prd` when the stakes call for full requirements | `bmad-spec` distills and will not coach; the input is too thin for it. The brief is the lighter of the two. |
+| A PRD and architecture, several epics, wants tracking | `bmad-ticket` | One tree of epics, entries, and joined plans. |
+| A team with an existing PRD, a tracker, approvals, or several engineers | The full path only when approvers, parallel teams, or required documents call for it | The existing PRD is input, each document has one owner, and sign-off attaches to skill results (`help/working-in-an-organization.md`). |
+| "Can BMad build my stories by itself?" | `bmad-build-auto`, dispatched per story by a loop | It suits settled decisions and well specified stories, with someone reading the results. For work planned with `bmad-ticket`, give it the ticket, one run per ticket (`help/unattended-builds.md`). |
+| Wants tickets or a tracker (Jira, Linear, GitHub) as the record | `bmad-ticket` | Tickets are the board. The build moves a ticket's `status` in its plan as far as `built`, and the user marks it done. |
+| "Where are we?" | `bmad-ticket` status | Reads the ticket tree and joined plan statuses. |
+| A v6 project (`epics.md`, `sprint-status.yaml`, dated folders under the planning folder) that wants the v7 layout | `bmad migrate method` | The module ships `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. |
+| A PR, a branch, a ticket in review, or code `bmad-build` did not write | `bmad-code-review` | Agent lenses over any diff. With no argument it offers the tickets in review. |
+| "Walk me through what changed" | `bmad-walkthrough` | The human is the reviewer. |
+| Every ticket of an epic is built, done, or dropped | `bmad-retrospective` | It judges the whole against the epic's Done when and the initiative's requirements. |
+| A big change surfaced mid-build | A spec-only change: update through `bmad-spec`. Otherwise `bmad-correct-course`. | Correct course needs a PRD or a spec and halts when it has neither. The user describes the affected epics and stories. |
+| Wants an expert to think a phase through with, or is unsure where to begin in it | The agent for that phase (see "The agents") | It guides across turns and runs the phase's skills from its menu. |
+| Agents keep making the same mistake in this repo | `bmad-project-context` | It records the rule in `AGENTS.md`. |
+
+## The skills
+
+One line per skill: what it is for and what it writes. The files it writes are how to tell what is already done. 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`. When none is active, `bmad-product-brief`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, `bmad-spec`, and `bmad-correct-course` hand off to the `bmad` skill to set one; `bmad-brainstorming`, `bmad-deep-recon`, `bmad-forge-idea`, `bmad-prfaq`, `bmad-party-mode`, and `bmad-build` ask once per session whether the work belongs to one; the rest write to `{output_folder}/`. Showing, switching, creating, or clearing the active initiative is a `bmad` request. `planning_artifacts` and `implementation_artifacts` are no longer read; a v6 project moves its files with `bmad migrate method`. Open the phase file for the full picture of a skill: what it gives, when to pick it, when not to.
+
+| Skill | For | Writes |
+|---|---|---|
+| **Analysis** (`help/analysis-skills.md`) | | |
+| `bmad-product-brief` | A 1-2 page brief of a product the user believes in. Lighter than a PRD, sharper than a hand-written intent file. It does not judge the idea. | `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-spec` | The hub. Distills any input into the contract builds read, and updates it. It does not slice or coach; splitting work into stories is `bmad-ticket`. | `spec-<slug>/spec-<slug>.md` and companions |
+| `bmad-prd` | Coaches detailed requirements out of the user, sized to the stakes. Also updates and validates a PRD. | `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` |
+| `bmad-ticket` | Plans initiatives, epics, and stories as a ticket tree and runs it as a board: ready, next, blocked, done. Stories are entries in `tickets.toml`; a file is written only when one is reviewed, refined, or published. Bugs go to `backlog/`. Optional tracker. | The ticket tree under `{output_folder}/{active_initiative}/`, plus `{output_folder}/backlog/` |
+| **Implementation** (`help/implementation-skills.md`) | | |
+| `bmad-build` | One session of delivery: clarifies intent, plans, implements, reviews, commits. The default for any real change. Takes free text, a ticket from the tree (nothing means the next ready one), or any file as intent. | 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` |
+| `bmad-correct-course` | Assesses a significant midstream change. Needs a PRD or a spec; lists epic and story changes for `bmad-ticket`. | `change-<slug>/change-<slug>.md` |
+| **Validation** (`help/validation-skills.md`) | | |
+| `bmad-code-review` | Agent review of any diff, PR, or branch, with triaged findings. 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 |
+| **Any time** (`help/project-context.md`) | | |
+| `bmad-project-context` | Keeps a small, verified block of rules for agents. Use it when an agent got something wrong in this repo, a repo has no usable `AGENTS.md`, or the stack was just decided. It gives no repo overview. | `{project-root}/AGENTS.md` |
+
+### Slicing and tracking the work
+
+`bmad-ticket` 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`.
+
+### 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
+
+Five named experts, each owning a phase and staying in the conversation across turns. An agent carries its role's judgment, offers a menu of the skills it owns, and helps the user decide what to do and why before and between skill runs. Offer one whenever the user wants an expert to work with rather than a single skill to run, is unsure where to begin in a phase, or likes the experience of interacting with unique personas. In the future these agents will have the ability to retain memory and work autonomously which is why they are still a core part of the project.
+
+| Agent | Phase | Work with them to |
+|---|---|---|
+| Mary, analyst — `bmad-agent-analyst` | Analysis | Brainstorm, research a market, domain, technology, or competitor, then shape a brief or a PRFAQ. |
+| John, product manager — `bmad-agent-pm` | Planning | Turn a vision into a PRD, epics and stories, check readiness, and handle a midstream change. |
+| Sally, UX designer — `bmad-agent-ux-designer` | Planning | Work out how the product looks and behaves. |
+| Winston, architect — `bmad-agent-architect` | Planning | Settle the technical decisions that keep the parts consistent, and check readiness. |
+| Amelia, developer — `bmad-agent-dev` | Implementation and validation | Build stories, generate tests, review code, manage the ticket board, and run a retrospective. |
+
+An agent and its skills are two ways into the same work: a skill run directly does the job, and an agent adds a guide who knows the whole phase. `bmad-party-mode` brings the agents together in one discussion and offers the `product-team` room.
+
+## After a skill finishes
+
+| Just finished | Offer next |
+|---|---|
+| `bmad-product-brief`, `bmad-prfaq` | `bmad-spec` with the result as input. `bmad-prd` first when the requirements still need drawing out. After a PRFAQ verdict with serious gaps, address those before anything else. |
+| `bmad-prd` | `bmad-spec` to absorb it. `bmad-ux` when the UI matters; `bmad-architecture` when parts must fit together. |
+| `bmad-ux` | `bmad-spec` to adopt the files as companions. When UX came first and requirements are still thin, `bmad-prd` or the lighter `bmad-product-brief` with the UX files as input. |
+| `bmad-architecture` | `bmad-spec` to adopt the spine as a companion. |
+| `bmad-spec` | Its open questions and assumptions, if any. Then `bmad-ticket` with the spec folder to plan the stories, and `bmad-build` per story, or straight to `bmad-build` when one session can do it. |
+| `bmad-build` | Open a PR, or `bmad-walkthrough` when a person wants to understand the change. Once the user marks the ticket done, the next ticket. `bmad-qa-generate-e2e-tests` when end-to-end coverage is wanted. |
+| The last ticket of an epic | `bmad-retrospective`, then a refactoring pass over the whole changeset, which is commonly skipped (`help/preparing-a-repo-for-agents.md`). Then close the epic through `bmad-ticket` and retain its plans (`help/artifact-lifetime.md`). |
+
+## Answering "what's next?"
+
+Read the state before recommending: which of the outputs named above exist, and what the codebase, git history, and the user say is done. A file's presence, or a plan with `status: done`, is evidence the skill ran, not proof the work is finished or current.
+
+- Mid-path, recommend the next unfinished step of the route the user is on, not a restart, and migrate legacy artifacts before resuming them.
+- When a significant change surfaces, route it as the table in "Match the situation" says, then resume at the earliest affected step. Do not replay unaffected work.
+- The work is complete when the intent is satisfied, its chosen checks pass, and no chosen review leaves material findings open — not when every skill has run.
+
+## When this document is not enough
+
+For a `method` question this document, its topic files, and the installed skills cannot answer, fetch the documentation site at `https://docs.bmad-method.org/` and follow the pages relevant to the question. The source repository it links to is the final authority on how anything actually behaves.

.agents/skills/bmod-method/help/implementation-skills.md

@@ -0,0 +1,23 @@
+# Implementation skills in detail
+
+Read this when the question is about `bmad-build`, `bmad-build-auto`, or `bmad-correct-course`. For running stories without a human, see `help/unattended-builds.md`.
+
+**`bmad-build`** — one session of delivery: clarifies intent, plans, implements, reviews, and presents a commit.
+- Takes: free text however brief; a 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.
+- 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`.
+
+**`bmad-correct-course`** — assesses a significant midstream change.
+- Gives: a change proposal covering impact across PRD, epics, architecture, and UX; a recommended path (adjust, roll back, or cut scope); and proposed edits. It drafts the edits to the PRD, architecture, UX, and stories and does not apply them: the user applies those through the owning skills. Its handoff lists the added, removed, resequenced, or rescoped epics and stories for the user to apply with `bmad-ticket`.
+- Pick when: a ticket exposes something that reaches across artifacts, such as a technical limit, a new or misread requirement, a pivot, or a failed approach.
+- Not when: there is neither a PRD nor a spec (it halts). A change that touches only the spec → update it with `bmad-spec`. A change that only re-slices tickets → `bmad-ticket`.
+- Reads: the PRD or spec, plus architecture and UX when present. It reads no epics file or ticket tree; the user describes the affected epics and stories.
+- Writes: `{output_folder}/{active_initiative}/change-<slug>/change-<slug>.md`.

.agents/skills/bmod-method/help/monorepo-and-polyrepo.md

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

.agents/skills/bmod-method/help/planning-skills.md

@@ -0,0 +1,38 @@
+# Planning skills in detail
+
+Read this when the question is about `bmad-spec`, `bmad-prd`, `bmad-ux`, `bmad-architecture`, or the skills that slice and track work: what each gives, when to pick it, when not to, and what it writes.
+
+**`bmad-spec`** — the hub. Condenses any input into the contract builds read.
+- Gives: a spec folder with `spec-<slug>.md` (why, capabilities with stable ids, constraints, non-goals, success signal) and companions. It adopts UX files and an architecture spine as companions and absorbs a PRD or brief as a source. On request it hands the spec folder to `bmad-ticket` to be planned into stories. It also updates and validates an existing spec.
+- Pick when: the user has anything to distill, or can explain the idea in detail; after any other analysis or planning skill finishes; when requirements change on the spec route (it appends to its log, re-derives the spec, and names the tickets that no longer match).
+- Not when: the input is a bare idea. It distills and does not coach → `bmad-product-brief` first, or `bmad-prd` when full requirements are needed.
+- Splitting into stories is not this skill: send the user to `bmad-ticket` with the spec folder, which plans one epic whose stories cite the spec's `CAP-N` ids. After writing a spec that reads as several slices, `bmad-spec` offers that hand-off once.
+- Writes: `{output_folder}/{active_initiative}/spec-<slug>/` holding `spec-<slug>.md` and companions, or `spec-<slug>/` inside the epic folder when the spec is for an epic.
+
+**`bmad-prd`** — coaches detailed requirements out of the user.
+- Gives: a PRD sized to the stakes (about 2 pages for a hobby project, longer for a launch): features, requirements with stable ids, user journeys, non-goals, MVP scope, metrics. Fast path or coaching path. Also updates and validates an existing PRD.
+- Pick when: the idea is too thin for `bmad-spec`; a consumer or multi-stakeholder product; compliance, integration, or SLA concerns; an existing PRD needs editing or critique.
+- Not when: scope is one or two stories → `bmad-build`. A lighter document will do → `bmad-product-brief`, then `bmad-spec`. A brief is an optional input, never a prerequisite.
+- Writes: `{output_folder}/{active_initiative}/prd-<slug>/prd-<slug>.md`.
+
+**`bmad-ux`** — captures how the product looks and how it works. It may lead, follow, or stand alone.
+- Gives: `DESIGN.md` (visual tokens and rules) and `EXPERIENCE.md` (structure, states, interactions, accessibility, key flows), optionally mockups and wireframes. It captures the user's vision and never imposes one. A design-handoff mode builds a prompt for an external design tool.
+- Pick when: the UI is a significant part of the work; the user wants to design first and derive requirements from the design; the user has design assets to fold in; design will happen in an outside tool but a contract is still needed.
+- Not when: there is no meaningful UI.
+- UX first: its files are good input to `bmad-prd` when requirements still need drawing out, to `bmad-product-brief` when a lighter write-up will do, or straight to `bmad-spec` when the design already says enough.
+- In the spec: both files are adopted as companions. Change them with `bmad-ux` update, not through the spec.
+- Writes: `{output_folder}/{active_initiative}/ux-<slug>/`: `DESIGN.md`, `EXPERIENCE.md`, and `ux-<slug>.md` naming them.
+
+**`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, and can start from a spec, a raw idea, an existing codebase, or a sprawling document to distill.
+- Pick when: two units built independently could choose incompatibly; an initiative has been cut into epics and more than one epic must adopt the same contract, format, or value list; the stack is open; the user does not know what stack, starter, or hosting to choose; a brownfield codebase has conventions worth ratifying; a feature touches an existing system.
+- Not when: the input is too thin → `bmad-spec` first. One session builds all of it → skip.
+- Next: it offers to have `bmad-spec` adopt the spine as a companion. Recommend that first.
+- Writes: `{output_folder}/{active_initiative}/architecture-<slug>/architecture-<slug>.md`.
+
+## Slicing and tracking the work
+
+`bmad-ticket` 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`.
+
+**`bmad-ticket`** — slices initiatives into epics, incepts each epic into entries, refines when needed, and manages the board and optional tracker publishing. A spec, 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.

.agents/skills/bmod-method/help/preparing-a-repo-for-agents.md

@@ -0,0 +1,31 @@
+# Preparing and keeping a repository fit for agents
+
+Use this when the user asks how to get an existing codebase ready for agentic coding, why agents produce inconsistent work in their repo, how much documentation to keep, or how to hold quality over time. For the order of skills on an existing codebase, see `help/existing-codebase.md`.
+
+## What makes a repository work well with agents
+
+- **Consistency.** An agent copies the patterns it finds. When the project does the same thing several different ways, the agent cannot be consistent either, and each session may pick a different way.
+- **A good initial `AGENTS.md`.** A short, verified set of rules is worth having from the start: the policies, commands, and conventions the code cannot show. `bmad-project-context` sets it up and keeps it small.
+- **Good end-to-end tests.** They let an agent change code and know it still works, and they make refactoring safe. `bmad-qa-generate-e2e-tests` adds them for features that already exist.
+- **Clean structure.** Very large files and tangled modules cost every session tokens and accuracy.
+
+## Improve before building, when quality is low
+
+If the codebase is inconsistent or untested, some refactoring and test work first goes a long way, and it pays back in every later session. Agents can help assess the code and carry out the improvements: ask for an assessment of inconsistent patterns, then make each cleanup its own `bmad-build` change with tests in place first. A skill dedicated to this is planned. A codebase of decent quality needs none of this: start with a small change.
+
+## Documentation: keep it small
+
+Earlier BMad guidance produced heavy documentation of a codebase. That is no longer suggested. Those documents were bloated, hard to maintain, and went stale quickly. A new documentation skill for codebases is planned.
+
+- The code is the best documentation for an agent. During coding, an agent should need few documents.
+- Documents should hold only what the code cannot explain: why a decision was made, a constraint from outside the code, a rule that spans components.
+- Recommend small numbered decision records (ADRs), written consistently, only for what is needed, in the repository's `docs` folder or similar.
+- `AGENTS.md` should make agents aware the records exist and when to consult them, without copying their content.
+
+## Refactor regularly
+
+After several stories, at the end of an epic, and every so often otherwise, do a refactoring pass toward cleaner code. This step is commonly skipped, and agent-built code drifts without it: duplication, near-copies of helpers, and patterns that diverged between sessions.
+
+- The end of an epic is a good moment because the whole changeset can be looked at together. `bmad-retrospective` reports duplication and drift across the epic's stories, and its findings are a ready list of refactoring work.
+- Run each refactoring as its own `bmad-build` change, separate from feature work.
+- Refactoring is safest with a good test suite in place. Without one, add tests first.

.agents/skills/bmod-method/help/project-context.md

@@ -0,0 +1,51 @@
+# 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.

.agents/skills/bmod-method/help/prototyping.md

@@ -0,0 +1,44 @@
+# Prototyping with the method
+
+Prototypes are underused, in hobby work and in the enterprise alike. Recommend one readily. The method has no prototype phase and needs none: a prototype is a fast, cheap way to learn, and what it teaches is some of the best input `bmad-spec` can get. Current models can produce an impressive first version from one prompt.
+
+## What a prototype is good for
+
+- **Is it worth doing?** Putting something real in front of users or stakeholders gets feedback within days, without the overhead of planning first.
+- **Is it feasible?** It proves out a risky technique, integration, or performance question before anyone commits to it.
+- **How complex is it really?** Building a slice shows where the effort is.
+- **What don't we know?** Unknowns surface when something runs. They rarely surface in a document.
+- **Was the idea any good?** Finding out that a good-sounding idea is a bad one is a successful prototype. It saved the cost of building it.
+
+## Who can prototype
+
+Anyone, not only engineers. A product manager, designer, product owner, or analyst can mock up or prove out an idea with an agent and bring the result to the team. When a non-engineer asks whether they can, the answer is yes, and a throwaway prototype needs no setup or planning skill first.
+
+## Greenfield and existing codebases
+
+Both work. In an existing codebase, a prototype on a branch shows how a change sits against the real system and what it touches. Treat it as a throwaway unless the team decides otherwise: prototype code written to learn fast seldom meets the codebase's standards.
+
+## Ways to prototype
+
+| The user wants | Recommend | Because |
+|---|---|---|
+| Something running fast, expected to be thrown away | Prompt it directly, no skill | For a throwaway, the smallest path is no path. |
+| A fast first version with a plan to approve, a review, and a commit | `bmad-build` with a one-line prompt | It accepts free text however brief. In an existing codebase it investigates the code first, so the prototype fits what is there. |
+| To see the screens and flows before any code | `bmad-ux` | It can produce HTML mocks of key screens and Excalidraw wireframes alongside its two design files. |
+| A technical unknown answered from outside sources instead of by building | `bmad-deep-recon` (core tools), if installed | Some feasibility questions are research, not code. |
+
+## After the prototype: throw it away or keep it
+
+Ask the user to decide this on purpose. The outcome to avoid is a prototype that becomes the real product with nobody deciding it should, and with no spec.
+
+- **Throw it away.** The prototype was research. Have the user note what it taught them: what worked, what surprised them, what users said, what they would do differently. Feed those notes, and the prototype itself if useful, to `bmad-spec`, or to `bmad-product-brief` first when the picture is still loose. Then build cleanly, one story at a time. This is the usual choice in an enterprise codebase and whenever a non-engineer built the prototype.
+- **Keep it.** Treat it as an existing codebase (see `help/existing-codebase.md`): `bmad-project-context` to record the rules agents must follow, `bmad-architecture` to ratify the decisions worth keeping and name what is still open, then `bmad-spec` for the rest of the work.
+- **Drop the idea.** The prototype showed it is not worth doing. Nothing more is needed.
+
+## Why plan at all after a good prototype
+
+A first version is rarely where a project goes wrong. Trouble starts several sessions later, when each new session does not know why earlier choices were made and the parts stop fitting together. The spec and the architecture decisions exist to prevent that. For work that one or two sessions will finish, the prototype may be all the user needs.
+
+## A prototype and the analysis skills
+
+A prototype answers questions by building. `bmad-prfaq` answers them by arguing the concept and researching the market claims. They complement each other: a prototype shows whether people want the thing and whether it can be built, and the PRFAQ tests whether the business case holds. When the stakes are high, the prototype's findings make the PRFAQ, the brief, or the PRD sharper.

.agents/skills/bmod-method/help/review-choices.md

@@ -0,0 +1,54 @@
+# 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 plan, a spec, or a plain description. A ticket in review brings its plan. 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, or on someone else's PR. It walks the change in blocks, intent first, and stays on a block until the user says it is done. It gives no severity and no verdict. Moves the user can pick:
+
+- **Thoughts**: the agent's own read. **Second opinion**: a fresh subagent's read.
+- **Formal review**: runs `bmad-code-review` when installed.
+- **Test**: helps test the part. **Drive**: starts the app and says what to click.
+- **Wrap-up**: proposes the follow-through, such as merging, and waits for a yes.
+
+For specs and docs, `bmad-review` (core tools), if installed, reports findings and fixes nothing.
+
+## What `bmad-customize` can change
+
+- The default depth, separately for `bmad-build`, `bmad-build-auto`, and `bmad-code-review`.
+- The lenses: add, replace, disable, or run one on another model.
+- `bmad-walkthrough`: instructions at start, per block, and at wrap-up.

.agents/skills/bmod-method/help/ticketing-and-epics.md

@@ -0,0 +1,7 @@
+# The ticket tree
+
+`bmad-ticket` 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.
+
+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.

.agents/skills/bmod-method/help/ticketing-setup.md

@@ -0,0 +1,48 @@
+# Setting up and using bmad-ticket
+
+Use this when a user asks how to set up or drive `bmad-ticket`. 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, the skill 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. The best input is a `bmad-spec` output with its source documents. `bmad-spec` offers to hand its spec folder to this skill, which does the story breakdown; the stories cite the spec's `CAP-N` ids.
+
+## Trackers
+
+- 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. The skill checks the needed CLI or connection at setup.
+- Repo is the most tested. The trackers are lightly tested.
+- With a tracker, the markdown files stay the working copy. Nothing syncs on its own: files and tracker line up only when the user runs the skill. The skill never pushes.
+
+## What the user says
+
+| Say | Result |
+|---|---|
+| "Split this initiative into epics" | Proposes epic boundaries and records the agreed order in the initiative's `tickets.toml`. |
+| "Incept the first epic" | Plans the whole epic into entries in the epic's `tickets.toml`, in build order, each with an `id` that names it under the epic. No story file is written. |
+| "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 at inception; with `publication = "on_start"`, each ticket publishes when it starts. On the repo store, committing the approved `tickets.toml` is the publish. |
+
+## 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 and its epic, plus the story file when there is one, and plans the story's acceptance criteria from the epic's Requirements and Done when, the entry's description, and its `Verify:` check.
+- A story needs no refining before `bmad-build`; the build refines it. Before an unattended run, review the stories with this skill. A bug, a ticket with no epic, and an entry the user marked `refine = true` get full criteria first; "what's next?" lists these under ready to refine.
+- 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-ticket" in the title, or post in the BMad Discord. Useful reports say what was given, asked, produced, and expected.

.agents/skills/bmod-method/help/unattended-builds.md

@@ -0,0 +1,65 @@
+# 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 move it through `bmad-ticket`.
+
+## 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.

.agents/skills/bmod-method/help/validation-skills.md

@@ -0,0 +1,31 @@
+# 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 and diffs from the chosen 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, 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, and nothing else. It marks nothing done.

.agents/skills/bmod-method/help/working-in-an-organization.md

@@ -0,0 +1,64 @@
+# Working in an organization
+
+Use this when the work belongs to a team or enterprise: a PRD already exists, a tracker such as Jira is the record, people must approve, several engineers build in parallel, or requirements change mid-flight.
+
+## When the full path is warranted
+
+A single builder, or a small team that already agrees, goes straight to `bmad-spec` and needs no PRD. Recommend the full path (PRD, architecture, one spec per epic, tracking) only when one of these is true:
+
+- People who did not do the thinking must approve what the product is.
+- Several epics, teams, or agents build against the same decisions and must not diverge.
+- A regulator, steering committee, or company process requires named documents.
+
+Before any of this, a product manager, designer, or analyst can prototype the idea (`help/prototyping.md`).
+
+## An existing PRD is input
+
+- Point `bmad-prd` at the existing PRD. Validate gives a findings report and changes nothing. Create rewrites the same requirements in the shape later skills read, with `[ASSUMPTION]` tags on what it filled in.
+- When the source PRD changes, run `bmad-prd` update. Tell the user never to hand-edit `prd-<slug>.md`.
+- `bmad-ux` and `bmad-architecture` start from the existing design system, architecture document, or codebase.
+
+## One owner per document
+
+Each document has one skill that writes it, so give it one owner. One person can hold several roles.
+
+| Role | Runs | Owns |
+|---|---|---|
+| Product manager | `bmad-prd` | `prd-<slug>.md` and its updates |
+| Designer | `bmad-ux` | `DESIGN.md`, `EXPERIENCE.md` |
+| Tech lead | `bmad-architecture` | The architecture spine |
+| One engineer per epic | `bmad-spec`, `bmad-build`, `bmad-retrospective` | That epic's spec, stories, verdict |
+| Whoever tracks the whole | `bmad-ticket` | the ticket tree |
+
+Several engineers can each take an epic at once. An epic-level spine inherits the parent spine's decisions as binding.
+
+## Where sign-off happens
+
+Each moment produces a written result an approval can attach to. Advise placing existing approvals here.
+
+| Moment | What it holds back |
+|---|---|
+| `bmad-prfaq` verdict | Writing the PRD |
+| `bmad-prd` validate | Design and architecture work |
+| Architecture spine review | Writing epic specs |
+| `bmad-ticket` 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. `bmad-prd` update. It surfaces conflicts with earlier decisions before applying anything.
+2. `bmad-architecture` update when a decision shared across epics changes.
+3. `bmad-spec` for each affected epic. Capability ids stay stable, and it says which stories no longer match.
+4. Story breakdown or `bmad-ticket` again. Existing plans retain status.
+
+For a change that threatens the plan itself, run `bmad-correct-course` first. It needs a PRD or a spec.
+
+## 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`.
+- `bmad-ticket` can publish tickets to Jira, Linear, or GitHub. When the skill 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`).