bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

package/{src/modules/cis/docs → docs/explanation/creative-intelligence}/index.md

@@ -1,20 +1,19 @@
-# CIS - Creative Intelligence Suite
+---
+title: "Creative Intelligence Suite (CIS)"
+description: AI-powered creative facilitation with the Creative Intelligence Suite
+---
 
-AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
-## Table of Contents
+AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
-- [Core Capabilities](#core-capabilities)
-- [Specialized Agents](#specialized-agents)
-- [Interactive Workflows](#interactive-workflows)
-- [Quick Start](#quick-start)
-- [Key Differentiators](#key-differentiators)
-- [Configuration](#configuration)
+---
 
 ## Core Capabilities
 
 CIS provides structured creative methodologies through distinctive agent personas who act as master facilitators, drawing out insights through strategic questioning rather than generating solutions directly.
 
+---
+
 ## Specialized Agents
 
 - **Carson** - Brainstorming Specialist (energetic facilitator)
@@ -23,74 +22,69 @@ CIS provides structured creative methodologies through distinctive agent persona
 - **Victor** - Innovation Oracle (bold strategic precision)
 - **Sophia** - Master Storyteller (whimsical narrator)
 
-## Interactive Workflows
+---
 
-[View all workflows →](../workflows/README.md)
+## Interactive Workflows
 
 **5 Workflows** with **150+ Creative Techniques:**
 
 ### Brainstorming
 
-36 techniques across 7 categories for ideation
-
+36 techniques across 7 categories for ideation:
 - Divergent/convergent thinking
 - Lateral connections
 - Forced associations
 
 ### Design Thinking
 
-Complete 5-phase human-centered process
-
+Complete 5-phase human-centered process:
 - Empathize → Define → Ideate → Prototype → Test
 - User journey mapping
 - Rapid iteration
 
 ### Problem Solving
 
-Systematic root cause analysis
-
+Systematic root cause analysis:
 - 5 Whys, Fishbone diagrams
 - Solution generation
 - Impact assessment
 
 ### Innovation Strategy
 
-Business model disruption
-
+Business model disruption:
 - Blue Ocean Strategy
 - Jobs-to-be-Done
 - Disruptive innovation patterns
 
 ### Storytelling
 
-25 narrative frameworks
-
+25 narrative frameworks:
 - Hero's Journey
 - Story circles
 - Compelling pitch structures
 
+---
+
 ## Quick Start
 
 ### Direct Workflow
 
 ```bash
-# Start interactive session
 workflow brainstorming
 
-# With context document
 workflow design-thinking --data /path/to/context.md
 ```
 
 ### Agent-Facilitated
 
 ```bash
-# Load agent
 agent cis/brainstorming-coach
 
-# Start workflow
 > *brainstorm
 ```
 
+---
+
 ## Key Differentiators
 
 - **Facilitation Over Generation** - Guides discovery through questions
@@ -99,30 +93,7 @@ agent cis/brainstorming-coach
 - **Persona-Driven** - Unique communication styles
 - **Rich Method Libraries** - 150+ proven techniques
 
-## Configuration
-
-Edit `/_bmad/cis/config.yaml`:
-
-```yaml
-output_folder: ./creative-outputs
-user_name: Your Name
-communication_language: english
-```
-
-## Module Structure
-
-```
-cis/
-├── agents/              # 5 specialized facilitators
-├── workflows/           # 5 interactive processes
-│   ├── brainstorming/
-│   ├── design-thinking/
-│   ├── innovation-strategy/
-│   ├── problem-solving/
-│   └── storytelling/
-├── tasks/              # Supporting operations
-└── teams/              # Agent collaborations
-```
+---
 
 ## Integration Points
 
@@ -132,6 +103,8 @@ CIS workflows integrate with:
 - **BMB** - Creative module design
 - **Custom Modules** - Shared creative resource
 
+---
+
 ## Best Practices
 
 1. **Set clear objectives** before starting sessions
@@ -140,10 +113,9 @@ CIS workflows integrate with:
 4. **Take breaks** when energy flags
 5. **Document insights** as they emerge
 
-## Related Documentation
-
-- **[BMM Documentation](../../bmm/docs/index.md)** - Core BMad Method documentation
-
 ---
 
-Part of BMad Method v6.0 - Transform creative potential through expert AI facilitation.
+## Related
+
+- [Facilitation Over Generation](/docs/explanation/philosophy/facilitation-over-generation.md) - Core philosophy
+- [Brainstorming Techniques](/docs/explanation/features/brainstorming-techniques.md) - Technique reference

package/docs/explanation/faq/brownfield-faq.md

@@ -0,0 +1,73 @@
+---
+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
+
+- [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)
+- [How does workflow-init handle old planning docs?](#how-does-workflow-init-handle-old-planning-docs)
+- [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
+- 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:
+
+1. Shows what it found (old PRD, epics, etc.)
+2. Asks: "Is this work in progress, previous effort, or proposed work?"
+3. If previous effort: Asks you to describe your NEW work
+4. 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](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/explanation/faq/getting-started-faq.md

@@ -0,0 +1,62 @@
+---
+title: "Getting Started FAQ"
+description: Common questions about getting started with the BMad Method
+---
+
+Quick answers to common questions about getting started with the BMad Method.
+
+## Questions
+
+- [Do I always need to run workflow-init?](#do-i-always-need-to-run-workflow-init)
+- [Why do I need fresh chats for each workflow?](#why-do-i-need-fresh-chats-for-each-workflow)
+- [Can I skip workflow-status and just start working?](#can-i-skip-workflow-status-and-just-start-working)
+- [What's the minimum I need to get started?](#whats-the-minimum-i-need-to-get-started)
+- [How do I know if I'm in Phase 1, 2, 3, or 4?](#how-do-i-know-if-im-in-phase-1-2-3-or-4)
+
+### Do I always need to run workflow-init?
+
+No, once you learn the flow you can go directly to workflows. However, workflow-init is helpful because it:
+
+- Determines your project's appropriate level automatically
+- Creates the tracking status file
+- Routes you to the correct starting workflow
+
+For experienced users: use the [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) to go directly to the right agent/workflow.
+
+### Why do I need fresh chats for each workflow?
+
+Context-intensive workflows (like brainstorming, PRD creation, architecture design) can cause AI hallucinations if run in sequence within the same chat. Starting fresh ensures the agent has maximum context capacity for each workflow. This is particularly important for:
+
+- Planning workflows (PRD, architecture)
+- Analysis workflows (brainstorming, research)
+- Complex story implementation
+
+Quick workflows like status checks can reuse chats safely.
+
+### Can I skip workflow-status and just start working?
+
+Yes, if you already know your project level and which workflow comes next. workflow-status is mainly useful for:
+
+- New projects (guides initial setup)
+- When you're unsure what to do next
+- After breaks in work (reminds you where you left off)
+- Checking overall progress
+
+### What's the minimum I need to get started?
+
+For the fastest path:
+
+1. Install BMad Method: `npx bmad-method@alpha install`
+2. For small changes: Load PM agent → run tech-spec → implement
+3. For larger projects: Load PM agent → run prd → architect → implement
+
+### How do I know if I'm in Phase 1, 2, 3, or 4?
+
+Check your `bmm-workflow-status.md` file (created by workflow-init). It shows your current phase and progress. If you don't have this file, you can also tell by what you're working on:
+
+- **Phase 1** — Brainstorming, research, product brief (optional)
+- **Phase 2** — Creating either a PRD or tech-spec (always required)
+- **Phase 3** — Architecture design (Level 2-4 only)
+- **Phase 4** — Actually writing code, implementing stories
+
+**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!

package/docs/explanation/faq/implementation-faq.md

@@ -0,0 +1,52 @@
+---
+title: "Implementation FAQ"
+description: Common questions about implementation in the BMad Method
+---
+
+Quick answers to common questions about implementation in the BMad Method.
+
+## Questions
+
+- [Does create-story include implementation context?](#does-create-story-include-implementation-context)
+- [How do I mark a story as done?](#how-do-i-mark-a-story-as-done)
+- [Can I work on multiple stories at once?](#can-i-work-on-multiple-stories-at-once)
+- [What if my story takes longer than estimated?](#what-if-my-story-takes-longer-than-estimated)
+- [When should I run retrospective?](#when-should-i-run-retrospective)
+
+### Does create-story include implementation context?
+
+Yes! The create-story workflow generates story files that include implementation-specific guidance, references existing patterns from your documentation, and provides technical context. The workflow loads your architecture, PRD, and existing project documentation to create comprehensive stories. For Quick Flow projects using tech-spec, the tech-spec itself is already comprehensive, so stories can be simpler.
+
+### How do I mark a story as done?
+
+After dev-story completes and code-review passes:
+
+1. Open `sprint-status.yaml` (created by sprint-planning)
+2. Change the story status from `review` to `done`
+3. Save the file
+
+### Can I work on multiple stories at once?
+
+Yes, if you have capacity! Stories within different epics can be worked in parallel. However, stories within the same epic are usually sequential because they build on each other.
+
+### What if my story takes longer than estimated?
+
+That's normal! Stories are estimates. If implementation reveals more complexity:
+
+1. Continue working until DoD is met
+2. Consider if story should be split
+3. Document learnings in retrospective
+4. Adjust future estimates based on this learning
+
+### When should I run retrospective?
+
+After completing all stories in an epic (when epic is done). Retrospectives capture:
+
+- What went well
+- What could improve
+- Technical insights
+- Learnings for future epics
+
+Don't wait until project end — run after each epic for continuous improvement.
+
+**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!

package/docs/explanation/faq/index.md

@@ -0,0 +1,16 @@
+---
+title: "Frequently Asked Questions"
+description: Frequently asked questions about the BMad Method
+---
+
+Quick answers to common questions about the BMad Method, organized by topic.
+
+## Topics
+
+- [Getting Started](/docs/explanation/faq/getting-started-faq.md) - Questions about starting with BMad
+- [Levels & Tracks](/docs/explanation/faq/levels-and-tracks-faq.md) - Choosing the right level
+- [Workflows](/docs/explanation/faq/workflows-faq.md) - Workflow and phase questions
+- [Planning](/docs/explanation/faq/planning-faq.md) - Planning document questions
+- [Implementation](/docs/explanation/faq/implementation-faq.md) - Implementation questions
+- [Brownfield](/docs/explanation/faq/brownfield-faq.md) - Existing codebase questions
+- [Tools & Advanced](/docs/explanation/faq/tools-faq.md) - Tools, IDEs, and advanced topics

package/docs/explanation/faq/levels-and-tracks-faq.md

@@ -0,0 +1,52 @@
+---
+title: "Levels and Tracks FAQ"
+description: Common questions about choosing the right level for your project
+---
+
+Quick answers to common questions about choosing the right level for your BMad Method project.
+
+## Questions
+
+- [How do I know which level my project is?](#how-do-i-know-which-level-my-project-is)
+- [Can I change levels mid-project?](#can-i-change-levels-mid-project)
+- [What if workflow-init suggests the wrong level?](#what-if-workflow-init-suggests-the-wrong-level)
+- [Do I always need architecture for Level 2?](#do-i-always-need-architecture-for-level-2)
+- [What's the difference between Level 1 and Level 2?](#whats-the-difference-between-level-1-and-level-2)
+
+### How do I know which level my project is?
+
+Use workflow-init for automatic detection, or self-assess using these keywords:
+
+- **Level 0** — "fix", "bug", "typo", "small change", "patch" → 1 story
+- **Level 1** — "simple", "basic", "small feature", "add" → 1-10 stories
+- **Level 2** — "dashboard", "several features", "admin panel" → 5-15 stories
+- **Level 3** — "platform", "integration", "complex", "system" → 12-40 stories
+- **Level 4** — "enterprise", "multi-tenant", "multiple products" → 40+ stories
+
+When in doubt, start smaller. You can always run create-prd later if needed.
+
+### Can I change levels mid-project?
+
+Yes! If you started at Level 1 but realize it's Level 2, you can run create-prd to add proper planning docs. The system is flexible — your initial level choice isn't permanent.
+
+### What if workflow-init suggests the wrong level?
+
+You can override it! workflow-init suggests a level but always asks for confirmation. If you disagree, just say so and choose the level you think is appropriate. Trust your judgment.
+
+### Do I always need architecture for Level 2?
+
+No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD created during planning.
+
+### What's the difference between Level 1 and Level 2?
+
+- **Level 1** — 1-10 stories, uses tech-spec (simpler, faster), no architecture
+- **Level 2** — 5-15 stories, uses PRD (product-focused), optional architecture
+
+The overlap (5-10 stories) is intentional. Choose based on:
+
+- Need product-level planning? → Level 2
+- Just need technical plan? → Level 1
+- Multiple epics? → Level 2
+- Single epic? → Level 1
+
+**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!

package/docs/explanation/faq/planning-faq.md

@@ -0,0 +1,41 @@
+---
+title: "Planning Documents FAQ"
+description: Common questions about planning documents in the BMad Method
+---
+
+Quick answers to common questions about planning documents in the BMad Method.
+
+## Questions
+
+- [Why no tech-spec at Level 2+?](#why-no-tech-spec-at-level-2)
+- [Do I need a PRD for a bug fix?](#do-i-need-a-prd-for-a-bug-fix)
+- [Can I skip the product brief?](#can-i-skip-the-product-brief)
+
+### Why no tech-spec at Level 2+?
+
+Level 2+ projects need product-level planning (PRD) and system-level design (Architecture), which tech-spec doesn't provide. Tech-spec is too narrow for coordinating multiple features. Instead, Level 2-4 uses:
+
+- PRD (product vision, functional requirements, non-functional requirements)
+- Architecture (system design)
+- Epics+Stories (created AFTER architecture is complete)
+
+### Do I need a PRD for a bug fix?
+
+No! Bug fixes are typically Level 0 (single atomic change). Use Quick Spec Flow:
+
+- Load PM agent
+- Run tech-spec workflow
+- Implement immediately
+
+PRDs are for Level 2-4 projects with multiple features requiring product-level coordination.
+
+### Can I skip the product brief?
+
+Yes, product brief is always optional. It's most valuable for:
+
+- Level 3-4 projects needing strategic direction
+- Projects with stakeholders requiring alignment
+- Novel products needing market research
+- When you want to explore solution space before committing
+
+**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!