feat: WIP create-docv2

2025-07-06 00:10:00 -05:00
parent be9453f234
commit c107af0598
16 changed files with 4064 additions and 1916 deletions
--- a/bmad-core/data/bmad-kb.md
+++ b/bmad-core/data/bmad-kb.md
@@ -33,13 +33,15 @@ BMad transforms you into a "Vibe CEO" - directing a team of specialized AI agent

 ### The Two-Phase Approach

-**Phase 1: Planning (Web UI - Cost Effective)**
+#### Phase 1: Planning (Web UI - Cost Effective)
+
 - Use large context windows (Gemini's 1M tokens)
 - Generate comprehensive documents (PRD, Architecture)
 - Leverage multiple agents for brainstorming
 - Create once, use throughout development

-**Phase 2: Development (IDE - Implementation)**
+#### Phase 2: Development (IDE - Implementation)
+
 - Shard documents into manageable pieces
 - Execute focused SM → Dev cycles
 - One story at a time, sequential progress
@@ -69,6 +71,7 @@ BMad transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 ### Quick Start Options

 #### Option 1: Web UI
+
 **Best for**: ChatGPT, Claude, Gemini users who want to start immediately

 1. Navigate to `dist/teams/`
@@ -78,6 +81,7 @@ BMad transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands

 #### Option 2: IDE Integration
+
 **Best for**: Cursor, Claude Code, Windsurf, Trae, Cline, Roo Code, Github Copilot users

 ```bash
@@ -86,6 +90,7 @@ npx bmad-method install
 ```

 **Installation Steps**:
+
 - Choose "Complete installation"
 - Select your IDE from supported options:
  - **Cursor**: Native AI integration
@@ -99,6 +104,7 @@ npx bmad-method install
 **Note for VS Code Users**: BMad-Method assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMad agents. The installer includes built-in support for Cline and Roo.

 **Verify Installation**:
+
 - `.bmad-core/` folder created with all agents
 - IDE-specific integration files created
 - All agent commands/rules/modes available
@@ -108,12 +114,14 @@ npx bmad-method install
 ### Environment Selection Guide

 **Use Web UI for**:
+
 - Initial planning and documentation (PRD, architecture)
 - Cost-effective document creation (especially with Gemini)
 - Brainstorming and analysis phases
 - Multi-agent consultation and planning

 **Use IDE for**:
+
 - Active development and coding
 - File operations and project integration
 - Document sharding and story management
@@ -126,35 +134,41 @@ npx bmad-method install
 **Can you do everything in IDE?** Yes, but understand the tradeoffs:

 **Pros of IDE-Only**:
+
 - Single environment workflow
 - Direct file operations from start
 - No copy/paste between environments
 - Immediate project integration

 **Cons of IDE-Only**:
+
 - Higher token costs for large document creation
 - Smaller context windows (varies by IDE/model)
 - May hit limits during planning phases
 - Less cost-effective for brainstorming

 **Using Web Agents in IDE**:
+
 - **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
 - **Why it matters**: Dev agents are kept lean to maximize coding context
 - **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization

 **About bmad-master and bmad-orchestrator**:
+
 - **bmad-master**: CAN do any task without switching agents, BUT...
 - **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
 - **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
 - **If using bmad-master/orchestrator**: Fine for planning phases, but...

 **CRITICAL RULE for Development**:
+
 - **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
 - **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
 - **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
 - **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation

 **Best Practice for IDE-Only**:
+
 1. Use PM/Architect/UX agents for planning (better than bmad-master)
 2. Create documents directly in project
 3. Shard immediately after creation
@@ -178,17 +192,20 @@ This configuration file acts as a map for BMad agents, telling them exactly wher
 ### Key Configuration Areas

 #### PRD Configuration
+
 - **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
 - **prdSharded**: Whether epics are embedded (false) or in separate files (true)
 - **prdShardedLocation**: Where to find sharded epic files
 - **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)

 #### Architecture Configuration
+
 - **architectureVersion**: v3 (monolithic) or v4 (sharded)
 - **architectureSharded**: Whether architecture is split into components
 - **architectureShardedLocation**: Where sharded architecture files live

 #### Developer Files
+
 - **devLoadAlwaysFiles**: List of files the dev agent loads for every task
 - **devDebugLog**: Where dev agent logs repeated failures
 - **agentCoreDump**: Export location for chat conversations
