bmad-method 6.0.0-alpha.3 → 6.0.0-alpha.5

package/bmad/core/tools/shard-doc.xml

@@ -12,28 +12,18 @@
   </llm>
 
   <critical-context>
-    <i>This task ONLY supports automated sharding via @kayvan/markdown-tree-parser</i>
-    <i>The tool automatically handles: section splitting, heading level adjustment, code block detection, index generation</i>
-    <i>All markdown formatting is preserved during sharding</i>
+    <i>Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index</i>
   </critical-context>
 
   <flow>
-    <step n="1" title="Verify Tool Installation">
-      <action>Check if @kayvan/markdown-tree-parser is installed globally</action>
-      <action>Run: npm list -g @kayvan/markdown-tree-parser</action>
-      <action if="not installed">Inform user that tool needs to be installed</action>
-      <action if="not installed">Run: npm install -g @kayvan/markdown-tree-parser</action>
-      <action if="installation fails">HALT with error message about npm/node requirements</action>
-    </step>
-
-    <step n="2" title="Get Source Document">
+    <step n="1" title="Get Source Document">
       <action>Ask user for the source document path if not provided already</action>
       <action>Verify file exists and is accessible</action>
       <action>Verify file is markdown format (.md extension)</action>
       <action if="file not found or not markdown">HALT with error message</action>
     </step>
 
-    <step n="3" title="Get Destination Folder">
+    <step n="2" title="Get Destination Folder">
       <action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
       <action>Example: /path/to/architecture.md → /path/to/architecture/</action>
       <action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
@@ -44,21 +34,21 @@
       <action if="permission denied">HALT with error message</action>
     </step>
 
-    <step n="4" title="Execute Sharding">
+    <step n="3" title="Execute Sharding">
       <action>Inform user that sharding is beginning</action>
-      <action>Execute command: md-tree explode [source-document] [destination-folder]</action>
+      <action>Execute command: `npx @kayvan/markdown-tree-parser [source-document] [destination-folder]`</action>
       <action>Capture command output and any errors</action>
       <action if="command fails">HALT and display error to user</action>
     </step>
 
-    <step n="5" title="Verify Output">
+    <step n="4" title="Verify Output">
       <action>Check that destination folder contains sharded files</action>
       <action>Verify index.md was created in destination folder</action>
       <action>Count the number of files created</action>
       <action if="no files created">HALT with error message</action>
     </step>
 
-    <step n="6" title="Report Completion">
+    <step n="5" title="Report Completion">
       <action>Display completion report to user including:</action>
       <i>- Source document path and name</i>
       <i>- Destination folder path</i>
@@ -70,31 +60,6 @@
   </flow>
 
   <halt-conditions critical="true">
-    <i>HALT if @kayvan/markdown-tree-parser cannot be installed</i>
-    <i>HALT if Node.js or npm is not available</i>
-    <i>HALT if source document does not exist or is inaccessible</i>
-    <i>HALT if source document is not markdown format (.md)</i>
-    <i>HALT if destination folder cannot be created</i>
-    <i>HALT if user does not have write permissions to destination</i>
-    <i>HALT if md-tree explode command fails</i>
-    <i>HALT if no output files were created</i>
+    <i>HALT if npx command fails or produces no output files</i>
   </halt-conditions>
-
-  <tool-info>
-    <name>@kayvan/markdown-tree-parser</name>
-    <command>md-tree explode [source-document] [destination-folder]</command>
-    <installation>npm install -g @kayvan/markdown-tree-parser</installation>
-    <requirements>
-      <i>Node.js installed</i>
-      <i>npm package manager</i>
-      <i>Global npm installation permissions</i>
-    </requirements>
-    <features>
-      <i>Automatic section splitting by level 2 headings</i>
-      <i>Automatic heading level adjustment</i>
-      <i>Handles edge cases (code blocks, diagrams)</i>
-      <i>Generates navigable index.md</i>
-      <i>Preserves all markdown formatting</i>
-    </features>
-  </tool-info>
 </tool>

package/docs/document-sharding-guide.md

@@ -0,0 +1,447 @@
+# 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, epics
+- `tech-spec` - Brief, research
+- `architecture` - PRD, epics, UX design
+- `solutioning-gate-check` - All planning docs
+
+#### Phase 4 (Selective Load)
+
+Workflows load only needed sections:
+
+**sprint-planning** (Full Load):
+
+- Needs ALL epics to build complete status
+
+**epic-tech-context, create-story, story-context, 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
+Epic-tech-context for Epic 3: 45k tokens
+Create-story for Epic 3: 45k tokens
+```
+
+**After Sharding:**
+
+```bash
+/shard-doc
+Source: docs/PRD.md
+Destination: docs/prd/
+
+Created:
+  prd/index.md
+  prd/overview.md (3k tokens)
+  prd/epic-1-auth.md (3k tokens)
+  prd/epic-2-dashboard.md (3k tokens)
+  prd/epic-3-reports.md (3k tokens)
+  ...15 epic files
+```
+
+**Result:**
+
+```
+Epic-tech-context for Epic 3: 3k tokens (93% reduction!)
+Create-story for Epic 3: 3k tokens (93% reduction!)
+```
+
+### 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](../src/modules/bmm/workflows/README.md) - Workflow overview
+- [Workflow Creation Guide](../src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md) - Custom workflow patterns
+
+---
+
+**Document sharding is optional but powerful** - use it when efficiency matters for large projects!

package/docs/index.md

@@ -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
@@ -104,32 +104,35 @@ Instructions for loading agents and running workflows in your development enviro
 ## 📊 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
 ```
 
 ---
@@ -139,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
@@ -147,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
@@ -155,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
@@ -220,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
-
----

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.0-alpha.3",
+  "version": "6.0.0-alpha.5",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",