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

package/docs/document-sharding-guide.md

@@ -1,449 +0,0 @@
-# Document Sharding Guide
-
-Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
-
-## Table of Contents
-
-- [What is Document Sharding?](#what-is-document-sharding)
-- [When to Use Sharding](#when-to-use-sharding)
-- [How Sharding Works](#how-sharding-works)
-- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
-- [Workflow Support](#workflow-support)
-- [Best Practices](#best-practices)
-- [Examples](#examples)
-
-## What is Document Sharding?
-
-Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
-
-- **Selective Loading** - Workflows load only the sections they need
-- **Reduced Token Usage** - Massive efficiency gains for large projects
-- **Better Organization** - Logical section-based file structure
-- **Maintained Context** - Index file preserves document structure
-
-### Architecture
-
-```
-Before Sharding:
-docs/
-└── PRD.md (large 50k token file)
-
-After Sharding:
-docs/
-└── prd/
-    ├── index.md                    # Table of contents with descriptions
-    ├── overview.md                 # Section 1
-    ├── user-requirements.md        # Section 2
-    ├── technical-requirements.md   # Section 3
-    └── ...                         # Additional sections
-```
-
-## When to Use Sharding
-
-### Ideal Candidates
-
-**Large Multi-Epic Projects:**
-
-- Very large complex PRDs
-- Architecture documents with multiple system layers
-- Epic files with 4+ epics (especially for Phase 4)
-- UX design specs covering multiple subsystems
-
-**Token Thresholds:**
-
-- **Consider sharding**: Documents > 20k tokens
-- **Strongly recommended**: Documents > 40k tokens
-- **Critical for efficiency**: Documents > 60k tokens
-
-### When NOT to Shard
-
-**Small Projects:**
-
-- Single epic projects
-- Level 0-1 projects (tech-spec only)
-- Documents under 10k tokens
-- Quick prototypes
-
-**Frequently Updated Docs:**
-
-- Active work-in-progress documents
-- Documents updated daily
-- Documents where whole-file context is essential
-
-## How Sharding Works
-
-### Sharding Process
-
-1. **Tool Execution**: Run `npx @kayvan/markdown-tree-parser source.md destination/` - this is abstracted with the core shard-doc task which is installed as a slash command or manual task rule depending on your tools.
-2. **Section Extraction**: Tool splits by level 2 headings
-3. **File Creation**: Each section becomes a separate file
-4. **Index Generation**: `index.md` created with structure and descriptions
-
-### Workflow Discovery
-
-BMad workflows use a **dual discovery system**:
-
-1. **Try whole document first** - Look for `document-name.md`
-2. **Check for sharded version** - Look for `document-name/index.md`
-3. **Priority rule** - Whole document takes precedence if both exist
-
-### Loading Strategies
-
-**Full Load (Phase 1-3 workflows):**
-
-```
-If sharded:
-  - Read index.md
-  - Read ALL section files
-  - Treat as single combined document
-```
-
-**Selective Load (Phase 4 workflows):**
-
-```
-If sharded epics and working on Epic 3:
-  - Read epics/index.md
-  - Load ONLY epics/epic-3.md
-  - Skip all other epic files
-  - 90%+ token savings!
-```
-
-## Using the Shard-Doc Tool
-
-### CLI Command
-
-```bash
-# Activate bmad-master or analyst agent, then:
-/shard-doc
-```
-
-### Interactive Process
-
-```
-Agent: Which document would you like to shard?
-User: docs/PRD.md
-
-Agent: Default destination: docs/prd/
-       Accept default? [y/n]
-User: y
-
-Agent: Sharding PRD.md...
-       ✓ Created 12 section files
-       ✓ Generated index.md
-       ✓ Complete!
-```
-
-### What Gets Created
-
-**index.md structure:**
-
-```markdown
-# PRD - Index
-
-## Sections
-
-1. [Overview](./overview.md) - Project vision and objectives
-2. [User Requirements](./user-requirements.md) - Feature specifications
-3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
-4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
-   ...
-```
-
-**Individual section files:**
-
-- Named from heading text (kebab-case)
-- Contains complete section content
-- Preserves all markdown formatting
-- Can be read independently
-
-## Workflow Support
-
-### Universal Support
-
-**All BMM workflows support both formats:**
-
-- ✅ Whole documents
-- ✅ Sharded documents
-- ✅ Automatic detection
-- ✅ Transparent to user
-
-### Workflow-Specific Patterns
-
-#### Phase 1-3 (Full Load)
-
-Workflows load entire sharded documents:
-
-- `product-brief` - Research, brainstorming docs
-- `prd` - Product brief, research
-- `gdd` - Game brief, research
-- `create-ux-design` - PRD, brief, architecture (if available)
-- `tech-spec` - Brief, research
-- `architecture` - PRD, UX design (if available)
-- `create-epics-and-stories` - PRD, architecture
-- `implementation-readiness` - All planning docs
-
-#### Phase 4 (Selective Load)
-
-Workflows load only needed sections:
-
-**sprint-planning** (Full Load):
-
-- Needs ALL epics to build complete status
-
-**create-story, code-review** (Selective):
-
-```
-Working on Epic 3, Story 2:
-  ✓ Load epics/epic-3.md only
-  ✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
-
-Result: 90%+ token reduction for 10-epic projects!
-```
-
-### Input File Patterns
-
-Workflows use standardized patterns:
-
-```yaml
-input_file_patterns:
-  prd:
-    whole: '{output_folder}/*prd*.md'
-    sharded: '{output_folder}/*prd*/index.md'
-
-  epics:
-    whole: '{output_folder}/*epic*.md'
-    sharded_index: '{output_folder}/*epic*/index.md'
-    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
-```
-
-## Best Practices
-
-### Sharding Strategy
-
-**Do:**
-
-- ✅ Shard after planning phase complete
-- ✅ Keep level 2 headings well-organized
-- ✅ Use descriptive section names
-- ✅ Shard before Phase 4 implementation
-- ✅ Keep original file as backup initially
-
-**Don't:**
-
-- ❌ Shard work-in-progress documents
-- ❌ Shard small documents (<20k tokens)
-- ❌ Mix sharded and whole versions
-- ❌ Manually edit index.md structure
-
-### Naming Conventions
-
-**Good Section Names:**
-
-```markdown
-## Epic 1: User Authentication
-
-## Technical Requirements
-
-## System Architecture
-
-## UX Design Principles
-```
-
-**Poor Section Names:**
-
-```markdown
-## Section 1
-
-## Part A
-
-## Details
-
-## More Info
-```
-
-### File Management
-
-**When to Re-shard:**
-
-- Significant structural changes to document
-- Adding/removing major sections
-- After major refactoring
-
-**Updating Sharded Docs:**
-
-1. Edit individual section files directly
-2. OR edit original, delete sharded folder, re-shard
-3. Don't manually edit index.md
-
-## Examples
-
-### Example 1: Large PRD
-
-**Scenario:** 15-epic project, PRD is 45k tokens
-
-**Before Sharding:**
-
-```
-Every workflow loads entire 45k token PRD
-Architecture workflow: 45k tokens
-UX design workflow: 45k tokens
-```
-
-**After Sharding:**
-
-```bash
-/shard-doc
-Source: docs/PRD.md
-Destination: docs/prd/
-
-Created:
-  prd/index.md
-  prd/overview.md (3k tokens)
-  prd/functional-requirements.md (8k tokens)
-  prd/non-functional-requirements.md (6k tokens)
-  prd/user-personas.md (4k tokens)
-  ...additional FR/NFR sections
-```
-
-**Result:**
-
-```
-Architecture workflow: Can load specific sections needed
-UX design workflow: Can load specific sections needed
-Significant token reduction for large requirement docs!
-```
-
-### Example 2: Sharding Epics File
-
-**Scenario:** 8 epics with detailed stories, 35k tokens total
-
-```bash
-/shard-doc
-Source: docs/bmm-epics.md
-Destination: docs/epics/
-
-Created:
-  epics/index.md
-  epics/epic-1.md
-  epics/epic-2.md
-  ...
-  epics/epic-8.md
-```
-
-**Efficiency Gain:**
-
-```
-Working on Epic 5 stories:
-  Old: Load all 8 epics (35k tokens)
-  New: Load epic-5.md only (4k tokens)
-  Savings: 88% reduction
-```
-
-### Example 3: Architecture Document
-
-**Scenario:** Multi-layer system architecture, 28k tokens
-
-```bash
-/shard-doc
-Source: docs/architecture.md
-Destination: docs/architecture/
-
-Created:
-  architecture/index.md
-  architecture/system-overview.md
-  architecture/frontend-architecture.md
-  architecture/backend-services.md
-  architecture/data-layer.md
-  architecture/infrastructure.md
-  architecture/security-architecture.md
-```
-
-**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
-
-## Custom Workflow Integration
-
-### For Workflow Builders
-
-When creating custom workflows that load large documents:
-
-**1. Add input_file_patterns to workflow.yaml:**
-
-```yaml
-input_file_patterns:
-  your_document:
-    whole: '{output_folder}/*your-doc*.md'
-    sharded: '{output_folder}/*your-doc*/index.md'
-```
-
-**2. Add discovery instructions to instructions.md:**
-
-```markdown
-## Document Discovery
-
-1. Search for whole document: _your-doc_.md
-2. Check for sharded version: _your-doc_/index.md
-3. If sharded: Read index + ALL sections (or specific sections if selective load)
-4. Priority: Whole document first
-```
-
-**3. Choose loading strategy:**
-
-- **Full Load**: Read all sections when sharded
-- **Selective Load**: Read only relevant sections (requires section identification logic)
-
-### Pattern Templates
-
-**Full Load Pattern:**
-
-```xml
-<action>Search for document: {output_folder}/*doc-name*.md</action>
-<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read index.md to understand structure</action>
-<action if="sharded found">Read ALL section files listed in index</action>
-<action if="sharded found">Combine content as single document</action>
-```
-
-**Selective Load Pattern (with section ID):**
-
-```xml
-<action>Determine section needed (e.g., epic_num = 3)</action>
-<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
-<action if="sharded found">Read ONLY the specific section file needed</action>
-<action if="sharded found">Skip all other section files</action>
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Both whole and sharded exist:**
-
-- Workflows will use whole document (priority rule)
-- Delete or archive the one you don't want
-
-**Index.md out of sync:**
-
-- Delete sharded folder
-- Re-run shard-doc on original
-
-**Workflow can't find document:**
-
-- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
-- Verify index.md exists in sharded folder
-- Check output_folder path in config
-
-**Sections too granular:**
-
-- Combine sections in original document
-- Use fewer level 2 headings
-- Re-shard
-
-## Related Documentation
-
-- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
-- [BMM Workflows Guide](./modules/bmm/index.md#-workflow-guides) - Workflow overview
-- [Workflow Creation Guide](./modules/bmb/workflows/index) - Custom workflow patterns
-
----
-
-**Document sharding is optional but powerful** - use it when efficiency matters for large projects!

package/docs/getting-started/installation.md

@@ -1,76 +0,0 @@
-# Installation
-
-Get BMAD Method running in your project in under 2 minutes.
-
-## Quick Install
-
-```bash
-npx bmad-method@alpha install
-```
-
-This interactive installer will:
-
-1. Detect your IDE (Claude Code, Cursor, VS Code, etc.)
-2. Let you choose which modules to install
-3. Configure agents and workflows for your project
-
-## Requirements
-
-- **Node.js** 18+ (for the installer)
-- **Git** (recommended for version control)
-- An **AI-powered IDE** or access to Claude/ChatGPT/Gemini
-
-## Module Options
-
-During installation, you'll choose which modules to install:
-
-| Module   | Description      | Best For                                 |
-| -------- | ---------------- | ---------------------------------------- |
-| **BMM**  | BMAD Method Core | Software development projects            |
-| **BMGD** | Game Development | Game projects with specialized workflows |
-| **BMB**  | Builder          | Creating custom agents and workflows     |
-
-## Post-Installation
-
-After installation, your project will have:
-
-```
-your-project/
-├── _bmad/              # BMAD configuration and agents
-│   ├── bmm/            # Method module (if installed)
-│   ├── bmgd/           # Game dev module (if installed)
-│   └── config.yaml     # Your project configuration
-├── .claude/            # IDE-specific setup (varies by IDE)
-└── ... your code
-```
-
-## Next Steps
-
-1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
-2. **Check your [IDE Guide](../ide-info/index.md)** for IDE-specific tips
-3. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
-
-## Alternative: Web Bundles
-
-Don't want to install? Use BMAD agents directly in:
-
-- **Claude Projects** - Upload the web bundle
-- **ChatGPT** - Use custom GPT bundles
-- **Gemini** - Import agent prompts
-
-See the [Web Bundles Guide](../web-bundles-gemini-gpt-guide.md) for details.
-
-## Troubleshooting
-
-### Common Issues
-
-**"Command not found: npx"**
-: Install Node.js 18+ from [nodejs.org](https://nodejs.org)
-
-**"Permission denied"**
-: Run with appropriate permissions or check your npm configuration
-
-**IDE not detected**
-: The installer will prompt you to select your IDE manually
-
-For more help, see [Troubleshooting](../modules/bmm/troubleshooting.md) or join our [Discord](https://discord.gg/bmad).

package/docs/ide-info/auggie.md

@@ -1,31 +0,0 @@
-# BMAD Method - Auggie CLI Instructions
-
-## Activating Agents
-
-BMAD agents can be installed in multiple locations based on your setup.
-
-### Common Locations
-
-- User Home: `~/.augment/commands/`
-- Project: `.augment/commands/`
-- Custom paths you selected
-
-### How to Use
-
-1. **Type Trigger**: Use `@{agent-name}` in your prompt
-2. **Activate**: Agent persona activates
-3. **Tasks**: Use `@task-{task-name}` for tasks
-
-### Examples
-
-```
-@dev - Activate development agent
-@architect - Activate architect agent
-@task-setup - Execute setup task
-```
-
-### Notes
-
-- Agents can be in multiple locations
-- Check your installation paths
-- Activation syntax same across all locations

package/docs/ide-info/claude-code.md

@@ -1,25 +0,0 @@
-# BMAD Method - Claude Code Instructions
-
-## Activating Agents
-
-BMAD agents are installed as slash commands in `.claude/commands/bmad/`.
-
-### How to Use
-
-1. **Type Slash Command**: Start with `/` to see available commands
-2. **Select Agent**: Type `/bmad-{agent-name}` (e.g., `/bmad-dev`)
-3. **Execute**: Press Enter to activate that agent persona
-
-### Examples
-
-```
-/bmad:bmm:agents:dev - Activate development agent
-/bmad:bmm:agents:architect - Activate architect agent
-/bmad:bmm:workflows:dev-story - Execute dev-story workflow
-```
-
-### Notes
-
-- Commands are autocompleted when you type `/`
-- Agent remains active for the conversation
-- Start a new conversation to switch agents

package/docs/ide-info/cline.md

@@ -1,31 +0,0 @@
-# BMAD Method - Cline Instructions
-
-## Activating Agents
-
-BMAD agents are installed as **toggleable rules** in `.clinerules/` directory.
-
-### Important: Rules are OFF by default
-
-- Rules are NOT automatically loaded to avoid context pollution
-- You must manually enable the agent you want to use
-
-### How to Use
-
-1. **Open Rules Panel**: Click the rules icon below the chat input
-2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`)
-3. **Activate in Chat**: Type `@{agent-name}` to activate that persona
-4. **Disable When Done**: Toggle OFF to free up context
-
-### Best Practices
-
-- Only enable 1-2 agents at a time to preserve context
-- Disable agents when switching tasks
-- Rules are numbered (01-, 02-) for organization, not priority
-
-### Example
-
-```
-Toggle ON: 01-core-dev.md
-In chat: "@dev help me refactor this code"
-When done: Toggle OFF the rule
-```

package/docs/ide-info/codex.md

@@ -1,21 +0,0 @@
-# BMAD Method - Codex Instructions
-
-## Activating Agents
-
-BMAD agents, tasks and workflows are installed as custom prompts in
-`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it
-defaults to `$HOME/.codex/`.
-
-### Examples
-
-```
-/bmad-bmm-agents-dev - Activate development agent
-/bmad-bmm-agents-architect - Activate architect agent
-/bmad-bmm-workflows-dev-story - Execute dev-story workflow
-```
-
-### Notes
-
-Prompts are autocompleted when you type /
-Agent remains active for the conversation
-Start a new conversation to switch agents

package/docs/ide-info/crush.md

@@ -1,30 +0,0 @@
-# BMAD Method - Crush Instructions
-
-## Activating Agents
-
-BMAD agents are installed as commands in `.crush/commands/bmad/`.
-
-### How to Use
-
-1. **Open Command Palette**: Use Crush command interface
-2. **Navigate**: Browse to `_bmad/{module}/agents/`
-3. **Select Agent**: Choose the agent command
-4. **Execute**: Run to activate agent persona
-
-### Command Structure
-
-```
-.crush/commands/bmad/
-├── agents/          # All agents
-├── tasks/           # All tasks
-├── core/            # Core module
-│   ├── agents/
-│   └── tasks/
-└── {module}/        # Other modules
-```
-
-### Notes
-
-- Commands organized by module
-- Can browse hierarchically
-- Agent activates for session

package/docs/ide-info/cursor.md

@@ -1,25 +0,0 @@
-# BMAD Method - Cursor Instructions
-
-## Activating Agents
-
-BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.
-
-### How to Use
-
-1. **Reference in Chat**: Use `@_bmad/{module}/agents/{agent-name}`
-2. **Include Entire Module**: Use `@_bmad/{module}`
-3. **Reference Index**: Use `@_bmad/index` for all available agents
-
-### Examples
-
-```
-@_bmad/core/agents/dev - Activate dev agent
-@_bmad/bmm/agents/architect - Activate architect agent
-@_bmad/core - Include all core agents/tasks
-```
-
-### Notes
-
-- Rules are Manual type - only loaded when explicitly referenced
-- No automatic context pollution
-- Can combine multiple agents: `@_bmad/core/agents/dev @_bmad/core/agents/test`