@@ -203,6 +220,7 @@ This configuration file acts as a map for BMad agents, telling them exactly wher
 ### Common Configurations

 **Legacy V3 Project**:
+
 ```yaml
 prdVersion: v3
 prdSharded: false
@@ -211,6 +229,7 @@ architectureSharded: false
 ```

 **V4 Optimized Project**:
+
 ```yaml
 prdVersion: v4
 prdSharded: true
@@ -276,6 +295,7 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 #### IDE-Specific Syntax

 **Agent Loading by IDE**:
+
 - **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
 - **Cursor**: `@agent-name` (e.g., `@bmad-master`)
 - **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
@@ -284,10 +304,12 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 - **Github Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.

 **Chat Management Guidelines**:
+
 - **Claude Code, Cursor, Windsurf, Trae**: Start new chats when switching agents
 - **Roo Code**: Switch modes within the same conversation

 **Common Task Commands**:
+
 - `*help` - Show available commands
 - `*status` - Show current context/progress
 - `*exit` - Exit the agent mode
@@ -296,6 +318,7 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 - `*create` - Run create-next-story task (SM agent)

 **In Web UI**:
+
 ```text
 /pm create-doc prd
 /architect review system design
@@ -309,16 +332,19 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 ### Pre-Built Teams

 #### Team All
+
 - **Includes**: All 10 agents + orchestrator
 - **Use Case**: Complete projects requiring all roles
 - **Bundle**: `team-all.txt`

 #### Team Fullstack
+
 - **Includes**: PM, Architect, Developer, QA, UX Expert
 - **Use Case**: End-to-end web/mobile development
 - **Bundle**: `team-fullstack.txt`

 #### Team No-UI
+
 - **Includes**: PM, Architect, Developer, QA (no UX Expert)
 - **Use Case**: Backend services, APIs, system development
 - **Bundle**: `team-no-ui.txt`
@@ -332,22 +358,26 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 ### Key Architectural Components

 #### 1. Agents (`bmad-core/agents/`)
+
 - **Purpose**: Each markdown file defines a specialized AI agent for a specific Agile role (PM, Dev, Architect, etc.)
 - **Structure**: Contains YAML headers specifying the agent's persona, capabilities, and dependencies
 - **Dependencies**: Lists of tasks, templates, checklists, and data files the agent can use
 - **Startup Instructions**: Can load project-specific documentation for immediate context

 #### 2. Agent Teams (`bmad-core/agent-teams/`)
+
 - **Purpose**: Define collections of agents bundled together for specific purposes
 - **Examples**: `team-all.yaml` (comprehensive bundle), `team-fullstack.yaml` (full-stack development)
 - **Usage**: Creates pre-packaged contexts for web UI environments

 #### 3. Workflows (`bmad-core/workflows/`)
+
 - **Purpose**: YAML files defining prescribed sequences of steps for specific project types
 - **Types**: Greenfield (new projects) and Brownfield (existing projects) for UI, service, and fullstack development
 - **Structure**: Defines agent interactions, artifacts created, and transition conditions

 #### 4. Reusable Resources
+
 - **Templates** (`bmad-core/templates/`): Markdown templates for PRDs, architecture specs, user stories
 - **Tasks** (`bmad-core/tasks/`): Instructions for specific repeatable actions like "shard-doc" or "create-next-story"
 - **Checklists** (`bmad-core/checklists/`): Quality assurance checklists for validation and review
@@ -387,6 +417,7 @@ BMad employs a sophisticated template system with three key components:
 ### Technical Preferences Integration

 The `technical-preferences.md` file serves as a persistent technical profile that:
+
 - Ensures consistency across all agents and projects
 - Eliminates repetitive technology specification
 - Provides personalized recommendations aligned with user preferences
@@ -395,6 +426,7 @@ The `technical-preferences.md` file serves as a persistent technical profile tha
 ### Build and Delivery Process

 The `web-builder.js` tool creates web-ready bundles by:
+
 1. Reading agent or team definition files
 2. Recursively resolving all dependencies
 3. Concatenating content into single text files with clear separators
@@ -409,11 +441,13 @@ This architecture enables seamless operation across environments while maintaini
 **Ideal for cost efficiency with Gemini's massive context:**

 **For Brownfield Projects - Start Here!**:
+
 1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
 2. **Document existing system**: `/analyst` → `*document-project`
 3. **Creates comprehensive docs** from entire codebase analysis

 **For All Projects**:
