bmad-code-org__bmad-method/docs/index.md at feat-set-flag-1663

mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00

Files

T

Brian 0dbfae675b feat(skills): TOML-based agent and workflow customization (#2284 )

* feat(skills): TOML-based agent customization with stdlib Python resolver

Re-applies PR #2282's three-layer customization model (skill defaults →
team → user) but swaps YAML for TOML and uv for stdlib tomllib. Users
no longer need uv, pip, or a virtualenv — plain python3 (3.11+) is
sufficient, since tomllib shipped in the standard library.

## Schema changes vs PR #2282

- Flat agent schema: fields live directly under [agent], no nested
  metadata/persona sub-tables. Easier to author, less indentation.
- Non-configurable identity: name and title are declared in
  customize.toml as source-of-truth metadata (for future skill-manifest
  generation) but SKILL.md ignores overrides there — identity is
  hardcoded to preserve brand recognition.
- role redefined: now describes what the skill does for the user
  within its module phase, not a restatement of the title.
- persistent_facts replaces the activation-time file-context load AND
  the old memories concept. Entries can be literal sentences or
  file: prefixed paths/globs; avoids collision with the upcoming
  runtime memory sidecar.
- activation_steps_prepend / activation_steps_append harmonized across
  agents and workflows (replaces agent-specific critical_actions).
- [workflow] namespace mirrors [agent] for workflow customization.
  Same four structural rules, same field vocabulary.

## Resolver (src/scripts/resolve_customization.py)

Four purely structural merge rules, zero field-name hardcoding:

  - Scalars: override wins
  - Tables: deep merge
  - Arrays of tables where every item has `code` or `id`: merge by
    that key (matching keys replace, new keys append)
  - Any other array: append

No removal mechanism — overrides cannot delete base items. Fork the
skill or override by code with a no-op value to suppress defaults.

## Agents ported (6)

All six BMad agents now ship customize.toml + rewritten SKILL.md:
analyst (Mary), tech-writer (Paige), pm (John), ux-designer (Sally),
architect (Winston), dev (Amelia). Each uses the same 8-step
activation template: resolve → execute prepend → adopt persona →
load persistent facts → load config → greet (with {agent.icon}) →
execute append → dispatch or present menu.

Step 8 supports fast-path invocation: "hey Mary, let's brainstorm"
dispatches the matching menu item directly after greeting, skipping
the menu render when intent is clear. Chat, clarifying questions,
and bmad-help remain available when nothing on the menu fits.

## Installer + tooling

- _bmad/scripts/ provisioned on install (copies src/scripts/)
- _bmad/custom/ seeded with .gitignore for *.user.toml on fresh install
- Non-module-dir filter extended to skip _memory, memory, docs,
  scripts, and custom when scanning for modules
- Dead _config/agents/ directory no longer created
- metadata.capabilities removed from agent-manifest.csv and schema
- eslint config extended to cover src/scripts/**
- validate-file-refs.js knows about custom/ as install-only

## Deferred for follow-up

- bmad-product-brief workflow port (the pilot that demonstrates
  [workflow] + on_complete)
- Translated docs (cs/fr/vi-vn/zh-cn) — regenerate from English

* feat(skills): port bmad-product-brief to TOML workflow customization

Completes the customization surface rollout by giving the product-brief
workflow the same override model as the six BMad agents, under the
[workflow] namespace instead of [agent].

## customize.toml

Mirrors the agent shape under [workflow] with:
- activation_steps_prepend / activation_steps_append (harmonized across
  agents and workflows — same field names, same append semantics)
- persistent_facts with the file: convention, seeded with
  file:{project-root}/**/project-context.md
- on_complete scalar (renamed from PR #2282's skill_end for clarity —
  reads cleaner as "what runs when the workflow completes")

## SKILL.md

7-step workflow activation:
  1. Resolve workflow block
  2. Execute prepend steps
  3. Load persistent facts (file: or literal)
  4. Load config
  5. Greet if not already
  6. Execute append steps
  7. Stage 1 — Understand Intent

python3 + stdlib tomllib invocation; no uv required.

## Prompt file changes

- Path normalization: ../agents/ → agents/, ../resources/ → resources/,
  bare foo.md → prompts/foo.md. All references now resolve from the
  skill root (matches the convention documented in SKILL.md).
