bmad-fh 6.0.0-alpha.23

package/docs/how-to/workflows/bmgd-quick-flow.md

@@ -0,0 +1,156 @@
+---
+title: "BMGD Quick-Flow Guide"
+description: Fast-track workflows for rapid game prototyping and flexible development
+---
+
+Use BMGD Quick-Flow workflows for rapid game prototyping and flexible development when you need to move fast.
+
+## When to Use This
+
+- Testing a game mechanic idea
+- Implementing a small feature
+- Rapid prototyping before committing to design
+- Bug fixes and tweaks
+
+## When to Use Full BMGD Instead
+
+- Building a major feature or system
+- The scope is unclear or large
+- Multiple team members need alignment
+- The work affects game pillars or core loop
+- You need documentation for future reference
+
+:::note[Prerequisites]
+- BMad Method installed with BMGD module
+- Game Solo Dev agent (Indie) or other BMGD agent available
+:::
+
+## Game Solo Dev Agent
+
+For dedicated quick-flow development, use the **Game Solo Dev** agent. This agent is optimized for solo developers and small teams who want to skip the full planning phases.
+
+**Switch to Game Solo Dev:** Type `@game-solo-dev` or select from your IDE.
+
+Includes: `quick-prototype`, `quick-dev`, `quick-spec`, `code-review`, `test-framework`
+
+## Quick-Prototype
+
+Use `quick-prototype` to rapidly test gameplay ideas with minimal setup.
+
+### When to Use
+
+- You have a mechanic idea and want to test the "feel"
+- You're not sure if something will be fun
+- You want to experiment before committing to design
+- You need a proof of concept
+
+### Steps
+
+1. Run `quick-prototype`
+2. Define what you're prototyping (mechanic, feature, system)
+3. Set success criteria (2-3 items)
+4. Build the minimum to test the idea
+5. Playtest and evaluate
+
+### Prototype Principles
+
+- **Minimum Viable Prototype** — Only what's needed to test the idea
+- **Hardcode First** — Magic numbers are fine, extract later
+- **Skip Edge Cases** — Happy path only for now
+- **Placeholder Everything** — Cubes, debug text, temp sounds
+- **Comment Intent** — Mark what's temporary vs keeper code
+
+### After Prototyping
+
+- **Develop** (`d`) — Use `quick-dev` to build production code
+- **Iterate** (`i`) — Adjust and re-test the prototype
+- **Archive** (`a`) — Keep as reference, move on to other ideas
+
+## Quick-Dev
+
+Use `quick-dev` for flexible development with game-specific considerations.
+
+### When to Use
+
+- Implementing a feature from a tech-spec
+- Building on a successful prototype
+- Making changes that don't need full story workflow
+- Quick fixes and improvements
+
+### Workflow Modes
+
+**Mode A: Tech-Spec Driven**
+```
+quick-dev tech-spec-combat.md
+```
+
+**Mode B: Direct Instructions**
+```
+quick-dev implement double-jump for the player
+```
+
+**Mode C: From Prototype**
+```
+quick-dev from the grappling hook prototype
+```
+
+### Game-Specific Checks
+
+Quick-dev includes automatic consideration of:
+- **Performance** — No allocations in hot paths, object pooling
+- **Feel** — Input responsiveness, visual/audio feedback
+- **Integration** — Save/load, multiplayer sync, platform testing
+
+### Complexity Routing
+
+| Signals | Recommendation |
+|---------|----------------|
+| Single mechanic, bug fix, tweak | Execute directly |
+| Multiple systems, performance-critical | Plan first (tech-spec) |
+| Platform/system level work | Use full BMGD workflow |
+
+## Choosing Between Quick-Flows
+
+| Scenario | Use |
+|----------|-----|
+| "Will this be fun?" | `quick-prototype` |
+| "How should this feel?" | `quick-prototype` |
+| "Build this feature" | `quick-dev` |
+| "Fix this bug" | `quick-dev` |
+| "Test then build" | `quick-prototype` → `quick-dev` |
+
+## Flow Comparison
+
+```
+Full BMGD Flow:
+Brief → GDD → Architecture → Sprint Planning → Stories → Implementation
+
+Quick-Flow:
+Idea → Quick-Prototype → Quick-Dev → Done
+```
+
+## Checklists
+
+**Quick-Prototype:**
+- [ ] Prototype scope defined
+- [ ] Success criteria established (2-3 items)
+- [ ] Minimum viable code written
+- [ ] Placeholder assets used
+- [ ] Each criterion evaluated
+- [ ] Decision made (develop/iterate/archive)
+
+**Quick-Dev:**
+- [ ] Context loaded (spec, prototype, or guidance)
+- [ ] Files to modify identified
+- [ ] All tasks completed
+- [ ] No allocations in hot paths
+- [ ] Game runs without errors
+- [ ] Manual playtest completed
+
+## Tips
+
+- **Timebox prototypes** — Set a limit (e.g., 2 hours). If it's not working, step back
+- **Embrace programmer art** — Focus on feel, not visuals
+- **Test on target hardware** — What feels right on dev machine might not on target
+- **Document learnings** — Even failed prototypes teach something
+- **Know when to graduate** — If quick-dev keeps expanding scope, create proper stories

