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
214
bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
Normal file
214
bmad/bmm/workflows/2-plan-workflows/tech-spec/checklist.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Tech-Spec Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate tech-spec workflow outputs are context-rich, definitive, complete, and implementation-ready.
|
||||
|
||||
**Scope**: Levels 0-1 software projects
|
||||
|
||||
**Expected Outputs**: tech-spec.md + story files (1 for Level 0, 2-3 for Level 1)
|
||||
|
||||
**New Standard**: Tech-spec should be comprehensive enough to replace story-context for Level 0-1 projects
|
||||
|
||||
---
|
||||
|
||||
## 1. Output Files Exist
|
||||
|
||||
- [ ] tech-spec.md created in output folder
|
||||
- [ ] Story file(s) created in dev_story_location
|
||||
- Level 0: 1 story file (story-{slug}.md)
|
||||
- Level 1: epics.md + 2-3 story files (story-{epic-slug}-N.md)
|
||||
- [ ] bmm-workflow-status.yaml updated (if not standalone mode)
|
||||
- [ ] No unfilled {{template_variables}} in any files
|
||||
|
||||
---
|
||||
|
||||
## 2. Context Gathering (NEW - CRITICAL)
|
||||
|
||||
### Document Discovery
|
||||
|
||||
- [ ] **Existing documents loaded**: Product brief, research docs found and incorporated (if they exist)
|
||||
- [ ] **Document-project output**: Checked for {output_folder}/docs/index.md (brownfield codebase map)
|
||||
- [ ] **Sharded documents**: If sharded versions found, ALL sections loaded and synthesized
|
||||
- [ ] **Context summary**: loaded_documents_summary lists all sources used
|
||||
|
||||
### Project Stack Detection
|
||||
|
||||
- [ ] **Setup files identified**: package.json, requirements.txt, or equivalent found and parsed
|
||||
- [ ] **Framework detected**: Exact framework name and version captured (e.g., "Express 4.18.2")
|
||||
- [ ] **Dependencies extracted**: All production dependencies with specific versions
|
||||
- [ ] **Dev tools identified**: TypeScript, Jest, ESLint, pytest, etc. with versions
|
||||
- [ ] **Scripts documented**: Available npm/pip/etc scripts identified
|
||||
- [ ] **Stack summary**: project_stack_summary is complete and accurate
|
||||
|
||||
### Brownfield Analysis (if applicable)
|
||||
|
||||
- [ ] **Directory structure**: Main code directories identified and documented
|
||||
- [ ] **Code patterns**: Dominant patterns identified (class-based, functional, MVC, etc.)
|
||||
- [ ] **Naming conventions**: Existing conventions documented (camelCase, snake_case, etc.)
|
||||
- [ ] **Key modules**: Important existing modules/services identified
|
||||
- [ ] **Testing patterns**: Test framework and patterns documented
|
||||
- [ ] **Structure summary**: existing_structure_summary is comprehensive
|
||||
|
||||
---
|
||||
|
||||
## 3. Tech-Spec Definitiveness (CRITICAL)
|
||||
|
||||
### No Ambiguity Allowed
|
||||
|
||||
- [ ] **Zero "or" statements**: NO "use X or Y", "either A or B", "options include"
|
||||
- [ ] **Specific versions**: All frameworks, libraries, tools have EXACT versions
|
||||
- ✅ GOOD: "Python 3.11", "React 18.2.0", "winston v3.8.2 (from package.json)"
|
||||
- ❌ BAD: "Python 2 or 3", "React 18+", "a logger like pino or winston"
|
||||
- [ ] **Definitive decisions**: Every technical choice is final, not a proposal
|
||||
- [ ] **Stack-aligned**: Decisions reference detected project stack
|
||||
|
||||
### Implementation Clarity
|
||||
|
||||
- [ ] **Source tree changes**: EXACT file paths with CREATE/MODIFY/DELETE actions
|
||||
- ✅ GOOD: "src/services/UserService.ts - MODIFY - Add validateEmail() method"
|
||||
- ❌ BAD: "Update some files in the services folder"
|
||||
- [ ] **Technical approach**: Describes SPECIFIC implementation using detected stack
|
||||
- [ ] **Existing patterns**: Documents brownfield patterns to follow (if applicable)
|
||||
- [ ] **Integration points**: Specific modules, APIs, services identified
|
||||
|
||||
---
|
||||
|
||||
## 4. Context-Rich Content (NEW)
|
||||
|
||||
### Context Section
|
||||
|
||||
- [ ] **Available Documents**: Lists all loaded documents
|
||||
- [ ] **Project Stack**: Complete framework and dependency information
|
||||
- [ ] **Existing Codebase Structure**: Brownfield analysis or greenfield notation
|
||||
|
||||
### The Change Section
|
||||
|
||||
- [ ] **Problem Statement**: Clear, specific problem definition
|
||||
- [ ] **Proposed Solution**: Concrete solution approach
|
||||
- [ ] **Scope In/Out**: Clear boundaries defined
|
||||
|
||||
### Development Context Section
|
||||
|
||||
- [ ] **Relevant Existing Code**: References to specific files and line numbers (brownfield)
|
||||
- [ ] **Framework Dependencies**: Complete list with exact versions from project
|
||||
- [ ] **Internal Dependencies**: Internal modules listed
|
||||
- [ ] **Configuration Changes**: Specific config file updates identified
|
||||
|
||||
### Developer Resources Section
|
||||
|
||||
- [ ] **File Paths Reference**: Complete list of all files involved
|
||||
- [ ] **Key Code Locations**: Functions, classes, modules with file:line references
|
||||
- [ ] **Testing Locations**: Specific test directories and patterns
|
||||
- [ ] **Documentation Updates**: Docs that need updating identified
|
||||
|
||||
---
|
||||
|
||||
## 5. Story Quality
|
||||
|
||||
### Story Format
|
||||
|
||||
- [ ] All stories use "As a [role], I want [capability], so that [benefit]" format
|
||||
- [ ] Each story has numbered acceptance criteria
|
||||
- [ ] Tasks reference AC numbers: (AC: #1), (AC: #2)
|
||||
- [ ] Dev Notes section links to tech-spec.md
|
||||
|
||||
### Story Context Integration (NEW)
|
||||
|
||||
- [ ] **Tech-Spec Reference**: Story explicitly references tech-spec.md as primary context
|
||||
- [ ] **Dev Agent Record**: Includes all required sections (Context Reference, Agent Model, etc.)
|
||||
- [ ] **Test Results section**: Placeholder ready for dev execution
|
||||
- [ ] **Review Notes section**: Placeholder ready for code review
|
||||
|
||||
### Story Sequencing (If Level 1)
|
||||
|
||||
- [ ] **Vertical slices**: Each story delivers complete, testable functionality
|
||||
- [ ] **Sequential ordering**: Stories in logical progression
|
||||
- [ ] **No forward dependencies**: No story depends on later work
|
||||
- [ ] Each story leaves system in working state
|
||||
|
||||
### Coverage
|
||||
|
||||
- [ ] Story acceptance criteria derived from tech-spec
|
||||
- [ ] Story tasks map to tech-spec implementation guide
|
||||
- [ ] Files in stories match tech-spec source tree
|
||||
- [ ] Key code references align with tech-spec Developer Resources
|
||||
|
||||
---
|
||||
|
||||
## 6. Epic Quality (Level 1 Only)
|
||||
|
||||
- [ ] **Epic title**: User-focused outcome (not implementation detail)
|
||||
- [ ] **Epic slug**: Clean kebab-case slug (2-3 words)
|
||||
- [ ] **Epic goal**: Clear purpose and value statement
|
||||
- [ ] **Epic scope**: Boundaries clearly defined
|
||||
- [ ] **Success criteria**: Measurable outcomes
|
||||
- [ ] **Story map**: Visual representation of epic → stories
|
||||
- [ ] **Implementation sequence**: Logical story ordering with dependencies
|
||||
- [ ] **Tech-spec reference**: Links back to tech-spec.md
|
||||
|
||||
---
|
||||
|
||||
## 7. Workflow Status Integration
|
||||
|
||||
- [ ] bmm-workflow-status.yaml updated (if exists)
|
||||
- [ ] Current phase reflects tech-spec completion
|
||||
- [ ] Progress percentage updated appropriately
|
||||
- [ ] Next workflow clearly identified
|
||||
|
||||
---
|
||||
|
||||
## 8. Implementation Readiness (NEW - ENHANCED)
|
||||
|
||||
### Can Developer Start Immediately?
|
||||
|
||||
- [ ] **All context available**: Brownfield analysis + stack details + existing patterns
|
||||
- [ ] **No research needed**: Developer doesn't need to hunt for framework versions or patterns
|
||||
- [ ] **Specific file paths**: Developer knows exactly which files to create/modify
|
||||
- [ ] **Code references**: Can find similar code to reference (brownfield)
|
||||
- [ ] **Testing clear**: Knows what to test and how
|
||||
- [ ] **Deployment documented**: Knows how to deploy and rollback
|
||||
|
||||
### Tech-Spec Replaces Story-Context?
|
||||
|
||||
- [ ] **Comprehensive enough**: Contains all info typically in story-context XML
|
||||
- [ ] **Brownfield analysis**: If applicable, includes codebase reconnaissance
|
||||
- [ ] **Framework specifics**: Exact versions and usage patterns
|
||||
- [ ] **Pattern guidance**: Shows examples of existing patterns to follow
|
||||
|
||||
---
|
||||
|
||||
## 9. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **Non-definitive technical decisions** (any "option A or B" or vague choices)
|
||||
- [ ] ❌ **Missing versions** (framework/library without specific version)
|
||||
- [ ] ❌ **Context not gathered** (didn't check for document-project, setup files, etc.)
|
||||
- [ ] ❌ **Stack mismatch** (decisions don't align with detected project stack)
|
||||
- [ ] ❌ **Stories don't match template** (missing Dev Agent Record sections)
|
||||
- [ ] ❌ **Missing tech-spec sections** (required section missing from enhanced template)
|
||||
- [ ] ❌ **Stories have forward dependencies** (would break sequential implementation)
|
||||
- [ ] ❌ **Vague source tree** (file changes not specific with actions)
|
||||
- [ ] ❌ **No brownfield analysis** (when document-project output exists but wasn't used)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- **Context Gathering Score**: [Comprehensive / Partial / Insufficient]
|
||||
- **Definitiveness Score**: [All definitive / Some ambiguity / Significant ambiguity]
|
||||
- **Brownfield Integration**: [N/A - Greenfield / Excellent / Partial / Missing]
|
||||
- **Stack Alignment**: [Perfect / Good / Partial / None]
|
||||
|
||||
## **Strengths:**
|
||||
|
||||
## **Issues to address:**
|
||||
|
||||
## **Recommended actions:**
|
||||
|
||||
**Ready for implementation?** [Yes / No - explain]
|
||||
|
||||
**Can skip story-context?** [Yes - tech-spec is comprehensive / No - additional context needed / N/A]
|
||||
|
||||
---
|
||||
|
||||
_The tech-spec should be a RICH CONTEXT DOCUMENT that gives developers everything they need without requiring separate context generation._
|
||||
@@ -0,0 +1,58 @@
|
||||
# {{project_name}} - Epic Breakdown
|
||||
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
|
||||
---
|
||||
|
||||
## Epic: {{epic_title}}
|
||||
|
||||
**Slug:** {{epic_slug}}
|
||||
|
||||
### Goal
|
||||
|
||||
{{epic_goal}}
|
||||
|
||||
### Scope
|
||||
|
||||
{{epic_scope}}
|
||||
|
||||
### Success Criteria
|
||||
|
||||
{{epic_success_criteria}}
|
||||
|
||||
### Dependencies
|
||||
|
||||
{{epic_dependencies}}
|
||||
|
||||
---
|
||||
|
||||
## Story Map
|
||||
|
||||
{{story_map}}
|
||||
|
||||
---
|
||||
|
||||
## Story Summaries
|
||||
|
||||
{{story_summaries}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Timeline
|
||||
|
||||
**Total Story Points:** {{total_points}}
|
||||
|
||||
**Estimated Timeline:** {{estimated_timeline}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
{{implementation_sequence}}
|
||||
|
||||
---
|
||||
|
||||
## Tech-Spec Reference
|
||||
|
||||
See [tech-spec.md](../tech-spec.md) for complete technical implementation details.
|
||||
@@ -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>
|
||||
@@ -0,0 +1,451 @@
|
||||
# Level 1 - Epic and Stories Generation
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This generates epic and user stories for Level 1 projects after tech-spec completion</critical>
|
||||
<critical>This is a lightweight story breakdown - not a full PRD</critical>
|
||||
<critical>Level 1 = coherent feature, 1-10 stories (prefer 2-3), 1 epic</critical>
|
||||
<critical>This workflow runs AFTER tech-spec.md has been completed</critical>
|
||||
<critical>Story 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 implementation tasks">
|
||||
|
||||
<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:
|
||||
|
||||
- Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
|
||||
- Implementation tasks from "Implementation Guide → Implementation Steps"
|
||||
- Time estimates from "Implementation Guide → Implementation Steps"
|
||||
- Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
|
||||
- Source tree from "Implementation Details → Source Tree Changes"
|
||||
- Framework dependencies from "Development Context → Framework/Libraries"
|
||||
- Existing code references from "Development Context → Relevant Existing Code"
|
||||
- File paths from "Developer Resources → File Paths Reference"
|
||||
- Key code locations from "Developer Resources → Key Code Locations"
|
||||
- Testing locations from "Developer Resources → Testing Locations"
|
||||
- Acceptance criteria from "Implementation Guide → Acceptance Criteria"
|
||||
</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Create single epic">
|
||||
|
||||
<action>Create 1 epic that represents the entire feature</action>
|
||||
<action>Epic title should be user-facing value statement</action>
|
||||
<action>Epic goal should describe why this matters to users</action>
|
||||
|
||||
<guidelines>
|
||||
**Epic Best Practices:**
|
||||
- Title format: User-focused outcome (not implementation detail)
|
||||
- Good: "JS Library Icon Reliability"
|
||||
- Bad: "Update recommendedLibraries.ts file"
|
||||
- Scope: Clearly define what's included/excluded
|
||||
- Success criteria: Measurable outcomes that define "done"
|
||||
</guidelines>
|
||||
|
||||
<example>
|
||||
**Epic:** JS Library Icon Reliability
|
||||
|
||||
**Goal:** Eliminate external dependencies for JS library icons to ensure consistent, reliable display and improve application performance.
|
||||
|
||||
**Scope:** Migrate all 14 recommended JS library icons from third-party CDN URLs (GitHub, jsDelivr) to internal static asset hosting.
|
||||
|
||||
**Success Criteria:**
|
||||
|
||||
- All library icons load from internal paths
|
||||
- Zero external requests for library icons
|
||||
- Icons load 50-200ms faster than baseline
|
||||
- No broken icons in production
|
||||
</example>
|
||||
|
||||
<action>Derive epic slug from epic title (kebab-case, 2-3 words max)</action>
|
||||
<example>
|
||||
|
||||
- "JS Library Icon Reliability" → "icon-reliability"
|
||||
- "OAuth Integration" → "oauth-integration"
|
||||
- "Admin Dashboard" → "admin-dashboard"
|
||||
</example>
|
||||
|
||||
<action>Initialize epics.md summary document using epics_template</action>
|
||||
|
||||
<action>Also capture project_level for the epic template</action>
|
||||
|
||||
<template-output file="{output_folder}/epics.md">project_level</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_title</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_slug</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_goal</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_scope</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_success_criteria</template-output>
|
||||
<template-output file="{output_folder}/epics.md">epic_dependencies</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Determine optimal story count">
|
||||
|
||||
<critical>Level 1 should have 2-3 stories maximum - prefer longer stories over more stories</critical>
|
||||
|
||||
<action>Analyze tech spec implementation tasks and time estimates</action>
|
||||
<action>Group related tasks into logical story boundaries</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Count Decision Matrix:**
|
||||
|
||||
**2 Stories (preferred for most Level 1):**
|
||||
|
||||
- Use when: Feature has clear build/verify split
|
||||
- Example: Story 1 = Build feature, Story 2 = Test and deploy
|
||||
- Typical points: 3-5 points per story
|
||||
|
||||
**3 Stories (only if necessary):**
|
||||
|
||||
- Use when: Feature has distinct setup, build, verify phases
|
||||
- Example: Story 1 = Setup, Story 2 = Core implementation, Story 3 = Integration and testing
|
||||
- Typical points: 2-3 points per story
|
||||
|
||||
**Never exceed 3 stories for Level 1:**
|
||||
|
||||
- If more needed, consider if project should be Level 2
|
||||
- Better to have longer stories (5 points) than more stories (5x 1-point stories)
|
||||
</guidelines>
|
||||
|
||||
<action>Determine story_count = 2 or 3 based on tech spec complexity</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Generate user stories from tech spec tasks">
|
||||
|
||||
<action>For each story (2-3 total), generate separate story file</action>
|
||||
<action>Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3</action>
|
||||
|
||||
<guidelines>
|
||||
**Story Generation Guidelines:**
|
||||
- Each story = multiple implementation tasks from tech spec
|
||||
- Story title format: User-focused deliverable (not implementation steps)
|
||||
- Include technical acceptance criteria from tech spec tasks
|
||||
- Link back to tech spec sections for implementation details
|
||||
|
||||
**CRITICAL: Acceptance Criteria Must Be:**
|
||||
|
||||
1. **Numbered** - AC #1, AC #2, AC #3, etc.
|
||||
2. **Specific** - No vague statements like "works well" or "is fast"
|
||||
3. **Testable** - Can be verified objectively
|
||||
4. **Complete** - Covers all success conditions
|
||||
5. **Independent** - Each AC tests one thing
|
||||
6. **Format**: Use Given/When/Then when applicable
|
||||
|
||||
**Good AC Examples:**
|
||||
✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds
|
||||
✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message
|
||||
✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage
|
||||
|
||||
**Bad AC Examples:**
|
||||
❌ "User can create account" (too vague)
|
||||
❌ "System performs well" (not measurable)
|
||||
❌ "Works correctly" (not specific)
|
||||
|
||||
**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
|
||||
|
||||
**Level 1 Typical Totals:**
|
||||
|
||||
- Total story points: 5-10 points
|
||||
- 2 stories: 3-5 points each
|
||||
- 3 stories: 2-3 points each
|
||||
- If total > 15 points, consider if this should be Level 2
|
||||
|
||||
**Story Structure (MUST match create-story format):**
|
||||
|
||||
- Status: Draft
|
||||
- Story: As a [role], I want [capability], so that [benefit]
|
||||
- Acceptance Criteria: Numbered list from tech spec
|
||||
- Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
|
||||
- Dev Notes: Technical summary, project structure notes, references
|
||||
- Dev Agent Record: Empty sections (tech-spec provides context)
|
||||
|
||||
**NEW: Comprehensive Context Fields**
|
||||
|
||||
Since tech-spec is context-rich, populate ALL template fields:
|
||||
|
||||
- dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
|
||||
- existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
|
||||
</guidelines>
|
||||
|
||||
<for-each story="1 to story_count">
|
||||
<action>Set story_path_{n} = "{dev_story_location}/story-{epic_slug}-{n}.md"</action>
|
||||
<action>Create story file from user_story_template with the following content:</action>
|
||||
|
||||
<template-output file="{story_path_{n}}">
|
||||
- story_title: User-focused deliverable title
|
||||
- role: User role (e.g., developer, user, admin)
|
||||
- capability: What they want to do
|
||||
- benefit: Why it matters
|
||||
- acceptance_criteria: Specific, measurable criteria from tech spec
|
||||
- tasks_subtasks: Implementation tasks with AC references
|
||||
- technical_summary: High-level approach, key decisions
|
||||
- files_to_modify: List of files that will change (from tech-spec "Developer Resources → File Paths Reference")
|
||||
- test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations")
|
||||
- story_points: Estimated effort (1/2/3/5)
|
||||
- time_estimate: Days/hours estimate
|
||||
- dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points")
|
||||
- existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations")
|
||||
- architecture_references: Links to tech-spec.md sections
|
||||
</template-output>
|
||||
</for-each>
|
||||
|
||||
<critical>Generate exactly {story_count} story files (2 or 3 based on Step 3 decision)</critical>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Create story map and implementation sequence with dependency validation">
|
||||
|
||||
<critical>Stories MUST be ordered so earlier stories don't depend on later ones</critical>
|
||||
<critical>Each story must have CLEAR, TESTABLE acceptance criteria</critical>
|
||||
|
||||
<action>Analyze dependencies between stories:
|
||||
|
||||
**Dependency Rules:**
|
||||
|
||||
1. Infrastructure/setup → Feature implementation → Testing/polish
|
||||
2. Database changes → API changes → UI changes
|
||||
3. Backend services → Frontend components
|
||||
4. Core functionality → Enhancement features
|
||||
5. No story can depend on a later story!
|
||||
|
||||
**Validate Story Sequence:**
|
||||
For each story N, check:
|
||||
|
||||
- Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
|
||||
- Does it only use things from Story 1...N-1? ✅ VALID
|
||||
- Can it be implemented independently or using only prior stories? ✅ VALID
|
||||
|
||||
If invalid dependencies found, REORDER stories!
|
||||
</action>
|
||||
|
||||
<action>Generate visual story map showing epic → stories hierarchy with dependencies</action>
|
||||
<action>Calculate total story points across all stories</action>
|
||||
<action>Estimate timeline based on total points (1-2 points per day typical)</action>
|
||||
<action>Define implementation sequence with explicit dependency notes</action>
|
||||
|
||||
<example>
|
||||
## Story Map
|
||||
|
||||
```
|
||||
Epic: Icon Reliability
|
||||
├── Story 1: Build Icon Infrastructure (3 points)
|
||||
│ Dependencies: None (foundational work)
|
||||
│
|
||||
└── Story 2: Test and Deploy Icons (2 points)
|
||||
Dependencies: Story 1 (requires infrastructure)
|
||||
```
|
||||
|
||||
**Total Story Points:** 5
|
||||
**Estimated Timeline:** 1 sprint (1 week)
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
1. **Story 1** → Build icon infrastructure (setup, download, configure)
|
||||
- Dependencies: None
|
||||
- Deliverable: Icon files downloaded, organized, accessible
|
||||
|
||||
2. **Story 2** → Test and deploy (depends on Story 1)
|
||||
- Dependencies: Story 1 must be complete
|
||||
- Deliverable: Icons verified, tested, deployed to production
|
||||
|
||||
**Dependency Validation:** ✅ Valid sequence - no forward dependencies
|
||||
</example>
|
||||
|
||||
<template-output file="{output_folder}/epics.md">story_summaries</template-output>
|
||||
<template-output file="{output_folder}/epics.md">story_map</template-output>
|
||||
<template-output file="{output_folder}/epics.md">total_points</template-output>
|
||||
<template-output file="{output_folder}/epics.md">estimated_timeline</template-output>
|
||||
<template-output file="{output_folder}/epics.md">implementation_sequence</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Update status and populate story backlog">
|
||||
|
||||
<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>
|
||||
<param>populate_stories_from: {epics_output_file}</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>✅ Status updated! Loaded {{total_stories}} stories from epics.</output>
|
||||
<output>Next: {{next_workflow}} ({{next_agent}} agent)</output>
|
||||
</check>
|
||||
|
||||
<check if="success == false">
|
||||
<output>⚠️ Status update failed: {{error}}</output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Auto-validate story quality and sequence">
|
||||
|
||||
<critical>Auto-run validation - NOT optional!</critical>
|
||||
|
||||
<action>Running automatic story validation...</action>
|
||||
|
||||
<action>**Validate Story Sequence (CRITICAL):**
|
||||
|
||||
For each story, check:
|
||||
|
||||
1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
|
||||
2. Are dependencies clearly documented? ✅ PASS
|
||||
3. Can stories be implemented in order 1→2→3? ✅ PASS
|
||||
|
||||
If sequence validation FAILS:
|
||||
|
||||
- Identify the problem dependencies
|
||||
- Propose new ordering
|
||||
- Ask user to confirm reordering
|
||||
</action>
|
||||
|
||||
<action>**Validate Acceptance Criteria Quality:**
|
||||
|
||||
For each story's AC, check:
|
||||
|
||||
1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
|
||||
2. Is it specific and testable? ✅ Required
|
||||
3. Does it use Given/When/Then or equivalent? ✅ Recommended
|
||||
4. Are all success conditions covered? ✅ Required
|
||||
|
||||
Count vague AC (contains "works", "good", "fast", "well"):
|
||||
|
||||
- 0 vague AC: ✅ EXCELLENT
|
||||
- 1-2 vague AC: ⚠️ WARNING - Should improve
|
||||
- 3+ vague AC: ❌ FAIL - Must improve
|
||||
</action>
|
||||
|
||||
<action>**Validate Story Completeness:**
|
||||
|
||||
1. Do all stories map to tech spec tasks? ✅ Required
|
||||
2. Do story points align with tech spec estimates? ✅ Recommended
|
||||
3. Are dependencies clearly noted? ✅ Required
|
||||
4. Does each story have testable AC? ✅ Required
|
||||
</action>
|
||||
|
||||
<action>Generate validation report</action>
|
||||
|
||||
<check if="sequence validation fails OR AC quality fails">
|
||||
<output>❌ **Story Validation Failed:**
|
||||
|
||||
{{issues_found}}
|
||||
|
||||
**Recommended Fixes:**
|
||||
{{recommended_fixes}}
|
||||
|
||||
Shall I fix these issues? (yes/no)</output>
|
||||
|
||||
<ask>Apply fixes? (yes/no)</ask>
|
||||
|
||||
<check if="yes">
|
||||
<action>Apply fixes (reorder stories, rewrite vague AC, add missing details)</action>
|
||||
<action>Re-validate</action>
|
||||
<output>✅ Validation passed after fixes!</output>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="validation passes">
|
||||
<output>✅ **Story Validation Passed!**
|
||||
|
||||
**Sequence:** ✅ Valid (no forward dependencies)
|
||||
**AC Quality:** ✅ All specific and testable
|
||||
**Completeness:** ✅ All tech spec tasks covered
|
||||
**Dependencies:** ✅ Clearly documented
|
||||
|
||||
Stories are implementation-ready!</output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Finalize and provide user guidance">
|
||||
|
||||
<action>Confirm all validation passed</action>
|
||||
<action>Verify total story points align with tech spec time estimates</action>
|
||||
<action>Confirm epic and stories are complete</action>
|
||||
|
||||
**Level 1 Planning Complete!**
|
||||
|
||||
**Epic:** {{epic_title}}
|
||||
**Total Stories:** {{story_count}}
|
||||
**Total Story Points:** {{total_points}}
|
||||
**Estimated Timeline:** {{estimated_timeline}}
|
||||
|
||||
**Generated Artifacts:**
|
||||
|
||||
- `tech-spec.md` → Technical source of truth
|
||||
- `epics.md` → Epic and story summary
|
||||
- `story-{epic_slug}-1.md` → First story (ready for implementation)
|
||||
- `story-{epic_slug}-2.md` → Second story
|
||||
{{#if story_3}}
|
||||
- `story-{epic_slug}-3.md` → Third story
|
||||
{{/if}}
|
||||
|
||||
**Story Location:** `{dev_story_location}/`
|
||||
|
||||
**Next Steps - Iterative Implementation:**
|
||||
|
||||
**🎯 RECOMMENDED - Direct to Development (Level 1):**
|
||||
|
||||
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
|
||||
- ✅ Dependencies clearly mapped
|
||||
|
||||
**You can skip story-context for most Level 1 stories!**
|
||||
|
||||
**1. Start with Story 1:**
|
||||
a. Load DEV agent: `{project-root}/bmad/bmm/agents/dev.md`
|
||||
b. Run `dev-story` workflow (select story-{epic_slug}-1.md)
|
||||
c. Tech-spec provides all context needed
|
||||
d. Implement story 1
|
||||
|
||||
**2. After Story 1 Complete:**
|
||||
|
||||
- Repeat for story-{epic_slug}-2.md
|
||||
- Reference completed story 1 in your work
|
||||
|
||||
**3. After Story 2 Complete:**
|
||||
{{#if story_3}}
|
||||
|
||||
- Repeat for story-{epic_slug}-3.md
|
||||
{{/if}}
|
||||
- Level 1 feature complete!
|
||||
|
||||
**Option B - Generate Additional Context (optional):**
|
||||
|
||||
Only needed for extremely complex multi-story dependencies:
|
||||
|
||||
1. Load SM agent: `{project-root}/bmad/bmm/agents/sm.md`
|
||||
2. Run `story-context` workflow for complex stories
|
||||
3. Then load DEV agent and run `dev-story`
|
||||
|
||||
**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 for story 1 (RECOMMENDED - tech-spec has all context)
|
||||
2. Generate additional story context first (for complex dependencies)
|
||||
3. Exit for now
|
||||
|
||||
Select option (1-3):</ask>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
1133
bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
Normal file
1133
bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,181 @@
|
||||
# {{project_name}} - Technical Specification
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
**Change Type:** {{change_type}}
|
||||
**Development Context:** {{development_context}}
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Available Documents
|
||||
|
||||
{{loaded_documents_summary}}
|
||||
|
||||
### Project Stack
|
||||
|
||||
{{project_stack_summary}}
|
||||
|
||||
### Existing Codebase Structure
|
||||
|
||||
{{existing_structure_summary}}
|
||||
|
||||
---
|
||||
|
||||
## The Change
|
||||
|
||||
### Problem Statement
|
||||
|
||||
{{problem_statement}}
|
||||
|
||||
### Proposed Solution
|
||||
|
||||
{{solution_overview}}
|
||||
|
||||
### Scope
|
||||
|
||||
**In Scope:**
|
||||
|
||||
{{scope_in}}
|
||||
|
||||
**Out of Scope:**
|
||||
|
||||
{{scope_out}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Source Tree Changes
|
||||
|
||||
{{source_tree_changes}}
|
||||
|
||||
### Technical Approach
|
||||
|
||||
{{technical_approach}}
|
||||
|
||||
### Existing Patterns to Follow
|
||||
|
||||
{{existing_patterns}}
|
||||
|
||||
### Integration Points
|
||||
|
||||
{{integration_points}}
|
||||
|
||||
---
|
||||
|
||||
## Development Context
|
||||
|
||||
### Relevant Existing Code
|
||||
|
||||
{{existing_code_references}}
|
||||
|
||||
### Dependencies
|
||||
|
||||
**Framework/Libraries:**
|
||||
|
||||
{{framework_dependencies}}
|
||||
|
||||
**Internal Modules:**
|
||||
|
||||
{{internal_dependencies}}
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
{{configuration_changes}}
|
||||
|
||||
### Existing Conventions (Brownfield)
|
||||
|
||||
{{existing_conventions}}
|
||||
|
||||
### Test Framework & Standards
|
||||
|
||||
{{test_framework_info}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Stack
|
||||
|
||||
{{implementation_stack}}
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
{{technical_details}}
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
{{development_setup}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
### Setup Steps
|
||||
|
||||
{{setup_steps}}
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
{{implementation_steps}}
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
---
|
||||
|
||||
## Developer Resources
|
||||
|
||||
### File Paths Reference
|
||||
|
||||
{{file_paths_complete}}
|
||||
|
||||
### Key Code Locations
|
||||
|
||||
{{key_code_locations}}
|
||||
|
||||
### Testing Locations
|
||||
|
||||
{{testing_locations}}
|
||||
|
||||
### Documentation to Update
|
||||
|
||||
{{documentation_updates}}
|
||||
|
||||
---
|
||||
|
||||
## UX/UI Considerations
|
||||
|
||||
{{ux_ui_considerations}}
|
||||
|
||||
---
|
||||
|
||||
## Testing Approach
|
||||
|
||||
{{testing_approach}}
|
||||
|
||||
---
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
### Deployment Steps
|
||||
|
||||
{{deployment_steps}}
|
||||
|
||||
### Rollback Plan
|
||||
|
||||
{{rollback_plan}}
|
||||
|
||||
### Monitoring
|
||||
|
||||
{{monitoring_approach}}
|
||||
@@ -0,0 +1,87 @@
|
||||
# Story: {{story_title}}
|
||||
|
||||
Status: Draft
|
||||
|
||||
## Story
|
||||
|
||||
As a {{role}},
|
||||
I want {{capability}},
|
||||
so that {{benefit}}.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
{{tasks_subtasks}}
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Technical Summary
|
||||
|
||||
{{technical_summary}}
|
||||
|
||||
### Tech-Spec Reference
|
||||
|
||||
**Full details:** See [tech-spec.md](../tech-spec.md)
|
||||
|
||||
The tech-spec contains comprehensive context including:
|
||||
|
||||
- Brownfield codebase analysis (if applicable)
|
||||
- Framework and library details with versions
|
||||
- Existing patterns to follow
|
||||
- Integration points and dependencies
|
||||
- Complete implementation guidance
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
- **Files to modify:** {{files_to_modify}}
|
||||
- **Expected test locations:** {{test_locations}}
|
||||
- **Estimated effort:** {{story_points}} story points ({{time_estimate}})
|
||||
- **Dependencies:** {{dependencies}}
|
||||
|
||||
### Key Code References
|
||||
|
||||
{{existing_code_references}}
|
||||
|
||||
### References
|
||||
|
||||
- **Tech Spec:** [tech-spec.md](../tech-spec.md) - Primary context document
|
||||
- **Architecture:** {{architecture_references}}
|
||||
|
||||
---
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Context Reference
|
||||
|
||||
**Primary Context:** [tech-spec.md](../tech-spec.md) - Contains all brownfield analysis, framework details, and implementation guidance
|
||||
|
||||
<!-- Additional context XML paths will be added here if story-context workflow is run -->
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Debug Log References
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### File List
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
### Test Results
|
||||
|
||||
<!-- Will be populated during dev-story execution -->
|
||||
|
||||
---
|
||||
|
||||
## Review Notes
|
||||
|
||||
<!-- Will be populated during code review -->
|
||||
60
bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
Normal file
60
bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
Normal file
@@ -0,0 +1,60 @@
|
||||
# Technical Specification Workflow (Level 0)
|
||||
name: tech-spec-sm
|
||||
description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
project_name: "{config_source}:project_name"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Runtime variables (captured during workflow execution)
|
||||
project_level: runtime-captured
|
||||
project_type: runtime-captured
|
||||
development_context: runtime-captured
|
||||
change_type: runtime-captured
|
||||
field_type: runtime-captured
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/tech-spec-template.md"
|
||||
|
||||
# Story generation instructions (invoked based on level)
|
||||
instructions_level0_story: "{installed_path}/instructions-level0-story.md"
|
||||
instructions_level1_stories: "{installed_path}/instructions-level1-stories.md"
|
||||
|
||||
# Templates
|
||||
user_story_template: "{installed_path}/user-story-template.md"
|
||||
epics_template: "{installed_path}/epics-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/tech-spec.md"
|
||||
user_story_file: "{output_folder}/user-story.md"
|
||||
epics_file: "{output_folder}/epics.md"
|
||||
|
||||
# Recommended input documents (optional for Level 0)
|
||||
recommended_inputs:
|
||||
- bug_report: "Bug description or issue ticket"
|
||||
- feature_request: "Brief feature description"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
product_brief:
|
||||
whole: "{output_folder}/*brief*.md"
|
||||
sharded: "{output_folder}/*brief*/index.md"
|
||||
|
||||
research:
|
||||
whole: "{output_folder}/*research*.md"
|
||||
sharded: "{output_folder}/*research*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
standalone: true
|
||||
Reference in New Issue
Block a user