BMAD-METHOD/expansion-packs/story-implementation/workflows/story-implementation.yml

563 lines
25 KiB
YAML

workflow:
id: story-implementation
name: Story Implementation - Epic to PR Ready
description: >-
Complete story implementation workflow from epic context to PR delivery with learning extraction and MANDATORY epic retrospectives.
Phase 1: Story Preparation (Epic + Story Number → Story Ready for Development)
Phase 2: Implementation (Story Development with Validation)
Phase 3: Quality Review (Architecture, Business, and QA Validation)
Phase 4: Learning Extraction (Triage + Collaborative Review)
Phase 5: Commit and PR Preparation (Context Generation)
Phase 6: PR Creation and Epic Progress (Delivery + Tracking)
Phase 7: Epic Retrospective (MANDATORY when epic reaches 100% completion)
type: story-implementation
shard_configuration:
base_path: "docs/stories/"
naming_pattern: "epic{epic_number}.story{story_number}.{shard_type}.md"
main_story_pattern: "epic{epic_number}.story{story_number}.story.md"
max_lines_per_shard: 400
shard_types:
architecture_review: "arch-review"
business_review: "biz-review"
process_review: "proc-review"
qa_review: "qa-review"
ux_review: "ux-review"
consolidation: "consolidated"
implementation: "implementation"
validation: "validation"
learning_triage: "learning"
learning_review: "review"
pr_context: "pr-context"
pr_information: "pr-info"
auto_shard_triggers:
- content_exceeds_max_lines: true
- section_exceeds_lines: 150
- parallel_agent_writes: true
visualization: |
```mermaid
flowchart TD
A[Epic + Story Number] --> A1{PO: Validate Epic<br/>Readiness}
A1 -->|Pass| B[SM: Create Story]
A1 -->|Fail| A2[PO: Address Epic Issues<br/>max 3 retries]
A2 --> A1
B --> C{SM: Validate Draft}
C -->|Pass| D{PO: Approve Story}
C -->|Fail| C2[SM: Revise Story<br/>max 3 retries]
C2 --> C
D -->|Pass| E[Infra: Setup Environment]
D -->|Fail| D2[PO: Clarify Requirements<br/>max 3 retries]
D2 --> D
E --> F[Dev: Implement Story<br/>with quality gates]
F --> G{Dev: Pre-Review Validation<br/>quality gates + DoD}
G -->|Pass| H[Round 1 Reviews<br/>Parallel]
G -->|Fail| G2[Dev: Fix Issues<br/>max 5 retries]
G2 --> G
H --> H1[Architect Review]
H --> H2[Business Review]
H --> H3[Process Review]
H --> H4[QA Review]
H --> H5[UX Review]
H1 --> I[Architect: Consolidate<br/>All Feedback]
H2 --> I
H3 --> I
H4 --> I
H5 --> I
I --> J[Dev: Implement<br/>Consolidated Fixes]
J --> J2{Dev: Verify<br/>Quality Gates}
J2 -->|Pass| K{Architect: Validate<br/>Fixes + Playwright}
J2 -->|Fail| J3[Dev: Fix Quality Issues<br/>max 3 retries]
J3 --> J2
K -->|Pass| L[Arch: Learning<br/>Triage]
K -->|Fail| K2[Dev: Additional Fixes<br/>max 3 retries]
K2 --> J2
L --> M[SM: Party Mode<br/>Learning Review]
M --> N[Dev: Commit &<br/>Prepare PR Context]
N --> O[PO: Create<br/>Comprehensive PR]
O --> P[SM: Update<br/>Epic Progress]
P --> P1{Epic Complete?<br/>100% Status Check}
P1 -->|Yes| R[SM: Epic Retrospective<br/>MANDATORY Multi-Agent]
P1 -->|No| Q[Story: Complete<br/>PR Delivered]
R --> Q
%% Styling
classDef phase1 fill:#e1f5fe
classDef phase2 fill:#f3e5f5
classDef phase3 fill:#e8f5e8
classDef phase4 fill:#fff8e1
classDef phase5 fill:#f1f8e9
classDef phase6 fill:#fce4ec
classDef phase7 fill:#e3f2fd
classDef failure fill:#ffebee
classDef decision fill:#fff3e0
classDef parallel fill:#f0f4f8
class A1,B,E phase1
class F,G phase2
class H,H1,H2,H3,H4,H5,I,J,J2,K phase3
class L,M phase4
class N phase5
class O,P,P1,Q phase6
class R phase7
class A2,C2,D2,G2,J3,K2 failure
class A1,C,D,G,J2,K decision
class H1,H2,H3,H4,H5 parallel
```
inputs:
epic_number:
type: string
description: The epic number (e.g., "1", "2", "3")
required: true
story_number:
type: string
description: The story number within the epic (e.g., "1", "2", "3")
required: true
outputs:
story_file:
type: string
description: Path to the created and approved story file
format: "docs/stories/epic{epic_number}.story{story_number}.story.md"
story_status:
type: string
description: Final story status
expected: "Done"
implementation_status:
type: string
description: Implementation completion status
expected: "Complete"
steps:
- step: validate_epic
agent: po
action: execute-checklist
inputs:
- epic_number
checklist: po-master-checklist.md
notes: "REQUIRED: Use Task tool for execution - Validate epic business readiness and dependencies before story creation"
story_status_update: "N/A - No story exists yet"
- step: create_story
agent: sm
action: create-next-story
requires: validate_epic
inputs:
- epic_number
- story_number
notes: "REQUIRED: Use Task tool for execution - Create comprehensive story from epic context using existing bmad-core task"
story_status_update: "Draft"
- step: validate_story_draft
agent: sm
action: execute-checklist
requires: create_story
inputs:
- story_file
checklist: story-draft-checklist.md
notes: "REQUIRED: Use Task tool for execution - Validate story draft quality and completeness using bmad-core checklist"
checklist_completion_tracking: true
- step: po_approval
agent: po
action: approve-story-for-development
requires: validate_story_draft
inputs:
- story_file
- epic_number
notes: "REQUIRED: Use Task tool for execution - Product Owner validates business value and approves for development"
story_status_update: "Approved"
- step: environment_setup
agent: infra-devops-platform
action: setup-development-environment
requires: po_approval
inputs:
- story_file
notes: "REQUIRED: Use Task tool for execution - Ensure development environment ready for story implementation"
- step: implement_story
agent: dev
action: implement-story-development
requires: environment_setup
inputs:
- story_file
- epic_number
- story_number
notes: "REQUIRED: Use Task tool for execution - Complete story implementation with validation (includes project quality gates)"
story_status_update: "In Progress"
- step: pre_review_validation
agent: dev
action: execute-checklist
requires: implement_story
inputs:
- story_file
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Final validation before reviews - ensures project quality gates pass"
story_status_update: "Review"
checklist_completion_tracking: true
- step: round1_architecture_review
agent: architect
action: execute-checklist
requires: pre_review_validation
inputs:
- story_file
outputs:
- arch_review_shard # Direct to shard: epic{N}.story{N}.arch-review.md
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Round 1 - Architect validates technical design and architecture. Write results directly to architecture review shard for parallel processing."
checklist_completion_tracking: true
- step: round1_business_review
agent: po
action: execute-checklist
requires: pre_review_validation
inputs:
- story_file
outputs:
- biz_review_shard # Direct to shard: epic{N}.story{N}.biz-review.md
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Round 1 - Product Owner validates business alignment and value. Write results directly to business review shard for parallel processing."
checklist_completion_tracking: true
- step: round1_process_review
agent: sm
action: execute-checklist
requires: pre_review_validation
inputs:
- story_file
outputs:
- proc_review_shard # Direct to shard: epic{N}.story{N}.proc-review.md
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Round 1 - Scrum Master validates process compliance and DoD. Write results directly to process review shard for parallel processing."
checklist_completion_tracking: true
- step: round1_qa_review
agent: qa
action: execute-checklist
requires: pre_review_validation
inputs:
- story_file
outputs:
- qa_review_shard # Direct to shard: epic{N}.story{N}.qa-review.md
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Round 1 - QA validates implementation quality and completeness. Write results directly to QA review shard for parallel processing."
checklist_completion_tracking: true
- step: round1_ux_review
agent: ux-expert
action: execute-checklist
requires: pre_review_validation
inputs:
- story_file
outputs:
- ux_review_shard # Direct to shard: epic{N}.story{N}.ux-review.md
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Round 1 - UX Expert validates user experience and accessibility. Write results directly to UX review shard for parallel processing."
checklist_completion_tracking: true
- step: consolidate_feedback
agent: sm
action: consolidate-review-feedback
requires: [round1_architecture_review, round1_business_review, round1_process_review, round1_qa_review, round1_ux_review]
inputs:
- story_file # Main story context
- arch_review_shard # From architect review
- biz_review_shard # From PO review
- proc_review_shard # From SM review
- qa_review_shard # From QA review
- ux_review_shard # From UX review
outputs:
- consolidated_shard # Direct to shard: epic{N}.story{N}.consolidated.md
notes: "REQUIRED: Use Task tool for execution - Scrum Master consolidates all review feedback from individual review shards with REQUIRED-FOR-COMPLETION/QUALITY-STANDARD/IMPROVEMENT/SCOPE-CREEP classification. Compare ALL feedback against original acceptance criteria to identify scope creep. Write consolidated results to dedicated shard."
- step: implement_fixes
agent: dev
action: implement-consolidated-fixes
requires: consolidate_feedback
inputs:
- story_file # Main story context
- consolidated_shard # From consolidation step
outputs:
- implementation_shard # Direct to shard: epic{N}.story{N}.implementation.md
notes: "REQUIRED: Use Task tool for execution - Dev implements consolidated fixes from consolidated feedback shard and documents results in implementation fixes shard. Read consolidated feedback from dedicated shard."
- step: verify_quality_gates
agent: dev
action: execute-checklist
requires: implement_fixes
inputs:
- story_file
checklist: story-dod-checklist.md
notes: "REQUIRED: Use Task tool for execution - Dev verifies all quality gates pass before SM validation"
checklist_completion_tracking: true
- step: validate_fixes
agent: sm
action: validate-consolidated-fixes
requires: verify_quality_gates
inputs:
- story_file # Main story context
- consolidated_shard # Original feedback from SM consolidation
- implementation_shard # Implemented fixes
outputs:
- validation_shard # Direct to shard: epic{N}.story{N}.validation.md
notes: "REQUIRED: Use Task tool for execution - SM validates that implemented fixes address consolidated feedback priorities and classification. Process compliance validation, not technical deep-dive."
story_status_update: "Implementation Validated"
- step: capture_learning_triage
agent: sm
action: capture-learning-triage
requires: validate_fixes
inputs:
- story_file # Main story context
- consolidated_shard # Original consolidated feedback
- implementation_shard # Implementation details
- validation_shard # SM validation results
outputs:
- learning_shard # Direct to shard: epic{N}.story{N}.learning.md
notes: "REQUIRED: Use Task tool for execution - SM extracts learnings from entire story implementation process with neutral perspective across all domains. Triage into structured categories with priorities."
story_status_update: "Learning Extracted"
- step: party_mode_review
agent: sm
action: party-mode-learning-review
requires: capture_learning_triage
inputs:
- story_file # Main story context
- learning_shard # Learning items from SM triage
outputs:
- review_shard # Direct to shard: epic{N}.story{N}.review.md
collaborators: [architect, po, dev]
notes: "REQUIRED: Use Task tool for execution - SM-facilitated collaborative team review of learning items with neutral facilitation. Architect provides key technical input. Build consensus on learning priorities and categorization."
story_status_update: "Learning Reviewed"
- step: commit_and_prepare_pr
agent: dev
action: commit-and-prepare-pr
requires: party_mode_review
inputs:
- story_file # Main story context
- review_shard # Learning review results
- implementation_shard # Implementation changes
outputs:
- pr_context_shard # Direct to shard: epic{N}.story{N}.pr-context.md
notes: "REQUIRED: Use Task tool for execution - Commit implementation and create PR context shard with comprehensive context. Read from dedicated shards for complete context."
story_status_update: "Changes Committed"
- step: create_comprehensive_pr
agent: po
action: create-comprehensive-pr
requires: commit_and_prepare_pr
inputs:
- story_file # Main story context
- pr_context_shard # PR context from commit step
- review_shard # Learning insights
outputs:
- pr_info_shard # Direct to shard: epic{N}.story{N}.pr-info.md
notes: "REQUIRED: Use Task tool for execution - Create PR from PR context shard with business summary, technical changes, and learning extraction. Write PR details to dedicated shard."
story_status_update: "PR Created"
- step: update_epic_progress
agent: sm
action: update-epic-progress
requires: create_comprehensive_pr
inputs:
- story_file # Main story context with epic number
- pr_info_shard # PR details
- review_shard # Learning items for integration
outputs:
- epic_file # Updated with story progress
notes: "REQUIRED: Use Task tool for execution - Update epic progress tracking from story and dedicated shards. Schedule learning integration from learning review shard."
story_status_update: "Done - Delivered"
- step: epic_retrospective
agent: sm
action: epic-party-mode-retrospective
requires: update_epic_progress
inputs:
- epic_number
- epic_completion_status
- all_story_files
- consolidated_learning_items
- epic_metrics
condition: epic_completion_status == "100%"
collaborators: [architect, po, dev, ux-expert]
notes: "REQUIRED: Use Task tool for execution - MANDATORY: Epic retrospective triggered automatically when epic reaches 100% completion"
story_status_update: "Epic Complete - Retrospective Done"
success_criteria:
- Epic readiness validated and approved for story creation
- Epic validated and story created following template standards
- Story draft quality validated by Scrum Master
- Business value validated and approved by Product Owner
- Technical environment ready for development
- Story implementation completed with all validations passing
- Pre-review validation confirms project quality gates pass
- Round 1 comprehensive reviews completed (architecture, business, process, QA, UX)
- Review feedback consolidated with REQUIRED-FOR-COMPLETION/QUALITY-STANDARD/IMPROVEMENT classification
- Consolidated fixes implemented and documented in story
- Quality gates verification confirms all technical validation passes
- Architect validates all fixes using story documentation and testing
- Learning extraction completed with structured triage and team review
- Implementation committed with comprehensive context
- PR created with business summary, technical changes, and learning insights
- Epic progress updated with story completion and learning integration
- MANDATORY: Epic retrospective executed when epic reaches 100% completion
- Epic-level strategic insights and patterns identified through multi-agent collaboration
- Next epic preparation actions defined with clear ownership
- Story status updated to "Done - Delivered" ("Epic Complete - Retrospective Done" if epic complete)
failure_handling:
- halt_on_failure: true
- Each step must complete successfully before proceeding
- Failed steps should be retried after addressing issues
retry_protocols:
epic_validation_failure:
- Issue: "Epic not ready for story creation (missing approval, dependencies, context)"
- Action: "PO addresses epic readiness issues (approval, dependencies, business context)"
- Retry: "Re-run validate_epic after epic issues resolved"
- Max_retries: 3
sm_validation_failure:
- Issue: "Story draft quality fails validation"
- Action: "SM revises story based on checklist feedback"
- Retry: "Re-run validate_story_draft after corrections"
- Max_retries: 3
po_approval_failure:
- Issue: "Business value or approval fails"
- Action: "PO clarifies requirements or updates story"
- Retry: "Re-run po_approval after business clarification"
- Max_retries: 3
pre_review_failure:
- Issue: "Project quality gates fail or DoD checklist incomplete"
- Action: "Dev fixes technical issues and quality problems"
- Retry: "Re-run pre_review_validation after fixes"
- Max_retries: 5
round1_reviews_failure:
- Issue: "Any Round 1 review fails (architecture, business, QA, UX)"
- Action: "Proceed to consolidation - Architect will classify as MVP-BLOCKING or not"
- Retry: "No retry at individual review level"
- Notes: "All feedback flows to consolidation regardless of pass/fail"
consolidation_failure:
- Issue: "Feedback consolidation fails or is incomplete"
- Action: "Architect re-analyzes review feedback and creates clear action plan"
- Retry: "Re-run consolidate_feedback after analysis"
- Max_retries: 2
quality_gates_failure:
- Issue: "Quality gates fail after implementing fixes"
- Action: "Dev fixes technical issues (tests, linting, etc.)"
- Retry: "Re-run implement_fixes → verify_quality_gates cycle"
- Max_retries: 3
- Notes: "Must pass all project quality gates before architect review"
fixes_validation_failure:
- Issue: "Architect finds fixes incomplete or incorrect"
- Action: "Dev implements additional fixes based on specific feedback"
- Retry: "Re-run implement_fixes → verify_quality_gates → validate_fixes cycle"
- Max_retries: 3
- Notes: "Each retry includes quality gate verification + browser MCP validation"
learning_triage_failure:
- Issue: "Learning extraction incomplete or poorly categorized"
- Action: "Architect re-analyzes implementation context and feedback patterns"
- Retry: "Re-run capture_learning_triage with improved analysis"
- Max_retries: 2
- Notes: "Focus on actionable learning items with clear ownership"
learning_review_failure:
- Issue: "Team consensus not achieved on learning priorities"
- Action: "SM facilitates additional discussion and conflict resolution"
- Retry: "Re-run party_mode_review with refined facilitation"
- Max_retries: 2
- Notes: "Use voting protocol and time-boxing to achieve consensus"
commit_preparation_failure:
- Issue: "Commit fails or PR context incomplete"
- Action: "Dev addresses git issues and completes context preparation"
- Retry: "Re-run commit_and_prepare_pr after resolving issues"
- Max_retries: 3
- Notes: "Ensure all quality gates pass before commit"
pr_creation_failure:
- Issue: "PR creation fails or context incomplete"
- Action: "PO addresses GitHub/PR platform issues and completes description"
- Retry: "Re-run create_comprehensive_pr after resolving platform issues"
- Max_retries: 3
- Notes: "Ensure comprehensive business and technical context"
epic_progress_failure:
- Issue: "Epic progress update fails or tracking incomplete"
- Action: "SM addresses epic file issues and completes progress tracking"
- Retry: "Re-run update_epic_progress after resolving tracking issues"
- Max_retries: 2
- Notes: "Ensure learning integration and next story readiness assessment"
dependencies:
core_bmad_agents:
- sm (Scrum Master)
- po (Product Owner)
- infra-devops-platform (DevOps Infrastructure)
- dev (Developer)
- architect (Technical Architect)
- qa (Quality Assurance)
- ux-expert (UX Expert)
core_bmad_tasks:
- create-next-story
- execute-checklist
- implement-story-development
core_bmad_checklists:
- story-draft-checklist.md
- architect-checklist.md
- po-master-checklist.md
- story-dod-checklist.md
expansion_tasks:
- approve-story-for-development
- setup-development-environment
- consolidate-review-feedback
- implement-consolidated-fixes
- validate-consolidated-fixes
- capture-learning-triage
- party-mode-learning-review
- commit-and-prepare-pr
- create-comprehensive-pr
- update-epic-progress
- epic-party-mode-retrospective
expansion_checklists: []
handoff_prompts:
po_validate_epic: "Validate epic {epic_number} readiness for story creation - check approval status, dependencies, and business context"
sm_create_story: "Create story {epic_number}.{story_number} using epic context and bmad-core story template"
sm_validate_draft: "Validate story draft quality using story-draft-checklist before PO review"
po_approval: "Validate business value and approve story {epic_number}.{story_number} for development"
infra_setup: "Story approved. Setup and validate development environment for implementation"
dev_implement: "Environment ready. Implement story {epic_number}.{story_number} with validation (project quality gates required)"
pre_review: "Implementation complete. Run final validation before reviews - ensure project quality gates pass"
round1_reviews: "Pre-review passed. Conduct comprehensive Round 1 reviews (architecture, business, process, QA, UX)"
consolidate: "Round 1 reviews complete. Consolidate all feedback with REQUIRED-FOR-COMPLETION/QUALITY-STANDARD/IMPROVEMENT classification"
implement_fixes: "Feedback consolidated. Implement fixes and document changes in story"
verify_gates: "Fixes implemented. Verify all quality gates pass before SM validation"
validate_fixes: "Quality gates passed. SM validates that fixes address consolidated feedback priorities and completion criteria"
capture_learning: "Implementation validated. SM extracts learnings from entire story process with neutral perspective across all domains"
party_review: "Learning triage complete. SM facilitates collaborative team review with architect providing key technical input to achieve consensus"
commit_prepare: "Learning review complete. Commit implementation changes and prepare comprehensive PR context"
create_pr: "Implementation committed. Create PR with business summary, technical changes, and learning extraction"
update_epic: "PR created. Update epic progress tracking and schedule learning integration. Checking epic completion status for MANDATORY epic retrospective."
epic_retrospective: "Epic {epic_number} complete (100%). SM MUST facilitate multi-agent retrospective for strategic process insights and next epic preparation. This is MANDATORY and integral to the process."
workflow_complete: "Story {epic_number}.{story_number} delivered. Epic retrospective status: {COMPLETED/NOT_TRIGGERED} based on epic completion (100% triggers MANDATORY retrospective)."