bmad-fh 6.0.0-alpha.052779ef

package/docs/how-to/brownfield/add-feature-to-existing.md

@@ -0,0 +1,74 @@
+---
+title: "How to Add a Feature to an Existing Project"
+description: How to add new features to an existing brownfield project
+---
+
+Use the `workflow-init` workflow to add new functionality to your brownfield codebase while respecting existing patterns and architecture.
+
+## When to Use This
+
+- Adding a new feature to an existing codebase
+- Major enhancements that need proper planning
+- Features that touch multiple parts of the system
+
+:::note[Prerequisites]
+- BMad Method installed
+- Existing project documentation (run `document-project` first if needed)
+- Clear understanding of what you want to build
+:::
+
+## Steps
+
+### 1. Run workflow-init
+
+```
+Run workflow-init
+```
+
+The workflow should recognize you're in an existing project. If not, explicitly clarify that this is brownfield development.
+
+### 2. Choose Your Approach
+
+| Feature Scope | Recommended Approach |
+|---------------|---------------------|
+| Small (1-5 stories) | Quick Flow with tech-spec |
+| Medium (5-15 stories) | BMad Method with PRD |
+| Large (15+ stories) | Full BMad Method with architecture |
+
+### 3. Create Planning Documents
+
+**For Quick Flow:**
+- Load PM agent
+- Run tech-spec workflow
+- The agent will analyze your existing codebase and create a context-aware spec
+
+**For BMad Method:**
+- Load PM agent
+- Run PRD workflow
+- Ensure the agent reads your existing documentation
+- Review that integration points are clearly identified
+
+### 4. Consider Architecture Impact
+
+If your feature affects system architecture:
+
+- Load Architect agent
+- Run architecture workflow
+- Ensure alignment with existing patterns
+- Document any new ADRs (Architecture Decision Records)
+
+### 5. Implement
+
+Follow the standard Phase 4 implementation workflows:
+
+1. `sprint-planning` - Organize your work
+2. `create-story` - Prepare each story
+3. `dev-story` - Implement with tests
+4. `code-review` - Quality assurance
+
+## Tips
+
+- Always ensure agents read your existing documentation
+- Pay attention to integration points with existing code
+- Follow existing conventions unless deliberately changing them
+- Document why you're adding new patterns (if any)

package/docs/how-to/brownfield/document-existing-project.md

@@ -0,0 +1,66 @@
+---
+title: "How to Document an Existing Project"
+description: How to document an existing brownfield codebase using BMad Method
+---
+
+Use the `document-project` workflow to scan your entire codebase and generate comprehensive documentation about its current state.
+
+## When to Use This
+
+- Starting work on an undocumented legacy project
+- Documentation is outdated and needs refresh
+- AI agents need context about existing code patterns
+- Onboarding new team members
+
+:::note[Prerequisites]
+- BMad Method installed in your project
+- Access to the codebase you want to document
+:::
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the document-project Workflow
+
+Tell the agent:
+
+```
+Run the document-project workflow
+```
+
+### 3. Let the Agent Scan Your Codebase
+
+The workflow will:
+
+- Scan your codebase structure
+- Identify architecture patterns
+- Document the technology stack
+- Create reference documentation
+- Generate a PRD-like document from existing code
+
+### 4. Review the Generated Documentation
+
+The output will be saved to `project-documentation-{date}.md` in your output folder.
+
+Review the documentation for:
+
+- Accuracy of detected patterns
+- Completeness of architecture description
+- Any missing business rules or intent
+
+## What You Get
+
+- **Project overview** - High-level description of what the project does
+- **Technology stack** - Detected frameworks, libraries, and tools
+- **Architecture patterns** - Code organization and design patterns found
+- **Business rules** - Logic extracted from the codebase
+- **Integration points** - External APIs and services
+
+## Tips
+
+- Run this before any major brownfield work
+- Keep the documentation updated as the project evolves
+- Use it as input for future PRD creation