package/docs/how-to/workflows/conduct-research.md

@@ -0,0 +1,97 @@
+---
+title: "How to Conduct Research"
+description: How to conduct market, technical, and competitive research using BMad Method
+---
+
+Use the `research` workflow to perform comprehensive multi-type research for validating ideas, understanding markets, and making informed decisions.
+
+## When to Use This
+
+- Need market viability validation
+- Choosing frameworks or platforms
+- Understanding competitive landscape
+- Need user understanding
+- Understanding domain or industry
+- Need deeper AI-assisted research
+
+:::note[Prerequisites]
+- BMad Method installed
+- Analyst agent available
+:::
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Research Workflow
+
+```
+*research
+```
+
+### 3. Choose Research Type
+
+Select the type of research you need:
+
+| Type | Purpose | Use When |
+|------|---------|----------|
+| **market** | TAM/SAM/SOM, competitive analysis | Need market viability validation |
+| **technical** | Technology evaluation, ADRs | Choosing frameworks/platforms |
+| **competitive** | Deep competitor analysis | Understanding competitive landscape |
+| **user** | Customer insights, personas, JTBD | Need user understanding |
+| **domain** | Industry deep dives, trends | Understanding domain/industry |
+| **deep_prompt** | Generate AI research prompts | Need deeper AI-assisted research |
+
+### 4. Provide Context
+
+Give the agent details about what you're researching:
+
+- "SaaS project management tool"
+- "React vs Vue for our dashboard"
+- "Fintech compliance requirements"
+
+### 5. Set Research Depth
+
+Choose your depth level:
+
+- **Quick** — Fast overview
+- **Standard** — Balanced depth
+- **Comprehensive** — Deep analysis
+
+## What You Get
+
+Research output varies by type:
+
+**Market Research:**
+- TAM/SAM/SOM analysis
+- Top competitors
+- Positioning recommendation
+
+**Technical Research:**
+- Comparison matrix
+- Trade-off analysis
+- Recommendations with rationale
+
+## Key Features
+
+- Real-time web research
+- Multiple analytical frameworks (Porter's Five Forces, SWOT, Technology Adoption Lifecycle)
+- Platform-specific optimization for deep_prompt type
+- Configurable research depth
+
+## Tips
+
+- **Use market research early** — Validates new product ideas
+- **Technical research helps architecture** — Inform ADRs with data
+- **Competitive research informs positioning** — Differentiate your product
+- **Domain research for specialized industries** — Fintech, healthcare, etc.
+
+## Next Steps
+
+After research:
+
+1. **Product Brief** — Capture strategic vision informed by research
+2. **PRD** — Use findings as context for requirements
+3. **Architecture** — Use technical research in ADRs

package/docs/how-to/workflows/create-architecture.md

@@ -0,0 +1,119 @@
+---
+title: "How to Create Architecture"
+description: How to create system architecture using the BMad Method
+---
+
+Use the `architecture` workflow to make technical decisions explicit and prevent agent conflicts during implementation.
+
+## When to Use This
+
+- Multi-epic projects (BMad Method, Enterprise)
+- Cross-cutting technical concerns
+- Multiple agents implementing different parts
+- Integration complexity exists
+- Technology choices need alignment
+
+## When to Skip This
+
+- Quick Flow (simple changes)
+- BMad Method Simple with straightforward tech stack
+- Single epic with clear technical approach
+
+:::note[Prerequisites]
+- BMad Method installed
+- Architect agent available
+- PRD completed
+:::
+
+## Steps
+
+### 1. Load the Architect Agent
+
+Start a fresh chat and load the Architect agent.
+
+### 2. Run the Architecture Workflow
+
+```
+*create-architecture
+```
+
+### 3. Engage in Discovery
+
+This is NOT a template filler. The architecture workflow:
+
+1. **Discovers** technical needs through conversation
+2. **Proposes** architectural options with trade-offs
+3. **Documents** decisions that prevent agent conflicts
+4. **Focuses** on decision points, not exhaustive documentation
+
+### 4. Document Key Decisions
+
+Work with the agent to create Architecture Decision Records (ADRs) for significant choices.
+
+### 5. Review the Architecture
+
+The agent produces a decision-focused architecture document.
+
+## What You Get
+
+An `architecture.md` document containing:
+
+1. **Architecture Overview** — System context, principles, style
+2. **System Architecture** — High-level diagram, component interactions
+3. **Data Architecture** — Database design, state management, caching
+4. **API Architecture** — API style (REST/GraphQL/gRPC), auth, versioning
+5. **Frontend Architecture** — Framework, state management, components
+6. **Integration Architecture** — Third-party integrations, messaging
+7. **Security Architecture** — Auth/authorization, data protection
+8. **Deployment Architecture** — CI/CD, environments, monitoring
+9. **ADRs** — Key decisions with context, options, rationale
+10. **FR/NFR-Specific Guidance** — Technical approach per requirement
+11. **Standards and Conventions** — Directory structure, naming, testing
+
+## ADR Format
+
+```markdown
+## ADR-001: Use GraphQL for All APIs
+
+**Status:** Accepted | **Date:** 2025-11-02
+
+**Context:** PRD requires flexible querying across multiple epics
+
+**Decision:** Use GraphQL for all client-server communication
+
+**Options Considered:**
+1. REST - Familiar but requires multiple endpoints
+2. GraphQL - Flexible querying, learning curve
+3. gRPC - High performance, poor browser support
+
+**Rationale:**
+- PRD requires flexible data fetching (Epic 1, 3)
+- Mobile app needs bandwidth optimization (Epic 2)
+- Team has GraphQL experience
+
+**Consequences:**
+- Positive: Flexible querying, reduced versioning
+- Negative: Caching complexity, N+1 query risk
+- Mitigation: Use DataLoader for batching
+```
+
+## Example
+
+E-commerce platform produces:
+- Monolith + PostgreSQL + Redis + Next.js + GraphQL
+- ADRs explaining each choice
+- FR/NFR-specific implementation guidance
+
+## Tips
+
+- **Focus on decisions that prevent conflicts** — Multiple agents need alignment
+- **Use ADRs for every significant choice** — Document the "why"
+- **Keep it practical** — Don't over-architect
+- **Architecture is living** — Update as you learn
+
+## Next Steps
+
+After architecture:
+
+1. **Create Epics and Stories** — Work breakdown informed by architecture
+2. **Implementation Readiness** — Gate check before Phase 4

package/docs/how-to/workflows/create-epics-and-stories.md

@@ -0,0 +1,109 @@
+---
+title: "How to Create Epics and Stories"
+description: How to break PRD requirements into epics and stories using BMad Method
+---
+
+Use the `create-epics-and-stories` workflow to transform PRD requirements into bite-sized stories organized into deliverable epics.
+
+## When to Use This
+
+- After architecture workflow completes
+- When PRD contains FRs/NFRs ready for implementation breakdown
+- Before implementation-readiness gate check
+
+:::note[Prerequisites]
+- BMad Method installed
+- PM agent available
+- PRD completed
+- Architecture completed
+:::
+
+## Why After Architecture?
+
+This workflow runs AFTER architecture because:
+
+1. **Informed Story Sizing** — Architecture decisions affect story complexity
+2. **Dependency Awareness** — Architecture reveals technical dependencies
+3. **Technical Feasibility** — Stories can be properly scoped knowing the tech stack
+4. **Consistency** — All stories align with documented architectural patterns
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent.
+
+### 2. Run the Workflow
+
+```
+*create-epics-and-stories
+```
+
+### 3. Provide Context
+
+Point the agent to:
+- Your PRD (FRs/NFRs)
+- Your architecture document
+- Optional: UX design artifacts
+
+### 4. Review Epic Breakdown
+
+The agent organizes requirements into logical epics with user stories.
+
+### 5. Validate Story Quality
+
+Ensure each story has:
+- Clear acceptance criteria
+- Appropriate priority
+- Identified dependencies
+- Technical notes from architecture
+
+## What You Get
+
+Epic files (one per epic) containing:
+
+1. **Epic objective and scope**
+2. **User stories with acceptance criteria**
+3. **Story priorities** (P0/P1/P2/P3)
+4. **Dependencies between stories**
+5. **Technical notes** referencing architecture decisions
+
+## Example
+
+E-commerce PRD with FR-001 (User Registration), FR-002 (Product Catalog) produces:
+
+- **Epic 1: User Management** (3 stories)
+  - Story 1.1: User registration form
+  - Story 1.2: Email verification
+  - Story 1.3: Login/logout
+
+- **Epic 2: Product Display** (4 stories)
+  - Story 2.1: Product listing page
+  - Story 2.2: Product detail page
+  - Story 2.3: Search functionality
+  - Story 2.4: Category filtering
+
+Each story references relevant ADRs from architecture.
+
+## Story Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| **P0** | Critical — Must have for MVP |
+| **P1** | High — Important for release |
+| **P2** | Medium — Nice to have |
+| **P3** | Low — Future consideration |
+
+## Tips
+
+- **Keep stories small** — Complete in a single session
+- **Make criteria testable** — Acceptance criteria should be verifiable
+- **Document dependencies clearly** — Know what blocks what
+- **Reference architecture** — Include ADR references in technical notes
+
+## Next Steps
+
+After creating epics and stories:
+
+1. **Implementation Readiness** — Validate alignment before Phase 4
+2. **Sprint Planning** — Organize work for implementation

package/docs/how-to/workflows/create-prd.md

@@ -0,0 +1,91 @@
+---
+title: "How to Create a PRD"
+description: How to create a Product Requirements Document using the BMad Method
+---
+
+Use the `prd` workflow to create a strategic Product Requirements Document with Functional Requirements (FRs) and Non-Functional Requirements (NFRs).
+
+## When to Use This
+
+- Medium to large feature sets
+- Multi-screen user experiences
+- Complex business logic
+- Multiple system integrations
+- Phased delivery required
+
+:::note[Prerequisites]
+- BMad Method installed
+- PM agent available
+- Optional: Product brief from Phase 1
+:::
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent.
+
+### 2. Run the PRD Workflow
+
+```
+*create-prd
+```
+
+### 3. Provide Context
+
+The workflow will:
+- Load any existing product brief
+- Ask about your project scope
+- Gather requirements through conversation
+
+### 4. Define Requirements
+
+Work with the agent to define:
+- Functional Requirements (FRs) — What the system should do
+- Non-Functional Requirements (NFRs) — How well it should do it
+
+### 5. Review the PRD
+
+The agent produces a comprehensive PRD scaled to your project.
+
+## What You Get
+
+A `PRD.md` document containing:
+
+- Executive summary
+- Problem statement
+- User personas
+- Functional requirements (FRs)
+- Non-functional requirements (NFRs)
+- Success metrics
+- Risks and assumptions
+
+## Scale-Adaptive Structure
+
+The PRD adapts to your project complexity:
+
+| Scale | Pages | Focus |
+|-------|-------|-------|
+| **Light** | 10-15 | Focused FRs/NFRs, simplified analysis |
+| **Standard** | 20-30 | Comprehensive FRs/NFRs, thorough analysis |
+| **Comprehensive** | 30-50+ | Extensive FRs/NFRs, multi-phase, stakeholder analysis |
+
+## Example
+
+E-commerce checkout → PRD with:
+- 15 FRs (user account, cart management, payment flow)
+- 8 NFRs (performance, security, scalability)
+
+## Tips
+
+- **Do Product Brief first** — Run product-brief from Phase 1 for better results
+- **Focus on "What" not "How"** — Planning defines what to build and why. Leave how (technical design) to Phase 3
+- **Document-Project first for Brownfield** — Always run `document-project` before planning brownfield projects. AI agents need existing codebase context
+
+## Next Steps
+
+After PRD:
+
+1. **Create UX Design** (optional) — If UX is critical
+2. **Create Architecture** — Technical design
+3. **Create Epics and Stories** — After architecture

package/docs/how-to/workflows/create-product-brief.md

@@ -0,0 +1,94 @@
+---
+title: "How to Create a Product Brief"
+description: How to create a product brief using the BMad Method
+---
+
+Use the `product-brief` workflow to define product vision and strategy through an interactive process.
+
+## When to Use This
+
+- Starting new product or major feature initiative
+- Aligning stakeholders before detailed planning
+- Transitioning from exploration to strategy
+- Need executive-level product documentation
+
+:::note[Prerequisites]
+- BMad Method installed
+- Analyst agent available
+- Optional: Research documents from previous workflows
+:::
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Product Brief Workflow
+
+```
+*product-brief
+```
+
+### 3. Answer the Interactive Questions
+
+The workflow guides you through strategic product vision definition:
+
+- What problem are you solving?
+- Who are your target users?
+- What makes this solution different?
+- What's the MVP scope?
+
+### 4. Review and Refine
+
+The agent will draft sections and let you refine them interactively.
+
+## What You Get
+
+The `product-brief.md` document includes:
+
+- **Executive summary** — High-level overview
+- **Problem statement** — With evidence
+- **Proposed solution** — And differentiators
+- **Target users** — Segmented
+- **MVP scope** — Ruthlessly defined
+- **Financial impact** — And ROI
+- **Strategic alignment** — With business goals
+- **Risks and open questions** — Documented upfront
+
+## Integration with Other Workflows
+
+The product brief feeds directly into the PRD workflow:
+
+| Analysis Output | Planning Input |
+|-----------------|----------------|
+| product-brief.md | **prd** workflow |
+| market-research.md | **prd** context |
+| technical-research.md | **architecture** (Phase 3) |
+
+Planning workflows automatically load the product brief if it exists.
+
+## Common Patterns
+
+**Greenfield Software (Full Analysis):**
+
+```
+1. brainstorm-project - explore approaches
+2. research (market/technical/domain) - validate viability
+3. product-brief - capture strategic vision
+4. → Phase 2: prd
+```
+
+**Skip Analysis (Clear Requirements):**
+
+```
+→ Phase 2: prd or tech-spec directly
+```
+
+## Tips
+
+- **Be specific about the problem** — Vague problems lead to vague solutions
+- **Ruthlessly prioritize MVP scope** — Less is more
+- **Document assumptions and risks** — Surface unknowns early
+- **Use research findings as evidence** — Back up claims with data
+- **Recommended for greenfield projects** — Sets strategic foundation