External/BMAD-METHOD
1
0
Fork 0
mirror of https://github.com/bmadcode/BMAD-METHOD.git synced 2025-12-29 16:14:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)

Browse Source 
## 📚 Complete Documentation Restructure

**BMM Documentation Hub Created:**
- New centralized documentation system at `src/modules/bmm/docs/`
- 18 comprehensive guides organized by topic (7000+ lines total)
- Clear learning paths for greenfield, brownfield, and quick spec flows
- Professional technical writing standards throughout

**New Documentation:**
- `README.md` - Complete documentation hub with navigation
- `quick-start.md` - 15-minute getting started guide
- `agents-guide.md` - Comprehensive 12-agent reference (45 min read)
- `party-mode.md` - Multi-agent collaboration guide (20 min read)
- `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read)
- `brownfield-guide.md` - Existing codebase development (53 min read)
- `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read)
- `workflows-analysis.md` - Phase 1 workflows (12 min read)
- `workflows-planning.md` - Phase 2 workflows (19 min read)
- `workflows-solutioning.md` - Phase 3 workflows (13 min read)
- `workflows-implementation.md` - Phase 4 workflows (33 min read)
- `workflows-testing.md` - Testing & QA workflows (29 min read)
- `workflow-architecture-reference.md` - Architecture workflow deep-dive
- `workflow-document-project-reference.md` - Document-project workflow reference
- `enterprise-agentic-development.md` - Team collaboration patterns
- `faq.md` - Comprehensive Q&A covering all topics
- `glossary.md` - Complete terminology reference
- `troubleshooting.md` - Common issues and solutions

**Documentation Improvements:**
- Removed all version/date footers (git handles versioning)
- Agent customization docs now include full rebuild process
- Cross-referenced links between all guides
- Reading time estimates for all major docs
- Consistent professional formatting and structure

**Consolidated & Streamlined:**
- Module README (`src/modules/bmm/README.md`) streamlined to lean signpost
- Root README polished with better hierarchy and clear CTAs
- Moved docs from root `docs/` to module-specific locations
- Better separation of user docs vs. developer reference

## 🤖 New Agent: Paige (Documentation Guide)

**Role:** Technical documentation specialist and information architect

**Expertise:**
- Professional technical writing standards
- Documentation structure and organization
- Information architecture and navigation
- User-focused content design
- Style guide enforcement

**Status:** Work in progress - Paige will evolve as documentation needs grow

**Integration:**
- Listed in agents-guide.md, glossary.md, FAQ
- Available for all phases (documentation is continuous)
- Can be customized like all BMM agents

## 🔧 Additional Changes

- Updated agent manifest with Paige
- Updated workflow manifest with new documentation workflows
- Fixed workflow-to-agent mappings across all guides
- Improved root README with clearer Quick Start section
- Better module structure explanations
- Enhanced community links with Discord channel names

**Total Impact:**
- 18 new/restructured documentation files
- 7000+ lines of professional technical documentation
- Complete navigation system with cross-references
- Clear learning paths for all user types
- Foundation for knowledge base (coming in beta)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
2025-11-02 21:18:33 -06:00
parent 8a00f8ad70
commit cfedecbd53
359 changed files with 72374 additions and 809 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
docs/BMad-Method-V6-Quick-Start.md
View File