package/docs/how-to/brownfield/index.md

@@ -0,0 +1,84 @@
+---
+title: "Brownfield Development"
+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.
+
+:::note[Prerequisites]
+- BMad Method installed (`npx bmad-method install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code, Cursor, or Windsurf)
+:::
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+
+- `docs/`
+- `_bmad-output/planning-artifacts/`
+- `_bmad-output/implementation-artifacts/`
+
+## Step 2: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- Intent and business rationale
+- Business rules
+- Architecture
+- Any other relevant project information
+
+For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
+
+## Step 3: Initialize for Brownfield Work
+
+Run `workflow-init`. It should recognize you are in an existing project. If not, explicitly clarify that this is brownfield development for a new feature.
+
+### Choosing Your Approach
+
+You have two primary options depending on the scope of changes:
+
+| Scope                          | Recommended Approach                                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad method is likely overkill. |
+| **Major changes or additions** | Start with the BMad method, applying as much or as little rigor as needed.                                                    |
+
+### During PRD Creation
+
+When creating a brief or jumping directly into the PRD, ensure the agent:
+
+- Finds and analyzes your existing project documentation
+- Reads the proper context about your current system
+
+You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
+
+### UX Considerations
+
+UX work is optional. The decision depends not on whether your project has a UX, but on:
+
+- Whether you will be working on UX changes
+- Whether significant new UX designs or patterns are needed
+
+If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
+
+### Architecture Considerations
+
+When doing architecture, ensure the architect:
+
+- Uses the proper documented files
+- Scans the existing codebase
+
+Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
+
+## Next Steps
+
+- **[Document Existing Project](/docs/how-to/brownfield/document-existing-project.md)** - How to document your brownfield codebase
+- **[Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md)** - Adding new functionality
+- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
+- **[Brownfield FAQ](/docs/explanation/faq/brownfield-faq.md)** - Common questions about brownfield development

package/docs/how-to/brownfield/quick-fix-in-brownfield.md

@@ -0,0 +1,77 @@
+---
+title: "How to Make Quick Fixes in Brownfield Projects"
+description: How to make quick fixes and ad-hoc changes in brownfield projects
+---
+
+Use the **DEV agent** directly for bug fixes, refactorings, or small targeted changes that don't require the full BMad method or Quick Flow.
+
+## When to Use This
+
+- Bug fixes
+- Small refactorings
+- Targeted code improvements
+- Learning about your codebase
+- One-off changes that don't need planning
+
+## Steps
+
+### 1. Load an Agent
+
+For quick fixes, you can use:
+
+- **DEV agent** - For implementation-focused work
+- **Quick Flow Solo Dev** - For slightly larger changes that still need a tech-spec
+
+### 2. Describe the Change
+
+Simply tell the agent what you need:
+
+```
+Fix the login validation bug that allows empty passwords
+```
+
+or
+
+```
+Refactor the UserService to use async/await instead of callbacks
+```
+
+### 3. Let the Agent Work
+
+The agent will:
+
+- Analyze the relevant code
+- Propose a solution
+- Implement the change
+- Run tests (if available)
+
+### 4. Review and Commit
+
+Review the changes made and commit when satisfied.
+
+## Learning Your Codebase
+
+This approach is also excellent for exploring unfamiliar code:
+
+```
+Explain how the authentication system works in this codebase
+```
+
+```
+Show me where error handling happens in the API layer
+```
+
+LLMs are excellent at interpreting and analyzing code—whether it was AI-generated or not. Use the agent to:
+
+- Learn about your project
+- Understand how things are built
+- Explore unfamiliar parts of the codebase
+
+## When to Upgrade to Formal Planning
+
+Consider using Quick Flow or full BMad Method when:
+
+- The change affects multiple files or systems
+- You're unsure about the scope
+- The fix keeps growing in complexity
+- You need documentation for the change