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.