- Paths: meta-line added to each of the 4 prompt files that reference
  other files, reinforcing "bare paths resolve from skill root" so the
  LLM doesn't lose the convention when operating two hops into a
  prompt chain.
- finalize.md terminal stage now calls the resolver for
  workflow.on_complete — non-empty values run as the final step.

## Validation

- Resolver output verified: 4 workflow fields returned cleanly.
- validate-file-refs.js: 254 files scanned, 139 refs checked, 0 broken.
- test:refs: passing.

* docs(skills): enterprise customization recipes + workflow template variable

Three independent improvements bundled because they share the same
surface (workflow/agent customization) and landed from the same design
discussion:

## Fallback sentence disambiguated (7 SKILL.md files)

The "if the script fails" fallback used to say `{project-root}/_bmad/
custom/{skill-name}.toml` for the team override and then just `{skill-
name}.user.toml` for the user override, leaving the user file's
location implicit. LLMs could reasonably guess skill root or project
root instead. Replaced with an unambiguous numbered list that spells
out the full path for every file in the merge chain.

## Product-brief: stage promotion + brief_template variable

- Promoted `## Stage 1: Understand Intent` from a nested step inside
  "On Activation" to a top-level section. The previous "Step 7: Stage
  1 — Understand Intent → Proceed to Stage 1 below" was mechanical
  numbering pretending to be a step. Activation now ends cleanly at
  Step 6; Stage 1 is a peer section.
- Added `brief_template` as a workflow-level scalar customization
  defaulting to `resources/brief-template.md`. Stage 4 reads
  `{workflow.brief_template}` instead of the hardcoded path, so orgs
  can point at their own template under `{project-root}/...` without
  forking the skill.

## New doc: docs/how-to/extend-bmad-for-your-org.md

Four worked recipes that together cover most enterprise scenarios:

1. Shape an agent across every workflow it dispatches (dev agent +
   Context7 MCP + Linear search — the highest-leverage pattern)
2. Enforce org conventions inside a specific workflow (product-brief
   + compliance-field persistent_facts)
3. Publish completed outputs to external systems (product-brief +
   Confluence + Jira via MCP, gated on user confirmation for Jira)
4. Swap in your own output template (product-brief + brief_template
   variable swap)

Opens with the two-layer mental model (agent spans workflows,
workflow is local) so readers pick the right granularity before
reading any recipe. Closes with a "Combining Recipes" section
showing all four composed. Cross-linked from customize-bmad.md.

## Validation

- Resolver: workflow.brief_template returns the default cleanly.
- validate-file-refs.js: 254 files scanned, 146 refs checked
  (+7 from this commit), 0 broken.

* docs(skills): encourage CLAUDE.md/AGENTS.md reinforcement of critical rules

Added a "Reinforce Global Rules in Your IDE's Session File" section to
extend-bmad-for-your-org.md. BMad customizations only load when a
skill activates, but IDE session files (CLAUDE.md, AGENTS.md, cursor
rules, copilot-instructions) load every turn — worth restating the
most critical rules there too so they survive ad-hoc chat outside a
BMad skill.

Includes a one-line example reinforcing the Recipe 1 Context7 rule,
plus a scope table that clarifies what each layer is for:
  - IDE session file: universal, every session, keep succinct
  - Agent customization: persona-specific, every dispatched workflow
  - Workflow customization: one workflow run

Emphasizes brevity — noise in the session file crowds out signal.

* docs(skills): add Named Agents explanation doc

New docs/explanation/named-agents.md walking through the three-legged
stool (skills + named agents + customization) with the "Hey Mary,
let's brainstorm" activation flow as the narrative thread.

Covers:
- Why named agents vs menu-driven or prompt-driven alternatives
- The 8-step activation flow and what each step contributes
- How customization scales the model beyond a single developer
- Cross-links to the how-to docs for implementation details

Sits alongside brainstorming.md, quick-dev.md, party-mode.md in the
explanation folder — feature narratives for users who want to
understand why BMad is designed the way it is, not just how to use it.

* docs(skills): clarify that keyed-merge requires a single identifier key per array