+
 1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
 2. **Project Brief**: Create foundation document (Analyst or user)
 3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
@@ -424,12 +458,14 @@ This architecture enables seamless operation across environments while maintaini
 #### Example Planning Prompts

 **For PRD Creation**:
+
 ```text
 "I want to build a [type] application that [core purpose].
 Help me brainstorm features and create a comprehensive PRD."
 ```

 **For Architecture Design**:
+
 ```text
 "Based on this PRD, design a scalable technical architecture
 that can handle [specific requirements]."
@@ -447,7 +483,7 @@ that can handle [specific requirements]."

 **Prerequisites**: Planning documents must exist in `docs/` folder

-1. **Document Sharding** (CRITICAL STEP): 
+1. **Document Sharding** (CRITICAL STEP):
   - Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
   - Two methods to shard:
     a) **Manual**: Drag `shard-doc` task + document file into chat
@@ -461,32 +497,33 @@ that can handle [specific requirements]."
   - Source tree document and coding standards for dev agent reference
   - Sharded docs for SM agent story creation

-**Resulting Folder Structure**:
+Resulting Folder Structure:
+
 - `docs/prd/` - Broken down PRD sections
 - `docs/architecture/` - Broken down architecture sections
 - `docs/stories/` - Generated user stories

-3. **Development Cycle** (Sequential, one story at a time):
+1. **Development Cycle** (Sequential, one story at a time):

   **CRITICAL CONTEXT MANAGEMENT**:
   - **Context windows matter!** Always use fresh, clean context windows
   - **Model selection matters!** Use most powerful thinking model for SM story creation
   - **ALWAYS start new chat between SM, Dev, and QA work**

-   **Step 1 - Story Creation**: 
+   **Step 1 - Story Creation**:
   - **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
   - SM executes create-next-story task
   - Review generated story in `docs/stories/`
   - Update status from "Draft" to "Approved"
-   
-   **Step 2 - Story Implementation**: 
+
+   **Step 2 - Story Implementation**:
   - **NEW CLEAN CHAT** → `@dev`
   - Agent asks which story to implement
   - Include story file content to save dev agent lookup time
   - Dev follows tasks/subtasks, marking completion
   - Dev maintains File List of all changes
   - Dev marks story as "Review" when complete with all tests passing
-   
+
   **Step 3 - Senior QA Review**:
   - **NEW CLEAN CHAT** → `@qa` → execute review-story task
   - QA performs senior developer code review
@@ -494,7 +531,7 @@ that can handle [specific requirements]."
   - QA appends results to story's QA Results section
   - If approved: Status → "Done"
   - If changes needed: Status stays "Review" with unchecked items for dev
-   
+
   **Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete

 **Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
@@ -502,6 +539,7 @@ that can handle [specific requirements]."
 ### Status Tracking Workflow

 Stories progress through defined statuses:
+
 - **Draft** → **Approved** → **InProgress** → **Done**

 Each status change requires user verification and approval before proceeding.
@@ -509,6 +547,7 @@ Each status change requires user verification and approval before proceeding.
 ### Workflow Types

 #### Greenfield Development
+
 - Business analysis and market research
 - Product requirements and feature definition  
 - System architecture and design
@@ -522,6 +561,7 @@ Each status change requires user verification and approval before proceeding.
 **Complete Brownfield Workflow Options**:

 **Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
+
 1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
 2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
 3. **Focused documentation**: `@analyst` → `*document-project`
@@ -532,18 +572,19 @@ Each status change requires user verification and approval before proceeding.
   - Avoids bloating docs with unused code

 **Option 2: Document-First (Good for Smaller Projects)**:
+
 1. **Upload project to Gemini Web**
 2. **Document everything**: `@analyst` → `*document-project`
 3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
   - More thorough but can create excessive documentation

-2. **Requirements Gathering**:
+4. **Requirements Gathering**:
   - **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
   - **Analyzes**: Existing system, constraints, integration points
   - **Defines**: Enhancement scope, compatibility requirements, risk assessment
   - **Creates**: Epic and story structure for changes

-3. **Architecture Planning**:
+5. **Architecture Planning**:
   - **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
   - **Integration Strategy**: How new features integrate with existing system
   - **Migration Planning**: Gradual rollout and backwards compatibility
@@ -552,10 +593,12 @@ Each status change requires user verification and approval before proceeding.
 **Brownfield-Specific Resources**:

 **Templates**:
+
 - `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
 - `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems

 **Tasks**:
+
 - `document-project`: Generates comprehensive documentation from existing codebase
 - `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
 - `brownfield-create-story`: Creates individual story for small, isolated changes
