mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
12d3492e0c
* feat: add link auditor tools and fix broken docs links - Add audit-doc-links.js to scan docs for broken links with auto-resolution - Add fix-doc-links.js to apply suggested fixes (dry-run by default) - Remove stale "Back to Core Concepts" breadcrumb links - Update BMad acronym to "Breakthrough Method of Agile AI Driven Development" - Update README links to docs.bmad-method.org - Simplify upgrade callout in getting-started tutorial Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: reorganize docs structure and archive v4 tutorial - Remove unused section index files (tutorials, how-to, explanation, reference) - Move getting-started-bmadv4.md to _archive - Update quick-start-bmgd.md to remove archived file reference - Update upgrade-to-v6.md - Update astro.config.mjs for new structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: ignore underscore directories in link checker Update check-doc-links.js to skip _archive, _planning, and other underscore-prefixed directories when validating links. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add v4 users section to README Add links to v4 documentation archive and upgrade guide for users migrating from previous versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * feat: convert docs to site-relative links and add validation tools - Convert all relative links (./ ../) to site-relative paths (/path/) - Strip .md extensions and use trailing slashes for Astro/Starlight - Add fix-doc-links.js to convert relative links to site-relative - Add validate-doc-links.js to check links point to existing files - Remove old audit-doc-links.js and check-doc-links.js - Update build-docs.js to use new validation script - Add npm scripts: docs:fix-links, docs:validate-links - Update style guide with validation steps Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: standardize acronym to BMad across documentation Replace incorrect "BMAD" with correct "BMad" in text and frontmatter while preserving "BMAD-METHOD" in GitHub URLs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: fix BMad acronym and remove draft README - Correct acronym to "Breakthrough Method of Agile AI Driven Development" - Remove unused README-draft.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: standardize BMad acronym in README Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: standardize FAQ format across all FAQ pages - Add TOC with jump links under "## Questions" - Use ### headers for questions (no Q: prefix) - Direct answers without **A:** prefix - Remove horizontal rules and "Related Documentation" sections - End each FAQ with issue/Discord CTA - Update style guide with new FAQ guidelines - Delete redundant faq/index.md (sidebar handles navigation) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: use repo-relative links with .md for GitHub compatibility Convert all documentation links to repo-relative format (/docs/path/file.md) so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix and converts .md to trailing slash at build time for Astro/Starlight. - Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths - Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension - Convert 217 links across 64 files to new format Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix: handle /docs/ prefix in link validator Update resolveLink to strip /docs/ prefix from repo-relative links before checking if files exist. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: restore FAQ index page Re-add the FAQ index page that was accidentally deleted, with updated repo-relative link format. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
3.0 KiB
3.0 KiB
title, description
| title | description |
|---|---|
| Brownfield Development FAQ | Common questions about brownfield development in the BMad Method |
Quick answers to common questions about brownfield (existing codebase) development in the BMad Method (BMM).
Questions
- What is brownfield vs greenfield?
- Do I have to run document-project for brownfield?
- What if I forget to run document-project?
- Can I use Quick Spec Flow for brownfield projects?
- How does workflow-init handle old planning docs?
- What if my existing code doesn't follow best practices?
What is brownfield vs greenfield?
- Greenfield — New project, starting from scratch, clean slate
- Brownfield — Existing project, working with established codebase and patterns
Do I have to run document-project for brownfield?
Highly recommended, especially if:
- No existing documentation
- Documentation is outdated
- AI agents need context about existing code
- Level 2-4 complexity
You can skip it if you have comprehensive, up-to-date documentation including docs/index.md.
What if I forget to run document-project?
Workflows will lack context about existing code. You may get:
- Suggestions that don't match existing patterns
- Integration approaches that miss existing APIs
- Architecture that conflicts with current structure
Run document-project and restart planning with proper context.
Can I use Quick Spec Flow for brownfield projects?
Yes! Quick Spec Flow works great for brownfield. It will:
- Auto-detect your existing stack
- Analyze brownfield code patterns
- Detect conventions and ask for confirmation
- Generate context-rich tech-spec that respects existing code
Perfect for bug fixes and small features in existing codebases.
How does workflow-init handle old planning docs?
workflow-init asks about YOUR current work first, then uses old artifacts as context:
- Shows what it found (old PRD, epics, etc.)
- Asks: "Is this work in progress, previous effort, or proposed work?"
- If previous effort: Asks you to describe your NEW work
- Determines level based on YOUR work, not old artifacts
This prevents old Level 3 PRDs from forcing Level 3 workflow for a new Level 0 bug fix.
What if my existing code doesn't follow best practices?
Quick Spec Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
- Yes → Maintain consistency with current codebase
- No → Establish new standards (document why in tech-spec)
BMM respects your choice — it won't force modernization, but it will offer it.
Have a question not answered here? Please open an issue or ask in Discord so we can add it!