Review feedback (PR #2284) flagged that the merge-rules wording was
ambiguous: "every item has a `code` or `id` field" could reasonably
be read as "each item individually has at least one of the two",
allowing arrays to mix `code` and `id` across items.

The resolver has always required all items share the *same* identifier
key (all `code`, or all `id`). Mixed arrays fall through to append —
intentional, because mixing identifier keys within one array is a
schema smell and any guess about which key should merge creates a
worse trap than the append-fallback.

Clarified in three places:
- Merge-rules table in customize-bmad.md: "every item shares the
  **same** identifier field"
- `code`/`id` convention paragraph: "pick **one** convention ... and
  stick with it across the whole array"
- Resolver docstring and `_detect_keyed_merge_field` docstring:
  explicit note that mixed arrays fall through with rationale

No behavior change.

* docs(skills): address CodeRabbit review — fallback rules, OS claim, headless greeting

Three fixes from PR #2284 review feedback:

## 1. Fallback merge wording (7 SKILL.md files)

Every SKILL.md told the LLM to merge the three customization files
"in priority order (later wins)" when the resolver fails. That reads
as shallow last-write-wins — but the resolver does structural merge
(scalars override, tables deep-merge, code/id-keyed arrays merge by
key, other arrays append). Following the old wording manually would
have silently stripped base `principles`, `persistent_facts`, and
`menu` items whenever a team override was present.

Expanded the fallback sentence to restate the four structural rules
explicitly, matching the resolver's behavior.

Applied to all 6 agents + bmad-product-brief workflow.

## 2. Python 3.11 / OS shipping claim (customize-bmad.md)

The docs claimed "macOS 13+, Ubuntu 22.04+, Debian 12+, Fedora 37+
all ship 3.11 or newer." Inaccurate — Ubuntu 22.04 defaults `python3`
to 3.10.6 (3.11 is a separate package), and macOS doesn't really
ship Python by default anymore.

Replaced with honest guidance: check `python3 --version` and note
that macOS without Homebrew and Ubuntu 22.04 default to 3.10 or
earlier.

## 3. Autonomous mode greeting gate (bmad-product-brief)

Product-brief's activation-mode detection documents autonomous mode
as "produce complete brief without interaction" — but Step 5 greeted
unconditionally, adding conversational output before the headless
artifact. Gated the greeting on `{mode}` != `autonomous`.

## Dismissed (replied on thread)

- `.gitignore` migration from *.user.yaml to *.user.toml: YAML
  installer code was in reverted #2282, never released. No users
  affected. Same rationale as Augment's earlier thread.

Validated: 254 files, 146 refs, 0 broken. test:refs 7/7,
test:install 242/242.

* docs: rename Extend to Expand throughout customization docs

2026-04-19 19:30:29 -05:00

3.6 KiB

Raw Permalink Blame History

title, description

title	description
Welcome to the BMad Method	AI-driven development framework with specialized agents, guided workflows, and intelligent planning

The BMad Method (Build More Architect Dreams) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform.

If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.

:::note[🚀 V6 is Here and We're Just Getting Started!] Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works. Check out the Roadmap → :::

New Here? Start with a Tutorial

The fastest way to understand BMad is to try it.

Get Started with BMad — Install and understand how BMad works
Workflow Map — Visual overview of BMM phases, workflows, and context management

:::tip[Just Want to Dive In?] Install BMad and use the bmad-help skill — it will guide you through everything based on your project and installed modules. :::

How to Use These Docs

These docs are organized into four sections based on what you're trying to do:

Section	Purpose
Tutorials	Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new.
How-To Guides	Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here.
Explanation	Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know why.
Reference	Information-oriented. Technical specifications for agents, workflows, and configuration.

Expand and Customize

Want to expand BMad with your own agents, workflows, or modules? The BMad Builder provides the framework and tools for creating custom extensions, whether you're adding new capabilities to BMad or building entirely new modules from scratch.

What You'll Need

BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:

Claude Code — Anthropic's CLI tool (recommended)
Cursor — AI-first code editor
Codex CLI — OpenAI's terminal coding agent

You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is required—that's what these docs are for.

3.6 KiB

Raw Permalink Blame History

New Here? Start with a Tutorial

How to Use These Docs

Expand and Customize

What You'll Need

Join the Community

Next Step

3.6 KiB Raw Permalink Blame History

New Here? Start with a Tutorial

How to Use These Docs

Expand and Customize

What You'll Need

Join the Community

Next Step

3.6 KiB

Raw Permalink Blame History