From eb814698b659b399e79f285a083d792f112e90dc Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 12:07:18 -0700 Subject: [PATCH] docs: audit the docs and README against v7 and add the upgrade-from-v6 page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every page under docs/start, docs/plan, docs/build, docs/customize, docs/existing-codebases, and docs/reference, plus README.md, the style guide, and the diagrams, checked claim by claim against the skills, their help, and the CHANGELOG. Each section below is one audit, with its finding list: Fix for a false claim, Left for a true one and why it stays. Source conflict lines record contradictions inside the skills and help, which this change does not edit. ## docs: drop retired names from the skills reference Those skill ids no longer ship, the technical writer is not on hiatus, and bmad setup offers to delete skills a module no longer ships. ## docs: keep manual cleanup advice for skills of a removed module ## docs: audit the start pages and README against v7 ### docs/start/install-bmad.md - Fix — the module records listed only `bmod-core-tools` and `bmod-method`; `bmod-toolsmith` now ships from this repository (bmod.toml, CHANGELOG Unreleased), so the sentence names all three. - Left — prerequisites (uv required per core-tools pre_install_message and setup.md; Node.js, npm, Git for the Skills CLI) are true. - Left — the by-name install example names only shipped skills (`bmad`, `bmod-core-tools`, `bmod-method`, `bmad-build`, `bmad-ticket`). - Left — plugin marketplace names and plugins live in the external bmad-plugins repository; nothing here contradicts them. - Left — Set Up and Verify: setup writes the shared and module scripts under `_bmad/`, `bmad status` reports versions, output goes to `_bmad-output` (config.template.toml) inside the active initiative, and `bmad` creates or switches it (core-tools help, SKILL.md). - Left — Update: version check and `npx skills update`, new config questions, `_bmad/custom/` moves for renamed skills, offers to delete retired skills, then the migration check, all match references/setup.md and CHANGELOG; plugin-managed modules update through the marketplace, as setup.md relays. - Left — What You Get: `_bmad/custom/` customizations surviving setup matches setup.md ("never changes an existing value"). ### docs/start/get-answers-about-bmad.md - Left — `bmad` reads the active initiative and the `-/` folders (references/help.md step 1). - Left — the tip's `bmad setup`, `bmad status`, `bmad migrate method`, and initiative switching are all `bmad` actions (SKILL.md). - Left — the `bmad-build` example (intent, issue, spec, or planned story) matches method help ("free text, a ticket from the tree, or any file as intent"). - Left — "over 80% of questions", the Discord channels, and the poem are not claims the sources speak to. ### docs/start/build-your-first-change.md - Fix — Before You Start omitted uv, which `bmad setup` requires (setup.md; core-tools pre_install_message), so the tutorial's setup step would fail; it now lists uv. - Left — the install, `bmad setup`, and `bmad-build` flow, the plan approval, and the hedge that questions and plan may differ match bmad-build's routes. - Left — `/bmad Explain what bmad-build just did.` is a help request the `bmad` skill answers. - Left — all links resolve (link validation passes); no headings changed. ### README.md - Fix — the module records listed only `bmod-method` and `bmod-core-tools`; it now adds `bmod-toolsmith`. - Fix — the ecosystem row named BMad Builder, which is retired; it is now Toolsmith (`bmod-toolsmith`: agent `bmad-toolsmith`, skill `bmad-eval`), "Build, convert, and evaluate skills, agents, and modules". Link target: the docs site page https://docs.bmad-method.org/toolsmith/toolsmith/, built from `docs/toolsmith/toolsmith.md` and in the sidebar, because Toolsmith ships from this repository and has no repository of its own; that page also says how it installs. - Left — `bmad status` and `bmad setup` as the update path (runs `npx skills update`, refreshes, cleans up renamed and removed skills) match setup.md and CHANGELOG; marketplace then `bmad setup` matches the plugin-managed case. - Left — install commands, the plugin marketplace text, the docs links, and the other ecosystem rows (external repositories) are not contradicted by the sources. ### docs/_STYLE_GUIDE.md - Fix — the Deep-Dive example `document-project.md` named a v6 workflow that no v7 skill provides; the example is now `bmad-eval.md`, an existing single-skill deep dive in `docs/toolsmith/`. - Fix — the context marker `*BMad Method/Enterprise.*` named the v6 Enterprise planning track, which v7 does not have (method help sizes work by project size and stakes); the marker is now `*BMad Method.*`. - Left — the skills table example (`bmad-brainstorming` via the Analyst's BP item, `bmad-prd` via the PM) is true. - Left — the folder-structure block (`_bmad-output/initiative-/prd-/prd-.md`, `AGENTS.md` via `bmad-project-context`) matches the v7 layout. - Left — the FAQ example's `bmad-correct-course` ships; `*Phase N.*` matches the four phases in method help; `*BMGD.*` names a current external module. - Left — the diagram paths (`docs-site/src/diagrams/`, `/diagrams/build-run.svg`, `docs/images/`) and the npm scripts (`export-readme-diagrams`, `fix-links`, `validate-links`, `build`) exist. - Left — the other example filenames (`core-concepts/index.md`, `what-are-agents.md`, `build.md`, `workflows/index.md`, `agents/index.md`, `core-tasks.md`, `glossary/index.md`, `bmgd-workflows.md`) are illustrative and name no skill, setting, or command. ### docs/404.md - Left — the link to `./index.md` resolves and the page names nothing versioned. ## docs: add the upgrade-from-v6 page - docs/start/upgrade-from-v6.md: new how-to covering skills install, bmad setup, bmad migrate method, and the v6-facing breaking changes. - docs-site/astro.config.mjs: add the Upgrade from v6 item to the Start sidebar after Install BMad. - docs/start/install-bmad.md: link the new page from the update section. - docs/start/build-your-first-change.md: link the new page for repositories already on v6. - docs/start/get-answers-about-bmad.md: link the new page from the tip that names bmad migrate method. Decision: this page is the one page in the epic allowed to name v6-era names (retired skills, old settings, the old installer) because it exists to say what replaced them. Every such name appears once, in a sentence that names its replacement or removal, and never as a current thing. ## docs: audit the choose-a-planning-path page and its diagrams against v7 ### docs/plan/choose-a-planning-path.md - Fix — "You need a PRD when more than one person must agree ... or more than one epic must not diverge; otherwise skip it" told a solo user with detailed, compliance, or integration requirements to skip the PRD, which help routes to `bmad-prd` (help.md Start here; planning-skills.md); the sentence now adds those conditions. - Fix — "The table runs from analysis through planning to solutioning" named a phase the method does not have: help's phases are analysis, planning, implementation, and validation, with `bmad-architecture` and `bmad-ticket` under planning (help.md skills and agents tables); it now runs "from analysis through planning". - Fix — documents with no active initiative were said to land in the output folder; `bmad-product-brief`, `bmad-prd`, `bmad-ux`, `bmad-spec`, and `bmad-architecture` have the user set one first and `bmad-ticket` offers to create one (each SKILL.md; help.md The skills), so the sentence now says so and keeps the output-folder case for the four skills that ask whether the work belongs to one. - Fix — the planning-skills alt text named a solutioning column; it now names the third column "planning how and in what slices", matching the diagram. - Left — intro and Start from the Intent: a well-defined intent goes to `bmad-spec`, one-session specs go to `bmad-build`, epic-sized ones to `bmad-ticket` then a Build per story, and the spec distills without coaching (help.md hub and Start here; bmad-spec SKILL.md). The input-size ceiling is not contradicted by any source. - Left — the gap table and "independent tools, not stages ... in any order" match help ("they can run in any order"); the PRFAQ under a written account for a pitch is not false (it writes a press release and FAQ). - Left — "A multi-epic product runs `bmad-spec` once per epic" matches the ticket tree's per-epic spec folders (bmad-ticket SKILL.md). - Left — every Produces cell matches its skill: `brainstorm-.md` and `brainstorm.html` (customize `output_folder_name = "brainstorm-{topic_slug}"`, finalize.md; the keepsake is the recommended default artifact), `forge-report.html` every run and `forge-.md` when hardened, cited `research-.md` with an optional briefing (`output_format`), `brief-.md` + `addendum.md`, `prfaq-.md` + `-distillate.md` (verdict.md), `prd-.md`, `addendum.md`, `.memlog.md` and `validation-report.html`/`.md`, `DESIGN.md`, `EXPERIENCE.md`, `ux-.md`, `.memlog.md`, `spec-.md` + companions, `architecture-.md` (`run_folder_pattern`), and epic envelopes, `tickets.toml`, and leaf files written only when pulled. - Left — `bmad-prd`'s three intents and asking when unclear, and the brief feeding the PRD with neither required (bmad-prd SKILL.md; planning-skills.md "never a prerequisite"). - Left — Size Follows the Intent: the escalation signals match help ("Risk, unclear requirements, architectural reach, or coordination ... push work up a tier"); the 20-session figure is not contradicted. - Left — Start Epic-Sized Work: spec, then `bmad-ticket` recording stories in build order in `tickets.toml`, building from the entry with no story file, refining for `refine = true` or a ticket with no epic, plans beside `tickets.toml` stopping at `built` until marked done, and `bmad-build-auto` one run per story (bmad-ticket SKILL.md; help.md). - Left — Finish the epic: `bmad-retrospective` takes an epic folder, id, or slug, reads entries and plans, and judges against Done when and the initiative's requirements (bmad-retrospective workflow.md). - Left — Start Project-Sized Work, After Decisions Stabilize, and What You Get match help's smallest-safe-path rule and `bmad-build-auto` as a per-ticket unattended run. - Left — headings unchanged; `#1-start-epic-sized-work` and `#planning-skills-and-what-they-produce` are the only anchors other pages link to. Source conflict: skills/bmad-agent-architect/customize.toml — its role places the architect in "the BMad Method solutioning phase"; help.md lists the architect's phase as Planning and names no solutioning phase. Source conflict: skills/bmod-method/help/help.md — says skills outside its two lists write to `{output_folder}/` when no initiative is active; skills/bmad-ticket/SKILL.md instead offers to create an initiative or backlog folder and records it as `active_initiative`. Source conflict: skills/bmad-prd/SKILL.md — its misroute scan suggests `bmad-workflow-builder` from the BMad Builder module, which skills/bmod-toolsmith/retired.toml lists as removed. ### docs-site/src/diagrams/planning-skills.svg - Fix — the third column was headed SOLUTIONING, a phase help does not have (architecture and ticket are planning skills in help.md); it is now headed PLANNING, keeping its subtitle "decide how, divide the work", and the description names it "Planning how and in what slices" and the second column "Planning what to build". - Left — every artifact label matches its skill, as verified for the page table: `brainstorm-.md, brainstorm.html`; `forge-.md, forge-report.html`; `research-.md`, optional HTML briefing; `brief-.md, addendum.md`; `prfaq-/` (the run folder, which exists); `prd-.md, addendum.md, .memlog.md` and the validate HTML + `.md` report; `ux-.md, DESIGN.md, EXPERIENCE.md`; `spec-.md` + companions with the `bmad-ticket` handoff; `architecture-.md`; ordered `tickets.toml` entries. - Left — the subtitle (any order, `-/` folder in the active initiative, hand results to `bmad-spec`) matches help's hub description. - Left — the column arrows and the hand-off arrows into `bmad-build`: forge-idea offers its forged idea to `bmad-build` directly (bmad-forge-idea SKILL.md Exits), and spec and ticket hand off to Build per help; the Build box's "one session per unit · built → user marks done · keep plans" matches help. - Left — the planning-column note "One session of work goes straight from the spec to Build" matches help's after-`bmad-spec` row. - Left — geometry, classes, and the existing `var(--dg-*)` usage are unchanged; the file still parses (xmllint) and no README exports it. ### docs-site/src/diagrams/development-paths.svg - Left — Trivial (Change, Edit, Verify) matches "Obvious and low-risk: just make the edit. No skill." - Left — One Session (Intent, Build with plan · build · review, Result) matches `bmad-build` clarifying, planning, implementing, and reviewing in one session. - Left — Epic-Sized (Intent, Spec, Stories, Build × stories, Integrate → retrospect) matches `bmad-spec`, `bmad-ticket`, one `bmad-build` per story, then `bmad-retrospective` judging the whole. - Left — Project-Sized (shared contracts product · UX · tech, then the epic path per epic) matches the page's PRD, UX, and architecture as shared documents with one spec per epic; "roughly 20+ sessions" matches the page. - Left — the page's alt text still describes the diagram; nothing changed. ## docs: audit the idea, research, requirements, and design pages against v7 ### docs/plan/explore-and-validate-an-idea.md - Fix — brainstorming said it aims past a hundred ideas "before it lets you wrap"; the skill ends when the user is spent or the topic is mined out (SKILL.md framing), so it now says it aims past a hundred ideas and resists an early wrap-up. - Fix — "You get an HTML record ... and a short `brainstorm-.md`" presented both as given; every artifact is opt-in in Facilitator and Creative Partner, and only Ideate for me makes the HTML keepsake without asking (references/finalize.md), so it now says it offers them at wrap-up. - Left — the situation table names only shipped skills (`bmad-brainstorming`, `bmad-forge-idea`, `bmad-deep-recon`, `bmad-party-mode`) and routes the brief and PRFAQ as method help does. - Left — the three brainstorming stances, technique batch or let-it-choose, converge on request, and pause and resume match bmad-brainstorming SKILL.md; the intent doc feeding brief, PRD, or spec matches finalize.md. - Left — the "Pressure-Test an Idea with Forge Idea" heading (linked from docs/reference/skills-and-agents.md) and its content: the three session goals, one question at a time with a proposed answer, fuzzy terms, project files as source of truth, attack/defend/switch roles, two voices per turn, name a persona or go one-on-one, all match bmad-forge-idea SKILL.md. - Left — the three exits, `forge-report.html` every run, `forge-.md` only when hardened, and its hand-off to `bmad-spec`, `bmad-prd`, or `bmad-prfaq` match the Exits section. - Left — `bmad-advanced-elicitation`: a menu of critique methods, proposed changes applied or rejected, true per its SKILL.md. "The brief, PRD, UX, and spec skills offer it at their own pauses" matches core-tools help. - Left — the tip to run `bmad` and the What Comes Next links resolve and are true. Source conflict: skills/bmod-core-tools/help/help.md — says other skills call `bmad-advanced-elicitation` at their pauses; bmad-product-brief, bmad-prd, bmad-ux, and bmad-spec SKILL.md only mention at the greeting that it is available any time. ### docs/plan/research-a-decision.md - Fix — the closing paragraph named `bmad-market-research`, `bmad-domain-research`, and `bmad-technical-research` and said "the old names still forward here"; none is under `skills/`, no `v6-shims/` exists in v7, and the Analyst menu reaches the types through `MR`, `DR`, and `TR` (bmad-agent-analyst customize.toml). It now says the v6 skills are Deep Recon's `market`, `domain`, and `technical` types, no skill remains under the old names, and to name the type or pick `MR`, `DR`, or `TR` from the Analyst's menu. - Left — the six research types, explore and select shapes, and custom types through `bmad-customize` match deep-recon customize.toml and SKILL.md. - Left — Draft (tool-tuned prompt with questions, recency, citation demand), Process (original filed untouched in `imports/`, claims extracted, gaps flagged, same summary), and Run (presets `quick`/`standard`/`deep`, validation `normal`/`high`/`max`, request overrides the preset) match references/draft.md, process.md, run.md, and customize.toml. - Left — the mode table, the bare-request trade stated once and remembered for the session, the single plan gate, sources retrieved this run, and project files shaping only questions match SKILL.md and help/research.md. - Left — the `research-/` folder in the active initiative or the output folder when loose (deep-recon asks once per session), its imports, digests, and `research-.md`, and Refresh and Deepen match lifecycle.md. - Left — the Starting It phrases and `/bmad-customize bmad-deep-recon` are requests the skill routes. ### docs/plan/define-requirements-and-a-specification.md - Fix — the "What each skill produces" note said each document lands in the output folder when no initiative is active; `bmad-product-brief`, `bmad-prd`, and `bmad-spec` hand off to `bmad` to set one first and only `bmad-prfaq` asks whether the work belongs to one (method help.md, each SKILL.md). It now says so. - Left — brain dump, then Fast or Coaching path, and pause and resume for the brief, PRD, and UX skills match their SKILL.md files. - Left — the brief: create, update, validate, right-sized to stakes, `brief-.md` plus `addendum.md` read by `bmad-prd`, and the suggestion of Deep Recon for deep market work match bmad-product-brief SKILL.md and analysis-skills.md. - Left — the PRFAQ: customer-first redirects, five stages, researched claims, the redirect to brainstorming or Forge Idea, `-H`, and the distillate for a PRD or spec match bmad-prfaq SKILL.md, references/verdict.md, and method help. - Left — the PRD: create, update, validate; Vision + Features or Journey-led on the Coaching path; FRs with stable IDs, NFRs, tech in `addendum.md`; length scaled to stakes; misroutes to brief or PRFAQ match bmad-prd SKILL.md. - Left — the spec: five fields, companions, rich input extracted, express or guided for sparse input, too thin goes to `bmad-prd`, single writer, stable capability IDs, assumptions and open questions reported, the one-time `bmad-ticket` hand-off match bmad-spec SKILL.md and planning-skills.md; the few-tens-of-thousands-of-tokens ceiling is not contradicted. - Left — dispatching each ticket to `bmad-build-auto` as `ticket ` with no leaf file pulled matches bmad-build-auto step-01 and help/unattended-builds.md. Source conflict: skills/bmad-prd/SKILL.md — its misroute list sends agent or skill work to `bmad-workflow-builder` "if the BMad Builder module is installed"; skills/bmod-toolsmith/retired.toml lists `bmad-workflow-builder` as removed and Toolsmith replaces BMad Builder. ### docs/plan/design-ux-and-architecture.md - Fix — the spine section said attaching the spine to the spec is how "Build and the readiness gate find it"; no v7 skill or agent menu item runs a readiness gate (`bmad-check-implementation-readiness` is removed per skills/bmod-method/retired.toml). It now says Build and `bmad-ticket` find it, which reads the spine when slicing (bmad-ticket references/slice.md). - Fix — What Comes Next said the readiness gate checks that stories do not depend on unrecorded decisions; it now says `bmad-ticket` checks each breakdown before approval: nothing may contradict the architecture, and every decision two or more epics must adopt needs a home (references/validate.md, validate-checks.md). - Left — the need table and the conflicting-choices section are guidance the sources do not contradict. - Left — the spine: invariants only, seed owned by code, the one-test rule, stable `AD` IDs, input from spec, idea, long document, or codebase, Coaching by default with alternatives shown, Fast path with `[ASSUMPTION]`, a current starter for an open stack, epic spines inheriting the parent, and the offer to attach to the spec match bmad-architecture SKILL.md. - Left — seeding project context from the spine matches method help (`bmad-project-context` when the stack was just decided); `bmad-correct-course` for a significant change matches help. - Left — UX: `DESIGN.md` and `EXPERIENCE.md` winning over mocks, the facilitator never volunteering a vision, Fast, Coaching, and design-handoff modes, and UX leading, following, or standing alone match bmad-ux SKILL.md and planning-skills.md. Source conflict: skills/bmad-ux/SKILL.md and skills/bmad-architecture/SKILL.md — both route agent or skill requests to `bmad-workflow-builder` "if the BMad Builder module is installed", which skills/bmod-toolsmith/retired.toml lists as removed. Source conflict: skills/bmod-method/help/help.md — says John (`bmad-agent-pm`) and Winston (`bmad-agent-architect`) "check readiness", but neither agent's menu has a readiness item and no shipped skill performs one. ## docs: move the upgrade page to Reference and fix README and diagram headings - docs/reference/upgrade-from-v6.md: moved from docs/start/; add sidebar order 2 and repoint the Install BMad link to ../start/install-bmad.md. - docs-site/astro.config.mjs: remove the Upgrade from v6 item from the Start sidebar. - docs/start/install-bmad.md: repoint the upgrade link to ../reference/upgrade-from-v6.md. - docs/start/get-answers-about-bmad.md: remove the upgrade-page sentence from the tip. - docs/start/build-your-first-change.md: remove the upgrade-page sentence from the intro. - README.md: drop the Toolsmith row from the ecosystem table and mention Toolsmith in the BMad Method row. - docs-site/src/diagrams/planning-skills.svg: retitle the second and third columns PLANNING: WHAT and PLANNING: HOW. Decision: the upgrade page lives in Reference, and the install page is the only page that links to it. A Start sidebar item is too prominent for an upgrade guide. Decision: the two planning columns are headed PLANNING: WHAT and PLANNING: HOW, with their subtitles unchanged. The alt text in choose-a-planning-path.md and the SVG's desc already describe the columns as planning what to build and planning how, so neither changed. ## docs: audit the build, review, and walkthrough pages and diagrams against v7 ### docs/build/build-a-change.md - Fix — step 4 said the route follows "three facts about the settled design: intent gaps, irreversible actions, and footprint"; no source names those facts. `route_selection` picks by estimated size, 100 changed lines or fewer going one-shot (bmad-build customize.toml), and both routes put intent gaps to you before implementing (step-02-plan.md Open Questions, step-oneshot.md). It now says the route follows estimated size, with no approval stop on the light path, and that intent gaps become open questions on either path. - Fix — step 5 said the build reviews "with independent reviewers"; the default `quick` review runs one lens (customize.toml `review = "quick"`, review-choices.md). It now says "one or more independent reviewers". - Fix — step 5 said a weak plan or goal always sends the run back to that layer; only the full route loops back on bad_plan and intent_gap (step-04-review.md). step-oneshot.md HALTs for a finding whose fix is not simple. A sentence now says so. - Fix — What You Get put a ticket's plan beside the epic's `tickets.toml`; a backlog ticket's plan sits in `backlog/` (tools/ticket-tree-rules.md, implementation-skills.md). The bullet now names it. - Fix — Deferred Work said several goals in one request are written to `deferred-work.md`; step-01 asks first and writes them only when you choose Split. It now says "and you choose to split them". - Fix — the skills table's `bmad-correct-course` cell said "Updated plan or re-routing"; it drafts a change proposal and does not apply edits (implementation-skills.md). It now says "Change proposal with drafted edits". - Fix — the `bmad-code-review` cell said "Findings + applied patches"; patches are applied only if you choose (step-04-present.md, validation-skills.md). It now says "Findings + the patches you choose to apply". - Left — intro, Size the Work (one goal, about 500 lines not counting tests, fresh chat), and the `build-run.svg` embed and alt text "The bmad-build run", which still names what the diagram shows. - Left — step 2: free text, an issue, a file, a ticket ref `.`, file, or title, and the no-argument flow (offer unfinished plans, then the next ready ticket, otherwise ask) match step-01 and tickets.py REF_HELP. The `intent-checkout.md` example is any file handed as intent, which step-01 accepts. - Left — step 3: investigate before asking, no interview up front, open questions on the finished design (step-01 RULES, step-02 item 2). - Left — step 6: short summary and the PR, walkthrough, or another-change offer (step-05-present.md); never pushes. - Left — the deferred-work location, When to Plan First, the bmad-build-auto pointer, the remaining table rows, and the "Why Does This Take So Long?" section, whose one-shot route and skip-review options are `oneshot` and `none` in SKILL.md. - Left — headings unchanged; no page links into this one by anchor. ### docs/build/review-a-change.md - Fix — triage was said to dismiss "unsubstantiated claims"; an unverified claim is rejected only when it would be low if true, and is otherwise deferred marked unverified (bmad-code-review step-03-triage.md). It now dismisses "unverified claims that would be minor even if true". - Fix — "Defer is a real pre-existing issue that is not this change" left out the unverified medium or high claims that also route to defer (step-03-triage.md, review-choices.md). It now adds "or a serious claim triage could not verify". - Fix — Your platform said that without subagents the lenses "fall back to the main session"; step-02-review.md writes each lens's prompt to a file and HALTs for you to run it elsewhere and paste back the findings. The paragraph now says so. - Left — the intro on re-handing `bmad-build` its `built` plan, which goes straight to review, and a `done` plan becoming context (bmad-build step-01, review-choices.md). The third-pass advice matches help. - Left — Run `bmad-code-review`: targets, offering tickets in review, diffing from `baseline_revision`, plan files, no-plan mode reclassifying decision-needed to patch or defer, the diff file, and the confirmation checkpoint all match step-01-gather-context.md and step-03-triage.md. The intent-alignment lens's `when` gate backs "only if it is told what the claims are". - Left — What a Run Does: parallel layers, verify, severity, routing, the dated `## Code Review` block or chat-only listing, user-chosen patches, and status never changed (step-04-present.md). - Left — Choose the Depth: `bmad-build` and `bmad-build-auto` default `quick` and `bmad-code-review` defaults `thorough` (each customize.toml); `bmad-customize` changes the default (review-choices.md). - Left — Customize the Lenses and the `/code-review` comparison: lenses can be added, replaced, disabled with an empty instruction, or run elsewhere (customize.toml lens comments). - Left — headings unchanged; `#choose-the-depth`, linked from autonomous-development-loops.md, is intact. ### docs/build/walk-through-a-change.md - Left — the intro and the human-review note match bmad-walkthrough workflow.md: one block at a time, done only when you say so. - Left — When to Use It: invoked by name (SKILL.md description "Use when invoked by name"), for a commit, PR, file, or directory. - Left — How it runs: orientation from plan or spec, PR description, and commits (step-01); narrative blocks intent, broad strokes, slices by concern, periphery, with the log in `walkthrough-/` under the initiative or output folder (workflow.md Block shapes, step-02); a link and one to three moves per block (step-03). - Left — the six moves and Formal review preferring `bmad-code-review` (step-03 Moves); What It Is Not: no severity, no verdict (review-choices.md). - Left — no diagram embedded; see walkthrough-run.svg below. ### docs-site/src/diagrams/build-run.svg - Fix — a "Fits AC?" gate sat between Implement and Review; step-03-implement.md says "Acceptance criteria are judged at review, not here." The gate is removed, and everything below it moves up. - Fix — an "interview" arrow from you into Clarify and route; step-01 says "Do not conduct an intent interview here", and gaps become open questions in planning (step-02 item 6, step-oneshot.md). The person now feeds Plan, labelled "open questions". - Fix — the one-shot bypass left Clarify and route and skipped Plan; one-shot still investigates and writes a minimal plan in step-02, skipping only approval. The bypass now leaves Plan and skips Approved plan, labelled "one-shot". - Fix — "plan review / optional" at Approved plan; on the full route Checkpoint 1 HALTs for approval every time (step-02). It now reads "you approve / the plan". - Fix — intent_gap returned to Clarify and route; step-04-review.md resolves it with you, then re-runs from step-02-plan.md. It now returns to Plan beside bad_plan. - Fix — "deferred_work.md"; the file is `deferred-work.md` (step-04-review.md). - Fix — the lens panel showed three lenses. The thorough set is four, including Intent Alignment Auditor, and the default quick set is one Quick lens (customize.toml, review-choices.md). The panel now shows Quick as the default and the four thorough lenses. - Fix — lens names "Edge Cases Hunter" and "Verification Gap Finder"; customize.toml names them "Edge Case Hunter" and "Verification Gap Reviewer". - Fix — Blind Hunter's "find any 10 things to fix"; its floor scales with diff size, min(floor(sqrt(kB) + 1), 10) (customize.toml). It now reads "bare diff: find things to fix". - Fix — the title said review can "void" the work; reject discards a finding, not the work (step-04 Classify). The title now describes the redrawn flow and says review can reject a finding. - Left — patch looping on Review, reject to Void, defer to the file, bad_plan back to Plan, Present, Result, and "you review the result" match step-04 and step-05-present.md. The loopbacks are the full route's; step-oneshot.md's patch, HALT, defer triage has no separate drawing. - Left — Edge Case Hunter "find forgotten corner cases" and Verification Gap Reviewer "is this covered by tests?" match review-prompts/edge-case-hunter.md and verification-gap.md. - Left — geometry and classes only, no colours; xmllint parses it, and no README exports it. ### docs-site/src/diagrams/walkthrough-run.svg - Fix — removed, never embedded. It drew Orientation, Walkthrough, Detail Pass, Testing, and Wrap-Up, with "Surface area stats" and Approve / Rework / Discuss outcomes. bmad-walkthrough runs Orientation, Create review narrative, then Walkthrough block by block; Test and Drive are moves picked per block, and Wrap-up proposes a follow-through and waits for a yes (step-01 to step-03). It has no detail-pass or testing stage, no surface stats, and gives no verdict. Fixing that means drawing a new diagram, not relabelling this one, and the page's numbered list already shows the three steps. Decision: walkthrough-run.svg is removed rather than embedded, because its flow cannot be made true to bmad-walkthrough by relabelling. ## docs: audit the ticketing and organization pages against v7 ### docs/plan/break-work-into-stories-and-track-it.md - Fix — Build an Entry said build reads "an existing refined leaf file"; it reads the story file whenever one was pulled, refined or not (tools/ticket-tree-rules.md, help/ticketing-setup.md Hand-off). It now says "the leaf file when one was pulled". - Fix — "Its numeric `ticket` joins the entry"; an id can be letters and digits such as `6a` (CHANGELOG Unreleased, bmad-ticket SKILL.md The ticket tree). It now says "Its `ticket`, the entry's id, joins the entry". - Fix — Correct Course said the skill requires a PRD and sent spec work without a PRD to `bmad-spec`; it needs a PRD or a spec and halts only with neither, and `bmad-spec` is for a change that touches only the spec (bmad-correct-course SKILL.md Missing documents, help/implementation-skills.md). It now says so. - Fix — Correct Course said the proposal lands in the output folder when no initiative is active; the skill hands off to `bmad` to set one first and writes only `{output_folder}/{active_initiative}/change-/change-.md` (bmad-correct-course SKILL.md Step 4 and Paths). It now says so. - Left — the intro (intent, a spec, or a PRD; one small story or bug straight to Build) matches bmad-ticket Intake. - Left — Plan the Work: initiative sliced into epic envelopes that record the parent requirement ids they own and Done when, inception into ordered stories and bugs with coverage, `after`, and `verify`, approval before writing, and standalone tickets in `backlog/` match references/slice.md and ticket.md. - Left — plan beside `tickets.toml` as `story--plan.md` for a story, backlog plan using the file stem, status and `baseline_revision` in the plan (tools/ticket-tree-rules.md); explicit one-ticket dispatch to `bmad-build-auto` that never picks work (help/unattended-builds.md). - Left — Track Progress: `next` and `status`, `built` shown as review, done by the user or an orchestrator, tracker status kept apart from build status (references/board.md Status); keeping completed plans (help/artifact-lifetime.md). - Left — Review and Close: dated `Code Review` block, status never changed, retrospective by folder, id, or slug writing in the epic folder, closure through `bmad-ticket` (tools/ticket-tree-rules.md, bmad-retrospective workflow.md). - Left — Correct Course reads no ticket tree and hands its edits to the owning skills and `bmad-ticket` (help/implementation-skills.md). The `#correct-course` heading, linked from build-a-change.md and reference/skills-and-agents.md, is unchanged. ### docs/plan/set-up-the-ticket-tree.md - Fix — the layout comment and Use `bmad-ticket` said a story gets its own file only when refined or published; reviewing a story pulls its file too (references/ticket.md Reviewing, help/ticketing-setup.md, the page's own "Review the stories" row). Both now include reviewing. - Fix — "By default the last entry is a 'Refactor sweep' story"; the sweep is proposed only for an epic of more than three entries, and a closing end-to-end suite can follow it (references/slice.md). It now says an epic of more than three entries closes with one by default. - Fix — Hand a Story to Build said build reads the story file "when you refined one"; it reads it whenever the story has one (tools/ticket-tree-rules.md). It now says "when it has one". - Fix — marking done on the repo store was "an edit to the plan that you commit with your work"; `bmad-ticket` runs `tickets.py mark` and then makes the commit its `write` verb describes (references/board.md Status, config/repo-ticketing.toml), and in a workspace the plan is in the store, not the code repo. It now says the skill commits it. - Fix — gap filled: Choose where the store lives gave no advice for the code repos in a workspace; help/monorepo-and-polyrepo.md recommends a bare clone per project with a worktree per branch. One sentence now says so. - Left — the install command and prerequisites match docs/start/install-bmad.md; `bmod-core-tools` and `bmod-method` are directories under `skills/`. - Left — store as the output folder, `_bmad-output` by default; `output_folder` under `[core]` in `_bmad/custom/config.toml`; `active_initiative` under `[core]` in `_bmad/custom/config.user.toml`; `bmad` showing, switching, creating, and clearing it (CHANGELOG Unreleased, bmad-ticket SKILL.md activation). No `root` key is named. - Left — the workspace layout, its own `git init`, and the AGENTS.md tip match help/monorepo-and-polyrepo.md and help/artifact-lifetime.md. - Left — `bmad migrate method` moving planning documents, `epics.md`, `sprint-status.yaml`, and stories behind an approved plan (skills/bmod-method/migration-1.toml, skills/bmad/references/migrate.md); the copy mapping and `ux-/` holding `DESIGN.md`, `EXPERIENCE.md`, and a short `ux-.md` (bmad-ux SKILL.md Create). - Left — `_bmad/custom/ticketing-store-config.toml` holding only the project's keys over the starter, the six stores and what each publishes as, setup offering connect, labels or fields, and a test ticket, and nothing syncing on its own (references/store-setup.md, config/*-ticketing.toml, help/ticketing-setup.md). - Left — three levels, a spec folder inside the container, `CAP-N` coverage, the say-this table, `tickets.toml` fields, `unknown`, spikes on request, entries built with no file, and the entry keeping `id`, `type`, `title`, `after`, and `hitl` after a pull (bmad-ticket SKILL.md, references/slice.md, ticket.md, assets/tickets-template.toml); `next` groups ready to refine, ready to start, in progress, and blocked (scripts/tickets.py). - Left — How epics are cut: ownership or deployment boundary, touch points, `_bmad/custom/bmad-ticket.toml` for the team's rule, shared decisions to `bmad-architecture` or hitl stories in the opening epic, `Source conflict:` lines (references/slice.md). - Left — the Refining is optional note, `built` and done, start on a tracker, and `tracker_status` never steering the build (references/board.md, help/working-in-an-organization.md); Tell Us What You Find matches help/ticketing-setup.md Feedback. - Left — headings unchanged; no page links into this one by anchor. ### docs/plan/plan-inside-an-organization.md - Fix — Who Owns What gave "Whoever tracks the whole" ownership of plan statuses; `bmad-build` and `bmad-build-auto` write every status up to `built`, and only `done` is the user's or an orchestrator's through `bmad-ticket` (references/board.md Status, tools/ticket-tree-rules.md). The cell now reads "The ticket tree and marking tickets done". - Fix — "An epic is a handful of Build sessions, usually a day's work for one person"; eight to twelve stories, each one agent session, is typical for an epic with one owner (references/slice.md Epic into stories). It now says "typically eight to twelve Build sessions, usually one person's work". - Left — when to take the full path, the scaled-down route, and the PRD as the owned document match help/working-in-an-organization.md; `bmad-ux` in `ux-/`, the spine, one spec per epic, and `bmad-ticket` tracking joined plans match planning-skills help. - Left — Bring the Documents You Have: validate, create with `[ASSUMPTION]` tags, Update mode instead of hand edits, design and architecture starting from what exists, tracker status mirrored and never steering a build (help/working-in-an-organization.md, references/board.md). - Left — the remaining owner rows: the help table gives `bmad-ticket` to whoever tracks the whole and the epic's stories to its engineer, which the page's `tickets.toml` and Build per story restate. - Left — the five sign-off moments, what each blocks, and `-H` on PRFAQ and Retrospective match the help's table; the retrospective judges the epic against its own Done when (bmad-retrospective workflow.md). - Left — Several Epics at Once and When Requirements Change: epic spines inheriting the parent, `bmad-prd` update surfacing conflicts, stable capability ids, `bmad-spec` naming stories that no longer match, existing plans keeping status, and `bmad-correct-course` for a plan-threatening change match the help. - Left — headings unchanged; no page links into this one by anchor. ## docs: audit the autonomous-loop, epic-closing, and testing pages against v7 ### docs/build/autonomous-development-loops.md - Fix — Context Inputs listed `_bmad/config.user.toml`; v7 reads `_bmad/config.toml`, `_bmad/custom/config.toml`, and `_bmad/custom/config.user.toml` (skills/bmad/scripts/config_utils.py load_central_config), and setup.py lists `_bmad/config.user.toml` as a legacy leftover. It now names the two `_bmad/custom/` files. - Fix — On `blocked` said `mark` creates the plan "with only that frontmatter" (status and the blocked fields); `tickets.py mark` also writes `title` and `ticket` (cmd_mark). It now says it creates a plan that holds only frontmatter. - Left — one run clarifies, plans, implements, and reviews one intent or ticket, never picks or advances to another ticket, and leaves backlog policy to a human or orchestrator: matches workflow.md, step-01, and help/unattended-builds.md. `bmad-loop` is presented as an external orchestrator with its repository link, and the note that it does not dispatch from the tree yet matches help. - Left — `quick` is the default review, overridable with `thorough` in the invocation or in `_bmad/custom/bmad-build-auto.toml` (customize.toml `review = "quick"`, SKILL.md `--set workflow.review`, render_skill.py override layers); the `#choose-the-depth` link resolves. - Left — `no subagents`, the clean tree, writable metadata, and the branch judged against the epic for a ticket match workflow.md Subagents and step-01 item 3. - Left — input shapes (a ticket named as a ticket or a ticket file, a bare ref not taken as one, free text, an intent file, a plan file), `tickets.py find`, `ticket not resolved`, never writing a ticket file or running `pull`, and reading same-epic prerequisite plans match step-01. `tickets.py` at `_bmad/method/scripts/` installed by `bmad-ticket` matches its bmod.toml and tools/ticket-tree-rules.md; `mark` refusing on a tracker store matches cmd_mark. - Left — `plan_checkpoint` and `done_checkpoint` belong to the orchestrator, `refined` is on find's row, and `Halt after planning.` stops at `ready-for-dev`: tickets.py docstring and public(), bmad-ticket references/board.md, step-02 gate. - Left — the resume table matches step-01's routing; `dropped` is not in it, but the table does not claim to cover it. - Left — `tickets.py next`, `ready_to_start` holding tickets whose prerequisites are done or in review, and `status` match tickets.py classify and HELP. - Left — Context Inputs' customization layers, empty `persistent_facts`, and the ticket and non-ticket planning documents read match customize.toml and step-01 item 1. - Left — the Plan Status table's statuses and board states match tickets.py STATUSES and STATE_OF; Build Auto never marks `done`, a follow-up pass on a `done` plan keeps it `done` (step-04 Finalize). - Left — deferred item fields, the maybe-false `(unverified)` severity, and the medium-or-worse rule match step-04 Classify and the defer shape. - Left — `ready-for-dev` as a halt outcome and its resume at implementation match step-02 and step-01. - Left — On `built`: final status, the Auto Run Result contents, `baseline_revision` with `NO_VCS`, `risk` never below the ticket's, `deferred`, commit without push, and a clean tree match step-03, step-04 Finalize, and plan-template.md. "`followup_review_recommended` true if LLM decided another pass seems worthwhile" matches the plan template's own comment; step-04 has the model compute it from the patched entries and a named risk. - Left — On `blocked`: `mark blocked --blocked`, details under `## Auto Run Result`, `blocked plan supplied` writing nothing, the fallback for a plan path or `mark` failure, every listed blocking condition, retry through `mark ` clearing the blocked fields, and the intent-gap patch saved beside the plan then reverted match workflow.md HALT, step-01 through step-04, and cmd_mark. - Left — plan path `--plan.md` from `find` (plan_path), `ticket` as the entry id or the story file's stem, `plan-.md` in `initiative_folder` for other work, the plan's sections, and the `bmad-build-auto-result-.md` fallback in `initiative_folder` match step-01, plan-template.md, workflow.md, and render_skill.py `_initiative_folder`. - Left — Orchestrator Responsibilities, including commit ranges between consecutive `baseline_revision` values, match the plan fields and the retrospective's evidence-gathering ranges. Source conflict: skills/bmod-method/help/review-choices.md — under "Review depth in `bmad-build` and `bmad-build-auto`" says review asks the user when the intent cannot settle a finding and logs pre-existing issues to `deferred-work.md`; bmad-build-auto step-04 halts `blocked` with `intent gap` and records deferred findings in the plan's `deferred` frontmatter. Source conflict: skills/bmod-method/help/unattended-builds.md — says `followup_review_recommended` is true when review fixed a high finding or two or more medium ones; bmad-build-auto step-04 sets it on a follow-up pass only for a patched high, and only when a specific unverified risk can be named. ### docs/build/finish-an-epic.md - Fix — What It Reads said the story file is read "only when the ticket was refined"; the retrospective reads `find`'s `story_file` whenever the ticket has one, which is any pulled ticket, reviewed, refined, or published (workflow.md Inputs, references/evidence-gathering.md). It now says when the ticket has one. - Fix — "only you mark a ticket done"; the user or an orchestrator marks it done with `tickets.py mark` (help/unattended-builds.md, bmad-build-auto docs). It now says only you, or an orchestrator. - Left — evidence over recollection, the aggregate defects, the `bmad-review` diff-scope pass weighting ticket seams, spec reconciliation, the end-to-end behavior check, previous-retro follow-through, and every finding needing a source match workflow.md Phases 1–2 and references/aggregate-views.md; the `#bmad-review` link resolves. - Left — inputs (`tickets.toml` build order via `status`, the epic file's Done when, the initiative's Requirements and `covers`, plan sections and `## Code Review` blocks, ranges between plan baselines, the previous retrospective) match workflow.md Inputs and evidence-gathering.md. - Left — finished means `built`, `done`, or `dropped`, and tickets still at `built` are listed: workflow.md and references/acceptance-verdict.md. - Left — `epic--retrospective.md` in the epic folder as the only write, nothing marked done, the three verdict spellings in frontmatter, unfinished tickets forcing `rejected`, human override, and never silently accepted match references/retro-document.md and acceptance-verdict.md. - Left — action items and spec reconciliations proposed, not applied, match acceptance-verdict.md. - Left — invocation by folder, id, or slug, the offer of finished epics with no input, the default stop at report and verdict, opt-in team discussion through party mode, and `-H ` match workflow.md Modes, Inputs, and Phase 3; the party-mode link resolves. ### docs/build/test-completed-work.md - Fix — the Setup row said the built-in skill is "Included with BMM", the v6 module name; v7 ships it in the BMad Method module (skills/bmad-qa-generate-e2e-tests/bmod.toml `bmod-method`, docs/reference/skills-and-agents.md). It now says the BMad Method module. - Left — `bmad-testarch-automate`, `bmad-testarch-test-design`, `bmad-testarch-trace`, ATDD, test review, NFR, and gates are presented as skills of the separate TEA module, and the TEA documentation URL as its external site; claims about them are outside these sources. - Left — the run steps (detect the framework from dependencies and existing tests, suggest one when none, ask or auto-discover what to test, API status codes and response shape with happy path and one or two errors, E2E with semantic locators and visible outcomes, run and fix, summary with what is uncovered) match SKILL.md Steps 0–5 and checklist.md. - Left — tests under `tests/`, the summary at `test-summary-/test-summary-.md` in the initiative or output folder, and tests run once and made to pass match SKILL.md Paths, Step 4, and Output. - Left — generates tests only, review is `bmad-build` or `bmad-code-review`, and no complex fixtures match SKILL.md's role and Keep It Simple. - Left — Where It Fits: running it after one change, and the retrospective as a separate epic check against its spec, match help/validation-skills.md and bmad-retrospective workflow.md. The Add Modules link resolves; that page's own content is outside this audit. ## docs: rewrite the add-modules page for v7 module installation Epic decisions: Toolsmith replaces BMad Builder everywhere on the page, including the build-your-own section, which points at docs/toolsmith/toolsmith.md and says only what the toolsmith help confirms. The ecosystem modules (Creative Intelligence Suite, Game Dev Studio, Test Architect) keep a short entry linking their own documentation and lose their v6 install commands; their v7 install route is not known, so the page says nothing about it. Every command on the page appears verbatim in README.md, the bmad skill, or the modules help. ### docs/customize/add-modules.md - Fix — intro said modules are selected during `npx bmad-method install` and add to core and BMM; now a module is a set of skills plus a `bmod-` record, installed with the Skills CLI and set up with `bmad setup`. - Fix — added "What a Module Adds": no installer, registry, or build step; setup questions, help, party mode, dependency offers, update checks (modules help). - Fix — "Official modules" listed code, npm package, and v6 feature lists for BMad Builder, CIS, GDS, and TEA; BMad Builder is gone (Toolsmith replaced it) and the other three are a short table linking their repositories. - Fix — "Install from a custom source" described the v6 interactive prompt, UNVERIFIED warning, URL/path input table, and `--custom-source`/`--modules` flags; now `npx skills add /` with the `bmod-` record, and setup offering a missing record. - Fix — "How the installer finds modules" (marketplace.json discovery vs direct mode) dropped; v7 has no such modes. - Fix — "Develop a module locally" (local `--custom-source` path) dropped; build in the source repository instead (toolsmith help). - Fix — "What you get" showed `_bmad//` folders and `_config/manifest.yaml`; now "Set Up the Module" says where config answers and scripts go, and what `bmad status` reports. - Fix — "Update modules" described `--action quick-update` and `--action update`; now `bmad setup` updates with `npx skills update`, migrates customizations of renamed skills, offers retired-skill deletion and migrations, and plugin-installed modules update through the marketplace. - Fix — "Create your own module" pointed at BMad Builder and `bmad-module-builder`; now Toolsmith's Smithy, the four registration choices, extending the method with your own prefix, and contributing by pull request. - Fix — install messages from module authors are shown quoted and never followed as instructions, replacing the v6 UNVERIFIED notice. - Left — title, sidebar order, and the TEA link to Test Completed Work, which still compares the two generate skills. Source conflict: skills/bmod-core-tools/help/modules.md — its last paragraph names the BMad Builder module for authoring; CHANGELOG Unreleased says Toolsmith replaced it. The page follows the CHANGELOG. Source conflict: docs/reference/skills-and-agents.md — says modules add their skills under the `bmad-` prefix and links here; the toolsmith help says a user's module takes its own prefix and never a `bmad-` name. Gap: BMad Loop is listed in the README ecosystem table but has no entry in the page's ecosystem table; it would go there once its v7 install route is known. Gap: no source states a trust caution for third-party modules; one would go under "Install the Module's Skills". ## docs: audit the customize, team-adoption, and party pages against v7 ### docs/customize/customize-bmad.md - Fix — "What an agent is made of" said central config controls how `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation` introduce an agent; `bmad-retrospective` reads no roster, and the roster readers are `bmad-party-mode`, `bmad-advanced-elicitation`, and `bmad-forge-idea` (help/party-mode.md, advanced-elicitation SKILL.md, forge-idea resolve_personas.py). A central `description` replaces the persona those skills voice, not an introduction line. It now says so. - Fix — the menu example replaced a shipped `CE` item on `bmad-agent-pm`; the PM menu has `PRD`, `CC`, and `TK` only (its customize.toml). The example now replaces `TK`. - Fix — "Override one rendered invocation" implied every skill's SKILL.md has a `render_skill.py` command; only `bmad-build`, `bmad-build-auto`, `bmad-code-review`, `bmad-retrospective`, and `bmad-walkthrough` do. It now names them. - Fix — Central configuration listed four files and four layers, including an installer-owned `_bmad/config.user.toml`; there are three: `_bmad/config.toml`, `_bmad/custom/config.toml`, `_bmad/custom/config.user.toml`, highest last (help/customization.md, config_utils.py). `bmad setup` writes user-scope answers to `_bmad/custom/config.user.toml`, so "the installer never touches `_bmad/custom/`" was false too. - Fix — "What lives where" credited scopes to a module's `module.yaml` and said `[agents.]` holds every agent's descriptor from the module's `agents:` block; questions come from the `bmod-` record, and `[agents.]` tables are optional, adding a user's own agent or describing an installed one, whose name, title, and icon come from its skill and override (help/customization.md). It now says so. - Fix — "Editing rules" called two files installer-owned and regenerated on every install and said to re-run the installer; all three may be hand-edited and `bmad setup` never changes an existing value, so a change is an edit to the key in its file (help/customization.md, bmad references/setup.md). It now says so. - Fix — the rebrand example set `icon` under `[agents.bmad-agent-pm]`; an installed agent's icon does not come from central config (help/customization.md, roster.py). The `icon` line is gone and the text says the description replaces the shipped persona. - Fix — the fictional-agent example said the `team` field filters who a party invites; nothing reads `team` (resolve_party.py keeps only name, icon, title, persona, capabilities, model), and a central-config agent joins the default room. The `team` line is gone; the text says Kirk joins the default room and points to party members for a cast called on demand. - Fix — "Override an install setting" said the team value wins over each developer's own config; `_bmad/custom/config.user.toml` outranks `_bmad/custom/config.toml`. It now says the team value wins over `_bmad/config.toml` and the personal file still wins; the table row "Pin team-enforced install settings" is now "Pin team setup answers". - Fix — Gap fill: help names `resolve_config.py` for checking merged central config and the page had no way to do so; "Check what resolved" now gives the command. - Left — the guided path, two surfaces, and `bmad-customize` writing per-skill overrides only match bmad-customize SKILL.md. - Left — three per-skill layers, the four shape rules, no removal, read-only `agent.name`/`agent.title`, and the full-copy caution match help/customization.md. - Left — scalars, the four append arrays, `file:` facts with globs, prepend before and append after the greeting, `[[agent.menu]]` keyed by `code` with one of `skill` or `prompt` match bmad-agent-pm customize.toml and SKILL.md. - Left — workflow `[workflow]` surface, `skill:` facts, `on_complete` string or array, and the six-step activation order match bmad-product-brief SKILL.md and customize.toml. - Left — `review` on `bmad-build`/`bmad-build-auto` (`quick`) and `bmad-code-review` (`thorough`), with four thorough lenses, matches their customize.toml files. - Left — `--set`, `--overrides`, plain-text strings, and TOML for other types match render_skill.py. - Left — `resolve_customization.py` flags, root inference, the stderr warning, and the Python 3.11 note match the script; Troubleshooting matches help's checklist. - Left — `.claude/skills/` and the per-IDE note match list_customizable_skills.py; `[core] active_initiative` in `_bmad/custom/config.user.toml` matches core-tools help.md; both inbound anchors (#central-configuration, #troubleshooting) are kept. Source conflict: skills/bmod-core-tools/help/customization.md — says overriding `agent.name` and `agent.title` does nothing, yet its central-config section says an installed agent's name, title, and icon come from "its own skill and its override file", and roster.py reads `agent.name` from the merged override for the party roster. Source conflict: skills/bmod-core-tools/help/customization.md — names `team` as a detail to add to an installed agent under `[agents.]`; bmad-party-mode's resolve_party.py drops it and no skill reads it. Source conflict: skills/bmad-party-mode/SKILL.md — calls resolve_config.py a "four-layer TOML merge"; help/customization.md and config_utils.py merge three. ### docs/customize/adopt-bmad-across-a-team.md - Fix — recipe 5 listed `bmad-retrospective` among roster-driven skills; it is now `bmad-advanced-elicitation` and `bmad-forge-idea` beside `bmad-party-mode`. - Fix — 5a said party mode introduces Mary with the new description; it now says the roster skills voice her with it in place of her shipped persona, and her name, title, and icon stay with her skill. - Fix — 5b keyed on a `team` value and said party mode filters by `team = "startrek"`; nothing reads `team`. The `team` lines are gone; the text says Spock and McCoy join the default room and links to building a party for a crew called on demand. - Fix — 5c pinned `[core] document_output_language`, which no v7 setup question or skill defines, and said the pin overrides each developer's own config; the key is gone and the text says the pin beats `_bmad/config.toml` while `_bmad/custom/config.user.toml` still wins. - Fix — 5c put personal settings (`user_name`, `communication_language`, `user_skill_level`) in `_bmad/config.user.toml`; that file does not exist and v7 setup asks none of those. It now says answers to user-scope questions stay in `_bmad/custom/config.user.toml`. - Left — the scope rule for picking a surface and the team/personal split match help/team-adoption.md. - Left — the tip (bmad-customize writes recipes 1–4 and 6, recipe 5 by hand) matches bmad-customize SKILL.md. - Left — recipe 1: `bmad-agent-dev` has `persistent_facts`, and its menu dispatches `bmad-build`, `bmad-code-review`, and `bmad-qa-generate-e2e-tests`. - Left — recipes 2–4: `persistent_facts` with `file:`, `on_complete` running once after output, and `brief_template = "assets/brief-template.md"` match bmad-product-brief customize.toml and SKILL.md. - Left — recipe 6: `bmad-prd` exposes `external_sources`, `external_handoffs`, `doc_standards` (default `skill:bmad-review lenses=structure,prose`, run in declared order within a document), `prd_template`, and `validation_checklist_template`. - Left — the IDE session-file section and layer table, the combining example (the Analyst's `CB` item dispatches `bmad-product-brief`), and Troubleshooting. `bmad-dev.toml` there is a deliberately wrong file name set against `bmad-agent-dev.toml`, not a skill name; `bmad-agent-` on the customize page is a placeholder. ### docs/customize/run-multi-agent-discussions.md - Fix — Gap fill: the page never said modules bring their own parties (help/party-mode.md). It now names The Product Team from the method roster (`--party product-team`) and points to Add Modules for sharing a cast as a module. - Fix — "Both shipped parties ... start fresh" would now be ambiguous beside The Product Team, whose roster sets `memory = true`; Memory now names the Code Review Crew and the Anti-Consensus Club, and says The Product Team remembers. - Fix — Gap fill: help says how to wipe a party's memory; Memory now says to delete its folder under `{output_folder}/party-mode/memories/`. - Left — the start-a-party table (`--mode`, `--non-interactive`, `--party`, `--list-groups`, inline casts, create/edit routing, `/bmad-customize bmad-party-mode`) matches SKILL.md On Activation and How It Runs. - Left — the four modes, `session` default, Claude Code-only `agent-team`, the fallback chain, runtime `--mode` winning, and interactive by default match SKILL.md, customize.toml, and references/mode-agent-team.md. - Left — personas, scenes, the six party shapes, focus groups paired with `subagent`, and writing through bmad-customize match references/create-party.md; default party, mode, and house rules map to `default_party`, `party_mode`, and `persistent_facts`. - Left — the Code Review Crew and Anti-Consensus Club member tables, inactive by default, and the subagent recommendation match customize.toml. - Left — steering, room switching, summoning by name, memory behavior, saving new faces, and the keepsake path (`{workflow.output_dir}` = active initiative folder) match SKILL.md, references/party-memory.md, and customize.toml. Source conflict: skills/bmad-party-mode/SKILL.md — says a mode the harness cannot run falls back to `session`; references/mode-agent-team.md says `agent-team` falls back to `subagent` first, then `session`. ## docs: audit the existing-codebase and project-context pages against v7 ### docs/existing-codebases/start-in-an-existing-codebase.md - Fix — the `bmad-build` link sat inside a code span and rendered as literal markdown; it is now a link around the code-formatted name. - Fix — said `bmad` "runs at the end of every workflow to say what comes next"; workflows end with their own next-step offers or a suggestion to invoke `bmad` (bmad-build step-05-present.md, bmad-prd and bmad-architecture Close), so it now says to ask `bmad` again when a workflow ends. - Fix — called `bmad-document-project` "deprecated"; it is not under `skills/`, and help/project-context.md says it was removed and `bmad-project-context` replaces it. It now says the skill replaces v6's document-project workflow, which v7 removed. - Fix (gap) — help/preparing-a-repo-for-agents.md and the `bmad-walkthrough` and `bmad-qa-generate-e2e-tests` steps of help/existing-codebase.md had no home in the docs. A new "Keep the Repository Fit for Agents" section covers cleanup first with tests in place, test generation for existing features, the walkthrough for unfamiliar code, refactoring after several stories and at each epic's end with the retrospective's drift findings, and small decision records pointed to from `AGENTS.md`. - Left — keeping the original greenfield PRD archived and out of reach matches help/preparing-a-repo-for-agents.md (the code is the best documentation; few documents during coding). - Left — the one-session, spec-plus-ticket epic, and project-sized paths match help/existing-codebase.md steps 4 and 5 and method help's after-a-skill-finishes table. - Left — Build looking at the code first and stopping only when investigation cannot settle intent matches bmad-build step-01 and step-02 (Open Questions). - Left — "Prepare Project Context, or Skip It": the small verified `AGENTS.md` block, skipping does not fail a Build, the same mistake every session until written down, and a later refresh or audit match help/existing-codebase.md and bmad-project-context SKILL.md. Skipping it when someone keeps the instructions current is advice the sources do not contradict. - Left — "Plan Around What Already Exists": PRD, optional UX, and architecture starting from the codebase match help/existing-codebase.md step 3. - Left — "Build Follows What It Finds": investigating, writing down what to reuse and what not to change, and following it match help/existing-codebase.md and bmad-build step-02 (Code Map). - Left — "Try It on a Known Tree First" describes Getting Deeper accurately. ### docs/existing-codebases/set-and-maintain-project-context.md - Fix — Step 1 showed `bmad-project-context` as a bash command; it is a skill, so the block is now a text block with `/bmad-project-context`, as the other tutorials invoke skills. - Fix — said everything outside the markers "is left unchanged, and no later run touches it"; SKILL.md step 5 and Adoption change text outside the markers through settled ledger entries (relocations, a `CLAUDE.md` reduced to `@AGENTS.md`) and proposed fixes to contradicting files, and refresh treats handwritten instructions outside the block as in adoption. It now says the splice touches nothing outside the markers and outside text changes only through a change you have seen and approved. - Fix — said a rule stays until what it is about is gone or you retire it; best-practices.md ground 2 and Maintain ("a check that lands deletes its line") also remove a rule a check enforces, so that ground is added. - Fix — said monorepo components and nested repositories "get their own file"; SKILL.md Children gives one only when the rules are subtree-exclusive and substantial, the split reduces the parent, loading is verified, and the user approves. It now says they get one when their rules are substantial and apply only there. - Fix — the note said `bmad-generate-project-context` and `bmad-document-project` "are deprecated and forward here; their trigger phrases still work"; neither is under `skills/` and help/project-context.md says both were removed. It now names them as v6's generate-project-context and document-project, says v7 removed both, and that the skill reads an old `project-context.md`, offers to absorb it, and does not delete it without agreement (SKILL.md Migration). - Left — the opening (new or existing codebase, standalone path, asks before writing), When to Use, the five intents and their routing, and the working-tree questions match SKILL.md Overview, Activation, and Resolution rules. - Left — Step 2 (reads existing files, reports, keeps and improves what you wrote, asks what you bring, greenfield vs brownfield) matches SKILL.md steps 1 and 2. - Left — Step 3 (path checks, reading config to know what not to repeat, the interview topics) matches steps 3 and 4. - Left — Step 4 (complete block shown first, markers in root `AGENTS.md`, verified `@AGENTS.md` import, never commits, closing report) matches steps 5 and 6. - Left — Keep It Healthy (refresh, record, audit) and What Earns a Line match SKILL.md Refresh, Record, Audit and best-practices.md Admit and Exclude. - Left — the intents table, the loading check before moving rules into a nested `AGENTS.md`, committing the block, and global config for personal or cross-project rules match best-practices.md Retrieval and Repo or home directory. - Left — Hand-Off to Architecture matches SKILL.md Greenfield. ### docs/existing-codebases/getting-deeper.md - Fix — said Build asks its questions "before it writes a plan"; bmad-build step-02 writes the plan with an Open Questions section, then asks and halts before presenting it. It now says before it presents a plan. - Left — the Django checkout, setup, starting behavior, install with `npx skills add bmad-code-org/BMAD-METHOD` and `bmad setup`, and the excluded `_bmad/` and `_bmad-output/` paths match docs/start/install-bmad.md. - Left — Build's plan approval, build, review, summary, and next-step offers match bmad-build step-02 through step-05. - Left — the spec path `_bmad-output/initiative-/spec-diffsettings-audit/spec-diffsettings-audit.md`, the initiative hand-off first, and `bmad-ticket` creating the epic and its `tickets.toml` entries match bmad-spec SKILL.md and bmad-ticket SKILL.md. - Left — running Build per ticket from the tree matches bmad-build step-01 ticket resolution. - Left — the retrospective reading `tickets.toml` and plans and writing `epic-diffsettings-audit-retrospective.md` in the epic folder, with plans kept, matches tools/ticket-tree-rules.md and docs/build/finish-an-epic.md. - Left — `bmad-forge-idea`, `bmad-advanced-elicitation`, and `bmad-party-mode` are installed skills used as described; `bmad-django`, `bmad-django-app`, and `bmad-getting-deeper` are a directory, a folder, and a branch name. ### docs/existing-codebases/theory-of-project-context.md - Fix — "Versus the two replaced skills" named `bmad-document-project` and `bmad-generate-project-context`, which are not under `skills/`; it now calls them v6's document-project and generate-project-context skills, with the comparison unchanged. - Left — the research findings (code access beats documentation, instruction files adding cost without success, the index comparison, skipped retrieval) are the evidence best-practices.md Retrieval and Size rest on; no source contradicts them. - Left — What earns a place and What is left out match best-practices.md Admit and Exclude, including prohibitions naming the alternative and a landed check deleting its line. - Left — A working rule stays matches best-practices.md Retire and the four deletion grounds. - Left — Two kinds of context: planning context as a separate capability still to come matches help/preparing-a-repo-for-agents.md ("A new documentation skill for codebases is planned"). - Left — Extra context is a cost matches SKILL.md Refresh and Audit. Source conflict: skills/bmod-method/help/project-context.md — says `bmad-generate-project-context` and `bmad-document-project` were removed, but skills/bmod-method/retired.toml lists only `bmad-bmm-generate-project-context` and `bmad-bmm-document-project`, so `bmad setup` would not offer to delete a still-installed copy under the unprefixed names. ## docs: correct the skill naming rule on the skills reference page ### docs/reference/skills-and-agents.md - Fix — "Naming and Modules" said every skill uses `bmad-` and modules add their skills under the same prefix; it now says `bmad-` marks skills BMad ships (core and BMad Method skills take a bare name, BMad's other modules insert their code as `bmad--` and `bmad--agent-`), and a module of your own takes its own prefix (`acme-release-notes`, record `bmod-acme`), never `bmad-` Checks: check 1 no output over 30 files (62 names); check 2 no output; check 3 prints only bmad-eval and bmad-toolsmith, as at base ## docs: describe retired v6 skills by role and name every intent-gap halt ### docs/existing-codebases/start-in-an-existing-codebase.md - Fix — named v6's document-project workflow; now says it replaces the earlier documentation-generating workflow, which v7 removed. - Left — the rest of the page names no v6 skill and was not reported false. ### docs/existing-codebases/theory-of-project-context.md - Fix — named document-project and generate-project-context; now the earlier documentation-generating skill and the earlier rules-file skill, keeping what each did and the right instinct. - Left — the "Versus the two replaced skills" heading, per the no-heading-changes rule; it names no v6 skill. ### docs/existing-codebases/set-and-maintain-project-context.md - Fix — the note's title and body named both v6 skills; now describes them by role and keeps the replacement and the absorb offer. - Left — the absorb behavior, checked against the Migration section of bmad-project-context's SKILL.md: it reads an existing project-context.md, offers to absorb it, and does not delete it without agreement. ### docs/reference/upgrade-from-v6.md - Fix — the retired-skills table lacked the project-context pair; adds bmad-bmm-document-project and bmad-bmm-generate-project-context, removed, replaced by bmad-project-context, named as retired.toml lists them. - Left — the rest of the table and page; no other page gained a link here. ### docs/build/autonomous-development-loops.md - Fix — said an intent gap halts only planning or review; now also names the implement step on the oneshot route, which records the gap in Implementation Notes and leaves the partial change uncommitted in the working tree with no patch saved. - Left — the review-step description (revert, patch beside the plan, git apply to resume), checked against the intent_gap branch of step-04-review.md and still true. ## docs: drop the unshipped module naming rule from the skills reference page ### docs/reference/skills-and-agents.md - Fix — "Naming and Modules" said the core and BMad Method modules use a bare `bmad-` name while BMad's other modules insert their code as `bmad--` and `bmad--agent-`, which no shipped module follows; that sentence is deleted, leaving that `bmad-` marks skills BMad ships, the three examples, and that a module of your own takes its own prefix, never `bmad-`, with the Add Modules link Source conflict: skills/bmod-toolsmith/help/naming.md — BMad modules name skills `bmad--` and agents `bmad--agent-` vs skills/bmod-toolsmith/bmod.toml — `code = "toolsmith"` ships `bmad-toolsmith` and `bmad-eval` ## docs: answer the review of the squashed commit ### docs/build/build-a-change.md - Fix — said every intent gap becomes an open question answered before implementation starts; bmad-build step-oneshot.md stops coding on a gap found while implementing and asks (light path) or sends the plan back to planning (full path). It now says so. ### docs/reference/upgrade-from-v6.md - Fix — said any `initiative-*/` folder blocks the migration; migration-1.toml blocks it only for a folder holding a same-named file, and treats that plus `tickets.toml` and a store config as already on v7. It now states those checks. --- README.md | 5 +- docs-site/src/diagrams/build-run.svg | 107 ++++--- docs-site/src/diagrams/planning-skills.svg | 8 +- docs-site/src/diagrams/walkthrough-run.svg | 48 --- docs/_STYLE_GUIDE.md | 4 +- docs/build/autonomous-development-loops.md | 6 +- docs/build/build-a-change.md | 39 ++- docs/build/finish-an-epic.md | 4 +- docs/build/review-a-change.md | 15 +- docs/build/test-completed-work.md | 2 +- docs/customize/add-modules.md | 301 +++++------------- docs/customize/adopt-bmad-across-a-team.md | 36 +-- docs/customize/customize-bmad.md | 91 +++--- docs/customize/run-multi-agent-discussions.md | 13 +- docs/existing-codebases/getting-deeper.md | 2 +- .../set-and-maintain-project-context.md | 34 +- .../start-in-an-existing-codebase.md | 33 +- .../theory-of-project-context.md | 6 +- .../break-work-into-stories-and-track-it.md | 6 +- docs/plan/choose-a-planning-path.md | 19 +- ...define-requirements-and-a-specification.md | 6 +- docs/plan/design-ux-and-architecture.md | 9 +- docs/plan/explore-and-validate-an-idea.md | 10 +- docs/plan/plan-inside-an-organization.md | 6 +- docs/plan/research-a-decision.md | 7 +- docs/plan/set-up-the-ticket-tree.md | 12 +- docs/reference/skills-and-agents.md | 14 +- docs/reference/upgrade-from-v6.md | 121 +++++++ docs/start/build-your-first-change.md | 9 +- docs/start/install-bmad.md | 4 +- 30 files changed, 485 insertions(+), 492 deletions(-) delete mode 100644 docs-site/src/diagrams/walkthrough-run.svg create mode 100644 docs/reference/upgrade-from-v6.md diff --git a/README.md b/README.md index b19b286126..2c45032ea8 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Choose one install route. You need an AI coding tool that supports skills and npx skills add bmad-code-org/BMAD-METHOD ``` -Select the skills and coding tool you want. Include `bmad` for setup and help, and the module record for each module you pick skills from: `bmod-method` and `bmod-core-tools`. To install by name instead, list them together: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-core-tools --skill bmod-method --skill bmad-build`. +Select the skills and coding tool you want. Include `bmad` for setup and help, and the module record for each module you pick skills from: `bmod-method`, `bmod-core-tools`, and `bmod-toolsmith`. To install by name instead, list them together: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-core-tools --skill bmod-method --skill bmad-build`. **Claude Code plugin** — add the marketplace inside Claude Code: @@ -71,8 +71,7 @@ Install the core method or add official modules for specialized work. | Module | Purpose | | --- | --- | -| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | Plan and deliver software, from new prototypes to established codebases | -| **[BMad Builder](https://github.com/bmad-code-org/bmad-builder)** | Skill, workflow, and agent builder | +| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | Plan and deliver software, from new prototypes to established codebases; includes Toolsmith for building, converting, and evaluating skills, agents, and modules | | **[BMad Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Creative thinking partners for innovation, design thinking, and storytelling | | **[BMad Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | Enterprise testing add-on for BMad Method | | **[BMad Loop](https://github.com/bmad-code-org/bmad-loop)** | Builds, verifies, and retros a whole epic unattended | diff --git a/docs-site/src/diagrams/build-run.svg b/docs-site/src/diagrams/build-run.svg index 617669b1a3..334bb7cd45 100644 --- a/docs-site/src/diagrams/build-run.svg +++ b/docs-site/src/diagrams/build-run.svg @@ -1,5 +1,5 @@ - -The bmad-build run: intent is clarified, planned, implemented, then reviewed. Review can patch the work, send it back to plan or clarification, void it, or defer it, before the result is presented to you. + +The bmad-build run: intent is clarified and planned, with open questions put to you. A small change goes straight to implementation; a larger one waits for you to approve the plan. Review, by one quick lens or four thorough ones, can patch the work, send it back to planning, reject a finding, or defer it, before the result is presented to you. @@ -15,62 +15,69 @@ Approved plan Implement - -Fits AC? + +Review -Review - -Present - -Result +Present + +Result - - + + - intent intent - -one-shot mode - -patch - -reject - -Void - -defer - -deferred_work.md - -bad_plan - -intent_gap - - -interview + +one-shot + +patch + +reject + +Void + +defer + +deferred-work.md + +bad_plan + +intent_gap + + +open questions -plan review -optional - - -you review the result - -Review lenses - -Blind Hunter -find any 10 things to fix - - -Edge Cases Hunter -find forgotten corner cases - - -Verification Gap Finder -is this covered by tests? - +you approve +the plan + + +you review the result + +Review lenses +quick, the default + +Quick +acceptance criteria, rules, bugs + +thorough + +Blind Hunter +bare diff: find things to fix + + +Edge Case Hunter +find forgotten corner cases + + +Verification Gap Reviewer +is this covered by tests? + + +Intent Alignment Auditor +does it do what was intended? + \ No newline at end of file diff --git a/docs-site/src/diagrams/planning-skills.svg b/docs-site/src/diagrams/planning-skills.svg index 9f87abbbda..2035735a21 100644 --- a/docs-site/src/diagrams/planning-skills.svg +++ b/docs-site/src/diagrams/planning-skills.svg @@ -1,6 +1,6 @@ Planning skills and what they produce - Three columns of skills and their artifacts. Analysis: bmad-brainstorming, bmad-forge-idea, bmad-deep-recon, bmad-product-brief, bmad-prfaq. Planning: bmad-prd, bmad-ux, bmad-spec. Solutioning: bmad-architecture and bmad-ticket. The columns flow left to right and hand off to bmad-build, one session per unit. Build finishes at built; the user marks done and retains the plan. + Three columns of skills and their artifacts. Analysis: bmad-brainstorming, bmad-forge-idea, bmad-deep-recon, bmad-product-brief, bmad-prfaq. Planning what to build: bmad-prd, bmad-ux, bmad-spec. Planning how and in what slices: bmad-architecture and bmad-ticket. The columns flow left to right and hand off to bmad-build, one session per unit. Build finishes at built; the user marks done and retains the plan. @@ -47,7 +47,7 @@ - PLANNING + PLANNING: WHAT define what to build @@ -72,10 +72,10 @@ straight from the spec to Build. - + - SOLUTIONING + PLANNING: HOW decide how, divide the work diff --git a/docs-site/src/diagrams/walkthrough-run.svg b/docs-site/src/diagrams/walkthrough-run.svg deleted file mode 100644 index aef726b9d7..0000000000 --- a/docs-site/src/diagrams/walkthrough-run.svg +++ /dev/null @@ -1,48 +0,0 @@ - -The bmad-walkthrough run: it reads the build plan or a pull request, then moves through orientation, the walkthrough itself, a detail pass and testing before wrapping up, where you approve, ask for rework, or open a discussion. - - - - - -bmad-build -plan file - - -PR / commit -branch - - -Orientation -Intent summary -Surface area stats - -Walkthrough -Organized by concern -Clickable path:line stops - -Detail Pass -Highest blast radius first -"dig into [area]" for a deep dive - -Testing -Manual observations -See it working - -Wrap-Up - - - - - -early exit - -Approve - - -Rework - - -Discuss - - \ No newline at end of file diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index 9b069ef477..e11ede01b5 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -259,7 +259,7 @@ cd docs-site && npm run export-readme-diagrams | ----------------- | --------------------- | | **Index/Landing** | `workflows/index.md` | | **Catalog** | `agents/index.md` | -| **Deep-Dive** | `document-project.md` | +| **Deep-Dive** | `bmad-eval.md` | | **Configuration** | `core-tasks.md` | | **Glossary** | `glossary/index.md` | | **Comprehensive** | `bmgd-workflows.md` | @@ -360,7 +360,7 @@ Starlight generates right-side "On this page" navigation from headers: Add italic context at definition start for limited-scope terms: - `*Direct-entry implementation only.*` -- `*BMad Method/Enterprise.*` +- `*BMad Method.*` - `*Phase N.*` - `*BMGD.*` - `*Established projects.*` diff --git a/docs/build/autonomous-development-loops.md b/docs/build/autonomous-development-loops.md index 95b52bcade..75db90a9c3 100644 --- a/docs/build/autonomous-development-loops.md +++ b/docs/build/autonomous-development-loops.md @@ -123,7 +123,7 @@ integration boundaries are explicit. On activation, the workflow resolves: -- `_bmad/config.toml`, `_bmad/config.user.toml`, and optional team/user overrides under `_bmad/custom/` +- `_bmad/config.toml`, with the team and user overrides `_bmad/custom/config.toml` and `_bmad/custom/config.user.toml` - Any configured workflow customizations from `customize.toml`, team overrides, and user overrides - Persistent facts listed in workflow config — empty unless you opt in, so nothing is loaded here by default @@ -190,7 +190,7 @@ The workflow commits but does not push. The working copy is clean at exit. On blocked completion, the workflow records the final status and a blocking condition: -- For a ticket named by its ref, file, or title, it runs `tickets.py mark blocked --blocked `. That writes `status: blocked`, `blocked_at` (the date), and `blocked_reason` to the plan, creating the plan with only that frontmatter when the run halted before planning. +- For a ticket named by its ref, file, or title, it runs `tickets.py mark blocked --blocked `. That writes `status: blocked`, `blocked_at` (the date), and `blocked_reason` to the plan, creating a plan that holds only frontmatter when the run halted before planning. - Details go under the plan's `## Auto Run Result`. On such a ticket, `blocked plan supplied` writes nothing, so the plan keeps its first reason. - If `mark` fails, or the run was given a plan path or work outside the tree, the workflow sets `status` in an existing plan or writes the fallback result artifact. The blocking condition is then only in `## Auto Run Result` or that file, not in `blocked_reason`. @@ -212,7 +212,7 @@ cause, then run `tickets.py mark ` with the status to resume from, which clears `blocked_at` and `blocked_reason`. When the plan holds only frontmatter, delete it instead, and the next dispatch starts fresh. -An `intent gap` means the captured intent cannot answer a question the run hit — it can halt the planning step (before any code exists) or the review step. When review halts on it, the working tree is reverted as usual, but the attempted change is first saved as a patch file beside the plan, referenced from the plan's triage log and the halt output. The patch shows which reading of the intent the run implemented — concrete evidence for repairing the intent. If the attempted reading turns out to be correct, `git apply` the patch and set the plan status to `in-review` to resume review on it instead of re-running from scratch. +An `intent gap` means the captured intent cannot answer a question the run hit — it can halt the planning step (before any code exists), the implement step on the oneshot route, or the review step. When the implement step halts on it, the gap is recorded in the plan's `## Implementation Notes`, and the partial change stays uncommitted in the working tree, with no patch saved. When review halts on it, the working tree is reverted as usual, but the attempted change is first saved as a patch file beside the plan, referenced from the plan's triage log and the halt output. The patch shows which reading of the intent the run implemented — concrete evidence for repairing the intent. If the attempted reading turns out to be correct, `git apply` the patch and set the plan status to `in-review` to resume review on it instead of re-running from scratch. ## Output Artifacts diff --git a/docs/build/build-a-change.md b/docs/build/build-a-change.md index 59f151575b..8c9a1a6b4e 100644 --- a/docs/build/build-a-change.md +++ b/docs/build/build-a-change.md @@ -93,13 +93,14 @@ expensive kind of mistake to find later. ### 4. Approve a Plan When Asked -After investigation, `bmad-build` routes to the smallest safe path. It reports -three facts about the settled design: intent gaps (things you did not say that you -would notice in the result), irreversible actions, and footprint. A design -clean on all three takes the light path — a minimal plan and implementation in -the same session, reviewed afterwards. Anything flagged gets a full written -plan first, with each intent gap recorded as an open question you answer -before approval. +After investigation, `bmad-build` routes to the smallest safe path by the +change's estimated size. About 100 changed lines or fewer takes the light path — +a minimal plan and implementation in the same session, reviewed afterwards, +with no approval stop. Anything larger gets a full written plan first. Either +way, each intent gap (something you did not say that you would notice in the +result) found while planning becomes an open question you answer before +implementation starts. A gap found while coding stops the build and asks you; +on the full path it sends the plan back to planning. Approve the plan when it describes the right thing to build. Push back if it does not — fixing the plan is cheaper than fixing the code. @@ -107,15 +108,17 @@ does not — fixing the plan is cheaper than fixing the code. ### 5. Implementation and Review After that decision, `bmad-build` implements the change, reviews its own work -with independent reviewers, fixes problems that belong to this change, and -commits locally. This works best on a platform that can spawn subagents, or at -least call another model from the command line and wait for a result. +with one or more independent reviewers, fixes problems that belong to this +change, and commits locally. This works best on a platform that can spawn +subagents, or at least call another model from the command line and wait for a +result. Review is triage, not a dump of every possible note. Issues that belong to the current change get fixed. Unrelated pre-existing issues get deferred. If the code is wrong because the plan was weak, or the plan is wrong because the goal was wrong, it goes back to that layer and regenerates from there instead of -patching only the diff. +patching only the diff. On the light path, a finding whose fix is not simple +stops the run and asks you instead. For a standalone review — a PR, someone else's change, an extra pass, or a review bot — see [Review a Change](review-a-change.md). @@ -144,9 +147,10 @@ different approach. - Modified source files with the change applied - Passing tests (if your project has a test suite) - A ready-to-push commit with a conventional commit message -- A plan recording the run: beside the epic's `tickets.toml` for a ticket, - otherwise `plan-.md` in the active initiative's folder, or directly - in the output folder when no initiative is active. It +- A plan recording the run: beside the epic's `tickets.toml` for a ticket, in + `backlog/` for a backlog ticket, otherwise `plan-.md` in the active + initiative's folder, or directly in the output folder when no initiative is + active. It carries the ticket's status, which the build leaves at `built` until you mark the ticket done @@ -156,7 +160,8 @@ For generated API and end-to-end coverage of the finished work, see ## Deferred Work Each run stays focused on one goal. If your request contains several independent -goals, or review finds pre-existing issues unrelated to your change, +goals and you choose to split them, or review finds pre-existing issues +unrelated to your change, `bmad-build` writes them to `deferred-work.md` in the active initiative's folder, or in the output folder when no initiative is active, instead of trying to do everything at once. @@ -194,8 +199,8 @@ decisions may set patterns for later work. Once those patterns are stable, | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `bmad-build` | Implement and review one direct intent or ticket with human checkpoints (this page) | Plan + code | | `bmad-build-auto` | Implement and review one ticket unattended for a caller or orchestrator ([Autonomous Development Loops](./autonomous-development-loops.md)) | Plan + code + terminal status | -| `bmad-code-review` | Review any code change with several independent reviewers ([Review a Change](./review-a-change.md)) | Findings + applied patches | -| `bmad-correct-course` | Assess the impact of a significant mid-sprint change ([Break Work into Stories and Track It](../plan/break-work-into-stories-and-track-it.md#correct-course)) | Updated plan or re-routing | +| `bmad-code-review` | Review any code change with several independent reviewers ([Review a Change](./review-a-change.md)) | Findings + the patches you choose to apply | +| `bmad-correct-course` | Assess the impact of a significant mid-sprint change ([Break Work into Stories and Track It](../plan/break-work-into-stories-and-track-it.md#correct-course)) | Change proposal with drafted edits | | `bmad-retrospective` | Review a completed epic against the evidence it left behind ([Finish an Epic](./finish-an-epic.md)) | Retro document, action items, acceptance verdict | Clear one-session work enters `bmad-build` directly. Larger work is sliced diff --git a/docs/build/finish-an-epic.md b/docs/build/finish-an-epic.md index d72bdbcbba..1936295618 100644 --- a/docs/build/finish-an-epic.md +++ b/docs/build/finish-an-epic.md @@ -57,14 +57,14 @@ The retrospective works on one epic folder in the ticket tree that - **The initiative's requirements**: what each ticket's `covers` points at. - **Each ticket's plan and story file**: the plan's triage log, verification, plan changes, and any `## Code Review` blocks; the story - file only when the ticket was refined. + file when the ticket has one. - **The git history**: each plan's diff and commits, from its `baseline_revision` to the next plan's. - **The previous epic's retrospective**: its action items, to check whether they landed. A ticket counts as finished when it is `built`, `done`, or `dropped`. Builds -stop at `built`, and only you mark a ticket done, so the retrospective lists +stop at `built`, and only you, or an orchestrator, mark a ticket done, so the retrospective lists the tickets still at `built` for you to close. ## What You Get diff --git a/docs/build/review-a-change.md b/docs/build/review-a-change.md index e9328c6ca2..33cae346ea 100644 --- a/docs/build/review-a-change.md +++ b/docs/build/review-a-change.md @@ -84,14 +84,14 @@ every layer has reported, triage judges each finding on its own: occurs - **Assign severity** from the verified consequence (`low`, `medium`, `high`) -- **Dismiss** noise, refuted claims, and unsubstantiated claims, with a - recorded reason — never silently +- **Dismiss** noise, refuted claims, and unverified claims that would be + minor even if true, with a recorded reason — never silently - **Route** survivors to **patch**, **defer**, or **decision needed** Patch is an unambiguous code fix. Defer is a real pre-existing issue that -is not this change. Decision needed is an ambiguous choice that requires -you. Without a plan, decision needed is not used — those findings go to -patch or defer. +is not this change, or a serious claim triage could not verify. Decision +needed is an ambiguous choice that requires you. Without a plan, decision +needed is not used — those findings go to patch or defer. You get a findings summary. With a plan, each run appends a dated block of findings to the plan's `## Code Review` section; without one, the @@ -165,8 +165,9 @@ review quality. Some runtimes have no subagents. Vendors, including Anthropic and OpenAI, sometimes ship changes that alter how subagents run. Until BMad catches up, the lenses execute one after another instead of in -parallel — or they fall back to the main session, which is far worse -for review quality than it sounds. +parallel. With no subagents at all, the skill writes each lens's +prompt to a file and asks you to run it in a separate session and +paste back the findings. If a review that usually runs for ten minutes suddenly takes an hour, or becomes inexplicably stupid, resume that session and ask why. diff --git a/docs/build/test-completed-work.md b/docs/build/test-completed-work.md index 2e06e8aa70..021d9d9a4e 100644 --- a/docs/build/test-completed-work.md +++ b/docs/build/test-completed-work.md @@ -20,7 +20,7 @@ is not the manual observations in [Walk Through a Change](walk-through-a-change. | Factor | `bmad-qa-generate-e2e-tests` | `bmad-testarch-automate` | | --- | --- | --- | | **Best for** | Simple coverage of implemented features | Heavier coverage of the same kind of work | -| **Setup** | Included with BMM | Install the TEA module | +| **Setup** | Included with the BMad Method module | Install the TEA module | | **Approach** | Generate from the code that exists | Same, standalone; optional test design improves the run | | **What it covers** | API and E2E; happy path plus a few errors | API, E2E, fixtures, more patterns; optional component tests | diff --git a/docs/customize/add-modules.md b/docs/customize/add-modules.md index ac375d30e4..9e4b88b0be 100644 --- a/docs/customize/add-modules.md +++ b/docs/customize/add-modules.md @@ -1,257 +1,120 @@ --- title: 'Add Modules' -description: Choose an official module, install a module from a Git URL or local path, understand how the installer finds modules, keep them updated, and know where to build your own. +description: Add a module with the Skills CLI and bmad setup, find the ecosystem modules, keep modules updated, and know where to build your own. sidebar: order: 3 --- -BMad extends through modules. Official modules are selected during -`npx bmad-method install` and add agents, workflows, and tasks for a domain -beyond the built-in core and BMM (Agile suite). Custom and community -modules come from any Git repository or local directory and install through -the same installer. Pick an official module first; if you need something -the official set does not cover, install it from a custom source. +Use the Skills CLI to install a module's skills, then ask the `bmad` skill to +run `bmad setup`. A module is a set of skills that belong together, plus one +folder named `bmod-`, the module record, that tells `bmad` about them. +BMad Method (`bmod-method`), the core tools (`bmod-core-tools`), and +Toolsmith (`bmod-toolsmith`) are modules. -## Official modules +## What a Module Adds -Run `npx bmad-method install` and select the modules you want. The installer -downloads, configures, and installs them into your IDE. Each module's own -documentation describes its workflows. +Adding a module needs no installer, registry, or build step. Once a module's skills +are installed, `bmad` finds the module on its next run, and the module gets: -### BMad Builder - -Create custom agents, workflows, and domain-specific modules. - -- **Code:** `bmb` -- **npm:** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) -- **GitHub:** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) - -**Provides:** - -- Agent Builder -- create agents with custom expertise and tools -- Workflow Builder -- design workflows with steps and decision points -- Module Builder -- package agents and workflows into modules others can install -- Interactive setup with YAML configuration and npm publishing support - -### Creative Intelligence Suite - -Agents and frameworks for brainstorming, design thinking, and early -problem-solving. - -- **Code:** `cis` -- **npm:** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) -- **GitHub:** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) - -**Provides:** - -- Innovation Strategist, Design Thinking Coach, and Brainstorming Coach agents -- Problem Solver and Creative Problem Solver for systematic and lateral thinking -- Storyteller and Presentation Master for narratives and pitches -- Ideation frameworks including SCAMPER, Reverse Brainstorming, and problem reframing - -### Game Dev Studio - -Game development workflows for Unity, Unreal, Godot, and custom engines, -from a prototype through to a planned production. Implementation uses -Build. - -- **Code:** `gds` -- **npm:** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) -- **GitHub:** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) - -**Provides:** - -- Game Design Document (GDD) generation workflow -- Game-aware planning and context that feed the standard Build implementation loop -- Narrative design support for characters, dialogue, and world-building -- Coverage for 21+ game types with engine-specific architecture guidance - -### Test Architect (TEA) - -Test strategy, automation guidance, and release-gate decisions through an -agent and nine workflows. Its `bmad-testarch-automate` skill generates -heavier test coverage than the built-in `bmad-qa-generate-e2e-tests`: -fixtures, more test levels, and knowledge-base patterns. See -[Test Completed Work](../build/test-completed-work.md) to choose between -the two. - -- **Code:** `tea` -- **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) -- **GitHub:** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) - -**Provides:** - -- Murat agent (Master Test Architect and Quality Advisor) -- Workflows for test design, ATDD, automation, test review, and traceability -- NFR assessment, CI setup, and framework scaffolding -- P0-P3 prioritization with optional Playwright Utils and MCP integrations - -## Install from a custom source - -A custom module is any module the installer reads from a Git repository or -a local directory instead of the official list. Community modules install -the same way; the -[bmad-plugins-marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace) -repository is where to find their URLs. +- Setup and config questions, which `bmad setup` asks once +- Help that `bmad` answers from, so it can recommend the module's skills +- Its agents and parties in [party mode](./run-multi-agent-discussions.md) +- Offers to install skills that the module's skills require or recommend +- Update checks :::note[Prerequisites] -Requires [Node.js](https://nodejs.org) v20.12+ and `npx` (included with -npm), plus Git for Git URL sources. Custom modules can be selected during a fresh install or added to an -existing installation. +BMad installed in the project; see [How to Install BMad](../start/install-bmad.md). +The Skills CLI needs Node.js, npm, and Git, and `bmad setup` needs +[uv](https://docs.astral.sh/uv/). ::: -### Interactive installation +## Install the Module's Skills -Run `npx bmad-method install`. After the official module selection, the -installer asks: - -:::note[Installer prompt] -Do you want to install custom or community modules (Git URL or local path)? -::: - -Answer yes and enter a source. For a URL source the installer warns -**UNVERIFIED MODULE: This module has not been reviewed by the BMad team. -Only install modules from sources you trust.** For a local path it notes -that changes take effect on reinstall. It then lists the modules it -found so you can pick which to install; modules that are already installed -are pre-checked as updates. You can add another source before the install -continues. - -| Input type | Example | -| --------------------- | ------------------------------------------------- | -| HTTPS URL (any host) | `https://github.com/org/repo` | -| HTTP URL (any host) | `http://host/org/repo` | -| HTTPS URL with subdir | `https://github.com/org/repo/tree/main/my-module` | -| SSH URL | `git@github.com:org/repo.git` | -| URL with `@ref` | `https://github.com/org/repo@v1.2.0` | -| Local path | `/Users/me/projects/my-module` | -| Local path with tilde | `~/projects/my-module` | - -### Non-interactive installation - -Use the `--custom-source` flag to install from the command line. Every -module discovered in the source is installed. +From your project directory, run the Skills CLI with the repository the +module lives in: ```bash -npx bmad-method install \ - --directory . \ - --custom-source /path/to/my-module \ - --tools claude-code \ - --yes +npx skills add / ``` -`--custom-source` without `--modules` installs only core and the custom -modules. To include official modules as well, add `--modules`: +Select your coding tool and the skills you want, and include the module's +`bmod-` record. If you leave the record out, `bmad setup` reports it +missing and offers to install it. -```bash -npx bmad-method install \ - --directory . \ - --modules bmm \ - --custom-source https://gitlab.com/myorg/my-module \ - --tools claude-code \ - --yes -``` - -Multiple sources can be comma-separated. A source that cannot be resolved -is reported and skipped; the remaining sources still install. - -```bash ---custom-source /path/one,https://github.com/org/repo,/path/two -``` +The modules in the BMAD-METHOD repository install the same way. Toolsmith, +for example, is not part of a default method install: run +`npx skills add bmad-code-org/BMAD-METHOD` and select `bmod-toolsmith`, +`bmad-toolsmith`, and `bmad-eval`. -## How the installer finds modules +`bmad setup` reads every skills folder your coding tool loads, so a module +installed in the project works with a `bmad` skill installed globally. -The installer uses one of two modes, chosen by what the source contains: +## Set Up the Module -| Mode | Trigger | Behavior | -| --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | -| Discovery | Source contains `.claude-plugin/marketplace.json` | Lists all plugins from the manifest; you pick which to install | -| Direct | No `marketplace.json` found | Scans the directory for skills (subdirectories with `SKILL.md`), resolves as a single module | +Open your coding tool in the project and ask the `bmad` skill to run +`bmad setup`. For each new module, setup: -Discovery mode is typical for published modules. Direct mode is convenient -when pointing at a skills directory during local development. +- Asks the module's config questions. A team answer goes to the committed `_bmad/config.toml`, a personal one to `_bmad/custom/config.user.toml`; an answer you already gave is never changed. +- Installs the module's scripts under `_bmad/`. +- Names the module's skills you did not install, and the skills its skills require or recommend, and offers to install them. +- Shows the module's post-install message, such as where to start. -:::note[About `.claude-plugin/`] -`.claude-plugin/marketplace.json` is a shared installer convention. It -does not require Claude or Claude APIs, and it does not change which AI -tool you use. +:::note[Install messages] +A module's author can add a message shown before an install or update that +`bmad` runs, and one shown after setup. `bmad` shows each message quoted, as +written, and never follows it as instructions. ::: -## Develop a module locally +Ask for `bmad status` to check the result without changing anything. It +lists each module with its version, scope, and whether an update is +available. -If you are building a module with -[BMad Builder](https://github.com/bmad-code-org/bmad-builder), install it -directly from your working directory: +## Ecosystem Modules -```bash -npx bmad-method install \ - --directory ~/my-project \ - --custom-source ~/my-module-repo/skills \ - --tools claude-code \ - --yes -``` - -Local sources are referenced by path, not copied to a cache. When you change -your module source and reinstall, the installer picks up the latest changes. - -:::caution[Source removal] -If you delete the local source directory after installation, the installed -module files in `_bmad/` are preserved. The module is skipped during updates -until the source path is restored. -::: +These modules live in their own repositories. Each one's documentation +describes what it provides. -## What you get +| Module | What it is for | +| --- | --- | +| [Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | Creative thinking partners for innovation, design thinking, and storytelling. | +| [Game Dev Studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | Ideate, design, and build games in any framework, including Unity, Unreal, Godot, and Phaser. | +| [Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | Enterprise testing add-on for BMad Method. [Test Completed Work](../build/test-completed-work.md) compares its `bmad-testarch-automate` with the built-in test skill. | -After installation, custom modules appear in `_bmad/` alongside official -modules: +## Update Modules -``` -your-project/ -├── _bmad/ -│ ├── core/ # Built-in core module -│ ├── bmm/ # Official module (if selected) -│ ├── my-module/ # Your custom module -│ │ ├── my-skill/ -│ │ │ └── SKILL.md -│ │ └── module-help.csv -│ └── _config/ -│ └── manifest.yaml # Tracks all modules, versions, and sources -└── ... -``` - -The manifest records the source of each custom module (`repoUrl` for Git -sources, `localPath` for local sources) so that updates can locate the -source again. +Ask `bmad` to run `bmad setup` again. When a module has a newer version, it +runs `npx skills update`, then asks any new config questions, moves your +`_bmad/custom/` files when a skill was renamed, and offers to delete skills +the module renamed or removed. Last, it checks whether a migration applies +and asks before running it. -## Update modules +A module installed through a plugin marketplace is updated there; update it, +then ask for `bmad setup`. -Custom modules participate in the normal update flow: +## Build Your Own Module -- **Quick update** (`--action quick-update`): Refreshes installed modules - from their recorded sources. A module whose source is no longer available - is skipped with a warning; its files stay in place. A Git source that - cannot be reached is not refreshed; the cached clone is used with a - warning. -- **Full update** (`--action update`): Re-runs module selection so you can - add or remove custom modules. With `--yes` and no `--action`, passing - `--custom-source` defaults to a full update instead of a quick update. +[Toolsmith](../toolsmith/toolsmith.md) is the module for authoring BMad +content. Its agent, Smithy (`bmad-toolsmith`), builds a skill or an agent from +a conversation and packages skills as a module. Nothing is written until you +approve a read-back, and the read-back says how the new skill registers with +`bmad`: -## Create your own module +| Registration | What it means | +| --- | --- | +| Plain skill | No module record. It works, but `bmad` never recommends it, and setup and update checks skip it. | +| Single-skill module | Its own record in the same folder, so setup asks its questions, help recommends it, and updates are checked. | +| Member of an existing module | Joins that module, takes that module's prefix, and is added to its record. | +| First skill of a new module | A new record folder plus the skill. | -Use [BMad Builder](https://github.com/bmad-code-org/bmad-builder) to create -modules that others can install: +A module can also be one skill, or only personas and parties for party mode, +with no skills. -1. Run `bmad-module-builder` to scaffold your module structure -2. Add skills, agents, and workflows with the BMad Builder tools -3. Publish to a Git repository or share the folder -4. Others install with `--custom-source ` +To extend BMad Method in your project, make your own module with your own +prefix, whose skills require or recommend the method skills they build on. +Its skills never take a `bmad-` name, and it never edits the installed +`bmod-method` record, which the next update would overwrite. To contribute to BMad Method itself, +open a pull request to the BMAD-METHOD repository. -For modules to support discovery mode, include a -`.claude-plugin/marketplace.json` in your repository root. See the -[BMad Builder documentation](https://github.com/bmad-code-org/bmad-builder) -for the `marketplace.json` format. - -:::tip[Test locally first] -During development, install your module with a local path to iterate quickly -before publishing to a Git repository. -::: +Build in the module's source repository, not in the installed copy, which +the next update overwrites. Push the repository, and others install it with +`npx skills add /` and run `bmad setup`. diff --git a/docs/customize/adopt-bmad-across-a-team.md b/docs/customize/adopt-bmad-across-a-team.md index f523c0f3c0..99e3a218e3 100644 --- a/docs/customize/adopt-bmad-across-a-team.md +++ b/docs/customize/adopt-bmad-across-a-team.md @@ -155,7 +155,7 @@ teams share one repository, each can point at its own template from **File:** `_bmad/custom/config.toml` (team) or `_bmad/custom/config.user.toml` (personal). Use central config to change who roster-driven skills (`bmad-party-mode`, -`bmad-retrospective`, `bmad-advanced-elicitation`) see, and to pin install +`bmad-advanced-elicitation`, `bmad-forge-idea`) see, and to pin setup answers the whole team shares. Per-skill files shape how one agent behaves when it activates; central config shapes what other skills see when they look at the roster. See @@ -173,13 +173,14 @@ file layout. description = "Mary the Regulatory-Aware Business Analyst — channels Porter and Minto, but lives and breathes FDA audit trails. Speaks like a forensic investigator presenting a case file." ``` -Party mode introduces Mary with the new description. It does not change -how she works when she activates; that still comes from her `[agent]` -override, as in recipe 1. +Party mode and the other roster skills voice Mary with the new description +in place of her shipped persona; her name, title, and icon stay with her +skill. It does not change how she works when she activates; that still +comes from her `[agent]` override, as in recipe 1. ### 5b. Add a fictional agent -**Key:** `[agents.]` with a `team` value. +**Key:** `[agents.]`. A full descriptor is enough for roster features; no skill folder is needed. Personal files suit this, since a cast is a matter of taste. @@ -188,44 +189,43 @@ needed. Personal files suit this, since a cast is a matter of taste. # _bmad/custom/config.user.toml (personal — gitignored) [agents.spock] -team = "startrek" name = "Commander Spock" title = "Science Officer" icon = "🖖" description = "Logic first, emotion suppressed. Begins observations with 'Fascinating.' Never rounds up. Counterpoint to any argument that relies on gut instinct." [agents.mccoy] -team = "startrek" name = "Dr. Leonard McCoy" title = "Chief Medical Officer" icon = "⚕️" description = "Country doctor's warmth, short fuse. 'Dammit Jim, I'm a doctor not a ___.' Ethics-driven counterweight to Spock." ``` -Ask party mode to "invite the Enterprise crew": it filters by -`team = "startrek"` and includes Spock and McCoy. You can include real -BMad agents in the same party. +Spock and McCoy join the default party room beside the installed BMad +agents. For a crew that meets only when you call it, save them as party +members in a party of their own instead; see +[Run Multi-Agent Discussions](./run-multi-agent-discussions.md#build-your-own-party). ### 5c. Pin team install settings -**Keys:** `[core] output_folder` and `[core] document_output_language`. +**Key:** `[core] output_folder`. When the team needs one answer for a setting such as where BMad writes its -output, pin it here; it overrides whatever a developer has in their own -config. `output_folder` holds every initiative folder, the ticket tree, and -`backlog/`, so pinning it moves all of them together. +output, pin it here; it overrides the answer recorded in +`_bmad/config.toml`, though a developer's own `_bmad/custom/config.user.toml` +still wins. `output_folder` holds every initiative folder, the ticket tree, +and `backlog/`, so pinning it moves all of them together. ```toml # _bmad/custom/config.toml [core] output_folder = "{project-root}/shared/bmad-output" -document_output_language = "English" ``` -Personal settings such as `user_name`, `communication_language`, and -`user_skill_level` stay in each developer's own `_bmad/config.user.toml`; -the team file should not set them. +Personal answers, from questions whose scope is `user`, stay in each +developer's own `_bmad/custom/config.user.toml`; the team file should not +set them. ## Reinforce global rules in your IDE's session file diff --git a/docs/customize/customize-bmad.md b/docs/customize/customize-bmad.md index 8addbe4018..eb425de79c 100644 --- a/docs/customize/customize-bmad.md +++ b/docs/customize/customize-bmad.md @@ -25,7 +25,7 @@ There are two surfaces: | Surface | File | Shapes | |---|---|---| | Per-skill override | `_bmad/custom/.toml` | How one agent or workflow behaves when it activates: persona, facts, hooks, menu, workflow fields | -| Central configuration | `_bmad/custom/config.toml` | Install answers and the agent roster that other skills read | +| Central configuration | `_bmad/custom/config.toml` | Setup answers and the agent roster that other skills read | `bmad-customize` writes per-skill overrides only. Central configuration is hand-authored; see [Central configuration](#central-configuration). @@ -43,10 +43,10 @@ persistent facts, and activation hooks. The shipped agents are listed in [Agents](../reference/skills-and-agents.md#agents). The per-skill file controls how the agent behaves when it activates. -Central configuration controls how `bmad-party-mode`, `bmad-retrospective`, -and `bmad-advanced-elicitation` introduce the agent. Rewriting Mary's -principles is per-skill; changing the one-line description a party uses -to introduce her is central. +Central configuration can change the persona `bmad-party-mode`, +`bmad-advanced-elicitation`, and `bmad-forge-idea` give the agent when they +cast it. Rewriting Mary's principles is per-skill; changing the description +a party voices her with is central. :::note[Prerequisites] @@ -157,11 +157,11 @@ matching code replaces the shipped item and a new code appends. Each item has exactly one of `skill` or `prompt`: ```toml -# Replace the shipped CE item with your own skill +# Replace the shipped TK item with your own skill [[agent.menu]] -code = "CE" -description = "Create Epics using our delivery framework" -skill = "custom-create-epics" +code = "TK" +description = "Plan epics using our delivery framework" +skill = "custom-plan-epics" # Add a new item [[agent.menu]] @@ -250,7 +250,9 @@ The workflow body begins after step 6. To change a skill's customization for one run only, add `--set key=value` arguments or an `--overrides ` file to the `render_skill.py` -command in its `SKILL.md`. Persistent project and user files stay as they +command in its `SKILL.md`. `bmad-build`, `bmad-build-auto`, +`bmad-code-review`, `bmad-retrospective`, and `bmad-walkthrough` render this +way. Persistent project and user files stay as they are. ```bash @@ -273,68 +275,67 @@ String values can be written as plain text. Other types use TOML syntax: ## Central configuration -Per-skill files cover one agent or workflow. Install answers and the agent -roster live in four TOML files: +Per-skill files cover one agent or workflow. Setup answers and the agent +roster live in three TOML files: ```text -_bmad/config.toml (installer-owned) team scope: install answers + agent roster -_bmad/config.user.toml (installer-owned) user scope: user_name, language, skill level -_bmad/custom/config.toml (human-authored) team overrides (committed) -_bmad/custom/config.user.toml (human-authored) personal overrides (gitignored), including `[core] active_initiative` +_bmad/config.toml (written by bmad setup) team answers (committed) +_bmad/custom/config.toml (hand-written) team pins (committed) +_bmad/custom/config.user.toml (written by bmad setup) personal answers and overrides (gitignored), including `[core] active_initiative` ``` -**Four layers**, merged with the same shape rules: +**Three layers**, merged with the same shape rules: ```text Priority 1 (wins): _bmad/custom/config.user.toml Priority 2: _bmad/custom/config.toml -Priority 3: _bmad/config.user.toml -Priority 4 (base): _bmad/config.toml +Priority 3 (base): _bmad/config.toml ``` -**What lives where.** The installer splits its answers by the `scope:` -declared on each prompt in a module's `module.yaml`: `[core]` and -`[modules.]` answers with scope `team` land in `_bmad/config.toml`, -scope `user` in `_bmad/config.user.toml`. `[agents.]` holds each -agent's descriptor — code, name, title, icon, description, team — taken -from the module's `agents:` block, always team-scoped. - -**Editing rules.** The two installer-owned files are regenerated on every -install; treat them as read-only output. To change an install answer so it -survives reinstall, re-run the installer (it remembers prior answers) or -override the value in `_bmad/custom/config.toml`. The two `_bmad/custom/` -files are never touched by the installer; they are the place for custom -agents, descriptor overrides, and any value you want pinned regardless of -install answers. - -**Rebrand an agent.** Party mode and other roster skills pick up the new -description automatically: +**What lives where.** `bmad setup` asks the config questions each module +declares in its `bmod-` record. An answer whose question has scope +`team` lands in `_bmad/config.toml`, scope `user` in +`_bmad/custom/config.user.toml`. `[core]` holds values such as +`output_folder`, and module answers sit under `[modules.]`. +`[agents.]` tables are optional: they add an agent of your own to the +roster or describe an installed one further. An installed agent's name, +title, and icon come from its own skill and its per-skill override, not +from here. + +**Editing rules.** All three files may be edited by hand. `bmad setup` +never changes an existing value, so to change an answer, edit its key in +the file that holds it; `bmad` shows setup's answers and the file of each. +`_bmad/custom/config.toml` is the place for any value the team wants to +pin over the answers in `_bmad/config.toml`. + +**Rebrand an agent.** Party mode and the other roster skills voice the +agent with the new description in place of its shipped persona: ```toml # _bmad/custom/config.toml [agents.bmad-agent-pm] description = "Healthcare PM — regulatory-aware, stakeholder-driven, FDA-shaped questions first." -icon = "🏥" ``` **Add a fictional agent.** No skill folder is needed; the descriptor alone -lets a party include Kirk, and the `team` field filters who gets invited. -See [Run Multi-Agent Discussions](./run-multi-agent-discussions.md). +puts Kirk in the default party room beside the installed agents. For a cast +that meets only when you call it, define party members instead; see +[Run Multi-Agent Discussions](./run-multi-agent-discussions.md). ```toml # _bmad/custom/config.user.toml [agents.kirk] -team = "startrek" name = "Captain James T. Kirk" title = "Starship Captain" icon = "🖖" description = "Bold, rule-bending commander. Speaks in dramatic pauses." ``` -**Override an install setting.** The override wins over whatever each -developer has in their own config: +**Override a setup answer.** The team value wins over the answer recorded +in `_bmad/config.toml`; a developer's own `_bmad/custom/config.user.toml` +still wins over it: ```toml # _bmad/custom/config.toml @@ -352,7 +353,7 @@ output_folder = "/shared/org-bmad-output" | Swap a workflow's output template | Per-skill: `_bmad/custom/.toml` scalar override | | Rebrand an agent's public descriptor | Central: `_bmad/custom/config.toml` `[agents.]` | | Add a custom or fictional agent to the roster | Central: `_bmad/custom/config.*.toml` new `[agents.]` | -| Pin team-enforced install settings | Central: `_bmad/custom/config.toml` `[modules.]` or `[core]` | +| Pin team setup answers | Central: `_bmad/custom/config.toml` `[modules.]` or `[core]` | | Choose which initiative your documents and tickets go to | Central: `_bmad/custom/config.user.toml` `[core] active_initiative`, or ask the `bmad` skill to switch it | ## Check what resolved @@ -380,6 +381,10 @@ uv run {project-root}/_bmad/scripts/resolve_customization.py \ Replace `{project-root}` with your project root; the skill resolves it for you at activation, but a shell will not. +To see the merged central config, run +`uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}`, +adding `--key core.output_folder` or another dotted key for one value. + `--skill` points at the skill's installed directory; the script derives the skill name from that folder and finds the matching `_bmad/custom/` files itself. Output is always JSON. diff --git a/docs/customize/run-multi-agent-discussions.md b/docs/customize/run-multi-agent-discussions.md index be4496292b..275948f401 100644 --- a/docs/customize/run-multi-agent-discussions.md +++ b/docs/customize/run-multi-agent-discussions.md @@ -109,6 +109,11 @@ party, choose its starting mode, and set house rules for the whole session. Any set of voices becomes a party: a founder squad, a compliance team, the authors of the Agile Manifesto, a room of comedians. +Installed modules can bring their own personas and parties, which appear +with no setup. BMad Method adds The Product Team (`--party product-team`), +its five agents in a planning room. To share a cast beyond one repository, +package it as a module; see [Add Modules](./add-modules.md). + ## The Code Review Crew The Code Review Crew ships alongside the default party as a template to @@ -170,9 +175,11 @@ breaking character. In a remembered party, someone who joined from an open-cast scene or a member you add mid-conversation is kept too; at wrap-up the room offers to save them into the roster. The default installed-agent room remembers unless -you turn it off in `/bmad-customize bmad-party-mode`. Both shipped parties -and any cast you create inline start fresh each time; save a cast as a party -and choose memory to give it one. +you turn it off in `/bmad-customize bmad-party-mode`. The Product Team +remembers too. The Code Review Crew, the Anti-Consensus Club, and any cast +you create inline start fresh each time; save a cast as a party and choose +memory to give it one. To wipe a party's memory, delete its +folder under `{output_folder}/party-mode/memories/`. ## A keepsake of the session diff --git a/docs/existing-codebases/getting-deeper.md b/docs/existing-codebases/getting-deeper.md index ec43158e17..5ada92d3c1 100644 --- a/docs/existing-codebases/getting-deeper.md +++ b/docs/existing-codebases/getting-deeper.md @@ -100,7 +100,7 @@ documentation. Leave the implementation in the working tree for local inspection. ``` -Build asks any questions it needs before it writes a plan. Answer according +Build asks any questions it needs before it presents a plan. Answer according to your own preferences for the new JSON output. There is no single required JSON design for this exercise. diff --git a/docs/existing-codebases/set-and-maintain-project-context.md b/docs/existing-codebases/set-and-maintain-project-context.md index 18bef9dc97..a0aecd8eba 100644 --- a/docs/existing-codebases/set-and-maintain-project-context.md +++ b/docs/existing-codebases/set-and-maintain-project-context.md @@ -22,8 +22,8 @@ before it writes; you approve every change. ## Step 1: Run It -```bash -bmad-project-context +```text +/bmad-project-context ``` Say what you want in plain language — "set up AGENTS.md", "adopt the AGENTS.md @@ -67,8 +67,10 @@ You see the complete block before anything is written. On approval it is written between the `` and `` markers in `AGENTS.md` at the repo root. For a tool that reads a different file, such as Claude Code's `CLAUDE.md`, the skill proposes and verifies a -one-line `@AGENTS.md` import for the tools you use. Everything outside those -markers is left unchanged, and no later run touches it. +one-line `@AGENTS.md` import for the tools you use. Writing the block touches +nothing outside those markers. Text outside them changes only through a change +you have seen and approved, such as moving an instruction you wrote or fixing +a line elsewhere that contradicts the block. It never commits. Changes stay in your working tree for you to review. @@ -85,9 +87,9 @@ At the end it tells you what went in, what was left out, and why. - **Audit** on demand. It re-checks and cuts; the block ends smaller or equal, never larger. -A rule stays until what it is about is gone, or you retire it. "Nothing broke -lately" is never a reason to delete one — a working rule erases the evidence -that it is still needed. +A rule stays until what it is about is gone, a check enforces it, or you +retire it. "Nothing broke lately" is never a reason to delete one — a working +rule erases the evidence that it is still needed. ## What Earns a Line @@ -131,9 +133,10 @@ the block is kept this small, see ## Where the File Lives Monorepo components and nested repositories get their own file under the same -rules, listed as pointers in the parent. A large rule set that only applies to -one directory can move into an `AGENTS.md` in that directory — but only after -checking that the tools you use actually read it there. If they do not, the +rules when their rules are substantial and apply only there, listed as +pointers in the parent. A large rule set that only applies to one directory +can move into an `AGENTS.md` in that directory — but only after checking that +the tools you use actually read it there. If they do not, the rules stay in the root file, each naming the directory it applies to. Commit what the skill writes. The team shares it, and it is versioned with the @@ -149,9 +152,10 @@ tradeoffs and more than one viable shape, the skill tells you to run ## Replaces Two Earlier Skills -:::note[Looking for bmad-generate-project-context or bmad-document-project?] -Both are deprecated and forward here; their trigger phrases still work. If you -have a `project-context.md` from `bmad-generate-project-context`, setup offers -to absorb its content rather than ignore it. `bmad-document-project` -generated repository documentation, which the evidence says not to do. +:::note[Looking for the earlier project-context or documentation skill?] +v7 removed both; this skill replaces them. If you have a `project-context.md` +from the earlier rules-file skill, this skill reads it and offers to absorb its +content, and does not delete the file without your agreement. The earlier +documentation-generating skill generated repository documentation, which the +evidence says not to do. ::: diff --git a/docs/existing-codebases/start-in-an-existing-codebase.md b/docs/existing-codebases/start-in-an-existing-codebase.md index f8657832a2..7418700141 100644 --- a/docs/existing-codebases/start-in-an-existing-codebase.md +++ b/docs/existing-codebases/start-in-an-existing-codebase.md @@ -16,7 +16,7 @@ archived for the few sessions that need it, and out of reach of an ordinary change — an agent doing a small request should not even be able to find it by accident. -For a small change, use `[bmad-build](../build/build-a-change.md)`. +For a small change, use [`bmad-build`](../build/build-a-change.md). For one that needs several coding sessions, run `bmad-spec`, plan its entries with `bmad-ticket`, and Build each entry directly. Then run `bmad-retrospective` on the epic. Keep its joined plans as live status and evidence. If it is bigger than that, treat it as a project and follow [Choose a Planning Path](../plan/choose-a-planning-path.md). Too little planning costs one Build run: Build looks at the code @@ -24,7 +24,7 @@ first, and stops to ask when it cannot settle the intent. Too much planning costs documents nobody reads. When unsure, ask `bmad` rather than deciding alone. It inspects the project and answers questions like "I have an existing Rails app, where should I start?" -It also runs at the end of every workflow to say what comes next. +Ask it again when a workflow ends and you want to know what comes next. Often, the codebase is all you need, but supplementing it with a tight project context in `AGENTS.md` and companion files really @@ -35,7 +35,8 @@ helps. `bmad-project-context` writes a small verified block of agent instructions into your repo's `AGENTS.md`. See [Set and Maintain Project Context](./set-and-maintain-project-context.md) for -how to run it. (The earlier `bmad-document-project` workflow is deprecated) +how to run it. It replaces the earlier documentation-generating workflow, which +v7 removed. Run it when those instructions are missing, stale, or you are not sure they are any good. Skip it when the repo already has an `AGENTS.md`, `CLAUDE.md`, @@ -78,6 +79,32 @@ match the code. Hoping it modernizes on its own continues the pattern. Changing one file and leaving the rest leaves two standards with no record of which one wins. +## Keep the Repository Fit for Agents + +An agent copies the patterns it finds. A codebase that does one thing several +ways, has few tests, or has very large tangled files costs every session +accuracy. If yours is like that, cleanup first pays back in every later +session: make each refactoring its own `bmad-build` change, with tests in +place first. `bmad-qa-generate-e2e-tests` adds API and end-to-end tests for +features that already exist; see [Test Completed Work](../build/test-completed-work.md). +A codebase of decent quality needs none of this. + +If you do not know the code yet, `bmad-walkthrough` guides you through a file, +directory, commit, or PR at your own pace; see +[Walk Through a Change](../build/walk-through-a-change.md). + +Agent-built code drifts: duplicated helpers, near-copies, and patterns that +diverge between sessions. After several stories, and at the end of every epic, +run a refactoring pass as its own `bmad-build` change. `bmad-retrospective` +reports the duplication and drift across an epic's stories, which gives you +the list. + +Keep documentation small. The code is the best documentation for an agent. +Write down only what the code cannot explain — why a decision was made, a +constraint from outside the code, a rule that spans components — as short +numbered decision records in the repository's `docs` folder, and let +`AGENTS.md` say when to consult them. + ## Try It on a Known Tree First [Getting Deeper](./getting-deeper.md) is optional. It walks through one diff --git a/docs/existing-codebases/theory-of-project-context.md b/docs/existing-codebases/theory-of-project-context.md index 0a44fe89b3..f1d118b8ad 100644 --- a/docs/existing-codebases/theory-of-project-context.md +++ b/docs/existing-codebases/theory-of-project-context.md @@ -152,13 +152,13 @@ why refresh and audit exist as their own commands. ## Versus the two replaced skills -`bmad-document-project` scanned an existing repo and generated a documentation -tree — overview, source tree, per-area deep dives. Large, unverified, stale on +The earlier documentation-generating skill scanned an existing repo and +generated a documentation tree — overview, source tree, per-area deep dives. Large, unverified, stale on arrival: the kind of context that makes agents worse. Its valid instinct — understand the repo before working in it — survives as the discovery pass, which now feeds verification instead of prose. -`bmad-generate-project-context` had the right instinct: a single small rules +The earlier rules-file skill had the right instinct: a single small rules file of unobvious, project-specific facts. What it lacked was everything around the file — no verification, no maintenance loop, no way to tell an inference from a confirmed fact. diff --git a/docs/plan/break-work-into-stories-and-track-it.md b/docs/plan/break-work-into-stories-and-track-it.md index 08478aae49..9a83ae5a74 100644 --- a/docs/plan/break-work-into-stories-and-track-it.md +++ b/docs/plan/break-work-into-stories-and-track-it.md @@ -17,9 +17,9 @@ See [Set Up the Ticket Tree](./set-up-the-ticket-tree.md) for store and tracker ## Build an Entry -Say “build story 1.2” to `bmad-build`. It reads the entry and epic, plus an existing refined leaf file, and writes acceptance criteria into its plan. Refinement before building is optional unless the work needs it. +Say “build story 1.2” to `bmad-build`. It reads the entry and epic, plus the leaf file when one was pulled, and writes acceptance criteria into its plan. Refinement before building is optional unless the work needs it. -The plan sits beside `tickets.toml` as `story--plan.md`. Its numeric `ticket` joins the entry. A backlog plan uses its leaf file stem instead. The plan owns status and records the baseline before changes. +The plan sits beside `tickets.toml` as `story--plan.md`. Its `ticket`, the entry's id, joins the entry. A backlog plan uses its leaf file stem instead. The plan owns status and records the baseline before changes. For unattended work, explicitly dispatch a ticket to `bmad-build-auto`, one invocation per ticket. It does not select the next ticket itself. Read [Autonomous Development Loops](../build/autonomous-development-loops.md) before wiring a runner. @@ -35,4 +35,4 @@ Keep completed plans. Deleting one removes the state and evidence later builds, ## Correct Course -Run `bmad-correct-course` when a requirement, architecture choice, or dependency changes significantly. It requires a PRD and your description of the affected work and dependencies. For standalone spec work without a PRD, update the spec with `bmad-spec` instead. Correct-course assesses the available planning documents and writes its proposal as `change-/change-.md` in the active initiative's folder, or in the output folder when none is active, with the edits and a `bmad-ticket` handoff. It does not read or edit the ticket tree. Apply the approved changes through the owning skills, then use `bmad-ticket` to revise the remaining breakdown. +Run `bmad-correct-course` when a requirement, architecture choice, or dependency changes significantly. It requires a PRD or a spec and your description of the affected work and dependencies. For a change that touches only the spec, update the spec with `bmad-spec` instead. Correct-course assesses the available planning documents and writes its proposal as `change-/change-.md` in the active initiative's folder, with the edits and a `bmad-ticket` handoff. With no active initiative, it hands off to `bmad` to set one first. It does not read or edit the ticket tree. Apply the approved changes through the owning skills, then use `bmad-ticket` to revise the remaining breakdown. diff --git a/docs/plan/choose-a-planning-path.md b/docs/plan/choose-a-planning-path.md index 4f63a49c78..abc0c28a76 100644 --- a/docs/plan/choose-a-planning-path.md +++ b/docs/plan/choose-a-planning-path.md @@ -59,7 +59,8 @@ any order. None of them build anything. Condense what they produce and hand | Shared decisions several epics or agents must follow | [Design UX and Architecture](./design-ux-and-architecture.md) | | Agreement, ownership, and sign-off among several people or teams | A PRD as the document the organization owns: [Plan Inside an Organization](./plan-inside-an-organization.md) | -A short list of decisions is often enough on its own. You need a PRD when more +A short list of decisions is often enough on its own. You need a PRD when the +requirements need real detail, compliance or integrations are involved, more than one person must agree on what the product is, or more than one epic must not diverge; otherwise skip it. A multi-epic product runs `bmad-spec` once per epic with those documents as sources. @@ -67,12 +68,14 @@ epic with those documents as sources. ## Planning Skills and What They Produce Every skill in this chapter writes a document you can hand on. The table runs -from analysis through planning to solutioning; each chapter page is linked -from the first skill it covers and explains when its skills fit. In an -installed project, `bmad` recommends the next one. Each document lands in -its own `-/` folder inside the active initiative's folder, or -directly in the output folder (`_bmad-output` by default) when no initiative -is active. +from analysis through planning; each chapter page is linked from the first +skill it covers and explains when its skills fit. In an installed project, +`bmad` recommends the next one. Each document lands in its own +`-/` folder inside the active initiative's folder. When no +initiative is active, most of these skills have you set one first; +`bmad-brainstorming`, `bmad-forge-idea`, `bmad-deep-recon`, and `bmad-prfaq` +instead ask whether the work belongs to one, and work that does not lands +directly in the output folder (`_bmad-output` by default). | Skill | Purpose | Produces | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | @@ -91,7 +94,7 @@ is active. want when you invoke it, or it will ask. `bmad-product-brief` feeds `bmad-prd`, which reads the brief during discovery, but neither requires the other. -![Three columns of planning skills and the files each writes: analysis (brainstorming, forge idea, deep recon, product brief, PRFAQ), planning (PRD, UX, spec), and solutioning (architecture and ticket), all handing off to bmad-build, one session per unit](/diagrams/planning-skills.svg) +![Three columns of planning skills and the files each writes: analysis (brainstorming, forge idea, deep recon, product brief, PRFAQ), planning what to build (PRD, UX, spec), and planning how and in what slices (architecture and ticket), all handing off to bmad-build, one session per unit](/diagrams/planning-skills.svg) ## Size Follows the Intent diff --git a/docs/plan/define-requirements-and-a-specification.md b/docs/plan/define-requirements-and-a-specification.md index 75a860653c..e6561af110 100644 --- a/docs/plan/define-requirements-and-a-specification.md +++ b/docs/plan/define-requirements-and-a-specification.md @@ -134,9 +134,9 @@ one run per ticket. No leaf file needs to be pulled first. PRFAQ document with a short summary for the PRD or spec. `bmad-prd`: `prd-.md` and `addendum.md`, or a validation report. `bmad-spec`: `spec-.md` plus supporting files. Each lands in its own `-/` -folder in the active initiative's folder, or in the output folder when no -initiative is active. Exact paths and options belong to each -skill; see +folder in the active initiative's folder. With no initiative active, +`bmad-prfaq` asks whether the work belongs to one, and the other three have you +set one first. Exact paths and options belong to each skill; see [Planning Skills and What They Produce](./choose-a-planning-path.md#planning-skills-and-what-they-produce). ::: diff --git a/docs/plan/design-ux-and-architecture.md b/docs/plan/design-ux-and-architecture.md index acd7911f67..b01bfbc2d1 100644 --- a/docs/plan/design-ux-and-architecture.md +++ b/docs/plan/design-ux-and-architecture.md @@ -61,8 +61,8 @@ already decides a lot of the architecture. Point it at the whole system or at one epic; an epic spine inherits the parent's decisions and records only what the parent left open. When it -finishes, it offers to attach itself to the spec, which is how Build and the -readiness gate find it. Seed +finishes, it offers to attach itself to the spec, which is how Build and +`bmad-ticket` find it. Seed [project context](../existing-codebases/set-and-maintain-project-context.md) from it so every later skill reads the same rules. @@ -95,5 +95,6 @@ changes to an existing UI that already has established patterns. The spine and the UX documents become input to the spec and to [Break Work into Stories and Track It](./break-work-into-stories-and-track-it.md), -where the readiness gate checks that stories do not depend on decisions -nothing records. +where `bmad-ticket` checks each breakdown before you approve it: nothing may +contradict the architecture, and every decision two or more epics must adopt +needs a home. diff --git a/docs/plan/explore-and-validate-an-idea.md b/docs/plan/explore-and-validate-an-idea.md index 33ba5e4e13..f64e763904 100644 --- a/docs/plan/explore-and-validate-an-idea.md +++ b/docs/plan/explore-and-validate-an-idea.md @@ -43,13 +43,13 @@ obvious ideas on it. You choose the stance for the session: Tell it what you are brainstorming and why; the goal shapes which techniques it offers. You pick a batch of techniques, or let it choose, and it runs each -until it stops producing, aiming well past a hundred ideas before it lets you -wrap. Say when you want to narrow and it switches to prioritizing and +until it stops producing, aiming past a hundred ideas and resisting an early +wrap-up. Say when you want to narrow and it switches to prioritizing and deciding. Sessions can be paused and resumed. -You get an HTML record of the session, and a short `brainstorm-.md` -holding only the chosen discoveries, shaped to feed `bmad-spec`, -`bmad-product-brief`, or `bmad-prd`. +At wrap-up it offers an HTML record of the session (Ideate for me makes it +without asking) and a short `brainstorm-.md` holding only the chosen +discoveries, shaped to feed `bmad-spec`, `bmad-product-brief`, or `bmad-prd`. ## Pressure-Test an Idea with Forge Idea diff --git a/docs/plan/plan-inside-an-organization.md b/docs/plan/plan-inside-an-organization.md index e08a83832e..4d318f5060 100644 --- a/docs/plan/plan-inside-an-organization.md +++ b/docs/plan/plan-inside-an-organization.md @@ -85,12 +85,12 @@ regenerated from it. | Designer | `bmad-ux` | `DESIGN.md`, `EXPERIENCE.md` | | Tech lead or architect | `bmad-architecture` | The architecture spine | | One engineer, per epic | `bmad-spec`, `bmad-ticket`, Build per story, `bmad-retrospective` | That epic: its spec, its `tickets.toml`, its verdict | -| Whoever tracks the whole | `bmad-ticket` | The ticket tree and plan statuses | +| Whoever tracks the whole | `bmad-ticket` | The ticket tree and marking tickets done | The rows are roles, not headcount. One person can hold several; what matters is that each document has exactly one owner, because each has exactly one -skill that writes it. An epic is a handful of Build sessions, usually a day's -work for one person. The organization's coordination lives in the PRD and the +skill that writes it. An epic is typically eight to twelve Build sessions, usually +one person's work. The organization's coordination lives in the PRD and the spine; the epic itself never needs a committee. ## Where Sign-Off Happens diff --git a/docs/plan/research-a-decision.md b/docs/plan/research-a-decision.md index ad23058551..5de2ff7136 100644 --- a/docs/plan/research-a-decision.md +++ b/docs/plan/research-a-decision.md @@ -109,6 +109,7 @@ fastest. **Refresh** re-checks only those claims and records what changed. | Refresh an existing report | "refresh the market research" | | Customize defaults | `/bmad-customize bmad-deep-recon` | -The v6 `bmad-market-research`, `bmad-domain-research`, and -`bmad-technical-research` skills merged into Deep Recon as the `market`, -`domain`, and `technical` types; the old names still forward here. +The separate v6 market, domain, and technical research skills are now Deep +Recon's `market`, `domain`, and `technical` types, and no skill remains under +the old names. Name the type in your request, or pick `MR`, `DR`, or `TR` from +the Analyst's menu (`bmad-agent-analyst`). diff --git a/docs/plan/set-up-the-ticket-tree.md b/docs/plan/set-up-the-ticket-tree.md index 6de1887da7..83700ff64a 100644 --- a/docs/plan/set-up-the-ticket-tree.md +++ b/docs/plan/set-up-the-ticket-tree.md @@ -29,7 +29,7 @@ The initiative store is the folder where planning lives: one folder per initiati The store is your BMad output folder, `_bmad-output` by default. You can configure it to be any folder; the example below uses `_bmad-initiative-store` instead, and step 2 shows the setting. In a single repo, the default inside the project works fine. -When the work spans several repos, install BMad in the workspace folder that holds them and put the store there too. Start your AI tool from that workspace folder, so one session can reach the plan and every repo it touches. Give the store its own `git init`, which keeps planning history apart from each repo's code history. +When the work spans several repos, install BMad in the workspace folder that holds them and put the store there too. Start your AI tool from that workspace folder, so one session can reach the plan and every repo it touches. Give the store its own `git init`, which keeps planning history apart from each repo's code history. For each code repo, a bare clone with a worktree per branch lets several branches stay open at once, so agents working in parallel do not collide in one checkout. ``` shop-workspace/ # start your AI tool here; not a repo itself @@ -44,7 +44,7 @@ shop-workspace/ # start your AI tool here; not a repo i │ │ ├── epic-cart-rules.md │ │ ├── tickets.toml # every planned story, in build order │ │ ├── story-cart-service-scaffold-plan.md # the build's plan, with the story's status -│ │ └── story-cart-ui-shell.md # a story's file, only when refined or published +│ │ └── story-cart-ui-shell.md # a story's file, only when reviewed, refined, or published │ ├── initiative-loyalty-program/ │ └── backlog/ │ └── bug-checkout-total-ignores-discount-codes.md @@ -142,9 +142,9 @@ It takes almost any input. The best input is a `bmad-spec` output together with | "Review the stories" | Writes each story's file from its entry if needed, then reviews and improves it with you: description, check, references, order, and prerequisites. | | "File a bug: checkout ignores discounts" | Writes one ticket straight into `backlog/`, with no epic needed. | -Each initiative and epic keeps its breakdown in a `tickets.toml` file beside its ticket file. The initiative's file lists the epics in build order. An epic's file lists every planned story and bug as an entry, in build order, each with an `id` that names it under the epic: what it delivers, how it will be verified, what it waits on (`after`), and what is still uncertain. When something must be settled before implementation, the skill asks you to answer it or records it as the entry's `unknown`. It adds a spike when you ask for one. By default the last entry is a "Refactor sweep" story for cleanup found during the epic. +Each initiative and epic keeps its breakdown in a `tickets.toml` file beside its ticket file. The initiative's file lists the epics in build order. An epic's file lists every planned story and bug as an entry, in build order, each with an `id` that names it under the epic: what it delivers, how it will be verified, what it waits on (`after`), and what is still uncertain. When something must be settled before implementation, the skill asks you to answer it or records it as the entry's `unknown`. It adds a spike when you ask for one. By default an epic of more than three entries closes with a "Refactor sweep" story for cleanup found during the epic. -An entry needs no file to be built. `bmad-build` plans the story's acceptance criteria when it builds, from the epic and the entry, so detail is not written months before it is used. It writes that plan beside `tickets.toml`, as `story--plan.md`, and the plan is never sent to a tracker. A story gets its own file only when you refine it or publish it to a tracker. From then on the file is truth: refining edits the file, and the entry keeps only the story's `id`, `type`, `title`, prerequisites (`after`, edited in both places), and `hitl`. +An entry needs no file to be built. `bmad-build` plans the story's acceptance criteria when it builds, from the epic and the entry, so detail is not written months before it is used. It writes that plan beside `tickets.toml`, as `story--plan.md`, and the plan is never sent to a tracker. A story gets its own file only when you review it, refine it, or publish it to a tracker. From then on the file is truth: refining edits the file, and the entry keeps only the story's `id`, `type`, `title`, prerequisites (`after`, edited in both places), and `hitl`. A story's `after` can name a story in another epic, or a whole epic. Ask "what's next?" about the initiative to see every epic at once. @@ -158,13 +158,13 @@ When your source contradicts the code, the skill records a `Source conflict:` li ## Hand a Story to Build -Name the story to `bmad-build`, for example "build story 1.2" for the second story of the first epic. There is no file to write first. Build reads the story's entry and its epic, plus the story file when you refined one. It plans the story's acceptance criteria from the epic's Requirements and Done when, the entry's description, and its `Verify:` check. +Name the story to `bmad-build`, for example "build story 1.2" for the second story of the first epic. There is no file to write first. Build reads the story's entry and its epic, plus the story file when it has one. It plans the story's acceptance criteria from the epic's Requirements and Done when, the entry's description, and its `Verify:` check. :::note[Refining is optional] A story needs no refining before `bmad-build`. Build refines it as part of the build: it questions you and writes the acceptance criteria itself. If you will build unattended, with `bmad-build-auto`, a loop, or a factory, nobody answers questions during the build, so review the sequence and each story with `bmad-ticket` first. `bmad-ticket` writes full acceptance criteria only for a bug, a ticket with no epic, or when you ask. ::: -The story's `status` lives in the build's plan. Build moves it as it works and stops at `built`; only you, or an orchestrator, mark a story done. When you have checked the work, say "mark story 1.2 done" to `bmad-ticket`. On the repo store that is an edit to the plan that you commit with your work. With a tracker, say "start story 1.2" before you build, so the ticket publishes if it has not and its card moves to in progress. The tracker's status is read into the story's file as `tracker_status`, so moving a card on the board never makes build skip planning. +The story's `status` lives in the build's plan. Build moves it as it works and stops at `built`; only you, or an orchestrator, mark a story done. When you have checked the work, say "mark story 1.2 done" to `bmad-ticket`. On the repo store that is an edit to the plan, which the skill commits. With a tracker, say "start story 1.2" before you build, so the ticket publishes if it has not and its card moves to in progress. The tracker's status is read into the story's file as `tracker_status`, so moving a card on the board never makes build skip planning. ## Tell Us What You Find diff --git a/docs/reference/skills-and-agents.md b/docs/reference/skills-and-agents.md index fd53c3ed1d..0aa87aa7b3 100644 --- a/docs/reference/skills-and-agents.md +++ b/docs/reference/skills-and-agents.md @@ -55,10 +55,6 @@ The BMad Method module installs five named agents. Load one with its skill ID, t | Developer (Amelia) | `bmad-agent-dev` | `BD`, `QA`, `CR`, `ER`, `TK` | Build; QA test generation; code review; epic retrospective; ticket planning and tracking | | UX Designer (Sally) | `bmad-agent-ux-designer` | `CU` | UX design | -:::note[Where is Paige?] -The Technical Writer (Paige) is on hiatus. Project context lives on: use the Analyst's `PC` code or invoke `bmad-project-context` directly. -::: - The Developer's `QA` code runs `bmad-qa-generate-e2e-tests`; the full Test Architect is a separate module. See [Test Completed Work](../build/test-completed-work.md). Each agent is an identity plus a customizable layer. See [Customize BMad](../customize/customize-bmad.md) for how that model works and how to change an agent. @@ -170,13 +166,9 @@ The BMad Method module adds the five agents above and these workflow skills. The | `bmad-qa-generate-e2e-tests` | Generate automated API and end-to-end tests for implemented features | [Test Completed Work](../build/test-completed-work.md) | | `bmad-retrospective` | Review a completed epic against its evidence and decide whether to accept it | [Finish an Epic](../build/finish-an-epic.md) | -## Deprecated Names - -Earlier skill IDs, such as `bmad-create-prd`, `bmad-edit-prd`, `bmad-market-research`, `bmad-generate-project-context`, and `bmad-checkpoint-preview`, still resolve as forwarders to the current skill. Use the current names in new work. - ## Naming and Modules -Every skill uses the `bmad-` prefix followed by a descriptive name: `bmad-agent-dev`, `bmad-prd`, `bmad-build`. Modules add their own skills under the same prefix; see [Add Modules](../customize/add-modules.md). +Every skill BMad ships uses the `bmad-` prefix followed by a descriptive name: `bmad-agent-dev`, `bmad-prd`, `bmad-build`. A module of your own takes a prefix of its own, such as `acme-release-notes` with the record `bmod-acme`, and never a `bmad-` name; see [Add Modules](../customize/add-modules.md). ## Troubleshooting @@ -184,4 +176,6 @@ Every skill uses the `bmad-` prefix followed by a descriptive name: `bmad-agent- **Expected skills are missing.** The skills CLI installs only the skills you named. Run `npx skills add bmad-code-org/BMAD-METHOD` again with the missing `--skill` entries, then `bmad setup`, and check that the skill directories exist. -**Skills from a removed module still appear.** The installer does not delete old skill directories. Remove the stale directories, or delete the whole skills directory and re-run the installer for a clean set. +**Skills a module no longer ships still appear.** Run `bmad setup`. It offers to delete them. + +**Skills from a removed module still appear.** `bmad setup` only knows the skills of installed modules. Remove the stale directories, or delete the whole skills directory and re-run the installer for a clean set. diff --git a/docs/reference/upgrade-from-v6.md b/docs/reference/upgrade-from-v6.md new file mode 100644 index 0000000000..829ecf5f9f --- /dev/null +++ b/docs/reference/upgrade-from-v6.md @@ -0,0 +1,121 @@ +--- +title: 'How to Upgrade from v6' +description: Move a BMad v6 project to v7 with bmad setup and bmad migrate method, and handle the breaking changes. +sidebar: + order: 2 +--- + +Use the `bmad` skill's `bmad setup` and `bmad migrate method` to move a project from BMad v6 to v7: install the v7 skills, clean up the skills v7 retired, and move your v6 planning and implementation files into the v7 initiative layout. + +## When to Use This + +- The project was installed with BMad v6. +- The project holds v6 planning documents, epics, sprint tracking, or story files. +- You customized or configured skills and settings that v7 renamed or removed. + +:::note[Prerequisites] +[uv](https://docs.astral.sh/uv/) is required. Setup stops without it. +::: + +## Install the v7 Skills + +Skills replace the v6 installer. From the project directory, run `npx skills add bmad-code-org/BMAD-METHOD`, or install from a plugin marketplace. [Install BMad](../start/install-bmad.md) lists the skills to select and the marketplace commands. + +## Run Setup + +Ask the `bmad` skill to run `bmad setup`. It is one flow that checks the installation, reports what it found, and fixes what you choose. It always asks before deleting anything or running a migration. + +- **Runtime.** It installs the shared scripts and each module's scripts under `_bmad/`, and asks any new config questions. +- **Updates.** When a module has a newer version, it runs `npx skills update` for you. +- **Renamed skills.** It moves a renamed skill's `_bmad/custom/` files to the new name when no file of that name exists yet. When both exist, you merge them. +- **Retired skills.** It offers to delete renamed and removed skills still in your skills folders, including ones your v6 install left behind, and says when a customization no longer applies. +- **Migrations.** It ends by checking whether a migration applies and asking whether to run it. + +Retired skills with a replacement: + +| v6 skill | In v7 | +| --- | --- | +| `bmad-sprint-planning`, `bmad-create-epics-and-stories` | Removed; `bmad-ticket` replaces both. | +| `bmad-create-ux-design` | Renamed to `bmad-ux`. | +| `bmad-agent-builder`, `bmad-workflow-builder`, `bmad-module-builder` | Removed; Toolsmith's `bmad-toolsmith` agent replaces them. | +| `bmad-eval-runner` | Renamed to `bmad-eval`. | +| `bmad-bmm-document-project`, `bmad-bmm-generate-project-context` | Removed; `bmad-project-context` replaces both. | + +Setup lists every other retired skill it finds. + +## Migrate Your v6 Files + +Accept setup's offer, or ask `bmad` to run `bmad migrate method`. The migration reads your files first, shows what it found, and changes nothing until you approve its plan. + +### What Counts as v6 + +The migration looks in your v6 planning and implementation folders and in the output folder. Any of these makes it worth running: + +| v6 file | In v7 | +| --- | --- | +| `epics.md` or `sprint-status.yaml` | A ticket tree: `tickets.toml` in the initiative and in each epic folder. The originals move to `archive-v6/` unchanged. | +| Story files named `--.md` or `spec---.md` with `route:` and `status:` in frontmatter | A plan, `story--plan.md`, beside its entry in the epic folder. A story that has not started can fold into its entry instead. | +| Dated folders such as `prds/prd--/prd.md` | `prd-/prd-.md`, with the date kept in `created` frontmatter. | +| `specs/spec-/SPEC.md` | `spec-/spec-.md`, with its companions unchanged. | + +It applies only while no active initiative is set and no `initiative-*/` folder under the output folder holds a file of the same name. A project that has those, with `tickets.toml` and a ticketing store config, is already on v7: the migration says so and stops, unless you name v6 leftovers to bring in. + +### The v7 Layout + +``` +/ +├── initiative-/ +│ ├── initiative-.md # the initiative envelope +│ ├── tickets.toml # one [[epic]] per epic, in build order +│ ├── prd-/prd-.md # each planning document in its own folder +│ ├── epic-/ +│ │ ├── epic-.md # the epic envelope +│ │ ├── tickets.toml # one [[entry]] per story +│ │ └── story--plan.md # a v6 build record; owns status +│ ├── archive-v6/ # the v6 tracking sources, unchanged +│ └── migration-v6-v7/migration-v6-v7.md # the plan and verification record +├── backlog/ # stories and bugs with no epic +└── inbox/ # v6 work with no home yet +``` + +No name the migration writes carries a date or a v6 story or epic number. No file is deleted: files that do not join the initiative go to `inbox/` or `archive-v6/`, or stay where they are. + +### Plan and Approve + +The migration asks its questions together, each with a default, so "all defaults" is an answer: + +| Question | Default | +| --- | --- | +| Back up the output folder first? A clean, committed git folder already counts as a backup. | Yes | +| Is the work one initiative or several, and what is each called? | One, named after the project | +| Will the work touch other repositories? If so, `_bmad/` and the planning files move into a workspace folder above them. | No | +| Keep the planning files' git history in their own repository? | No | +| Finish stories in progress or in review in v6 first, or migrate now? | Finish first | +| Fold the story files of unstarted stories into their entries and archive them? | Yes | + +It writes the plan to `migration-v6-v7/migration-v6-v7.md` in the output folder. The plan lists which files join the initiative and the evidence for each, which go to `inbox/`, which stay, and which are archived, plus each story's new entry and status. Correct the lists once and approve. Until then, the only things written are the plan and the backup. Under git, every move is a `git mv`, so history follows the file, and in an existing repository the migration commits after each group of moves. It never pushes. + +## Check the Result + +The migration runs its checklist, records each result in the plan, and fixes or reports each failure. It then reports the ticket tree's status, the archived sources, the files left in place, and plans with no baseline revision. Then: + +1. Read the checklist results in the plan, now at `migration-v6-v7/migration-v6-v7.md` in the initiative folder. +2. Update the references the report lists outside the output folder and `_bmad/`. The migration finds them but never edits them. +3. If the migration created a repository for the planning files, accept its initial commit, or the tree stays uncommitted. +4. Delete the backup when you no longer need it. It is yours to delete. + +Next, run `bmad-build` on the next entry, `bmad-retrospective` on an epic, or `bmad-project-context` for a root `AGENTS.md` that names the active initiative. + +## Handle the Breaking Changes + +| Change | What to do | +| --- | --- | +| `planning_artifacts` and `implementation_artifacts` are no longer read or seeded. | Run `bmad migrate method`. It finds your v6 files through them and moves those files into the initiative layout. | +| The ticketing store's `root` key is gone. The ticket tree is `{output_folder}/{active_initiative}`. | To move the store, set `core.output_folder` in `_bmad/custom/config.toml`. | +| `active_initiative` moved from `[modules.bmm]` to `[core]` in `_bmad/custom/config.user.toml`. | If you set it on a preview build, move the line. The migration and `bmad` write it under `[core]`. | +| `bmad-preview-ticketing` is now `bmad-ticket`, and no forwarder remains under the old name. | Run `bmad setup`. It moves the skill's `_bmad/custom/` file to `bmad-ticket.toml`, offers to delete the old skill, and offers to install `bmad-ticket`. | +| Web bundles are removed: the `web-bundles/` folder, its packager, and its docs pages. | Gemini Gems and ChatGPT Custom GPTs are deprecated, and both platforms are replacing them with skills. Use BMad's skills instead. | + +## What You Get + +The project runs the v7 skills, with the retired ones deleted where you agreed. Your v6 planning documents, epics, and stories sit in one initiative folder as a ticket tree whose plans own status, and that initiative is active. The v6 tracking sources are archived unchanged, and the plan records every question, answer, and check. diff --git a/docs/start/build-your-first-change.md b/docs/start/build-your-first-change.md index 9aaef63cd8..88fdc9ea91 100644 --- a/docs/start/build-your-first-change.md +++ b/docs/start/build-your-first-change.md @@ -17,10 +17,11 @@ project. This tutorial follows the coherent request goes directly to the `bmad-build` skill. :::note[Before You Start] -Use a macOS or Linux shell with Node.js 20.12+, Python 3, and a coding tool -supported by BMad. The exact install and launch commands below are for Claude -Code. If you use another supported tool, select it when installing BMad and run -the `bmad-build` skill there instead. +Use a macOS or Linux shell with Node.js 20.12+, Python 3, +[uv](https://docs.astral.sh/uv/), and a coding tool supported by BMad. The +exact install and launch commands below are for Claude Code. If you use another +supported tool, select it when installing BMad and run the `bmad-build` skill +there instead. ::: ## Create an Empty Project diff --git a/docs/start/install-bmad.md b/docs/start/install-bmad.md index b11fd7b9f4..dd7720720d 100644 --- a/docs/start/install-bmad.md +++ b/docs/start/install-bmad.md @@ -17,7 +17,7 @@ From your project directory, run: npx skills add bmad-code-org/BMAD-METHOD ``` -Select your coding tool and skills. Include `bmad` for setup and help, and the module records `bmod-core-tools` and `bmod-method` for the modules you use. To install a small set by name: +Select your coding tool and skills. Include `bmad` for setup and help, and the module records `bmod-core-tools`, `bmod-method`, and `bmod-toolsmith` for the modules you use. To install a small set by name: ```bash npx skills add bmad-code-org/BMAD-METHOD --skill bmad --skill bmod-core-tools --skill bmod-method --skill bmad-build --skill bmad-ticket @@ -53,6 +53,8 @@ Ask the `bmad` skill to run `bmad setup` again. It checks each module's version If you update by hand with `npx skills update`, run `bmad setup` afterwards. For plugins, use your marketplace's update flow, then `bmad setup`. Restart your coding tool when its skill catalog needs refreshing. +To move a project from BMad v6, follow [Upgrade from v6](../reference/upgrade-from-v6.md). + ## What You Get Your coding tool discovers the installed skills. The project's `_bmad/` holds shared configuration and supporting scripts. Team and personal customizations live under `_bmad/custom/` and survive setup refreshes.