@@ -1,341 +0,0 @@
# BMad Method V6 Quick Start Guide
Get started with BMad Method v6 for your new greenfield project. This guide walks you through building software from scratch using AI-powered workflows.
## TL;DR - The Quick Path
1. **Install**: `npx bmad-method@alpha install`
2. **Initialize**: Load Analyst agent → Run "workflow-init"
3. **Plan**: Load PM agent → Run "prd" (or "tech-spec" for small projects)
4. **Architect**: Load Architect agent → Run "create-architecture" (10+ stories only)
5. **Build**: Load SM agent → Run workflows for each story → Load DEV agent → Implement
6. **Always use fresh chats** for each workflow to avoid hallucinations
---
## What is BMad Method?
BMad Method (BMM) helps you build software through guided workflows with specialized AI agents. The process follows four phases:
1. **Phase 1: Analysis** (Optional) - Brainstorming, Research, Product Brief
2. **Phase 2: Planning** (Required) - Create your requirements (tech-spec or PRD)
3. **Phase 3: Architecture** (Conditional) - Design the architecture for complex projects (10+ stories)
4. **Phase 4: Implementation** (Required) - Build your software Epic by Epic, Story by Story
## Installation
```bash
# Install v6 Alpha to your project
npx bmad-method@alpha install
```
The interactive installer will guide you through setup and create a `bmad/` folder with all agents and workflows.
---
## Getting Started
### Step 1: Initialize Your Workflow
1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](../docs/ide-info/) for how to activate agents:
- [Claude Code](../docs/ide-info/claude-code.md)
- [VS Code/Cursor/Windsurf](../docs/ide-info/) - Check your IDE folder
- Other IDEs also supported
2. **Wait for the agent's menu** to appear
3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
#### What happens during workflow-init?
Workflows are interactive processes in V6 that replaced tasks and templates from prior versions. There are many types of workflows, and you can even create your own with the BMad Builder module. For the BMad Method, you'll be interacting with expert-designed workflows crafted to work with you to get the best out of both you and the LLM.
During workflow-init, you'll describe:
- Your project and its goals
- Whether there's an existing codebase or this is a new project
- The general size and complexity (you can adjust this later)
#### Project Scale Levels
Based on your description, the workflow will suggest a level and let you choose from:
**Greenfield Project Levels:**
- **Level 0** - Single atomic change (1 story) - bug fixes, typos, minor updates, single file changes
- **Level 1** - Small feature (1-10 stories) - simple additions, isolated features, one module
- **Level 2** - Medium feature set (5-15 stories) - dashboards, multiple related features, several modules
- **Level 3** - Complex integration (12-40 stories) - platform features, major integrations, architectural changes
- **Level 4** - Enterprise expansion (40+ stories) - multi-tenant, ecosystem changes, system-wide initiatives
#### What gets created?
Once you confirm your level, the `bmm-workflow-status.md` file will be created in your project's docs folder (assuming default install location). This file tracks your progress through all phases.
**Important notes:**
- Every level has different paths through the phases
- Story counts can still change based on overall complexity as you work
- For this guide, we'll assume a Level 2 project
- This workflow will guide you through Phase 1 (optional), Phase 2 (required), and Phase 3 (required for Level 2+ complexity)
### Step 2: Work Through Phases 1-3
After workflow-init completes, you'll work through the planning phases. **Important: Use fresh chats for each workflow to avoid context limitations.**
#### Checking Your Status
If you're unsure what to do next:
1. Load any agent in a new chat
2. Ask for "workflow-status"
3. The agent will tell you the next recommended or required workflow
**Example response:**
```
Phase 1 (Analysis) is entirely optional. All workflows are optional or recommended:
- brainstorm-project - optional
- research - optional
- product-brief - RECOMMENDED (but not required)
The next TRULY REQUIRED step is:
- PRD (Product Requirements Document) in Phase 2 - Planning
- Agent: pm
- Command: /bmad:bmm:workflows:prd
```
#### How to Run Workflows in Phases 1-3
When an agent tells you to run a workflow (like `/bmad:bmm:workflows:prd`):
1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](../docs/ide-info/) for your IDE's specific instructions
2. **Wait for the menu** to appear
3. **Tell the agent** to run it using any of these formats:
- Type the shorthand: `*prd`
- Say it naturally: "Let's create a new PRD"
- Select the menu number for "create-prd"
The agents in V6 are very good with fuzzy menu matching!
#### Quick Reference: Agent → Document Mapping
For v4 users or those who prefer to skip workflow-status guidance:
- **Analyst** → Brainstorming, Product Brief
- **PM** → PRD (10+ stories) OR tech-spec (1-10 stories)
- **UX-Designer** → UX Design Document (if UI-heavy)
- **Architect** → Architecture (10+ stories)
#### Phase 2: Planning - Creating the PRD
**For Level 2+ projects (10+ stories):**
1. Load the **PM agent** in a new chat
2. Tell it to run the PRD workflow
3. Once complete, you'll have two files:
- **PRD.md** - Your Product Requirements Document
- **Epics.md** - High-level epics with stories
**For smaller projects (Levels 0-1):**
- Use **tech-spec** instead of PRD (no architecture needed)
#### Phase 2 (Optional): UX Design
If your project has a user interface:
1. Load the **UX-Designer agent** in a new chat
2. Tell it to run the UX design workflow
3. After completion, run validations to ensure the Epics file stays updated
#### Phase 3: Architecture
**For Level 2+ projects only:**
1. Load the **Architect agent** in a new chat
2. Tell it to run the create-architecture workflow
3. After completion, run validations to ensure the Epics file stays updated
#### Phase 3: Solutioning Gate Check (Highly Recommended)
Once architecture is complete:
1. Load the **Architect agent** in a new chat
2. Tell it to run "solutioning-gate-check"
3. This validates cohesion across all your planning documents (PRD, UX, Architecture, Epics)
4. This was called the "PO Master Checklist" in v4
**Why run this?** It ensures all your planning assets align properly before you start building.
#### Context Management Tips
- **Use 200k+ context models** for best results (Claude Sonnet 4.5, GPT-4, etc.)
- **Fresh chat for each workflow** - Brainstorming, Briefs, Research, and PRD generation are all context-intensive
- **No document sharding needed** - Unlike v4, you don't need to split documents
- **Web Bundles coming soon** - Will help save LLM tokens for users with limited plans
### Step 3: Start Building (Phase 4 - Implementation)
Once planning and architecture are complete, you'll move to Phase 4. **Important: Each workflow below should be run in a fresh chat to avoid context limitations and hallucinations.**
#### 3.1 Initialize Sprint Planning
1. **Start a new chat** with the **SM (Scrum Master) agent**
2. Wait for the menu to appear
3. Tell the agent: "Run sprint-planning"
4. This creates your `sprint-status.yaml` file that tracks all epics and stories
#### 3.2 Create Epic Context (Optional but Recommended)
1. **Start a new chat** with the **SM agent**
2. Wait for the menu
3. Tell the agent: "Run epic-tech-context"
4. This creates technical context for the current epic before drafting stories
#### 3.3 Draft Your First Story
1. **Start a new chat** with the **SM agent**
2. Wait for the menu
3. Tell the agent: "Run create-story"
4. This drafts the story file from the epic
#### 3.4 Add Story Context (Optional but Recommended)
1. **Start a new chat** with the **SM agent**
2. Wait for the menu
3. Tell the agent: "Run story-context"
4. This creates implementation-specific technical context for the story
#### 3.5 Implement the Story
1. **Start a new chat** with the **DEV agent**
2. Wait for the menu
3. Tell the agent: "Run dev-story"
4. The DEV agent will implement the story and update the sprint status
#### 3.6 Review the Code (Optional but Recommended)
1. **Start a new chat** with the **DEV agent**
2. Wait for the menu
3. Tell the agent: "Run code-review"
4. The DEV agent performs quality validation (this was called QA in v4)
### Step 4: Keep Going
For each subsequent story, repeat the cycle using **fresh chats** for each workflow:
1. **New chat** → SM agent → "Run create-story"
2. **New chat** → SM agent → "Run story-context"
3. **New chat** → DEV agent → "Run dev-story"
4. **New chat** → DEV agent → "Run code-review" (optional but recommended)
After completing all stories in an epic:
1. **Start a new chat** with the **SM agent**
2. Tell the agent: "Run retrospective"
**Why fresh chats?** Context-intensive workflows can cause hallucinations if you keep issuing commands in the same chat. Starting fresh ensures the agent has maximum context capacity for each workflow.
---
## Understanding the Agents
Each agent is a specialized AI persona:
- **Analyst** - Initializes workflows and tracks progress
- **PM** - Creates requirements and specifications
- **UX-Designer** - If your project has a front end - this designer will help produce artifacts, come up with mock updates, and design a great look and feel with you giving it guidance.
- **Architect** - Designs system architecture
- **SM (Scrum Master)** - Manages sprints and creates stories
- **DEV** - Implements code and reviews work
## How Workflows Work
1. **Load an agent** - Open the agent file in your IDE to activate it
2. **Wait for the menu** - The agent will present its available workflows
3. **Tell the agent what to run** - Say "Run [workflow-name]"
4. **Follow the prompts** - The agent guides you through each step
The agent creates documents, asks questions, and helps you make decisions throughout the process.
## Project Tracking Files
BMad creates two files to track your progress:
**1. bmm-workflow-status.md**
- Shows which phase you're in and what's next
- Created by workflow-init
- Updated automatically as you progress through phases
**2. sprint-status.yaml** (Phase 4 only)
- Tracks all your epics and stories during implementation
- Critical for SM and DEV agents to know what to work on next
- Created by sprint-planning workflow
- Updated automatically as stories progress
**You don't need to edit these manually** - agents update them as you work.
---
## The Complete Flow Visualized
```
Phase 1 (Optional) Phase 2 (Required) Phase 3 (Conditional) Phase 4 (Required)
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ Analysis │ │ Planning │ │ Architecture │ │ Implementation │
│ │ │ │ │ │ │ │
│ • Brainstorm │ │ Level 0-1: │ │ Level 2+: │ │ Per Epic: │
│ • Research │───────▶│ • tech-spec │───────▶│ • architecture │────────▶│ • epic context │
│ • Brief │ │ │ │ • gate-check │ │ │
│ │ │ Level 2+: │ │ │ │ Per Story: │
│ (Analyst) │ │ • PRD │ │ (Architect) │ │ • create-story │
│ │ │ • UX (opt) │ │ │ │ • story-context │
│ │ │ │ │ │ │ • dev-story │
│ │ │ (PM, UX) │ │ │ │ • code-review │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ (SM, DEV) │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └──────────────────┘
```
## Common Questions
**Q: Do I always need architecture?**
A: Only for larger projects (10+ stories). Small projects can skip straight from tech-spec to implementation.
**Q: Can I change my plan later?**
A: Yes! The SM agent has a "correct-course" workflow for handling scope changes.
**Q: What if I want to brainstorm first?**
A: Load the Analyst agent and tell it to "Run brainstorm-project" before running workflow-init.
**Q: Why do I need fresh chats for each workflow?**
A: Context-intensive workflows can cause hallucinations if run in sequence. Fresh chats ensure maximum context capacity.
**Q: Can I skip workflow-init and workflow-status?**
A: Yes, once you learn the flow. Use the Quick Reference in Step 2 to go directly to the workflows you need.
## Getting Help
- **During workflows**: Agents guide you with questions and explanations
- **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
- **Complete guide**: [BMM Workflows README](../src/modules/bmm/workflows/README.md)
- **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
---
## Key Takeaways
✅ **Always use fresh chats** - Load agents in new chats for each workflow to avoid context issues
✅ **Let workflow-status guide you** - Load any agent and ask for status when unsure what's next
✅ **Level matters** - Small projects (0-1) use tech-spec, larger projects (2+) need PRD and architecture
✅ **Tracking is automatic** - The status files update themselves, no manual editing needed
✅ **Agents are flexible** - Use menu numbers, shortcuts (\*prd), or natural language
**Ready to start building?** Install BMad, load the Analyst, run workflow-init, and let the agents guide you!
---
**Version**: v6-alpha
**Last Updated**: 2025-01
**For detailed documentation**: [Complete BMM Workflows Guide](../src/modules/bmm/workflows/README.md)

