mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)
## 📚 Complete Documentation Restructure **BMM Documentation Hub Created:** - New centralized documentation system at `src/modules/bmm/docs/` - 18 comprehensive guides organized by topic (7000+ lines total) - Clear learning paths for greenfield, brownfield, and quick spec flows - Professional technical writing standards throughout **New Documentation:** - `README.md` - Complete documentation hub with navigation - `quick-start.md` - 15-minute getting started guide - `agents-guide.md` - Comprehensive 12-agent reference (45 min read) - `party-mode.md` - Multi-agent collaboration guide (20 min read) - `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read) - `brownfield-guide.md` - Existing codebase development (53 min read) - `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read) - `workflows-analysis.md` - Phase 1 workflows (12 min read) - `workflows-planning.md` - Phase 2 workflows (19 min read) - `workflows-solutioning.md` - Phase 3 workflows (13 min read) - `workflows-implementation.md` - Phase 4 workflows (33 min read) - `workflows-testing.md` - Testing & QA workflows (29 min read) - `workflow-architecture-reference.md` - Architecture workflow deep-dive - `workflow-document-project-reference.md` - Document-project workflow reference - `enterprise-agentic-development.md` - Team collaboration patterns - `faq.md` - Comprehensive Q&A covering all topics - `glossary.md` - Complete terminology reference - `troubleshooting.md` - Common issues and solutions **Documentation Improvements:** - Removed all version/date footers (git handles versioning) - Agent customization docs now include full rebuild process - Cross-referenced links between all guides - Reading time estimates for all major docs - Consistent professional formatting and structure **Consolidated & Streamlined:** - Module README (`src/modules/bmm/README.md`) streamlined to lean signpost - Root README polished with better hierarchy and clear CTAs - Moved docs from root `docs/` to module-specific locations - Better separation of user docs vs. developer reference ## 🤖 New Agent: Paige (Documentation Guide) **Role:** Technical documentation specialist and information architect **Expertise:** - Professional technical writing standards - Documentation structure and organization - Information architecture and navigation - User-focused content design - Style guide enforcement **Status:** Work in progress - Paige will evolve as documentation needs grow **Integration:** - Listed in agents-guide.md, glossary.md, FAQ - Available for all phases (documentation is continuous) - Can be customized like all BMM agents ## 🔧 Additional Changes - Updated agent manifest with Paige - Updated workflow manifest with new documentation workflows - Fixed workflow-to-agent mappings across all guides - Improved root README with clearer Quick Start section - Better module structure explanations - Enhanced community links with Discord channel names **Total Impact:** - 18 new/restructured documentation files - 7000+ lines of professional technical documentation - Complete navigation system with cross-references - Clear learning paths for all user types - Foundation for knowledge base (coming in beta) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Brian Madison
@@ -0,0 +1,200 @@
|
||||
# Level 0 - Minimal User Story Generation
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This generates a single user story for Level 0 atomic changes</critical>
|
||||
<critical>Level 0 = single file change, bug fix, or small isolated task</critical>
|
||||
<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
|
||||
<critical>Output format MUST match create-story template for compatibility with story-context and dev-story workflows</critical>
|
||||
|
||||
<step n="1" goal="Load tech spec and extract the change">
|
||||
|
||||
<action>Read the completed tech-spec.md file from {output_folder}/tech-spec.md</action>
|
||||
<action>Load bmm-workflow-status.yaml from {output_folder}/bmm-workflow-status.yaml (if exists)</action>
|
||||
<action>Extract dev_story_location from config (where stories are stored)</action>
|
||||
|
||||
<action>Extract from the ENHANCED tech-spec structure:
|
||||
|
||||
- Problem statement from "The Change → Problem Statement" section
|
||||
- Solution overview from "The Change → Proposed Solution" section
|
||||
- Scope from "The Change → Scope" section
|
||||
- Source tree from "Implementation Details → Source Tree Changes" section
|
||||
- Time estimate from "Implementation Guide → Implementation Steps" section
|
||||
- Acceptance criteria from "Implementation Guide → Acceptance Criteria" section
|
||||
- Framework dependencies from "Development Context → Framework/Libraries" section
|
||||
- Existing code references from "Development Context → Relevant Existing Code" section
|
||||
- File paths from "Developer Resources → File Paths Reference" section
|
||||
- Key code locations from "Developer Resources → Key Code Locations" section
|
||||
- Testing locations from "Developer Resources → Testing Locations" section
|
||||
</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Generate story slug and filename">
|
||||
|
||||
<action>Derive a short URL-friendly slug from the feature/change name</action>
|
||||
<action>Max slug length: 3-5 words, kebab-case format</action>
|
||||
|
||||
<example>
|
||||
- "Migrate JS Library Icons" → "icon-migration"
|
||||
- "Fix Login Validation Bug" → "login-fix"
|
||||
- "Add OAuth Integration" → "oauth-integration"
|
||||
</example>
|
||||
|
||||
<action>Set story_filename = "story-{slug}.md"</action>
|
||||
<action>Set story_path = "{dev_story_location}/story-{slug}.md"</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Create user story in standard format">
|
||||
|
||||
<action>Create 1 story that describes the technical change as a deliverable</action>
|
||||
<action>Story MUST use create-story template format for compatibility</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Point Estimation:**
|
||||
- 1 point = < 1 day (2-4 hours)
|
||||
- 2 points = 1-2 days
|
||||
- 3 points = 2-3 days
|
||||
- 5 points = 3-5 days (if this high, question if truly Level 0)
|
||||
|
||||
**Story Title Best Practices:**
|
||||
|
||||
- Use active, user-focused language
|
||||
- Describe WHAT is delivered, not HOW
|
||||
- Good: "Icon Migration to Internal CDN"
|
||||
- Bad: "Run curl commands to download PNGs"
|
||||
|
||||
**Story Description Format:**
|
||||
|
||||
- As a [role] (developer, user, admin, etc.)
|
||||
- I want [capability/change]
|
||||
- So that [benefit/value]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
- Extract from tech-spec "Testing Approach" section
|
||||
- Must be specific, measurable, and testable
|
||||
- Include performance criteria if specified
|
||||
|
||||
**Tasks/Subtasks:**
|
||||
|
||||
- Map directly to tech-spec "Implementation Guide" tasks
|
||||
- Use checkboxes for tracking
|
||||
- Reference AC numbers: (AC: #1), (AC: #2)
|
||||
- Include explicit testing subtasks
|
||||
|
||||
**Dev Notes:**
|
||||
|
||||
- Extract technical constraints from tech-spec
|
||||
- Include file paths from "Developer Resources → File Paths Reference"
|
||||
- Include existing code references from "Development Context → Relevant Existing Code"
|
||||
- Reference architecture patterns if applicable
|
||||
- Cite tech-spec sections for implementation details
|
||||
- Note dependencies (internal and external)
|
||||
|
||||
**NEW: Comprehensive Context**
|
||||
|
||||
Since tech-spec is now context-rich, populate all new template fields:
|
||||
|
||||
- dependencies: Extract from "Development Context" and "Implementation Details → Integration Points"
|
||||
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
|
||||
</guidelines>
|
||||
|
||||
<action>Initialize story file using user_story_template</action>
|
||||
|
||||
<template-output file="{story_path}">story_title</template-output>
|
||||
<template-output file="{story_path}">role</template-output>
|
||||
<template-output file="{story_path}">capability</template-output>
|
||||
<template-output file="{story_path}">benefit</template-output>
|
||||
<template-output file="{story_path}">acceptance_criteria</template-output>
|
||||
<template-output file="{story_path}">tasks_subtasks</template-output>
|
||||
<template-output file="{story_path}">technical_summary</template-output>
|
||||
<template-output file="{story_path}">files_to_modify</template-output>
|
||||
<template-output file="{story_path}">test_locations</template-output>
|
||||
<template-output file="{story_path}">story_points</template-output>
|
||||
<template-output file="{story_path}">time_estimate</template-output>
|
||||
<template-output file="{story_path}">dependencies</template-output>
|
||||
<template-output file="{story_path}">existing_code_references</template-output>
|
||||
<template-output file="{story_path}">architecture_references</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Update status - Level 0 single story">
|
||||
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: tech-spec</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Tech-spec complete! Next: {{next_workflow}}</output>
|
||||
</check>
|
||||
|
||||
<action>Load {{status_file_path}}</action>
|
||||
<action>Set STORIES_SEQUENCE: [{slug}]</action>
|
||||
<action>Set TODO_STORY: {slug}</action>
|
||||
<action>Set TODO_TITLE: {{story_title}}</action>
|
||||
<action>Set IN_PROGRESS_STORY: (empty)</action>
|
||||
<action>Set STORIES_DONE: []</action>
|
||||
<action>Save {{status_file_path}}</action>
|
||||
|
||||
<output>Story queue initialized with single story: {slug}</output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Provide user guidance for next steps">
|
||||
|
||||
<action>Display completion summary</action>
|
||||
|
||||
**Level 0 Planning Complete!**
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `tech-spec.md` → Technical source of truth
|
||||
- `story-{slug}.md` → User story ready for implementation
|
||||
|
||||
**Story Location:** `{story_path}`
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
**🎯 RECOMMENDED - Direct to Development (Level 0):**
|
||||
|
||||
Since the tech-spec is now CONTEXT-RICH with:
|
||||
|
||||
- ✅ Brownfield codebase analysis (if applicable)
|
||||
- ✅ Framework and library details with exact versions
|
||||
- ✅ Existing patterns and code references
|
||||
- ✅ Complete file paths and integration points
|
||||
|
||||
**You can skip story-context and go straight to dev!**
|
||||
|
||||
1. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
|
||||
2. Run `dev-story` workflow
|
||||
3. Begin implementation immediately
|
||||
|
||||
**Option B - Generate Additional Context (optional):**
|
||||
|
||||
Only needed for extremely complex scenarios:
|
||||
|
||||
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
|
||||
2. Run `story-context` workflow (generates additional XML context)
|
||||
3. Then load DEV agent and run `dev-story` workflow
|
||||
|
||||
**Progress Tracking:**
|
||||
|
||||
- All decisions logged in: `bmm-workflow-status.yaml`
|
||||
- Next action clearly identified
|
||||
|
||||
<ask>Ready to proceed? Choose your path:
|
||||
|
||||
1. Go directly to dev-story (RECOMMENDED - tech-spec has all context)
|
||||
2. Generate additional story context (for complex edge cases)
|
||||
3. Exit for now
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
Reference in New Issue
Block a user