ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad/bmm/workflows/4-implementation/create-story
History
Brian Madison cfedecbd53 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>
 		2025-11-02 21:18:33 -06:00
..
README.md docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00
checklist.md docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00
instructions.md docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00
template.md docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00
workflow.yaml docs: massive documentation overhaul + introduce Paige (Documentation Guide agent) 2025-11-02 21:18:33 -06:00

README.md

Create Story Workflow

Just-in-time story generation creating one story at a time based on epic backlog state. Run by Scrum Master (SM) agent to ensure planned stories align with approved epics.

Table of Contents

Usage

# SM initiates next story creation
bmad sm *create-story

When to run:

  • Sprint has capacity for new work
  • Previous story is Done/Approved
  • Team ready for next planned story

Key Features

Strict Planning Enforcement

  • Only creates stories enumerated in epics.md
  • Halts if story not found in epic plan
  • Prevents scope creep through validation

Intelligent Document Discovery

  • Auto-finds tech spec: tech-spec-epic-{N}-*.md
  • Discovers architecture docs across directories
  • Builds prioritized requirement sources

Source Document Grounding

  • Every requirement traced to source
  • No invention of domain facts
  • Citations included in output

Non-Interactive Mode

  • Default "#yolo" mode minimizes prompts
  • Smooth automated story preparation
  • Only prompts when critical

Inputs & Outputs

Required Files

File Purpose Priority
epics.md Story enumeration (MANDATORY) Critical
tech-spec-epic-{N}-*.md Epic technical spec High
PRD.md Product requirements Medium
Architecture docs Technical constraints Low

Auto-Discovered Docs

  • tech-stack.md, unified-project-structure.md
  • testing-strategy.md, backend/frontend-architecture.md
  • data-models.md, database-schema.md, api-specs.md

Output

Story Document: {story_dir}/story-{epic}.{story}.md

  • User story statement (role, action, benefit)
  • Acceptance criteria from tech spec/epics
  • Tasks mapped to ACs
  • Testing requirements
  • Dev notes with sources
  • Status: "Draft"

Workflow Behavior

Story Number Management

  • Auto-detects next story number
  • No duplicates or skipped numbers
  • Maintains epic.story convention

Update vs Create

  • If current story not Done: Updates existing
  • If current story Done: Creates next (if planned)

Validation Safeguards

No Story Found:

"No planned next story found in epics.md for epic {N}.
Run *correct-course to add/modify epic stories."

Missing Config: Ensure dev_story_location set in config.yaml

Integration

v6 Implementation Cycle

  1. create-story ← Current step (defines "what")
  2. story-context (adds technical "how")
  3. dev-story (implementation)
  4. code-review (validation)
  5. correct-course (if needed)
  6. retrospective (after epic)

Document Priority

  1. tech_spec_file - Epic-specific spec
  2. epics_file - Story breakdown
  3. prd_file - Business requirements
  4. architecture_docs - Technical guidance

Configuration

# bmad/bmm/config.yaml
dev_story_location: ./stories
output_folder: ./output

# workflow.yaml defaults
non_interactive: true
auto_run_context: true

Troubleshooting

Issue Solution
"No planned next story" Run *correct-course to add story to epic
Missing story_dir Set dev_story_location in config
Tech spec not found Use naming: tech-spec-epic-{N}-*.md
No architecture docs Add docs to docs/ or output/ folder

For workflow details, see instructions.md and checklist.md.