1260
docs/bmad-brownfield-guide.md
View File

File diff suppressed because it is too large Load Diff

82
docs/index.md
View File

@@ -8,11 +8,11 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.
**New users:** Start with one of these based on your situation:
| Your Situation | Start Here | Then Read |
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
| **Brand new to BMad** | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) | [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) |
| **Upgrading from v4** | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) |
| **Brownfield project** | [Brownfield Guide](./bmad-brownfield-guide.md) | [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) |
| Your Situation | Start Here | Then Read |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
| **Brand new to BMad** | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) | [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) |
| **Upgrading from v4** | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) |
| **Brownfield project** | [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) | [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) |
---
@@ -27,9 +27,8 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.
### Installation & Setup
- **[BMad Method V6 Quick Start](./BMad-Method-V6-Quick-Start.md)** - Step-by-step guide to building your first project with BMM
- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
- **[Brownfield Guide](./bmad-brownfield-guide.md)** - Guidance for working with existing codebases
- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
---
@@ -39,12 +38,13 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.
The flagship module for agile AI-driven development.
- **[BMM Module README](../src/modules/bmm/README.md)** - Module overview, agents, and structure
- **[BMM Workflows Guide](../src/modules/bmm/workflows/README.md)** - **ESSENTIAL READING** - Complete v6 workflow system explanation
- Phase 1: Analysis (optional)
- Phase 2: Planning (required, scale-adaptive)
- Phase 3: Solutioning (complex projects)
- Phase 4: Implementation (iterative)
- **[BMM Module README](../src/modules/bmm/README.md)** - Module overview, agents, and complete documentation index
- **[BMM Documentation](../src/modules/bmm/docs/)** - All BMM-specific guides and references:
- [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Step-by-step guide to building your first project
- [Quick Spec Flow](../src/modules/bmm/docs/quick-spec-flow.md) - Rapid Level 0-1 development
- [Scale Adaptive System](../src/modules/bmm/docs/scale-adaptive-system.md) - Understanding the 5-level system
- [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Working with existing codebases
- **[BMM Workflows Guide](../src/modules/bmm/workflows/README.md)** - **ESSENTIAL READING**
- **[Test Architect Guide](../src/modules/bmm/testarch/README.md)** - Testing strategy and quality assurance
### BMad Builder (BMB) - Create Custom Solutions
@@ -99,41 +99,40 @@ Instructions for loading agents and running workflows in your development enviro
- [Installers & Platforms Reference](./installers-bundlers/installers-modules-platforms-reference.md) - CLI tool and platform support
- [Web Bundler Usage](./installers-bundlers/web-bundler-usage.md) - Creating web-compatible bundles
### Optimization & Efficiency
- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings in Phase 4 workflows
---
## 📊 Documentation Map
```
docs/
docs/ # Core/cross-module documentation
├── index.md (this file)
├── BMad-Method-V6-Quick-Start.md
├── v4-to-v6-upgrade.md
├── bmad-brownfield-guide.md
├── ide-info/
├── document-sharding-guide.md
├── ide-info/ # IDE setup guides
│ ├── claude-code.md
│ ├── cursor.md
│ ├── windsurf.md
│ └── [14+ other IDEs]
└── installers-bundlers/
└── installers-bundlers/ # Installation reference
├── ide-injections.md
├── installers-modules-platforms-reference.md
└── web-bundler-usage.md
src/
├── modules/
│ ├── bmm/
│ │ ├── README.md
│ │ ├── workflows/README.md (ESSENTIAL)
│ │ └── testarch/README.md
│ ├── bmb/
│ │ ├── README.md
│ │ └── workflows/create-agent/README.md
│ └── cis/
│ └── README.md
src/modules/
├── bmm/ # BMad Method module
│ ├── README.md # Module overview & docs index
│ ├── docs/ # BMM-specific documentation
│ │ ├── quick-start.md
│ │ ├── quick-spec-flow.md
│ │ ├── scale-adaptive-system.md
│ │ └── brownfield-guide.md
│ ├── workflows/README.md # ESSENTIAL workflow guide
│ └── testarch/README.md # Testing strategy
├── bmb/ # BMad Builder module
│ ├── README.md
│ └── workflows/create-agent/README.md
└── cis/ # Creative Intelligence Suite
└── README.md
```
---
@@ -143,7 +142,7 @@ src/
### Path 1: Brand New to BMad (Software Project)
1. [README.md](../README.md) - Understand the vision
2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Get hands-on
2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
3. [BMM Module README](../src/modules/bmm/README.md) - Understand agents
4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
5. [Your IDE guide](./ide-info/) - Optimize your workflow
@@ -151,7 +150,7 @@ src/
### Path 2: Game Development Project
1. [README.md](../README.md) - Understand the vision
2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Get hands-on
2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Get hands-on
3. [BMM Module README](../src/modules/bmm/README.md) - Game agents are included
4. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Game workflows
5. [Your IDE guide](./ide-info/) - Optimize your workflow
@@ -159,13 +158,13 @@ src/
### Path 3: Upgrading from v4
1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Reorient yourself
2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Reorient yourself
3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Learn new v6 workflows
### Path 4: Working with Existing Codebase (Brownfield)
1. [Brownfield Guide](./bmad-brownfield-guide.md) - Approach for legacy code
2. [Quick Start Guide](./BMad-Method-V6-Quick-Start.md) - Follow the process
1. [Brownfield Guide](../src/modules/bmm/docs/brownfield-guide.md) - Approach for legacy code
2. [Quick Start Guide](../src/modules/bmm/docs/quick-start.md) - Follow the process
3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Master the methodology
### Path 5: Building Custom Solutions
@@ -224,10 +223,3 @@ All agent customizations go in `bmad/_cfg/agents/` and survive updates. See your
- #bugs-issues - Bug reports
- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
- **YouTube**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
---
**Version**: v6-alpha
**Last Updated**: 2025-10-30
---

645
docs/quick-spec-flow.md
View File

@@ -1,645 +0,0 @@
# BMad Quick Spec Flow
**Perfect for:** Bug fixes, small features, rapid prototyping, and quick enhancements
**Time to implementation:** Minutes, not hours
---
## What is Quick Spec Flow?
Quick Spec Flow is a **streamlined alternative** to the full BMad Method for Level 0-1 projects. Instead of going through Product Brief → PRD → Architecture, you go **straight to a context-aware technical specification** and start coding.
### When to Use Quick Spec Flow
✅ **Use Quick Spec Flow (Level 0-1) when:**
- Single bug fix or small enhancement (Level 0)
- Small feature with 2-3 related changes (Level 1)
- Rapid prototyping or experimentation
- Adding to existing brownfield codebase
- You know exactly what you want to build
❌ **Use Full BMM Flow (Level 2-4) when:**
- Building new products or major features (Level 2-4)
- Need stakeholder alignment
- Complex multi-team coordination
- Requires extensive planning and architecture
💡 **Not sure?** Run `workflow-init` to get a recommendation based on your project's size and complexity!
---
## Quick Spec Flow Overview
```
┌─────────────────────────────────────────────────────────────┐
│ QUICK SPEC FLOW │
│ (Level 0-1 Projects) │
└─────────────────────────────────────────────────────────────┘
Step 1: Run Tech-Spec Workflow
│
├─► Detects your project stack (package.json, requirements.txt, etc.)
├─► Analyzes brownfield codebase (if exists)
├─► Detects test frameworks and conventions
├─► Confirms conventions with you
├─► Generates context-rich tech-spec
└─► Creates ready-to-implement stories
Step 2: Optional - Generate Story Context (SM Agent)
│
└─► For complex scenarios only
Step 3: Implement (DEV Agent)
│
└─► Code, test, commit
DONE! 🚀
```
---
## Level 0: Single Atomic Change
**Best for:** Bug fixes, single file changes, isolated improvements
### What You Get
1. **tech-spec.md** - Comprehensive technical specification with:
- Problem statement and solution
- Detected framework versions and dependencies
- Brownfield code patterns (if applicable)
- Existing test patterns to follow
- Specific file paths to modify
- Complete implementation guidance
2. **story-[slug].md** - Single user story ready for development
### Quick Spec Flow Commands
```bash
# Start Quick Spec Flow (no workflow-init needed!)
# Load PM agent and run tech-spec
# When complete, implement directly:
# Load DEV agent and run dev-story
```
### What Makes It Quick
- ✅ No Product Brief needed
- ✅ No PRD needed
- ✅ No Architecture doc needed
- ✅ Auto-detects your stack
- ✅ Auto-analyzes brownfield code
- ✅ Auto-validates quality
- ✅ Story context optional (tech-spec is comprehensive!)
### Example Level 0 Scenarios
- "Fix the login validation bug"
- "Add email field to user registration form"
- "Update API endpoint to return additional field"
- "Improve error handling in payment processing"
---
## Level 1: Coherent Small Feature
**Best for:** Small features with 2-3 related user stories
### What You Get
1. **tech-spec.md** - Same comprehensive spec as Level 0
2. **epics.md** - Epic organization with story breakdown
3. **story-[epic-slug]-1.md** - First story
4. **story-[epic-slug]-2.md** - Second story
5. **story-[epic-slug]-3.md** - Third story (if needed)
### Quick Spec Flow Commands
```bash
# Start Quick Spec Flow
# Load PM agent and run tech-spec
# Optional: Organize stories as a sprint
# Load SM agent and run sprint-planning
# Implement story-by-story:
# Load DEV agent and run dev-story for each story
```
### Story Sequencing
Stories are **automatically validated** to ensure proper sequence:
- ✅ No forward dependencies (Story 2 can't depend on Story 3)
- ✅ Clear dependency documentation
- ✅ Infrastructure → Features → Polish order
- ✅ Backend → Frontend flow
### Example Level 1 Scenarios
- "Add OAuth social login (Google, GitHub, Twitter)"
- "Build user profile page with avatar upload"
- "Implement basic search with filters"
- "Add dark mode toggle to application"
---
## Smart Context Discovery
Quick Spec Flow automatically discovers and uses:
### 1. Existing Documentation
- Product briefs (if they exist)
- Research documents
- `document-project` output (brownfield codebase map)
### 2. Project Stack
- **Node.js:** package.json → frameworks, dependencies, scripts, test framework
- **Python:** requirements.txt, pyproject.toml → packages, tools
- **Ruby:** Gemfile → gems and versions
- **Java:** pom.xml, build.gradle → Maven/Gradle dependencies
- **Go:** go.mod → modules
- **Rust:** Cargo.toml → crates
- **PHP:** composer.json → packages
### 3. Brownfield Code Patterns
- Directory structure and organization
- Existing code patterns (class-based, functional, MVC)
- Naming conventions (camelCase, snake_case, PascalCase)
- Test frameworks and patterns
- Code style (semicolons, quotes, indentation)
- Linter/formatter configs
- Error handling patterns
- Logging conventions
- Documentation style
### 4. Convention Confirmation
**IMPORTANT:** Quick Spec Flow detects your conventions and **asks for confirmation**:
```
I've detected these conventions in your codebase:
Code Style:
- ESLint with Airbnb config
- Prettier with single quotes, 2-space indent
- No semicolons
Test Patterns:
- Jest test framework
- .test.js file naming
- expect() assertion style
Should I follow these existing conventions? (yes/no)
```
**You decide:** Conform to existing patterns or establish new standards!
---
## Modern Best Practices via WebSearch
Quick Spec Flow stays current by using WebSearch when appropriate:
### For Greenfield Projects
- Searches for latest framework versions
- Recommends official starter templates
- Suggests modern best practices
### For Outdated Dependencies
- Detects if your dependencies are >2 years old
- Searches for migration guides
- Notes upgrade complexity
### Starter Template Recommendations
For greenfield projects, Quick Spec Flow recommends:
**React:**
- Vite (modern, fast)
- Next.js (full-stack)
**Python:**
- cookiecutter templates
- FastAPI starter
**Node.js:**
- NestJS CLI
- express-generator
**Benefits:**
- ✅ Modern best practices baked in
- ✅ Proper project structure
- ✅ Build tooling configured
- ✅ Testing framework set up
- ✅ Faster time to first feature
---
## UX/UI Considerations
For user-facing changes, Quick Spec Flow captures:
- UI components affected (create vs modify)
- UX flow changes (current vs new)
- Responsive design needs (mobile, tablet, desktop)
- Accessibility requirements:
- Keyboard navigation
- Screen reader compatibility
- ARIA labels
- Color contrast standards
- User feedback patterns:
- Loading states
- Error messages
- Success confirmations
- Progress indicators
---
## Auto-Validation & Quality Assurance
Quick Spec Flow **automatically validates** everything:
### Tech-Spec Validation (Always Runs)
Checks:
- ✅ Context gathering completeness
- ✅ Definitiveness (no "use X or Y" statements)
- ✅ Brownfield integration quality
- ✅ Stack alignment
- ✅ Implementation readiness
Generates scores:
```
✅ Validation Passed!
- Context Gathering: Comprehensive
- Definitiveness: All definitive
- Brownfield Integration: Excellent
- Stack Alignment: Perfect
- Implementation Readiness: ✅ Ready
```
### Story Validation (Level 1 Only)
Checks:
- ✅ Story sequence (no forward dependencies!)
- ✅ Acceptance criteria quality (specific, testable)
- ✅ Completeness (all tech spec tasks covered)
- ✅ Clear dependency documentation
**Auto-fixes issues if found!**
---
## Complete User Journey
### Scenario 1: Bug Fix (Level 0)
**Goal:** Fix login validation bug
**Steps:**
1. **Start:** Load PM agent, say "I want to fix the login validation bug"
2. **PM runs tech-spec workflow:**
- Asks: "What problem are you solving?"
- You explain the validation issue
- Detects your Node.js stack (Express 4.18.2, Jest for testing)
- Analyzes existing UserService code patterns
- Asks: "Should I follow your existing conventions?" → You say yes
- Generates tech-spec.md with specific file paths and patterns
- Creates story-login-fix.md
3. **Implement:** Load DEV agent, run `dev-story`
- DEV reads tech-spec (has all context!)
- Implements fix following existing patterns
- Runs tests (following existing Jest patterns)
- Done!
**Total time:** 15-30 minutes (mostly implementation)
---
### Scenario 2: Small Feature (Level 1)
**Goal:** Add OAuth social login (Google, GitHub)
**Steps:**
1. **Start:** Load PM agent, say "I want to add OAuth social login"
2. **PM runs tech-spec workflow:**
- Asks about the feature scope
- You specify: Google and GitHub OAuth
- Detects your stack (Next.js 13.4, NextAuth.js already installed!)
- Analyzes existing auth patterns
- Confirms conventions with you
- Generates:
- tech-spec.md (comprehensive implementation guide)
- epics.md (OAuth Integration epic)
- story-oauth-1.md (Backend OAuth setup)
- story-oauth-2.md (Frontend login buttons)
3. **Optional Sprint Planning:** Load SM agent, run `sprint-planning`
4. **Implement Story 1:**
- Load DEV agent, run `dev-story` for story 1
- DEV implements backend OAuth
5. **Implement Story 2:**
- DEV agent, run `dev-story` for story 2
- DEV implements frontend
- Done!
**Total time:** 1-3 hours (mostly implementation)
---
## Integration with Phase 4 Workflows
Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
### story-context (SM Agent)
- ✅ Recognizes tech-spec.md as authoritative source
- ✅ Extracts context from tech-spec (replaces PRD)
- ✅ Generates XML context for complex scenarios
### create-story (SM Agent)
- ✅ Can work with tech-spec.md instead of PRD
- ✅ Uses epics.md from tech-spec workflow
- ✅ Creates additional stories if needed
### sprint-planning (SM Agent)
- ✅ Works with epics.md from tech-spec
- ✅ Organizes Level 1 stories for coordinated implementation
- ✅ Tracks progress through sprint-status.yaml
### dev-story (DEV Agent)
- ✅ Reads stories generated by tech-spec
- ✅ Uses tech-spec.md as comprehensive context
- ✅ Implements following detected conventions
---
## Comparison: Quick Spec vs Full BMM
| Aspect | Quick Spec Flow (Level 0-1) | Full BMM Flow (Level 2-4) |
| --------------------- | ---------------------------- | ---------------------------------- |
| **Setup** | None (standalone) | workflow-init recommended |
| **Planning Docs** | tech-spec.md only | Product Brief → PRD → Architecture |
| **Time to Code** | Minutes | Hours to days |
| **Best For** | Bug fixes, small features | New products, major features |
| **Context Discovery** | Automatic | Manual + guided |
| **Story Context** | Optional (tech-spec is rich) | Required (generated from PRD) |
| **Validation** | Auto-validates everything | Manual validation steps |
| **Brownfield** | Auto-analyzes and conforms | Manual documentation required |
| **Conventions** | Auto-detects and confirms | Document in PRD/Architecture |
---
## When to Graduate from Quick Spec to Full BMM
Start with Quick Spec, but switch to Full BMM when:
- ❌ Project grows beyond 3-5 stories
- ❌ Multiple teams need coordination
- ❌ Stakeholders need formal documentation
- ❌ Product vision is unclear
- ❌ Architectural decisions need deep analysis
- ❌ Compliance/regulatory requirements exist
💡 **Tip:** You can always run `workflow-init` later to transition from Quick Spec to Full BMM!
---
## Quick Spec Flow - Key Benefits
### 🚀 **Speed**
- No Product Brief
- No PRD
- No Architecture doc
- Straight to implementation
### 🧠 **Intelligence**
- Auto-detects stack
- Auto-analyzes brownfield
- Auto-validates quality
- WebSearch for current info
### 📐 **Respect for Existing Code**
- Detects conventions
- Asks for confirmation
- Follows patterns
- Adapts vs. changes
### ✅ **Quality**
- Auto-validation
- Definitive decisions (no "or" statements)
- Comprehensive context
- Clear acceptance criteria
### 🎯 **Focus**
- Level 0: Single atomic change
- Level 1: Coherent small feature
- No scope creep
- Fast iteration
---
## Getting Started
### Prerequisites
- BMad Method installed (`npx bmad-method install`)
- Project directory with code (or empty for greenfield)
### Quick Start Commands
```bash
# For a quick bug fix or small change:
# 1. Load PM agent
# 2. Say: "I want to [describe your change]"
# 3. PM will ask if you want to run tech-spec
# 4. Answer questions about your change
# 5. Get tech-spec + story
# 6. Load DEV agent and implement!
# For a small feature with multiple stories:
# Same as above, but get epic + 2-3 stories
# Optionally use SM sprint-planning to organize
```
### No workflow-init Required!
Quick Spec Flow is **fully standalone**:
- Detects if you're Level 0 or Level 1
- Asks for greenfield vs brownfield
- Works without status file tracking
- Perfect for rapid prototyping
---
## FAQ
### Q: Can I use Quick Spec Flow on an existing project?
**A:** Yes! It's perfect for brownfield projects. It will analyze your existing code, detect patterns, and ask if you want to follow them.
### Q: What if I don't have a package.json or requirements.txt?
**A:** Quick Spec Flow will work in greenfield mode, recommend starter templates, and use WebSearch for modern best practices.
### Q: Do I need to run workflow-init first?
**A:** No! Quick Spec Flow is standalone. But if you want guidance on which flow to use, workflow-init can help.
### Q: Can I use this for frontend changes?
**A:** Absolutely! Quick Spec Flow captures UX/UI considerations, component changes, and accessibility requirements.
### Q: What if my Level 0 project grows?
**A:** No problem! You can always transition to Full BMM by running workflow-init and create-prd. Your tech-spec becomes input for the PRD.
### Q: Do I need story-context for every story?
**A:** Usually no! Tech-spec is comprehensive enough for most Level 0-1 projects. Only use story-context for complex edge cases.
### Q: Can I skip validation?
**A:** No, validation always runs automatically. But it's fast and catches issues early!
### Q: Will it work with my team's code style?
**A:** Yes! It detects your conventions and asks for confirmation. You control whether to follow existing patterns or establish new ones.
---
## Tips & Best Practices
### 1. **Be Specific in Discovery**
When describing your change, provide specifics:
- ✅ "Fix email validation in UserService to allow plus-addressing"
- ❌ "Fix validation bug"
### 2. **Trust the Convention Detection**
If it detects your patterns correctly, say yes! It's faster than establishing new conventions.
### 3. **Use WebSearch Recommendations for Greenfield**
Starter templates save hours of setup time. Let Quick Spec Flow find the best ones.
### 4. **Review the Auto-Validation**
When validation runs, read the scores. They tell you if your spec is production-ready.
### 5. **Story Context is Optional**
For Level 0, try going directly to dev-story first. Only add story-context if you hit complexity.
### 6. **Keep Level 0 Truly Atomic**
If your "single change" needs 3+ files, it might be Level 1. Let the workflow guide you.
### 7. **Validate Story Sequence for Level 1**
When you get multiple stories, check the dependency validation output. Proper sequence matters!
---
## Real-World Examples
### Example 1: Adding Logging (Level 0)
**Input:** "Add structured logging to payment processing"
**Tech-Spec Output:**
- Detected: winston 3.8.2 already in package.json
- Analyzed: Existing services use winston with JSON format
- Confirmed: Follow existing logging patterns
- Generated: Specific file paths, log levels, format example
- Story: Ready to implement in 1-2 hours
**Result:** Consistent logging added, following team patterns, no research needed.
---
### Example 2: Search Feature (Level 1)
**Input:** "Add search to product catalog with filters"
**Tech-Spec Output:**
- Detected: React 18.2.0, MUI component library, Express backend
- Analyzed: Existing ProductList component patterns
- Confirmed: Follow existing API and component structure
- Generated:
- Epic: Product Search Functionality
- Story 1: Backend search API with filters
- Story 2: Frontend search UI component
- Auto-validated: Story 1 → Story 2 sequence correct
**Result:** Search feature implemented in 4-6 hours with proper architecture.
---
## Summary
Quick Spec Flow is your **fast path from idea to implementation** for:
- 🐛 Bug fixes
- ✨ Small features
- 🚀 Rapid prototyping
- 🔧 Quick enhancements
**Key Features:**
- Auto-detects your stack
- Auto-analyzes brownfield code
- Auto-validates quality
- Respects existing conventions
- Uses WebSearch for modern practices
- Generates comprehensive tech-specs
- Creates implementation-ready stories
**Time to code:** Minutes, not hours.
**Ready to try it?** Load the PM agent and say what you want to build! 🚀
---
## Next Steps
- **Try it now:** Load PM agent and describe a small change
- **Learn more:** See `src/modules/bmm/workflows/README.md` for full BMM workflow guide
- **Need help deciding?** Run `workflow-init` to get a recommendation
- **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
---
_Quick Spec Flow - Because not every change needs a Product Brief._

1045
docs/scale-adaptive-system.md
View File

File diff suppressed because it is too large Load Diff