mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-08-29 03:44:18 +08:00
Brian
47bab7d15c
* feat(project-context): rewrite as prescriptive AGENTS.md generator Replace the kernel+bundle context system with a single product: a short verified agent guide (AGENTS.md). A field trial of the first version showed repo scanning produces polished-but-useless factoids; the rewrite fills a fixed section plan from ranked evidence channels (executable config and CI, targeted git history, session logs, human interview) and uses the repository only to verify claims, never as the source of knowledge. - Intents: bootstrap, refresh, record (capture an observed agent mistake), audit; query is gone with the bundle - Per-fact entry files, trust frontmatter, index, placement machinery, and the skill's context.py mechanics script are removed; accountability moves to one plain ledger file recording every candidate claim and its disposition - Skill directory only; docs, forwarding husks, and shared scripts untouched * refactor(project-context): per-section admission rules, two-tier guide Revisions from two end-to-end trials plus review: - Replace the global non-derivable test with per-section admission rules: brevity (orientation), authority (policy), universal need verified by execution (commands, verification), wrong-default-assumption (conventions), localization value (pointers), observed failure only (pitfalls) - Two-tier output: AGENTS.md (orientation + policy + pointer) for every session, AGENTS-dev.md for coding sessions; single file when tiny - Pitfalls can never be nominated by scans: sources are recorded lessons, maintainer recall, session evidence, and the writing session's own caught mistakes; retirement only when the guarded thing is gone or the human says so, since a working rule erases its own evidence - Interview ergonomics: recall questions, never review lists; testimony the repo contradicts is surfaced with evidence, never written or dropped - Trial-driven fixes: guide-to-filesystem link check, mutating-command go-ahead as the interview's first question, plain-English rewrite throughout * fix(project-context): bidirectional coverage trace, history-evidenced pitfalls Round-3 trial findings: an unsourced pitfall entered the guide at composition time because coverage only checked ledger-to-guide; and repeat-fix git history, the strongest pitfall evidence observed, was not an explicitly admitted source. * refactor(project-context): move Where-things-are to AGENTS.md, imperative lines Where-things-are pointers serve planning sessions as much as coding ones, so they belong in the always-loaded file. Shape rules now require every line to state an action (bare facts only as justification clauses) and stable contract headings across runs. * docs(project-context): session-kind guides as a third structural axis A maintainer-named frequent session kind (UX, manual testing, data work) may earn its own AGENTS-<kind>.md behind a pointer; module-level differences stay with scoped guides. * refactor(project-context): action-gated dev-guide pointer, two-file example The AGENTS-dev.md hop is the most common progressive-discovery trigger, so it is now gated on the first hands-on action rather than session self-classification, names its payoff, and names the exemption. The contract's worked example shows the two-file form with the pointer in situ. Scoped-guide discovery no longer assumes harness nearest-file loading: the root-guide pointer is the mechanism. * refactor(project-context): adopt shared memlog, drop unearned claims The run record is now a standard memlog kept with the shared memlog.py script — append-only typed entries, latest entry wins — replacing the bespoke ledger format; stale-disposition notes become structurally impossible. Two appeal-to-measurement assertions cut: the operative admission and exclusion rules carry that load. * docs(project-context): guard handwritten guides The skill never commits — its output stays as working-tree changes for the user. Headless runs never rewrite a guide the memlog doesn't record writing; they leave an AGENTS.md.proposed for an interactive merge. * docs(project-context): fold in prior-art research findings Five adoptions from the generator prior-art survey: prohibitions name their permitted alternative; an emphasis-marker budget; a git-log --diff-filter=DR drift check on refresh; TODO placeholders over guessed greenfield commands; commit and branch conventions mined from history. * docs(project-context): route candidates to enforcement before prose Compose now asks, per accepted candidate, whether a hook, lint rule, or CI check enforces it better than a guide line; the line is the fallback and a landed check deletes it. * docs(project-context): narrow refresh interview and contradiction flagging Refresh interviews shrink to one recall question — what changed since the last run. Cross-file contradictions are flagged only when they change behavior; rewording and overlap are not contradictions. * refactor(project-context): conversational skill, no script, AGENTS.md block Refine the skill into an implementation-layer capability: a conversation that produces one small verified block inside the repo's AGENTS.md. The human is in the loop for every write; there is no autonomous mode. - Drop src/scripts/context.py and its tests. Nothing it did is needed once the output is a single spliced block rather than a bundle of files. - Replace guide-contract.md and evidence.md with best-practices.md (admission, exclusion, retirement, retrieval, maintenance) and template.md (section list plus a worked example, no placeholders). - Collapse the two-file AGENTS.md/AGENTS-dev.md split into one block. A pointer the agent must choose to follow gets skipped; anything load-bearing goes in the always-loaded file. - Replace per-section admission rules with one test: anything derivable from source is read live, never stored. Commands stated in package.json, a Makefile, or CI config no longer earn a line; their caveats do. - Ask up front whether a run covers the root only or named sub-projects, gated on observable evidence (a workspace manifest, per-directory build manifests). - Husk bmad-document-project and bmad-generate-project-context onto setup intent, and say plainly that the deeper system-explanation altitude is a separate capability rather than shipping a thin substitute. - Align module-help.csv, bmad-correct-course, the analyst menu, and the docs set with the block as the output. --------- Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
Agile Ai Driven Development — turn an idea or change request into working software without giving up the thinking.
Ai Driven Development (AiDD) covers the whole effort, not only the code: what to build, how it holds together, and how it changes as you learn. BMad Method is the agile way to do it — decisions stay explicit, context carries forward, and the process sizes itself to the work. Small changes go straight to build. Complex work gets the depth it needs. The same method covers a weekend prototype and a system with years of history behind it.
Start anywhere. Use BMad end to end, or carry its briefs, specifications, and architecture into your existing delivery workflow.
Start Building
Prerequisites: Node.js 20.12+, Python 3.10+, and uv
npx bmad-method install
Open your project in your AI coding tool, invoke bmad-build with what you want to change, and keep making the decisions that matter. Run bmad-help whenever you want guidance on what comes next or what is optional.
Build your first project with BMad →
Add BMad to an existing codebase →
BMad is free and open source, with no paywalled workflows or gated community. For prerelease builds, CI/CD, configuration overrides, and non-interactive setup, see the installation guide.
Why BMad?
Coding assistants are effective at implementation, but they often turn unstated assumptions into code. BMad keeps you in control while its agents and workflows make the important decisions explicit and preserve them as context for the work that follows.
- Right-sized process — Go directly to implementation for clear changes or add deeper planning for larger initiatives.
- New or existing code — Start from nothing, or establish verified context on a codebase you inherited and work from what is actually there.
- Durable context — Carry product and technical decisions forward instead of re-explaining them in every chat.
- Specialized perspectives — Bring in product, architecture, UX, development, and testing expertise when it helps.
- Guided collaboration — Use structured workflows and multiple-agent discussions without handing over judgment.
- One delivery path — Move from early thinking through reviewed implementation, correction, and learning.
See how the workflows fit together →
BMad Ecosystem
Install the core method or add official modules for specialized work.
| Module | Purpose |
|---|---|
| BMad Method | Plan and deliver software, from new prototypes to established codebases |
| BMad Builder | Skill, workflow, and agent builder |
| BMad Creative Intelligence Suite | Creative thinking partners for innovation, design thinking, and storytelling |
| BMad Test Architect | Enterprise testing add-on for BMad Method |
| BMad Loop | Builds, verifies, and retros a whole epic unattended |
| BMad Game Dev Studio | Ideate, design, and build games in any framework, including Unity, Unreal, Godot, and Phaser |
Plan on the Web
Web bundles package selected BMad workflows as Google Gemini Gems and ChatGPT Custom GPTs. Use them for planning in your existing web subscription, then bring the resulting artifacts into your AI coding tool for implementation.
Documentation
- Getting Started — Install BMad and build a small project.
- Workflow Map — Understand the available paths and outputs.
- Established Projects — Add BMad to an existing codebase.
- Upgrade to V6 — Migrate from an earlier version.
Roadmap
See what is in progress and what is planned on the public roadmap.
Community
- Discord — Get help, share ideas, and collaborate.
- YouTube — Watch tutorials and master classes.
- GitHub Issues — Report bugs and request features.
- GitHub Discussions — Join longer community conversations.
- BMad Code — Explore the wider ecosystem.
Support and Contributing
BMad is free for everyone and always will be. Star the repository, buy me a coffee, or email contact@bmadcode.com for corporate sponsorship.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.
License
MIT License — see LICENSE for details.
BMad and BMAD-METHOD are trademarks of BMad Code, LLC. See TRADEMARK.md for details.
See CONTRIBUTORS.md for contributor information.