@@ -563,18 +606,21 @@ Each status change requires user verification and approval before proceeding.
 **When to Use Each Approach**:

 **Full Brownfield Workflow** (Recommended for):
+
 - Major feature additions
 - System modernization
 - Complex integrations
 - Multiple related changes

 **Quick Epic/Story Creation** (Use when):
+
 - Single, focused enhancement
 - Isolated bug fixes
 - Small feature additions
 - Well-documented existing system

 **Critical Success Factors**:
+
 1. **Documentation First**: Always run `document-project` if docs are outdated/missing
 2. **Context Matters**: Provide agents access to relevant code sections
 3. **Integration Focus**: Emphasize compatibility and non-breaking changes
@@ -590,6 +636,7 @@ Each status change requires user verification and approval before proceeding.
 - `docs/architecture.md` - System Architecture Document

 **Why These Names Matter**:
+
 - Agents automatically reference these files during development
 - Sharding tasks expect these specific filenames
 - Workflow automation depends on standard naming
@@ -608,6 +655,7 @@ Each status change requires user verification and approval before proceeding.
 Templates with Level 2 headings (`##`) can be automatically sharded:

 **Original PRD**:
+
 ```markdown
 ## Goals and Background Context
 ## Requirements  
@@ -616,6 +664,7 @@ Templates with Level 2 headings (`##`) can be automatically sharded:
 ```

 **After Sharding**:
+
 - `docs/prd/goals-and-background-context.md`
 - `docs/prd/requirements.md`
 - `docs/prd/user-interface-design-goals.md`
@@ -628,12 +677,14 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
 ### Environment-Specific Usage

 **Web UI Best For**:
+
 - Initial planning and documentation phases
 - Cost-effective large document creation
 - Agent consultation and brainstorming
 - Multi-agent workflows with orchestrator

 **IDE Best For**:
+
 - Active development and implementation
 - File operations and project integration
 - Story management and development cycles
@@ -668,6 +719,7 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
 For full details, see `CONTRIBUTING.md`. Key points:

 **Fork Workflow**:
+
 1. Fork the repository
 2. Create feature branches
 3. Submit PRs to `next` branch (default) or `main` for critical fixes only
@@ -675,12 +727,14 @@ For full details, see `CONTRIBUTING.md`. Key points:
 5. One feature/fix per PR

 **PR Requirements**:
+
 - Clear descriptions (max 200 words) with What/Why/How/Testing
 - Use conventional commits (feat:, fix:, docs:)
 - Atomic commits - one logical change per commit
 - Must align with guiding principles

 **Core Principles** (from GUIDING-PRINCIPLES.md):
+
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
 - **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
@@ -702,12 +756,14 @@ Expansion packs extend BMad-Method beyond traditional software development into
 ### Available Expansion Packs

 **Technical Packs**:
+
 - **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
 - **Game Development**: Game designers, level designers, narrative writers
 - **Mobile Development**: iOS/Android specialists, mobile UX experts
 - **Data Science**: ML engineers, data scientists, visualization experts

 **Non-Technical Packs**:
+
 - **Business Strategy**: Consultants, financial analysts, marketing strategists
 - **Creative Writing**: Plot architects, character developers, world builders
 - **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
@@ -715,6 +771,7 @@ Expansion packs extend BMad-Method beyond traditional software development into
 - **Legal Support**: Contract analysts, compliance checkers

 **Specialty Packs**:
+
 - **Expansion Creator**: Tools to build your own expansion packs
 - **RPG Game Master**: Tabletop gaming assistance
 - **Life Event Planning**: Wedding planners, event coordinators
@@ -724,11 +781,13 @@ Expansion packs extend BMad-Method beyond traditional software development into

 1. **Browse Available Packs**: Check `expansion-packs/` directory
 2. **Get Inspiration**: See `docs/expansion-packs.md` for detailed examples and ideas
-3. **Install via CLI**: 
+3. **Install via CLI**:
+
   ```bash
   npx bmad-method install
   # Select "Install expansion pack" option
   ```
+
 4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents

 ### Creating Custom Expansion Packs