From 2aab028f96b5d1cc800640793ec23ad4f7570f7f Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Thu, 5 Feb 2026 17:57:40 -0700 Subject: [PATCH] docs: rename brownfield to established projects (#1539) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: rename brownfield to established projects Flatten how-to/brownfield/ subdirectory and replace jargon term "brownfield" with more accessible "established projects" throughout. - brownfield/index.md → established-projects.md - brownfield/quick-fix-in-brownfield.md → quick-fixes.md - brownfield-faq.md → established-projects-faq.md - Update all internal links and references * docs: remove redundant phrase from quick-fixes description * docs: restore natural language in established-projects body --- docs/_STYLE_GUIDE.md | 4 +- docs/explanation/brownfield-faq.md | 55 ------------------- docs/explanation/established-projects-faq.md | 48 ++++++++++++++++ .../index.md => established-projects.md} | 12 ++-- ...ck-fix-in-brownfield.md => quick-fixes.md} | 4 +- docs/reference/workflow-map.md | 2 +- 6 files changed, 57 insertions(+), 68 deletions(-) delete mode 100644 docs/explanation/brownfield-faq.md create mode 100644 docs/explanation/established-projects-faq.md rename docs/how-to/{brownfield/index.md => established-projects.md} (84%) rename docs/how-to/{brownfield/quick-fix-in-brownfield.md => quick-fixes.md} (93%) diff --git a/docs/_STYLE_GUIDE.md b/docs/_STYLE_GUIDE.md index e5fb51ff..3e78387a 100644 --- a/docs/_STYLE_GUIDE.md +++ b/docs/_STYLE_GUIDE.md @@ -147,7 +147,7 @@ your-project/ | **Concept** | `what-are-agents.md` | | **Feature** | `quick-flow.md` | | **Philosophy** | `why-solutioning-matters.md` | -| **FAQ** | `brownfield-faq.md` | +| **FAQ** | `established-projects-faq.md` | ### General Template @@ -325,7 +325,7 @@ Add italic context at definition start for limited-scope terms: - `*BMad Method/Enterprise.*` - `*Phase N.*` - `*BMGD.*` -- `*Brownfield.*` +- `*Established projects.*` ### Glossary Checklist diff --git a/docs/explanation/brownfield-faq.md b/docs/explanation/brownfield-faq.md deleted file mode 100644 index 1c9b3b82..00000000 --- a/docs/explanation/brownfield-faq.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "Brownfield Development FAQ" -description: 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 - -- [Questions](#questions) - - [What is brownfield vs greenfield?](#what-is-brownfield-vs-greenfield) - - [Do I have to run document-project for brownfield?](#do-i-have-to-run-document-project-for-brownfield) - - [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project) - - [Can I use Quick Spec Flow for brownfield projects?](#can-i-use-quick-spec-flow-for-brownfield-projects) - - [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-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 - -You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system. - -### What if I forget to run document-project? - -Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date. - -### 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. - -### 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](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it! diff --git a/docs/explanation/established-projects-faq.md b/docs/explanation/established-projects-faq.md new file mode 100644 index 00000000..e940b4db --- /dev/null +++ b/docs/explanation/established-projects-faq.md @@ -0,0 +1,48 @@ +--- +title: "Established Projects FAQ" +description: Common questions about using BMad Method on established projects +--- +Quick answers to common questions about working on established projects with the BMad Method (BMM). + +## Questions + +- [Do I have to run document-project first?](#do-i-have-to-run-document-project-first) +- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project) +- [Can I use Quick Flow for established projects?](#can-i-use-quick-flow-for-established-projects) +- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices) + +### Do I have to run document-project first? + +Highly recommended, especially if: + +- No existing documentation +- Documentation is outdated +- AI agents need context about existing code + +You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system. + +### What if I forget to run document-project? + +Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date. + +### Can I use Quick Flow for established projects? + +Yes! Quick Flow works great for established projects. It will: + +- Auto-detect your existing stack +- Analyze existing 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. + +### What if my existing code doesn't follow best practices? + +Quick 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](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it! diff --git a/docs/how-to/brownfield/index.md b/docs/how-to/established-projects.md similarity index 84% rename from docs/how-to/brownfield/index.md rename to docs/how-to/established-projects.md index 75bab690..b756691c 100644 --- a/docs/how-to/brownfield/index.md +++ b/docs/how-to/established-projects.md @@ -1,15 +1,11 @@ --- -title: "Brownfield Development" +title: "Established Projects" description: How to use BMad Method on existing codebases --- Use BMad Method effectively when working on existing projects and legacy codebases. -## What is Brownfield Development? - -**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate. - -This guide covers the essential workflow for onboarding to brownfield projects with BMad Method. +This guide covers the essential workflow for onboarding to existing projects with BMad Method. :::note[Prerequisites] - BMad Method installed (`npx bmad-method install`) @@ -80,5 +76,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th ## More Information -- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes -- **[Brownfield FAQ](/docs/explanation/brownfield-faq.md)** - Common questions about brownfield development +- **[Quick Fixes](/docs/how-to/quick-fixes.md)** - Bug fixes and ad-hoc changes +- **[Established Projects FAQ](/docs/explanation/established-projects-faq.md)** - Common questions about working on established projects diff --git a/docs/how-to/brownfield/quick-fix-in-brownfield.md b/docs/how-to/quick-fixes.md similarity index 93% rename from docs/how-to/brownfield/quick-fix-in-brownfield.md rename to docs/how-to/quick-fixes.md index 9dc430f1..5b6cfe35 100644 --- a/docs/how-to/brownfield/quick-fix-in-brownfield.md +++ b/docs/how-to/quick-fixes.md @@ -1,6 +1,6 @@ --- -title: "How to Make Quick Fixes in Brownfield Projects" -description: How to make quick fixes and ad-hoc changes in brownfield projects +title: "Quick Fixes" +description: How to make quick fixes and ad-hoc changes --- Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow. diff --git a/docs/reference/workflow-map.md b/docs/reference/workflow-map.md index 1425c469..0df3d3ec 100644 --- a/docs/reference/workflow-map.md +++ b/docs/reference/workflow-map.md @@ -73,7 +73,7 @@ Skip phases 1-3 for small, well-understood work. Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions. -For brownfield projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand. +For established projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand. All implementation workflows load `project-context.md` if it exists. Additional context per workflow: