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
113
bmad/bmm/workflows/1-analysis/brainstorm-project/README.md
Normal file
113
bmad/bmm/workflows/1-analysis/brainstorm-project/README.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Project Brainstorming Workflow
|
||||
|
||||
Structured ideation for software projects exploring problem spaces, architectures, and innovative solutions beyond traditional requirements gathering.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Purpose](#purpose)
|
||||
- [Usage](#usage)
|
||||
- [Process](#process)
|
||||
- [Inputs & Outputs](#inputs--outputs)
|
||||
- [Integration](#integration)
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate multiple solution approaches for software projects through:
|
||||
|
||||
- Parallel ideation tracks (architecture, UX, integration, value delivery)
|
||||
- Technical-business alignment from inception
|
||||
- Hidden assumption discovery
|
||||
- Innovation beyond obvious solutions
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Run brainstorming session
|
||||
bmad bmm *brainstorm-project
|
||||
|
||||
# Or via Analyst agent
|
||||
*brainstorm-project
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Context Capture
|
||||
|
||||
- Business objectives and constraints
|
||||
- Technical environment
|
||||
- Stakeholder needs
|
||||
- Success criteria
|
||||
|
||||
### 2. Parallel Ideation
|
||||
|
||||
- **Architecture Track**: Technical approaches with trade-offs
|
||||
- **UX Track**: Interface paradigms and user journeys
|
||||
- **Integration Track**: System connection patterns
|
||||
- **Value Track**: Feature prioritization and delivery
|
||||
|
||||
### 3. Solution Synthesis
|
||||
|
||||
- Evaluate feasibility and impact
|
||||
- Align with strategic objectives
|
||||
- Surface hidden assumptions
|
||||
- Generate recommendations
|
||||
|
||||
## Inputs & Outputs
|
||||
|
||||
### Inputs
|
||||
|
||||
| Input | Type | Purpose |
|
||||
| ----------------- | -------- | --------------------------------------------- |
|
||||
| Project Context | Document | Business objectives, environment, constraints |
|
||||
| Problem Statement | Optional | Core challenge or opportunity |
|
||||
|
||||
### Outputs
|
||||
|
||||
| Output | Content |
|
||||
| ------------------------ | ------------------------------------------- |
|
||||
| Architecture Proposals | Multiple approaches with trade-off analysis |
|
||||
| Value Framework | Prioritized features aligned to objectives |
|
||||
| Risk Analysis | Dependencies, challenges, opportunities |
|
||||
| Strategic Recommendation | Synthesized direction with rationale |
|
||||
|
||||
## Integration
|
||||
|
||||
### Workflow Chain
|
||||
|
||||
1. **brainstorm-project** ← Current step
|
||||
2. research (optional deep dive)
|
||||
3. product-brief (strategic document)
|
||||
4. Phase 2 planning (PRD/tech-spec)
|
||||
|
||||
### Feed Into
|
||||
|
||||
- Product Brief development
|
||||
- Architecture decisions
|
||||
- PRD requirements
|
||||
- Epic prioritization
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Prepare context** - Gather business and technical background
|
||||
2. **Think broadly** - Explore non-obvious approaches
|
||||
3. **Document assumptions** - Capture implicit beliefs
|
||||
4. **Consider constraints** - Technical, organizational, resource
|
||||
5. **Focus on value** - Align to business objectives
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# bmad/bmm/config.yaml
|
||||
output_folder: ./output
|
||||
project_name: Your Project
|
||||
```
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- [Research](../research/README.md) - Deep investigation
|
||||
- [Product Brief](../product-brief/README.md) - Strategic planning
|
||||
- [PRD](../../2-plan-workflows/prd/README.md) - Requirements document
|
||||
|
||||
---
|
||||
|
||||
Part of BMad Method v6 - Phase 1 Analysis workflows
|
||||
110
bmad/bmm/workflows/1-analysis/brainstorm-project/instructions.md
Normal file
110
bmad/bmm/workflows/1-analysis/brainstorm-project/instructions.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Brainstorm Project - Workflow Instructions
|
||||
|
||||
```xml
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
<critical>This is a meta-workflow that orchestrates the CIS brainstorming workflow with project-specific context</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Brainstorming is optional - you can continue without status tracking.</output>
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "brainstorm-project" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="brainstorm-project status is file path (already completed)">
|
||||
<output>⚠️ Brainstorming session already completed: {{brainstorm-project status}}</output>
|
||||
<ask>Re-running will create a new session. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="brainstorm-project is not the next expected workflow (anything after brainstorm-project is completed already)">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Brainstorming is out of sequence.</output>
|
||||
<ask>Continue with brainstorming anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Load project brainstorming context">
|
||||
<action>Read the project context document from: {project_context}</action>
|
||||
<action>This context provides project-specific guidance including:
|
||||
- Focus areas for project ideation
|
||||
- Key considerations for software/product projects
|
||||
- Recommended techniques for project brainstorming
|
||||
- Output structure guidance
|
||||
</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Invoke core brainstorming with project context">
|
||||
<action>Execute the CIS brainstorming workflow with project context</action>
|
||||
<invoke-workflow path="{core_brainstorming}" data="{project_context}">
|
||||
The CIS brainstorming workflow will:
|
||||
- Present interactive brainstorming techniques menu
|
||||
- Guide the user through selected ideation methods
|
||||
- Generate and capture brainstorming session results
|
||||
- Save output to: {output_folder}/brainstorming-session-results-{{date}}.md
|
||||
</invoke-workflow>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Update status and complete" tag="workflow-status">
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "brainstorm-project"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["brainstorm-project"] = "{output_folder}/bmm-brainstorming-session-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Brainstorming Session Complete, {user_name}!**
|
||||
|
||||
**Session Results:**
|
||||
|
||||
- Brainstorming results saved to: {output_folder}/bmm-brainstorming-session-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
- **Next required:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** You can run other analysis workflows (research, product-brief) before proceeding
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
**Next Steps:**
|
||||
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
# Project Brainstorming Context
|
||||
|
||||
This context guide provides project-specific considerations for brainstorming sessions focused on software and product development.
|
||||
|
||||
## Session Focus Areas
|
||||
|
||||
When brainstorming for projects, consider exploring:
|
||||
|
||||
- **User Problems and Pain Points** - What challenges do users face?
|
||||
- **Feature Ideas and Capabilities** - What could the product do?
|
||||
- **Technical Approaches** - How might we build it?
|
||||
- **User Experience** - How will users interact with it?
|
||||
- **Business Model and Value** - How does it create value?
|
||||
- **Market Differentiation** - What makes it unique?
|
||||
- **Technical Risks and Challenges** - What could go wrong?
|
||||
- **Success Metrics** - How will we measure success?
|
||||
|
||||
## Integration with Project Workflow
|
||||
|
||||
Brainstorming sessions typically feed into:
|
||||
|
||||
- **Product Briefs** - Initial product vision and strategy
|
||||
- **PRDs** - Detailed requirements documents
|
||||
- **Technical Specifications** - Architecture and implementation plans
|
||||
- **Research Activities** - Areas requiring further investigation
|
||||
@@ -0,0 +1,26 @@
|
||||
# Brainstorm Project Workflow Configuration
|
||||
name: "brainstorm-project"
|
||||
description: "Facilitate project brainstorming sessions by orchestrating the CIS brainstorming workflow with project-specific context and guidance."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/brainstorm-project"
|
||||
template: false
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
|
||||
# Context document for project brainstorming
|
||||
project_context: "{installed_path}/project-context.md"
|
||||
|
||||
# CORE brainstorming workflow to invoke
|
||||
core_brainstorming: "{project-root}/bmad/core/workflows/brainstorming/workflow.yaml"
|
||||
|
||||
standalone: true
|
||||
423
bmad/bmm/workflows/1-analysis/domain-research/instructions.md
Normal file
423
bmad/bmm/workflows/1-analysis/domain-research/instructions.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# Domain Research - Collaborative Domain Exploration
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This is COLLABORATIVE RESEARCH - engage the user as a partner, not just a data source</critical>
|
||||
<critical>The goal is PRACTICAL UNDERSTANDING that directly informs requirements and architecture</critical>
|
||||
<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>LIVING DOCUMENT: Write to domain-brief.md continuously as you discover - never wait until the end</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Set research context">
|
||||
<action>Welcome {user_name} to collaborative domain research
|
||||
|
||||
Check for context:
|
||||
|
||||
- Was this triggered from PRD workflow?
|
||||
- Is there a workflow-status.yaml with project context?
|
||||
- Did user provide initial domain/project description?
|
||||
|
||||
If context exists, reflect it back:
|
||||
"I understand you're building [description]. Let's explore the [domain] aspects together to ensure we capture all critical requirements."
|
||||
|
||||
If no context:
|
||||
"Let's explore your project's domain together. Tell me about what you're building and what makes it unique or complex."</action>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Domain detection and scoping">
|
||||
<action>Through conversation, identify the domain and its complexity
|
||||
|
||||
Listen for domain signals and explore:
|
||||
|
||||
- "Is this in a regulated industry?"
|
||||
- "Are there safety or compliance concerns?"
|
||||
- "What could go wrong if this fails?"
|
||||
- "Who are the stakeholders beyond direct users?"
|
||||
- "Are there industry standards we need to follow?"
|
||||
|
||||
Based on responses, identify primary domain(s):
|
||||
|
||||
- Healthcare/Medical
|
||||
- Financial Services
|
||||
- Government/Public Sector
|
||||
- Education
|
||||
- Aerospace/Defense
|
||||
- Automotive
|
||||
- Energy/Utilities
|
||||
- Legal
|
||||
- Insurance
|
||||
- Scientific/Research
|
||||
- Other specialized domain
|
||||
|
||||
Share your understanding:
|
||||
"Based on our discussion, this appears to be a [domain] project with [key characteristics]. The main areas we should research are:
|
||||
|
||||
- [Area 1]
|
||||
- [Area 2]
|
||||
- [Area 3]
|
||||
|
||||
What concerns you most about building in this space?"</action>
|
||||
|
||||
<template-output>domain_overview</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Collaborative concern mapping">
|
||||
<action>Work WITH the user to identify critical concerns
|
||||
|
||||
"Let's map out the important considerations together. I'll share what I typically see in [domain], and you tell me what applies to your case."
|
||||
|
||||
For detected domain, explore relevant areas:
|
||||
|
||||
HEALTHCARE:
|
||||
"In healthcare software, teams often worry about:
|
||||
|
||||
- FDA approval pathways (510k, De Novo, PMA)
|
||||
- HIPAA compliance for patient data
|
||||
- Clinical validation requirements
|
||||
- Integration with hospital systems (HL7, FHIR, DICOM)
|
||||
- Patient safety and liability
|
||||
|
||||
Which of these apply to you? What else concerns you?"
|
||||
|
||||
FINTECH:
|
||||
"Financial software typically deals with:
|
||||
|
||||
- KYC/AML requirements
|
||||
- Payment processing regulations (PCI DSS)
|
||||
- Regional compliance (US, EU, specific countries?)
|
||||
- Fraud prevention
|
||||
- Audit trails and reporting
|
||||
|
||||
What's your situation with these? Any specific regions?"
|
||||
|
||||
AEROSPACE:
|
||||
"Aerospace software often requires:
|
||||
|
||||
- DO-178C certification levels
|
||||
- Safety analysis (FMEA, FTA)
|
||||
- Simulation validation
|
||||
- Real-time performance guarantees
|
||||
- Export control (ITAR)
|
||||
|
||||
Which are relevant for your project?"
|
||||
|
||||
[Continue for other domains...]
|
||||
|
||||
Document concerns as the user shares them
|
||||
Ask follow-up questions to understand depth:
|
||||
|
||||
- "How critical is this requirement?"
|
||||
- "Is this a must-have for launch or can it come later?"
|
||||
- "Do you have expertise here or need guidance?"</action>
|
||||
|
||||
<template-output>concern_mapping</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Research key requirements together">
|
||||
<action>Conduct research WITH the user watching and contributing
|
||||
|
||||
"Let me research the current requirements for [specific concern]. You can guide me toward what's most relevant."
|
||||
|
||||
<WebSearch>{specific_requirement} requirements {date}</WebSearch>
|
||||
|
||||
Share findings immediately:
|
||||
"Here's what I found about [requirement]:
|
||||
|
||||
- [Key point 1]
|
||||
- [Key point 2]
|
||||
- [Key point 3]
|
||||
|
||||
Does this match your understanding? Anything surprising or concerning?"
|
||||
|
||||
For each major concern:
|
||||
|
||||
1. Research current standards/regulations
|
||||
2. Share findings with user
|
||||
3. Get their interpretation
|
||||
4. Note practical implications
|
||||
|
||||
If user has expertise:
|
||||
"You seem knowledgeable about [area]. What should I know that might not be in public documentation?"
|
||||
|
||||
If user is learning:
|
||||
"This might be new territory. Let me explain what this means practically for your development..."</action>
|
||||
|
||||
<template-output>regulatory_requirements</template-output>
|
||||
<template-output>industry_standards</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Identify practical implications">
|
||||
<action>Translate research into practical development impacts
|
||||
|
||||
"Based on what we've learned, here's what this means for your project:
|
||||
|
||||
ARCHITECTURE IMPLICATIONS:
|
||||
|
||||
- [How this affects system design]
|
||||
- [Required components or patterns]
|
||||
- [Performance or security needs]
|
||||
|
||||
DEVELOPMENT IMPLICATIONS:
|
||||
|
||||
- [Additional development effort]
|
||||
- [Special expertise needed]
|
||||
- [Testing requirements]
|
||||
|
||||
TIMELINE IMPLICATIONS:
|
||||
|
||||
- [Certification/approval timelines]
|
||||
- [Validation requirements]
|
||||
- [Documentation needs]
|
||||
|
||||
COST IMPLICATIONS:
|
||||
|
||||
- [Compliance costs]
|
||||
- [Required tools or services]
|
||||
- [Ongoing maintenance]
|
||||
|
||||
Does this align with your expectations? Any surprises we should dig into?"</action>
|
||||
|
||||
<template-output>practical_implications</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Discover domain-specific patterns">
|
||||
<action>Explore how others solve similar problems
|
||||
|
||||
"Let's look at how successful [domain] products handle these challenges."
|
||||
|
||||
<WebSearch>best {domain} software architecture patterns {date}</WebSearch>
|
||||
<WebSearch>{domain} software case studies {date}</WebSearch>
|
||||
|
||||
Discuss patterns:
|
||||
"I found these common approaches in [domain]:
|
||||
|
||||
Pattern 1: [Description]
|
||||
|
||||
- Pros: [Benefits]
|
||||
- Cons: [Tradeoffs]
|
||||
- When to use: [Conditions]
|
||||
|
||||
Pattern 2: [Description]
|
||||
|
||||
- Pros: [Benefits]
|
||||
- Cons: [Tradeoffs]
|
||||
- When to use: [Conditions]
|
||||
|
||||
Which resonates with your vision? Or are you thinking something different?"
|
||||
|
||||
If user proposes novel approach:
|
||||
"That's interesting and different from the standard patterns. Let's explore:
|
||||
|
||||
- What makes your approach unique?
|
||||
- What problem does it solve that existing patterns don't?
|
||||
- What are the risks?
|
||||
- How do we validate it?"</action>
|
||||
|
||||
<template-output>domain_patterns</template-output>
|
||||
<template-output if="novel approach">innovation_notes</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Risk assessment and mitigation">
|
||||
<action>Collaboratively identify and address risks
|
||||
|
||||
"Every [domain] project has risks. Let's think through yours:
|
||||
|
||||
REGULATORY RISKS:
|
||||
|
||||
- What if regulations change during development?
|
||||
- What if approval/certification takes longer?
|
||||
- What if we misinterpret requirements?
|
||||
|
||||
TECHNICAL RISKS:
|
||||
|
||||
- What if the domain requirements conflict with user experience?
|
||||
- What if performance requirements are harder than expected?
|
||||
- What if integrations are more complex?
|
||||
|
||||
MARKET RISKS:
|
||||
|
||||
- What if competitors move faster?
|
||||
- What if domain experts are hard to find?
|
||||
- What if users resist domain-mandated workflows?
|
||||
|
||||
For each risk you're concerned about, let's identify:
|
||||
|
||||
1. How likely is it?
|
||||
2. What's the impact if it happens?
|
||||
3. How can we mitigate it?
|
||||
4. What's our plan B?"</action>
|
||||
|
||||
<template-output>risk_assessment</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Create validation strategy">
|
||||
<action>Plan how to ensure domain requirements are met
|
||||
|
||||
"Let's plan how to validate that we're meeting [domain] requirements:
|
||||
|
||||
COMPLIANCE VALIDATION:
|
||||
|
||||
- How do we verify regulatory compliance?
|
||||
- Who needs to review/approve?
|
||||
- What documentation is required?
|
||||
|
||||
TECHNICAL VALIDATION:
|
||||
|
||||
- How do we prove the system works correctly?
|
||||
- What metrics matter?
|
||||
- What testing is required?
|
||||
|
||||
DOMAIN EXPERT VALIDATION:
|
||||
|
||||
- Who are the domain experts to involve?
|
||||
- When should they review?
|
||||
- What are their success criteria?
|
||||
|
||||
USER VALIDATION:
|
||||
|
||||
- How do we ensure it's still usable despite constraints?
|
||||
- What user testing is needed?
|
||||
- How do we balance domain requirements with UX?
|
||||
|
||||
What validation is most critical for your confidence?"</action>
|
||||
|
||||
<template-output>validation_strategy</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Document decision points">
|
||||
<action>Capture key decisions and rationale
|
||||
|
||||
"Let's document the important decisions we've made:
|
||||
|
||||
DOMAIN APPROACH:
|
||||
|
||||
- We're choosing [approach] because [rationale]
|
||||
- We're prioritizing [requirement] over [requirement] because [reason]
|
||||
- We're deferring [requirement] to Phase 2 because [justification]
|
||||
|
||||
COMPLIANCE STRATEGY:
|
||||
|
||||
- We'll pursue [pathway] for regulatory approval
|
||||
- We'll implement [standard] for industry compliance
|
||||
- We'll handle [requirement] by [approach]
|
||||
|
||||
RISK DECISIONS:
|
||||
|
||||
- We accept [risk] because [reason]
|
||||
- We'll mitigate [risk] through [approach]
|
||||
- We'll monitor [risk] by [method]
|
||||
|
||||
Any decisions you want to revisit or rationale to add?"</action>
|
||||
|
||||
<template-output>key_decisions</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Create actionable recommendations">
|
||||
<action>Synthesize research into specific recommendations
|
||||
|
||||
"Based on our research, here are my recommendations for your PRD and development:
|
||||
|
||||
MUST HAVE (Domain Critical):
|
||||
|
||||
1. [Specific requirement with why it's critical]
|
||||
2. [Specific requirement with why it's critical]
|
||||
3. [Specific requirement with why it's critical]
|
||||
|
||||
SHOULD HAVE (Domain Important):
|
||||
|
||||
1. [Requirement that's important but not blocking]
|
||||
2. [Requirement that's important but not blocking]
|
||||
|
||||
CONSIDER (Domain Nice-to-Have):
|
||||
|
||||
1. [Enhancement that would differentiate]
|
||||
2. [Enhancement that would differentiate]
|
||||
|
||||
DEVELOPMENT SEQUENCE:
|
||||
|
||||
1. First: [What to build first and why]
|
||||
2. Then: [What comes next and why]
|
||||
3. Later: [What can wait and why]
|
||||
|
||||
EXPERTISE NEEDED:
|
||||
|
||||
- [Domain expert role]: For [specific areas]
|
||||
- [Technical expert role]: For [specific requirements]
|
||||
|
||||
TIMELINE CONSIDERATIONS:
|
||||
|
||||
- Allow [time] for [process/approval]
|
||||
- Start [requirement] early because [reason]
|
||||
- [Requirement] can be parallel with development
|
||||
|
||||
Do these recommendations feel right? What would you adjust?"</action>
|
||||
|
||||
<template-output>recommendations</template-output>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Package for PRD integration">
|
||||
<action>Create clear handoff to PRD workflow
|
||||
|
||||
"I've captured everything in domain-brief.md. Here's the summary for your PRD:
|
||||
|
||||
DOMAIN: {identified_domain}
|
||||
COMPLEXITY: {high|medium}
|
||||
|
||||
KEY REQUIREMENTS TO INCORPORATE:
|
||||
|
||||
- [Requirement 1 - critical for domain]
|
||||
- [Requirement 2 - critical for domain]
|
||||
- [Requirement 3 - important consideration]
|
||||
|
||||
IMPACTS ON:
|
||||
|
||||
- Functional Requirements: [How domain affects features]
|
||||
- Non-Functional Requirements: [Performance, security, etc.]
|
||||
- Architecture: [System design considerations]
|
||||
- Development: [Process and timeline impacts]
|
||||
|
||||
REFERENCE DOCS:
|
||||
|
||||
- Full domain analysis: domain-brief.md
|
||||
- Regulations researched: [List with links]
|
||||
- Standards referenced: [List with links]
|
||||
|
||||
When you return to PRD, reference this brief for domain context.
|
||||
|
||||
Any final questions before we wrap up the domain research?"</action>
|
||||
|
||||
<template-output>summary_for_prd</template-output>
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Close with next steps">
|
||||
<output>**✅ Domain Research Complete, {user_name}!**
|
||||
|
||||
We've explored the {domain} aspects of your project together and documented critical requirements.
|
||||
|
||||
**Created:**
|
||||
|
||||
- **domain-brief.md** - Complete domain analysis with requirements and recommendations
|
||||
|
||||
**Key Findings:**
|
||||
|
||||
- Primary domain: {domain}
|
||||
- Complexity level: {complexity}
|
||||
- Critical requirements: {count} identified
|
||||
- Risks identified: {count} with mitigation strategies
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Return to PRD workflow with this domain context
|
||||
2. Domain requirements will shape your functional requirements
|
||||
3. Reference domain-brief.md for detailed requirements
|
||||
|
||||
**Remember:**
|
||||
{most_important_finding}
|
||||
|
||||
The domain research will ensure your PRD captures not just what to build, but HOW to build it correctly for {domain}.
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
180
bmad/bmm/workflows/1-analysis/domain-research/template.md
Normal file
180
bmad/bmm/workflows/1-analysis/domain-research/template.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Domain Brief - {project_name}
|
||||
|
||||
Generated: {date}
|
||||
Domain: {primary_domain}
|
||||
Complexity: {complexity_level}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{brief_overview_of_domain_research_findings}
|
||||
|
||||
## Domain Overview
|
||||
|
||||
### Industry Context
|
||||
|
||||
{domain_overview}
|
||||
|
||||
### Regulatory Landscape
|
||||
|
||||
{regulatory_environment}
|
||||
|
||||
### Key Stakeholders
|
||||
|
||||
{stakeholder_analysis}
|
||||
|
||||
## Critical Concerns
|
||||
|
||||
### Compliance Requirements
|
||||
|
||||
{concern_mapping}
|
||||
|
||||
### Technical Constraints
|
||||
|
||||
{technical_limitations_from_domain}
|
||||
|
||||
### Safety/Risk Considerations
|
||||
|
||||
{safety_risk_factors}
|
||||
|
||||
## Regulatory Requirements
|
||||
|
||||
{regulatory_requirements}
|
||||
|
||||
## Industry Standards
|
||||
|
||||
{industry_standards}
|
||||
|
||||
## Practical Implications
|
||||
|
||||
### Architecture Impact
|
||||
|
||||
{architecture_implications}
|
||||
|
||||
### Development Impact
|
||||
|
||||
{development_implications}
|
||||
|
||||
### Timeline Impact
|
||||
|
||||
{timeline_implications}
|
||||
|
||||
### Cost Impact
|
||||
|
||||
{cost_implications}
|
||||
|
||||
## Domain Patterns
|
||||
|
||||
### Established Patterns
|
||||
|
||||
{domain_patterns}
|
||||
|
||||
### Innovation Opportunities
|
||||
|
||||
{innovation_notes}
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Identified Risks
|
||||
|
||||
{risk_assessment}
|
||||
|
||||
### Mitigation Strategies
|
||||
|
||||
{mitigation_approaches}
|
||||
|
||||
## Validation Strategy
|
||||
|
||||
### Compliance Validation
|
||||
|
||||
{compliance_validation_approach}
|
||||
|
||||
### Technical Validation
|
||||
|
||||
{technical_validation_approach}
|
||||
|
||||
### Domain Expert Validation
|
||||
|
||||
{expert_validation_approach}
|
||||
|
||||
## Key Decisions
|
||||
|
||||
{key_decisions}
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Must Have (Critical)
|
||||
|
||||
{critical_requirements}
|
||||
|
||||
### Should Have (Important)
|
||||
|
||||
{important_requirements}
|
||||
|
||||
### Consider (Nice-to-Have)
|
||||
|
||||
{optional_enhancements}
|
||||
|
||||
### Development Sequence
|
||||
|
||||
{recommended_sequence}
|
||||
|
||||
### Required Expertise
|
||||
|
||||
{expertise_needed}
|
||||
|
||||
## PRD Integration Guide
|
||||
|
||||
### Summary for PRD
|
||||
|
||||
{summary_for_prd}
|
||||
|
||||
### Requirements to Incorporate
|
||||
|
||||
- {requirement_1}
|
||||
- {requirement_2}
|
||||
- {requirement_3}
|
||||
|
||||
### Architecture Considerations
|
||||
|
||||
- {architecture_consideration_1}
|
||||
- {architecture_consideration_2}
|
||||
|
||||
### Development Considerations
|
||||
|
||||
- {development_consideration_1}
|
||||
- {development_consideration_2}
|
||||
|
||||
## References
|
||||
|
||||
### Regulations Researched
|
||||
|
||||
- {regulation_1_with_link}
|
||||
- {regulation_2_with_link}
|
||||
|
||||
### Standards Referenced
|
||||
|
||||
- {standard_1_with_link}
|
||||
- {standard_2_with_link}
|
||||
|
||||
### Additional Resources
|
||||
|
||||
- {resource_1}
|
||||
- {resource_2}
|
||||
|
||||
## Appendix
|
||||
|
||||
### Research Notes
|
||||
|
||||
{detailed_research_notes}
|
||||
|
||||
### Conversation Highlights
|
||||
|
||||
{key_discussion_points_with_user}
|
||||
|
||||
### Open Questions
|
||||
|
||||
{questions_requiring_further_research}
|
||||
|
||||
---
|
||||
|
||||
_This domain brief was created through collaborative research between {user_name} and the AI facilitator. It should be referenced during PRD creation and updated as new domain insights emerge._
|
||||
36
bmad/bmm/workflows/1-analysis/domain-research/workflow.yaml
Normal file
36
bmad/bmm/workflows/1-analysis/domain-research/workflow.yaml
Normal file
@@ -0,0 +1,36 @@
|
||||
workflow:
|
||||
id: domain-research
|
||||
name: "Domain Research"
|
||||
module: bmm
|
||||
version: "6.0.0-alpha"
|
||||
description: "Collaborative exploration of domain-specific requirements, regulations, and patterns for complex projects"
|
||||
|
||||
environment:
|
||||
# Inherit from parent workflow or set defaults
|
||||
user_name: "partner"
|
||||
user_skill_level: "intermediate"
|
||||
communication_language: "English"
|
||||
document_output_language: "English"
|
||||
date: "{system.date}"
|
||||
|
||||
required_files:
|
||||
- instructions.md
|
||||
- template.md
|
||||
|
||||
optional_files:
|
||||
- domain-knowledge-base.md
|
||||
|
||||
outputs:
|
||||
- domain-brief.md
|
||||
|
||||
metadata:
|
||||
category: "analysis"
|
||||
complexity: "medium"
|
||||
estimated_time: "30-45 minutes"
|
||||
prerequisites:
|
||||
- "Basic project understanding"
|
||||
when_to_use:
|
||||
- "Complex regulated domains (healthcare, finance, aerospace)"
|
||||
- "Novel technical domains requiring deep understanding"
|
||||
- "Before PRD when domain expertise needed"
|
||||
- "When compliance and regulations matter"
|
||||
180
bmad/bmm/workflows/1-analysis/product-brief/README.md
Normal file
180
bmad/bmm/workflows/1-analysis/product-brief/README.md
Normal file
@@ -0,0 +1,180 @@
|
||||
# Product Brief Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration. Supports both structured interactive mode and rapid "YOLO" mode for quick draft generation.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Dual Mode Operation** - Interactive step-by-step or rapid draft generation
|
||||
- **Multi-Input Support** - Integrates market research, competitive analysis, and brainstorming results
|
||||
- **Conversational Design** - Guides users through strategic thinking with probing questions
|
||||
- **Executive Summary Generation** - Creates compelling summaries for stakeholder communication
|
||||
- **Comprehensive Coverage** - Addresses all critical product planning dimensions
|
||||
- **Stakeholder Ready** - Generates professional briefs suitable for PM handoff
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow product-brief
|
||||
```
|
||||
|
||||
### With Input Documents
|
||||
|
||||
```bash
|
||||
# With market research
|
||||
workflow product-brief --input market-research.md
|
||||
|
||||
# With multiple inputs
|
||||
workflow product-brief --input market-research.md --input competitive-analysis.md
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **brief_format**: "comprehensive" (full detail) or "executive" (3-page limit)
|
||||
- **autonomous**: false (requires user collaboration)
|
||||
- **output_folder**: Location for generated brief
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
product-brief/
|
||||
├── workflow.yaml # Configuration and metadata
|
||||
├── instructions.md # Interactive workflow steps
|
||||
├── template.md # Product brief document structure
|
||||
├── checklist.md # Validation criteria
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Initialization and Context (Steps 0-2)
|
||||
|
||||
- **Project Setup**: Captures project name and basic context
|
||||
- **Input Gathering**: Collects and analyzes available documents
|
||||
- **Mode Selection**: Chooses interactive or YOLO collaboration approach
|
||||
- **Context Extraction**: Identifies core problems and opportunities
|
||||
|
||||
### Phase 2: Interactive Development (Steps 3-12) - Interactive Mode
|
||||
|
||||
- **Problem Definition**: Deep dive into user pain points and market gaps
|
||||
- **Solution Articulation**: Develops clear value proposition and approach
|
||||
- **User Segmentation**: Defines primary and secondary target audiences
|
||||
- **Success Metrics**: Establishes measurable goals and KPIs
|
||||
- **MVP Scoping**: Ruthlessly defines minimum viable features
|
||||
- **Financial Planning**: Assesses ROI and strategic alignment
|
||||
- **Technical Context**: Captures platform and technology considerations
|
||||
- **Risk Assessment**: Identifies constraints, assumptions, and unknowns
|
||||
|
||||
### Phase 3: Rapid Generation (Steps 3-4) - YOLO Mode
|
||||
|
||||
- **Complete Draft**: Generates full brief based on initial context
|
||||
- **Iterative Refinement**: User-guided section improvements
|
||||
- **Quality Validation**: Ensures completeness and consistency
|
||||
|
||||
### Phase 4: Finalization (Steps 13-15)
|
||||
|
||||
- **Executive Summary**: Creates compelling overview for stakeholders
|
||||
- **Supporting Materials**: Compiles research summaries and references
|
||||
- **Final Review**: Quality check and handoff preparation
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: product-brief-{project_name}-{date}.md
|
||||
- **Supporting files**: Research summaries and stakeholder input documentation
|
||||
|
||||
### Output Structure
|
||||
|
||||
1. **Executive Summary** - High-level product concept and value proposition
|
||||
2. **Problem Statement** - Detailed problem analysis with evidence
|
||||
3. **Proposed Solution** - Core approach and key differentiators
|
||||
4. **Target Users** - Primary and secondary user segments with personas
|
||||
5. **Goals and Success Metrics** - Business objectives and measurable KPIs
|
||||
6. **MVP Scope** - Must-have features and out-of-scope items
|
||||
7. **Post-MVP Vision** - Phase 2 features and long-term roadmap
|
||||
8. **Financial Impact** - Investment requirements and ROI projections
|
||||
9. **Strategic Alignment** - Connection to company OKRs and initiatives
|
||||
10. **Technical Considerations** - Platform requirements and preferences
|
||||
11. **Constraints and Assumptions** - Resource limits and key assumptions
|
||||
12. **Risks and Open Questions** - Risk assessment and research needs
|
||||
13. **Supporting Materials** - Research summaries and references
|
||||
|
||||
## Requirements
|
||||
|
||||
No special requirements - designed to work with or without existing documentation.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Gather Available Research**: Collect any market research, competitive analysis, or user feedback
|
||||
2. **Define Stakeholder Audience**: Know who will use this brief for decision-making
|
||||
3. **Set Time Boundaries**: Interactive mode requires 60-90 minutes for quality results
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Be Specific**: Avoid generic statements - provide concrete examples and data
|
||||
2. **Think Strategically**: Focus on "why" and "what" rather than "how"
|
||||
3. **Challenge Assumptions**: Use the conversation to test and refine your thinking
|
||||
4. **Scope Ruthlessly**: Resist feature creep in MVP definition
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Validate with Checklist**: Use included criteria to ensure completeness
|
||||
2. **Stakeholder Review**: Share executive summary first, then full brief
|
||||
3. **Iterate Based on Feedback**: Product briefs should evolve with new insights
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Brief lacks specificity or contains vague statements
|
||||
|
||||
- **Solution**: Restart problem definition with concrete examples and measurable impacts
|
||||
- **Check**: Ensure each section answers "so what?" and provides actionable insights
|
||||
|
||||
**Issue**: MVP scope is too large or undefined
|
||||
|
||||
- **Solution**: Use the "what's the minimum to validate core hypothesis?" filter
|
||||
- **Check**: Verify that each MVP feature is truly essential for initial value delivery
|
||||
|
||||
**Issue**: Missing strategic context or business justification
|
||||
|
||||
- **Solution**: Return to financial impact and strategic alignment sections
|
||||
- **Check**: Ensure connection to company goals and clear ROI potential
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Questions**: Update instructions.md to add industry-specific or company-specific prompts
|
||||
2. **Adjust Template**: Customize template.md sections for organizational brief standards
|
||||
3. **Add Validation**: Extend checklist.md with company-specific quality criteria
|
||||
4. **Configure Modes**: Adjust brief_format settings for different output styles
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - Interactive conversational design with dual modes
|
||||
- Interactive and YOLO mode support
|
||||
- Multi-input document integration
|
||||
- Executive summary generation
|
||||
- Strategic alignment focus
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Consider running market research workflow first if lacking business context
|
||||
- Consult BMAD documentation for product planning methodology
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
115
bmad/bmm/workflows/1-analysis/product-brief/checklist.md
Normal file
115
bmad/bmm/workflows/1-analysis/product-brief/checklist.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# Product Brief Validation Checklist
|
||||
|
||||
## Document Structure
|
||||
|
||||
- [ ] All required sections are present (Executive Summary through Appendices)
|
||||
- [ ] No placeholder text remains (e.g., [TODO], [NEEDS CONFIRMATION], {{variable}})
|
||||
- [ ] Document follows the standard brief template format
|
||||
- [ ] Sections are properly numbered and formatted with headers
|
||||
- [ ] Cross-references between sections are accurate
|
||||
|
||||
## Executive Summary Quality
|
||||
|
||||
- [ ] Product concept is explained in 1-2 clear sentences
|
||||
- [ ] Primary problem is clearly identified
|
||||
- [ ] Target market is specifically named (not generic)
|
||||
- [ ] Value proposition is compelling and differentiated
|
||||
- [ ] Summary accurately reflects the full document content
|
||||
|
||||
## Problem Statement
|
||||
|
||||
- [ ] Current state pain points are specific and measurable
|
||||
- [ ] Impact is quantified where possible (time, money, opportunities)
|
||||
- [ ] Explanation of why existing solutions fall short is provided
|
||||
- [ ] Urgency for solving the problem now is justified
|
||||
- [ ] Problem is validated with evidence or data points
|
||||
|
||||
## Solution Definition
|
||||
|
||||
- [ ] Core approach is clearly explained without implementation details
|
||||
- [ ] Key differentiators from existing solutions are identified
|
||||
- [ ] Explanation of why this will succeed is compelling
|
||||
- [ ] Solution aligns directly with stated problems
|
||||
- [ ] Vision paints a clear picture of the user experience
|
||||
|
||||
## Target Users
|
||||
|
||||
- [ ] Primary user segment has specific demographic/firmographic profile
|
||||
- [ ] User behaviors and current workflows are documented
|
||||
- [ ] Specific pain points are tied to user segments
|
||||
- [ ] User goals are clearly articulated
|
||||
- [ ] Secondary segment (if applicable) is equally detailed
|
||||
- [ ] Avoids generic personas like "busy professionals"
|
||||
|
||||
## Goals and Metrics
|
||||
|
||||
- [ ] Business objectives include measurable outcomes with targets
|
||||
- [ ] User success metrics focus on behaviors, not features
|
||||
- [ ] 3-5 KPIs are defined with clear definitions
|
||||
- [ ] All goals follow SMART criteria (Specific, Measurable, Achievable, Relevant, Time-bound)
|
||||
- [ ] Success metrics align with problem statement
|
||||
|
||||
## MVP Scope
|
||||
|
||||
- [ ] Core features list contains only true must-haves
|
||||
- [ ] Each core feature includes rationale for why it's essential
|
||||
- [ ] Out of scope section explicitly lists deferred features
|
||||
- [ ] MVP success criteria are specific and measurable
|
||||
- [ ] Scope is genuinely minimal and viable
|
||||
- [ ] No feature creep evident in "must-have" list
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- [ ] Target platforms are specified (web/mobile/desktop)
|
||||
- [ ] Browser/OS support requirements are documented
|
||||
- [ ] Performance requirements are defined if applicable
|
||||
- [ ] Accessibility requirements are noted
|
||||
- [ ] Technology preferences are marked as preferences, not decisions
|
||||
- [ ] Integration requirements with existing systems are identified
|
||||
|
||||
## Constraints and Assumptions
|
||||
|
||||
- [ ] Budget constraints are documented if known
|
||||
- [ ] Timeline or deadline pressures are specified
|
||||
- [ ] Team/resource limitations are acknowledged
|
||||
- [ ] Technical constraints are clearly stated
|
||||
- [ ] Key assumptions are listed and testable
|
||||
- [ ] Assumptions will be validated during development
|
||||
|
||||
## Risk Assessment (if included)
|
||||
|
||||
- [ ] Key risks include potential impact descriptions
|
||||
- [ ] Open questions are specific and answerable
|
||||
- [ ] Research areas are identified with clear objectives
|
||||
- [ ] Risk mitigation strategies are suggested where applicable
|
||||
|
||||
## Overall Quality
|
||||
|
||||
- [ ] Language is clear and free of jargon
|
||||
- [ ] Terminology is used consistently throughout
|
||||
- [ ] Document is ready for handoff to Product Manager
|
||||
- [ ] All [PM-TODO] items are clearly marked if present
|
||||
- [ ] References and source documents are properly cited
|
||||
|
||||
## Completeness Check
|
||||
|
||||
- [ ] Document provides sufficient detail for PRD creation
|
||||
- [ ] All user inputs have been incorporated
|
||||
- [ ] Market research findings are reflected if provided
|
||||
- [ ] Competitive analysis insights are included if available
|
||||
- [ ] Brief aligns with overall product strategy
|
||||
|
||||
## Final Validation
|
||||
|
||||
### Critical Issues Found:
|
||||
|
||||
- [ ] None identified
|
||||
|
||||
### Minor Issues to Address:
|
||||
|
||||
- [ ] List any minor issues here
|
||||
|
||||
### Ready for PM Handoff:
|
||||
|
||||
- [ ] Yes, brief is complete and validated
|
||||
- [ ] No, requires additional work (specify above)
|
||||
524
bmad/bmm/workflows/1-analysis/product-brief/instructions.md
Normal file
524
bmad/bmm/workflows/1-analysis/product-brief/instructions.md
Normal file
@@ -0,0 +1,524 @@
|
||||
# Product Brief - Context-Adaptive Discovery Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses INTENT-DRIVEN FACILITATION - adapt organically to what emerges</critical>
|
||||
<critical>The goal is DISCOVERING WHAT MATTERS through natural conversation, not filling a template</critical>
|
||||
<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>LIVING DOCUMENT: Write to the document continuously as you discover - never wait until the end</critical>
|
||||
|
||||
## Input Document Discovery
|
||||
|
||||
This workflow may reference: market research, brainstorming documents, user specified other inputs, or brownfield project documentation.
|
||||
|
||||
**Discovery Process** (execute for each referenced document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<action if="status file not found">Set standalone_mode = true</action>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "product-brief" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="project_level < 2">
|
||||
<output>**Note: Level {{project_level}} Project**
|
||||
|
||||
Product Brief is most valuable for Level 2+ projects, but can help clarify vision for any project.</output>
|
||||
</check>
|
||||
|
||||
<check if="product-brief status is file path (already completed)">
|
||||
<output>⚠️ Product Brief already completed: {{product-brief status}}</output>
|
||||
<ask>Re-running will overwrite the existing brief. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="product-brief is not the next expected workflow">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Product Brief is out of sequence.</output>
|
||||
<ask>Continue with Product Brief anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Begin the journey and understand context">
|
||||
<action>Welcome {user_name} warmly in {communication_language}
|
||||
|
||||
Adapt your tone to {user_skill_level}:
|
||||
|
||||
- Expert: "Let's define your product vision. What are you building?"
|
||||
- Intermediate: "I'm here to help shape your product vision. Tell me about your idea."
|
||||
- Beginner: "Hi! I'm going to help you figure out exactly what you want to build. Let's start with your idea - what got you excited about this?"
|
||||
|
||||
Start with open exploration:
|
||||
|
||||
- What sparked this idea?
|
||||
- What are you hoping to build?
|
||||
- Who is this for - yourself, a business, users you know?
|
||||
|
||||
CRITICAL: Listen for context clues that reveal their situation:
|
||||
|
||||
- Personal/hobby project (fun, learning, small audience)
|
||||
- Startup/solopreneur (market opportunity, competition matters)
|
||||
- Enterprise/corporate (stakeholders, compliance, strategic alignment)
|
||||
- Technical enthusiasm (implementation focused)
|
||||
- Business opportunity (market/revenue focused)
|
||||
- Problem frustration (solution focused)
|
||||
|
||||
Based on their initial response, sense:
|
||||
|
||||
- How formal/casual they want to be
|
||||
- Whether they think in business or technical terms
|
||||
- If they have existing materials to share
|
||||
- Their confidence level with the domain</action>
|
||||
|
||||
<ask>What's the project name, and what got you excited about building this?</ask>
|
||||
|
||||
<action>From even this first exchange, create initial document sections</action>
|
||||
<template-output>project_name</template-output>
|
||||
<template-output>executive_summary</template-output>
|
||||
|
||||
<action>If they mentioned existing documents (research, brainstorming, etc.):
|
||||
|
||||
- Load and analyze these materials
|
||||
- Extract key themes and insights
|
||||
- Reference these naturally in conversation: "I see from your research that..."
|
||||
- Use these to accelerate discovery, not repeat questions</action>
|
||||
|
||||
<template-output>initial_vision</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover the problem worth solving">
|
||||
<action>Guide problem discovery through natural conversation
|
||||
|
||||
DON'T ask: "What problem does this solve?"
|
||||
|
||||
DO explore conversationally based on their context:
|
||||
|
||||
For hobby projects:
|
||||
|
||||
- "What's annoying you that this would fix?"
|
||||
- "What would this make easier or more fun?"
|
||||
- "Show me what the experience is like today without this"
|
||||
|
||||
For business ventures:
|
||||
|
||||
- "Walk me through the frustration your users face today"
|
||||
- "What's the cost of this problem - time, money, opportunities?"
|
||||
- "Who's suffering most from this? Tell me about them"
|
||||
- "What solutions have people tried? Why aren't they working?"
|
||||
|
||||
For enterprise:
|
||||
|
||||
- "What's driving the need for this internally?"
|
||||
- "Which teams/processes are most affected?"
|
||||
- "What's the business impact of not solving this?"
|
||||
- "Are there compliance or strategic drivers?"
|
||||
|
||||
Listen for depth cues:
|
||||
|
||||
- Brief answers → dig deeper with follow-ups
|
||||
- Detailed passion → let them flow, capture everything
|
||||
- Uncertainty → help them explore with examples
|
||||
- Multiple problems → help prioritize the core issue
|
||||
|
||||
Adapt your response:
|
||||
|
||||
- If they struggle: offer analogies, examples, frameworks
|
||||
- If they're clear: validate and push for specifics
|
||||
- If they're technical: explore implementation challenges
|
||||
- If they're business-focused: quantify impact</action>
|
||||
|
||||
<action>Immediately capture what emerges - even if preliminary</action>
|
||||
<template-output>problem_statement</template-output>
|
||||
|
||||
<check if="user mentioned metrics, costs, or business impact">
|
||||
<action>Explore the measurable impact of the problem</action>
|
||||
<template-output>problem_impact</template-output>
|
||||
</check>
|
||||
|
||||
<check if="user mentioned current solutions or competitors">
|
||||
<action>Understand why existing solutions fall short</action>
|
||||
<template-output>existing_solutions_gaps</template-output>
|
||||
</check>
|
||||
|
||||
<action>Reflect understanding: "So the core issue is {{problem_summary}}, and {{impact_if_mentioned}}. Let me capture that..."</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Shape the solution vision">
|
||||
<action>Transition naturally from problem to solution
|
||||
|
||||
Based on their energy and context, explore:
|
||||
|
||||
For builders/makers:
|
||||
|
||||
- "How do you envision this working?"
|
||||
- "Walk me through the experience you want to create"
|
||||
- "What's the 'magic moment' when someone uses this?"
|
||||
|
||||
For business minds:
|
||||
|
||||
- "What's your unique approach to solving this?"
|
||||
- "How is this different from what exists today?"
|
||||
- "What makes this the RIGHT solution now?"
|
||||
|
||||
For enterprise:
|
||||
|
||||
- "What would success look like for the organization?"
|
||||
- "How does this fit with existing systems/processes?"
|
||||
- "What's the transformation you're enabling?"
|
||||
|
||||
Go deeper based on responses:
|
||||
|
||||
- If innovative → explore the unique angle
|
||||
- If standard → focus on execution excellence
|
||||
- If technical → discuss key capabilities
|
||||
- If user-focused → paint the journey
|
||||
|
||||
Web research when relevant:
|
||||
|
||||
- If they mention competitors → research current solutions
|
||||
- If they claim innovation → verify uniqueness
|
||||
- If they reference trends → get current data</action>
|
||||
|
||||
<action if="competitor or market mentioned">
|
||||
<WebSearch>{{competitor/market}} latest features 2024</WebSearch>
|
||||
<action>Use findings to sharpen differentiation discussion</action>
|
||||
</action>
|
||||
|
||||
<template-output>proposed_solution</template-output>
|
||||
|
||||
<check if="unique differentiation discussed">
|
||||
<template-output>key_differentiators</template-output>
|
||||
</check>
|
||||
|
||||
<action>Continue building the living document</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Understand the people who need this">
|
||||
<action>Discover target users through storytelling, not demographics
|
||||
|
||||
Facilitate based on project type:
|
||||
|
||||
Personal/hobby:
|
||||
|
||||
- "Who else would love this besides you?"
|
||||
- "Tell me about someone who would use this"
|
||||
- Keep it light and informal
|
||||
|
||||
Startup/business:
|
||||
|
||||
- "Describe your ideal first customer - not demographics, but their situation"
|
||||
- "What are they doing today without your solution?"
|
||||
- "What would make them say 'finally, someone gets it!'?"
|
||||
- "Are there different types of users with different needs?"
|
||||
|
||||
Enterprise:
|
||||
|
||||
- "Which roles/departments will use this?"
|
||||
- "Walk me through their current workflow"
|
||||
- "Who are the champions vs skeptics?"
|
||||
- "What about indirect stakeholders?"
|
||||
|
||||
Push beyond generic personas:
|
||||
|
||||
- Not: "busy professionals" → "Sales reps who waste 2 hours/day on data entry"
|
||||
- Not: "tech-savvy users" → "Developers who know Docker but hate configuring it"
|
||||
- Not: "small businesses" → "Shopify stores doing $10-50k/month wanting to scale"
|
||||
|
||||
For each user type that emerges:
|
||||
|
||||
- Current behavior/workflow
|
||||
- Specific frustrations
|
||||
- What they'd value most
|
||||
- Their technical comfort level</action>
|
||||
|
||||
<template-output>primary_user_segment</template-output>
|
||||
|
||||
<check if="multiple user types mentioned">
|
||||
<action>Explore secondary users only if truly different needs</action>
|
||||
<template-output>secondary_user_segment</template-output>
|
||||
</check>
|
||||
|
||||
<check if="user journey or workflow discussed">
|
||||
<template-output>user_journey</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Define what success looks like" repeat="adapt-to-context">
|
||||
<action>Explore success measures that match their context
|
||||
|
||||
For personal projects:
|
||||
|
||||
- "How will you know this is working well?"
|
||||
- "What would make you proud of this?"
|
||||
- Keep metrics simple and meaningful
|
||||
|
||||
For startups:
|
||||
|
||||
- "What metrics would convince you this is taking off?"
|
||||
- "What user behaviors show they love it?"
|
||||
- "What business metrics matter most - users, revenue, retention?"
|
||||
- Push for specific targets: "100 users" not "lots of users"
|
||||
|
||||
For enterprise:
|
||||
|
||||
- "How will the organization measure success?"
|
||||
- "What KPIs will stakeholders care about?"
|
||||
- "What are the must-hit metrics vs nice-to-haves?"
|
||||
|
||||
Only dive deep into metrics if they show interest
|
||||
Skip entirely for pure hobby projects
|
||||
Focus on what THEY care about measuring</action>
|
||||
|
||||
<check if="metrics or goals discussed">
|
||||
<template-output>success_metrics</template-output>
|
||||
|
||||
<check if="business objectives mentioned">
|
||||
<template-output>business_objectives</template-output>
|
||||
</check>
|
||||
|
||||
<check if="KPIs matter to them">
|
||||
<template-output>key_performance_indicators</template-output>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Keep the document growing with each discovery</action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Discover the MVP scope">
|
||||
<critical>Focus on FEATURES not epics - that comes in Phase 2</critical>
|
||||
|
||||
<action>Guide MVP scoping based on their maturity
|
||||
|
||||
For experimental/hobby:
|
||||
|
||||
- "What's the ONE thing this must do to be useful?"
|
||||
- "What would make a fun first version?"
|
||||
- Embrace simplicity
|
||||
|
||||
For business ventures:
|
||||
|
||||
- "What's the smallest version that proves your hypothesis?"
|
||||
- "What features would make early adopters say 'good enough'?"
|
||||
- "What's tempting to add but would slow you down?"
|
||||
- Be ruthless about scope creep
|
||||
|
||||
For enterprise:
|
||||
|
||||
- "What's the pilot scope that demonstrates value?"
|
||||
- "Which capabilities are must-have for initial rollout?"
|
||||
- "What can we defer to Phase 2?"
|
||||
|
||||
Use this framing:
|
||||
|
||||
- Core features: "Without this, the product doesn't work"
|
||||
- Nice-to-have: "This would be great, but we can launch without it"
|
||||
- Future vision: "This is where we're headed eventually"
|
||||
|
||||
Challenge feature creep:
|
||||
|
||||
- "Do we need that for launch, or could it come later?"
|
||||
- "What if we started without that - what breaks?"
|
||||
- "Is this core to proving the concept?"</action>
|
||||
|
||||
<template-output>core_features</template-output>
|
||||
|
||||
<check if="scope creep discussed">
|
||||
<template-output>out_of_scope</template-output>
|
||||
</check>
|
||||
|
||||
<check if="future features mentioned">
|
||||
<template-output>future_vision_features</template-output>
|
||||
</check>
|
||||
|
||||
<check if="success criteria for MVP mentioned">
|
||||
<template-output>mvp_success_criteria</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Explore relevant context dimensions" repeat="until-natural-end">
|
||||
<critical>Only explore what emerges naturally - skip what doesn't matter</critical>
|
||||
|
||||
<action>Based on the conversation so far, selectively explore:
|
||||
|
||||
IF financial aspects emerged:
|
||||
|
||||
- Development investment needed
|
||||
- Revenue potential or cost savings
|
||||
- ROI timeline
|
||||
- Budget constraints
|
||||
<check if="discussed">
|
||||
<template-output>financial_considerations</template-output>
|
||||
</check>
|
||||
|
||||
IF market competition mentioned:
|
||||
|
||||
- Competitive landscape
|
||||
- Market opportunity size
|
||||
- Differentiation strategy
|
||||
- Market timing
|
||||
<check if="discussed">
|
||||
<WebSearch>{{market}} size trends 2024</WebSearch>
|
||||
<template-output>market_analysis</template-output>
|
||||
</check>
|
||||
|
||||
IF technical preferences surfaced:
|
||||
|
||||
- Platform choices (web/mobile/desktop)
|
||||
- Technology stack preferences
|
||||
- Integration needs
|
||||
- Performance requirements
|
||||
<check if="discussed">
|
||||
<template-output>technical_preferences</template-output>
|
||||
</check>
|
||||
|
||||
IF organizational context emerged:
|
||||
|
||||
- Strategic alignment
|
||||
- Stakeholder buy-in needs
|
||||
- Change management considerations
|
||||
- Compliance requirements
|
||||
<check if="discussed">
|
||||
<template-output>organizational_context</template-output>
|
||||
</check>
|
||||
|
||||
IF risks or concerns raised:
|
||||
|
||||
- Key risks and mitigation
|
||||
- Critical assumptions
|
||||
- Open questions needing research
|
||||
<check if="discussed">
|
||||
<template-output>risks_and_assumptions</template-output>
|
||||
</check>
|
||||
|
||||
IF timeline pressures mentioned:
|
||||
|
||||
- Launch timeline
|
||||
- Critical milestones
|
||||
- Dependencies
|
||||
<check if="discussed">
|
||||
<template-output>timeline_constraints</template-output>
|
||||
</check>
|
||||
|
||||
Skip anything that hasn't naturally emerged
|
||||
Don't force sections that don't fit their context</action>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Refine and complete the living document">
|
||||
<action>Review what's been captured with the user
|
||||
|
||||
"Let me show you what we've built together..."
|
||||
|
||||
Present the actual document sections created so far
|
||||
|
||||
- Not a summary, but the real content
|
||||
- Shows the document has been growing throughout
|
||||
|
||||
Ask:
|
||||
"Looking at this, what stands out as most important to you?"
|
||||
"Is there anything critical we haven't explored?"
|
||||
"Does this capture your vision?"
|
||||
|
||||
Based on their response:
|
||||
|
||||
- Refine sections that need more depth
|
||||
- Add any missing critical elements
|
||||
- Remove or simplify sections that don't matter
|
||||
- Ensure the document fits THEIR needs, not a template</action>
|
||||
|
||||
<action>Make final refinements based on feedback</action>
|
||||
<template-output>final_refinements</template-output>
|
||||
|
||||
<action>Create executive summary that captures the essence</action>
|
||||
<template-output>executive_summary</template-output>
|
||||
</step>
|
||||
<step n="9" goal="Complete and save the product brief">
|
||||
<action>The document has been building throughout our conversation
|
||||
Now ensure it's complete and well-organized</action>
|
||||
|
||||
<check if="research documents were provided">
|
||||
<action>Append summary of incorporated research</action>
|
||||
<template-output>supporting_materials</template-output>
|
||||
</check>
|
||||
|
||||
<action>Ensure the document structure makes sense for what was discovered:
|
||||
|
||||
- Hobbyist projects might be 2-3 pages focused on problem/solution/features
|
||||
- Startup ventures might be 5-7 pages with market analysis and metrics
|
||||
- Enterprise briefs might be 10+ pages with full strategic context
|
||||
|
||||
The document should reflect their world, not force their world into a template</action>
|
||||
|
||||
<ask>Your product brief is ready! Would you like to:
|
||||
|
||||
1. Review specific sections together
|
||||
2. Make any final adjustments
|
||||
3. Save and move forward
|
||||
|
||||
What feels right?</ask>
|
||||
|
||||
<action>Make any requested refinements</action>
|
||||
<template-output>final_document</template-output>
|
||||
</step>
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "product-brief"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["product-brief"] = "{output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Product Brief Complete, {user_name}!**
|
||||
|
||||
Your product vision has been captured in a document that reflects what matters most for your {{context_type}} project.
|
||||
|
||||
**Document saved:** {output_folder}/bmm-product-brief-{{project_name}}-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**What's next:** {{next_workflow}} ({{next_agent}} agent)
|
||||
|
||||
The next phase will take your brief and create the detailed planning artifacts needed for implementation.
|
||||
{{else}}
|
||||
**Next steps:**
|
||||
|
||||
- Run `workflow-init` to set up guided workflow tracking
|
||||
- Or proceed directly to the PRD workflow if you know your path
|
||||
{{/if}}
|
||||
|
||||
Remember: This brief captures YOUR vision. It grew from our conversation, not from a rigid template. It's ready to guide the next phase of bringing your idea to life.
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
181
bmad/bmm/workflows/1-analysis/product-brief/template.md
Normal file
181
bmad/bmm/workflows/1-analysis/product-brief/template.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Product Brief: {{project_name}}
|
||||
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
**Context:** {{context_type}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
---
|
||||
|
||||
## Core Vision
|
||||
|
||||
### Problem Statement
|
||||
|
||||
{{problem_statement}}
|
||||
|
||||
{{#if problem_impact}}
|
||||
|
||||
### Problem Impact
|
||||
|
||||
{{problem_impact}}
|
||||
{{/if}}
|
||||
|
||||
{{#if existing_solutions_gaps}}
|
||||
|
||||
### Why Existing Solutions Fall Short
|
||||
|
||||
{{existing_solutions_gaps}}
|
||||
{{/if}}
|
||||
|
||||
### Proposed Solution
|
||||
|
||||
{{proposed_solution}}
|
||||
|
||||
{{#if key_differentiators}}
|
||||
|
||||
### Key Differentiators
|
||||
|
||||
{{key_differentiators}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Target Users
|
||||
|
||||
### Primary Users
|
||||
|
||||
{{primary_user_segment}}
|
||||
|
||||
{{#if secondary_user_segment}}
|
||||
|
||||
### Secondary Users
|
||||
|
||||
{{secondary_user_segment}}
|
||||
{{/if}}
|
||||
|
||||
{{#if user_journey}}
|
||||
|
||||
### User Journey
|
||||
|
||||
{{user_journey}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
{{#if success_metrics}}
|
||||
|
||||
## Success Metrics
|
||||
|
||||
{{success_metrics}}
|
||||
|
||||
{{#if business_objectives}}
|
||||
|
||||
### Business Objectives
|
||||
|
||||
{{business_objectives}}
|
||||
{{/if}}
|
||||
|
||||
{{#if key_performance_indicators}}
|
||||
|
||||
### Key Performance Indicators
|
||||
|
||||
{{key_performance_indicators}}
|
||||
{{/if}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## MVP Scope
|
||||
|
||||
### Core Features
|
||||
|
||||
{{core_features}}
|
||||
|
||||
{{#if out_of_scope}}
|
||||
|
||||
### Out of Scope for MVP
|
||||
|
||||
{{out_of_scope}}
|
||||
{{/if}}
|
||||
|
||||
{{#if mvp_success_criteria}}
|
||||
|
||||
### MVP Success Criteria
|
||||
|
||||
{{mvp_success_criteria}}
|
||||
{{/if}}
|
||||
|
||||
{{#if future_vision_features}}
|
||||
|
||||
### Future Vision
|
||||
|
||||
{{future_vision_features}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
{{#if market_analysis}}
|
||||
|
||||
## Market Context
|
||||
|
||||
{{market_analysis}}
|
||||
{{/if}}
|
||||
|
||||
{{#if financial_considerations}}
|
||||
|
||||
## Financial Considerations
|
||||
|
||||
{{financial_considerations}}
|
||||
{{/if}}
|
||||
|
||||
{{#if technical_preferences}}
|
||||
|
||||
## Technical Preferences
|
||||
|
||||
{{technical_preferences}}
|
||||
{{/if}}
|
||||
|
||||
{{#if organizational_context}}
|
||||
|
||||
## Organizational Context
|
||||
|
||||
{{organizational_context}}
|
||||
{{/if}}
|
||||
|
||||
{{#if risks_and_assumptions}}
|
||||
|
||||
## Risks and Assumptions
|
||||
|
||||
{{risks_and_assumptions}}
|
||||
{{/if}}
|
||||
|
||||
{{#if timeline_constraints}}
|
||||
|
||||
## Timeline
|
||||
|
||||
{{timeline_constraints}}
|
||||
{{/if}}
|
||||
|
||||
{{#if supporting_materials}}
|
||||
|
||||
## Supporting Materials
|
||||
|
||||
{{supporting_materials}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
_This Product Brief captures the vision and requirements for {{project_name}}._
|
||||
|
||||
_It was created through collaborative discovery and reflects the unique needs of this {{context_type}} project._
|
||||
|
||||
{{#if next_workflow}}
|
||||
_Next: {{next_workflow}} will transform this brief into detailed planning artifacts._
|
||||
{{else}}
|
||||
_Next: Use the PRD workflow to create detailed product requirements from this brief._
|
||||
{{/if}}
|
||||
45
bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml
Normal file
45
bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml
Normal file
@@ -0,0 +1,45 @@
|
||||
# Product Brief - Interactive Workflow Configuration
|
||||
name: product-brief
|
||||
description: "Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
|
||||
# Optional input documents
|
||||
recommended_inputs:
|
||||
- market_research: "Market research document (optional)"
|
||||
- brainstorming_results: "Brainstorming session outputs (optional)"
|
||||
- competitive_analysis: "Competitive analysis (optional)"
|
||||
- initial_ideas: "Initial product ideas or notes (optional)"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
research:
|
||||
whole: "{output_folder}/*research*.md"
|
||||
sharded: "{output_folder}/*research*/index.md"
|
||||
|
||||
brainstorming:
|
||||
whole: "{output_folder}/*brainstorm*.md"
|
||||
sharded: "{output_folder}/*brainstorm*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief"
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/product-brief-{{project_name}}-{{date}}.md"
|
||||
|
||||
standalone: true
|
||||
454
bmad/bmm/workflows/1-analysis/research/README.md
Normal file
454
bmad/bmm/workflows/1-analysis/research/README.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# Research Workflow - Multi-Type Research System
|
||||
|
||||
## Overview
|
||||
|
||||
The Research Workflow is a comprehensive, adaptive research system that supports multiple research types through an intelligent router pattern. This workflow consolidates various research methodologies into a single, powerful tool that adapts to your specific research needs - from market analysis to technical evaluation to AI prompt generation.
|
||||
|
||||
**Version 2.0.0** - Multi-type research system with router-based architecture
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🔀 Intelligent Research Router
|
||||
|
||||
- **6 Research Types**: Market, Deep Prompt, Technical, Competitive, User, Domain
|
||||
- **Dynamic Instructions**: Loads appropriate instruction set based on research type
|
||||
- **Adaptive Templates**: Selects optimal output format for research goal
|
||||
- **Context-Aware**: Adjusts frameworks and methods per research type
|
||||
|
||||
### 🔍 Market Research (Type: `market`)
|
||||
|
||||
- Real-time web research for current market data
|
||||
- TAM/SAM/SOM calculations with multiple methodologies
|
||||
- Competitive landscape analysis and positioning
|
||||
- Customer persona development and Jobs-to-be-Done
|
||||
- Porter's Five Forces and strategic frameworks
|
||||
- Go-to-market strategy recommendations
|
||||
|
||||
### 🤖 Deep Research Prompt Generation (Type: `deep_prompt`)
|
||||
|
||||
- **Optimized for AI Research Platforms**: ChatGPT Deep Research, Gemini, Grok DeepSearch, Claude Projects
|
||||
- **Prompt Engineering Best Practices**: Multi-stage research workflows, iterative refinement
|
||||
- **Platform-Specific Optimization**: Tailored prompts for each AI research tool
|
||||
- **Context Packaging**: Structures background information for optimal AI understanding
|
||||
- **Research Question Refinement**: Transforms vague questions into precise research prompts
|
||||
|
||||
### 🏗️ Technical/Architecture Research (Type: `technical`)
|
||||
|
||||
- Technology evaluation and comparison matrices
|
||||
- Architecture pattern research and trade-off analysis
|
||||
- Framework/library assessment with pros/cons
|
||||
- Technical feasibility studies
|
||||
- Cost-benefit analysis for technology decisions
|
||||
- Architecture Decision Records (ADR) generation
|
||||
|
||||
### 🎯 Competitive Intelligence (Type: `competitive`)
|
||||
|
||||
- Deep competitor analysis and profiling
|
||||
- Competitive positioning and gap analysis
|
||||
- Strategic group mapping
|
||||
- Feature comparison matrices
|
||||
- Pricing strategy analysis
|
||||
- Market share and growth tracking
|
||||
|
||||
### 👥 User Research (Type: `user`)
|
||||
|
||||
- Customer insights and behavioral analysis
|
||||
- Persona development with demographics and psychographics
|
||||
- Jobs-to-be-Done framework application
|
||||
- Customer journey mapping
|
||||
- Pain point identification
|
||||
- Willingness-to-pay analysis
|
||||
|
||||
### 🌐 Domain/Industry Research (Type: `domain`)
|
||||
|
||||
- Industry deep dives and trend analysis
|
||||
- Regulatory landscape assessment
|
||||
- Domain expertise synthesis
|
||||
- Best practices identification
|
||||
- Standards and compliance requirements
|
||||
- Emerging patterns and disruptions
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow research
|
||||
```
|
||||
|
||||
The workflow will prompt you to select a research type.
|
||||
|
||||
### Direct Research Type Selection
|
||||
|
||||
```bash
|
||||
# Market research
|
||||
workflow research --type market
|
||||
|
||||
# Deep research prompt generation
|
||||
workflow research --type deep_prompt
|
||||
|
||||
# Technical evaluation
|
||||
workflow research --type technical
|
||||
|
||||
# Competitive intelligence
|
||||
workflow research --type competitive
|
||||
|
||||
# User research
|
||||
workflow research --type user
|
||||
|
||||
# Domain analysis
|
||||
workflow research --type domain
|
||||
```
|
||||
|
||||
### With Input Documents
|
||||
|
||||
```bash
|
||||
workflow research --type market --input product-brief.md --input competitor-list.md
|
||||
workflow research --type technical --input requirements.md --input architecture.md
|
||||
workflow research --type deep_prompt --input research-question.md
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
Can be customized through `workflow.yaml`:
|
||||
|
||||
- **research_depth**: `quick`, `standard`, or `comprehensive`
|
||||
- **enable_web_research**: `true`/`false` for real-time data gathering
|
||||
- **enable_competitor_analysis**: `true`/`false` (market/competitive types)
|
||||
- **enable_financial_modeling**: `true`/`false` (market type)
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
research/
|
||||
├── workflow.yaml # Multi-type configuration
|
||||
├── instructions-router.md # Router logic (loads correct instructions)
|
||||
├── instructions-market.md # Market research workflow
|
||||
├── instructions-deep-prompt.md # Deep prompt generation workflow
|
||||
├── instructions-technical.md # Technical evaluation workflow
|
||||
├── template-market.md # Market research report template
|
||||
├── template-deep-prompt.md # Research prompt template
|
||||
├── template-technical.md # Technical evaluation template
|
||||
├── checklist.md # Universal validation criteria
|
||||
├── README.md # This file
|
||||
└── claude-code/ # Claude Code enhancements (optional)
|
||||
├── injections.yaml # Integration configuration
|
||||
└── sub-agents/ # Specialized research agents
|
||||
├── bmm-market-researcher.md
|
||||
├── bmm-trend-spotter.md
|
||||
├── bmm-data-analyst.md
|
||||
├── bmm-competitor-analyzer.md
|
||||
├── bmm-user-researcher.md
|
||||
└── bmm-technical-evaluator.md
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Research Type Selection and Setup
|
||||
|
||||
1. Router presents research type menu
|
||||
2. User selects research type (market, deep_prompt, technical, competitive, user, domain)
|
||||
3. Router loads appropriate instructions and template
|
||||
4. Gather research parameters and inputs
|
||||
|
||||
### Phase 2: Research Type-Specific Execution
|
||||
|
||||
**For Market Research:**
|
||||
|
||||
1. Define research objectives and market boundaries
|
||||
2. Conduct web research across multiple sources
|
||||
3. Calculate TAM/SAM/SOM with triangulation
|
||||
4. Develop customer segments and personas
|
||||
5. Analyze competitive landscape
|
||||
6. Apply industry frameworks (Porter's Five Forces, etc.)
|
||||
7. Identify trends and opportunities
|
||||
8. Develop strategic recommendations
|
||||
9. Create financial projections (optional)
|
||||
10. Compile comprehensive report
|
||||
|
||||
**For Deep Prompt Generation:**
|
||||
|
||||
1. Analyze research question or topic
|
||||
2. Identify optimal AI research platform (ChatGPT, Gemini, Grok, Claude)
|
||||
3. Structure research context and background
|
||||
4. Generate platform-optimized prompt
|
||||
5. Create multi-stage research workflow
|
||||
6. Define iteration and refinement strategy
|
||||
7. Package with context documents
|
||||
8. Provide execution guidance
|
||||
|
||||
**For Technical Research:**
|
||||
|
||||
1. Define technical requirements and constraints
|
||||
2. Identify technologies/frameworks to evaluate
|
||||
3. Research each option (documentation, community, maturity)
|
||||
4. Create comparison matrix with criteria
|
||||
5. Perform trade-off analysis
|
||||
6. Calculate cost-benefit for each option
|
||||
7. Generate Architecture Decision Record (ADR)
|
||||
8. Provide recommendation with rationale
|
||||
|
||||
**For Competitive/User/Domain:**
|
||||
|
||||
- Uses market research workflow with specific focus
|
||||
- Adapts questions and frameworks to research type
|
||||
- Customizes output format for target audience
|
||||
|
||||
### Phase 3: Validation and Delivery
|
||||
|
||||
1. Review outputs against checklist
|
||||
2. Validate completeness and quality
|
||||
3. Generate final report/document
|
||||
4. Provide next steps and recommendations
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files by Research Type
|
||||
|
||||
**Market Research:**
|
||||
|
||||
- `market-research-{product_name}-{date}.md`
|
||||
- Comprehensive market analysis report (10+ sections)
|
||||
|
||||
**Deep Research Prompt:**
|
||||
|
||||
- `deep-research-prompt-{date}.md`
|
||||
- Optimized AI research prompt with context and instructions
|
||||
|
||||
**Technical Research:**
|
||||
|
||||
- `technical-research-{date}.md`
|
||||
- Technology evaluation with comparison matrix and ADR
|
||||
|
||||
**Competitive Intelligence:**
|
||||
|
||||
- `competitive-intelligence-{date}.md`
|
||||
- Detailed competitor analysis and positioning
|
||||
|
||||
**User Research:**
|
||||
|
||||
- `user-research-{date}.md`
|
||||
- Customer insights and persona documentation
|
||||
|
||||
**Domain Research:**
|
||||
|
||||
- `domain-research-{date}.md`
|
||||
- Industry deep dive with trends and best practices
|
||||
|
||||
## Requirements
|
||||
|
||||
### All Research Types
|
||||
|
||||
- BMAD Core v6 project structure
|
||||
- Web search capability (for real-time research)
|
||||
- Access to research data sources
|
||||
|
||||
### Market Research
|
||||
|
||||
- Product or business description
|
||||
- Target customer hypotheses (optional)
|
||||
- Known competitors list (optional)
|
||||
|
||||
### Deep Prompt Research
|
||||
|
||||
- Research question or topic
|
||||
- Background context documents (optional)
|
||||
- Target AI platform preference (optional)
|
||||
|
||||
### Technical Research
|
||||
|
||||
- Technical requirements document
|
||||
- Current architecture (if brownfield)
|
||||
- Technical constraints list
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Know Your Research Goal**: Select the most appropriate research type
|
||||
2. **Gather Context**: Collect relevant documents before starting
|
||||
3. **Set Depth Level**: Choose appropriate research_depth (quick/standard/comprehensive)
|
||||
4. **Define Success Criteria**: What decisions will this research inform?
|
||||
|
||||
### During Execution
|
||||
|
||||
**Market Research:**
|
||||
|
||||
- Provide specific product/service details
|
||||
- Validate market boundaries carefully
|
||||
- Review TAM/SAM/SOM assumptions
|
||||
- Challenge competitive positioning
|
||||
|
||||
**Deep Prompt Generation:**
|
||||
|
||||
- Be specific about research platform target
|
||||
- Provide rich context documents
|
||||
- Clarify expected research outcome
|
||||
- Define iteration strategy
|
||||
|
||||
**Technical Research:**
|
||||
|
||||
- List all evaluation criteria upfront
|
||||
- Weight criteria by importance
|
||||
- Consider long-term implications
|
||||
- Include cost analysis
|
||||
|
||||
### After Completion
|
||||
|
||||
1. Review using the validation checklist
|
||||
2. Update with any missing information
|
||||
3. Share with stakeholders for feedback
|
||||
4. Schedule follow-up research if needed
|
||||
5. Document decisions made based on research
|
||||
|
||||
## Research Frameworks Available
|
||||
|
||||
### Market Research Frameworks
|
||||
|
||||
- TAM/SAM/SOM Analysis
|
||||
- Porter's Five Forces
|
||||
- Jobs-to-be-Done (JTBD)
|
||||
- Technology Adoption Lifecycle
|
||||
- SWOT Analysis
|
||||
- Value Chain Analysis
|
||||
|
||||
### Technical Research Frameworks
|
||||
|
||||
- Trade-off Analysis Matrix
|
||||
- Architecture Decision Records (ADR)
|
||||
- Technology Radar
|
||||
- Comparison Matrix
|
||||
- Cost-Benefit Analysis
|
||||
- Technical Risk Assessment
|
||||
|
||||
### Deep Prompt Frameworks
|
||||
|
||||
- ChatGPT Deep Research Best Practices
|
||||
- Gemini Deep Research Framework
|
||||
- Grok DeepSearch Optimization
|
||||
- Claude Projects Methodology
|
||||
- Iterative Prompt Refinement
|
||||
|
||||
## Data Sources
|
||||
|
||||
The workflow leverages multiple data sources:
|
||||
|
||||
- Industry reports and publications
|
||||
- Government statistics and databases
|
||||
- Financial reports and SEC filings
|
||||
- News articles and press releases
|
||||
- Academic research papers
|
||||
- Technical documentation and RFCs
|
||||
- GitHub repositories and discussions
|
||||
- Stack Overflow and developer forums
|
||||
- Market research firm reports
|
||||
- Social media and communities
|
||||
- Patent databases
|
||||
- Benchmarking studies
|
||||
|
||||
## Claude Code Enhancements
|
||||
|
||||
### Available Subagents
|
||||
|
||||
1. **bmm-market-researcher** - Market intelligence gathering
|
||||
2. **bmm-trend-spotter** - Emerging trends and weak signals
|
||||
3. **bmm-data-analyst** - Quantitative analysis and modeling
|
||||
4. **bmm-competitor-analyzer** - Competitive intelligence
|
||||
5. **bmm-user-researcher** - Customer insights and personas
|
||||
6. **bmm-technical-evaluator** - Technology assessment
|
||||
|
||||
These are automatically invoked during workflow execution if Claude Code integration is configured.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Don't know which research type to choose
|
||||
|
||||
- **Solution**: Start with research question - "What do I need to know?"
|
||||
- Market viability? → `market`
|
||||
- Best technology? → `technical`
|
||||
- Need AI to research deeper? → `deep_prompt`
|
||||
- Who are competitors? → `competitive`
|
||||
- Who are users? → `user`
|
||||
- Industry understanding? → `domain`
|
||||
|
||||
### Issue: Market research results seem incomplete
|
||||
|
||||
- **Solution**: Increase research_depth to `comprehensive`
|
||||
- **Check**: Enable web_research in workflow.yaml
|
||||
- **Try**: Run competitive and user research separately for more depth
|
||||
|
||||
### Issue: Deep prompt doesn't work with target platform
|
||||
|
||||
- **Solution**: Review platform-specific best practices in generated prompt
|
||||
- **Check**: Ensure context documents are included
|
||||
- **Try**: Regenerate with different platform selection
|
||||
|
||||
### Issue: Technical comparison is subjective
|
||||
|
||||
- **Solution**: Add more objective criteria (performance metrics, cost, community size)
|
||||
- **Check**: Weight criteria by business importance
|
||||
- **Try**: Run pilot implementations for top 2 options
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding New Research Types
|
||||
|
||||
1. Create new instructions file: `instructions-{type}.md`
|
||||
2. Create new template file: `template-{type}.md`
|
||||
3. Add research type to `workflow.yaml` `research_types` section
|
||||
4. Update router logic in `instructions-router.md`
|
||||
|
||||
### Modifying Existing Research Types
|
||||
|
||||
1. Edit appropriate `instructions-{type}.md` file
|
||||
2. Update corresponding `template-{type}.md` if needed
|
||||
3. Adjust validation criteria in `checklist.md`
|
||||
|
||||
### Creating Custom Frameworks
|
||||
|
||||
Add to `workflow.yaml` `frameworks` section under appropriate research type.
|
||||
|
||||
## Version History
|
||||
|
||||
- **v2.0.0** - Multi-type research system with router architecture
|
||||
- Added deep_prompt research type for AI research platform optimization
|
||||
- Added technical research type for technology evaluation
|
||||
- Consolidated competitive, user, domain under market with focus variants
|
||||
- Router-based instruction loading
|
||||
- Template selection by research type
|
||||
- Enhanced Claude Code subagent support
|
||||
|
||||
- **v1.0.0** - Initial market research only implementation
|
||||
- Single-purpose market research workflow
|
||||
- Now deprecated in favor of v2.0.0 multi-type system
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Check validation against `checklist.md`
|
||||
- Examine router logic in `instructions-router.md`
|
||||
- Review research type-specific instructions
|
||||
- Consult BMAD Method v6 documentation
|
||||
|
||||
## Migration from v1.0 market-research
|
||||
|
||||
If you're used to the standalone `market-research` workflow:
|
||||
|
||||
```bash
|
||||
# Old way
|
||||
workflow market-research
|
||||
|
||||
# New way
|
||||
workflow research --type market
|
||||
# Or just: workflow research (then select market)
|
||||
```
|
||||
|
||||
All market research functionality is preserved and enhanced in v2.0.0.
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (BMad Method) Module - Empowering systematic research and analysis_
|
||||
144
bmad/bmm/workflows/1-analysis/research/checklist-deep-prompt.md
Normal file
144
bmad/bmm/workflows/1-analysis/research/checklist-deep-prompt.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Deep Research Prompt Validation Checklist
|
||||
|
||||
## 🚨 CRITICAL: Anti-Hallucination Instructions (PRIORITY)
|
||||
|
||||
### Citation Requirements Built Into Prompt
|
||||
|
||||
- [ ] Prompt EXPLICITLY instructs: "Cite sources with URLs for ALL factual claims"
|
||||
- [ ] Prompt requires: "Include source name, date, and URL for every statistic"
|
||||
- [ ] Prompt mandates: "If you cannot find reliable data, state 'No verified data found for [X]'"
|
||||
- [ ] Prompt specifies inline citation format (e.g., "[Source: Company, Year, URL]")
|
||||
- [ ] Prompt requires References section at end with all sources listed
|
||||
|
||||
### Multi-Source Verification Requirements
|
||||
|
||||
- [ ] Prompt instructs: "Cross-reference critical claims with at least 2 independent sources"
|
||||
- [ ] Prompt requires: "Note when sources conflict and present all viewpoints"
|
||||
- [ ] Prompt specifies: "Verify version numbers and dates from official sources"
|
||||
- [ ] Prompt mandates: "Mark confidence levels: [Verified], [Single source], [Uncertain]"
|
||||
|
||||
### Fact vs Analysis Distinction
|
||||
|
||||
- [ ] Prompt requires clear labeling: "Distinguish FACTS (sourced), ANALYSIS (your interpretation), SPECULATION (projections)"
|
||||
- [ ] Prompt instructs: "Do not present assumptions or analysis as verified facts"
|
||||
- [ ] Prompt requires: "Label projections and forecasts clearly as such"
|
||||
- [ ] Prompt warns: "Avoid vague attributions like 'experts say' - name the expert/source"
|
||||
|
||||
### Source Quality Guidance
|
||||
|
||||
- [ ] Prompt specifies preferred sources (e.g., "Official docs > analyst reports > blog posts")
|
||||
- [ ] Prompt prioritizes recency: "Prioritize {{current_year}} sources for time-sensitive data"
|
||||
- [ ] Prompt requires credibility assessment: "Note source credibility for each citation"
|
||||
- [ ] Prompt warns against: "Do not rely on single blog posts for critical claims"
|
||||
|
||||
### Anti-Hallucination Safeguards
|
||||
|
||||
- [ ] Prompt warns: "If data seems convenient or too round, verify with additional sources"
|
||||
- [ ] Prompt instructs: "Flag suspicious claims that need third-party verification"
|
||||
- [ ] Prompt requires: "Provide date accessed for all web sources"
|
||||
- [ ] Prompt mandates: "Do NOT invent statistics - only use verified data"
|
||||
|
||||
## Prompt Foundation
|
||||
|
||||
### Topic and Scope
|
||||
|
||||
- [ ] Research topic is specific and focused (not too broad)
|
||||
- [ ] Target platform is specified (ChatGPT, Gemini, Grok, Claude)
|
||||
- [ ] Temporal scope defined and includes "current {{current_year}}" requirement
|
||||
- [ ] Source recency requirement specified (e.g., "prioritize 2024-2025 sources")
|
||||
|
||||
## Content Requirements
|
||||
|
||||
### Information Specifications
|
||||
|
||||
- [ ] Types of information needed are listed (quantitative, qualitative, trends, case studies, etc.)
|
||||
- [ ] Preferred sources are specified (academic, industry reports, news, etc.)
|
||||
- [ ] Recency requirements are stated (e.g., "prioritize {{current_year}} sources")
|
||||
- [ ] Keywords and technical terms are included for search optimization
|
||||
- [ ] Validation criteria are defined (how to verify findings)
|
||||
|
||||
### Output Structure
|
||||
|
||||
- [ ] Desired format is clear (executive summary, comparison table, timeline, SWOT, etc.)
|
||||
- [ ] Key sections or questions are outlined
|
||||
- [ ] Depth level is specified (overview, standard, comprehensive, exhaustive)
|
||||
- [ ] Citation requirements are stated
|
||||
- [ ] Any special formatting needs are mentioned
|
||||
|
||||
## Platform Optimization
|
||||
|
||||
### Platform-Specific Elements
|
||||
|
||||
- [ ] Prompt is optimized for chosen platform's capabilities
|
||||
- [ ] Platform-specific tips are included
|
||||
- [ ] Query limit considerations are noted (if applicable)
|
||||
- [ ] Platform strengths are leveraged (e.g., ChatGPT's multi-step search, Gemini's plan modification)
|
||||
|
||||
### Execution Guidance
|
||||
|
||||
- [ ] Research persona/perspective is specified (if applicable)
|
||||
- [ ] Special requirements are stated (bias considerations, recency, etc.)
|
||||
- [ ] Follow-up strategy is outlined
|
||||
- [ ] Validation approach is defined
|
||||
|
||||
## Quality and Usability
|
||||
|
||||
### Clarity and Completeness
|
||||
|
||||
- [ ] Prompt language is clear and unambiguous
|
||||
- [ ] All placeholders and variables are replaced with actual values
|
||||
- [ ] Prompt can be copy-pasted directly into platform
|
||||
- [ ] No contradictory instructions exist
|
||||
- [ ] Prompt is self-contained (doesn't assume unstated context)
|
||||
|
||||
### Practical Utility
|
||||
|
||||
- [ ] Execution checklist is provided (before, during, after research)
|
||||
- [ ] Platform usage tips are included
|
||||
- [ ] Follow-up questions are anticipated
|
||||
- [ ] Success criteria are defined
|
||||
- [ ] Output file format is specified
|
||||
|
||||
## Research Depth
|
||||
|
||||
### Scope Appropriateness
|
||||
|
||||
- [ ] Scope matches user's available time and resources
|
||||
- [ ] Depth is appropriate for decision at hand
|
||||
- [ ] Key questions that MUST be answered are identified
|
||||
- [ ] Nice-to-have vs. critical information is distinguished
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
### Quality Standards
|
||||
|
||||
- [ ] Method for cross-referencing sources is specified
|
||||
- [ ] Approach to handling conflicting information is defined
|
||||
- [ ] Confidence level indicators are requested
|
||||
- [ ] Gap identification is included
|
||||
- [ ] Fact vs. opinion distinction is required
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical Issues
|
||||
|
||||
_List any critical gaps or errors that must be addressed:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
### Minor Improvements
|
||||
|
||||
_List minor improvements that would enhance the prompt:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
---
|
||||
|
||||
**Validation Complete:** ☐ Yes ☐ No
|
||||
**Ready to Execute:** ☐ Yes ☐ No
|
||||
**Reviewer:** \***\*\_\*\***
|
||||
**Date:** \***\*\_\*\***
|
||||
249
bmad/bmm/workflows/1-analysis/research/checklist-technical.md
Normal file
249
bmad/bmm/workflows/1-analysis/research/checklist-technical.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# Technical/Architecture Research Validation Checklist
|
||||
|
||||
## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
|
||||
|
||||
### Version Number Verification (MANDATORY)
|
||||
|
||||
- [ ] **EVERY** technology version number has cited source with URL
|
||||
- [ ] Version numbers verified via WebSearch from {{current_year}} (NOT from training data!)
|
||||
- [ ] Official documentation/release pages cited for each version
|
||||
- [ ] Release dates included with version numbers
|
||||
- [ ] LTS status verified from official sources (with URL)
|
||||
- [ ] No "assumed" or "remembered" version numbers - ALL must be verified
|
||||
|
||||
### Technical Claim Source Verification
|
||||
|
||||
- [ ] **EVERY** feature claim has source (official docs, release notes, website)
|
||||
- [ ] Performance benchmarks cite source (official benchmarks, third-party tests with URLs)
|
||||
- [ ] Compatibility claims verified (official compatibility matrix, documentation)
|
||||
- [ ] Community size/popularity backed by sources (GitHub stars, npm downloads, official stats)
|
||||
- [ ] "Supports X" claims verified via official documentation with URL
|
||||
- [ ] No invented capabilities or features
|
||||
|
||||
### Source Quality for Technical Data
|
||||
|
||||
- [ ] Official documentation prioritized (docs.technology.com > blog posts)
|
||||
- [ ] Version info from official release pages (highest credibility)
|
||||
- [ ] Benchmarks from official sources or reputable third-parties (not random blogs)
|
||||
- [ ] Community data from verified sources (GitHub, npm, official registries)
|
||||
- [ ] Pricing from official pricing pages (with URL and date verified)
|
||||
|
||||
### Multi-Source Verification (Critical Technical Claims)
|
||||
|
||||
- [ ] Major technical claims (performance, scalability) verified by 2+ sources
|
||||
- [ ] Technology comparisons cite multiple independent sources
|
||||
- [ ] "Best for X" claims backed by comparative analysis with sources
|
||||
- [ ] Production experience claims cite real case studies or articles with URLs
|
||||
- [ ] No single-source critical decisions without flagging need for verification
|
||||
|
||||
### Anti-Hallucination for Technical Data
|
||||
|
||||
- [ ] No invented version numbers or release dates
|
||||
- [ ] No assumed feature availability without verification
|
||||
- [ ] If current data not found, explicitly states "Could not verify {{current_year}} information"
|
||||
- [ ] Speculation clearly labeled (e.g., "Based on trends, technology may...")
|
||||
- [ ] No "probably supports" or "likely compatible" without verification
|
||||
|
||||
## Technology Evaluation
|
||||
|
||||
### Comprehensive Profiling
|
||||
|
||||
For each evaluated technology:
|
||||
|
||||
- [ ] Core capabilities and features are documented
|
||||
- [ ] Architecture and design philosophy are explained
|
||||
- [ ] Maturity level is assessed (experimental, stable, mature, legacy)
|
||||
- [ ] Community size and activity are measured
|
||||
- [ ] Maintenance status is verified (active, maintenance mode, abandoned)
|
||||
|
||||
### Practical Considerations
|
||||
|
||||
- [ ] Learning curve is evaluated
|
||||
- [ ] Documentation quality is assessed
|
||||
- [ ] Developer experience is considered
|
||||
- [ ] Tooling ecosystem is reviewed
|
||||
- [ ] Testing and debugging capabilities are examined
|
||||
|
||||
### Operational Assessment
|
||||
|
||||
- [ ] Deployment complexity is understood
|
||||
- [ ] Monitoring and observability options are evaluated
|
||||
- [ ] Operational overhead is estimated
|
||||
- [ ] Cloud provider support is verified
|
||||
- [ ] Container/Kubernetes compatibility is checked (if relevant)
|
||||
|
||||
## Comparative Analysis
|
||||
|
||||
### Multi-Dimensional Comparison
|
||||
|
||||
- [ ] Technologies are compared across relevant dimensions
|
||||
- [ ] Performance benchmarks are included (if available)
|
||||
- [ ] Scalability characteristics are compared
|
||||
- [ ] Complexity trade-offs are analyzed
|
||||
- [ ] Total cost of ownership is estimated for each option
|
||||
|
||||
### Trade-off Analysis
|
||||
|
||||
- [ ] Key trade-offs between options are identified
|
||||
- [ ] Decision factors are prioritized based on user needs
|
||||
- [ ] Conditions favoring each option are specified
|
||||
- [ ] Weighted analysis reflects user's priorities
|
||||
|
||||
## Real-World Evidence
|
||||
|
||||
### Production Experience
|
||||
|
||||
- [ ] Real-world production experiences are researched
|
||||
- [ ] Known issues and gotchas are documented
|
||||
- [ ] Performance data from actual deployments is included
|
||||
- [ ] Migration experiences are considered (if replacing existing tech)
|
||||
- [ ] Community discussions and war stories are referenced
|
||||
|
||||
### Source Quality
|
||||
|
||||
- [ ] Multiple independent sources validate key claims
|
||||
- [ ] Recent sources from {{current_year}} are prioritized
|
||||
- [ ] Practitioner experiences are included (blog posts, conference talks, forums)
|
||||
- [ ] Both proponent and critic perspectives are considered
|
||||
|
||||
## Decision Support
|
||||
|
||||
### Recommendations
|
||||
|
||||
- [ ] Primary recommendation is clearly stated with rationale
|
||||
- [ ] Alternative options are explained with use cases
|
||||
- [ ] Fit for user's specific context is explained
|
||||
- [ ] Decision is justified by requirements and constraints
|
||||
|
||||
### Implementation Guidance
|
||||
|
||||
- [ ] Proof-of-concept approach is outlined
|
||||
- [ ] Key implementation decisions are identified
|
||||
- [ ] Migration path is described (if applicable)
|
||||
- [ ] Success criteria are defined
|
||||
- [ ] Validation approach is recommended
|
||||
|
||||
### Risk Management
|
||||
|
||||
- [ ] Technical risks are identified
|
||||
- [ ] Mitigation strategies are provided
|
||||
- [ ] Contingency options are outlined (if primary choice doesn't work)
|
||||
- [ ] Exit strategy considerations are discussed
|
||||
|
||||
## Architecture Decision Record
|
||||
|
||||
### ADR Completeness
|
||||
|
||||
- [ ] Status is specified (Proposed, Accepted, Superseded)
|
||||
- [ ] Context and problem statement are clear
|
||||
- [ ] Decision drivers are documented
|
||||
- [ ] All considered options are listed
|
||||
- [ ] Chosen option and rationale are explained
|
||||
- [ ] Consequences (positive, negative, neutral) are identified
|
||||
- [ ] Implementation notes are included
|
||||
- [ ] References to research sources are provided
|
||||
|
||||
## References and Source Documentation (CRITICAL)
|
||||
|
||||
### References Section Completeness
|
||||
|
||||
- [ ] Report includes comprehensive "References and Sources" section
|
||||
- [ ] Sources organized by category (official docs, benchmarks, community, architecture)
|
||||
- [ ] Every source includes: Title, Publisher/Site, Date Accessed, Full URL
|
||||
- [ ] URLs are clickable and functional (documentation links, release pages, GitHub)
|
||||
- [ ] Version verification sources clearly listed
|
||||
- [ ] Inline citations throughout report reference the sources section
|
||||
|
||||
### Technology Source Documentation
|
||||
|
||||
- [ ] For each technology evaluated, sources documented:
|
||||
- Official documentation URL
|
||||
- Release notes/changelog URL for version
|
||||
- Pricing page URL (if applicable)
|
||||
- Community/GitHub URL
|
||||
- Benchmark source URLs
|
||||
- [ ] Comparison data cites source for each claim
|
||||
- [ ] Architecture pattern sources cited (articles, books, official guides)
|
||||
|
||||
### Source Quality Metrics
|
||||
|
||||
- [ ] Report documents total sources cited
|
||||
- [ ] Official sources count (highest credibility)
|
||||
- [ ] Third-party sources count (benchmarks, articles)
|
||||
- [ ] Version verification count (all technologies verified {{current_year}})
|
||||
- [ ] Outdated sources flagged (if any used)
|
||||
|
||||
### Citation Format Standards
|
||||
|
||||
- [ ] Inline citations format: [Source: Docs URL] or [Version: 1.2.3, Source: Release Page URL]
|
||||
- [ ] Consistent citation style throughout
|
||||
- [ ] No vague citations like "according to the community" without specifics
|
||||
- [ ] GitHub links include star count and last update date
|
||||
- [ ] Documentation links point to current stable version docs
|
||||
|
||||
## Document Quality
|
||||
|
||||
### Anti-Hallucination Final Check
|
||||
|
||||
- [ ] Spot-check 5 random version numbers - can you find the cited source?
|
||||
- [ ] Verify feature claims against official documentation
|
||||
- [ ] Check any performance numbers have benchmark sources
|
||||
- [ ] Ensure no "cutting edge" or "latest" without specific version number
|
||||
- [ ] Cross-check technology comparisons with cited sources
|
||||
|
||||
### Structure and Completeness
|
||||
|
||||
- [ ] Executive summary captures key findings
|
||||
- [ ] No placeholder text remains (all {{variables}} are replaced)
|
||||
- [ ] References section is complete and properly formatted
|
||||
- [ ] Version verification audit trail included
|
||||
- [ ] Document ready for technical fact-checking by third party
|
||||
|
||||
## Research Completeness
|
||||
|
||||
### Coverage
|
||||
|
||||
- [ ] All user requirements were addressed
|
||||
- [ ] All constraints were considered
|
||||
- [ ] Sufficient depth for the decision at hand
|
||||
- [ ] Optional analyses were considered and included/excluded appropriately
|
||||
- [ ] Web research was conducted for current market data
|
||||
|
||||
### Data Freshness
|
||||
|
||||
- [ ] Current {{current_year}} data was used throughout
|
||||
- [ ] Version information is up-to-date
|
||||
- [ ] Recent developments and trends are included
|
||||
- [ ] Outdated or deprecated information is flagged or excluded
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical Issues
|
||||
|
||||
_List any critical gaps or errors that must be addressed:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
### Minor Improvements
|
||||
|
||||
_List minor improvements that would enhance the report:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
### Additional Research Needed
|
||||
|
||||
_List areas requiring further investigation:_
|
||||
|
||||
- [ ] Topic 1: [Description]
|
||||
- [ ] Topic 2: [Description]
|
||||
|
||||
---
|
||||
|
||||
**Validation Complete:** ☐ Yes ☐ No
|
||||
**Ready for Decision:** ☐ Yes ☐ No
|
||||
**Reviewer:** \***\*\_\*\***
|
||||
**Date:** \***\*\_\*\***
|
||||
299
bmad/bmm/workflows/1-analysis/research/checklist.md
Normal file
299
bmad/bmm/workflows/1-analysis/research/checklist.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Market Research Report Validation Checklist
|
||||
|
||||
## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
|
||||
|
||||
### Source Citation Completeness
|
||||
|
||||
- [ ] **EVERY** market size claim has at least 2 cited sources with URLs
|
||||
- [ ] **EVERY** growth rate/CAGR has cited sources with URLs
|
||||
- [ ] **EVERY** competitive data point (pricing, features, funding) has sources with URLs
|
||||
- [ ] **EVERY** customer statistic or insight has cited sources
|
||||
- [ ] **EVERY** industry trend claim has sources from {{current_year}} or recent years
|
||||
- [ ] All sources include: Name, Date, URL (clickable links)
|
||||
- [ ] No claims exist without verifiable sources
|
||||
|
||||
### Source Quality and Credibility
|
||||
|
||||
- [ ] Market size sources are HIGH credibility (Gartner, Forrester, IDC, government data, industry associations)
|
||||
- [ ] NOT relying on single blog posts or unverified sources for critical data
|
||||
- [ ] Sources are recent ({{current_year}} or within 1-2 years for time-sensitive data)
|
||||
- [ ] Primary sources prioritized over secondary/tertiary sources
|
||||
- [ ] Paywalled reports are cited with proper attribution (e.g., "Gartner Market Report 2025")
|
||||
|
||||
### Multi-Source Verification (Critical Claims)
|
||||
|
||||
- [ ] TAM calculation verified by at least 2 independent sources
|
||||
- [ ] SAM calculation methodology is transparent and sourced
|
||||
- [ ] SOM estimates are conservative and based on comparable benchmarks
|
||||
- [ ] Market growth rates corroborated by multiple analyst reports
|
||||
- [ ] Competitive market share data verified across sources
|
||||
|
||||
### Conflicting Data Resolution
|
||||
|
||||
- [ ] Where sources conflict, ALL conflicting estimates are presented
|
||||
- [ ] Variance between sources is explained (methodology, scope differences)
|
||||
- [ ] No arbitrary selection of "convenient" numbers without noting alternatives
|
||||
- [ ] Conflicting data is flagged with confidence levels
|
||||
- [ ] User is made aware of uncertainty in conflicting claims
|
||||
|
||||
### Confidence Level Marking
|
||||
|
||||
- [ ] Every major claim is marked with confidence level:
|
||||
- **[Verified - 2+ sources]** = High confidence, multiple independent sources agree
|
||||
- **[Single source - verify]** = Medium confidence, only one source found
|
||||
- **[Estimated - low confidence]** = Low confidence, calculated/projected without strong sources
|
||||
- [ ] Low confidence claims are clearly flagged for user to verify independently
|
||||
- [ ] Speculative/projected data is labeled as PROJECTION or FORECAST, not presented as fact
|
||||
|
||||
### Fact vs Analysis vs Speculation
|
||||
|
||||
- [ ] Clear distinction between:
|
||||
- **FACT:** Sourced data with citations (e.g., "Market is $5.2B [Source: Gartner 2025]")
|
||||
- **ANALYSIS:** Interpretation of facts (e.g., "This suggests strong growth momentum")
|
||||
- **SPECULATION:** Educated guesses (e.g., "This trend may continue if...")
|
||||
- [ ] Analysis and speculation are NOT presented as verified facts
|
||||
- [ ] Recommendations are based on sourced facts, not unsupported assumptions
|
||||
|
||||
### Anti-Hallucination Verification
|
||||
|
||||
- [ ] No invented statistics or "made up" market sizes
|
||||
- [ ] All percentages, dollar amounts, and growth rates are traceable to sources
|
||||
- [ ] If data couldn't be found, report explicitly states "No verified data available for [X]"
|
||||
- [ ] No use of vague sources like "industry experts say" without naming the expert/source
|
||||
- [ ] Version numbers, dates, and specific figures match source material exactly
|
||||
|
||||
## Market Sizing Analysis (Source-Verified)
|
||||
|
||||
### TAM Calculation Sources
|
||||
|
||||
- [ ] TAM figure has at least 2 independent source citations
|
||||
- [ ] Calculation methodology is sourced (not invented)
|
||||
- [ ] Industry benchmarks used for sanity-check are cited
|
||||
- [ ] Growth rate assumptions are backed by sourced projections
|
||||
- [ ] Any adjustments or filters applied are justified and documented
|
||||
|
||||
### SAM and SOM Source Verification
|
||||
|
||||
- [ ] SAM constraints are based on sourced data (addressable market scope)
|
||||
- [ ] SOM competitive assumptions cite actual competitor data
|
||||
- [ ] Market share benchmarks reference comparable companies with sources
|
||||
- [ ] Scenarios (conservative/realistic/optimistic) are justified with sourced reasoning
|
||||
|
||||
## Competitive Analysis (Source-Verified)
|
||||
|
||||
### Competitor Data Source Verification
|
||||
|
||||
- [ ] **EVERY** competitor mentioned has source for basic company info
|
||||
- [ ] Competitor pricing data has sources (website URLs, pricing pages, reviews)
|
||||
- [ ] Funding amounts cite sources (Crunchbase, press releases, SEC filings)
|
||||
- [ ] Product features verified through sources (official website, documentation, reviews)
|
||||
- [ ] Market positioning claims are backed by sources (analyst reports, company statements)
|
||||
- [ ] Customer count/user numbers cite sources (company announcements, verified reports)
|
||||
- [ ] Recent news and developments cite article URLs with dates from {{current_year}}
|
||||
|
||||
### Competitive Data Credibility
|
||||
|
||||
- [ ] Company websites/official sources used for product info (highest credibility)
|
||||
- [ ] Financial data from Crunchbase, PitchBook, or SEC filings (not rumors)
|
||||
- [ ] Review sites cited for customer sentiment (G2, Capterra, TrustPilot with URLs)
|
||||
- [ ] Pricing verified from official pricing pages (with URL and date checked)
|
||||
- [ ] No assumptions about competitors without sourced evidence
|
||||
|
||||
### Competitive Claims Verification
|
||||
|
||||
- [ ] Market share claims cite analyst reports or verified data
|
||||
- [ ] "Leading" or "dominant" claims backed by sourced market data
|
||||
- [ ] Competitor weaknesses cited from reviews, articles, or public statements (not speculation)
|
||||
- [ ] Product comparison claims verified (feature lists from official sources)
|
||||
|
||||
## Customer Intelligence (Source-Verified)
|
||||
|
||||
### Customer Data Sources
|
||||
|
||||
- [ ] Customer segment data cites research sources (reports, surveys, studies)
|
||||
- [ ] Demographics/firmographics backed by census data, industry reports, or studies
|
||||
- [ ] Pain points sourced from customer research, reviews, surveys (not assumed)
|
||||
- [ ] Willingness to pay backed by pricing studies, surveys, or comparable market data
|
||||
- [ ] Buying behavior sourced from research studies or industry data
|
||||
- [ ] Jobs-to-be-Done insights cite customer research or validated frameworks
|
||||
|
||||
### Customer Insight Credibility
|
||||
|
||||
- [ ] Primary research (if conducted) documents sample size and methodology
|
||||
- [ ] Secondary research cites the original study/report with full attribution
|
||||
- [ ] Customer quotes or testimonials cite the source (interview, review site, case study)
|
||||
- [ ] Persona data based on real research findings (not fictional archetypes)
|
||||
- [ ] No invented customer statistics or behaviors without source backing
|
||||
|
||||
### Positioning Analysis
|
||||
|
||||
- [ ] Market positioning map uses relevant dimensions for the industry
|
||||
- [ ] White space opportunities are clearly identified
|
||||
- [ ] Differentiation strategy is supported by competitive gaps
|
||||
- [ ] Switching costs and barriers are quantified
|
||||
- [ ] Network effects and moats are assessed
|
||||
|
||||
## Industry Analysis
|
||||
|
||||
### Porter's Five Forces
|
||||
|
||||
- [ ] Each force has a clear rating (Low/Medium/High) with justification
|
||||
- [ ] Specific examples and evidence support each assessment
|
||||
- [ ] Industry-specific factors are considered (not generic template)
|
||||
- [ ] Implications for strategy are drawn from each force
|
||||
- [ ] Overall industry attractiveness conclusion is provided
|
||||
|
||||
### Trends and Dynamics
|
||||
|
||||
- [ ] At least 5 major trends are identified with evidence
|
||||
- [ ] Technology disruptions are assessed for probability and timeline
|
||||
- [ ] Regulatory changes and their impacts are documented
|
||||
- [ ] Social/cultural shifts relevant to adoption are included
|
||||
- [ ] Market maturity stage is identified with supporting indicators
|
||||
|
||||
## Strategic Recommendations
|
||||
|
||||
### Go-to-Market Strategy
|
||||
|
||||
- [ ] Target segment prioritization has clear rationale
|
||||
- [ ] Positioning statement is specific and differentiated
|
||||
- [ ] Channel strategy aligns with customer buying behavior
|
||||
- [ ] Partnership opportunities are identified with specific targets
|
||||
- [ ] Pricing strategy is justified by willingness-to-pay analysis
|
||||
|
||||
### Opportunity Assessment
|
||||
|
||||
- [ ] Each opportunity is sized quantitatively
|
||||
- [ ] Resource requirements are estimated (time, money, people)
|
||||
- [ ] Success criteria are measurable and time-bound
|
||||
- [ ] Dependencies and prerequisites are identified
|
||||
- [ ] Quick wins vs. long-term plays are distinguished
|
||||
|
||||
### Risk Analysis
|
||||
|
||||
- [ ] All major risk categories are covered (market, competitive, execution, regulatory)
|
||||
- [ ] Each risk has probability and impact assessment
|
||||
- [ ] Mitigation strategies are specific and actionable
|
||||
- [ ] Early warning indicators are defined
|
||||
- [ ] Contingency plans are outlined for high-impact risks
|
||||
|
||||
## References and Source Documentation (CRITICAL)
|
||||
|
||||
### References Section Completeness
|
||||
|
||||
- [ ] Report includes comprehensive "References and Sources" section
|
||||
- [ ] Sources organized by category (market size, competitive, customer, trends)
|
||||
- [ ] Every source includes: Title/Name, Publisher, Date, Full URL
|
||||
- [ ] URLs are clickable and functional (not broken links)
|
||||
- [ ] Sources are numbered or organized for easy reference
|
||||
- [ ] Inline citations throughout report reference the sources section
|
||||
|
||||
### Source Quality Metrics
|
||||
|
||||
- [ ] Report documents total sources cited count
|
||||
- [ ] High confidence claims (2+ sources) count is reported
|
||||
- [ ] Single source claims are identified and counted
|
||||
- [ ] Low confidence/speculative claims are flagged
|
||||
- [ ] Web searches conducted count is included (for transparency)
|
||||
|
||||
### Source Audit Trail
|
||||
|
||||
- [ ] For each major section, sources are listed
|
||||
- [ ] TAM/SAM/SOM calculations show source for each number
|
||||
- [ ] Competitive data shows source for each competitor profile
|
||||
- [ ] Customer insights show research sources
|
||||
- [ ] Industry trends show article/report sources with dates
|
||||
|
||||
### Citation Format Standards
|
||||
|
||||
- [ ] Inline citations format: [Source: Company/Publication, Year, URL] or similar
|
||||
- [ ] Consistent citation style throughout document
|
||||
- [ ] No vague citations like "according to sources" without specifics
|
||||
- [ ] URLs are complete (not truncated)
|
||||
- [ ] Accessed/verified dates included for web sources
|
||||
|
||||
## Document Quality
|
||||
|
||||
### Anti-Hallucination Final Check
|
||||
|
||||
- [ ] Read through entire report - does anything "feel" invented or too convenient?
|
||||
- [ ] Spot-check 5-10 random claims - can you find the cited source?
|
||||
- [ ] Check suspicious round numbers - are they actually from sources?
|
||||
- [ ] Verify any "shocking" statistics have strong sources
|
||||
- [ ] Cross-check key market size claims against multiple cited sources
|
||||
|
||||
### Structure and Completeness
|
||||
|
||||
- [ ] Executive summary captures all key insights
|
||||
- [ ] No placeholder text remains (all {{variables}} are replaced)
|
||||
- [ ] References section is complete and properly formatted
|
||||
- [ ] Source quality assessment included
|
||||
- [ ] Document ready for fact-checking by third party
|
||||
|
||||
## Research Completeness
|
||||
|
||||
### Coverage Check
|
||||
|
||||
- [ ] All workflow steps were completed (none skipped without justification)
|
||||
- [ ] Optional analyses were considered and included where valuable
|
||||
- [ ] Web research was conducted for current market intelligence
|
||||
- [ ] Financial projections align with market size analysis
|
||||
- [ ] Implementation roadmap provides clear next steps
|
||||
|
||||
### Validation
|
||||
|
||||
- [ ] Key findings are triangulated across multiple sources
|
||||
- [ ] Surprising insights are double-checked for accuracy
|
||||
- [ ] Calculations are verified for mathematical accuracy
|
||||
- [ ] Conclusions logically follow from the analysis
|
||||
- [ ] Recommendations are actionable and specific
|
||||
|
||||
## Final Quality Assurance
|
||||
|
||||
### Ready for Decision-Making
|
||||
|
||||
- [ ] Research answers all initial objectives
|
||||
- [ ] Sufficient detail for investment decisions
|
||||
- [ ] Clear go/no-go recommendation provided
|
||||
- [ ] Success metrics are defined
|
||||
- [ ] Follow-up research needs are identified
|
||||
|
||||
### Document Meta
|
||||
|
||||
- [ ] Research date is current
|
||||
- [ ] Confidence levels are indicated for key assertions
|
||||
- [ ] Next review date is set
|
||||
- [ ] Distribution list is appropriate
|
||||
- [ ] Confidentiality classification is marked
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical Issues
|
||||
|
||||
_List any critical gaps or errors that must be addressed:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
### Minor Issues
|
||||
|
||||
_List minor improvements that would enhance the report:_
|
||||
|
||||
- [ ] Issue 1: [Description]
|
||||
- [ ] Issue 2: [Description]
|
||||
|
||||
### Additional Research Needed
|
||||
|
||||
_List areas requiring further investigation:_
|
||||
|
||||
- [ ] Topic 1: [Description]
|
||||
- [ ] Topic 2: [Description]
|
||||
|
||||
---
|
||||
|
||||
**Validation Complete:** ☐ Yes ☐ No
|
||||
**Ready for Distribution:** ☐ Yes ☐ No
|
||||
**Reviewer:** **\*\***\_\_\_\_**\*\***
|
||||
**Date:** **\*\***\_\_\_\_**\*\***
|
||||
@@ -0,0 +1,114 @@
|
||||
# Market Research Workflow - Claude Code Integration Configuration
|
||||
# This file configures how subagents are installed and integrated
|
||||
|
||||
subagents:
|
||||
# List of subagent files to be installed
|
||||
files:
|
||||
- bmm-market-researcher.md
|
||||
- bmm-trend-spotter.md
|
||||
- bmm-data-analyst.md
|
||||
- bmm-competitor-analyzer.md
|
||||
- bmm-user-researcher.md
|
||||
|
||||
# Installation configuration
|
||||
installation:
|
||||
prompt: "The Market Research workflow includes specialized AI subagents for enhanced research capabilities. Would you like to install them?"
|
||||
location_options:
|
||||
- project # Install to .claude/agents/ in project
|
||||
- user # Install to ~/.claude/agents/ for all projects
|
||||
default_location: project
|
||||
|
||||
# Content injections for the workflow
|
||||
injections:
|
||||
- injection_point: "market-research-subagents"
|
||||
description: "Injects subagent activation instructions into the workflow"
|
||||
content: |
|
||||
<critical>
|
||||
Claude Code Enhanced Mode: The following specialized subagents are available to enhance your market research:
|
||||
|
||||
- **bmm-market-researcher**: Comprehensive market intelligence gathering and analysis
|
||||
- **bmm-trend-spotter**: Identifies emerging trends and weak signals
|
||||
- **bmm-data-analyst**: Quantitative analysis and market sizing calculations
|
||||
- **bmm-competitor-analyzer**: Deep competitive intelligence and positioning
|
||||
- **bmm-user-researcher**: User research, personas, and journey mapping
|
||||
|
||||
These subagents will be automatically invoked when their expertise is relevant to the current research task.
|
||||
Use them PROACTIVELY throughout the workflow for enhanced insights.
|
||||
</critical>
|
||||
|
||||
- injection_point: "market-tam-calculations"
|
||||
description: "Enhanced TAM calculation with data analyst"
|
||||
content: |
|
||||
<invoke-subagent name="bmm-data-analyst">
|
||||
Calculate TAM using multiple methodologies and provide confidence intervals.
|
||||
Use all available market data from previous research steps.
|
||||
Show detailed calculations and assumptions.
|
||||
</invoke-subagent>
|
||||
|
||||
- injection_point: "market-trends-analysis"
|
||||
description: "Enhanced trend analysis with trend spotter"
|
||||
content: |
|
||||
<invoke-subagent name="bmm-trend-spotter">
|
||||
Identify emerging trends, weak signals, and future disruptions.
|
||||
Look for cross-industry patterns and second-order effects.
|
||||
Provide timeline estimates for mainstream adoption.
|
||||
</invoke-subagent>
|
||||
|
||||
- injection_point: "market-customer-segments"
|
||||
description: "Enhanced customer research"
|
||||
content: |
|
||||
<invoke-subagent name="bmm-user-researcher">
|
||||
Develop detailed user personas with jobs-to-be-done analysis.
|
||||
Map the complete customer journey with pain points and opportunities.
|
||||
Provide behavioral and psychographic insights.
|
||||
</invoke-subagent>
|
||||
|
||||
- injection_point: "market-executive-summary"
|
||||
description: "Enhanced executive summary synthesis"
|
||||
content: |
|
||||
<invoke-subagent name="bmm-market-researcher">
|
||||
Synthesize all research findings into a compelling executive summary.
|
||||
Highlight the most critical insights and strategic implications.
|
||||
Ensure all key metrics and recommendations are captured.
|
||||
</invoke-subagent>
|
||||
|
||||
# Configuration for subagent behavior
|
||||
configuration:
|
||||
auto_invoke: true # Automatically invoke subagents when relevant
|
||||
parallel_execution: true # Allow parallel subagent execution
|
||||
cache_results: true # Cache subagent outputs for reuse
|
||||
|
||||
# Subagent-specific configurations
|
||||
subagent_config:
|
||||
bmm-market-researcher:
|
||||
priority: high
|
||||
max_execution_time: 300 # seconds
|
||||
retry_on_failure: true
|
||||
|
||||
bmm-trend-spotter:
|
||||
priority: medium
|
||||
max_execution_time: 180
|
||||
retry_on_failure: false
|
||||
|
||||
bmm-data-analyst:
|
||||
priority: high
|
||||
max_execution_time: 240
|
||||
retry_on_failure: true
|
||||
|
||||
bmm-competitor-analyzer:
|
||||
priority: high
|
||||
max_execution_time: 300
|
||||
retry_on_failure: true
|
||||
|
||||
bmm-user-researcher:
|
||||
priority: medium
|
||||
max_execution_time: 240
|
||||
retry_on_failure: false
|
||||
|
||||
# Metadata
|
||||
metadata:
|
||||
compatible_with: "claude-code-1.0+"
|
||||
workflow: "market-research"
|
||||
module: "bmm"
|
||||
author: "BMad Builder"
|
||||
description: "Claude Code enhancements for comprehensive market research"
|
||||
@@ -0,0 +1,439 @@
|
||||
# Deep Research Prompt Generator Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
|
||||
<critical>This workflow generates structured research prompts optimized for AI platforms</critical>
|
||||
<critical>Based on {{current_year}} best practices from ChatGPT, Gemini, Grok, and Claude</critical>
|
||||
<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
|
||||
<critical>🚨 BUILD ANTI-HALLUCINATION INTO PROMPTS 🚨</critical>
|
||||
<critical>Generated prompts MUST instruct AI to cite sources with URLs for all factual claims</critical>
|
||||
<critical>Include validation requirements: "Cross-reference claims with at least 2 independent sources"</critical>
|
||||
<critical>Add explicit instructions: "If you cannot find reliable data, state 'No verified data found for [X]'"</critical>
|
||||
<critical>Require confidence indicators in prompts: "Mark each claim with confidence level and source quality"</critical>
|
||||
<critical>Include fact-checking instructions: "Distinguish between verified facts, analysis, and speculation"</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Discover what research prompt they need">
|
||||
|
||||
<action>Engage conversationally to understand their needs:
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"Let's craft a research prompt optimized for AI deep research tools.
|
||||
|
||||
What topic or question do you want to investigate, and which platform are you planning to use? (ChatGPT Deep Research, Gemini, Grok, Claude Projects)"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'intermediate'">
|
||||
"I'll help you create a structured research prompt for AI platforms like ChatGPT Deep Research, Gemini, or Grok.
|
||||
|
||||
These tools work best with well-structured prompts that define scope, sources, and output format.
|
||||
|
||||
What do you want to research?"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Think of this as creating a detailed brief for an AI research assistant.
|
||||
|
||||
Tools like ChatGPT Deep Research can spend hours searching the web and synthesizing information - but they work best when you give them clear instructions about what to look for and how to present it.
|
||||
|
||||
What topic are you curious about?"
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Through conversation, discover:
|
||||
|
||||
- **The research topic** - What they want to explore
|
||||
- **Their purpose** - Why they need this (decision-making, learning, writing, etc.)
|
||||
- **Target platform** - Which AI tool they'll use (affects prompt structure)
|
||||
- **Existing knowledge** - What they already know vs. what's uncertain
|
||||
|
||||
Adapt your questions based on their clarity:
|
||||
|
||||
- If they're vague → Help them sharpen the focus
|
||||
- If they're specific → Capture the details
|
||||
- If they're unsure about platform → Guide them to the best fit
|
||||
|
||||
Don't make them fill out a form - have a real conversation.
|
||||
</action>
|
||||
|
||||
<template-output>research_topic</template-output>
|
||||
<template-output>research_goal</template-output>
|
||||
<template-output>target_platform</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define Research Scope and Boundaries">
|
||||
<action>Help user define clear boundaries for focused research</action>
|
||||
|
||||
**Let's define the scope to ensure focused, actionable results:**
|
||||
|
||||
<ask>**Temporal Scope** - What time period should the research cover?
|
||||
|
||||
- Current state only (last 6-12 months)
|
||||
- Recent trends (last 2-3 years)
|
||||
- Historical context (5-10 years)
|
||||
- Future outlook (projections 3-5 years)
|
||||
- Custom date range (specify)</ask>
|
||||
|
||||
<template-output>temporal_scope</template-output>
|
||||
|
||||
<ask>**Geographic Scope** - What geographic focus?
|
||||
|
||||
- Global
|
||||
- Regional (North America, Europe, Asia-Pacific, etc.)
|
||||
- Specific countries
|
||||
- US-focused
|
||||
- Other (specify)</ask>
|
||||
|
||||
<template-output>geographic_scope</template-output>
|
||||
|
||||
<ask>**Thematic Boundaries** - Are there specific aspects to focus on or exclude?
|
||||
|
||||
Examples:
|
||||
|
||||
- Focus: technological innovation, regulatory changes, market dynamics
|
||||
- Exclude: historical background, unrelated adjacent markets</ask>
|
||||
|
||||
<template-output>thematic_boundaries</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Specify Information Types and Sources">
|
||||
<action>Determine what types of information and sources are needed</action>
|
||||
|
||||
**What types of information do you need?**
|
||||
|
||||
<ask>Select all that apply:
|
||||
|
||||
- [ ] Quantitative data and statistics
|
||||
- [ ] Qualitative insights and expert opinions
|
||||
- [ ] Trends and patterns
|
||||
- [ ] Case studies and examples
|
||||
- [ ] Comparative analysis
|
||||
- [ ] Technical specifications
|
||||
- [ ] Regulatory and compliance information
|
||||
- [ ] Financial data
|
||||
- [ ] Academic research
|
||||
- [ ] Industry reports
|
||||
- [ ] News and current events</ask>
|
||||
|
||||
<template-output>information_types</template-output>
|
||||
|
||||
<ask>**Preferred Sources** - Any specific source types or credibility requirements?
|
||||
|
||||
Examples:
|
||||
|
||||
- Peer-reviewed academic journals
|
||||
- Industry analyst reports (Gartner, Forrester, IDC)
|
||||
- Government/regulatory sources
|
||||
- Financial reports and SEC filings
|
||||
- Technical documentation
|
||||
- News from major publications
|
||||
- Expert blogs and thought leadership
|
||||
- Social media and forums (with caveats)</ask>
|
||||
|
||||
<template-output>preferred_sources</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Define Output Structure and Format">
|
||||
<action>Specify desired output format for the research</action>
|
||||
|
||||
<ask>**Output Format** - How should the research be structured?
|
||||
|
||||
1. Executive Summary + Detailed Sections
|
||||
2. Comparative Analysis Table
|
||||
3. Chronological Timeline
|
||||
4. SWOT Analysis Framework
|
||||
5. Problem-Solution-Impact Format
|
||||
6. Question-Answer Format
|
||||
7. Custom structure (describe)</ask>
|
||||
|
||||
<template-output>output_format</template-output>
|
||||
|
||||
<ask>**Key Sections** - What specific sections or questions should the research address?
|
||||
|
||||
Examples for market research:
|
||||
|
||||
- Market size and growth
|
||||
- Key players and competitive landscape
|
||||
- Trends and drivers
|
||||
- Challenges and barriers
|
||||
- Future outlook
|
||||
|
||||
Examples for technical research:
|
||||
|
||||
- Current state of technology
|
||||
- Alternative approaches and trade-offs
|
||||
- Best practices and patterns
|
||||
- Implementation considerations
|
||||
- Tool/framework comparison</ask>
|
||||
|
||||
<template-output>key_sections</template-output>
|
||||
|
||||
<ask>**Depth Level** - How detailed should each section be?
|
||||
|
||||
- High-level overview (2-3 paragraphs per section)
|
||||
- Standard depth (1-2 pages per section)
|
||||
- Comprehensive (3-5 pages per section with examples)
|
||||
- Exhaustive (deep dive with all available data)</ask>
|
||||
|
||||
<template-output>depth_level</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Add Context and Constraints">
|
||||
<action>Gather additional context to make the prompt more effective</action>
|
||||
|
||||
<ask>**Persona/Perspective** - Should the research take a specific viewpoint?
|
||||
|
||||
Examples:
|
||||
|
||||
- "Act as a venture capital analyst evaluating investment opportunities"
|
||||
- "Act as a CTO evaluating technology choices for a fintech startup"
|
||||
- "Act as an academic researcher reviewing literature"
|
||||
- "Act as a product manager assessing market opportunities"
|
||||
- No specific persona needed</ask>
|
||||
|
||||
<template-output>research_persona</template-output>
|
||||
|
||||
<ask>**Special Requirements or Constraints:**
|
||||
|
||||
- Citation requirements (e.g., "Include source URLs for all claims")
|
||||
- Bias considerations (e.g., "Consider perspectives from both proponents and critics")
|
||||
- Recency requirements (e.g., "Prioritize sources from 2024-2025")
|
||||
- Specific keywords or technical terms to focus on
|
||||
- Any topics or angles to avoid</ask>
|
||||
|
||||
<template-output>special_requirements</template-output>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Define Validation and Follow-up Strategy">
|
||||
<action>Establish how to validate findings and what follow-ups might be needed</action>
|
||||
|
||||
<ask>**Validation Criteria** - How should the research be validated?
|
||||
|
||||
- Cross-reference multiple sources for key claims
|
||||
- Identify conflicting viewpoints and resolve them
|
||||
- Distinguish between facts, expert opinions, and speculation
|
||||
- Note confidence levels for different findings
|
||||
- Highlight gaps or areas needing more research</ask>
|
||||
|
||||
<template-output>validation_criteria</template-output>
|
||||
|
||||
<ask>**Follow-up Questions** - What potential follow-up questions should be anticipated?
|
||||
|
||||
Examples:
|
||||
|
||||
- "If cost data is unclear, drill deeper into pricing models"
|
||||
- "If regulatory landscape is complex, create separate analysis"
|
||||
- "If multiple technical approaches exist, create comparison matrix"</ask>
|
||||
|
||||
<template-output>follow_up_strategy</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Generate Optimized Research Prompt">
|
||||
<action>Synthesize all inputs into platform-optimized research prompt</action>
|
||||
|
||||
<critical>Generate the deep research prompt using best practices for the target platform</critical>
|
||||
|
||||
**Prompt Structure Best Practices:**
|
||||
|
||||
1. **Clear Title/Question** (specific, focused)
|
||||
2. **Context and Goal** (why this research matters)
|
||||
3. **Scope Definition** (boundaries and constraints)
|
||||
4. **Information Requirements** (what types of data/insights)
|
||||
5. **Output Structure** (format and sections)
|
||||
6. **Source Guidance** (preferred sources and credibility)
|
||||
7. **Validation Requirements** (how to verify findings)
|
||||
8. **Keywords** (precise technical terms, brand names)
|
||||
|
||||
<action>Generate prompt following this structure</action>
|
||||
|
||||
<template-output file="deep-research-prompt.md">deep_research_prompt</template-output>
|
||||
|
||||
<ask>Review the generated prompt:
|
||||
|
||||
- [a] Accept and save
|
||||
- [e] Edit sections
|
||||
- [r] Refine with additional context
|
||||
- [o] Optimize for different platform</ask>
|
||||
|
||||
<check if="edit or refine">
|
||||
<ask>What would you like to adjust?</ask>
|
||||
<goto step="7">Regenerate with modifications</goto>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Generate Platform-Specific Tips">
|
||||
<action>Provide platform-specific usage tips based on target platform</action>
|
||||
|
||||
<check if="target_platform includes ChatGPT">
|
||||
**ChatGPT Deep Research Tips:**
|
||||
|
||||
- Use clear verbs: "compare," "analyze," "synthesize," "recommend"
|
||||
- Specify keywords explicitly to guide search
|
||||
- Answer clarifying questions thoroughly (requests are more expensive)
|
||||
- You have 25-250 queries/month depending on tier
|
||||
- Review the research plan before it starts searching
|
||||
</check>
|
||||
|
||||
<check if="target_platform includes Gemini">
|
||||
**Gemini Deep Research Tips:**
|
||||
|
||||
- Keep initial prompt simple - you can adjust the research plan
|
||||
- Be specific and clear - vagueness is the enemy
|
||||
- Review and modify the multi-point research plan before it runs
|
||||
- Use follow-up questions to drill deeper or add sections
|
||||
- Available in 45+ languages globally
|
||||
</check>
|
||||
|
||||
<check if="target_platform includes Grok">
|
||||
**Grok DeepSearch Tips:**
|
||||
|
||||
- Include date windows: "from Jan-Jun 2025"
|
||||
- Specify output format: "bullet list + citations"
|
||||
- Pair with Think Mode for reasoning
|
||||
- Use follow-up commands: "Expand on [topic]" to deepen sections
|
||||
- Verify facts when obscure sources cited
|
||||
- Free tier: 5 queries/24hrs, Premium: 30/2hrs
|
||||
</check>
|
||||
|
||||
<check if="target_platform includes Claude">
|
||||
**Claude Projects Tips:**
|
||||
|
||||
- Use Chain of Thought prompting for complex reasoning
|
||||
- Break into sub-prompts for multi-step research (prompt chaining)
|
||||
- Add relevant documents to Project for context
|
||||
- Provide explicit instructions and examples
|
||||
- Test iteratively and refine prompts
|
||||
</check>
|
||||
|
||||
<template-output>platform_tips</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Generate Research Execution Checklist">
|
||||
<action>Create a checklist for executing and evaluating the research</action>
|
||||
|
||||
Generate execution checklist with:
|
||||
|
||||
**Before Running Research:**
|
||||
|
||||
- [ ] Prompt clearly states the research question
|
||||
- [ ] Scope and boundaries are well-defined
|
||||
- [ ] Output format and structure specified
|
||||
- [ ] Keywords and technical terms included
|
||||
- [ ] Source guidance provided
|
||||
- [ ] Validation criteria clear
|
||||
|
||||
**During Research:**
|
||||
|
||||
- [ ] Review research plan before execution (if platform provides)
|
||||
- [ ] Answer any clarifying questions thoroughly
|
||||
- [ ] Monitor progress if platform shows reasoning process
|
||||
- [ ] Take notes on unexpected findings or gaps
|
||||
|
||||
**After Research Completion:**
|
||||
|
||||
- [ ] Verify key facts from multiple sources
|
||||
- [ ] Check citation credibility
|
||||
- [ ] Identify conflicting information and resolve
|
||||
- [ ] Note confidence levels for findings
|
||||
- [ ] Identify gaps requiring follow-up
|
||||
- [ ] Ask clarifying follow-up questions
|
||||
- [ ] Export/save research before query limit resets
|
||||
|
||||
<template-output>execution_checklist</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Finalize and Export">
|
||||
<action>Save complete research prompt package</action>
|
||||
|
||||
**Your Deep Research Prompt Package is ready!**
|
||||
|
||||
The output includes:
|
||||
|
||||
1. **Optimized Research Prompt** - Ready to paste into AI platform
|
||||
2. **Platform-Specific Tips** - How to get the best results
|
||||
3. **Execution Checklist** - Ensure thorough research process
|
||||
4. **Follow-up Strategy** - Questions to deepen findings
|
||||
|
||||
<action>Save all outputs to {default_output_file}</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
1. Generate a variation for a different platform
|
||||
2. Create a follow-up prompt based on hypothetical findings
|
||||
3. Generate a related research prompt
|
||||
4. Exit workflow
|
||||
|
||||
Select option (1-4):</ask>
|
||||
|
||||
<check if="option 1">
|
||||
<goto step="1">Start with different platform selection</goto>
|
||||
</check>
|
||||
|
||||
<check if="option 2 or 3">
|
||||
<goto step="1">Start new prompt with context from previous</goto>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "research"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["research"] = "{output_folder}/bmm-research-deep-prompt-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Deep Research Prompt Generated**
|
||||
|
||||
**Research Prompt:**
|
||||
|
||||
- Structured research prompt generated and saved to {output_folder}/bmm-research-deep-prompt-{{date}}.md
|
||||
- Ready to execute with ChatGPT, Claude, Gemini, or Grok
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: research marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** Execute the research prompt with AI platform, gather findings, or run additional research workflows
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Execute the research prompt with AI platform and gather findings
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
679
bmad/bmm/workflows/1-analysis/research/instructions-market.md
Normal file
679
bmad/bmm/workflows/1-analysis/research/instructions-market.md
Normal file
@@ -0,0 +1,679 @@
|
||||
# Market Research Workflow Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
|
||||
<critical>This is a HIGHLY INTERACTIVE workflow - collaborate with user throughout, don't just gather info and disappear</critical>
|
||||
<critical>Web research is MANDATORY - use WebSearch tool with {{current_year}} for all market intelligence gathering</critical>
|
||||
<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
|
||||
<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
|
||||
<critical>NEVER invent market data - if you cannot find reliable data, explicitly state: "I could not find verified data for [X]"</critical>
|
||||
<critical>EVERY statistic, market size, growth rate, or competitive claim MUST have a cited source with URL</critical>
|
||||
<critical>For CRITICAL claims (TAM/SAM/SOM, market size, growth rates), require 2+ independent sources that agree</critical>
|
||||
<critical>When data sources conflict (e.g., different market size estimates), present ALL estimates with sources and explain variance</critical>
|
||||
<critical>Mark data confidence: [Verified - 2+ sources], [Single source - verify], [Estimated - low confidence]</critical>
|
||||
<critical>Clearly label: FACT (sourced data), ANALYSIS (your interpretation), PROJECTION (forecast/speculation)</critical>
|
||||
<critical>After each WebSearch, extract and store source URLs - include them in the report</critical>
|
||||
<critical>If a claim seems suspicious or too convenient, STOP and cross-verify with additional searches</critical>
|
||||
|
||||
<!-- IDE-INJECT-POINT: market-research-subagents -->
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Discover research needs and scope collaboratively">
|
||||
|
||||
<action>Welcome {user_name} warmly. Position yourself as their collaborative research partner who will:
|
||||
|
||||
- Gather live {{current_year}} market data
|
||||
- Share findings progressively throughout
|
||||
- Help make sense of what we discover together
|
||||
|
||||
Ask what they're building and what market questions they need answered.
|
||||
</action>
|
||||
|
||||
<action>Through natural conversation, discover:
|
||||
|
||||
- The product/service and current stage
|
||||
- Their burning questions (what they REALLY need to know)
|
||||
- Context and urgency (fundraising? launch decision? pivot?)
|
||||
- Existing knowledge vs. uncertainties
|
||||
- Desired depth (gauge from their needs, don't ask them to choose)
|
||||
|
||||
Adapt your approach: If uncertain → help them think it through. If detailed → dig deeper.
|
||||
|
||||
Collaboratively define scope:
|
||||
|
||||
- Markets/segments to focus on
|
||||
- Geographic boundaries
|
||||
- Critical questions vs. nice-to-have
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to confirm you're aligned on what matters.</action>
|
||||
|
||||
<template-output>product_name</template-output>
|
||||
<template-output>product_description</template-output>
|
||||
<template-output>research_objectives</template-output>
|
||||
<template-output>research_scope</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Market Definition and Boundaries">
|
||||
<action>Help the user precisely define the market scope</action>
|
||||
|
||||
Work with the user to establish:
|
||||
|
||||
1. **Market Category Definition**
|
||||
- Primary category/industry
|
||||
- Adjacent or overlapping markets
|
||||
- Where this fits in the value chain
|
||||
|
||||
2. **Geographic Scope**
|
||||
- Global, regional, or country-specific?
|
||||
- Primary markets vs. expansion markets
|
||||
- Regulatory considerations by region
|
||||
|
||||
3. **Customer Segment Boundaries**
|
||||
- B2B, B2C, or B2B2C?
|
||||
- Primary vs. secondary segments
|
||||
- Segment size estimates
|
||||
|
||||
<ask>Should we include adjacent markets in the TAM calculation? This could significantly increase market size but may be less immediately addressable.</ask>
|
||||
|
||||
<template-output>market_definition</template-output>
|
||||
<template-output>geographic_scope</template-output>
|
||||
<template-output>segment_boundaries</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Gather live market intelligence collaboratively">
|
||||
|
||||
<critical>This step REQUIRES WebSearch tool usage - gather CURRENT data from {{current_year}}</critical>
|
||||
<critical>Share findings as you go - make this collaborative, not a black box</critical>
|
||||
|
||||
<action>Let {user_name} know you're searching for current {{market_category}} market data: size, growth, analyst reports, recent trends. Tell them you'll share what you find in a few minutes and review it together.</action>
|
||||
|
||||
<step n="3a" title="Search for market size and industry data">
|
||||
<action>Conduct systematic web searches using WebSearch tool:
|
||||
|
||||
<WebSearch>{{market_category}} market size {{geographic_scope}} {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} industry report Gartner Forrester IDC {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} market growth rate CAGR forecast {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} market trends {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} TAM SAM market opportunity {{current_year}}</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Share findings WITH SOURCES including URLs and dates. Ask if it aligns with their expectations.</action>
|
||||
|
||||
<action>CRITICAL - Validate data before proceeding:
|
||||
|
||||
- Multiple sources with similar figures?
|
||||
- Recent sources ({{current_year}} or within 1-2 years)?
|
||||
- Credible sources (Gartner, Forrester, govt data, reputable pubs)?
|
||||
- Conflicts? Note explicitly, search for more sources, mark [Low Confidence]
|
||||
</action>
|
||||
|
||||
<action if="user_has_questions">Explore surprising data points together</action>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
<template-output>sources_market_size</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3b" title="Search for recent news and developments" optional="true">
|
||||
<action>Search for recent market developments:
|
||||
|
||||
<WebSearch>{{market_category}} news {{current_year}} funding acquisitions</WebSearch>
|
||||
<WebSearch>{{market_category}} recent developments {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} regulatory changes {{current_year}}</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Share noteworthy findings:
|
||||
|
||||
"I found some interesting recent developments:
|
||||
|
||||
{{key_news_highlights}}
|
||||
|
||||
Anything here surprise you or confirm what you suspected?"
|
||||
</action>
|
||||
</step>
|
||||
|
||||
<step n="3c" title="Optional: Government and academic sources" optional="true">
|
||||
<action if="research needs high credibility">Search for authoritative sources:
|
||||
|
||||
<WebSearch>{{market_category}} government statistics census data {{current_year}}</WebSearch>
|
||||
<WebSearch>{{market_category}} academic research white papers {{current_year}}</WebSearch>
|
||||
</action>
|
||||
</step>
|
||||
|
||||
<template-output>market_intelligence_raw</template-output>
|
||||
<template-output>key_data_points</template-output>
|
||||
<template-output>source_credibility_notes</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="TAM, SAM, SOM Calculations">
|
||||
<action>Calculate market sizes using multiple methodologies for triangulation</action>
|
||||
|
||||
<critical>Use actual data gathered in previous steps, not hypothetical numbers</critical>
|
||||
|
||||
<step n="4a" title="TAM Calculation">
|
||||
**Method 1: Top-Down Approach**
|
||||
- Start with total industry size from research
|
||||
- Apply relevant filters and segments
|
||||
- Show calculation: Industry Size × Relevant Percentage
|
||||
|
||||
**Method 2: Bottom-Up Approach**
|
||||
|
||||
- Number of potential customers × Average revenue per customer
|
||||
- Build from unit economics
|
||||
|
||||
**Method 3: Value Theory Approach**
|
||||
|
||||
- Value created × Capturable percentage
|
||||
- Based on problem severity and alternative costs
|
||||
|
||||
<ask>Which TAM calculation method seems most credible given our data? Should we use multiple methods and triangulate?</ask>
|
||||
|
||||
<template-output>tam_calculation</template-output>
|
||||
<template-output>tam_methodology</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4b" title="SAM Calculation">
|
||||
<action>Calculate Serviceable Addressable Market</action>
|
||||
|
||||
Apply constraints to TAM:
|
||||
|
||||
- Geographic limitations (markets you can serve)
|
||||
- Regulatory restrictions
|
||||
- Technical requirements (e.g., internet penetration)
|
||||
- Language/cultural barriers
|
||||
- Current business model limitations
|
||||
|
||||
SAM = TAM × Serviceable Percentage
|
||||
Show the calculation with clear assumptions.
|
||||
|
||||
<template-output>sam_calculation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4c" title="SOM Calculation">
|
||||
<action>Calculate realistic market capture</action>
|
||||
|
||||
Consider competitive dynamics:
|
||||
|
||||
- Current market share of competitors
|
||||
- Your competitive advantages
|
||||
- Resource constraints
|
||||
- Time to market considerations
|
||||
- Customer acquisition capabilities
|
||||
|
||||
Create 3 scenarios:
|
||||
|
||||
1. Conservative (1-2% market share)
|
||||
2. Realistic (3-5% market share)
|
||||
3. Optimistic (5-10% market share)
|
||||
|
||||
<template-output>som_scenarios</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Customer Segment Deep Dive">
|
||||
<action>Develop detailed understanding of target customers</action>
|
||||
|
||||
<step n="5a" title="Segment Identification" repeat="for-each-segment">
|
||||
For each major segment, research and define:
|
||||
|
||||
**Demographics/Firmographics:**
|
||||
|
||||
- Size and scale characteristics
|
||||
- Geographic distribution
|
||||
- Industry/vertical (for B2B)
|
||||
|
||||
**Psychographics:**
|
||||
|
||||
- Values and priorities
|
||||
- Decision-making process
|
||||
- Technology adoption patterns
|
||||
|
||||
**Behavioral Patterns:**
|
||||
|
||||
- Current solutions used
|
||||
- Purchasing frequency
|
||||
- Budget allocation
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
<template-output>segment*profile*{{segment_number}}</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5b" title="Jobs-to-be-Done Framework">
|
||||
<action>Apply JTBD framework to understand customer needs</action>
|
||||
|
||||
For primary segment, identify:
|
||||
|
||||
**Functional Jobs:**
|
||||
|
||||
- Main tasks to accomplish
|
||||
- Problems to solve
|
||||
- Goals to achieve
|
||||
|
||||
**Emotional Jobs:**
|
||||
|
||||
- Feelings sought
|
||||
- Anxieties to avoid
|
||||
- Status desires
|
||||
|
||||
**Social Jobs:**
|
||||
|
||||
- How they want to be perceived
|
||||
- Group dynamics
|
||||
- Peer influences
|
||||
|
||||
<ask>Would you like to conduct actual customer interviews or surveys to validate these jobs? (We can create an interview guide)</ask>
|
||||
|
||||
<template-output>jobs_to_be_done</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5c" title="Willingness to Pay Analysis">
|
||||
<action>Research and estimate pricing sensitivity</action>
|
||||
|
||||
Analyze:
|
||||
|
||||
- Current spending on alternatives
|
||||
- Budget allocation for this category
|
||||
- Value perception indicators
|
||||
- Price points of substitutes
|
||||
|
||||
<template-output>pricing_analysis</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Understand the competitive landscape">
|
||||
<action>Ask if they know their main competitors or if you should search for them.</action>
|
||||
|
||||
<step n="6a" title="Discover competitors together">
|
||||
<action if="user doesn't know competitors">Search for competitors:
|
||||
|
||||
<WebSearch>{{product_category}} competitors {{geographic_scope}} {{current_year}}</WebSearch>
|
||||
<WebSearch>{{product_category}} alternatives comparison {{current_year}}</WebSearch>
|
||||
<WebSearch>top {{product_category}} companies {{current_year}}</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Present findings. Ask them to pick the 3-5 that matter most (most concerned about or curious to understand).</action>
|
||||
</step>
|
||||
|
||||
<step n="6b" title="Research each competitor together" repeat="for-each-selected-competitor">
|
||||
<action>For each competitor, search for:
|
||||
- Company overview, product features
|
||||
- Pricing model
|
||||
- Funding and recent news
|
||||
- Customer reviews and ratings
|
||||
|
||||
Use {{current_year}} in all searches.
|
||||
</action>
|
||||
|
||||
<action>Share findings with sources. Ask what jumps out and if it matches expectations.</action>
|
||||
|
||||
<action if="user has follow-up questions">Dig deeper based on their interests</action>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
<template-output>competitor*analysis*{{competitor_name}}</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6c" title="Competitive Positioning Map">
|
||||
<action>Create positioning analysis</action>
|
||||
|
||||
Map competitors on key dimensions:
|
||||
|
||||
- Price vs. Value
|
||||
- Feature completeness vs. Ease of use
|
||||
- Market segment focus
|
||||
- Technology approach
|
||||
- Business model
|
||||
|
||||
Identify:
|
||||
|
||||
- Gaps in the market
|
||||
- Over-served areas
|
||||
- Differentiation opportunities
|
||||
|
||||
<template-output>competitive_positioning</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Industry Forces Analysis">
|
||||
<action>Apply Porter's Five Forces framework</action>
|
||||
|
||||
<critical>Use specific evidence from research, not generic assessments</critical>
|
||||
|
||||
Analyze each force with concrete examples:
|
||||
|
||||
<step n="7a" title="Supplier Power">
|
||||
Rate: [Low/Medium/High]
|
||||
- Key suppliers and dependencies
|
||||
- Switching costs
|
||||
- Concentration of suppliers
|
||||
- Forward integration threat
|
||||
</step>
|
||||
|
||||
<step n="7b" title="Buyer Power">
|
||||
Rate: [Low/Medium/High]
|
||||
- Customer concentration
|
||||
- Price sensitivity
|
||||
- Switching costs for customers
|
||||
- Backward integration threat
|
||||
</step>
|
||||
|
||||
<step n="7c" title="Competitive Rivalry">
|
||||
Rate: [Low/Medium/High]
|
||||
- Number and strength of competitors
|
||||
- Industry growth rate
|
||||
- Exit barriers
|
||||
- Differentiation levels
|
||||
</step>
|
||||
|
||||
<step n="7d" title="Threat of New Entry">
|
||||
Rate: [Low/Medium/High]
|
||||
- Capital requirements
|
||||
- Regulatory barriers
|
||||
- Network effects
|
||||
- Brand loyalty
|
||||
</step>
|
||||
|
||||
<step n="7e" title="Threat of Substitutes">
|
||||
Rate: [Low/Medium/High]
|
||||
- Alternative solutions
|
||||
- Switching costs to substitutes
|
||||
- Price-performance trade-offs
|
||||
</step>
|
||||
|
||||
<template-output>porters_five_forces</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Market Trends and Future Outlook">
|
||||
<action>Identify trends and future market dynamics</action>
|
||||
|
||||
Research and analyze:
|
||||
|
||||
**Technology Trends:**
|
||||
|
||||
- Emerging technologies impacting market
|
||||
- Digital transformation effects
|
||||
- Automation possibilities
|
||||
|
||||
**Social/Cultural Trends:**
|
||||
|
||||
- Changing customer behaviors
|
||||
- Generational shifts
|
||||
- Social movements impact
|
||||
|
||||
**Economic Trends:**
|
||||
|
||||
- Macroeconomic factors
|
||||
- Industry-specific economics
|
||||
- Investment trends
|
||||
|
||||
**Regulatory Trends:**
|
||||
|
||||
- Upcoming regulations
|
||||
- Compliance requirements
|
||||
- Policy direction
|
||||
|
||||
<ask>Should we explore any specific emerging technologies or disruptions that could reshape this market?</ask>
|
||||
|
||||
<template-output>market_trends</template-output>
|
||||
<template-output>future_outlook</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Opportunity Assessment and Strategy">
|
||||
<action>Synthesize research into strategic opportunities</action>
|
||||
|
||||
<step n="9a" title="Opportunity Identification">
|
||||
Based on all research, identify top 3-5 opportunities:
|
||||
|
||||
For each opportunity:
|
||||
|
||||
- Description and rationale
|
||||
- Size estimate (from SOM)
|
||||
- Resource requirements
|
||||
- Time to market
|
||||
- Risk assessment
|
||||
- Success criteria
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
<template-output>market_opportunities</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9b" title="Go-to-Market Recommendations">
|
||||
Develop GTM strategy based on research:
|
||||
|
||||
**Positioning Strategy:**
|
||||
|
||||
- Value proposition refinement
|
||||
- Differentiation approach
|
||||
- Messaging framework
|
||||
|
||||
**Target Segment Sequencing:**
|
||||
|
||||
- Beachhead market selection
|
||||
- Expansion sequence
|
||||
- Segment-specific approaches
|
||||
|
||||
**Channel Strategy:**
|
||||
|
||||
- Distribution channels
|
||||
- Partnership opportunities
|
||||
- Marketing channels
|
||||
|
||||
**Pricing Strategy:**
|
||||
|
||||
- Model recommendation
|
||||
- Price points
|
||||
- Value metrics
|
||||
|
||||
<template-output>gtm_strategy</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9c" title="Risk Analysis">
|
||||
Identify and assess key risks:
|
||||
|
||||
**Market Risks:**
|
||||
|
||||
- Demand uncertainty
|
||||
- Market timing
|
||||
- Economic sensitivity
|
||||
|
||||
**Competitive Risks:**
|
||||
|
||||
- Competitor responses
|
||||
- New entrants
|
||||
- Technology disruption
|
||||
|
||||
**Execution Risks:**
|
||||
|
||||
- Resource requirements
|
||||
- Capability gaps
|
||||
- Scaling challenges
|
||||
|
||||
For each risk: Impact (H/M/L) × Probability (H/M/L) = Risk Score
|
||||
Provide mitigation strategies.
|
||||
|
||||
<template-output>risk_assessment</template-output>
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Financial Projections" optional="true" if="enable_financial_modeling == true">
|
||||
<action>Create financial model based on market research</action>
|
||||
|
||||
<ask>Would you like to create a financial model with revenue projections based on the market analysis?</ask>
|
||||
|
||||
<check if="yes">
|
||||
Build 3-year projections:
|
||||
|
||||
- Revenue model based on SOM scenarios
|
||||
- Customer acquisition projections
|
||||
- Unit economics
|
||||
- Break-even analysis
|
||||
- Funding requirements
|
||||
|
||||
<template-output>financial_projections</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Synthesize findings together into executive summary">
|
||||
|
||||
<critical>This is the last major content section - make it collaborative</critical>
|
||||
|
||||
<action>Review the research journey together. Share high-level summaries of market size, competitive dynamics, customer insights. Ask what stands out most - what surprised them or confirmed their thinking.</action>
|
||||
|
||||
<action>Collaboratively craft the narrative:
|
||||
|
||||
- What's the headline? (The ONE thing someone should know)
|
||||
- What are the 3-5 critical insights?
|
||||
- Recommended path forward?
|
||||
- Key risks?
|
||||
|
||||
This should read like a strategic brief, not a data dump.
|
||||
</action>
|
||||
|
||||
<action>Draft executive summary and share. Ask if it captures the essence and if anything is missing or overemphasized.</action>
|
||||
|
||||
<template-output>executive_summary</template-output>
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Validate sources and compile report">
|
||||
|
||||
<critical>MANDATORY SOURCE VALIDATION - Do NOT skip this step!</critical>
|
||||
|
||||
<action>Before finalizing, conduct source audit:
|
||||
|
||||
Review every major claim in the report and verify:
|
||||
|
||||
**For Market Size Claims:**
|
||||
|
||||
- [ ] At least 2 independent sources cited with URLs
|
||||
- [ ] Sources are from {{current_year}} or within 2 years
|
||||
- [ ] Sources are credible (Gartner, Forrester, govt data, reputable pubs)
|
||||
- [ ] Conflicting estimates are noted with all sources
|
||||
|
||||
**For Competitive Data:**
|
||||
|
||||
- [ ] Competitor information has source URLs
|
||||
- [ ] Pricing data is current and sourced
|
||||
- [ ] Funding data is verified with dates
|
||||
- [ ] Customer reviews/ratings have source links
|
||||
|
||||
**For Growth Rates and Projections:**
|
||||
|
||||
- [ ] CAGR and forecast data are sourced
|
||||
- [ ] Methodology is explained or linked
|
||||
- [ ] Multiple analyst estimates are compared if available
|
||||
|
||||
**For Customer Insights:**
|
||||
|
||||
- [ ] Persona data is based on real research (cited)
|
||||
- [ ] Survey/interview data has sample size and source
|
||||
- [ ] Behavioral claims are backed by studies/data
|
||||
</action>
|
||||
|
||||
<action>Count and document source quality:
|
||||
|
||||
- Total sources cited: {{count_all_sources}}
|
||||
- High confidence (2+ sources): {{high_confidence_claims}}
|
||||
- Single source (needs verification): {{single_source_claims}}
|
||||
- Uncertain/speculative: {{low_confidence_claims}}
|
||||
|
||||
If {{single_source_claims}} or {{low_confidence_claims}} is high, consider additional research.
|
||||
</action>
|
||||
|
||||
<action>Compile full report with ALL sources properly referenced:
|
||||
|
||||
Generate the complete market research report using the template:
|
||||
|
||||
- Ensure every statistic has inline citation: [Source: Company, Year, URL]
|
||||
- Populate all {{sources_*}} template variables
|
||||
- Include confidence levels for major claims
|
||||
- Add References section with full source list
|
||||
</action>
|
||||
|
||||
<action>Present source quality summary to user:
|
||||
|
||||
"I've completed the research with {{count_all_sources}} total sources:
|
||||
|
||||
- {{high_confidence_claims}} claims verified with multiple sources
|
||||
- {{single_source_claims}} claims from single sources (marked for verification)
|
||||
- {{low_confidence_claims}} claims with low confidence or speculation
|
||||
|
||||
Would you like me to strengthen any areas with additional research?"
|
||||
</action>
|
||||
|
||||
<ask>Would you like to review any specific sections before finalizing? Are there any additional analyses you'd like to include?</ask>
|
||||
|
||||
<goto step="9a" if="user requests changes">Return to refine opportunities</goto>
|
||||
|
||||
<template-output>final_report_ready</template-output>
|
||||
<template-output>source_audit_complete</template-output>
|
||||
</step>
|
||||
|
||||
<step n="13" goal="Appendices and Supporting Materials" optional="true">
|
||||
<ask>Would you like to include detailed appendices with calculations, full competitor profiles, or raw research data?</ask>
|
||||
|
||||
<check if="yes">
|
||||
Create appendices with:
|
||||
|
||||
- Detailed TAM/SAM/SOM calculations
|
||||
- Full competitor profiles
|
||||
- Customer interview notes
|
||||
- Data sources and methodology
|
||||
- Financial model details
|
||||
- Glossary of terms
|
||||
|
||||
<template-output>appendices</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="14" goal="Update status file on completion" tag="workflow-status">
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "research"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["research"] = "{output_folder}/bmm-research-{{research_mode}}-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Research Complete ({{research_mode}} mode)**
|
||||
|
||||
**Research Report:**
|
||||
|
||||
- Research report generated and saved to {output_folder}/bmm-research-{{research_mode}}-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: research marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** Review findings with stakeholders, or run additional analysis workflows (product-brief, game-brief, etc.)
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Review research findings
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
133
bmad/bmm/workflows/1-analysis/research/instructions-router.md
Normal file
133
bmad/bmm/workflows/1-analysis/research/instructions-router.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Research Workflow Router Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate in {communication_language}, generate documents in {document_output_language}</critical>
|
||||
<critical>Web research is ENABLED - always use current {{current_year}} data</critical>
|
||||
|
||||
<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
|
||||
<critical>NEVER present information without a verified source - if you cannot find a source, say "I could not find reliable data on this"</critical>
|
||||
<critical>ALWAYS cite sources with URLs when presenting data, statistics, or factual claims</critical>
|
||||
<critical>REQUIRE at least 2 independent sources for critical claims (market size, growth rates, competitive data)</critical>
|
||||
<critical>When sources conflict, PRESENT BOTH views and note the discrepancy - do NOT pick one arbitrarily</critical>
|
||||
<critical>Flag any data you are uncertain about with confidence levels: [High Confidence], [Medium Confidence], [Low Confidence - verify]</critical>
|
||||
<critical>Distinguish clearly between: FACTS (from sources), ANALYSIS (your interpretation), and SPECULATION (educated guesses)</critical>
|
||||
<critical>When using WebSearch results, ALWAYS extract and include the source URL for every claim</critical>
|
||||
|
||||
<!-- IDE-INJECT-POINT: research-subagents -->
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>This is a ROUTER that directs to specialized research instruction sets</critical>
|
||||
|
||||
<step n="1" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Research is optional - you can continue without status tracking.</output>
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "research" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
<action>Pass status context to loaded instruction set for final update</action>
|
||||
|
||||
<check if="research status is file path (already completed)">
|
||||
<output>⚠️ Research already completed: {{research status}}</output>
|
||||
<ask>Re-running will create a new research report. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="research is not the next expected workflow (latter items are completed already in the list)">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Research is out of sequence.</output>
|
||||
<output>Note: Research can provide valuable insights at any project stage.</output>
|
||||
<ask>Continue with Research anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover research needs through conversation">
|
||||
|
||||
<action>Welcome {user_name} warmly. Position yourself as their research partner who uses live {{current_year}} web data. Ask what they're looking to understand or research.</action>
|
||||
|
||||
<action>Listen and collaboratively identify the research type based on what they describe:
|
||||
|
||||
- Market/Business questions → Market Research
|
||||
- Competitor questions → Competitive Intelligence
|
||||
- Customer questions → User Research
|
||||
- Technology questions → Technical Research
|
||||
- Industry questions → Domain Research
|
||||
- Creating research prompts for AI platforms → Deep Research Prompt Generator
|
||||
|
||||
Confirm your understanding of what type would be most helpful and what it will produce.
|
||||
</action>
|
||||
|
||||
<action>Capture {{research_type}} and {{research_mode}}</action>
|
||||
|
||||
<template-output>research_type_discovery</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Route to Appropriate Research Instructions">
|
||||
|
||||
<critical>Based on user selection, load the appropriate instruction set</critical>
|
||||
|
||||
<check if="research_type == 1 OR fuzzy match market research">
|
||||
<action>Set research_mode = "market"</action>
|
||||
<action>LOAD: {installed_path}/instructions-market.md</action>
|
||||
<action>Continue with market research workflow</action>
|
||||
</check>
|
||||
|
||||
<check if="research_type == 2 or prompt or fuzzy match deep research prompt">
|
||||
<action>Set research_mode = "deep-prompt"</action>
|
||||
<action>LOAD: {installed_path}/instructions-deep-prompt.md</action>
|
||||
<action>Continue with deep research prompt generation</action>
|
||||
</check>
|
||||
|
||||
<check if="research_type == 3 technical or architecture or fuzzy match indicates technical type of research">
|
||||
<action>Set research_mode = "technical"</action>
|
||||
<action>LOAD: {installed_path}/instructions-technical.md</action>
|
||||
<action>Continue with technical research workflow</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="research_type == 4 or fuzzy match competitive">
|
||||
<action>Set research_mode = "competitive"</action>
|
||||
<action>This will use market research workflow with competitive focus</action>
|
||||
<action>LOAD: {installed_path}/instructions-market.md</action>
|
||||
<action>Pass mode="competitive" to focus on competitive intelligence</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="research_type == 5 or fuzzy match user research">
|
||||
<action>Set research_mode = "user"</action>
|
||||
<action>This will use market research workflow with user research focus</action>
|
||||
<action>LOAD: {installed_path}/instructions-market.md</action>
|
||||
<action>Pass mode="user" to focus on customer insights</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="research_type == 6 or fuzzy match domain or industry or category">
|
||||
<action>Set research_mode = "domain"</action>
|
||||
<action>This will use market research workflow with domain focus</action>
|
||||
<action>LOAD: {installed_path}/instructions-market.md</action>
|
||||
<action>Pass mode="domain" to focus on industry/domain analysis</action>
|
||||
</check>
|
||||
|
||||
<critical>The loaded instruction set will continue from here with full context of the {research_type}</critical>
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
538
bmad/bmm/workflows/1-analysis/research/instructions-technical.md
Normal file
538
bmad/bmm/workflows/1-analysis/research/instructions-technical.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# Technical/Architecture Research Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
|
||||
<critical>This is a HIGHLY INTERACTIVE workflow - make technical decisions WITH user, not FOR them</critical>
|
||||
<critical>Web research is MANDATORY - use WebSearch tool with {{current_year}} for current version info and trends</critical>
|
||||
<critical>ALWAYS verify current versions - NEVER use hardcoded or outdated version numbers</critical>
|
||||
<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
|
||||
<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
|
||||
<critical>NEVER invent version numbers, features, or technical details - ALWAYS verify with current {{current_year}} sources</critical>
|
||||
<critical>Every technical claim (version, feature, performance, compatibility) MUST have a cited source with URL</critical>
|
||||
<critical>Version numbers MUST be verified via WebSearch - do NOT rely on training data (it's outdated!)</critical>
|
||||
<critical>When comparing technologies, cite sources for each claim (performance benchmarks, community size, etc.)</critical>
|
||||
<critical>Mark confidence levels: [Verified {{current_year}} source], [Older source - verify], [Uncertain - needs verification]</critical>
|
||||
<critical>Distinguish: FACT (from official docs/sources), OPINION (from community/reviews), SPECULATION (your analysis)</critical>
|
||||
<critical>If you cannot find current information about a technology, state: "I could not find recent {{current_year}} data on [X]"</critical>
|
||||
<critical>Extract and include source URLs in all technology profiles and comparisons</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Discover technical research needs through conversation">
|
||||
|
||||
<action>Engage conversationally based on skill level:
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"Let's research the technical options for your decision.
|
||||
|
||||
I'll gather current data from {{current_year}}, compare approaches, and help you think through trade-offs.
|
||||
|
||||
What technical question are you wrestling with?"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'intermediate'">
|
||||
"I'll help you research and evaluate your technical options.
|
||||
|
||||
We'll look at current technologies (using {{current_year}} data), understand the trade-offs, and figure out what fits your needs best.
|
||||
|
||||
What technical decision are you trying to make?"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Think of this as having a technical advisor help you research your options.
|
||||
|
||||
I'll explain what different technologies do, why you might choose one over another, and help you make an informed decision.
|
||||
|
||||
What technical challenge brought you here?"
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Through conversation, understand:
|
||||
|
||||
- **The technical question** - What they need to decide or understand
|
||||
- **The context** - Greenfield? Brownfield? Learning? Production?
|
||||
- **Current constraints** - Languages, platforms, team skills, budget
|
||||
- **What they already know** - Do they have candidates in mind?
|
||||
|
||||
Don't interrogate - explore together. If they're unsure, help them articulate the problem.
|
||||
</action>
|
||||
|
||||
<template-output>technical_question</template-output>
|
||||
<template-output>project_context</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define Technical Requirements and Constraints">
|
||||
<action>Gather requirements and constraints that will guide the research</action>
|
||||
|
||||
**Let's define your technical requirements:**
|
||||
|
||||
<ask>**Functional Requirements** - What must the technology do?
|
||||
|
||||
Examples:
|
||||
|
||||
- Handle 1M requests per day
|
||||
- Support real-time data processing
|
||||
- Provide full-text search capabilities
|
||||
- Enable offline-first mobile app
|
||||
- Support multi-tenancy</ask>
|
||||
|
||||
<template-output>functional_requirements</template-output>
|
||||
|
||||
<ask>**Non-Functional Requirements** - Performance, scalability, security needs?
|
||||
|
||||
Consider:
|
||||
|
||||
- Performance targets (latency, throughput)
|
||||
- Scalability requirements (users, data volume)
|
||||
- Reliability and availability needs
|
||||
- Security and compliance requirements
|
||||
- Maintainability and developer experience</ask>
|
||||
|
||||
<template-output>non_functional_requirements</template-output>
|
||||
|
||||
<ask>**Constraints** - What limitations or requirements exist?
|
||||
|
||||
- Programming language preferences or requirements
|
||||
- Cloud platform (AWS, Azure, GCP, on-prem)
|
||||
- Budget constraints
|
||||
- Team expertise and skills
|
||||
- Timeline and urgency
|
||||
- Existing technology stack (if brownfield)
|
||||
- Open source vs commercial requirements
|
||||
- Licensing considerations</ask>
|
||||
|
||||
<template-output>technical_constraints</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Discover and evaluate technology options together">
|
||||
|
||||
<critical>MUST use WebSearch to find current options from {{current_year}}</critical>
|
||||
|
||||
<action>Ask if they have candidates in mind:
|
||||
|
||||
"Do you already have specific technologies you want to compare, or should I search for the current options?"
|
||||
</action>
|
||||
|
||||
<action if="user has candidates">Great! Let's research: {{user_candidates}}</action>
|
||||
|
||||
<action if="discovering options">Search for current leading technologies:
|
||||
|
||||
<WebSearch>{{technical_category}} best tools {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technical_category}} comparison {{use_case}} {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technical_category}} popular frameworks {{current_year}}</WebSearch>
|
||||
<WebSearch>state of {{technical_category}} {{current_year}}</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Share findings conversationally:
|
||||
|
||||
"Based on current {{current_year}} data, here are the main options:
|
||||
|
||||
{{discovered_options}}
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
These are the leaders right now. Which ones make sense to evaluate for your use case?"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
Each of these is popular for different reasons. Let me know if you want me to explain what makes each one different."
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
<template-output>technology_options</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Research each technology together in depth">
|
||||
|
||||
<critical>For each option, use WebSearch to gather CURRENT {{current_year}} information</critical>
|
||||
|
||||
<step n="4a" title="Deep dive on each technology" repeat="for-each-option">
|
||||
|
||||
<action>For {{technology_name}}, conduct comprehensive research:
|
||||
|
||||
<WebSearch>{{technology_name}} overview what is {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technology_name}} latest version release notes {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technology_name}} pros cons trade-offs {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technology_name}} production experience real world {{current_year}}</WebSearch>
|
||||
<WebSearch>{{technology_name}} vs alternatives comparison {{current_year}}</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Share findings conversationally and collaboratively:
|
||||
|
||||
"Here's what I found about {{technology_name}}:
|
||||
|
||||
**Overview:**
|
||||
{{what_it_is_and_solves}}
|
||||
|
||||
**Current Status ({{current_year}}):**
|
||||
{{maturity_community_release_cadence}}
|
||||
|
||||
**Technical Characteristics:**
|
||||
|
||||
- Architecture and design philosophy
|
||||
- Core features and capabilities
|
||||
- Performance characteristics
|
||||
- Scalability approach
|
||||
- Integration capabilities
|
||||
|
||||
**Developer Experience:**
|
||||
|
||||
- Learning curve
|
||||
- Documentation quality
|
||||
- Tooling ecosystem
|
||||
- Testing support
|
||||
- Debugging capabilities
|
||||
|
||||
**Operations:**
|
||||
|
||||
- Deployment complexity
|
||||
- Monitoring and observability
|
||||
- Operational overhead
|
||||
- Cloud provider support
|
||||
- Container/K8s compatibility
|
||||
|
||||
**Ecosystem:**
|
||||
|
||||
- Available libraries and plugins
|
||||
- Third-party integrations
|
||||
- Commercial support options
|
||||
- Training and educational resources
|
||||
|
||||
**Community and Adoption:**
|
||||
|
||||
- GitHub stars/contributors (if applicable)
|
||||
- Production usage examples
|
||||
- Case studies from similar use cases
|
||||
- Community support channels
|
||||
- Job market demand
|
||||
|
||||
**Costs:**
|
||||
|
||||
- Licensing model
|
||||
- Hosting/infrastructure costs
|
||||
- Support costs
|
||||
- Training costs
|
||||
- Total cost of ownership estimate
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
<template-output>tech*profile*{{option_number}}</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Comparative Analysis">
|
||||
<action>Create structured comparison across all options</action>
|
||||
|
||||
**Create comparison matrices:**
|
||||
|
||||
<action>Generate comparison table with key dimensions:</action>
|
||||
|
||||
**Comparison Dimensions:**
|
||||
|
||||
1. **Meets Requirements** - How well does each meet functional requirements?
|
||||
2. **Performance** - Speed, latency, throughput benchmarks
|
||||
3. **Scalability** - Horizontal/vertical scaling capabilities
|
||||
4. **Complexity** - Learning curve and operational complexity
|
||||
5. **Ecosystem** - Maturity, community, libraries, tools
|
||||
6. **Cost** - Total cost of ownership
|
||||
7. **Risk** - Maturity, vendor lock-in, abandonment risk
|
||||
8. **Developer Experience** - Productivity, debugging, testing
|
||||
9. **Operations** - Deployment, monitoring, maintenance
|
||||
10. **Future-Proofing** - Roadmap, innovation, sustainability
|
||||
|
||||
<action>Rate each option on relevant dimensions (High/Medium/Low or 1-5 scale)</action>
|
||||
|
||||
<template-output>comparative_analysis</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Trade-offs and Decision Factors">
|
||||
<action>Analyze trade-offs between options</action>
|
||||
|
||||
**Identify key trade-offs:**
|
||||
|
||||
For each pair of leading options, identify trade-offs:
|
||||
|
||||
- What do you gain by choosing Option A over Option B?
|
||||
- What do you sacrifice?
|
||||
- Under what conditions would you choose one vs the other?
|
||||
|
||||
**Decision factors by priority:**
|
||||
|
||||
<ask>What are your top 3 decision factors?
|
||||
|
||||
Examples:
|
||||
|
||||
- Time to market
|
||||
- Performance
|
||||
- Developer productivity
|
||||
- Operational simplicity
|
||||
- Cost efficiency
|
||||
- Future flexibility
|
||||
- Team expertise match
|
||||
- Community and support</ask>
|
||||
|
||||
<template-output>decision_priorities</template-output>
|
||||
|
||||
<action>Weight the comparison analysis by decision priorities</action>
|
||||
|
||||
<template-output>weighted_analysis</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Use Case Fit Analysis">
|
||||
<action>Evaluate fit for specific use case</action>
|
||||
|
||||
**Match technologies to your specific use case:**
|
||||
|
||||
Based on:
|
||||
|
||||
- Your functional and non-functional requirements
|
||||
- Your constraints (team, budget, timeline)
|
||||
- Your context (greenfield vs brownfield)
|
||||
- Your decision priorities
|
||||
|
||||
Analyze which option(s) best fit your specific scenario.
|
||||
|
||||
<ask>Are there any specific concerns or "must-haves" that would immediately eliminate any options?</ask>
|
||||
|
||||
<template-output>use_case_fit</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Real-World Evidence">
|
||||
<action>Gather production experience evidence</action>
|
||||
|
||||
**Search for real-world experiences:**
|
||||
|
||||
For top 2-3 candidates:
|
||||
|
||||
- Production war stories and lessons learned
|
||||
- Known issues and gotchas
|
||||
- Migration experiences (if replacing existing tech)
|
||||
- Performance benchmarks from real deployments
|
||||
- Team scaling experiences
|
||||
- Reddit/HackerNews discussions
|
||||
- Conference talks and blog posts from practitioners
|
||||
|
||||
<template-output>real_world_evidence</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Architecture Pattern Research" optional="true">
|
||||
<action>If researching architecture patterns, provide pattern analysis</action>
|
||||
|
||||
<ask>Are you researching architecture patterns (microservices, event-driven, etc.)?</ask>
|
||||
|
||||
<check if="yes">
|
||||
|
||||
Research and document:
|
||||
|
||||
**Pattern Overview:**
|
||||
|
||||
- Core principles and concepts
|
||||
- When to use vs when not to use
|
||||
- Prerequisites and foundations
|
||||
|
||||
**Implementation Considerations:**
|
||||
|
||||
- Technology choices for the pattern
|
||||
- Reference architectures
|
||||
- Common pitfalls and anti-patterns
|
||||
- Migration path from current state
|
||||
|
||||
**Trade-offs:**
|
||||
|
||||
- Benefits and drawbacks
|
||||
- Complexity vs benefits analysis
|
||||
- Team skill requirements
|
||||
- Operational overhead
|
||||
|
||||
<template-output>architecture_pattern_analysis</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Recommendations and Decision Framework">
|
||||
<action>Synthesize research into clear recommendations</action>
|
||||
|
||||
**Generate recommendations:**
|
||||
|
||||
**Top Recommendation:**
|
||||
|
||||
- Primary technology choice with rationale
|
||||
- Why it best fits your requirements and constraints
|
||||
- Key benefits for your use case
|
||||
- Risks and mitigation strategies
|
||||
|
||||
**Alternative Options:**
|
||||
|
||||
- Second and third choices
|
||||
- When you might choose them instead
|
||||
- Scenarios where they would be better
|
||||
|
||||
**Implementation Roadmap:**
|
||||
|
||||
- Proof of concept approach
|
||||
- Key decisions to make during implementation
|
||||
- Migration path (if applicable)
|
||||
- Success criteria and validation approach
|
||||
|
||||
**Risk Mitigation:**
|
||||
|
||||
- Identified risks and mitigation plans
|
||||
- Contingency options if primary choice doesn't work
|
||||
- Exit strategy considerations
|
||||
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
<template-output>recommendations</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Decision Documentation">
|
||||
<action>Create architecture decision record (ADR) template</action>
|
||||
|
||||
**Generate Architecture Decision Record:**
|
||||
|
||||
Create ADR format documentation:
|
||||
|
||||
```markdown
|
||||
# ADR-XXX: [Decision Title]
|
||||
|
||||
## Status
|
||||
|
||||
[Proposed | Accepted | Superseded]
|
||||
|
||||
## Context
|
||||
|
||||
[Technical context and problem statement]
|
||||
|
||||
## Decision Drivers
|
||||
|
||||
[Key factors influencing the decision]
|
||||
|
||||
## Considered Options
|
||||
|
||||
[Technologies/approaches evaluated]
|
||||
|
||||
## Decision
|
||||
|
||||
[Chosen option and rationale]
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive:**
|
||||
|
||||
- [Benefits of this choice]
|
||||
|
||||
**Negative:**
|
||||
|
||||
- [Drawbacks and risks]
|
||||
|
||||
**Neutral:**
|
||||
|
||||
- [Other impacts]
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
[Key considerations for implementation]
|
||||
|
||||
## References
|
||||
|
||||
[Links to research, benchmarks, case studies]
|
||||
```
|
||||
|
||||
<template-output>architecture_decision_record</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Finalize Technical Research Report">
|
||||
<action>Compile complete technical research report</action>
|
||||
|
||||
**Your Technical Research Report includes:**
|
||||
|
||||
1. **Executive Summary** - Key findings and recommendation
|
||||
2. **Requirements and Constraints** - What guided the research
|
||||
3. **Technology Options** - All candidates evaluated
|
||||
4. **Detailed Profiles** - Deep dive on each option
|
||||
5. **Comparative Analysis** - Side-by-side comparison
|
||||
6. **Trade-off Analysis** - Key decision factors
|
||||
7. **Real-World Evidence** - Production experiences
|
||||
8. **Recommendations** - Detailed recommendation with rationale
|
||||
9. **Architecture Decision Record** - Formal decision documentation
|
||||
10. **Next Steps** - Implementation roadmap
|
||||
|
||||
<action>Save complete report to {default_output_file}</action>
|
||||
|
||||
<ask>Would you like to:
|
||||
|
||||
1. Deep dive into specific technology
|
||||
2. Research implementation patterns for chosen technology
|
||||
3. Generate proof-of-concept plan
|
||||
4. Create deep research prompt for ongoing investigation
|
||||
5. Exit workflow
|
||||
|
||||
Select option (1-5):</ask>
|
||||
|
||||
<check if="option 4">
|
||||
<action>LOAD: {installed_path}/instructions-deep-prompt.md</action>
|
||||
<action>Pre-populate with technical research context</action>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="FINAL" goal="Update status file on completion" tag="workflow-status">
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "research"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["research"] = "{output_folder}/bmm-research-technical-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Technical Research Complete**
|
||||
|
||||
**Research Report:**
|
||||
|
||||
- Technical research report generated and saved to {output_folder}/bmm-research-technical-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: research marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** Review findings with architecture team, or run additional analysis workflows
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Review technical research findings
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,94 @@
|
||||
# Deep Research Prompt
|
||||
|
||||
**Generated:** {{date}}
|
||||
**Created by:** {{user_name}}
|
||||
**Target Platform:** {{target_platform}}
|
||||
|
||||
---
|
||||
|
||||
## Research Prompt (Ready to Use)
|
||||
|
||||
### Research Question
|
||||
|
||||
{{research_topic}}
|
||||
|
||||
### Research Goal and Context
|
||||
|
||||
**Objective:** {{research_goal}}
|
||||
|
||||
**Context:**
|
||||
{{research_persona}}
|
||||
|
||||
### Scope and Boundaries
|
||||
|
||||
**Temporal Scope:** {{temporal_scope}}
|
||||
|
||||
**Geographic Scope:** {{geographic_scope}}
|
||||
|
||||
**Thematic Focus:**
|
||||
{{thematic_boundaries}}
|
||||
|
||||
### Information Requirements
|
||||
|
||||
**Types of Information Needed:**
|
||||
{{information_types}}
|
||||
|
||||
**Preferred Sources:**
|
||||
{{preferred_sources}}
|
||||
|
||||
### Output Structure
|
||||
|
||||
**Format:** {{output_format}}
|
||||
|
||||
**Required Sections:**
|
||||
{{key_sections}}
|
||||
|
||||
**Depth Level:** {{depth_level}}
|
||||
|
||||
### Research Methodology
|
||||
|
||||
**Keywords and Technical Terms:**
|
||||
{{research_keywords}}
|
||||
|
||||
**Special Requirements:**
|
||||
{{special_requirements}}
|
||||
|
||||
**Validation Criteria:**
|
||||
{{validation_criteria}}
|
||||
|
||||
### Follow-up Strategy
|
||||
|
||||
{{follow_up_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## Complete Research Prompt (Copy and Paste)
|
||||
|
||||
```
|
||||
{{deep_research_prompt}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Usage Tips
|
||||
|
||||
{{platform_tips}}
|
||||
|
||||
---
|
||||
|
||||
## Research Execution Checklist
|
||||
|
||||
{{execution_checklist}}
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Workflow:** BMad Research Workflow - Deep Research Prompt Generator v2.0
|
||||
**Generated:** {{date}}
|
||||
**Research Type:** Deep Research Prompt
|
||||
**Platform:** {{target_platform}}
|
||||
|
||||
---
|
||||
|
||||
_This research prompt was generated using the BMad Method Research Workflow, incorporating best practices from ChatGPT Deep Research, Gemini Deep Research, Grok DeepSearch, and Claude Projects (2025)._
|
||||
347
bmad/bmm/workflows/1-analysis/research/template-market.md
Normal file
347
bmad/bmm/workflows/1-analysis/research/template-market.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# Market Research Report: {{product_name}}
|
||||
|
||||
**Date:** {{date}}
|
||||
**Prepared by:** {{user_name}}
|
||||
**Research Depth:** {{research_depth}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
### Key Market Metrics
|
||||
|
||||
- **Total Addressable Market (TAM):** {{tam_calculation}}
|
||||
- **Serviceable Addressable Market (SAM):** {{sam_calculation}}
|
||||
- **Serviceable Obtainable Market (SOM):** {{som_scenarios}}
|
||||
|
||||
### Critical Success Factors
|
||||
|
||||
{{key_success_factors}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Research Objectives and Methodology
|
||||
|
||||
### Research Objectives
|
||||
|
||||
{{research_objectives}}
|
||||
|
||||
### Scope and Boundaries
|
||||
|
||||
- **Product/Service:** {{product_description}}
|
||||
- **Market Definition:** {{market_definition}}
|
||||
- **Geographic Scope:** {{geographic_scope}}
|
||||
- **Customer Segments:** {{segment_boundaries}}
|
||||
|
||||
### Research Methodology
|
||||
|
||||
{{research_methodology}}
|
||||
|
||||
### Data Sources
|
||||
|
||||
{{source_credibility_notes}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Overview
|
||||
|
||||
### Market Definition
|
||||
|
||||
{{market_definition}}
|
||||
|
||||
### Market Size and Growth
|
||||
|
||||
#### Total Addressable Market (TAM)
|
||||
|
||||
**Methodology:** {{tam_methodology}}
|
||||
|
||||
{{tam_calculation}}
|
||||
|
||||
#### Serviceable Addressable Market (SAM)
|
||||
|
||||
{{sam_calculation}}
|
||||
|
||||
#### Serviceable Obtainable Market (SOM)
|
||||
|
||||
{{som_scenarios}}
|
||||
|
||||
### Market Intelligence Summary
|
||||
|
||||
{{market_intelligence_raw}}
|
||||
|
||||
### Key Data Points
|
||||
|
||||
{{key_data_points}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Market Trends and Drivers
|
||||
|
||||
### Key Market Trends
|
||||
|
||||
{{market_trends}}
|
||||
|
||||
### Growth Drivers
|
||||
|
||||
{{growth_drivers}}
|
||||
|
||||
### Market Inhibitors
|
||||
|
||||
{{market_inhibitors}}
|
||||
|
||||
### Future Outlook
|
||||
|
||||
{{future_outlook}}
|
||||
|
||||
---
|
||||
|
||||
## 4. Customer Analysis
|
||||
|
||||
### Target Customer Segments
|
||||
|
||||
{{#segment_profile_1}}
|
||||
|
||||
#### Segment 1
|
||||
|
||||
{{segment_profile_1}}
|
||||
{{/segment_profile_1}}
|
||||
|
||||
{{#segment_profile_2}}
|
||||
|
||||
#### Segment 2
|
||||
|
||||
{{segment_profile_2}}
|
||||
{{/segment_profile_2}}
|
||||
|
||||
{{#segment_profile_3}}
|
||||
|
||||
#### Segment 3
|
||||
|
||||
{{segment_profile_3}}
|
||||
{{/segment_profile_3}}
|
||||
|
||||
{{#segment_profile_4}}
|
||||
|
||||
#### Segment 4
|
||||
|
||||
{{segment_profile_4}}
|
||||
{{/segment_profile_4}}
|
||||
|
||||
{{#segment_profile_5}}
|
||||
|
||||
#### Segment 5
|
||||
|
||||
{{segment_profile_5}}
|
||||
{{/segment_profile_5}}
|
||||
|
||||
### Jobs-to-be-Done Analysis
|
||||
|
||||
{{jobs_to_be_done}}
|
||||
|
||||
### Pricing Analysis and Willingness to Pay
|
||||
|
||||
{{pricing_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## 5. Competitive Landscape
|
||||
|
||||
### Market Structure
|
||||
|
||||
{{market_structure}}
|
||||
|
||||
### Competitor Analysis
|
||||
|
||||
{{#competitor_analysis_1}}
|
||||
|
||||
#### Competitor 1
|
||||
|
||||
{{competitor_analysis_1}}
|
||||
{{/competitor_analysis_1}}
|
||||
|
||||
{{#competitor_analysis_2}}
|
||||
|
||||
#### Competitor 2
|
||||
|
||||
{{competitor_analysis_2}}
|
||||
{{/competitor_analysis_2}}
|
||||
|
||||
{{#competitor_analysis_3}}
|
||||
|
||||
#### Competitor 3
|
||||
|
||||
{{competitor_analysis_3}}
|
||||
{{/competitor_analysis_3}}
|
||||
|
||||
{{#competitor_analysis_4}}
|
||||
|
||||
#### Competitor 4
|
||||
|
||||
{{competitor_analysis_4}}
|
||||
{{/competitor_analysis_4}}
|
||||
|
||||
{{#competitor_analysis_5}}
|
||||
|
||||
#### Competitor 5
|
||||
|
||||
{{competitor_analysis_5}}
|
||||
{{/competitor_analysis_5}}
|
||||
|
||||
### Competitive Positioning
|
||||
|
||||
{{competitive_positioning}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Industry Analysis
|
||||
|
||||
### Porter's Five Forces Assessment
|
||||
|
||||
{{porters_five_forces}}
|
||||
|
||||
### Technology Adoption Lifecycle
|
||||
|
||||
{{adoption_lifecycle}}
|
||||
|
||||
### Value Chain Analysis
|
||||
|
||||
{{value_chain_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## 7. Market Opportunities
|
||||
|
||||
### Identified Opportunities
|
||||
|
||||
{{market_opportunities}}
|
||||
|
||||
### Opportunity Prioritization Matrix
|
||||
|
||||
{{opportunity_prioritization}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Strategic Recommendations
|
||||
|
||||
### Go-to-Market Strategy
|
||||
|
||||
{{gtm_strategy}}
|
||||
|
||||
#### Positioning Strategy
|
||||
|
||||
{{positioning_strategy}}
|
||||
|
||||
#### Target Segment Sequencing
|
||||
|
||||
{{segment_sequencing}}
|
||||
|
||||
#### Channel Strategy
|
||||
|
||||
{{channel_strategy}}
|
||||
|
||||
#### Pricing Strategy
|
||||
|
||||
{{pricing_recommendations}}
|
||||
|
||||
### Implementation Roadmap
|
||||
|
||||
{{implementation_roadmap}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Risk Assessment
|
||||
|
||||
### Risk Analysis
|
||||
|
||||
{{risk_assessment}}
|
||||
|
||||
### Mitigation Strategies
|
||||
|
||||
{{mitigation_strategies}}
|
||||
|
||||
---
|
||||
|
||||
## 10. Financial Projections
|
||||
|
||||
{{#financial_projections}}
|
||||
{{financial_projections}}
|
||||
{{/financial_projections}}
|
||||
|
||||
---
|
||||
|
||||
## Appendices
|
||||
|
||||
### Appendix A: Data Sources and References
|
||||
|
||||
{{data_sources}}
|
||||
|
||||
### Appendix B: Detailed Calculations
|
||||
|
||||
{{detailed_calculations}}
|
||||
|
||||
### Appendix C: Additional Analysis
|
||||
|
||||
{{#appendices}}
|
||||
{{appendices}}
|
||||
{{/appendices}}
|
||||
|
||||
### Appendix D: Glossary of Terms
|
||||
|
||||
{{glossary}}
|
||||
|
||||
---
|
||||
|
||||
## References and Sources
|
||||
|
||||
**CRITICAL: All data in this report must be verifiable through the sources listed below**
|
||||
|
||||
### Market Size and Growth Data Sources
|
||||
|
||||
{{sources_market_size}}
|
||||
|
||||
### Competitive Intelligence Sources
|
||||
|
||||
{{sources_competitive}}
|
||||
|
||||
### Customer Research Sources
|
||||
|
||||
{{sources_customer}}
|
||||
|
||||
### Industry Trends and Analysis Sources
|
||||
|
||||
{{sources_trends}}
|
||||
|
||||
### Additional References
|
||||
|
||||
{{sources_additional}}
|
||||
|
||||
### Source Quality Assessment
|
||||
|
||||
- **High Credibility Sources (2+ corroborating):** {{high_confidence_count}} claims
|
||||
- **Medium Credibility (single source):** {{medium_confidence_count}} claims
|
||||
- **Low Credibility (needs verification):** {{low_confidence_count}} claims
|
||||
|
||||
**Note:** Any claim marked [Low Confidence] or [Single source] should be independently verified before making critical business decisions.
|
||||
|
||||
---
|
||||
|
||||
## Document Information
|
||||
|
||||
**Workflow:** BMad Market Research Workflow v1.0
|
||||
**Generated:** {{date}}
|
||||
**Next Review:** {{next_review_date}}
|
||||
**Classification:** {{classification}}
|
||||
|
||||
### Research Quality Metrics
|
||||
|
||||
- **Data Freshness:** Current as of {{date}}
|
||||
- **Source Reliability:** {{source_reliability_score}}
|
||||
- **Confidence Level:** {{confidence_level}}
|
||||
- **Total Sources Cited:** {{total_sources}}
|
||||
- **Web Searches Conducted:** {{search_count}}
|
||||
|
||||
---
|
||||
|
||||
_This market research report was generated using the BMad Method Market Research Workflow, combining systematic analysis frameworks with real-time market intelligence gathering. All factual claims are backed by cited sources with verification dates._
|
||||
245
bmad/bmm/workflows/1-analysis/research/template-technical.md
Normal file
245
bmad/bmm/workflows/1-analysis/research/template-technical.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# Technical Research Report: {{technical_question}}
|
||||
|
||||
**Date:** {{date}}
|
||||
**Prepared by:** {{user_name}}
|
||||
**Project Context:** {{project_context}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{recommendations}}
|
||||
|
||||
### Key Recommendation
|
||||
|
||||
**Primary Choice:** [Technology/Pattern Name]
|
||||
|
||||
**Rationale:** [2-3 sentence summary]
|
||||
|
||||
**Key Benefits:**
|
||||
|
||||
- [Benefit 1]
|
||||
- [Benefit 2]
|
||||
- [Benefit 3]
|
||||
|
||||
---
|
||||
|
||||
## 1. Research Objectives
|
||||
|
||||
### Technical Question
|
||||
|
||||
{{technical_question}}
|
||||
|
||||
### Project Context
|
||||
|
||||
{{project_context}}
|
||||
|
||||
### Requirements and Constraints
|
||||
|
||||
#### Functional Requirements
|
||||
|
||||
{{functional_requirements}}
|
||||
|
||||
#### Non-Functional Requirements
|
||||
|
||||
{{non_functional_requirements}}
|
||||
|
||||
#### Technical Constraints
|
||||
|
||||
{{technical_constraints}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Technology Options Evaluated
|
||||
|
||||
{{technology_options}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Detailed Technology Profiles
|
||||
|
||||
{{#tech_profile_1}}
|
||||
|
||||
### Option 1: [Technology Name]
|
||||
|
||||
{{tech_profile_1}}
|
||||
{{/tech_profile_1}}
|
||||
|
||||
{{#tech_profile_2}}
|
||||
|
||||
### Option 2: [Technology Name]
|
||||
|
||||
{{tech_profile_2}}
|
||||
{{/tech_profile_2}}
|
||||
|
||||
{{#tech_profile_3}}
|
||||
|
||||
### Option 3: [Technology Name]
|
||||
|
||||
{{tech_profile_3}}
|
||||
{{/tech_profile_3}}
|
||||
|
||||
{{#tech_profile_4}}
|
||||
|
||||
### Option 4: [Technology Name]
|
||||
|
||||
{{tech_profile_4}}
|
||||
{{/tech_profile_4}}
|
||||
|
||||
{{#tech_profile_5}}
|
||||
|
||||
### Option 5: [Technology Name]
|
||||
|
||||
{{tech_profile_5}}
|
||||
{{/tech_profile_5}}
|
||||
|
||||
---
|
||||
|
||||
## 4. Comparative Analysis
|
||||
|
||||
{{comparative_analysis}}
|
||||
|
||||
### Weighted Analysis
|
||||
|
||||
**Decision Priorities:**
|
||||
{{decision_priorities}}
|
||||
|
||||
{{weighted_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## 5. Trade-offs and Decision Factors
|
||||
|
||||
{{use_case_fit}}
|
||||
|
||||
### Key Trade-offs
|
||||
|
||||
[Comparison of major trade-offs between top options]
|
||||
|
||||
---
|
||||
|
||||
## 6. Real-World Evidence
|
||||
|
||||
{{real_world_evidence}}
|
||||
|
||||
---
|
||||
|
||||
## 7. Architecture Pattern Analysis
|
||||
|
||||
{{#architecture_pattern_analysis}}
|
||||
{{architecture_pattern_analysis}}
|
||||
{{/architecture_pattern_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Recommendations
|
||||
|
||||
{{recommendations}}
|
||||
|
||||
### Implementation Roadmap
|
||||
|
||||
1. **Proof of Concept Phase**
|
||||
- [POC objectives and timeline]
|
||||
|
||||
2. **Key Implementation Decisions**
|
||||
- [Critical decisions to make during implementation]
|
||||
|
||||
3. **Migration Path** (if applicable)
|
||||
- [Migration approach from current state]
|
||||
|
||||
4. **Success Criteria**
|
||||
- [How to validate the decision]
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
{{risk_mitigation}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Architecture Decision Record (ADR)
|
||||
|
||||
{{architecture_decision_record}}
|
||||
|
||||
---
|
||||
|
||||
## 10. References and Resources
|
||||
|
||||
### Documentation
|
||||
|
||||
- [Links to official documentation]
|
||||
|
||||
### Benchmarks and Case Studies
|
||||
|
||||
- [Links to benchmarks and real-world case studies]
|
||||
|
||||
### Community Resources
|
||||
|
||||
- [Links to communities, forums, discussions]
|
||||
|
||||
### Additional Reading
|
||||
|
||||
- [Links to relevant articles, papers, talks]
|
||||
|
||||
---
|
||||
|
||||
## Appendices
|
||||
|
||||
### Appendix A: Detailed Comparison Matrix
|
||||
|
||||
[Full comparison table with all evaluated dimensions]
|
||||
|
||||
### Appendix B: Proof of Concept Plan
|
||||
|
||||
[Detailed POC plan if needed]
|
||||
|
||||
### Appendix C: Cost Analysis
|
||||
|
||||
[TCO analysis if performed]
|
||||
|
||||
---
|
||||
|
||||
## References and Sources
|
||||
|
||||
**CRITICAL: All technical claims, versions, and benchmarks must be verifiable through sources below**
|
||||
|
||||
### Official Documentation and Release Notes
|
||||
|
||||
{{sources_official_docs}}
|
||||
|
||||
### Performance Benchmarks and Comparisons
|
||||
|
||||
{{sources_benchmarks}}
|
||||
|
||||
### Community Experience and Reviews
|
||||
|
||||
{{sources_community}}
|
||||
|
||||
### Architecture Patterns and Best Practices
|
||||
|
||||
{{sources_architecture}}
|
||||
|
||||
### Additional Technical References
|
||||
|
||||
{{sources_additional}}
|
||||
|
||||
### Version Verification
|
||||
|
||||
- **Technologies Researched:** {{technology_count}}
|
||||
- **Versions Verified ({{current_year}}):** {{verified_versions_count}}
|
||||
- **Sources Requiring Update:** {{outdated_sources_count}}
|
||||
|
||||
**Note:** All version numbers were verified using current {{current_year}} sources. Versions may change - always verify latest stable release before implementation.
|
||||
|
||||
---
|
||||
|
||||
## Document Information
|
||||
|
||||
**Workflow:** BMad Research Workflow - Technical Research v2.0
|
||||
**Generated:** {{date}}
|
||||
**Research Type:** Technical/Architecture Research
|
||||
**Next Review:** [Date for review/update]
|
||||
**Total Sources Cited:** {{total_sources}}
|
||||
|
||||
---
|
||||
|
||||
_This technical research report was generated using the BMad Method Research Workflow, combining systematic technology evaluation frameworks with real-time research and analysis. All version numbers and technical claims are backed by current {{current_year}} sources._
|
||||
44
bmad/bmm/workflows/1-analysis/research/workflow.yaml
Normal file
44
bmad/bmm/workflows/1-analysis/research/workflow.yaml
Normal file
@@ -0,0 +1,44 @@
|
||||
# Research Workflow - Multi-Type Research System
|
||||
name: research
|
||||
description: "Adaptive research workflow supporting multiple research types: market research, deep research prompt generation, technical/architecture evaluation, competitive intelligence, user research, and domain analysis"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
current_year: system-generated
|
||||
current_month: system-generated
|
||||
|
||||
# Research behavior - WEB RESEARCH IS DEFAULT
|
||||
enable_web_research: true
|
||||
|
||||
# Source tracking and verification - CRITICAL FOR ACCURACY
|
||||
require_citations: true
|
||||
require_source_urls: true
|
||||
minimum_sources_per_claim: 2
|
||||
fact_check_critical_data: true
|
||||
|
||||
# Workflow components - ROUTER PATTERN
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/research"
|
||||
instructions: "{installed_path}/instructions-router.md" # Router loads specific instruction sets
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Research type specific instructions (loaded by router)
|
||||
instructions_market: "{installed_path}/instructions-market.md"
|
||||
instructions_deep_prompt: "{installed_path}/instructions-deep-prompt.md"
|
||||
instructions_technical: "{installed_path}/instructions-technical.md"
|
||||
|
||||
# Templates (loaded based on research type)
|
||||
template_market: "{installed_path}/template-market.md"
|
||||
template_deep_prompt: "{installed_path}/template-deep-prompt.md"
|
||||
template_technical: "{installed_path}/template-technical.md"
|
||||
|
||||
# Output configuration (dynamic based on research type selected in router)
|
||||
default_output_file: "{output_folder}/research-{{research_type}}-{{date}}.md"
|
||||
|
||||
standalone: true
|
||||
258
bmad/bmm/workflows/2-plan-workflows/README.md
Normal file
258
bmad/bmm/workflows/2-plan-workflows/README.md
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Project Planning Workflow (Phase 2)
|
||||
|
||||
The Phase 2 Planning workflow is **scale-adaptive**, meaning it automatically determines the right level of planning documentation based on project complexity (Levels 0-4). This ensures planning overhead matches project value—from minimal tech specs for bug fixes to comprehensive PRDs for enterprise platforms.
|
||||
|
||||
## Scale-Adaptive Flow (Levels 0-4)
|
||||
|
||||
The workflow routes to different planning approaches based on project level:
|
||||
|
||||
### Level 0 - Single File Change / Bug Fix
|
||||
|
||||
**Planning:** Tech-spec only (lightweight implementation plan)
|
||||
**Output:** `tech-spec.md` with single story
|
||||
**Next Phase:** Direct to implementation (Phase 4)
|
||||
|
||||
### Level 1 - Small Feature (1-3 files, 2-5 stories)
|
||||
|
||||
**Planning:** Tech-spec only (implementation-focused)
|
||||
**Output:** `tech-spec.md` with epic breakdown and stories
|
||||
**Next Phase:** Direct to implementation (Phase 4)
|
||||
|
||||
### Level 2 - Feature Set / Small Project (5-15 stories, 1-2 epics)
|
||||
|
||||
**Planning:** PRD (product-focused) + Tech-spec (technical planning)
|
||||
**Output:** `PRD.md`, `epics.md`, `tech-spec.md`
|
||||
**Next Phase:** Tech-spec workflow (lightweight solutioning), then implementation (Phase 4)
|
||||
**Note:** Level 2 uses tech-spec instead of full architecture to keep planning lightweight
|
||||
|
||||
### Level 3 - Medium Project (15-40 stories, 2-5 epics)
|
||||
|
||||
**Planning:** PRD (strategic product document)
|
||||
**Output:** `PRD.md`, `epics.md`
|
||||
**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
|
||||
|
||||
### Level 4 - Large/Enterprise Project (40-100+ stories, 5-10 epics)
|
||||
|
||||
**Planning:** PRD (comprehensive product specification)
|
||||
**Output:** `PRD.md`, `epics.md`
|
||||
**Next Phase:** create-architecture workflow (Phase 3), then implementation (Phase 4)
|
||||
|
||||
**Critical Distinction:**
|
||||
|
||||
- **Levels 0-1:** No PRD, tech-spec only
|
||||
- **Level 2:** PRD + tech-spec (skips full architecture)
|
||||
- **Levels 3-4:** PRD → full create-architecture workflow
|
||||
|
||||
Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Scale-adaptive planning** - Automatically determines output based on project complexity
|
||||
- **Intelligent routing** - Uses router system to load appropriate instruction sets
|
||||
- **Continuation support** - Can resume from previous sessions and handle incremental work
|
||||
- **Multi-level outputs** - Supports 5 project levels (0-4) with appropriate artifacts
|
||||
- **Input integration** - Leverages product briefs and market research when available
|
||||
- **Template-driven** - Uses validated templates for consistent output structure
|
||||
|
||||
### Configuration
|
||||
|
||||
The workflow adapts automatically based on project assessment, but key configuration options include:
|
||||
|
||||
- **scale_parameters**: Defines story/epic counts for each project level
|
||||
- **output_folder**: Where all generated documents are stored
|
||||
- **project_name**: Used in document names and templates
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
2-plan-workflows/
|
||||
├── README.md # Overview and usage details
|
||||
├── checklist.md # Shared validation criteria
|
||||
├── prd/
|
||||
│ ├── epics-template.md # Epic breakdown template
|
||||
│ ├── instructions.md # Level 2-4 PRD instructions
|
||||
│ ├── prd-template.md # Product Requirements Document template
|
||||
│ └── workflow.yaml
|
||||
├── tech-spec/
|
||||
│ ├── epics-template.md # Epic-to-story handoff template
|
||||
│ ├── instructions-level0-story.md
|
||||
│ ├── instructions-level1-stories.md
|
||||
│ ├── instructions.md # Level 0-1 tech-spec instructions
|
||||
│ ├── tech-spec-template.md # Technical Specification template
|
||||
│ ├── user-story-template.md # Story template for Level 0/1
|
||||
│ └── workflow.yaml
|
||||
├── gdd/
|
||||
│ ├── instructions-gdd.md # Game Design Document instructions
|
||||
│ ├── gdd-template.md # GDD template
|
||||
│ ├── game-types.csv # Genre catalog
|
||||
│ ├── game-types/ # Genre-specific templates
|
||||
│ └── workflow.yaml
|
||||
├── narrative/
|
||||
│ ├── instructions-narrative.md # Narrative design instructions
|
||||
│ ├── narrative-template.md # Narrative planning template
|
||||
│ └── workflow.yaml
|
||||
└── create-ux-design/
|
||||
├── instructions.md # UX design instructions
|
||||
├── ux-design-template.md # UX design template
|
||||
├── checklist.md # UX design validation checklist
|
||||
└── workflow.yaml
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Assessment and Routing (Steps 1-5)
|
||||
|
||||
- **Project Analysis**: Determines project type (greenfield/brownfield/legacy)
|
||||
- **Scope Assessment**: Classifies into 5 levels based on complexity
|
||||
- **Document Discovery**: Identifies existing inputs and documentation
|
||||
- **Workflow Routing**: Loads appropriate instruction set based on level
|
||||
- **Continuation Handling**: Resumes from previous work when applicable
|
||||
|
||||
### Phase 2: Level-Specific Planning (Steps vary by level)
|
||||
|
||||
**Level 0 (Single File Change / Bug Fix)**:
|
||||
|
||||
- Tech-spec only workflow
|
||||
- Single story implementation plan
|
||||
- Direct to Phase 4 (implementation)
|
||||
|
||||
**Level 1 (Small Feature)**:
|
||||
|
||||
- Tech-spec only workflow
|
||||
- Epic breakdown with 2-5 stories
|
||||
- Direct to Phase 4 (implementation)
|
||||
|
||||
**Level 2 (Feature Set / Small Project)**:
|
||||
|
||||
- PRD workflow (strategic product document)
|
||||
- Generates `PRD.md` and `epics.md`
|
||||
- Then runs tech-spec workflow (lightweight solutioning)
|
||||
- Then to Phase 4 (implementation)
|
||||
|
||||
**Level 3-4 (Medium to Enterprise Projects)**:
|
||||
|
||||
- PRD workflow (comprehensive product specification)
|
||||
- Generates `PRD.md` and `epics.md`
|
||||
- Hands off to Phase 3 (create-architecture workflow)
|
||||
- Full architecture design before implementation
|
||||
|
||||
### Phase 3: Validation and Handoff (Final steps)
|
||||
|
||||
- **Document Review**: Validates outputs against checklists
|
||||
- **Architect Preparation**: For Level 3-4, prepares handoff materials
|
||||
- **Next Steps**: Provides guidance for development phase
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: PRD.md (except Level 0), tech-spec.md, bmm-workflow-status.md
|
||||
- **Supporting files**: epics.md (Level 2-4), PRD-validation-report.md (if validation run)
|
||||
|
||||
### Output Structure by Level
|
||||
|
||||
**Level 0 - Tech Spec Only**:
|
||||
|
||||
- `tech-spec.md` - Single story implementation plan
|
||||
- Direct to implementation
|
||||
|
||||
**Level 1 - Tech Spec with Epic Breakdown**:
|
||||
|
||||
- `tech-spec.md` - Epic breakdown with 2-5 stories
|
||||
- Direct to implementation
|
||||
|
||||
**Level 2 - PRD + Tech Spec**:
|
||||
|
||||
- `PRD.md` - Strategic product document (goals, requirements, user journeys, UX principles, UI goals, epic list, scope)
|
||||
- `epics.md` - Tactical implementation roadmap (detailed story breakdown)
|
||||
- `tech-spec.md` - Lightweight technical planning (generated after PRD)
|
||||
- Then to implementation
|
||||
|
||||
**Level 3-4 - PRD + Full Architecture**:
|
||||
|
||||
- `PRD.md` - Comprehensive product specification
|
||||
- `epics.md` - Complete epic/story breakdown
|
||||
- Hands off to create-architecture workflow (Phase 3)
|
||||
- `architecture.md` - Generated by architect workflow
|
||||
- Then to implementation
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Input Documents**: Product brief and/or market research (recommended but not required)
|
||||
- **Project Configuration**: Valid config.yaml with project_name and output_folder
|
||||
- **Assessment Readiness**: Clear understanding of project scope and objectives
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Gather Context**: Collect any existing product briefs, market research, or requirements
|
||||
2. **Define Scope**: Have a clear sense of project boundaries and complexity
|
||||
3. **Prepare Stakeholders**: Ensure key stakeholders are available for input if needed
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Be Honest About Scope**: Accurate assessment ensures appropriate planning depth
|
||||
2. **Leverage Existing Work**: Reference previous documents and avoid duplication
|
||||
3. **Think Incrementally**: Remember that planning can evolve - start with what you know
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Validate Against Checklist**: Use included validation criteria to ensure completeness
|
||||
2. **Share with Stakeholders**: Distribute appropriate documents to relevant team members
|
||||
3. **Prepare for Architecture**: For Level 3-4 projects, ensure architect has complete context
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Workflow creates wrong level of documentation
|
||||
|
||||
- **Solution**: Review project assessment and restart with correct scope classification
|
||||
- **Check**: Verify the bmm-workflow-status.md reflects actual project complexity
|
||||
|
||||
**Issue**: Missing input documents cause incomplete planning
|
||||
|
||||
- **Solution**: Gather recommended inputs or proceed with manual context gathering
|
||||
- **Check**: Ensure critical business context is captured even without formal documents
|
||||
|
||||
**Issue**: Continuation from previous session fails
|
||||
|
||||
- **Solution**: Check for existing bmm-workflow-status.md and ensure output folder is correct
|
||||
- **Check**: Verify previous session completed at a valid checkpoint
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Assessment Logic**: Update instructions-router.md to adjust level classification
|
||||
2. **Adjust Templates**: Customize PRD, tech-spec, or epic templates for organizational needs
|
||||
3. **Add Validation**: Extend checklist.md with organization-specific quality criteria
|
||||
4. **Configure Outputs**: Modify workflow.yaml to change file naming or structure
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - Scale-adaptive architecture with intelligent routing
|
||||
- Multi-level project support (0-4)
|
||||
- Continuation and resumption capabilities
|
||||
- Template-driven output generation
|
||||
- Input document integration
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Consult project assessment in `bmm-workflow-status.md`
|
||||
- Check continuation status in existing output documents
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
@@ -0,0 +1,310 @@
|
||||
# Create UX Design Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate UX Design Specification is complete, collaborative, and implementation-ready.
|
||||
|
||||
**Paradigm**: Visual collaboration-driven, not template generation
|
||||
|
||||
**Expected Outputs**:
|
||||
|
||||
- ux-design-specification.md
|
||||
- ux-color-themes.html (color theme visualizer)
|
||||
- ux-design-directions.html (design mockups)
|
||||
- Optional: ux-prototype.html, ux-component-showcase.html, ai-frontend-prompt.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output Files Exist
|
||||
|
||||
- [ ] **ux-design-specification.md** created in output folder
|
||||
- [ ] **ux-color-themes.html** generated (interactive color exploration)
|
||||
- [ ] **ux-design-directions.html** generated (6-8 design mockups)
|
||||
- [ ] No unfilled {{template_variables}} in specification
|
||||
- [ ] All sections have content (not placeholder text)
|
||||
|
||||
---
|
||||
|
||||
## 2. Collaborative Process Validation
|
||||
|
||||
**The workflow should facilitate decisions WITH the user, not FOR them**
|
||||
|
||||
- [ ] **Design system chosen by user** (not auto-selected)
|
||||
- [ ] **Color theme selected from options** (user saw visualizations and chose)
|
||||
- [ ] **Design direction chosen from mockups** (user explored 6-8 options)
|
||||
- [ ] **User journey flows designed collaboratively** (options presented, user decided)
|
||||
- [ ] **UX patterns decided with user input** (not just generated)
|
||||
- [ ] **Decisions documented WITH rationale** (why each choice was made)
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Collaboration Artifacts
|
||||
|
||||
### Color Theme Visualizer
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-color-themes.html)
|
||||
- [ ] **Shows 3-4 theme options** (or documented existing brand)
|
||||
- [ ] **Each theme has complete palette** (primary, secondary, semantic colors)
|
||||
- [ ] **Live UI component examples** in each theme (buttons, forms, cards)
|
||||
- [ ] **Side-by-side comparison** enabled
|
||||
- [ ] **User's selection documented** in specification
|
||||
|
||||
### Design Direction Mockups
|
||||
|
||||
- [ ] **HTML file exists and is valid** (ux-design-directions.html)
|
||||
- [ ] **6-8 different design approaches** shown
|
||||
- [ ] **Full-screen mockups** of key screens
|
||||
- [ ] **Design philosophy labeled** for each direction (e.g., "Dense Dashboard", "Spacious Explorer")
|
||||
- [ ] **Interactive navigation** between directions
|
||||
- [ ] **Responsive preview** toggle available
|
||||
- [ ] **User's choice documented WITH reasoning** (what they liked, why it fits)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design System Foundation
|
||||
|
||||
- [ ] **Design system chosen** (or custom design decision documented)
|
||||
- [ ] **Current version identified** (if using established system)
|
||||
- [ ] **Components provided by system documented**
|
||||
- [ ] **Custom components needed identified**
|
||||
- [ ] **Decision rationale clear** (why this system for this project)
|
||||
|
||||
---
|
||||
|
||||
## 5. Core Experience Definition
|
||||
|
||||
- [ ] **Defining experience articulated** (the ONE thing that makes this app unique)
|
||||
- [ ] **Novel UX patterns identified** (if applicable)
|
||||
- [ ] **Novel patterns fully designed** (interaction model, states, feedback)
|
||||
- [ ] **Core experience principles defined** (speed, guidance, flexibility, feedback)
|
||||
|
||||
---
|
||||
|
||||
## 6. Visual Foundation
|
||||
|
||||
### Color System
|
||||
|
||||
- [ ] **Complete color palette** (primary, secondary, accent, semantic, neutrals)
|
||||
- [ ] **Semantic color usage defined** (success, warning, error, info)
|
||||
- [ ] **Color accessibility considered** (contrast ratios for text)
|
||||
- [ ] **Brand alignment** (follows existing brand or establishes new identity)
|
||||
|
||||
### Typography
|
||||
|
||||
- [ ] **Font families selected** (heading, body, monospace if needed)
|
||||
- [ ] **Type scale defined** (h1-h6, body, small, etc.)
|
||||
- [ ] **Font weights documented** (when to use each)
|
||||
- [ ] **Line heights specified** for readability
|
||||
|
||||
### Spacing & Layout
|
||||
|
||||
- [ ] **Spacing system defined** (base unit, scale)
|
||||
- [ ] **Layout grid approach** (columns, gutters)
|
||||
- [ ] **Container widths** for different breakpoints
|
||||
|
||||
---
|
||||
|
||||
## 7. Design Direction
|
||||
|
||||
- [ ] **Specific direction chosen** from mockups (not generic)
|
||||
- [ ] **Layout pattern documented** (navigation, content structure)
|
||||
- [ ] **Visual hierarchy defined** (density, emphasis, focus)
|
||||
- [ ] **Interaction patterns specified** (modal vs inline, disclosure approach)
|
||||
- [ ] **Visual style documented** (minimal, balanced, rich, maximalist)
|
||||
- [ ] **User's reasoning captured** (why this direction fits their vision)
|
||||
|
||||
---
|
||||
|
||||
## 8. User Journey Flows
|
||||
|
||||
- [ ] **All critical journeys from PRD designed** (no missing flows)
|
||||
- [ ] **Each flow has clear goal** (what user accomplishes)
|
||||
- [ ] **Flow approach chosen collaboratively** (user picked from options)
|
||||
- [ ] **Step-by-step documentation** (screens, actions, feedback)
|
||||
- [ ] **Decision points and branching** defined
|
||||
- [ ] **Error states and recovery** addressed
|
||||
- [ ] **Success states specified** (completion feedback)
|
||||
- [ ] **Mermaid diagrams or clear flow descriptions** included
|
||||
|
||||
---
|
||||
|
||||
## 9. Component Library Strategy
|
||||
|
||||
- [ ] **All required components identified** (from design system + custom)
|
||||
- [ ] **Custom components fully specified**:
|
||||
- Purpose and user-facing value
|
||||
- Content/data displayed
|
||||
- User actions available
|
||||
- All states (default, hover, active, loading, error, disabled)
|
||||
- Variants (sizes, styles, layouts)
|
||||
- Behavior on interaction
|
||||
- Accessibility considerations
|
||||
- [ ] **Design system components customization needs** documented
|
||||
|
||||
---
|
||||
|
||||
## 10. UX Pattern Consistency Rules
|
||||
|
||||
**These patterns ensure consistent UX across the entire app**
|
||||
|
||||
- [ ] **Button hierarchy defined** (primary, secondary, tertiary, destructive)
|
||||
- [ ] **Feedback patterns established** (success, error, warning, info, loading)
|
||||
- [ ] **Form patterns specified** (labels, validation, errors, help text)
|
||||
- [ ] **Modal patterns defined** (sizes, dismiss behavior, focus, stacking)
|
||||
- [ ] **Navigation patterns documented** (active state, breadcrumbs, back button)
|
||||
- [ ] **Empty state patterns** (first use, no results, cleared content)
|
||||
- [ ] **Confirmation patterns** (when to confirm destructive actions)
|
||||
- [ ] **Notification patterns** (placement, duration, stacking, priority)
|
||||
- [ ] **Search patterns** (trigger, results, filters, no results)
|
||||
- [ ] **Date/time patterns** (format, timezone, pickers)
|
||||
|
||||
**Each pattern should have:**
|
||||
|
||||
- [ ] Clear specification (how it works)
|
||||
- [ ] Usage guidance (when to use)
|
||||
- [ ] Examples (concrete implementations)
|
||||
|
||||
---
|
||||
|
||||
## 11. Responsive Design
|
||||
|
||||
- [ ] **Breakpoints defined** for target devices (mobile, tablet, desktop)
|
||||
- [ ] **Adaptation patterns documented** (how layouts change)
|
||||
- [ ] **Navigation adaptation** (how nav changes on small screens)
|
||||
- [ ] **Content organization changes** (multi-column to single, grid to list)
|
||||
- [ ] **Touch targets adequate** on mobile (minimum size specified)
|
||||
- [ ] **Responsive strategy aligned** with chosen design direction
|
||||
|
||||
---
|
||||
|
||||
## 12. Accessibility
|
||||
|
||||
- [ ] **WCAG compliance level specified** (A, AA, or AAA)
|
||||
- [ ] **Color contrast requirements** documented (ratios for text)
|
||||
- [ ] **Keyboard navigation** addressed (all interactive elements accessible)
|
||||
- [ ] **Focus indicators** specified (visible focus states)
|
||||
- [ ] **ARIA requirements** noted (roles, labels, announcements)
|
||||
- [ ] **Screen reader considerations** (meaningful labels, structure)
|
||||
- [ ] **Alt text strategy** for images
|
||||
- [ ] **Form accessibility** (label associations, error identification)
|
||||
- [ ] **Testing strategy** defined (automated tools, manual testing)
|
||||
|
||||
---
|
||||
|
||||
## 13. Coherence and Integration
|
||||
|
||||
- [ ] **Design system and custom components visually consistent**
|
||||
- [ ] **All screens follow chosen design direction**
|
||||
- [ ] **Color usage consistent with semantic meanings**
|
||||
- [ ] **Typography hierarchy clear and consistent**
|
||||
- [ ] **Similar actions handled the same way** (pattern consistency)
|
||||
- [ ] **All PRD user journeys have UX design**
|
||||
- [ ] **All entry points designed**
|
||||
- [ ] **Error and edge cases handled**
|
||||
- [ ] **Every interactive element meets accessibility requirements**
|
||||
- [ ] **All flows keyboard-navigable**
|
||||
- [ ] **Colors meet contrast requirements**
|
||||
|
||||
---
|
||||
|
||||
## 14. Cross-Workflow Alignment (Epics File Update)
|
||||
|
||||
**As UX design progresses, you discover implementation details that affect the story breakdown**
|
||||
|
||||
### Stories Discovered During UX Design
|
||||
|
||||
- [ ] **Review epics.md file** for alignment with UX design
|
||||
- [ ] **New stories identified** during UX design that weren't in epics.md:
|
||||
- [ ] Custom component build stories (if significant)
|
||||
- [ ] UX pattern implementation stories
|
||||
- [ ] Animation/transition stories
|
||||
- [ ] Responsive adaptation stories
|
||||
- [ ] Accessibility implementation stories
|
||||
- [ ] Edge case handling stories discovered during journey design
|
||||
- [ ] Onboarding/empty state stories
|
||||
- [ ] Error state handling stories
|
||||
|
||||
### Story Complexity Adjustments
|
||||
|
||||
- [ ] **Existing stories complexity reassessed** based on UX design:
|
||||
- [ ] Stories that are now more complex (UX revealed additional requirements)
|
||||
- [ ] Stories that are simpler (design system handles more than expected)
|
||||
- [ ] Stories that should be split (UX design shows multiple components/flows)
|
||||
- [ ] Stories that can be combined (UX design shows they're tightly coupled)
|
||||
|
||||
### Epic Alignment
|
||||
|
||||
- [ ] **Epic scope still accurate** after UX design
|
||||
- [ ] **New epic needed** for discovered work (if significant)
|
||||
- [ ] **Epic ordering might change** based on UX dependencies
|
||||
|
||||
### Action Items for Epics File Update
|
||||
|
||||
- [ ] **List of new stories to add** to epics.md documented
|
||||
- [ ] **Complexity adjustments noted** for existing stories
|
||||
- [ ] **Update epics.md** OR flag for architecture review first
|
||||
- [ ] **Rationale documented** for why new stories/changes are needed
|
||||
|
||||
**Note:** If significant story changes are identified, consider running architecture workflow BEFORE updating epics.md, since architecture decisions might reveal additional adjustments needed.
|
||||
|
||||
---
|
||||
|
||||
## 15. Decision Rationale
|
||||
|
||||
**Unlike template-driven workflows, this workflow should document WHY**
|
||||
|
||||
- [ ] **Design system choice has rationale** (why this fits the project)
|
||||
- [ ] **Color theme selection has reasoning** (why this emotional impact)
|
||||
- [ ] **Design direction choice explained** (what user liked, how it fits vision)
|
||||
- [ ] **User journey approaches justified** (why this flow pattern)
|
||||
- [ ] **UX pattern decisions have context** (why these patterns for this app)
|
||||
- [ ] **Responsive strategy aligned with user priorities**
|
||||
- [ ] **Accessibility level appropriate for deployment intent**
|
||||
|
||||
---
|
||||
|
||||
## 16. Implementation Readiness
|
||||
|
||||
- [ ] **Designers can create high-fidelity mockups** from this spec
|
||||
- [ ] **Developers can implement** with clear UX guidance
|
||||
- [ ] **Sufficient detail** for frontend development
|
||||
- [ ] **Component specifications actionable** (states, variants, behaviors)
|
||||
- [ ] **Flows implementable** (clear steps, decision logic, error handling)
|
||||
- [ ] **Visual foundation complete** (colors, typography, spacing all defined)
|
||||
- [ ] **Pattern consistency enforceable** (clear rules for implementation)
|
||||
|
||||
---
|
||||
|
||||
## 17. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No visual collaboration** (color themes or design mockups not generated)
|
||||
- [ ] ❌ **User not involved in decisions** (auto-generated without collaboration)
|
||||
- [ ] ❌ **No design direction chosen** (missing key visual decisions)
|
||||
- [ ] ❌ **No user journey designs** (critical flows not documented)
|
||||
- [ ] ❌ **No UX pattern consistency rules** (implementation will be inconsistent)
|
||||
- [ ] ❌ **Missing core experience definition** (no clarity on what makes app unique)
|
||||
- [ ] ❌ **No component specifications** (components not actionable)
|
||||
- [ ] ❌ **Responsive strategy missing** (for multi-platform projects)
|
||||
- [ ] ❌ **Accessibility ignored** (no compliance target or requirements)
|
||||
- [ ] ❌ **Generic/templated content** (not specific to this project)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document findings:**
|
||||
|
||||
- UX Design Quality: [Exceptional / Strong / Adequate / Needs Work / Incomplete]
|
||||
- Collaboration Level: [Highly Collaborative / Collaborative / Somewhat Collaborative / Generated]
|
||||
- Visual Artifacts: [Complete & Interactive / Partial / Missing]
|
||||
- Implementation Readiness: [Ready / Needs Design Phase / Not Ready]
|
||||
|
||||
## **Strengths:**
|
||||
|
||||
## **Areas for Improvement:**
|
||||
|
||||
## **Recommended Actions:**
|
||||
|
||||
**Ready for next phase?** [Yes - Proceed to Design / Yes - Proceed to Development / Needs Refinement]
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates collaborative UX design facilitation, not template generation. A successful UX workflow creates design decisions WITH the user through visual exploration and informed choices._
|
||||
1319
bmad/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
Normal file
1319
bmad/bmm/workflows/2-plan-workflows/create-ux-design/instructions.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,145 @@
|
||||
# {{project_name}} UX Design Specification
|
||||
|
||||
_Created on {{date}} by {{user_name}}_
|
||||
_Generated using BMad Method - Create UX Design Workflow v1.0_
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{project_vision}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Design System Foundation
|
||||
|
||||
### 1.1 Design System Choice
|
||||
|
||||
{{design_system_decision}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Core User Experience
|
||||
|
||||
### 2.1 Defining Experience
|
||||
|
||||
{{core_experience}}
|
||||
|
||||
### 2.2 Novel UX Patterns
|
||||
|
||||
{{novel_ux_patterns}}
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Foundation
|
||||
|
||||
### 3.1 Color System
|
||||
|
||||
{{visual_foundation}}
|
||||
|
||||
**Interactive Visualizations:**
|
||||
|
||||
- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
|
||||
|
||||
---
|
||||
|
||||
## 4. Design Direction
|
||||
|
||||
### 4.1 Chosen Design Approach
|
||||
|
||||
{{design_direction_decision}}
|
||||
|
||||
**Interactive Mockups:**
|
||||
|
||||
- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
|
||||
|
||||
---
|
||||
|
||||
## 5. User Journey Flows
|
||||
|
||||
### 5.1 Critical User Paths
|
||||
|
||||
{{user_journey_flows}}
|
||||
|
||||
---
|
||||
|
||||
## 6. Component Library
|
||||
|
||||
### 6.1 Component Strategy
|
||||
|
||||
{{component_library_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 7. UX Pattern Decisions
|
||||
|
||||
### 7.1 Consistency Rules
|
||||
|
||||
{{ux_pattern_decisions}}
|
||||
|
||||
---
|
||||
|
||||
## 8. Responsive Design & Accessibility
|
||||
|
||||
### 8.1 Responsive Strategy
|
||||
|
||||
{{responsive_accessibility_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementation Guidance
|
||||
|
||||
### 9.1 Completion Summary
|
||||
|
||||
{{completion_summary}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Related Documents
|
||||
|
||||
- Product Requirements: `{{prd_file}}`
|
||||
- Product Brief: `{{brief_file}}`
|
||||
- Brainstorming: `{{brainstorm_file}}`
|
||||
|
||||
### Core Interactive Deliverables
|
||||
|
||||
This UX Design Specification was created through visual collaboration:
|
||||
|
||||
- **Color Theme Visualizer**: {{color_themes_html}}
|
||||
- Interactive HTML showing all color theme options explored
|
||||
- Live UI component examples in each theme
|
||||
- Side-by-side comparison and semantic color usage
|
||||
|
||||
- **Design Direction Mockups**: {{design_directions_html}}
|
||||
- Interactive HTML with 6-8 complete design approaches
|
||||
- Full-screen mockups of key screens
|
||||
- Design philosophy and rationale for each direction
|
||||
|
||||
### Optional Enhancement Deliverables
|
||||
|
||||
_This section will be populated if additional UX artifacts are generated through follow-up workflows._
|
||||
|
||||
<!-- Additional deliverables added here by other workflows -->
|
||||
|
||||
### Next Steps & Follow-Up Workflows
|
||||
|
||||
This UX Design Specification can serve as input to:
|
||||
|
||||
- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
|
||||
- **Figma Design Workflow** - Generate Figma files via MCP integration
|
||||
- **Interactive Prototype Workflow** - Build clickable HTML prototypes
|
||||
- **Component Showcase Workflow** - Create interactive component library
|
||||
- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
|
||||
- **Solution Architecture Workflow** - Define technical architecture with UX context
|
||||
|
||||
### Version History
|
||||
|
||||
| Date | Version | Changes | Author |
|
||||
| -------- | ------- | ------------------------------- | ------------- |
|
||||
| {{date}} | 1.0 | Initial UX Design Specification | {{user_name}} |
|
||||
|
||||
---
|
||||
|
||||
_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._
|
||||
@@ -0,0 +1,64 @@
|
||||
# Create UX Design Workflow Configuration
|
||||
name: create-ux-design
|
||||
description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
|
||||
# Input requirements - We work from PRD, Brief, or Brainstorming docs
|
||||
recommended_inputs:
|
||||
- prd: "Product Requirements Document with features and user journeys"
|
||||
- product_brief: "Product brief with vision and target users"
|
||||
- brainstorming: "Brainstorming documents with ideas and concepts"
|
||||
|
||||
# Input file references (fuzzy matched from output folder)
|
||||
prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
|
||||
brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
|
||||
brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
product_brief:
|
||||
whole: "{output_folder}/*brief*.md"
|
||||
sharded: "{output_folder}/*brief*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
|
||||
brainstorming:
|
||||
whole: "{output_folder}/*brainstorm*.md"
|
||||
sharded: "{output_folder}/*brainstorm*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/ux-design-template.md"
|
||||
|
||||
# Knowledge bases for intelligent UX decisions
|
||||
ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
|
||||
color_psychology: "{installed_path}/color-psychology.yaml"
|
||||
layout_patterns: "{installed_path}/layout-patterns.yaml"
|
||||
|
||||
# Output configuration - Progressive saves throughout workflow
|
||||
default_output_file: "{output_folder}/ux-design-specification.md"
|
||||
color_themes_html: "{output_folder}/ux-color-themes.html"
|
||||
design_directions_html: "{output_folder}/ux-design-directions.html"
|
||||
|
||||
standalone: true
|
||||
139
bmad/bmm/workflows/2-plan-workflows/narrative/checklist.md
Normal file
139
bmad/bmm/workflows/2-plan-workflows/narrative/checklist.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Narrative Design Workflow Validation Checklist
|
||||
|
||||
**Purpose**: Validate narrative design outputs are complete, cohesive, and ready for implementation.
|
||||
|
||||
**Scope**: Story-driven games and applications (follows GDD workflow)
|
||||
|
||||
**Expected Output**: narrative-design.md
|
||||
|
||||
---
|
||||
|
||||
## 1. Output File Exists
|
||||
|
||||
- [ ] narrative-design.md created in output folder
|
||||
- [ ] GDD.md exists (narrative workflow requires GDD first)
|
||||
- [ ] No unfilled {{template_variables}}
|
||||
|
||||
---
|
||||
|
||||
## 2. Story Foundation
|
||||
|
||||
### Core Elements
|
||||
|
||||
- [ ] **Narrative premise** clearly stated (elevator pitch, 2-3 sentences)
|
||||
- [ ] **Core themes** identified (2-4 meaningful themes)
|
||||
- [ ] **Tone and atmosphere** established
|
||||
- [ ] Premise is compelling and fits game type
|
||||
|
||||
### Story Structure
|
||||
|
||||
- [ ] **Story structure chosen** (3-act, hero's journey, branching, etc.)
|
||||
- [ ] **Acts/sections broken down** with clear progression
|
||||
- [ ] **Major story beats** documented (key moments that drive narrative)
|
||||
- [ ] Structure fits narrative complexity level
|
||||
|
||||
---
|
||||
|
||||
## 3. Characters
|
||||
|
||||
### Protagonist(s)
|
||||
|
||||
- [ ] Background and motivation explained
|
||||
- [ ] Character arc defined (how they change)
|
||||
- [ ] Internal and external conflicts identified
|
||||
|
||||
### Antagonist(s)
|
||||
|
||||
- [ ] Motivation clear (why they oppose protagonist)
|
||||
- [ ] Goals and methods explained
|
||||
- [ ] Not one-dimensional
|
||||
|
||||
### Supporting Cast
|
||||
|
||||
- [ ] Major supporting characters documented
|
||||
- [ ] Each has distinct role in story
|
||||
- [ ] Character relationships mapped
|
||||
|
||||
### Character Arcs
|
||||
|
||||
- [ ] Major characters have starting → transformation → ending states
|
||||
- [ ] Arc progression makes sense
|
||||
|
||||
---
|
||||
|
||||
## 4. World and Lore
|
||||
|
||||
- [ ] **World setting** defined (time, place, world type)
|
||||
- [ ] **World rules** explained (magic, technology, society)
|
||||
- [ ] **History and backstory** documented
|
||||
- [ ] Key locations described with narrative significance
|
||||
|
||||
---
|
||||
|
||||
## 5. Dialogue and Delivery
|
||||
|
||||
### Dialogue Framework
|
||||
|
||||
- [ ] Dialogue style established
|
||||
- [ ] Key conversations identified
|
||||
- [ ] Branching dialogue system described (if applicable)
|
||||
|
||||
### Narrative Delivery
|
||||
|
||||
- [ ] Cutscenes/cinematics approach defined
|
||||
- [ ] In-game storytelling methods explained
|
||||
- [ ] Optional vs. required content distinguished
|
||||
- [ ] Multiple endings documented (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 6. Gameplay Integration
|
||||
|
||||
- [ ] **Narrative-gameplay harmony** addressed (how story and mechanics connect)
|
||||
- [ ] **Story gates** explained (how narrative controls progression)
|
||||
- [ ] **Player agency** level defined (can player affect story?)
|
||||
- [ ] Integration doesn't fight game design
|
||||
|
||||
---
|
||||
|
||||
## 7. Production Scope
|
||||
|
||||
- [ ] **Writing scope** estimated (word count, scene count, dialogue lines)
|
||||
- [ ] Scope realistic for project level
|
||||
- [ ] Localization considerations noted (if applicable)
|
||||
- [ ] Voice acting plans documented (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 8. Consistency with GDD
|
||||
|
||||
- [ ] Narrative aligns with GDD game design
|
||||
- [ ] Tone matches GDD art/audio direction
|
||||
- [ ] Story supports game mechanics (doesn't contradict)
|
||||
- [ ] No conflicts between narrative and gameplay
|
||||
|
||||
---
|
||||
|
||||
## 9. Critical Failures (Auto-Fail)
|
||||
|
||||
- [ ] ❌ **No GDD** (narrative workflow requires GDD first)
|
||||
- [ ] ❌ **No character arcs** (protagonist has no development)
|
||||
- [ ] ❌ **No story beats** (major moments not identified)
|
||||
- [ ] ❌ **Contradicts GDD** (narrative fights game design)
|
||||
|
||||
---
|
||||
|
||||
## Validation Notes
|
||||
|
||||
**Document any findings:**
|
||||
|
||||
- Narrative strength: [Compelling / Interesting / Adequate / Weak]
|
||||
- Strengths:
|
||||
- Issues to address:
|
||||
- Recommended actions:
|
||||
|
||||
**Ready for solutioning?** [Yes / No - explain]
|
||||
|
||||
---
|
||||
|
||||
_Adapt based on narrative complexity level (Critical/Heavy/Moderate/Light)._
|
||||
@@ -0,0 +1,608 @@
|
||||
# Narrative Design Workflow
|
||||
|
||||
<workflow>
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already completed the GDD workflow</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
<critical>This workflow creates detailed narrative content for story-driven games</critical>
|
||||
<critical>Uses narrative_template for output</critical>
|
||||
<critical>If users mention gameplay mechanics, note them but keep focus on narrative</critical>
|
||||
<critical>Facilitate good brainstorming techniques throughout with the user, pushing them to come up with much of the narrative you will help weave together. The goal is for the user to feel that they crafted the narrative and story arc unless they push you to do it all or indicate YOLO</critical>
|
||||
|
||||
<step n="0" goal="Check for workflow status" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Narrative workflow is optional - you can continue without status tracking.</output>
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "narrative" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="narrative status is file path (already completed)">
|
||||
<output>⚠️ Narrative Design Document already completed: {{narrative status}}</output>
|
||||
<ask>Re-running will overwrite the existing narrative document. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="narrative is not the next expected workflow (latter items are completed already in the list)">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Narrative is out of sequence.</output>
|
||||
<ask>Continue with Narrative Design anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load GDD context and assess narrative complexity">
|
||||
|
||||
<action>Load GDD.md from {output_folder}</action>
|
||||
<action>Extract game_type, game_name, and any narrative mentions</action>
|
||||
|
||||
<ask>What level of narrative complexity does your game have?
|
||||
|
||||
**Narrative Complexity:**
|
||||
|
||||
1. **Critical** - Story IS the game (Visual Novel, Text-Based Adventure)
|
||||
2. **Heavy** - Story drives the experience (Story-driven RPG, Narrative Adventure)
|
||||
3. **Moderate** - Story enhances gameplay (Metroidvania, Tactics RPG, Horror)
|
||||
4. **Light** - Story provides context (most other genres)
|
||||
|
||||
Your game type ({{game_type}}) suggests **{{suggested_complexity}}**. Confirm or adjust:</ask>
|
||||
|
||||
<action>Set narrative_complexity</action>
|
||||
|
||||
<check if="complexity == Light">
|
||||
<ask>Light narrative games usually don't need a full Narrative Design Document. Are you sure you want to continue?
|
||||
|
||||
- GDD story sections may be sufficient
|
||||
- Consider just expanding GDD narrative notes
|
||||
- Proceed with full narrative workflow
|
||||
|
||||
Your choice:</ask>
|
||||
|
||||
<action>Load narrative_template from workflow.yaml</action>
|
||||
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Define narrative premise and themes">
|
||||
|
||||
<ask>Describe your narrative premise in 2-3 sentences.
|
||||
|
||||
This is the "elevator pitch" of your story.
|
||||
|
||||
Examples:
|
||||
|
||||
- "A young knight discovers they're the last hope to stop an ancient evil, but must choose between saving the kingdom or their own family."
|
||||
- "After a mysterious pandemic, survivors must navigate a world where telling the truth is deadly but lying corrupts your soul."
|
||||
|
||||
Your premise:</ask>
|
||||
|
||||
<template-output>narrative_premise</template-output>
|
||||
|
||||
<ask>What are the core themes of your narrative? (2-4 themes)
|
||||
|
||||
Themes are the underlying ideas/messages.
|
||||
|
||||
Examples: redemption, sacrifice, identity, corruption, hope vs. despair, nature vs. technology
|
||||
|
||||
Your themes:</ask>
|
||||
|
||||
<template-output>core_themes</template-output>
|
||||
|
||||
<ask>Describe the tone and atmosphere.
|
||||
|
||||
Consider: dark, hopeful, comedic, melancholic, mysterious, epic, intimate, etc.
|
||||
|
||||
Your tone:</ask>
|
||||
|
||||
<template-output>tone_atmosphere</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Define story structure">
|
||||
|
||||
<ask>What story structure are you using?
|
||||
|
||||
Common structures:
|
||||
|
||||
- **3-Act** (Setup, Confrontation, Resolution)
|
||||
- **Hero's Journey** (Campbell's monomyth)
|
||||
- **Kishōtenketsu** (4-act: Introduction, Development, Twist, Conclusion)
|
||||
- **Episodic** (Self-contained episodes with arc)
|
||||
- **Branching** (Multiple paths and endings)
|
||||
- **Freeform** (Player-driven narrative)
|
||||
|
||||
Your structure:</ask>
|
||||
|
||||
<template-output>story_type</template-output>
|
||||
|
||||
<ask>Break down your story into acts/sections.
|
||||
|
||||
For 3-Act:
|
||||
|
||||
- Act 1: Setup and inciting incident
|
||||
- Act 2: Rising action and midpoint
|
||||
- Act 3: Climax and resolution
|
||||
|
||||
Describe each act/section for your game:</ask>
|
||||
|
||||
<template-output>act_breakdown</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Define major story beats">
|
||||
|
||||
<ask>List the major story beats (10-20 key moments).
|
||||
|
||||
Story beats are significant events that drive the narrative forward.
|
||||
|
||||
Format:
|
||||
|
||||
1. [Beat name] - Brief description
|
||||
2. [Beat name] - Brief description
|
||||
...
|
||||
|
||||
Your story beats:</ask>
|
||||
|
||||
<template-output>story_beats</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
<ask>Describe the pacing and flow of your narrative.
|
||||
|
||||
Consider:
|
||||
|
||||
- Slow burn vs. fast-paced
|
||||
- Tension/release rhythm
|
||||
- Story-heavy vs. gameplay-heavy sections
|
||||
- Optional vs. required narrative content
|
||||
|
||||
Your pacing:</ask>
|
||||
|
||||
<template-output>pacing_flow</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Develop protagonist(s)">
|
||||
|
||||
<ask>Describe your protagonist(s).
|
||||
|
||||
For each protagonist include:
|
||||
|
||||
- Name and brief description
|
||||
- Background and motivation
|
||||
- Character arc (how they change)
|
||||
- Strengths and flaws
|
||||
- Relationships to other characters
|
||||
- Internal and external conflicts
|
||||
|
||||
Your protagonist(s):</ask>
|
||||
|
||||
<template-output>protagonists</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Develop antagonist(s)">
|
||||
|
||||
<ask>Describe your antagonist(s).
|
||||
|
||||
For each antagonist include:
|
||||
|
||||
- Name and brief description
|
||||
- Background and motivation
|
||||
- Goals (what they want)
|
||||
- Methods (how they pursue goals)
|
||||
- Relationship to protagonist
|
||||
- Sympathetic elements (if any)
|
||||
|
||||
Your antagonist(s):</ask>
|
||||
|
||||
<template-output>antagonists</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Develop supporting characters">
|
||||
|
||||
<ask>Describe supporting characters (allies, mentors, companions, NPCs).
|
||||
|
||||
For each character include:
|
||||
|
||||
- Name and role
|
||||
- Personality and traits
|
||||
- Relationship to protagonist
|
||||
- Function in story (mentor, foil, comic relief, etc.)
|
||||
- Key scenes/moments
|
||||
|
||||
Your supporting characters:</ask>
|
||||
|
||||
<template-output>supporting_characters</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Map character arcs">
|
||||
|
||||
<ask>Describe the character arcs for major characters.
|
||||
|
||||
Character arc: How does the character change from beginning to end?
|
||||
|
||||
For each arc:
|
||||
|
||||
- Starting state
|
||||
- Key transformation moments
|
||||
- Ending state
|
||||
- Lessons learned
|
||||
|
||||
Your character arcs:</ask>
|
||||
|
||||
<template-output>character_arcs</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Build world and lore">
|
||||
|
||||
<ask>Describe your world.
|
||||
|
||||
Include:
|
||||
|
||||
- Setting (time period, location, world type)
|
||||
- World rules (magic systems, technology level, societal norms)
|
||||
- Atmosphere and aesthetics
|
||||
- What makes this world unique
|
||||
|
||||
Your world:</ask>
|
||||
|
||||
<template-output>world_overview</template-output>
|
||||
|
||||
<ask>What is the history and backstory of your world?
|
||||
|
||||
- Major historical events
|
||||
- How did the world reach its current state?
|
||||
- Legends and myths
|
||||
- Past conflicts
|
||||
|
||||
Your history:</ask>
|
||||
|
||||
<template-output>history_backstory</template-output>
|
||||
<invoke-task halt="true">{project-root}/bmad/core/tasks/adv-elicit.xml</invoke-task>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Define factions and locations">
|
||||
|
||||
<ask optional="true">Describe factions, organizations, or groups (if applicable).
|
||||
|
||||
For each:
|
||||
|
||||
- Name and purpose
|
||||
- Leadership and structure
|
||||
- Goals and methods
|
||||
- Relationships with other factions
|
||||
|
||||
Your factions:</ask>
|
||||
|
||||
<template-output>factions_organizations</template-output>
|
||||
|
||||
<ask>Describe key locations in your world.
|
||||
|
||||
For each location:
|
||||
|
||||
- Name and description
|
||||
- Narrative significance
|
||||
- Atmosphere and mood
|
||||
- Key events that occur there
|
||||
|
||||
Your locations:</ask>
|
||||
|
||||
<template-output>locations</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Define dialogue framework">
|
||||
|
||||
<ask>Describe your dialogue style.
|
||||
|
||||
Consider:
|
||||
|
||||
- Formal vs. casual
|
||||
- Period-appropriate vs. modern
|
||||
- Verbose vs. concise
|
||||
- Humor level
|
||||
- Profanity/mature language
|
||||
|
||||
Your dialogue style:</ask>
|
||||
|
||||
<template-output>dialogue_style</template-output>
|
||||
|
||||
<ask>List key conversations/dialogue moments.
|
||||
|
||||
Include:
|
||||
|
||||
- Who is involved
|
||||
- When it occurs
|
||||
- What's discussed
|
||||
- Narrative purpose
|
||||
- Emotional tone
|
||||
|
||||
Your key conversations:</ask>
|
||||
|
||||
<template-output>key_conversations</template-output>
|
||||
|
||||
<check if="game has branching dialogue">
|
||||
<ask>Describe your branching dialogue system.
|
||||
|
||||
- How many branches/paths?
|
||||
- What determines branches? (stats, choices, flags)
|
||||
- Do branches converge?
|
||||
- How much unique dialogue?
|
||||
|
||||
Your branching system:</ask>
|
||||
|
||||
<template-output>branching_dialogue</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Environmental storytelling">
|
||||
|
||||
<ask>How will you tell story through the environment?
|
||||
|
||||
Visual storytelling:
|
||||
|
||||
- Set dressing and props
|
||||
- Environmental damage/aftermath
|
||||
- Visual symbolism
|
||||
- Color and lighting
|
||||
|
||||
Your visual storytelling:</ask>
|
||||
|
||||
<template-output>visual_storytelling</template-output>
|
||||
|
||||
<ask>How will audio contribute to storytelling?
|
||||
|
||||
- Ambient sounds
|
||||
- Music emotional cues
|
||||
- Voice acting
|
||||
- Audio logs/recordings
|
||||
|
||||
Your audio storytelling:</ask>
|
||||
|
||||
<template-output>audio_storytelling</template-output>
|
||||
|
||||
<ask optional="true">Will you have found documents (journals, notes, emails)?
|
||||
|
||||
If yes, describe:
|
||||
|
||||
- Types of documents
|
||||
- How many
|
||||
- What they reveal
|
||||
- Optional vs. required reading
|
||||
|
||||
Your found documents:</ask>
|
||||
|
||||
<template-output>found_documents</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="13" goal="Narrative delivery methods">
|
||||
|
||||
<ask>How will you deliver narrative content?
|
||||
|
||||
**Cutscenes/Cinematics:**
|
||||
|
||||
- How many?
|
||||
- Skippable?
|
||||
- Real-time or pre-rendered?
|
||||
- Average length
|
||||
|
||||
Your cutscenes:</ask>
|
||||
|
||||
<template-output>cutscenes</template-output>
|
||||
|
||||
<ask>How will you deliver story during gameplay?
|
||||
|
||||
- NPC conversations
|
||||
- Radio/comm chatter
|
||||
- Environmental cues
|
||||
- Player actions
|
||||
- Show vs. tell balance
|
||||
|
||||
Your in-game storytelling:</ask>
|
||||
|
||||
<template-output>ingame_storytelling</template-output>
|
||||
|
||||
<ask>What narrative content is optional?
|
||||
|
||||
- Side quests
|
||||
- Collectible lore
|
||||
- Optional conversations
|
||||
- Secret endings
|
||||
|
||||
Your optional content:</ask>
|
||||
|
||||
<template-output>optional_content</template-output>
|
||||
|
||||
<check if="multiple endings">
|
||||
<ask>Describe your ending structure.
|
||||
|
||||
- How many endings?
|
||||
- What determines ending? (choices, stats, completion)
|
||||
- Ending variety (minor variations vs. drastically different)
|
||||
- True/golden ending?
|
||||
|
||||
Your endings:</ask>
|
||||
|
||||
<template-output>multiple_endings</template-output>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="14" goal="Gameplay integration">
|
||||
|
||||
<ask>How does narrative integrate with gameplay?
|
||||
|
||||
- Does story unlock mechanics?
|
||||
- Do mechanics reflect themes?
|
||||
- Ludonarrative harmony or dissonance?
|
||||
- Balance of story vs. gameplay
|
||||
|
||||
Your narrative-gameplay integration:</ask>
|
||||
|
||||
<template-output>narrative_gameplay</template-output>
|
||||
|
||||
<ask>How does story gate progression?
|
||||
|
||||
- Story-locked areas
|
||||
- Cutscene triggers
|
||||
- Mandatory story beats
|
||||
- Optional vs. required narrative
|
||||
|
||||
Your story gates:</ask>
|
||||
|
||||
<template-output>story_gates</template-output>
|
||||
|
||||
<ask>How much agency does the player have?
|
||||
|
||||
- Can player affect story?
|
||||
- Meaningful choices?
|
||||
- Role-playing freedom?
|
||||
- Predetermined vs. dynamic narrative
|
||||
|
||||
Your player agency:</ask>
|
||||
|
||||
<template-output>player_agency</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="15" goal="Production planning">
|
||||
|
||||
<ask>Estimate your writing scope.
|
||||
|
||||
- Word count estimate
|
||||
- Number of scenes/chapters
|
||||
- Dialogue lines estimate
|
||||
- Branching complexity
|
||||
|
||||
Your scope:</ask>
|
||||
|
||||
<template-output>writing_scope</template-output>
|
||||
|
||||
<ask>Localization considerations?
|
||||
|
||||
- Target languages
|
||||
- Cultural adaptation needs
|
||||
- Text expansion concerns
|
||||
- Dialogue recording implications
|
||||
|
||||
Your localization:</ask>
|
||||
|
||||
<template-output>localization</template-output>
|
||||
|
||||
<ask>Voice acting plans?
|
||||
|
||||
- Fully voiced, partially voiced, or text-only?
|
||||
- Number of characters needing voices
|
||||
- Dialogue volume
|
||||
- Budget considerations
|
||||
|
||||
Your voice acting:</ask>
|
||||
|
||||
<template-output>voice_acting</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="16" goal="Completion and next steps">
|
||||
|
||||
<action>Generate character relationship map (text-based diagram)</action>
|
||||
<template-output>relationship_map</template-output>
|
||||
|
||||
<action>Generate story timeline</action>
|
||||
<template-output>timeline</template-output>
|
||||
|
||||
<ask optional="true">Any references or inspirations to note?
|
||||
|
||||
- Books, movies, games that inspired you
|
||||
- Reference materials
|
||||
- Tone/theme references
|
||||
|
||||
Your references:</ask>
|
||||
|
||||
<template-output>references</template-output>
|
||||
|
||||
<ask>**✅ Narrative Design Complete, {user_name}!**
|
||||
|
||||
Next steps:
|
||||
|
||||
1. Proceed to solutioning (technical architecture)
|
||||
2. Create detailed script/screenplay (outside workflow)
|
||||
3. Review narrative with team/stakeholders
|
||||
4. Exit workflow
|
||||
|
||||
Which would you like?</ask>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="17" goal="Update status if tracking enabled" tag="workflow-status">
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "narrative"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["narrative"] = "{output_folder}/bmm-narrative-{{game_name}}-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Narrative Design Complete, {user_name}!**
|
||||
|
||||
**Narrative Document:**
|
||||
|
||||
- Narrative design saved to {output_folder}/bmm-narrative-{{game_name}}-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: narrative marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- **Optional:** Review narrative with writing team or stakeholders
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Review narrative design with team
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,195 @@
|
||||
# {{game_name}} - Narrative Design Document
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Game Type:** {{game_type}}
|
||||
**Narrative Complexity:** {{narrative_complexity}}
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
### Narrative Premise
|
||||
|
||||
{{narrative_premise}}
|
||||
|
||||
### Core Themes
|
||||
|
||||
{{core_themes}}
|
||||
|
||||
### Tone and Atmosphere
|
||||
|
||||
{{tone_atmosphere}}
|
||||
|
||||
---
|
||||
|
||||
## Story Structure
|
||||
|
||||
### Story Type
|
||||
|
||||
{{story_type}}
|
||||
|
||||
**Structure used:** (3-act, hero's journey, kishōtenketsu, episodic, branching, etc.)
|
||||
|
||||
### Act Breakdown
|
||||
|
||||
{{act_breakdown}}
|
||||
|
||||
### Story Beats
|
||||
|
||||
{{story_beats}}
|
||||
|
||||
### Pacing and Flow
|
||||
|
||||
{{pacing_flow}}
|
||||
|
||||
---
|
||||
|
||||
## Characters
|
||||
|
||||
### Protagonist(s)
|
||||
|
||||
{{protagonists}}
|
||||
|
||||
### Antagonist(s)
|
||||
|
||||
{{antagonists}}
|
||||
|
||||
### Supporting Characters
|
||||
|
||||
{{supporting_characters}}
|
||||
|
||||
### Character Arcs
|
||||
|
||||
{{character_arcs}}
|
||||
|
||||
---
|
||||
|
||||
## World and Lore
|
||||
|
||||
### World Overview
|
||||
|
||||
{{world_overview}}
|
||||
|
||||
### History and Backstory
|
||||
|
||||
{{history_backstory}}
|
||||
|
||||
### Factions and Organizations
|
||||
|
||||
{{factions_organizations}}
|
||||
|
||||
### Locations
|
||||
|
||||
{{locations}}
|
||||
|
||||
### Cultural Elements
|
||||
|
||||
{{cultural_elements}}
|
||||
|
||||
---
|
||||
|
||||
## Dialogue Framework
|
||||
|
||||
### Dialogue Style
|
||||
|
||||
{{dialogue_style}}
|
||||
|
||||
### Key Conversations
|
||||
|
||||
{{key_conversations}}
|
||||
|
||||
### Branching Dialogue
|
||||
|
||||
{{branching_dialogue}}
|
||||
|
||||
### Voice and Characterization
|
||||
|
||||
{{voice_characterization}}
|
||||
|
||||
---
|
||||
|
||||
## Environmental Storytelling
|
||||
|
||||
### Visual Storytelling
|
||||
|
||||
{{visual_storytelling}}
|
||||
|
||||
### Audio Storytelling
|
||||
|
||||
{{audio_storytelling}}
|
||||
|
||||
### Found Documents
|
||||
|
||||
{{found_documents}}
|
||||
|
||||
### Environmental Clues
|
||||
|
||||
{{environmental_clues}}
|
||||
|
||||
---
|
||||
|
||||
## Narrative Delivery
|
||||
|
||||
### Cutscenes and Cinematics
|
||||
|
||||
{{cutscenes}}
|
||||
|
||||
### In-Game Storytelling
|
||||
|
||||
{{ingame_storytelling}}
|
||||
|
||||
### Optional Content
|
||||
|
||||
{{optional_content}}
|
||||
|
||||
### Multiple Endings
|
||||
|
||||
{{multiple_endings}}
|
||||
|
||||
---
|
||||
|
||||
## Integration with Gameplay
|
||||
|
||||
### Narrative-Gameplay Harmony
|
||||
|
||||
{{narrative_gameplay}}
|
||||
|
||||
### Story Gates
|
||||
|
||||
{{story_gates}}
|
||||
|
||||
### Player Agency
|
||||
|
||||
{{player_agency}}
|
||||
|
||||
---
|
||||
|
||||
## Production Notes
|
||||
|
||||
### Writing Scope
|
||||
|
||||
{{writing_scope}}
|
||||
|
||||
### Localization Considerations
|
||||
|
||||
{{localization}}
|
||||
|
||||
### Voice Acting
|
||||
|
||||
{{voice_acting}}
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Character Relationship Map
|
||||
|
||||
{{relationship_map}}
|
||||
|
||||
### Timeline
|
||||
|
||||
{{timeline}}
|
||||
|
||||
### References and Inspirations
|
||||
|
||||
{{references}}
|
||||
29
bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
Normal file
29
bmad/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
Normal file
@@ -0,0 +1,29 @@
|
||||
# Narrative Design Workflow
|
||||
name: narrative
|
||||
description: "Narrative design workflow for story-driven games and applications. Creates comprehensive narrative documentation including story structure, character arcs, dialogue systems, and narrative implementation guidance."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/narrative"
|
||||
instructions: "{installed_path}/instructions-narrative.md"
|
||||
template: "{installed_path}/narrative-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/narrative-design.md"
|
||||
|
||||
# Recommended input documents
|
||||
recommended_inputs:
|
||||
- game_brief: "{output_folder}/game-brief.md"
|
||||
- gdd: "{output_folder}/GDD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
|
||||
standalone: true
|
||||
349
bmad/bmm/workflows/2-plan-workflows/prd/checklist.md
Normal file
349
bmad/bmm/workflows/2-plan-workflows/prd/checklist.md
Normal file
@@ -0,0 +1,349 @@
|
||||
# PRD + Epics + Stories Validation Checklist
|
||||
|
||||
**Purpose**: Comprehensive validation that PRD, epics, and stories form a complete, implementable product plan.
|
||||
|
||||
**Scope**: Validates the complete planning output (PRD.md + epics.md) for Levels 2-4 software projects
|
||||
|
||||
**Expected Outputs**:
|
||||
|
||||
- PRD.md with complete requirements
|
||||
- epics.md with detailed epic and story breakdown
|
||||
- Updated bmm-workflow-status.yaml
|
||||
|
||||
---
|
||||
|
||||
## 1. PRD Document Completeness
|
||||
|
||||
### Core Sections Present
|
||||
|
||||
- [ ] Executive Summary with vision alignment
|
||||
- [ ] Product magic essence clearly articulated
|
||||
- [ ] Project classification (type, domain, complexity)
|
||||
- [ ] Success criteria defined
|
||||
- [ ] Product scope (MVP, Growth, Vision) clearly delineated
|
||||
- [ ] Functional requirements comprehensive and numbered
|
||||
- [ ] Non-functional requirements (when applicable)
|
||||
- [ ] References section with source documents
|
||||
|
||||
### Project-Specific Sections
|
||||
|
||||
- [ ] **If complex domain:** Domain context and considerations documented
|
||||
- [ ] **If innovation:** Innovation patterns and validation approach documented
|
||||
- [ ] **If API/Backend:** Endpoint specification and authentication model included
|
||||
- [ ] **If Mobile:** Platform requirements and device features documented
|
||||
- [ ] **If SaaS B2B:** Tenant model and permission matrix included
|
||||
- [ ] **If UI exists:** UX principles and key interactions documented
|
||||
|
||||
### Quality Checks
|
||||
|
||||
- [ ] No unfilled template variables ({{variable}})
|
||||
- [ ] All variables properly populated with meaningful content
|
||||
- [ ] Product magic woven throughout (not just stated once)
|
||||
- [ ] Language is clear, specific, and measurable
|
||||
- [ ] Project type correctly identified and sections match
|
||||
- [ ] Domain complexity appropriately addressed
|
||||
|
||||
---
|
||||
|
||||
## 2. Functional Requirements Quality
|
||||
|
||||
### FR Format and Structure
|
||||
|
||||
- [ ] Each FR has unique identifier (FR-001, FR-002, etc.)
|
||||
- [ ] FRs describe WHAT capabilities, not HOW to implement
|
||||
- [ ] FRs are specific and measurable
|
||||
- [ ] FRs are testable and verifiable
|
||||
- [ ] FRs focus on user/business value
|
||||
- [ ] No technical implementation details in FRs (those belong in architecture)
|
||||
|
||||
### FR Completeness
|
||||
|
||||
- [ ] All MVP scope features have corresponding FRs
|
||||
- [ ] Growth features documented (even if deferred)
|
||||
- [ ] Vision features captured for future reference
|
||||
- [ ] Domain-mandated requirements included
|
||||
- [ ] Innovation requirements captured with validation needs
|
||||
- [ ] Project-type specific requirements complete
|
||||
|
||||
### FR Organization
|
||||
|
||||
- [ ] FRs organized by capability/feature area (not by tech stack)
|
||||
- [ ] Related FRs grouped logically
|
||||
- [ ] Dependencies between FRs noted when critical
|
||||
- [ ] Priority/phase indicated (MVP vs Growth vs Vision)
|
||||
|
||||
---
|
||||
|
||||
## 3. Epics Document Completeness
|
||||
|
||||
### Required Files
|
||||
|
||||
- [ ] epics.md exists in output folder
|
||||
- [ ] Epic list in PRD.md matches epics in epics.md (titles and count)
|
||||
- [ ] All epics have detailed breakdown sections
|
||||
|
||||
### Epic Quality
|
||||
|
||||
- [ ] Each epic has clear goal and value proposition
|
||||
- [ ] Each epic includes complete story breakdown
|
||||
- [ ] Stories follow proper user story format: "As a [role], I want [goal], so that [benefit]"
|
||||
- [ ] Each story has numbered acceptance criteria
|
||||
- [ ] Prerequisites/dependencies explicitly stated per story
|
||||
- [ ] Stories are AI-agent sized (completable in 2-4 hour session)
|
||||
|
||||
---
|
||||
|
||||
## 4. FR Coverage Validation (CRITICAL)
|
||||
|
||||
### Complete Traceability
|
||||
|
||||
- [ ] **Every FR from PRD.md is covered by at least one story in epics.md**
|
||||
- [ ] Each story references relevant FR numbers
|
||||
- [ ] No orphaned FRs (requirements without stories)
|
||||
- [ ] No orphaned stories (stories without FR connection)
|
||||
- [ ] Coverage matrix verified (can trace FR → Epic → Stories)
|
||||
|
||||
### Coverage Quality
|
||||
|
||||
- [ ] Stories sufficiently decompose FRs into implementable units
|
||||
- [ ] Complex FRs broken into multiple stories appropriately
|
||||
- [ ] Simple FRs have appropriately scoped single stories
|
||||
- [ ] Non-functional requirements reflected in story acceptance criteria
|
||||
- [ ] Domain requirements embedded in relevant stories
|
||||
|
||||
---
|
||||
|
||||
## 5. Story Sequencing Validation (CRITICAL)
|
||||
|
||||
### Epic 1 Foundation Check
|
||||
|
||||
- [ ] **Epic 1 establishes foundational infrastructure**
|
||||
- [ ] Epic 1 delivers initial deployable functionality
|
||||
- [ ] Epic 1 creates baseline for subsequent epics
|
||||
- [ ] Exception: If adding to existing app, foundation requirement adapted appropriately
|
||||
|
||||
### Vertical Slicing
|
||||
|
||||
- [ ] **Each story delivers complete, testable functionality** (not horizontal layers)
|
||||
- [ ] No "build database" or "create UI" stories in isolation
|
||||
- [ ] Stories integrate across stack (data + logic + presentation when applicable)
|
||||
- [ ] Each story leaves system in working/deployable state
|
||||
|
||||
### No Forward Dependencies
|
||||
|
||||
- [ ] **No story depends on work from a LATER story or epic**
|
||||
- [ ] Stories within each epic are sequentially ordered
|
||||
- [ ] Each story builds only on previous work
|
||||
- [ ] Dependencies flow backward only (can reference earlier stories)
|
||||
- [ ] Parallel tracks clearly indicated if stories are independent
|
||||
|
||||
### Value Delivery Path
|
||||
|
||||
- [ ] Each epic delivers significant end-to-end value
|
||||
- [ ] Epic sequence shows logical product evolution
|
||||
- [ ] User can see value after each epic completion
|
||||
- [ ] MVP scope clearly achieved by end of designated epics
|
||||
|
||||
---
|
||||
|
||||
## 6. Scope Management
|
||||
|
||||
### MVP Discipline
|
||||
|
||||
- [ ] MVP scope is genuinely minimal and viable
|
||||
- [ ] Core features list contains only true must-haves
|
||||
- [ ] Each MVP feature has clear rationale for inclusion
|
||||
- [ ] No obvious scope creep in "must-have" list
|
||||
|
||||
### Future Work Captured
|
||||
|
||||
- [ ] Growth features documented for post-MVP
|
||||
- [ ] Vision features captured to maintain long-term direction
|
||||
- [ ] Out-of-scope items explicitly listed
|
||||
- [ ] Deferred features have clear reasoning for deferral
|
||||
|
||||
### Clear Boundaries
|
||||
|
||||
- [ ] Stories marked as MVP vs Growth vs Vision
|
||||
- [ ] Epic sequencing aligns with MVP → Growth progression
|
||||
- [ ] No confusion about what's in vs out of initial scope
|
||||
|
||||
---
|
||||
|
||||
## 7. Research and Context Integration
|
||||
|
||||
### Source Document Integration
|
||||
|
||||
- [ ] **If product brief exists:** Key insights incorporated into PRD
|
||||
- [ ] **If domain brief exists:** Domain requirements reflected in FRs and stories
|
||||
- [ ] **If research documents exist:** Research findings inform requirements
|
||||
- [ ] **If competitive analysis exists:** Differentiation strategy clear in PRD
|
||||
- [ ] All source documents referenced in PRD References section
|
||||
|
||||
### Research Continuity to Architecture
|
||||
|
||||
- [ ] Domain complexity considerations documented for architects
|
||||
- [ ] Technical constraints from research captured
|
||||
- [ ] Regulatory/compliance requirements clearly stated
|
||||
- [ ] Integration requirements with existing systems documented
|
||||
- [ ] Performance/scale requirements informed by research data
|
||||
|
||||
### Information Completeness for Next Phase
|
||||
|
||||
- [ ] PRD provides sufficient context for architecture decisions
|
||||
- [ ] Epics provide sufficient detail for technical design
|
||||
- [ ] Stories have enough acceptance criteria for implementation
|
||||
- [ ] Non-obvious business rules documented
|
||||
- [ ] Edge cases and special scenarios captured
|
||||
|
||||
---
|
||||
|
||||
## 8. Cross-Document Consistency
|
||||
|
||||
### Terminology Consistency
|
||||
|
||||
- [ ] Same terms used across PRD and epics for concepts
|
||||
- [ ] Feature names consistent between documents
|
||||
- [ ] Epic titles match between PRD and epics.md
|
||||
- [ ] No contradictions between PRD and epics
|
||||
|
||||
### Alignment Checks
|
||||
|
||||
- [ ] Success metrics in PRD align with story outcomes
|
||||
- [ ] Product magic articulated in PRD reflected in epic goals
|
||||
- [ ] Technical preferences in PRD align with story implementation hints
|
||||
- [ ] Scope boundaries consistent across all documents
|
||||
|
||||
---
|
||||
|
||||
## 9. Readiness for Implementation
|
||||
|
||||
### Architecture Readiness (Next Phase)
|
||||
|
||||
- [ ] PRD provides sufficient context for architecture workflow
|
||||
- [ ] Technical constraints and preferences documented
|
||||
- [ ] Integration points identified
|
||||
- [ ] Performance/scale requirements specified
|
||||
- [ ] Security and compliance needs clear
|
||||
|
||||
### Development Readiness
|
||||
|
||||
- [ ] Stories are specific enough to estimate
|
||||
- [ ] Acceptance criteria are testable
|
||||
- [ ] Technical unknowns identified and flagged
|
||||
- [ ] Dependencies on external systems documented
|
||||
- [ ] Data requirements specified
|
||||
|
||||
### Level-Appropriate Detail
|
||||
|
||||
**If Level 2:**
|
||||
|
||||
- [ ] PRD supports lightweight tech-spec workflow
|
||||
- [ ] 5-15 story scope reasonable for project size
|
||||
- [ ] Complexity appropriate for small team/solo dev
|
||||
|
||||
**If Level 3-4:**
|
||||
|
||||
- [ ] PRD supports full architecture workflow
|
||||
- [ ] Epic structure supports phased delivery
|
||||
- [ ] Scope appropriate for team-based development
|
||||
- [ ] Clear value delivery through epic sequence
|
||||
|
||||
---
|
||||
|
||||
## 10. Quality and Polish
|
||||
|
||||
### Writing Quality
|
||||
|
||||
- [ ] Language is clear and free of jargon (or jargon is defined)
|
||||
- [ ] Sentences are concise and specific
|
||||
- [ ] No vague statements ("should be fast", "user-friendly")
|
||||
- [ ] Measurable criteria used throughout
|
||||
- [ ] Professional tone appropriate for stakeholder review
|
||||
|
||||
### Document Structure
|
||||
|
||||
- [ ] Sections flow logically
|
||||
- [ ] Headers and numbering consistent
|
||||
- [ ] Cross-references accurate (FR numbers, section references)
|
||||
- [ ] Formatting consistent throughout
|
||||
- [ ] Tables/lists formatted properly
|
||||
|
||||
### Completeness Indicators
|
||||
|
||||
- [ ] No [TODO] or [TBD] markers remain
|
||||
- [ ] No placeholder text
|
||||
- [ ] All sections have substantive content
|
||||
- [ ] Optional sections either complete or omitted (not half-done)
|
||||
|
||||
---
|
||||
|
||||
## Critical Failures (Auto-Fail)
|
||||
|
||||
If ANY of these are true, validation FAILS:
|
||||
|
||||
- [ ] ❌ **No epics.md file exists** (two-file output required)
|
||||
- [ ] ❌ **Epic 1 doesn't establish foundation** (violates core sequencing principle)
|
||||
- [ ] ❌ **Stories have forward dependencies** (breaks sequential implementation)
|
||||
- [ ] ❌ **Stories not vertically sliced** (horizontal layers block value delivery)
|
||||
- [ ] ❌ **Epics don't cover all FRs** (orphaned requirements)
|
||||
- [ ] ❌ **FRs contain technical implementation details** (should be in architecture)
|
||||
- [ ] ❌ **No FR traceability to stories** (can't validate coverage)
|
||||
- [ ] ❌ **Template variables unfilled** (incomplete document)
|
||||
|
||||
---
|
||||
|
||||
## Validation Summary
|
||||
|
||||
**Total Validation Points:** ~85
|
||||
|
||||
### Scoring Guide
|
||||
|
||||
- **Pass Rate ≥ 95% (81+/85):** ✅ EXCELLENT - Ready for architecture phase
|
||||
- **Pass Rate 85-94% (72-80/85):** ⚠️ GOOD - Minor fixes needed
|
||||
- **Pass Rate 70-84% (60-71/85):** ⚠️ FAIR - Important issues to address
|
||||
- **Pass Rate < 70% (<60/85):** ❌ POOR - Significant rework required
|
||||
|
||||
### Critical Issue Threshold
|
||||
|
||||
- **0 Critical Failures:** Proceed to fixes
|
||||
- **1+ Critical Failures:** STOP - Must fix critical issues first
|
||||
|
||||
---
|
||||
|
||||
## Validation Execution Notes
|
||||
|
||||
**When validating:**
|
||||
|
||||
1. **Load ALL documents:**
|
||||
- PRD.md (required)
|
||||
- epics.md (required)
|
||||
- product-brief.md (if exists)
|
||||
- domain-brief.md (if exists)
|
||||
- research documents (if referenced)
|
||||
|
||||
2. **Validate in order:**
|
||||
- Check critical failures first (immediate stop if any found)
|
||||
- Verify PRD completeness
|
||||
- Verify epics completeness
|
||||
- Cross-reference FR coverage (most important)
|
||||
- Check sequencing (second most important)
|
||||
- Validate research integration
|
||||
- Check polish and quality
|
||||
|
||||
3. **Report findings:**
|
||||
- List critical failures prominently
|
||||
- Group issues by severity
|
||||
- Provide specific line numbers/sections
|
||||
- Suggest concrete fixes
|
||||
- Highlight what's working well
|
||||
|
||||
4. **Provide actionable next steps:**
|
||||
- If validation passes: "Ready for architecture workflow"
|
||||
- If minor issues: "Fix [X] items then re-validate"
|
||||
- If major issues: "Rework [sections] then re-validate"
|
||||
- If critical failures: "Must fix critical items before proceeding"
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This validation ensures the entire planning phase is complete and the implementation phase has everything needed to succeed. Be thorough but fair - the goal is quality, not perfection.
|
||||
@@ -0,0 +1,63 @@
|
||||
# {{project_name}} - Epic Breakdown
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
**Target Scale:** {{target_scale}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the detailed epic breakdown for {{project_name}}, expanding on the high-level epic list in the [PRD](./PRD.md).
|
||||
|
||||
Each epic includes:
|
||||
|
||||
- Expanded goal and value proposition
|
||||
- Complete story breakdown with user stories
|
||||
- Acceptance criteria for each story
|
||||
- Story sequencing and dependencies
|
||||
|
||||
**Epic Sequencing Principles:**
|
||||
|
||||
- Epic 1 establishes foundational infrastructure and initial functionality
|
||||
- Subsequent epics build progressively, each delivering significant end-to-end value
|
||||
- Stories within epics are vertically sliced and sequentially ordered
|
||||
- No forward dependencies - each story builds only on previous work
|
||||
|
||||
---
|
||||
|
||||
{{epic_details}}
|
||||
|
||||
---
|
||||
|
||||
## Story Guidelines Reference
|
||||
|
||||
**Story Format:**
|
||||
|
||||
```
|
||||
**Story [EPIC.N]: [Story Title]**
|
||||
|
||||
As a [user type],
|
||||
I want [goal/desire],
|
||||
So that [benefit/value].
|
||||
|
||||
**Acceptance Criteria:**
|
||||
1. [Specific testable criterion]
|
||||
2. [Another specific criterion]
|
||||
3. [etc.]
|
||||
|
||||
**Prerequisites:** [Dependencies on previous stories, if any]
|
||||
```
|
||||
|
||||
**Story Requirements:**
|
||||
|
||||
- **Vertical slices** - Complete, testable functionality delivery
|
||||
- **Sequential ordering** - Logical progression within epic
|
||||
- **No forward dependencies** - Only depend on previous work
|
||||
- **AI-agent sized** - Completable in 2-4 hour focused session
|
||||
- **Value-focused** - Integrate technical enablers into value-delivering stories
|
||||
|
||||
---
|
||||
|
||||
**For implementation:** Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown.
|
||||
@@ -0,0 +1,395 @@
|
||||
# Epic and Story Decomposition - Bite-Sized Implementation Planning
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow transforms requirements into BITE-SIZED STORIES for limited context agents</critical>
|
||||
<critical>EVERY story must be completable by a single limited context window dev agent in one session</critical>
|
||||
<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>LIVING DOCUMENT: Write to epics.md continuously as you work - never wait until the end</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Load context and requirements">
|
||||
<action>Welcome the {user_name} to the project inception high level epic and story planning.
|
||||
|
||||
Load required documents:
|
||||
|
||||
1. PRD.md (must exist - fuzzy match on name, might be a folder with an index and smaller sharded files also)
|
||||
2. domain-brief.md (if exists)
|
||||
3. product-brief.md (if exists)
|
||||
|
||||
Extract from PRD:
|
||||
|
||||
- Functional requirements
|
||||
- Non-functional requirements
|
||||
- Domain considerations
|
||||
- Project type
|
||||
- MVP scope vs growth features
|
||||
|
||||
If continuing from PRD workflow:
|
||||
"Great! Now let's break down your requirements into actionable epics and bite-sized stories that development agents can implement independently."
|
||||
|
||||
If starting fresh:
|
||||
"I'll help you transform your PRD into organized epics with implementable stories. Each story will be small enough for a single dev agent to complete in one session."</action>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Form epics from natural groupings">
|
||||
<action>Transform requirements into epics organically
|
||||
|
||||
INTENT: Find natural boundaries that make sense for THIS product
|
||||
|
||||
Look at the requirements and find patterns:
|
||||
|
||||
- Features that work together
|
||||
- User journeys that connect
|
||||
- Technical systems that relate
|
||||
- Business capabilities that group
|
||||
- Domain requirements that cluster (compliance, validation, etc.)
|
||||
|
||||
Examples of natural epic formation:
|
||||
|
||||
- Auth features → "User Management" epic
|
||||
- Payment features → "Monetization" epic
|
||||
- Social features → "Community" epic
|
||||
- Admin features → "Administration" epic
|
||||
- Compliance requirements → "Regulatory Compliance" epic
|
||||
- API endpoints → "API Infrastructure" epic
|
||||
|
||||
But let the product guide you - don't force standard patterns
|
||||
|
||||
Each epic should:
|
||||
|
||||
- Have a clear business goal
|
||||
- Be independently valuable
|
||||
- Contain 3-8 related features
|
||||
- Be completable in 1-2 sprints
|
||||
|
||||
Name epics based on value, not technical components:
|
||||
GOOD: "User Onboarding", "Content Discovery", "Team Collaboration"
|
||||
NOT: "Database", "Frontend", "API"
|
||||
|
||||
If domain considerations exist:
|
||||
|
||||
- Create dedicated compliance/validation epics
|
||||
- Note special expertise needed per epic
|
||||
- Flag epics with regulatory dependencies
|
||||
|
||||
Present epic groupings conversationally:
|
||||
"Based on your requirements, I see these natural epic groupings:
|
||||
|
||||
1. [Epic Name] - [Brief description]
|
||||
2. [Epic Name] - [Brief description]
|
||||
3. [Epic Name] - [Brief description]
|
||||
|
||||
Does this organization make sense for how you think about the product?"</action>
|
||||
|
||||
<template-output>epics_structure</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Decompose into bite-sized stories">
|
||||
<critical>Small vertical sliced small stories are best for agentic dumb developers to implement without forgetting things</critical>
|
||||
|
||||
<action>Break each epic into small, implementable stories
|
||||
|
||||
INTENT: Create stories that one dev agent can complete independently
|
||||
|
||||
For each epic, decompose into stories that are:
|
||||
|
||||
- Small enough for single context window
|
||||
- Clear enough for autonomous implementation
|
||||
- Independent enough to develop in parallel when possible
|
||||
- Specific enough to have clear acceptance criteria
|
||||
|
||||
GOOD story examples:
|
||||
|
||||
- "Create login API endpoint that accepts email/password and returns JWT"
|
||||
- "Build user profile component with avatar upload to S3"
|
||||
- "Add password reset email template and sending logic"
|
||||
- "Implement rate limiting on auth endpoints (5 attempts per minute)"
|
||||
- "Create HIPAA-compliant audit log for patient data access"
|
||||
- "Build FDA 21 CFR Part 11 electronic signature component"
|
||||
|
||||
BAD story examples:
|
||||
|
||||
- "Build complete authentication system" (too big)
|
||||
- "Handle user management" (too vague)
|
||||
- "Make it secure" (not specific)
|
||||
- "Integrate everything" (requires multiple contexts)
|
||||
|
||||
Story format:
|
||||
"As a [user type], I want [specific feature], so that [clear value]"
|
||||
|
||||
Technical notes to include:
|
||||
|
||||
- Affected files/components if known
|
||||
- Required endpoints/methods
|
||||
- Data structures needed
|
||||
- Specific validation rules
|
||||
- Compliance requirements if applicable
|
||||
- Dependencies on other stories
|
||||
|
||||
Domain-aware story creation:
|
||||
|
||||
- For healthcare: Include specific regulations per story
|
||||
- For fintech: Note PCI/security requirements per story
|
||||
- For govtech: Flag accessibility needs per story
|
||||
- For aerospace: Include safety/validation requirements
|
||||
|
||||
Check each story:
|
||||
|
||||
- Can this be explained in <1000 words?
|
||||
- Can one agent complete without another's output?
|
||||
- Is the scope crystal clear?
|
||||
- Are success criteria obvious?
|
||||
- Are domain requirements specified?
|
||||
|
||||
If too big → split into smaller stories
|
||||
If too vague → add specifics
|
||||
If dependent → note the dependency clearly
|
||||
If domain-critical → flag compliance needs</action>
|
||||
|
||||
<template-output>epic_1_stories</template-output>
|
||||
<template-output>epic_2_stories</template-output>
|
||||
<template-output>epic_3_stories</template-output>
|
||||
|
||||
<!-- Continue for each epic discovered -->
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Sequence for smart implementation">
|
||||
<action>Order stories for successful development
|
||||
|
||||
INTENT: Create a logical flow that minimizes blockers and maximizes progress
|
||||
|
||||
Consider dependencies:
|
||||
TECHNICAL:
|
||||
|
||||
- Authentication before protected features
|
||||
- Data models before business logic
|
||||
- Core features before enhancements
|
||||
- API before frontend that uses it
|
||||
|
||||
DOMAIN:
|
||||
|
||||
- Compliance infrastructure before features
|
||||
- Validation framework before clinical features
|
||||
- Audit logging before financial transactions
|
||||
- Safety systems before operational features
|
||||
|
||||
PRACTICAL:
|
||||
|
||||
- What gives visible progress early?
|
||||
- What reduces risk soonest?
|
||||
- What enables parallel work?
|
||||
- What delivers value fastest?
|
||||
|
||||
Create implementation phases:
|
||||
|
||||
Phase 1 - Foundation:
|
||||
|
||||
- Core data models
|
||||
- Authentication/authorization
|
||||
- Basic infrastructure
|
||||
- Essential APIs
|
||||
- Compliance foundation (if domain requires)
|
||||
|
||||
Phase 2 - Core Features:
|
||||
|
||||
- MVP functionality
|
||||
- Key user flows
|
||||
- Basic UI/UX
|
||||
- Critical integrations
|
||||
- Domain validations (if applicable)
|
||||
|
||||
Phase 3 - Enhancement:
|
||||
|
||||
- Polish and refinement
|
||||
- Additional features
|
||||
- Performance optimization
|
||||
- Extended functionality
|
||||
- Advanced compliance features
|
||||
|
||||
Phase 4 - Growth:
|
||||
|
||||
- Analytics and monitoring
|
||||
- Advanced features
|
||||
- Scaling preparations
|
||||
- Nice-to-have additions
|
||||
|
||||
For complex domains, add gates:
|
||||
|
||||
- "Gate: Security audit before payment processing"
|
||||
- "Gate: Clinical validation before patient features"
|
||||
- "Gate: Compliance review before launch"
|
||||
|
||||
Present the sequencing conversationally:
|
||||
"Here's a smart implementation order:
|
||||
|
||||
**Phase 1 (Foundation) - Week 1-2:**
|
||||
|
||||
- Story 1.1: [Description]
|
||||
- Story 1.2: [Description] (can parallel with 1.1)
|
||||
- Story 1.3: [Description] (depends on 1.1)
|
||||
|
||||
**Phase 2 (Core) - Week 3-4:**
|
||||
[Continue...]
|
||||
|
||||
This gives you something working by [milestone] and allows [X] stories to run in parallel."</action>
|
||||
|
||||
<template-output>implementation_sequence</template-output>
|
||||
<template-output>development_phases</template-output>
|
||||
<template-output>dependency_graph</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Validate story sizing and clarity">
|
||||
<action>Review all stories for dev agent compatibility
|
||||
|
||||
Run through each story and verify:
|
||||
|
||||
SIZE CHECK:
|
||||
|
||||
- Story description < 500 words
|
||||
- Clear inputs and outputs defined
|
||||
- Single responsibility principle
|
||||
- No hidden complexity
|
||||
|
||||
CLARITY CHECK:
|
||||
|
||||
- Acceptance criteria explicit
|
||||
- Technical approach clear
|
||||
- No ambiguous requirements
|
||||
- Success measurable
|
||||
|
||||
DEPENDENCY CHECK:
|
||||
|
||||
- Dependencies documented
|
||||
- Can start with clear inputs
|
||||
- Outputs well-defined
|
||||
- Parallel opportunities noted
|
||||
|
||||
DOMAIN CHECK (if applicable):
|
||||
|
||||
- Compliance requirements stated
|
||||
- Validation criteria defined
|
||||
- Regulatory references included
|
||||
- Special expertise noted
|
||||
|
||||
If any issues found:
|
||||
"Story [X] seems too large. Let me split it:
|
||||
|
||||
- [Smaller story 1]
|
||||
- [Smaller story 2]"
|
||||
|
||||
"Story [Y] needs clarification on [aspect]. How should we handle [specific question]?"
|
||||
|
||||
Final validation:
|
||||
"All stories are now sized for 200k context limits.
|
||||
|
||||
- Total stories: [count]
|
||||
- Can run in parallel: [count]
|
||||
- Sequential dependencies: [count]
|
||||
- Estimated completion: [timeframe]"</action>
|
||||
|
||||
<template-output>story_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Create development guidance">
|
||||
<action>Add practical guidance for implementation teams
|
||||
|
||||
Create quick reference for development:
|
||||
|
||||
GETTING STARTED:
|
||||
"Start with Phase 1 stories - multiple can run in parallel.
|
||||
Key files to create first: [list]
|
||||
Recommended agent allocation: [suggestion]"
|
||||
|
||||
DOMAIN GUIDANCE (if applicable):
|
||||
"Critical compliance checkpoints:
|
||||
|
||||
- After story [X]: Run [validation]
|
||||
- Before story [Y]: Review [regulation]
|
||||
- Throughout: Maintain [audit trail]"
|
||||
|
||||
TECHNICAL NOTES:
|
||||
"Architecture decisions needed:
|
||||
|
||||
- [Decision 1] affects stories [A, B, C]
|
||||
- [Decision 2] blocks story [D]
|
||||
|
||||
Consider these patterns:
|
||||
|
||||
- [Pattern] for [epic]
|
||||
- [Pattern] for [requirement]"
|
||||
|
||||
RISK MITIGATION:
|
||||
"Watch out for:
|
||||
|
||||
- [Risk] in story [X]
|
||||
- [Complexity] in epic [Y]
|
||||
- [Dependency] between [A] and [B]"
|
||||
|
||||
SUCCESS METRICS:
|
||||
"You'll know Phase 1 is complete when:
|
||||
|
||||
- [Measurable outcome]
|
||||
- [Testable feature]
|
||||
- [Validation passed]"</action>
|
||||
|
||||
<template-output>implementation_guidance</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Finalize and prepare handoff">
|
||||
<action>Complete the epics document and prepare for development
|
||||
|
||||
Review what we've created:
|
||||
"We've successfully decomposed your requirements into:
|
||||
|
||||
- [x] epics
|
||||
- [Y] total stories
|
||||
- [Z] phases of development
|
||||
|
||||
Every story is sized for a single dev agent to complete independently."
|
||||
|
||||
Highlight key achievements:
|
||||
|
||||
- Stories respect 200k context limit
|
||||
- Dependencies clearly mapped
|
||||
- Domain requirements integrated
|
||||
- Parallel development enabled
|
||||
|
||||
Save completed epics.md with:
|
||||
|
||||
- Full epic descriptions
|
||||
- All stories with acceptance criteria
|
||||
- Implementation sequence
|
||||
- Development phases
|
||||
- Dependency notes
|
||||
- Domain compliance requirements (if applicable)</action>
|
||||
|
||||
<output>**✅ Epic Decomposition Complete, {user_name}!**
|
||||
|
||||
Your requirements are now organized into **{epic_count} epics** with **{story_count} bite-sized stories**.
|
||||
|
||||
**Created:**
|
||||
|
||||
- **epics.md** - Complete epic breakdown with implementable stories
|
||||
|
||||
**Key Stats:**
|
||||
|
||||
- Average story size: Fits in 200k context
|
||||
- Parallel stories: {parallel_count} can run simultaneously
|
||||
- Sequential chains: {sequential_count} dependency chains
|
||||
- Estimated velocity: {velocity_estimate}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Review epics.md for the complete breakdown
|
||||
2. Start Phase 1 implementation with parallel stories
|
||||
3. Use story IDs for tracking progress
|
||||
|
||||
Each story is crafted for a single dev agent to complete autonomously. No monoliths, no confusion, just clear implementation paths.
|
||||
|
||||
Ready to begin development with any story marked "can start immediately"!</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,33 @@
|
||||
# Epic and Story Decomposition Workflow
|
||||
name: create-epics-and-stories
|
||||
description: "Transform PRD requirements into bite-sized stories organized in epics for 200k context dev agents"
|
||||
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
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/epics-template.md"
|
||||
|
||||
# Input files (from parent PRD workflow)
|
||||
prd_file: "{output_folder}/PRD.md"
|
||||
|
||||
# Output files
|
||||
default_output_file: "{output_folder}/epics.md"
|
||||
|
||||
# Optional input documents
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/PRD.md"
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
- domain_brief: "{output_folder}/domain-brief.md"
|
||||
|
||||
standalone: true
|
||||
@@ -0,0 +1,13 @@
|
||||
domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
|
||||
healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
|
||||
fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
|
||||
govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
|
||||
edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
|
||||
aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
|
||||
automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
|
||||
scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
|
||||
legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
|
||||
insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
|
||||
energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
|
||||
gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
|
||||
general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"
|
||||
|
423
bmad/bmm/workflows/2-plan-workflows/prd/instructions.md
Normal file
423
bmad/bmm/workflows/2-plan-workflows/prd/instructions.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# PRD Workflow - Intent-Driven Product Planning
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses INTENT-DRIVEN PLANNING - adapt organically to product type and context</critical>
|
||||
<critical>Communicate all responses in {communication_language} and adapt deeply to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>LIVING DOCUMENT: Write to PRD.md continuously as you discover - never wait until the end</critical>
|
||||
<critical>GUIDING PRINCIPLE: Find and weave the product's magic throughout - what makes it special should inspire every section</critical>
|
||||
|
||||
## 📚 Input Document Discovery
|
||||
|
||||
This workflow requires: product brief, and may reference market research or brownfield project documentation.
|
||||
|
||||
**Discovery Process** (execute for each referenced document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {status_file} exists</action>
|
||||
|
||||
<action if="status file not found">Set standalone_mode = true</action>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {status_file}</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "prd" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="project_level < 2">
|
||||
<output>**Level {{project_level}} Project - Redirecting**
|
||||
|
||||
Level 0-1 projects use tech-spec workflow for simpler planning.
|
||||
PRD is for Level 2-4 projects that need comprehensive requirements.</output>
|
||||
<action>Exit and suggest tech-spec workflow</action>
|
||||
</check>
|
||||
|
||||
<check if="prd status is file path (already completed)">
|
||||
<output>⚠️ PRD already completed: {{prd status}}</output>
|
||||
<ask>Re-running will overwrite the existing PRD. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Discovery - Project, Domain, and Vision">
|
||||
<action>Welcome {user_name} and begin comprehensive discovery, and then start to GATHER ALL CONTEXT:
|
||||
1. Check workflow-status.yaml for project_context (if exists)
|
||||
2. Look for existing documents (Product Brief, Domain Brief, research)
|
||||
3. Detect project type AND domain complexity
|
||||
|
||||
Load references:
|
||||
{installed_path}/project-types.csv
|
||||
{installed_path}/domain-complexity.csv
|
||||
|
||||
Through natural conversation:
|
||||
"Tell me about what you want to build - what problem does it solve and for whom?"
|
||||
|
||||
DUAL DETECTION:
|
||||
Project type signals: API, mobile, web, CLI, SDK, SaaS
|
||||
Domain complexity signals: medical, finance, government, education, aerospace
|
||||
|
||||
SPECIAL ROUTING:
|
||||
If game detected → Suggest game-brief and GDD workflows
|
||||
If complex domain detected → Offer domain research options:
|
||||
A) Run domain-research workflow (thorough)
|
||||
B) Quick web search (basic)
|
||||
C) User provides context
|
||||
D) Continue with general knowledge
|
||||
|
||||
CAPTURE THE MAGIC EARLY with a few questions such as for example: "What excites you most about this product?", "What would make users love this?", "What's the moment that will make people go 'wow'?"
|
||||
|
||||
This excitement becomes the thread woven throughout the PRD.</action>
|
||||
|
||||
<template-output>vision_alignment</template-output>
|
||||
<template-output>project_classification</template-output>
|
||||
<template-output>project_type</template-output>
|
||||
<template-output>domain_type</template-output>
|
||||
<template-output>complexity_level</template-output>
|
||||
<check if="complex domain">
|
||||
<template-output>domain_context_summary</template-output>
|
||||
</check>
|
||||
<template-output>product_magic_essence</template-output>
|
||||
<template-output>product_brief_path</template-output>
|
||||
<template-output>domain_brief_path</template-output>
|
||||
<template-output>research_documents</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Success Definition">
|
||||
<action>Define what winning looks like for THIS specific product
|
||||
|
||||
INTENT: Meaningful success criteria, not generic metrics
|
||||
|
||||
Adapt to context:
|
||||
|
||||
- Consumer: User love, engagement, retention
|
||||
- B2B: ROI, efficiency, adoption
|
||||
- Developer tools: Developer experience, community
|
||||
- Regulated: Compliance, safety, validation
|
||||
|
||||
Make it specific:
|
||||
|
||||
- NOT: "10,000 users"
|
||||
- BUT: "100 power users who rely on it daily"
|
||||
|
||||
- NOT: "99.9% uptime"
|
||||
- BUT: "Zero data loss during critical operations"
|
||||
|
||||
Weave in the magic:
|
||||
|
||||
- "Success means users experience [that special moment] and [desired outcome]"</action>
|
||||
|
||||
<template-output>success_criteria</template-output>
|
||||
<check if="business focus">
|
||||
<template-output>business_metrics</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Scope Definition">
|
||||
<action>Smart scope negotiation - find the sweet spot
|
||||
|
||||
The Scoping Game:
|
||||
|
||||
1. "What must work for this to be useful?" → MVP
|
||||
2. "What makes it competitive?" → Growth
|
||||
3. "What's the dream version?" → Vision
|
||||
|
||||
Challenge scope creep conversationally:
|
||||
|
||||
- "Could that wait until after launch?"
|
||||
- "Is that essential for proving the concept?"
|
||||
|
||||
For complex domains:
|
||||
|
||||
- Include compliance minimums in MVP
|
||||
- Note regulatory gates between phases</action>
|
||||
|
||||
<template-output>mvp_scope</template-output>
|
||||
<template-output>growth_features</template-output>
|
||||
<template-output>vision_features</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Domain-Specific Exploration" optional="true">
|
||||
<action>Only if complex domain detected or domain-brief exists
|
||||
|
||||
Synthesize domain requirements that will shape everything:
|
||||
|
||||
- Regulatory requirements
|
||||
- Compliance needs
|
||||
- Industry standards
|
||||
- Safety/risk factors
|
||||
- Required validations
|
||||
- Special expertise needed
|
||||
|
||||
These inform:
|
||||
|
||||
- What features are mandatory
|
||||
- What NFRs are critical
|
||||
- How to sequence development
|
||||
- What validation is required</action>
|
||||
|
||||
<check if="complex domain">
|
||||
<template-output>domain_considerations</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Innovation Discovery" optional="true">
|
||||
<action>Identify truly novel patterns if applicable
|
||||
|
||||
Listen for innovation signals:
|
||||
|
||||
- "Nothing like this exists"
|
||||
- "We're rethinking how [X] works"
|
||||
- "Combining [A] with [B] for the first time"
|
||||
|
||||
Explore deeply:
|
||||
|
||||
- What makes it unique?
|
||||
- What assumption are you challenging?
|
||||
- How do we validate it?
|
||||
- What's the fallback?
|
||||
|
||||
<WebSearch if="novel">{concept} innovations {date}</WebSearch></action>
|
||||
|
||||
<check if="innovation detected">
|
||||
<template-output>innovation_patterns</template-output>
|
||||
<template-output>validation_approach</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Project-Specific Deep Dive">
|
||||
<action>Based on detected project type, dive deep into specific needs
|
||||
|
||||
Load project type requirements from CSV and expand naturally.
|
||||
|
||||
FOR API/BACKEND:
|
||||
|
||||
- Map out endpoints, methods, parameters
|
||||
- Define authentication and authorization
|
||||
- Specify error codes and rate limits
|
||||
- Document data schemas
|
||||
|
||||
FOR MOBILE:
|
||||
|
||||
- Platform requirements (iOS/Android/both)
|
||||
- Device features needed
|
||||
- Offline capabilities
|
||||
- Store compliance
|
||||
|
||||
FOR SAAS B2B:
|
||||
|
||||
- Multi-tenant architecture
|
||||
- Permission models
|
||||
- Subscription tiers
|
||||
- Critical integrations
|
||||
|
||||
[Continue for other types...]
|
||||
|
||||
Always relate back to the product magic:
|
||||
"How does [requirement] enhance [the special thing]?"</action>
|
||||
|
||||
<template-output>project_type_requirements</template-output>
|
||||
|
||||
<!-- Dynamic sections based on project type -->
|
||||
<check if="API/Backend project">
|
||||
<template-output>endpoint_specification</template-output>
|
||||
<template-output>authentication_model</template-output>
|
||||
</check>
|
||||
|
||||
<check if="Mobile project">
|
||||
<template-output>platform_requirements</template-output>
|
||||
<template-output>device_features</template-output>
|
||||
</check>
|
||||
|
||||
<check if="SaaS B2B project">
|
||||
<template-output>tenant_model</template-output>
|
||||
<template-output>permission_matrix</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="UX Principles" optional="true">
|
||||
<action>Only if product has a UI
|
||||
|
||||
Light touch on UX - not full design:
|
||||
|
||||
- Visual personality
|
||||
- Key interaction patterns
|
||||
- Critical user flows
|
||||
|
||||
"How should this feel to use?"
|
||||
"What's the vibe - professional, playful, minimal?"
|
||||
|
||||
Connect to the magic:
|
||||
"The UI should reinforce [the special moment] through [design approach]"</action>
|
||||
|
||||
<check if="has UI">
|
||||
<template-output>ux_principles</template-output>
|
||||
<template-output>key_interactions</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Functional Requirements Synthesis">
|
||||
<action>Transform everything discovered into clear functional requirements
|
||||
|
||||
Pull together:
|
||||
|
||||
- Core features from scope
|
||||
- Domain-mandated features
|
||||
- Project-type specific needs
|
||||
- Innovation requirements
|
||||
|
||||
Organize by capability, not technology:
|
||||
|
||||
- User Management (not "auth system")
|
||||
- Content Discovery (not "search algorithm")
|
||||
- Team Collaboration (not "websockets")
|
||||
|
||||
Each requirement should:
|
||||
|
||||
- Be specific and measurable
|
||||
- Connect to user value
|
||||
- Include acceptance criteria
|
||||
- Note domain constraints
|
||||
|
||||
The magic thread:
|
||||
Highlight which requirements deliver the special experience</action>
|
||||
|
||||
<template-output>functional_requirements_complete</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Non-Functional Requirements Discovery">
|
||||
<action>Only document NFRs that matter for THIS product
|
||||
|
||||
Performance: Only if user-facing impact
|
||||
Security: Only if handling sensitive data
|
||||
Scale: Only if growth expected
|
||||
Accessibility: Only if broad audience
|
||||
Integration: Only if connecting systems
|
||||
|
||||
For each NFR:
|
||||
|
||||
- Why it matters for THIS product
|
||||
- Specific measurable criteria
|
||||
- Domain-driven requirements
|
||||
|
||||
Skip categories that don't apply!</action>
|
||||
|
||||
<!-- Only output sections that were discussed -->
|
||||
<check if="performance matters">
|
||||
<template-output>performance_requirements</template-output>
|
||||
</check>
|
||||
<check if="security matters">
|
||||
<template-output>security_requirements</template-output>
|
||||
</check>
|
||||
<check if="scale matters">
|
||||
<template-output>scalability_requirements</template-output>
|
||||
</check>
|
||||
<check if="accessibility matters">
|
||||
<template-output>accessibility_requirements</template-output>
|
||||
</check>
|
||||
<check if="integration matters">
|
||||
<template-output>integration_requirements</template-output>
|
||||
</check>
|
||||
<check if="no NFRs discussed">
|
||||
<template-output>no_nfrs</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Review PRD and transition to epics">
|
||||
<action>Review the PRD we've built together
|
||||
|
||||
"Let's review what we've captured:
|
||||
|
||||
- Vision: [summary]
|
||||
- Success: [key metrics]
|
||||
- Scope: [MVP highlights]
|
||||
- Requirements: [count] functional, [count] non-functional
|
||||
- Special considerations: [domain/innovation]
|
||||
|
||||
Does this capture your product vision?"
|
||||
|
||||
After confirmation:
|
||||
"Excellent! Now we need to break these requirements into implementable epics and stories.
|
||||
|
||||
For the epic breakdown, you have two options:
|
||||
|
||||
1. Start a new session focused on epics (recommended for complex projects)
|
||||
2. Continue here (I'll transform requirements into epics now)
|
||||
|
||||
Which would you prefer?"
|
||||
|
||||
If new session:
|
||||
"To start epic planning in a new session:
|
||||
|
||||
1. Save your work here
|
||||
2. Start fresh and run: workflow epics-stories
|
||||
3. It will load your PRD and create the epic breakdown
|
||||
|
||||
This keeps each session focused and manageable."
|
||||
|
||||
If continue:
|
||||
"Let's continue with epic breakdown here..."
|
||||
[Proceed with epics-stories subworkflow]
|
||||
Set project_level and target_scale based on project analysis
|
||||
Generate epic_details for the epics breakdown document</action>
|
||||
|
||||
<template-output>prd_summary</template-output>
|
||||
<template-output>project_level</template-output>
|
||||
<template-output>target_scale</template-output>
|
||||
<template-output>epic_details</template-output>
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Complete PRD and suggest next steps">
|
||||
<template-output>product_magic_summary</template-output>
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {status_file}</action>
|
||||
<action>Update workflow_status["prd"] = "{default_output_file}"</action>
|
||||
<action>Save file, preserving ALL comments and structure</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ PRD Complete, {user_name}!**
|
||||
|
||||
Your product requirements are documented and ready for implementation.
|
||||
|
||||
**Created:**
|
||||
|
||||
- **PRD.md** - Complete requirements adapted to {project_type} and {domain}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. **Epic Breakdown** (Required)
|
||||
Run: `workflow create-epics-and-stories` to decompose requirements into implementable stories
|
||||
|
||||
2. **UX Design** (If UI exists)
|
||||
Run: `workflow ux-design` for detailed user experience design
|
||||
|
||||
3. **Architecture** (Recommended)
|
||||
Run: `workflow create-architecture` for technical architecture decisions
|
||||
|
||||
The magic of your product - {product_magic_summary} - is woven throughout the PRD and will guide all subsequent work.
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
237
bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md
Normal file
237
bmad/bmm/workflows/2-plan-workflows/prd/prd-template.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# {{project_name}} - Product Requirements Document
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Version:** 1.0
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{vision_alignment}}
|
||||
|
||||
### What Makes This Special
|
||||
|
||||
{{product_magic_essence}}
|
||||
|
||||
---
|
||||
|
||||
## Project Classification
|
||||
|
||||
**Technical Type:** {{project_type}}
|
||||
**Domain:** {{domain_type}}
|
||||
**Complexity:** {{complexity_level}}
|
||||
|
||||
{{project_classification}}
|
||||
|
||||
{{#if domain_context_summary}}
|
||||
|
||||
### Domain Context
|
||||
|
||||
{{domain_context_summary}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{{success_criteria}}
|
||||
|
||||
{{#if business_metrics}}
|
||||
|
||||
### Business Metrics
|
||||
|
||||
{{business_metrics}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Product Scope
|
||||
|
||||
### MVP - Minimum Viable Product
|
||||
|
||||
{{mvp_scope}}
|
||||
|
||||
### Growth Features (Post-MVP)
|
||||
|
||||
{{growth_features}}
|
||||
|
||||
### Vision (Future)
|
||||
|
||||
{{vision_features}}
|
||||
|
||||
---
|
||||
|
||||
{{#if domain_considerations}}
|
||||
|
||||
## Domain-Specific Requirements
|
||||
|
||||
{{domain_considerations}}
|
||||
|
||||
This section shapes all functional and non-functional requirements below.
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
{{#if innovation_patterns}}
|
||||
|
||||
## Innovation & Novel Patterns
|
||||
|
||||
{{innovation_patterns}}
|
||||
|
||||
### Validation Approach
|
||||
|
||||
{{validation_approach}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
{{#if project_type_requirements}}
|
||||
|
||||
## {{project_type}} Specific Requirements
|
||||
|
||||
{{project_type_requirements}}
|
||||
|
||||
{{#if endpoint_specification}}
|
||||
|
||||
### API Specification
|
||||
|
||||
{{endpoint_specification}}
|
||||
{{/if}}
|
||||
|
||||
{{#if authentication_model}}
|
||||
|
||||
### Authentication & Authorization
|
||||
|
||||
{{authentication_model}}
|
||||
{{/if}}
|
||||
|
||||
{{#if platform_requirements}}
|
||||
|
||||
### Platform Support
|
||||
|
||||
{{platform_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if device_features}}
|
||||
|
||||
### Device Capabilities
|
||||
|
||||
{{device_features}}
|
||||
{{/if}}
|
||||
|
||||
{{#if tenant_model}}
|
||||
|
||||
### Multi-Tenancy Architecture
|
||||
|
||||
{{tenant_model}}
|
||||
{{/if}}
|
||||
|
||||
{{#if permission_matrix}}
|
||||
|
||||
### Permissions & Roles
|
||||
|
||||
{{permission_matrix}}
|
||||
{{/if}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
{{#if ux_principles}}
|
||||
|
||||
## User Experience Principles
|
||||
|
||||
{{ux_principles}}
|
||||
|
||||
### Key Interactions
|
||||
|
||||
{{key_interactions}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
{{functional_requirements_complete}}
|
||||
|
||||
---
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
{{#if performance_requirements}}
|
||||
|
||||
### Performance
|
||||
|
||||
{{performance_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if security_requirements}}
|
||||
|
||||
### Security
|
||||
|
||||
{{security_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if scalability_requirements}}
|
||||
|
||||
### Scalability
|
||||
|
||||
{{scalability_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if accessibility_requirements}}
|
||||
|
||||
### Accessibility
|
||||
|
||||
{{accessibility_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if integration_requirements}}
|
||||
|
||||
### Integration
|
||||
|
||||
{{integration_requirements}}
|
||||
{{/if}}
|
||||
|
||||
{{#if no_nfrs}}
|
||||
_No specific non-functional requirements identified for this project type._
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Planning
|
||||
|
||||
### Epic Breakdown Required
|
||||
|
||||
Requirements must be decomposed into epics and bite-sized stories (200k context limit).
|
||||
|
||||
**Next Step:** Run `workflow epics-stories` to create the implementation breakdown.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
{{#if product_brief_path}}
|
||||
|
||||
- Product Brief: {{product_brief_path}}
|
||||
{{/if}}
|
||||
{{#if domain_brief_path}}
|
||||
- Domain Brief: {{domain_brief_path}}
|
||||
{{/if}}
|
||||
{{#if research_documents}}
|
||||
- Research: {{research_documents}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Epic & Story Breakdown** - Run: `workflow epics-stories`
|
||||
2. **UX Design** (if UI) - Run: `workflow ux-design`
|
||||
3. **Architecture** - Run: `workflow create-architecture`
|
||||
|
||||
---
|
||||
|
||||
_This PRD captures the essence of {{project_name}} - {{product_magic_summary}}_
|
||||
|
||||
_Created through collaborative discovery between {{user_name}} and AI facilitator._
|
||||
11
bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv
Normal file
11
bmad/bmm/workflows/2-plan-workflows/prd/project-types.csv
Normal file
@@ -0,0 +1,11 @@
|
||||
project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
|
||||
api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
|
||||
mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
|
||||
saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
|
||||
developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
|
||||
cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
|
||||
web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
|
||||
game,"game,player,gameplay,level,character","REDIRECT TO GAME WORKFLOWS","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
|
||||
desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
|
||||
iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
|
||||
blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"
|
||||
|
46
bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml
Normal file
46
bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml
Normal file
@@ -0,0 +1,46 @@
|
||||
# Product Requirements Document (PRD) Workflow
|
||||
name: prd
|
||||
description: "Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow."
|
||||
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
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
|
||||
# Templates
|
||||
prd_template: "{installed_path}/prd-template.md"
|
||||
|
||||
# Output files
|
||||
status_file: "{output_folder}/bmm-workflow-status.yaml"
|
||||
default_output_file: "{output_folder}/PRD.md"
|
||||
|
||||
# Recommended input documents
|
||||
recommended_inputs:
|
||||
- product_brief: "{output_folder}/product-brief.md"
|
||||
- market_research: "{output_folder}/market-research.md"
|
||||
|
||||
# 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
|
||||
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
|
||||
1
bmad/bmm/workflows/3-solutioning/README.md
Normal file
1
bmad/bmm/workflows/3-solutioning/README.md
Normal file
@@ -0,0 +1 @@
|
||||
New Doc Incoming...
|
||||
318
bmad/bmm/workflows/3-solutioning/architecture/README.md
Normal file
318
bmad/bmm/workflows/3-solutioning/architecture/README.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Decision Architecture Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
The Decision Architecture workflow is a complete reimagining of how architectural decisions are made in the BMAD Method. Instead of template-driven documentation, this workflow facilitates an intelligent conversation that produces a **decision-focused architecture document** optimized for preventing AI agent conflicts during implementation.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
**The Problem**: When multiple AI agents implement different parts of a system, they make conflicting technical decisions leading to incompatible implementations.
|
||||
|
||||
**The Solution**: A "consistency contract" that documents all critical technical decisions upfront, ensuring every agent follows the same patterns and uses the same technologies.
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Starter Template Intelligence ⭐ NEW
|
||||
|
||||
- Discovers relevant starter templates (create-next-app, create-t3-app, etc.)
|
||||
- Considers UX requirements when selecting templates (animations, accessibility, etc.)
|
||||
- Searches for current CLI options and defaults
|
||||
- Documents decisions made BY the starter template
|
||||
- Makes remaining architectural decisions around the starter foundation
|
||||
- First implementation story becomes "initialize with starter command"
|
||||
|
||||
### 2. Adaptive Facilitation
|
||||
|
||||
- Adjusts conversation style based on user skill level (beginner/intermediate/expert)
|
||||
- Experts get rapid, technical discussions
|
||||
- Beginners receive education and protection from complexity
|
||||
- Everyone produces the same high-quality output
|
||||
|
||||
### 3. Dynamic Version Verification
|
||||
|
||||
- NEVER trusts hardcoded version numbers
|
||||
- Uses WebSearch to find current stable versions
|
||||
- Verifies versions during the conversation
|
||||
- Documents only verified, current versions
|
||||
|
||||
### 4. Intelligent Discovery
|
||||
|
||||
- No rigid project type templates
|
||||
- Analyzes PRD to identify which decisions matter for THIS project
|
||||
- Uses knowledge base of decisions and patterns
|
||||
- Scales to infinite project types
|
||||
|
||||
### 5. Collaborative Decision Making
|
||||
|
||||
- Facilitates discussion for each critical decision
|
||||
- Presents options with trade-offs
|
||||
- Integrates advanced elicitation for innovative approaches
|
||||
- Ensures decisions are coherent and compatible
|
||||
|
||||
### 6. Consistent Output
|
||||
|
||||
- Structured decision collection during conversation
|
||||
- Strict document generation from collected decisions
|
||||
- Validated against hard requirements
|
||||
- Optimized for AI agent consumption
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
```
|
||||
Step 0: Validate workflow and extract project configuration
|
||||
Step 0.5: Validate workflow sequencing
|
||||
Step 1: Load PRD and understand project context
|
||||
Step 2: Discover and evaluate starter templates ⭐ NEW
|
||||
Step 3: Adapt facilitation style and identify remaining decisions
|
||||
Step 4: Facilitate collaborative decision making (with version verification)
|
||||
Step 5: Address cross-cutting concerns
|
||||
Step 6: Define project structure and boundaries
|
||||
Step 7: Design novel architectural patterns (when needed) ⭐ NEW
|
||||
Step 8: Define implementation patterns to prevent agent conflicts
|
||||
Step 9: Validate architectural coherence
|
||||
Step 10: Generate decision architecture document (with initialization commands)
|
||||
Step 11: Validate document completeness
|
||||
Step 12: Final review and update workflow status
|
||||
```
|
||||
|
||||
## Files in This Workflow
|
||||
|
||||
- **workflow.yaml** - Configuration and metadata
|
||||
- **instructions.md** - The adaptive facilitation flow
|
||||
- **decision-catalog.yaml** - Knowledge base of all architectural decisions
|
||||
- **architecture-patterns.yaml** - Common patterns identified from requirements
|
||||
- **pattern-categories.csv** - Pattern principles that teach LLM what needs defining
|
||||
- **checklist.md** - Validation requirements for the output document
|
||||
- **architecture-template.md** - Strict format for the final document
|
||||
|
||||
## How It's Different from Old architecture
|
||||
|
||||
| Aspect | Old Workflow | New Workflow |
|
||||
| -------------------- | -------------------------------------------- | ----------------------------------------------- |
|
||||
| **Approach** | Template-driven | Conversation-driven |
|
||||
| **Project Types** | 11 rigid types with 22+ files | Infinite flexibility with intelligent discovery |
|
||||
| **User Interaction** | Output sections with "Continue?" | Collaborative decision facilitation |
|
||||
| **Skill Adaptation** | One-size-fits-all | Adapts to beginner/intermediate/expert |
|
||||
| **Decision Making** | Late in process (Step 5) | Upfront and central focus |
|
||||
| **Output** | Multiple documents including faux tech-specs | Single decision-focused architecture |
|
||||
| **Time** | Confusing and slow | 30-90 minutes depending on skill level |
|
||||
| **Elicitation** | Never used | Integrated at decision points |
|
||||
|
||||
## Expected Inputs
|
||||
|
||||
- **PRD** (Product Requirements Document) with:
|
||||
- Functional Requirements
|
||||
- Non-Functional Requirements
|
||||
- Performance and compliance needs
|
||||
|
||||
- **Epics** file with:
|
||||
- User stories
|
||||
- Acceptance criteria
|
||||
- Dependencies
|
||||
|
||||
- **UX Spec** (Optional but valuable) with:
|
||||
- Interface designs and interaction patterns
|
||||
- Accessibility requirements (WCAG levels)
|
||||
- Animation and transition needs
|
||||
- Platform-specific UI requirements
|
||||
- Performance expectations for interactions
|
||||
|
||||
## Output Document
|
||||
|
||||
A single `architecture.md` file containing:
|
||||
|
||||
- Executive summary (2-3 sentences)
|
||||
- Project initialization command (if using starter template)
|
||||
- Decision summary table with verified versions and epic mapping
|
||||
- Complete project structure
|
||||
- Integration specifications
|
||||
- Consistency rules for AI agents
|
||||
|
||||
## How Novel Pattern Design Works
|
||||
|
||||
Step 7 handles unique or complex patterns that need to be INVENTED:
|
||||
|
||||
1. **Detection**:
|
||||
The workflow analyzes the PRD for concepts that don't have standard solutions:
|
||||
- Novel interaction patterns (e.g., "swipe to match" when Tinder doesn't exist)
|
||||
- Complex multi-epic workflows (e.g., "viral invitation system")
|
||||
- Unique data relationships (e.g., "social graph" before Facebook)
|
||||
- New paradigms (e.g., "ephemeral messages" before Snapchat)
|
||||
|
||||
2. **Design Collaboration**:
|
||||
Instead of just picking technologies, the workflow helps DESIGN the solution:
|
||||
- Identifies the core problem to solve
|
||||
- Explores different approaches with the user
|
||||
- Documents how components interact
|
||||
- Creates sequence diagrams for complex flows
|
||||
- Uses elicitation to find innovative solutions
|
||||
|
||||
3. **Documentation**:
|
||||
Novel patterns become part of the architecture with:
|
||||
- Pattern name and purpose
|
||||
- Component interactions
|
||||
- Data flow diagrams
|
||||
- Which epics/stories are affected
|
||||
- Implementation guidance for agents
|
||||
|
||||
4. **Example**:
|
||||
```
|
||||
PRD: "Users can create 'circles' of friends with overlapping membership"
|
||||
↓
|
||||
Workflow detects: This is a novel social structure pattern
|
||||
↓
|
||||
Designs with user: Circle membership model, permission cascading, UI patterns
|
||||
↓
|
||||
Documents: "Circle Pattern" with component design and data flow
|
||||
↓
|
||||
All agents understand how to implement circle-related features consistently
|
||||
```
|
||||
|
||||
## How Implementation Patterns Work
|
||||
|
||||
Step 8 prevents agent conflicts by defining patterns for consistency:
|
||||
|
||||
1. **The Core Principle**:
|
||||
|
||||
> "Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture"
|
||||
|
||||
The LLM asks: "What could an agent encounter where they'd have to guess?"
|
||||
|
||||
2. **Pattern Categories** (principles, not prescriptions):
|
||||
- **Naming**: How things are named (APIs, database fields, files)
|
||||
- **Structure**: How things are organized (folders, modules, layers)
|
||||
- **Format**: How data is formatted (JSON structures, responses)
|
||||
- **Communication**: How components talk (events, messages, protocols)
|
||||
- **Lifecycle**: How states change (workflows, transitions)
|
||||
- **Location**: Where things go (URLs, paths, storage)
|
||||
- **Consistency**: Cross-cutting concerns (dates, errors, logs)
|
||||
|
||||
3. **LLM Intelligence**:
|
||||
- Uses the principle to identify patterns beyond the 7 categories
|
||||
- Figures out what specific patterns matter for chosen tech
|
||||
- Only asks about patterns that could cause conflicts
|
||||
- Skips obvious patterns that the tech choice determines
|
||||
|
||||
4. **Example**:
|
||||
```
|
||||
Tech chosen: REST API + PostgreSQL + React
|
||||
↓
|
||||
LLM identifies needs:
|
||||
- REST: URL structure, response format, status codes
|
||||
- PostgreSQL: table naming, column naming, FK patterns
|
||||
- React: component structure, state management, test location
|
||||
↓
|
||||
Facilitates each with user
|
||||
↓
|
||||
Documents as Implementation Patterns in architecture
|
||||
```
|
||||
|
||||
## How Starter Templates Work
|
||||
|
||||
When the workflow detects a project type that has a starter template:
|
||||
|
||||
1. **Discovery**: Searches for relevant starter templates based on PRD
|
||||
2. **Investigation**: Looks up current CLI options and defaults
|
||||
3. **Presentation**: Shows user what the starter provides
|
||||
4. **Integration**: Documents starter decisions as "PROVIDED BY STARTER"
|
||||
5. **Continuation**: Only asks about decisions NOT made by starter
|
||||
6. **Documentation**: Includes exact initialization command in architecture
|
||||
|
||||
### Example Flow
|
||||
|
||||
```
|
||||
PRD says: "Next.js web application with authentication"
|
||||
↓
|
||||
Workflow finds: create-next-app and create-t3-app
|
||||
↓
|
||||
User chooses: create-t3-app (includes auth setup)
|
||||
↓
|
||||
Starter provides: Next.js, TypeScript, tRPC, Prisma, NextAuth, Tailwind
|
||||
↓
|
||||
Workflow only asks about: Database choice, deployment target, additional services
|
||||
↓
|
||||
First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# In your BMAD-enabled project
|
||||
workflow architecture
|
||||
```
|
||||
|
||||
The AI agent will:
|
||||
|
||||
1. Load your PRD and epics
|
||||
2. Identify critical decisions needed
|
||||
3. Facilitate discussion on each decision
|
||||
4. Generate a comprehensive architecture document
|
||||
5. Validate completeness
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates
|
||||
2. **Intelligence over Templates** - Use AI understanding rather than rigid structures
|
||||
3. **Decisions over Details** - Focus on what prevents agent conflicts, not implementation minutiae
|
||||
4. **Adaptation over Uniformity** - Meet users where they are while ensuring quality output
|
||||
5. **Collaboration over Output** - The conversation matters as much as the document
|
||||
|
||||
## For Developers
|
||||
|
||||
This workflow assumes:
|
||||
|
||||
- Single developer + AI agents (not teams)
|
||||
- Speed matters (decisions in minutes, not days)
|
||||
- AI agents need clear constraints to prevent conflicts
|
||||
- The architecture document is for agents, not humans
|
||||
|
||||
## Migration from architecture
|
||||
|
||||
Projects using the old `architecture` workflow should:
|
||||
|
||||
1. Complete any in-progress architecture work
|
||||
2. Use `architecture` for new projects
|
||||
3. The old workflow remains available but is deprecated
|
||||
|
||||
## Version
|
||||
|
||||
1.3.2 - UX specification integration and fuzzy file matching
|
||||
|
||||
- Added UX spec as optional input with fuzzy file matching
|
||||
- Updated workflow.yaml with input file references
|
||||
- Starter template selection now considers UX requirements
|
||||
- Added UX alignment validation to checklist
|
||||
- Instructions use variable references for flexible file names
|
||||
|
||||
1.3.1 - Workflow refinement and standardization
|
||||
|
||||
- Added workflow status checking at start (Steps 0 and 0.5)
|
||||
- Added workflow status updating at end (Step 12)
|
||||
- Reorganized step numbering for clarity (removed fractional steps)
|
||||
- Enhanced with intent-based approach throughout
|
||||
- Improved cohesiveness across all workflow components
|
||||
|
||||
1.3.0 - Novel pattern design for unique architectures
|
||||
|
||||
- Added novel pattern design (now Step 7, formerly Step 5.3)
|
||||
- Detects novel concepts in PRD that need architectural invention
|
||||
- Facilitates design collaboration with sequence diagrams
|
||||
- Uses elicitation for innovative approaches
|
||||
- Documents custom patterns for multi-epic consistency
|
||||
|
||||
1.2.0 - Implementation patterns for agent consistency
|
||||
|
||||
- Added implementation patterns (now Step 8, formerly Step 5.5)
|
||||
- Created principle-based pattern-categories.csv (7 principles, not 118 prescriptions)
|
||||
- Core principle: "What could agents decide differently?"
|
||||
- LLM uses principle to identify patterns beyond the categories
|
||||
- Prevents agent conflicts through intelligent pattern discovery
|
||||
|
||||
1.1.0 - Enhanced with starter template discovery and version verification
|
||||
|
||||
- Added intelligent starter template detection and integration (now Step 2)
|
||||
- Added dynamic version verification via web search
|
||||
- Starter decisions are documented as "PROVIDED BY STARTER"
|
||||
- First implementation story uses starter initialization command
|
||||
|
||||
1.0.0 - Initial release replacing architecture workflow
|
||||
@@ -0,0 +1,347 @@
|
||||
# Architecture Patterns - Common patterns identified from requirements
|
||||
|
||||
requirement_patterns:
|
||||
realtime_collaboration:
|
||||
triggers:
|
||||
- "real-time"
|
||||
- "collaborative"
|
||||
- "live updates"
|
||||
- "multi-user"
|
||||
- "simultaneous editing"
|
||||
decisions_needed:
|
||||
- websocket_solution
|
||||
- conflict_resolution
|
||||
- state_synchronization
|
||||
- presence_tracking
|
||||
- optimistic_updates
|
||||
suggested_stack:
|
||||
- "Socket.io or WebSocket native"
|
||||
- "Redis for pub/sub"
|
||||
- "Operational Transforms or CRDTs for conflict resolution"
|
||||
- "PostgreSQL for persistence"
|
||||
|
||||
ecommerce:
|
||||
triggers:
|
||||
- "shopping cart"
|
||||
- "checkout"
|
||||
- "payments"
|
||||
- "inventory"
|
||||
- "product catalog"
|
||||
decisions_needed:
|
||||
- payment_processor
|
||||
- cart_persistence
|
||||
- inventory_management
|
||||
- order_workflow
|
||||
- tax_calculation
|
||||
suggested_stack:
|
||||
- "Stripe or PayPal for payments"
|
||||
- "PostgreSQL for products and orders"
|
||||
- "Redis for cart sessions"
|
||||
- "BullMQ for order processing"
|
||||
|
||||
saas_platform:
|
||||
triggers:
|
||||
- "multi-tenant"
|
||||
- "subscription"
|
||||
- "billing"
|
||||
- "team management"
|
||||
- "roles and permissions"
|
||||
decisions_needed:
|
||||
- tenancy_model
|
||||
- subscription_billing
|
||||
- permission_system
|
||||
- team_collaboration
|
||||
- usage_tracking
|
||||
suggested_stack:
|
||||
- "PostgreSQL with Row Level Security"
|
||||
- "Stripe Billing for subscriptions"
|
||||
- "RBAC or ABAC for permissions"
|
||||
- "NextAuth or Clerk for auth"
|
||||
|
||||
content_platform:
|
||||
triggers:
|
||||
- "CMS"
|
||||
- "blog"
|
||||
- "publishing"
|
||||
- "content management"
|
||||
- "editorial workflow"
|
||||
decisions_needed:
|
||||
- content_storage
|
||||
- rich_text_editor
|
||||
- media_handling
|
||||
- version_control
|
||||
- publishing_workflow
|
||||
suggested_stack:
|
||||
- "PostgreSQL for structured content"
|
||||
- "S3 or Cloudinary for media"
|
||||
- "Tiptap or Slate for rich text"
|
||||
- "Algolia for search"
|
||||
|
||||
data_analytics:
|
||||
triggers:
|
||||
- "dashboards"
|
||||
- "reporting"
|
||||
- "metrics"
|
||||
- "analytics"
|
||||
- "data visualization"
|
||||
decisions_needed:
|
||||
- data_warehouse
|
||||
- etl_pipeline
|
||||
- visualization_library
|
||||
- query_optimization
|
||||
- caching_strategy
|
||||
suggested_stack:
|
||||
- "PostgreSQL or ClickHouse"
|
||||
- "Apache Airflow or Temporal for ETL"
|
||||
- "Chart.js or D3 for visualization"
|
||||
- "Redis for query caching"
|
||||
|
||||
social_platform:
|
||||
triggers:
|
||||
- "social network"
|
||||
- "feed"
|
||||
- "following"
|
||||
- "likes"
|
||||
- "comments"
|
||||
decisions_needed:
|
||||
- graph_relationships
|
||||
- feed_algorithm
|
||||
- notification_system
|
||||
- content_moderation
|
||||
- privacy_controls
|
||||
suggested_stack:
|
||||
- "PostgreSQL with graph extensions or Neo4j"
|
||||
- "Redis for feed caching"
|
||||
- "Elasticsearch for user search"
|
||||
- "WebSockets for notifications"
|
||||
|
||||
marketplace:
|
||||
triggers:
|
||||
- "marketplace"
|
||||
- "vendors"
|
||||
- "buyers and sellers"
|
||||
- "transactions"
|
||||
- "escrow"
|
||||
decisions_needed:
|
||||
- payment_splitting
|
||||
- escrow_handling
|
||||
- vendor_management
|
||||
- dispute_resolution
|
||||
- commission_model
|
||||
suggested_stack:
|
||||
- "Stripe Connect for payments"
|
||||
- "PostgreSQL for transactions"
|
||||
- "BullMQ for async processing"
|
||||
- "S3 for vendor assets"
|
||||
|
||||
streaming_platform:
|
||||
triggers:
|
||||
- "video streaming"
|
||||
- "live streaming"
|
||||
- "media delivery"
|
||||
- "broadcast"
|
||||
decisions_needed:
|
||||
- video_encoding
|
||||
- cdn_strategy
|
||||
- streaming_protocol
|
||||
- bandwidth_optimization
|
||||
- drm_protection
|
||||
suggested_stack:
|
||||
- "AWS MediaConvert or Mux"
|
||||
- "CloudFront or Fastly CDN"
|
||||
- "HLS or DASH protocol"
|
||||
- "S3 for video storage"
|
||||
|
||||
iot_platform:
|
||||
triggers:
|
||||
- "IoT"
|
||||
- "sensors"
|
||||
- "device management"
|
||||
- "telemetry"
|
||||
- "edge computing"
|
||||
decisions_needed:
|
||||
- message_protocol
|
||||
- time_series_database
|
||||
- device_authentication
|
||||
- data_ingestion
|
||||
- edge_processing
|
||||
suggested_stack:
|
||||
- "MQTT or CoAP protocol"
|
||||
- "TimescaleDB or InfluxDB"
|
||||
- "Apache Kafka for ingestion"
|
||||
- "Grafana for monitoring"
|
||||
|
||||
ai_application:
|
||||
triggers:
|
||||
- "machine learning"
|
||||
- "AI features"
|
||||
- "LLM integration"
|
||||
- "computer vision"
|
||||
- "NLP"
|
||||
decisions_needed:
|
||||
- model_serving
|
||||
- vector_database
|
||||
- prompt_management
|
||||
- token_optimization
|
||||
- fallback_strategy
|
||||
suggested_stack:
|
||||
- "OpenAI or Anthropic API"
|
||||
- "Pinecone or pgvector for embeddings"
|
||||
- "Redis for prompt caching"
|
||||
- "Langchain or LlamaIndex"
|
||||
|
||||
# Quality attribute patterns
|
||||
quality_attributes:
|
||||
high_availability:
|
||||
triggers:
|
||||
- "99.9% uptime"
|
||||
- "high availability"
|
||||
- "fault tolerance"
|
||||
- "disaster recovery"
|
||||
architectural_needs:
|
||||
- load_balancing
|
||||
- database_replication
|
||||
- health_checks
|
||||
- circuit_breakers
|
||||
- graceful_degradation
|
||||
|
||||
high_performance:
|
||||
triggers:
|
||||
- "millisecond response"
|
||||
- "high throughput"
|
||||
- "low latency"
|
||||
- "performance critical"
|
||||
architectural_needs:
|
||||
- caching_layers
|
||||
- database_optimization
|
||||
- cdn_strategy
|
||||
- code_splitting
|
||||
- lazy_loading
|
||||
|
||||
high_security:
|
||||
triggers:
|
||||
- "compliance"
|
||||
- "HIPAA"
|
||||
- "GDPR"
|
||||
- "financial data"
|
||||
- "PCI DSS"
|
||||
architectural_needs:
|
||||
- encryption_at_rest
|
||||
- encryption_in_transit
|
||||
- audit_logging
|
||||
- access_controls
|
||||
- data_isolation
|
||||
|
||||
scalability:
|
||||
triggers:
|
||||
- "millions of users"
|
||||
- "elastic scale"
|
||||
- "global reach"
|
||||
- "viral growth"
|
||||
architectural_needs:
|
||||
- horizontal_scaling
|
||||
- database_sharding
|
||||
- microservices
|
||||
- queue_systems
|
||||
- auto_scaling
|
||||
|
||||
# Integration patterns
|
||||
integration_requirements:
|
||||
payment_processing:
|
||||
common_choices:
|
||||
- "Stripe - most developer friendly"
|
||||
- "PayPal - widest consumer adoption"
|
||||
- "Square - best for in-person + online"
|
||||
considerations:
|
||||
- transaction_fees
|
||||
- international_support
|
||||
- subscription_handling
|
||||
- marketplace_capabilities
|
||||
|
||||
email_service:
|
||||
common_choices:
|
||||
- "Resend - modern, developer friendly"
|
||||
- "SendGrid - mature, scalable"
|
||||
- "Amazon SES - cost effective at scale"
|
||||
- "Postmark - transactional focus"
|
||||
considerations:
|
||||
- deliverability
|
||||
- template_management
|
||||
- analytics_needs
|
||||
- cost_per_email
|
||||
|
||||
sms_notifications:
|
||||
common_choices:
|
||||
- "Twilio - most comprehensive"
|
||||
- "Amazon SNS - AWS integrated"
|
||||
- "Vonage - competitive pricing"
|
||||
considerations:
|
||||
- international_coverage
|
||||
- delivery_rates
|
||||
- two_way_messaging
|
||||
- cost_per_message
|
||||
|
||||
authentication_providers:
|
||||
social_providers:
|
||||
- "Google - highest adoption"
|
||||
- "GitHub - developer focused"
|
||||
- "Microsoft - enterprise"
|
||||
- "Apple - iOS users"
|
||||
enterprise_providers:
|
||||
- "SAML 2.0"
|
||||
- "OAuth 2.0"
|
||||
- "OpenID Connect"
|
||||
- "Active Directory"
|
||||
|
||||
# Decision heuristics
|
||||
decision_rules:
|
||||
database_selection:
|
||||
if_requirements_include:
|
||||
- complex_relationships: "PostgreSQL"
|
||||
- flexible_schema: "MongoDB"
|
||||
- time_series: "TimescaleDB"
|
||||
- graph_data: "Neo4j or PostgreSQL with extensions"
|
||||
- key_value: "Redis"
|
||||
- wide_column: "Cassandra"
|
||||
|
||||
api_pattern_selection:
|
||||
if_requirements_include:
|
||||
- simple_crud: "REST"
|
||||
- complex_queries: "GraphQL"
|
||||
- type_safety_critical: "tRPC"
|
||||
- microservices: "gRPC"
|
||||
- public_api: "REST with OpenAPI"
|
||||
|
||||
deployment_selection:
|
||||
if_requirements_include:
|
||||
- nextjs_only: "Vercel"
|
||||
- complex_infrastructure: "AWS"
|
||||
- quick_prototype: "Railway"
|
||||
- global_edge: "Fly.io"
|
||||
- kubernetes_needed: "GCP or AWS EKS"
|
||||
|
||||
# Anti-patterns to avoid
|
||||
anti_patterns:
|
||||
overengineering:
|
||||
signs:
|
||||
- "Microservices for < 10k users"
|
||||
- "Kubernetes for single app"
|
||||
- "GraphQL for 5 endpoints"
|
||||
- "Event sourcing for CRUD app"
|
||||
recommendation: "Start simple, evolve as needed"
|
||||
|
||||
underengineering:
|
||||
signs:
|
||||
- "No authentication strategy"
|
||||
- "No error handling plan"
|
||||
- "No monitoring approach"
|
||||
- "No backup strategy"
|
||||
recommendation: "Cover the fundamentals"
|
||||
|
||||
technology_soup:
|
||||
signs:
|
||||
- "5+ different databases"
|
||||
- "Multiple frontend frameworks"
|
||||
- "Inconsistent patterns"
|
||||
- "Too many languages"
|
||||
recommendation: "Maintain consistency"
|
||||
@@ -0,0 +1,103 @@
|
||||
# Architecture
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
{{project_initialization_section}}
|
||||
|
||||
## Decision Summary
|
||||
|
||||
| Category | Decision | Version | Affects Epics | Rationale |
|
||||
| -------- | -------- | ------- | ------------- | --------- |
|
||||
|
||||
{{decision_table_rows}}
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
{{project_root}}/
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## Epic to Architecture Mapping
|
||||
|
||||
{{epic_mapping_table}}
|
||||
|
||||
## Technology Stack Details
|
||||
|
||||
### Core Technologies
|
||||
|
||||
{{core_stack_details}}
|
||||
|
||||
### Integration Points
|
||||
|
||||
{{integration_details}}
|
||||
|
||||
{{novel_pattern_designs_section}}
|
||||
|
||||
## Implementation Patterns
|
||||
|
||||
These patterns ensure consistent implementation across all AI agents:
|
||||
|
||||
{{implementation_patterns}}
|
||||
|
||||
## Consistency Rules
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
{{naming_conventions}}
|
||||
|
||||
### Code Organization
|
||||
|
||||
{{code_organization_patterns}}
|
||||
|
||||
### Error Handling
|
||||
|
||||
{{error_handling_approach}}
|
||||
|
||||
### Logging Strategy
|
||||
|
||||
{{logging_approach}}
|
||||
|
||||
## Data Architecture
|
||||
|
||||
{{data_models_and_relationships}}
|
||||
|
||||
## API Contracts
|
||||
|
||||
{{api_specifications}}
|
||||
|
||||
## Security Architecture
|
||||
|
||||
{{security_approach}}
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
{{performance_strategies}}
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
{{deployment_approach}}
|
||||
|
||||
## Development Environment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
{{development_prerequisites}}
|
||||
|
||||
### Setup Commands
|
||||
|
||||
```bash
|
||||
{{setup_commands}}
|
||||
```
|
||||
|
||||
## Architecture Decision Records (ADRs)
|
||||
|
||||
{{key_architecture_decisions}}
|
||||
|
||||
---
|
||||
|
||||
_Generated by BMAD Decision Architecture Workflow v1.0_
|
||||
_Date: {{date}}_
|
||||
_For: {{user_name}}_
|
||||
244
bmad/bmm/workflows/3-solutioning/architecture/checklist.md
Normal file
244
bmad/bmm/workflows/3-solutioning/architecture/checklist.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Architecture Document Validation Checklist
|
||||
|
||||
**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
|
||||
|
||||
**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
|
||||
|
||||
---
|
||||
|
||||
## 1. Decision Completeness
|
||||
|
||||
### All Decisions Made
|
||||
|
||||
- [ ] Every critical decision category has been resolved
|
||||
- [ ] All important decision categories addressed
|
||||
- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
|
||||
- [ ] Optional decisions either resolved or explicitly deferred with rationale
|
||||
|
||||
### Decision Coverage
|
||||
|
||||
- [ ] Data persistence approach decided
|
||||
- [ ] API pattern chosen
|
||||
- [ ] Authentication/authorization strategy defined
|
||||
- [ ] Deployment target selected
|
||||
- [ ] All functional requirements have architectural support
|
||||
|
||||
---
|
||||
|
||||
## 2. Version Specificity
|
||||
|
||||
### Technology Versions
|
||||
|
||||
- [ ] Every technology choice includes a specific version number
|
||||
- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
|
||||
- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
|
||||
- [ ] Verification dates noted for version checks
|
||||
|
||||
### Version Verification Process
|
||||
|
||||
- [ ] WebSearch used during workflow to verify current versions
|
||||
- [ ] No hardcoded versions from decision catalog trusted without verification
|
||||
- [ ] LTS vs. latest versions considered and documented
|
||||
- [ ] Breaking changes between versions noted if relevant
|
||||
|
||||
---
|
||||
|
||||
## 3. Starter Template Integration (if applicable)
|
||||
|
||||
### Template Selection
|
||||
|
||||
- [ ] Starter template chosen (or "from scratch" decision documented)
|
||||
- [ ] Project initialization command documented with exact flags
|
||||
- [ ] Starter template version is current and specified
|
||||
- [ ] Command search term provided for verification
|
||||
|
||||
### Starter-Provided Decisions
|
||||
|
||||
- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
|
||||
- [ ] List of what starter provides is complete
|
||||
- [ ] Remaining decisions (not covered by starter) clearly identified
|
||||
- [ ] No duplicate decisions that starter already makes
|
||||
|
||||
---
|
||||
|
||||
## 4. Novel Pattern Design (if applicable)
|
||||
|
||||
### Pattern Detection
|
||||
|
||||
- [ ] All unique/novel concepts from PRD identified
|
||||
- [ ] Patterns that don't have standard solutions documented
|
||||
- [ ] Multi-epic workflows requiring custom design captured
|
||||
|
||||
### Pattern Documentation Quality
|
||||
|
||||
- [ ] Pattern name and purpose clearly defined
|
||||
- [ ] Component interactions specified
|
||||
- [ ] Data flow documented (with sequence diagrams if complex)
|
||||
- [ ] Implementation guide provided for agents
|
||||
- [ ] Edge cases and failure modes considered
|
||||
- [ ] States and transitions clearly defined
|
||||
|
||||
### Pattern Implementability
|
||||
|
||||
- [ ] Pattern is implementable by AI agents with provided guidance
|
||||
- [ ] No ambiguous decisions that could be interpreted differently
|
||||
- [ ] Clear boundaries between components
|
||||
- [ ] Explicit integration points with standard patterns
|
||||
|
||||
---
|
||||
|
||||
## 5. Implementation Patterns
|
||||
|
||||
### Pattern Categories Coverage
|
||||
|
||||
- [ ] **Naming Patterns**: API routes, database tables, components, files
|
||||
- [ ] **Structure Patterns**: Test organization, component organization, shared utilities
|
||||
- [ ] **Format Patterns**: API responses, error formats, date handling
|
||||
- [ ] **Communication Patterns**: Events, state updates, inter-component messaging
|
||||
- [ ] **Lifecycle Patterns**: Loading states, error recovery, retry logic
|
||||
- [ ] **Location Patterns**: URL structure, asset organization, config placement
|
||||
- [ ] **Consistency Patterns**: UI date formats, logging, user-facing errors
|
||||
|
||||
### Pattern Quality
|
||||
|
||||
- [ ] Each pattern has concrete examples
|
||||
- [ ] Conventions are unambiguous (agents can't interpret differently)
|
||||
- [ ] Patterns cover all technologies in the stack
|
||||
- [ ] No gaps where agents would have to guess
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
|
||||
---
|
||||
|
||||
## 6. Technology Compatibility
|
||||
|
||||
### Stack Coherence
|
||||
|
||||
- [ ] Database choice compatible with ORM choice
|
||||
- [ ] Frontend framework compatible with deployment target
|
||||
- [ ] Authentication solution works with chosen frontend/backend
|
||||
- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
|
||||
- [ ] Starter template compatible with additional choices
|
||||
|
||||
### Integration Compatibility
|
||||
|
||||
- [ ] Third-party services compatible with chosen stack
|
||||
- [ ] Real-time solutions (if any) work with deployment target
|
||||
- [ ] File storage solution integrates with framework
|
||||
- [ ] Background job system compatible with infrastructure
|
||||
|
||||
---
|
||||
|
||||
## 7. Document Structure
|
||||
|
||||
### Required Sections Present
|
||||
|
||||
- [ ] Executive summary exists (2-3 sentences maximum)
|
||||
- [ ] Project initialization section (if using starter template)
|
||||
- [ ] Decision summary table with ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Implementation patterns section comprehensive
|
||||
- [ ] Novel patterns section (if applicable)
|
||||
|
||||
### Document Quality
|
||||
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
- [ ] Technical language used consistently
|
||||
- [ ] Tables used instead of prose where appropriate
|
||||
- [ ] No unnecessary explanations or justifications
|
||||
- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
|
||||
|
||||
---
|
||||
|
||||
## 8. AI Agent Clarity
|
||||
|
||||
### Clear Guidance for Agents
|
||||
|
||||
- [ ] No ambiguous decisions that agents could interpret differently
|
||||
- [ ] Clear boundaries between components/modules
|
||||
- [ ] Explicit file organization patterns
|
||||
- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
|
||||
- [ ] Novel patterns have clear implementation guidance
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] No conflicting guidance present
|
||||
|
||||
### Implementation Readiness
|
||||
|
||||
- [ ] Sufficient detail for agents to implement without guessing
|
||||
- [ ] File paths and naming conventions explicit
|
||||
- [ ] Integration points clearly defined
|
||||
- [ ] Error handling patterns specified
|
||||
- [ ] Testing patterns documented
|
||||
|
||||
---
|
||||
|
||||
## 9. Practical Considerations
|
||||
|
||||
### Technology Viability
|
||||
|
||||
- [ ] Chosen stack has good documentation and community support
|
||||
- [ ] Development environment can be set up with specified versions
|
||||
- [ ] No experimental or alpha technologies for critical path
|
||||
- [ ] Deployment target supports all chosen technologies
|
||||
- [ ] Starter template (if used) is stable and well-maintained
|
||||
|
||||
### Scalability
|
||||
|
||||
- [ ] Architecture can handle expected user load
|
||||
- [ ] Data model supports expected growth
|
||||
- [ ] Caching strategy defined if performance is critical
|
||||
- [ ] Background job processing defined if async work needed
|
||||
- [ ] Novel patterns scalable for production use
|
||||
|
||||
---
|
||||
|
||||
## 10. Common Issues to Check
|
||||
|
||||
### Beginner Protection
|
||||
|
||||
- [ ] Not overengineered for actual requirements
|
||||
- [ ] Standard patterns used where possible (starter templates leveraged)
|
||||
- [ ] Complex technologies justified by specific needs
|
||||
- [ ] Maintenance complexity appropriate for team size
|
||||
|
||||
### Expert Validation
|
||||
|
||||
- [ ] No obvious anti-patterns present
|
||||
- [ ] Performance bottlenecks addressed
|
||||
- [ ] Security best practices followed
|
||||
- [ ] Future migration paths not blocked
|
||||
- [ ] Novel patterns follow architectural principles
|
||||
|
||||
---
|
||||
|
||||
## Validation Summary
|
||||
|
||||
### Document Quality Score
|
||||
|
||||
- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
|
||||
- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
|
||||
- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
|
||||
- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
|
||||
|
||||
### Critical Issues Found
|
||||
|
||||
- [ ] Issue 1: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 2: **\*\***\_\_\_**\*\***
|
||||
- [ ] Issue 3: **\*\***\_\_\_**\*\***
|
||||
|
||||
### Recommended Actions Before Implementation
|
||||
|
||||
1. ***
|
||||
2. ***
|
||||
3. ***
|
||||
|
||||
---
|
||||
|
||||
**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._
|
||||
@@ -0,0 +1,222 @@
|
||||
# Decision Catalog - Composability knowledge for architectural decisions
|
||||
# This provides RELATIONSHIPS and WORKFLOW LOGIC, not generic tech knowledge
|
||||
#
|
||||
# ⚠️ CRITICAL: All version/feature info MUST be verified via WebSearch during workflow
|
||||
# This file only provides: triggers, relationships (pairs_with), and opinionated stacks
|
||||
|
||||
decision_categories:
|
||||
data_persistence:
|
||||
triggers: ["database", "storage", "data model", "persistence", "state management"]
|
||||
importance: "critical"
|
||||
affects: "most epics"
|
||||
options:
|
||||
postgresql:
|
||||
pairs_with: ["Prisma ORM", "TypeORM", "Drizzle", "node-postgres"]
|
||||
mongodb:
|
||||
pairs_with: ["Mongoose", "Prisma", "MongoDB driver"]
|
||||
redis:
|
||||
pairs_with: ["ioredis", "node-redis"]
|
||||
supabase:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase:
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
api_pattern:
|
||||
triggers: ["API", "client communication", "frontend backend", "service communication"]
|
||||
importance: "critical"
|
||||
affects: "all client-facing epics"
|
||||
options:
|
||||
rest:
|
||||
pairs_with: ["Express", "Fastify", "NestJS", "Hono"]
|
||||
graphql:
|
||||
pairs_with: ["Apollo Server", "GraphQL Yoga", "Mercurius"]
|
||||
trpc:
|
||||
pairs_with: ["Next.js", "React Query"]
|
||||
grpc:
|
||||
pairs_with: ["@grpc/grpc-js", "protobufjs"]
|
||||
|
||||
authentication:
|
||||
triggers: ["auth", "login", "user management", "security", "identity"]
|
||||
importance: "critical"
|
||||
affects: "security and user epics"
|
||||
options:
|
||||
nextauth:
|
||||
pairs_with: ["Next.js", "Prisma"]
|
||||
auth0:
|
||||
pairs_with: ["@auth0/nextjs-auth0"]
|
||||
clerk:
|
||||
pairs_with: ["@clerk/nextjs"]
|
||||
supabase_auth:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_auth:
|
||||
pairs_with: ["firebase-admin"]
|
||||
|
||||
real_time:
|
||||
triggers: ["real-time", "websocket", "live updates", "chat", "collaboration"]
|
||||
importance: "medium"
|
||||
affects: "real-time features"
|
||||
options:
|
||||
socket_io:
|
||||
pairs_with: ["Express", "socket.io-client"]
|
||||
pusher:
|
||||
pairs_with: ["pusher-js"]
|
||||
ably:
|
||||
pairs_with: ["ably"]
|
||||
supabase_realtime:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
firebase_realtime:
|
||||
pairs_with: ["firebase"]
|
||||
|
||||
email:
|
||||
triggers: ["email", "notifications", "transactional email"]
|
||||
importance: "medium"
|
||||
affects: "notification epics"
|
||||
options:
|
||||
resend:
|
||||
pairs_with: ["resend", "react-email"]
|
||||
sendgrid:
|
||||
pairs_with: ["@sendgrid/mail"]
|
||||
postmark:
|
||||
pairs_with: ["postmark"]
|
||||
ses:
|
||||
pairs_with: ["@aws-sdk/client-ses"]
|
||||
|
||||
file_storage:
|
||||
triggers: ["upload", "file storage", "images", "media", "CDN"]
|
||||
importance: "medium"
|
||||
affects: "media handling epics"
|
||||
options:
|
||||
s3:
|
||||
pairs_with: ["@aws-sdk/client-s3", "multer"]
|
||||
cloudinary:
|
||||
pairs_with: ["cloudinary"]
|
||||
uploadthing:
|
||||
pairs_with: ["uploadthing"]
|
||||
supabase_storage:
|
||||
pairs_with: ["@supabase/supabase-js"]
|
||||
|
||||
search:
|
||||
triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
|
||||
importance: "medium"
|
||||
affects: "search and discovery epics"
|
||||
options:
|
||||
postgres_fts:
|
||||
pairs_with: ["PostgreSQL"]
|
||||
elasticsearch:
|
||||
pairs_with: ["@elastic/elasticsearch"]
|
||||
algolia:
|
||||
pairs_with: ["algoliasearch"]
|
||||
typesense:
|
||||
pairs_with: ["typesense"]
|
||||
|
||||
background_jobs:
|
||||
triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
|
||||
importance: "medium"
|
||||
affects: "async processing epics"
|
||||
options:
|
||||
bullmq:
|
||||
pairs_with: ["Redis"]
|
||||
sqs:
|
||||
pairs_with: ["@aws-sdk/client-sqs"]
|
||||
temporal:
|
||||
pairs_with: ["@temporalio/client"]
|
||||
inngest:
|
||||
pairs_with: ["inngest"]
|
||||
|
||||
deployment_target:
|
||||
triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
|
||||
importance: "high"
|
||||
affects: "all epics"
|
||||
options:
|
||||
vercel:
|
||||
pairs_with: ["Next.js", "serverless functions"]
|
||||
aws:
|
||||
pairs_with: ["any stack"]
|
||||
railway:
|
||||
pairs_with: ["any stack", "managed databases"]
|
||||
fly_io:
|
||||
pairs_with: ["Docker containers"]
|
||||
|
||||
# Opinionated stack combinations (BMM methodology)
|
||||
common_stacks:
|
||||
modern_fullstack:
|
||||
name: "Modern Full-Stack"
|
||||
components: ["Next.js", "PostgreSQL or Supabase", "Prisma ORM", "NextAuth.js", "Tailwind CSS", "TypeScript", "Vercel"]
|
||||
good_for: "Most web applications"
|
||||
|
||||
enterprise_stack:
|
||||
name: "Enterprise Stack"
|
||||
components: ["NestJS", "PostgreSQL", "TypeORM", "Auth0", "Redis", "Docker", "AWS"]
|
||||
good_for: "Large-scale enterprise applications"
|
||||
|
||||
rapid_prototype:
|
||||
name: "Rapid Prototype"
|
||||
components: ["Next.js", "Supabase", "shadcn/ui", "Vercel"]
|
||||
good_for: "MVP and rapid development"
|
||||
|
||||
real_time_app:
|
||||
name: "Real-Time Application"
|
||||
components: ["Next.js", "Supabase Realtime", "PostgreSQL", "Prisma", "Socket.io fallback"]
|
||||
good_for: "Chat, collaboration, live updates"
|
||||
|
||||
mobile_app:
|
||||
name: "Mobile Application"
|
||||
components: ["Expo", "React Native", "Supabase or Firebase", "React Query"]
|
||||
good_for: "Cross-platform mobile apps"
|
||||
|
||||
# Starter templates and what decisions they make
|
||||
starter_templates:
|
||||
create_next_app:
|
||||
name: "Create Next App"
|
||||
command_search: "npx create-next-app@latest"
|
||||
decisions_provided: ["Next.js framework", "TypeScript option", "App Router vs Pages", "Tailwind CSS option", "ESLint"]
|
||||
good_for: ["React web applications", "Full-stack apps", "SSR/SSG"]
|
||||
|
||||
create_t3_app:
|
||||
name: "Create T3 App"
|
||||
command_search: "npm create t3-app@latest"
|
||||
decisions_provided: ["Next.js", "TypeScript", "tRPC", "Prisma", "NextAuth", "Tailwind CSS"]
|
||||
good_for: ["Type-safe full-stack apps"]
|
||||
|
||||
create_vite:
|
||||
name: "Create Vite"
|
||||
command_search: "npm create vite@latest"
|
||||
decisions_provided: ["Framework choice (React/Vue/Svelte)", "TypeScript option", "Vite bundler"]
|
||||
good_for: ["Fast dev SPAs", "Library development"]
|
||||
|
||||
create_remix:
|
||||
name: "Create Remix"
|
||||
command_search: "npx create-remix@latest"
|
||||
decisions_provided: ["Remix framework", "TypeScript option", "Deployment target", "CSS solution"]
|
||||
good_for: ["Web standards", "Nested routing", "Progressive enhancement"]
|
||||
|
||||
nest_new:
|
||||
name: "NestJS CLI"
|
||||
command_search: "nest new project"
|
||||
decisions_provided: ["TypeScript (always)", "Package manager", "Testing framework (Jest)", "Project structure"]
|
||||
good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
|
||||
|
||||
create_expo_app:
|
||||
name: "Create Expo App"
|
||||
command_search: "npx create-expo-app"
|
||||
decisions_provided: ["React Native", "Expo SDK", "TypeScript option", "Navigation option"]
|
||||
good_for: ["Cross-platform mobile", "React Native apps"]
|
||||
|
||||
# Starter selection heuristics (workflow logic)
|
||||
starter_selection_rules:
|
||||
by_project_type:
|
||||
web_application:
|
||||
recommended: ["create_next_app", "create_t3_app", "create_vite"]
|
||||
considerations: "SSR needs? → Next.js. Type safety critical? → T3. SPA only? → Vite"
|
||||
|
||||
mobile_app:
|
||||
recommended: ["create_expo_app"]
|
||||
considerations: "Cross-platform → Expo. Native-heavy → React Native CLI"
|
||||
|
||||
api_backend:
|
||||
recommended: ["nest_new"]
|
||||
considerations: "Enterprise → NestJS. Simple → Express starter. Performance → Fastify"
|
||||
|
||||
full_stack:
|
||||
recommended: ["create_t3_app", "create_remix"]
|
||||
considerations: "Type safety → T3. Web standards → Remix. Monolith → RedwoodJS"
|
||||
715
bmad/bmm/workflows/3-solutioning/architecture/instructions.md
Normal file
715
bmad/bmm/workflows/3-solutioning/architecture/instructions.md
Normal file
@@ -0,0 +1,715 @@
|
||||
# Decision Architecture Workflow Instructions
|
||||
|
||||
<workflow name="architecture">
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
|
||||
<critical>The goal is ARCHITECTURAL DECISIONS that prevent AI agent conflicts, not detailed implementation specs</critical>
|
||||
<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>This workflow replaces architecture with a conversation-driven approach</critical>
|
||||
|
||||
## 📚 Input Document Discovery
|
||||
|
||||
This workflow requires: PRD and epics/stories, and may reference UX design specifications or brownfield project documentation.
|
||||
|
||||
**Discovery Process** (execute for each referenced document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Decision Architecture can run standalone or as part of BMM workflow path.</output>
|
||||
<output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
|
||||
<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
|
||||
<check if="continue">
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
<check if="exit">
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "create-architecture" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="project_level < 3">
|
||||
<output>**Note: Level {{project_level}} Project**
|
||||
|
||||
The Detailed Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
|
||||
|
||||
For Level {{project_level}}, we'll keep the architecture appropriately scoped.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="create-architecture status is file path (already completed)">
|
||||
<output>⚠️ Architecture already completed: {{create-architecture status}}</output>
|
||||
<ask>Re-running will overwrite the existing architecture. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="create-architecture is not the next expected workflow">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Architecture is out of sequence.</output>
|
||||
<ask>Continue with Architecture anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
|
||||
<action>Check for existing PRD and epics files using fuzzy matching</action>
|
||||
|
||||
<action>Fuzzy match PRD file: {prd_file}</action>
|
||||
<check if="PRD_not_found">
|
||||
<output>**PRD Not Found**
|
||||
|
||||
Decision Architecture works from your Product Requirements Document (PRD).
|
||||
|
||||
Looking for: _PRD_, PRD.md, or prd/index.md + files in {output_folder}
|
||||
|
||||
Please run the PRD workflow first to define your requirements.
|
||||
|
||||
Architect: `create-prd`
|
||||
</output>
|
||||
<action>Exit workflow - PRD required</action>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load and understand project context">
|
||||
<action>Load the PRD using fuzzy matching: {prd_file}, if the PRD is mulitple files in a folder, load the index file and all files associated with the PRD</action>
|
||||
<action>Load epics file using fuzzy matching: {epics_file}</action>
|
||||
|
||||
<action>Check for UX specification using fuzzy matching:
|
||||
<action>Attempt to locate: {ux_spec_file}</action>
|
||||
<check if="ux_spec_found">
|
||||
<action>Load UX spec and extract architectural implications: - Component complexity (simple forms vs rich interactions) - Animation/transition requirements - Real-time update needs (live data, collaborative features) - Platform-specific UI requirements - Accessibility standards (WCAG compliance level) - Responsive design breakpoints - Offline capability requirements - Performance expectations (load times, interaction responsiveness)
|
||||
</action>
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned
|
||||
</action>
|
||||
|
||||
<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
"I'm reviewing your project documentation for {{project_name}}.
|
||||
I see {{epic_count}} epics with {{story_count}} total stories.
|
||||
{{if_ux_spec}}I also found your UX specification which defines the user experience requirements.{{/if_ux_spec}}
|
||||
|
||||
Key aspects I notice:
|
||||
- [Summarize core functionality]
|
||||
- [Note critical NFRs]
|
||||
{{if_ux_spec}}- [Note UX complexity and requirements]{{/if_ux_spec}}
|
||||
- [Identify unique challenges]
|
||||
|
||||
This will help me guide you through the architectural decisions needed
|
||||
to ensure AI agents implement this consistently."
|
||||
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of the project?</ask>
|
||||
<template-output>project_context_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover and evaluate starter templates">
|
||||
<critical>Modern starter templates make many good architectural decisions by default</critical>
|
||||
|
||||
<action>Based on PRD analysis, identify the primary technology domain: - Web application → Look for Next.js, Vite, Remix starters - Mobile app → Look for React Native, Expo, Flutter starters - API/Backend → Look for NestJS, Express, Fastify starters - CLI tool → Look for CLI framework starters - Full-stack → Look for T3, RedwoodJS, Blitz starters
|
||||
</action>
|
||||
|
||||
<check if="ux_spec_loaded">
|
||||
<action>Consider UX requirements when selecting starter:
|
||||
- Rich animations → Framer Motion compatible starter
|
||||
- Complex forms → React Hook Form included starter
|
||||
- Real-time features → Socket.io or WebSocket ready starter
|
||||
- Accessibility focus → WCAG-compliant component library starter
|
||||
- Design system → Storybook-enabled starter
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>Search for relevant starter templates with websearch, examples:
|
||||
<WebSearch>{{primary_technology}} starter template CLI create command latest {date}</WebSearch>
|
||||
<WebSearch>{{primary_technology}} boilerplate generator latest options</WebSearch>
|
||||
</action>
|
||||
|
||||
<check if="starter_templates_found">
|
||||
<action>Investigate what each starter provides:
|
||||
<WebSearch>{{starter_name}} default setup technologies included latest</WebSearch>
|
||||
<WebSearch>{{starter_name}} project structure file organization</WebSearch>
|
||||
</action>
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
<action>Present starter options concisely:
|
||||
"Found {{starter_name}} which provides:
|
||||
{{quick_decision_list}}
|
||||
|
||||
This would establish our base architecture. Use it?"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
<action>Explain starter benefits:
|
||||
"I found {{starter_name}}, which is like a pre-built foundation for your project.
|
||||
|
||||
Think of it like buying a prefab house frame instead of cutting each board yourself.
|
||||
|
||||
It makes these decisions for you:
|
||||
{{friendly_decision_list}}
|
||||
|
||||
This is a great starting point that follows best practices. Should we use it?"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<ask>Use {{starter_name}} as the foundation? (recommended) [y/n]</ask>
|
||||
|
||||
<check if="user_accepts_starter">
|
||||
<action>Get current starter command and options:
|
||||
<WebSearch>{{starter_name}} CLI command options flags latest 2024</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Document the initialization command:
|
||||
Store command: {{full_starter_command_with_options}}
|
||||
Example: "npx create-next-app@latest my-app --typescript --tailwind --app"
|
||||
</action>
|
||||
|
||||
<action>Extract and document starter-provided decisions:
|
||||
Starter provides these architectural decisions:
|
||||
- Language/TypeScript: {{provided_or_not}}
|
||||
- Styling solution: {{provided_or_not}}
|
||||
- Testing framework: {{provided_or_not}}
|
||||
- Linting/Formatting: {{provided_or_not}}
|
||||
- Build tooling: {{provided_or_not}}
|
||||
- Project structure: {{provided_pattern}}
|
||||
</action>
|
||||
|
||||
<action>Mark these decisions as "PROVIDED BY STARTER" in our decision tracking</action>
|
||||
|
||||
<action>Note for first implementation story:
|
||||
"Project initialization using {{starter_command}} should be the first implementation story"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="user_rejects_starter">
|
||||
<ask>Any specific reason to avoid the starter? (helps me understand constraints)</ask>
|
||||
<action>Note: Manual setup required, all decisions need to be made explicitly</action>
|
||||
</check>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="no_starter_found_or_applicable">
|
||||
<action>Note: No standard starter template found for this project type.
|
||||
We will make all architectural decisions explicitly.</action>
|
||||
</check>
|
||||
|
||||
<template-output>starter_template_decision</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Adapt facilitation style and identify remaining decisions">
|
||||
<action>Based on {user_skill_level} from config, set facilitation approach:
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
Set mode: EXPERT
|
||||
- Use technical terminology freely
|
||||
- Move quickly through decisions
|
||||
- Assume familiarity with patterns and tools
|
||||
- Focus on edge cases and advanced concerns
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'intermediate'">
|
||||
Set mode: INTERMEDIATE
|
||||
- Balance technical accuracy with clarity
|
||||
- Explain complex patterns briefly
|
||||
- Confirm understanding at key points
|
||||
- Provide context for non-obvious choices
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
Set mode: BEGINNER
|
||||
- Use analogies and real-world examples
|
||||
- Explain technical concepts in simple terms
|
||||
- Provide education about why decisions matter
|
||||
- Protect from complexity overload
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Load decision catalog: {decision_catalog}</action>
|
||||
<action>Load architecture patterns: {architecture_patterns}</action>
|
||||
|
||||
<action>Analyze PRD against patterns to identify needed decisions: - Match functional requirements to known patterns - Identify which categories of decisions are needed - Flag any novel/unique aspects requiring special attention - Consider which decisions the starter template already made (if applicable)
|
||||
</action>
|
||||
|
||||
<action>Create decision priority list:
|
||||
CRITICAL (blocks everything): - {{list_of_critical_decisions}}
|
||||
|
||||
IMPORTANT (shapes architecture):
|
||||
- {{list_of_important_decisions}}
|
||||
|
||||
NICE-TO-HAVE (can defer):
|
||||
- {{list_of_optional_decisions}}
|
||||
|
||||
</action>
|
||||
|
||||
<action>Announce plan to {user_name} based on mode:
|
||||
<check if="mode == 'EXPERT'">
|
||||
"Based on your PRD, we need to make {{total_decision_count}} architectural decisions.
|
||||
{{starter_covered_count}} are covered by the starter template.
|
||||
Let's work through the remaining {{remaining_count}} decisions."
|
||||
</check>
|
||||
|
||||
<check if="mode == 'BEGINNER'">
|
||||
"Great! I've analyzed your requirements and found {{total_decision_count}} technical
|
||||
choices we need to make. Don't worry - I'll guide you through each one and explain
|
||||
why it matters. {{if_starter}}The starter template handles {{starter_covered_count}}
|
||||
of these automatically.{{/if_starter}}"
|
||||
</check>
|
||||
|
||||
</action>
|
||||
|
||||
<template-output>decision_identification</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Facilitate collaborative decision making" repeat="for-each-decision">
|
||||
<critical>Each decision must be made WITH the user, not FOR them</critical>
|
||||
<critical>ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions</critical>
|
||||
|
||||
<action>For each decision in priority order:</action>
|
||||
|
||||
<action>Present the decision based on mode:
|
||||
<check if="mode == 'EXPERT'">
|
||||
"{{Decision_Category}}: {{Specific_Decision}}
|
||||
|
||||
Options: {{concise_option_list_with_tradeoffs}}
|
||||
|
||||
Recommendation: {{recommendation}} for {{reason}}"
|
||||
|
||||
</check>
|
||||
|
||||
<check if="mode == 'INTERMEDIATE'">
|
||||
"Next decision: {{Human_Friendly_Category}}
|
||||
|
||||
We need to choose {{Specific_Decision}}.
|
||||
|
||||
Common options:
|
||||
{{option_list_with_brief_explanations}}
|
||||
|
||||
For your project, {{recommendation}} would work well because {{reason}}."
|
||||
|
||||
</check>
|
||||
|
||||
<check if="mode == 'BEGINNER'">
|
||||
"Let's talk about {{Human_Friendly_Category}}.
|
||||
|
||||
{{Educational_Context_About_Why_This_Matters}}
|
||||
|
||||
Think of it like {{real_world_analogy}}.
|
||||
|
||||
Your main options:
|
||||
{{friendly_options_with_pros_cons}}
|
||||
|
||||
My suggestion: {{recommendation}}
|
||||
This is good for you because {{beginner_friendly_reason}}."
|
||||
|
||||
</check>
|
||||
|
||||
</action>
|
||||
|
||||
<check if="decision_involves_specific_technology">
|
||||
<action>Verify current stable version:
|
||||
<WebSearch>{{technology}} latest stable version 2024</WebSearch>
|
||||
<WebSearch>{{technology}} current LTS version</WebSearch>
|
||||
</action>
|
||||
|
||||
<action>Update decision record with verified version:
|
||||
Technology: {{technology}}
|
||||
Verified Version: {{version_from_search}}
|
||||
Verification Date: {{today}}
|
||||
</action>
|
||||
|
||||
</check>
|
||||
|
||||
<ask>What's your preference? (or 'explain more' for details)</ask>
|
||||
|
||||
<check if="user_wants_more_info">
|
||||
<action>Provide deeper explanation appropriate to skill level</action>
|
||||
<check if="complex_tradeoffs">
|
||||
<action>Consider using advanced elicitation:
|
||||
"Would you like to explore innovative approaches to this decision?
|
||||
I can help brainstorm unconventional solutions if you have specific goals."
|
||||
</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Record decision:
|
||||
Category: {{category}}
|
||||
Decision: {{user_choice}}
|
||||
Version: {{verified_version_if_applicable}}
|
||||
Affects Epics: {{list_of_affected_epics}}
|
||||
Rationale: {{user_reasoning_or_default}}
|
||||
Provided by Starter: {{yes_if_from_starter}}
|
||||
</action>
|
||||
|
||||
<action>Check for cascading implications:
|
||||
"This choice means we'll also need to {{related_decisions}}"
|
||||
</action>
|
||||
|
||||
<template-output>decision_record</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Address cross-cutting concerns">
|
||||
<critical>These decisions affect EVERY epic and story</critical>
|
||||
|
||||
<action>Facilitate decisions for consistency patterns: - Error handling strategy (How will all agents handle errors?) - Logging approach (Structured? Format? Levels?) - Date/time handling (Timezone? Format? Library?) - Authentication pattern (Where? How? Token format?) - API response format (Structure? Status codes? Errors?) - Testing strategy (Unit? Integration? E2E?)
|
||||
</action>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
<action>Explain why these matter why its critical to go through and decide these things now.</action>
|
||||
</check>
|
||||
|
||||
<template-output>cross_cutting_decisions</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Define project structure and boundaries">
|
||||
<action>Based on all decisions made, define the project structure</action>
|
||||
|
||||
<action>Create comprehensive source tree: - Root configuration files - Source code organization - Test file locations - Build/dist directories - Documentation structure
|
||||
</action>
|
||||
|
||||
<action>Map epics to architectural boundaries:
|
||||
"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
|
||||
</action>
|
||||
|
||||
<action>Define integration points: - Where do components communicate? - What are the API boundaries? - How do services interact?
|
||||
</action>
|
||||
|
||||
<template-output>project_structure</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Design novel architectural patterns" optional="true">
|
||||
<critical>Some projects require INVENTING new patterns, not just choosing existing ones</critical>
|
||||
|
||||
<action>Scan PRD for concepts that don't have standard solutions: - Novel interaction patterns (e.g., "swipe to match" before Tinder existed) - Unique multi-component workflows (e.g., "viral invitation system") - New data relationships (e.g., "social graph" before Facebook) - Unprecedented user experiences (e.g., "ephemeral messages" before Snapchat) - Complex state machines crossing multiple epics
|
||||
</action>
|
||||
|
||||
<check if="novel_patterns_detected">
|
||||
<action>For each novel pattern identified:</action>
|
||||
|
||||
<action>Engage user in design collaboration:
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"The {{pattern_name}} concept requires architectural innovation.
|
||||
|
||||
Core challenge: {{challenge_description}}
|
||||
|
||||
Let's design the component interaction model:"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Your idea about {{pattern_name}} is unique - there isn't a standard way to build this yet!
|
||||
|
||||
This is exciting - we get to invent the architecture together.
|
||||
|
||||
Let me help you think through how this should work:"
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Facilitate pattern design:
|
||||
1. Identify core components involved
|
||||
2. Map data flow between components
|
||||
3. Design state management approach
|
||||
4. Create sequence diagrams for complex flows
|
||||
5. Define API contracts for the pattern
|
||||
6. Consider edge cases and failure modes
|
||||
</action>
|
||||
|
||||
<action>Use advanced elicitation for innovation:
|
||||
"What if we approached this differently?
|
||||
- What would the ideal user experience look like?
|
||||
- Are there analogies from other domains we could apply?
|
||||
- What constraints can we challenge?"
|
||||
</action>
|
||||
|
||||
<action>Document the novel pattern:
|
||||
Pattern Name: {{pattern_name}}
|
||||
Purpose: {{what_problem_it_solves}}
|
||||
Components:
|
||||
{{component_list_with_responsibilities}}
|
||||
Data Flow:
|
||||
{{sequence_description_or_diagram}}
|
||||
Implementation Guide:
|
||||
{{how_agents_should_build_this}}
|
||||
Affects Epics:
|
||||
{{epics_that_use_this_pattern}}
|
||||
</action>
|
||||
|
||||
<action>Validate pattern completeness:
|
||||
"Does this {{pattern_name}} design cover all the use cases in your epics?
|
||||
- {{use_case_1}}: ✓ Handled by {{component}}
|
||||
- {{use_case_2}}: ✓ Handled by {{component}}
|
||||
..."
|
||||
</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="no_novel_patterns">
|
||||
<action>Note: All patterns in this project have established solutions.
|
||||
Proceeding with standard architectural patterns.</action>
|
||||
</check>
|
||||
|
||||
<template-output>novel_pattern_designs</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Define implementation patterns to prevent agent conflicts">
|
||||
<critical>These patterns ensure multiple AI agents write compatible code</critical>
|
||||
<critical>Focus on what agents could decide DIFFERENTLY if not specified</critical>
|
||||
|
||||
<action>Load pattern categories: {pattern_categories}</action>
|
||||
|
||||
<action>Based on chosen technologies, identify potential conflict points:
|
||||
"Given that we're using {{tech_stack}}, agents need consistency rules for:"
|
||||
</action>
|
||||
|
||||
<action>For each relevant pattern category, facilitate decisions:
|
||||
|
||||
NAMING PATTERNS (How things are named):
|
||||
<check if="has_api">
|
||||
- REST endpoint naming: /users or /user? Plural or singular?
|
||||
- Route parameter format: :id or {id}?
|
||||
</check>
|
||||
<check if="has_database">
|
||||
- Table naming: users or Users or user?
|
||||
- Column naming: user_id or userId?
|
||||
- Foreign key format: user_id or fk_user?
|
||||
</check>
|
||||
<check if="has_frontend">
|
||||
- Component naming: UserCard or user-card?
|
||||
- File naming: UserCard.tsx or user-card.tsx?
|
||||
</check>
|
||||
|
||||
STRUCTURE PATTERNS (How things are organized):
|
||||
- Where do tests live? __tests__/ or *.test.ts co-located?
|
||||
- How are components organized? By feature or by type?
|
||||
- Where do shared utilities go?
|
||||
|
||||
FORMAT PATTERNS (Data exchange formats):
|
||||
<check if="has_api">
|
||||
- API response wrapper? {data: ..., error: ...} or direct response?
|
||||
- Error format? {message, code} or {error: {type, detail}}?
|
||||
- Date format in JSON? ISO strings or timestamps?
|
||||
</check>
|
||||
|
||||
COMMUNICATION PATTERNS (How components interact):
|
||||
<check if="has_events">
|
||||
- Event naming convention?
|
||||
- Event payload structure?
|
||||
</check>
|
||||
<check if="has_state_management">
|
||||
- State update pattern?
|
||||
- Action naming convention?
|
||||
</check>
|
||||
|
||||
LIFECYCLE PATTERNS (State and flow):
|
||||
- How are loading states handled?
|
||||
- What's the error recovery pattern?
|
||||
- How are retries implemented?
|
||||
|
||||
LOCATION PATTERNS (Where things go):
|
||||
- API route structure?
|
||||
- Static asset organization?
|
||||
- Config file locations?
|
||||
|
||||
CONSISTENCY PATTERNS (Cross-cutting):
|
||||
- How are dates formatted in the UI?
|
||||
- What's the logging format?
|
||||
- How are user-facing errors written?
|
||||
|
||||
</action>
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
<action>Rapid-fire through patterns:
|
||||
"Quick decisions on implementation patterns:
|
||||
- {{pattern}}: {{suggested_convention}} OK? [y/n/specify]"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
<action>Explain each pattern's importance:
|
||||
"Let me explain why this matters:
|
||||
If one AI agent names database tables 'users' and another names them 'Users',
|
||||
your app will crash. We need to pick one style and make sure everyone follows it."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>Document implementation patterns:
|
||||
Category: {{pattern_category}}
|
||||
Pattern: {{specific_pattern}}
|
||||
Convention: {{decided_convention}}
|
||||
Example: {{concrete_example}}
|
||||
Enforcement: "All agents MUST follow this pattern"
|
||||
</action>
|
||||
|
||||
<template-output>implementation_patterns</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Validate architectural coherence">
|
||||
<action>Run coherence checks:</action>
|
||||
|
||||
<action>Check decision compatibility: - Do all decisions work together? - Are there any conflicting choices? - Do the versions align properly?
|
||||
</action>
|
||||
|
||||
<action>Verify epic coverage: - Does every epic have architectural support? - Are all user stories implementable with these decisions? - Are there any gaps?
|
||||
</action>
|
||||
|
||||
<action>Validate pattern completeness: - Are there any patterns we missed that agents would need? - Do novel patterns integrate with standard architecture? - Are implementation patterns comprehensive enough?
|
||||
</action>
|
||||
|
||||
<check if="issues_found">
|
||||
<action>Address issues with {user_name}:
|
||||
"I notice {{issue_description}}.
|
||||
We should {{suggested_resolution}}."
|
||||
</action>
|
||||
<ask>How would you like to resolve this?</ask>
|
||||
<action>Update decisions based on resolution</action>
|
||||
</check>
|
||||
|
||||
<template-output>coherence_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Generate decision architecture document">
|
||||
<critical>The document must be complete, specific, and validation-ready</critical>
|
||||
<critical>This is the consistency contract for all AI agents</critical>
|
||||
|
||||
<action>Load template: {architecture_template}</action>
|
||||
|
||||
<action>Generate sections: 1. Executive Summary (2-3 sentences about the architecture approach) 2. Project Initialization (starter command if applicable) 3. Decision Summary Table (with verified versions and epic mapping) 4. Complete Project Structure (full tree, no placeholders) 5. Epic to Architecture Mapping (every epic placed) 6. Technology Stack Details (versions, configurations) 7. Integration Points (how components connect) 8. Novel Pattern Designs (if any were created) 9. Implementation Patterns (all consistency rules) 10. Consistency Rules (naming, organization, formats) 11. Data Architecture (models and relationships) 12. API Contracts (request/response formats) 13. Security Architecture (auth, authorization, data protection) 14. Performance Considerations (from NFRs) 15. Deployment Architecture (where and how) 16. Development Environment (setup and prerequisites) 17. Architecture Decision Records (key decisions with rationale)
|
||||
</action>
|
||||
|
||||
<action>Fill template with all collected decisions and patterns</action>
|
||||
|
||||
<action>Ensure starter command is first implementation story:
|
||||
<check if="using_starter_template">
|
||||
"## Project Initialization
|
||||
|
||||
First implementation story should execute:
|
||||
```bash
|
||||
{{starter_command_with_options}}
|
||||
```
|
||||
|
||||
This establishes the base architecture with these decisions:
|
||||
{{starter_provided_decisions}}"
|
||||
</check>
|
||||
|
||||
</action>
|
||||
|
||||
<template-output>architecture_document</template-output>
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Validate document completeness">
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
|
||||
<action>Run validation checklist from {installed_path}/checklist.md</action>
|
||||
|
||||
<action>Verify MANDATORY items:
|
||||
□ Decision table has Version column with specific versions
|
||||
□ Every epic is mapped to architecture components
|
||||
□ Source tree is complete, not generic
|
||||
□ No placeholder text remains
|
||||
□ All FRs from PRD have architectural support
|
||||
□ All NFRs from PRD are addressed
|
||||
□ Implementation patterns cover all potential conflicts
|
||||
□ Novel patterns are fully documented (if applicable)
|
||||
</action>
|
||||
|
||||
<check if="validation_failed">
|
||||
<action>Fix missing items automatically</action>
|
||||
<goto step="10">Regenerate document section</goto>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Final review and update workflow status">
|
||||
<action>Present completion summary:</action>
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"Architecture complete. {{decision_count}} decisions documented.
|
||||
Ready for implementation phase."
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Excellent! Your architecture is complete. You made {{decision_count}} important
|
||||
decisions that will keep AI agents consistent as they build your app.
|
||||
|
||||
What happens next:
|
||||
1. AI agents will read this architecture before implementing each story
|
||||
2. They'll follow your technical choices exactly
|
||||
3. Your app will be built with consistent patterns throughout
|
||||
|
||||
You're ready to move to the implementation phase!"
|
||||
|
||||
</check>
|
||||
|
||||
<action>Save document to {output_folder}/architecture.md</action>
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "create-architecture"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["create-architecture"] = "{output_folder}/bmm-architecture-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
|
||||
</check>
|
||||
|
||||
<output>✅ Decision Architecture workflow complete!</output>
|
||||
|
||||
<output>**Deliverables Created:**
|
||||
|
||||
- ✅ architecture.md - Complete architectural decisions document
|
||||
{{if_novel_patterns}}
|
||||
- ✅ Novel pattern designs for unique concepts
|
||||
{{/if_novel_patterns}}
|
||||
{{if_starter_template}}
|
||||
- ✅ Project initialization command documented
|
||||
{{/if_starter_template}}
|
||||
|
||||
The architecture is ready to guide AI agents through consistent implementation.
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
- **Next required:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- Review the architecture.md document before proceeding
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
</output>
|
||||
|
||||
<template-output>completion_summary</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,13 @@
|
||||
category,when_needed,what_to_define,why_critical
|
||||
naming_patterns,Any technology with named entities,How things are named (format/case/structure),Agents will create different names for same concept
|
||||
structure_patterns,Any technology with organization,How things are organized (folders/modules/layers),Agents will put things in different places
|
||||
format_patterns,Any technology with data exchange,How data is formatted (JSON/XML/responses),Agents will use incompatible formats
|
||||
communication_patterns,Any technology with inter-component communication,How components talk (protocols/events/messages),Agents will use different communication methods
|
||||
lifecycle_patterns,Any technology with state or flow,How state changes and flows work,Agents will handle state transitions differently
|
||||
location_patterns,Any technology with storage or routing,Where things go (URLs/paths/storage),Agents will put things in different locations
|
||||
consistency_patterns,Always,Cross-cutting concerns (dates/errors/logs),Every agent will do these differently
|
||||
|
||||
# PRINCIPLE FOR LLM:
|
||||
# Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture.
|
||||
# Think about: What could an agent encounter where they'd have to guess?
|
||||
# If they'd guess, define the pattern. If it's obvious from the tech choice, skip it.
|
||||
|
67
bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml
Normal file
67
bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml
Normal file
@@ -0,0 +1,67 @@
|
||||
# Architecture Workflow Configuration
|
||||
name: architecture
|
||||
description: "Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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
|
||||
|
||||
# Input requirements - We work from PRD, Epics, and optionally UX Spec
|
||||
recommended_inputs:
|
||||
- prd: "Product Requirements Document with FRs and NFRs"
|
||||
- epics: "Epic definitions with user stories and acceptance criteria"
|
||||
- ux_spec: "UX specification with interface designs and interaction patterns (optional)"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
|
||||
ux_design:
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/architecture-template.md"
|
||||
|
||||
# Knowledge bases for intelligent decision making
|
||||
decision_catalog: "{installed_path}/decision-catalog.yaml"
|
||||
architecture_patterns: "{installed_path}/architecture-patterns.yaml"
|
||||
pattern_categories: "{installed_path}/pattern-categories.csv"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/architecture.md"
|
||||
|
||||
# Workflow metadata
|
||||
version: "1.3.2"
|
||||
replaces: "architecture"
|
||||
paradigm: "facilitation-driven"
|
||||
execution_time: "30-90 minutes depending on user skill level"
|
||||
features:
|
||||
- "Starter template discovery and integration"
|
||||
- "Dynamic version verification via web search"
|
||||
- "Adaptive facilitation by skill level"
|
||||
- "Decision-focused architecture"
|
||||
- "Novel pattern design for unique concepts"
|
||||
- "Intelligent pattern identification - LLM figures out what patterns matter"
|
||||
- "Implementation patterns for agent consistency"
|
||||
|
||||
standalone: true
|
||||
@@ -0,0 +1,177 @@
|
||||
# Implementation Ready Check Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
The Implementation Ready Check workflow provides a systematic validation of all planning and solutioning artifacts before transitioning from Phase 3 (Solutioning) to Phase 4 (Implementation) in the BMad Method. This workflow ensures that PRDs, architecture documents, and story breakdowns are properly aligned with no critical gaps or contradictions.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow is designed to:
|
||||
|
||||
- **Validate Completeness**: Ensure all required planning documents exist and are complete
|
||||
- **Verify Alignment**: Check that PRD, architecture, and stories are cohesive and aligned
|
||||
- **Identify Gaps**: Detect missing stories, unaddressed requirements, or sequencing issues
|
||||
- **Assess Risks**: Find contradictions, conflicts, or potential implementation blockers
|
||||
- **Provide Confidence**: Give teams confidence that planning is solid before starting development
|
||||
|
||||
## When to Use
|
||||
|
||||
This workflow should be invoked:
|
||||
|
||||
- At the end of Phase 3 (Solutioning) for Level 2-4 projects
|
||||
- Before beginning Phase 4 (Implementation)
|
||||
- After significant planning updates or architectural changes
|
||||
- When validating readiness for Level 0-1 projects (simplified validation)
|
||||
|
||||
## Project Level Adaptations
|
||||
|
||||
The workflow adapts its validation based on project level:
|
||||
|
||||
### Level 0-1 Projects
|
||||
|
||||
- Validates tech spec and simple stories only
|
||||
- Checks internal consistency and basic coverage
|
||||
- Lighter validation appropriate for simple projects
|
||||
|
||||
### Level 2 Projects
|
||||
|
||||
- Validates PRD, tech spec (with embedded architecture), and stories
|
||||
- Ensures PRD requirements are fully covered
|
||||
- Verifies technical approach aligns with business goals
|
||||
|
||||
### Level 3-4 Projects
|
||||
|
||||
- Full validation of PRD, architecture document, and comprehensive stories
|
||||
- Deep cross-reference checking across all artifacts
|
||||
- Validates architectural decisions don't introduce scope creep
|
||||
- Checks UX artifacts if applicable
|
||||
|
||||
## How to Invoke
|
||||
|
||||
### Via Scrum Master Agent
|
||||
|
||||
```
|
||||
*solutioning-gate-check
|
||||
```
|
||||
|
||||
### Direct Workflow Invocation
|
||||
|
||||
```
|
||||
workflow solutioning-gate-check
|
||||
```
|
||||
|
||||
## Expected Inputs
|
||||
|
||||
The workflow will automatically search your project's output folder for:
|
||||
|
||||
- Product Requirements Documents (PRD)
|
||||
- Architecture documents
|
||||
- Technical Specifications
|
||||
- Epic and Story breakdowns
|
||||
- UX artifacts (if applicable)
|
||||
|
||||
No manual input file specification needed - the workflow discovers documents automatically.
|
||||
|
||||
## Generated Output
|
||||
|
||||
The workflow produces a comprehensive **Implementation Readiness Report** containing:
|
||||
|
||||
1. **Executive Summary** - Overall readiness status
|
||||
2. **Document Inventory** - What was found and reviewed
|
||||
3. **Alignment Validation** - Cross-reference analysis results
|
||||
4. **Gap Analysis** - Missing items and risks identified
|
||||
5. **Findings by Severity** - Critical, High, Medium, Low issues
|
||||
6. **Recommendations** - Specific actions to address issues
|
||||
7. **Readiness Decision** - Ready, Ready with Conditions, or Not Ready
|
||||
|
||||
Output Location: `{output_folder}/implementation-readiness-report-{date}.md`
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
1. **Initialize** - Get current workflow status and project level
|
||||
2. **Document Discovery** - Find all planning artifacts
|
||||
3. **Deep Analysis** - Extract requirements, decisions, and stories
|
||||
4. **Cross-Reference Validation** - Check alignment between all documents
|
||||
5. **Gap and Risk Analysis** - Identify issues and conflicts
|
||||
6. **UX Validation** (optional) - Verify UX concerns are addressed
|
||||
7. **Generate Report** - Compile comprehensive readiness assessment
|
||||
8. **Status Update** (optional) - Offer to advance workflow to next phase
|
||||
|
||||
## Validation Criteria
|
||||
|
||||
The workflow uses systematic validation rules adapted to each project level:
|
||||
|
||||
- **Document completeness and quality**
|
||||
- **Requirement to story traceability**
|
||||
- **Architecture to implementation alignment**
|
||||
- **Story sequencing and dependencies**
|
||||
- **Greenfield project setup coverage**
|
||||
- **Risk identification and mitigation**
|
||||
|
||||
For projects using the new architecture workflow (decision-architecture.md), additional validations include:
|
||||
|
||||
- **Implementation patterns defined for consistency**
|
||||
- **Technology versions verified and current**
|
||||
- **Starter template initialization as first story**
|
||||
- **UX specification alignment (if provided)**
|
||||
|
||||
## Special Features
|
||||
|
||||
### Intelligent Adaptation
|
||||
|
||||
- Automatically adjusts validation based on project level
|
||||
- Recognizes when UX workflow is active
|
||||
- Handles greenfield vs. brownfield projects differently
|
||||
|
||||
### Comprehensive Coverage
|
||||
|
||||
- Validates not just presence but quality and alignment
|
||||
- Checks for both gaps and gold-plating
|
||||
- Ensures logical story sequencing
|
||||
|
||||
### Actionable Output
|
||||
|
||||
- Provides specific, actionable recommendations
|
||||
- Categorizes issues by severity
|
||||
- Includes positive findings and commendations
|
||||
|
||||
## Integration with BMad Method
|
||||
|
||||
This workflow integrates seamlessly with the BMad Method workflow system:
|
||||
|
||||
- Uses workflow-status to understand project context
|
||||
- Can update workflow status to advance to next phase
|
||||
- Follows standard BMad document naming conventions
|
||||
- Searches standard output folders automatically
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Documents Not Found
|
||||
|
||||
- Ensure documents are in the configured output folder
|
||||
- Check that document names follow BMad conventions
|
||||
- Verify workflow-status is properly configured
|
||||
|
||||
### Validation Too Strict
|
||||
|
||||
- The workflow adapts to project level automatically
|
||||
- Level 0-1 projects get lighter validation
|
||||
- Consider if your project level is set correctly
|
||||
|
||||
### Report Too Long
|
||||
|
||||
- Focus on Critical and High priority issues first
|
||||
- Use the executive summary for quick decisions
|
||||
- Review detailed findings only for areas of concern
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about this workflow:
|
||||
|
||||
- Consult the BMad Method documentation
|
||||
- Check the SM agent for workflow guidance
|
||||
- Review validation-criteria.yaml for detailed rules
|
||||
|
||||
---
|
||||
|
||||
_This workflow is part of the BMad Method v6-alpha suite of planning and solutioning tools_
|
||||
@@ -0,0 +1,175 @@
|
||||
# Implementation Readiness Validation Checklist
|
||||
|
||||
## Document Completeness
|
||||
|
||||
### Core Planning Documents
|
||||
|
||||
- [ ] PRD exists and is complete (Level 2-4 projects)
|
||||
- [ ] PRD contains measurable success criteria
|
||||
- [ ] PRD defines clear scope boundaries and exclusions
|
||||
- [ ] Architecture document exists (architecture\*.md) (Level 3-4 projects)
|
||||
- [ ] Technical Specification exists with implementation details
|
||||
- [ ] Epic and story breakdown document exists
|
||||
- [ ] All documents are dated and versioned
|
||||
|
||||
### Document Quality
|
||||
|
||||
- [ ] No placeholder sections remain in any document
|
||||
- [ ] All documents use consistent terminology
|
||||
- [ ] Technical decisions include rationale and trade-offs
|
||||
- [ ] Assumptions and risks are explicitly documented
|
||||
- [ ] Dependencies are clearly identified and documented
|
||||
|
||||
## Alignment Verification
|
||||
|
||||
### PRD to Architecture Alignment (Level 3-4)
|
||||
|
||||
- [ ] Every functional requirement in PRD has architectural support documented
|
||||
- [ ] All non-functional requirements from PRD are addressed in architecture
|
||||
- [ ] Architecture doesn't introduce features beyond PRD scope
|
||||
- [ ] Performance requirements from PRD match architecture capabilities
|
||||
- [ ] Security requirements from PRD are fully addressed in architecture
|
||||
- [ ] If architecture.md: Implementation patterns are defined for consistency
|
||||
- [ ] If architecture.md: All technology choices have verified versions
|
||||
- [ ] If UX spec exists: Architecture supports UX requirements
|
||||
|
||||
### PRD to Stories Coverage (Level 2-4)
|
||||
|
||||
- [ ] Every PRD requirement maps to at least one story
|
||||
- [ ] All user journeys in PRD have complete story coverage
|
||||
- [ ] Story acceptance criteria align with PRD success criteria
|
||||
- [ ] Priority levels in stories match PRD feature priorities
|
||||
- [ ] No stories exist without PRD requirement traceability
|
||||
|
||||
### Architecture to Stories Implementation
|
||||
|
||||
- [ ] All architectural components have implementation stories
|
||||
- [ ] Infrastructure setup stories exist for each architectural layer
|
||||
- [ ] Integration points defined in architecture have corresponding stories
|
||||
- [ ] Data migration/setup stories exist if required by architecture
|
||||
- [ ] Security implementation stories cover all architecture security decisions
|
||||
|
||||
## Story and Sequencing Quality
|
||||
|
||||
### Story Completeness
|
||||
|
||||
- [ ] All stories have clear acceptance criteria
|
||||
- [ ] Technical tasks are defined within relevant stories
|
||||
- [ ] Stories include error handling and edge cases
|
||||
- [ ] Each story has clear definition of done
|
||||
- [ ] Stories are appropriately sized (no epic-level stories remaining)
|
||||
|
||||
### Sequencing and Dependencies
|
||||
|
||||
- [ ] Stories are sequenced in logical implementation order
|
||||
- [ ] Dependencies between stories are explicitly documented
|
||||
- [ ] No circular dependencies exist
|
||||
- [ ] Prerequisite technical tasks precede dependent stories
|
||||
- [ ] Foundation/infrastructure stories come before feature stories
|
||||
|
||||
### Greenfield Project Specifics
|
||||
|
||||
- [ ] Initial project setup and configuration stories exist
|
||||
- [ ] If using architecture.md: First story is starter template initialization command
|
||||
- [ ] Development environment setup is documented
|
||||
- [ ] CI/CD pipeline stories are included early in sequence
|
||||
- [ ] Database/storage initialization stories are properly placed
|
||||
- [ ] Authentication/authorization stories precede protected features
|
||||
|
||||
## Risk and Gap Assessment
|
||||
|
||||
### Critical Gaps
|
||||
|
||||
- [ ] No core PRD requirements lack story coverage
|
||||
- [ ] No architectural decisions lack implementation stories
|
||||
- [ ] All integration points have implementation plans
|
||||
- [ ] Error handling strategy is defined and implemented
|
||||
- [ ] Security concerns are all addressed
|
||||
|
||||
### Technical Risks
|
||||
|
||||
- [ ] No conflicting technical approaches between stories
|
||||
- [ ] Technology choices are consistent across all documents
|
||||
- [ ] Performance requirements are achievable with chosen architecture
|
||||
- [ ] Scalability concerns are addressed if applicable
|
||||
- [ ] Third-party dependencies are identified with fallback plans
|
||||
|
||||
## UX and Special Concerns (if applicable)
|
||||
|
||||
### UX Coverage
|
||||
|
||||
- [ ] UX requirements are documented in PRD
|
||||
- [ ] UX implementation tasks exist in relevant stories
|
||||
- [ ] Accessibility requirements have story coverage
|
||||
- [ ] Responsive design requirements are addressed
|
||||
- [ ] User flow continuity is maintained across stories
|
||||
|
||||
### Special Considerations
|
||||
|
||||
- [ ] Compliance requirements are fully addressed
|
||||
- [ ] Internationalization needs are covered if required
|
||||
- [ ] Performance benchmarks are defined and measurable
|
||||
- [ ] Monitoring and observability stories exist
|
||||
- [ ] Documentation stories are included where needed
|
||||
|
||||
## Overall Readiness
|
||||
|
||||
### Ready to Proceed Criteria
|
||||
|
||||
- [ ] All critical issues have been resolved
|
||||
- [ ] High priority concerns have mitigation plans
|
||||
- [ ] Story sequencing supports iterative delivery
|
||||
- [ ] Team has necessary skills for implementation
|
||||
- [ ] No blocking dependencies remain unresolved
|
||||
|
||||
### Quality Indicators
|
||||
|
||||
- [ ] Documents demonstrate thorough analysis
|
||||
- [ ] Clear traceability exists across all artifacts
|
||||
- [ ] Consistent level of detail throughout documents
|
||||
- [ ] Risks are identified with mitigation strategies
|
||||
- [ ] Success criteria are measurable and achievable
|
||||
|
||||
## Assessment Completion
|
||||
|
||||
### Report Quality
|
||||
|
||||
- [ ] All findings are supported by specific examples
|
||||
- [ ] Recommendations are actionable and specific
|
||||
- [ ] Severity levels are appropriately assigned
|
||||
- [ ] Positive findings are highlighted
|
||||
- [ ] Next steps are clearly defined
|
||||
|
||||
### Process Validation
|
||||
|
||||
- [ ] All expected documents were reviewed
|
||||
- [ ] Cross-references were systematically checked
|
||||
- [ ] Project level considerations were applied correctly
|
||||
- [ ] Workflow status was checked and considered
|
||||
- [ ] Output folder was thoroughly searched for artifacts
|
||||
|
||||
---
|
||||
|
||||
## Issue Log
|
||||
|
||||
### Critical Issues Found
|
||||
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
|
||||
### High Priority Issues Found
|
||||
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
|
||||
### Medium Priority Issues Found
|
||||
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
- [ ] ***
|
||||
|
||||
---
|
||||
|
||||
_Use this checklist to ensure comprehensive validation of implementation readiness_
|
||||
@@ -0,0 +1,322 @@
|
||||
# Implementation Ready Check - Workflow Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml</critical>
|
||||
<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
|
||||
|
||||
## 📚 Input Document Discovery
|
||||
|
||||
This workflow validates: PRD, epics/stories, architecture, and may reference UX design, tech specs, or brownfield project documentation.
|
||||
|
||||
**Discovery Process** (execute for each referenced document):
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching to find the complete document
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat the combined content as if it were a single document
|
||||
4. **Brownfield projects**: The `document-project` workflow always creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations in naming conventions.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Implementation Ready Check can run standalone or as part of BMM workflow path.</output>
|
||||
<output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
|
||||
<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
|
||||
<check if="continue">
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
<check if="exit">
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "solutioning-gate-check" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<action>Based on the project_level, understand what artifacts should exist: - Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning) - Level 2: PRD, tech spec, epics/stories (no separate architecture doc) - Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
|
||||
</action>
|
||||
|
||||
<check if="solutioning-gate-check status is file path (already completed)">
|
||||
<output>⚠️ Gate check already completed: {{solutioning-gate-check status}}</output>
|
||||
<ask>Re-running will create a new validation report. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="solutioning-gate-check is not the next expected workflow">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Gate check is out of sequence.</output>
|
||||
<ask>Continue with gate check anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
|
||||
<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
|
||||
|
||||
<template-output>project_context</template-output>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Discover and inventory project artifacts">
|
||||
<action>Search the {output_folder} for relevant planning and solutioning documents based on project level identified in Step 0</action>
|
||||
|
||||
<action>For Level 0-1 projects, locate:
|
||||
|
||||
- Technical specification document(s)
|
||||
- Story/task lists or simple epic breakdowns
|
||||
- Any API or interface definitions
|
||||
</action>
|
||||
|
||||
<action>For Level 2-4 projects, locate:
|
||||
|
||||
- Product Requirements Document (PRD)
|
||||
- Architecture document (architecture.md) (Level 3-4 only)
|
||||
- Technical Specification (Level 2 includes architecture within)
|
||||
- Epic and story breakdowns
|
||||
- UX artifacts if the active path includes UX workflow
|
||||
- Any supplementary planning documents
|
||||
</action>
|
||||
|
||||
<action>Create an inventory of found documents with:
|
||||
|
||||
- Document type and purpose
|
||||
- File path and last modified date
|
||||
- Brief description of what each contains
|
||||
- Any missing expected documents flagged as potential issues
|
||||
</action>
|
||||
|
||||
<template-output>document_inventory</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Deep analysis of core planning documents">
|
||||
<action>Load and thoroughly analyze each discovered document to extract:
|
||||
- Core requirements and success criteria
|
||||
- Architectural decisions and constraints
|
||||
- Technical implementation approaches
|
||||
- User stories and acceptance criteria
|
||||
- Dependencies and sequencing requirements
|
||||
- Any assumptions or risks documented
|
||||
</action>
|
||||
|
||||
<action>For PRD analysis (Level 2-4), focus on:
|
||||
|
||||
- User requirements and use cases
|
||||
- Functional and non-functional requirements
|
||||
- Success metrics and acceptance criteria
|
||||
- Scope boundaries and explicitly excluded items
|
||||
- Priority levels for different features
|
||||
</action>
|
||||
|
||||
<action>For Architecture/Tech Spec analysis, focus on:
|
||||
|
||||
- System design decisions and rationale
|
||||
- Technology stack and framework choices
|
||||
- Integration points and APIs
|
||||
- Data models and storage decisions
|
||||
- Security and performance considerations
|
||||
- Any architectural constraints that might affect story implementation
|
||||
</action>
|
||||
|
||||
<action>For Epic/Story analysis, focus on:
|
||||
|
||||
- Coverage of PRD requirements
|
||||
- Story sequencing and dependencies
|
||||
- Acceptance criteria completeness
|
||||
- Technical tasks within stories
|
||||
- Estimated complexity and effort indicators
|
||||
</action>
|
||||
|
||||
<template-output>document_analysis</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Cross-reference validation and alignment check">
|
||||
<action>Systematically validate alignment between all artifacts, adapting validation based on project level</action>
|
||||
|
||||
<action>PRD ↔ Architecture Alignment (Level 3-4):
|
||||
|
||||
- Verify every PRD requirement has corresponding architectural support
|
||||
- Check that architectural decisions don't contradict PRD constraints
|
||||
- Identify any architectural additions beyond PRD scope (potential gold-plating)
|
||||
- Ensure non-functional requirements from PRD are addressed in architecture document
|
||||
- If using new architecture workflow: verify implementation patterns are defined
|
||||
</action>
|
||||
|
||||
<action>PRD ↔ Stories Coverage (Level 2-4):
|
||||
|
||||
- Map each PRD requirement to implementing stories
|
||||
- Identify any PRD requirements without story coverage
|
||||
- Find stories that don't trace back to PRD requirements
|
||||
- Validate that story acceptance criteria align with PRD success criteria
|
||||
</action>
|
||||
|
||||
<action>Architecture ↔ Stories Implementation Check:
|
||||
|
||||
- Verify architectural decisions are reflected in relevant stories
|
||||
- Check that story technical tasks align with architectural approach
|
||||
- Identify any stories that might violate architectural constraints
|
||||
- Ensure infrastructure and setup stories exist for architectural components
|
||||
</action>
|
||||
|
||||
<action>For Level 0-1 projects (Tech Spec only):
|
||||
|
||||
- Validate internal consistency within tech spec
|
||||
- Check that all specified features have corresponding stories
|
||||
- Verify story sequencing matches technical dependencies
|
||||
</action>
|
||||
|
||||
<template-output>alignment_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Gap and risk analysis">
|
||||
<action>Identify and categorize all gaps, risks, and potential issues discovered during validation</action>
|
||||
|
||||
<action>Check for Critical Gaps:
|
||||
|
||||
- Missing stories for core requirements
|
||||
- Unaddressed architectural concerns
|
||||
- Absent infrastructure or setup stories for greenfield projects
|
||||
- Missing error handling or edge case coverage
|
||||
- Security or compliance requirements not addressed
|
||||
</action>
|
||||
|
||||
<action>Identify Sequencing Issues:
|
||||
|
||||
- Dependencies not properly ordered
|
||||
- Stories that assume components not yet built
|
||||
- Parallel work that should be sequential
|
||||
- Missing prerequisite technical tasks
|
||||
</action>
|
||||
|
||||
<action>Detect Potential Contradictions:
|
||||
|
||||
- Conflicts between PRD and architecture approaches
|
||||
- Stories with conflicting technical approaches
|
||||
- Acceptance criteria that contradict requirements
|
||||
- Resource or technology conflicts
|
||||
</action>
|
||||
|
||||
<action>Find Gold-Plating and Scope Creep:
|
||||
|
||||
- Features in architecture not required by PRD
|
||||
- Stories implementing beyond requirements
|
||||
- Technical complexity beyond project needs
|
||||
- Over-engineering indicators
|
||||
</action>
|
||||
|
||||
<template-output>gap_risk_analysis</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="UX and special concerns validation" optional="true">
|
||||
<check if="UX artifacts exist or UX workflow in active path">
|
||||
<action>Review UX artifacts and validate integration:
|
||||
- Check that UX requirements are reflected in PRD
|
||||
- Verify stories include UX implementation tasks
|
||||
- Ensure architecture supports UX requirements (performance, responsiveness)
|
||||
- Identify any UX concerns not addressed in stories
|
||||
</action>
|
||||
|
||||
<action>Validate accessibility and usability coverage:
|
||||
|
||||
- Check for accessibility requirement coverage in stories
|
||||
- Verify responsive design considerations if applicable
|
||||
- Ensure user flow completeness across stories
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<template-output>ux_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Generate comprehensive readiness assessment">
|
||||
<action>Compile all findings into a structured readiness report with:
|
||||
- Executive summary of readiness status
|
||||
- Project context and validation scope
|
||||
- Document inventory and coverage assessment
|
||||
- Detailed findings organized by severity (Critical, High, Medium, Low)
|
||||
- Specific recommendations for each issue
|
||||
- Overall readiness recommendation (Ready, Ready with Conditions, Not Ready)
|
||||
</action>
|
||||
|
||||
<action>Provide actionable next steps:
|
||||
|
||||
- List any critical issues that must be resolved
|
||||
- Suggest specific document updates needed
|
||||
- Recommend additional stories or tasks required
|
||||
- Propose sequencing adjustments if needed
|
||||
</action>
|
||||
|
||||
<action>Include positive findings:
|
||||
|
||||
- Highlight well-aligned areas
|
||||
- Note particularly thorough documentation
|
||||
- Recognize good architectural decisions
|
||||
- Commend comprehensive story coverage where found
|
||||
</action>
|
||||
|
||||
<template-output>readiness_assessment</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Update status and complete" tag="workflow-status">
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
|
||||
<action>Find workflow_status key "solutioning-gate-check"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["solutioning-gate-check"] = "{output_folder}/bmm-readiness-assessment-{{date}}.md"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
|
||||
<action>Determine next agent from path file based on next workflow</action>
|
||||
</check>
|
||||
|
||||
<output>**✅ Implementation Ready Check Complete!**
|
||||
|
||||
**Assessment Report:**
|
||||
|
||||
- Readiness assessment saved to: {output_folder}/bmm-readiness-assessment-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: solutioning-gate-check marked complete
|
||||
- Next workflow: {{next_workflow}}
|
||||
{{else}}
|
||||
**Note:** Running in standalone mode (no progress tracking)
|
||||
{{/if}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
|
||||
- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
|
||||
- Review the assessment report and address any critical issues before proceeding
|
||||
|
||||
Check status anytime with: `workflow-status`
|
||||
{{else}}
|
||||
Since no workflow is in progress:
|
||||
|
||||
- Refer to the BMM workflow guide if unsure what to do next
|
||||
- Or run `workflow-init` to create a workflow path and get guided next steps
|
||||
{{/if}}
|
||||
</output>
|
||||
|
||||
<template-output>status_update_result</template-output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,146 @@
|
||||
# Implementation Readiness Assessment Report
|
||||
|
||||
**Date:** {{date}}
|
||||
**Project:** {{project_name}}
|
||||
**Assessed By:** {{user_name}}
|
||||
**Assessment Type:** Phase 3 to Phase 4 Transition Validation
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{readiness_assessment}}
|
||||
|
||||
---
|
||||
|
||||
## Project Context
|
||||
|
||||
{{project_context}}
|
||||
|
||||
---
|
||||
|
||||
## Document Inventory
|
||||
|
||||
### Documents Reviewed
|
||||
|
||||
{{document_inventory}}
|
||||
|
||||
### Document Analysis Summary
|
||||
|
||||
{{document_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## Alignment Validation Results
|
||||
|
||||
### Cross-Reference Analysis
|
||||
|
||||
{{alignment_validation}}
|
||||
|
||||
---
|
||||
|
||||
## Gap and Risk Analysis
|
||||
|
||||
### Critical Findings
|
||||
|
||||
{{gap_risk_analysis}}
|
||||
|
||||
---
|
||||
|
||||
## UX and Special Concerns
|
||||
|
||||
{{ux_validation}}
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### 🔴 Critical Issues
|
||||
|
||||
_Must be resolved before proceeding to implementation_
|
||||
|
||||
{{critical_issues}}
|
||||
|
||||
### 🟠 High Priority Concerns
|
||||
|
||||
_Should be addressed to reduce implementation risk_
|
||||
|
||||
{{high_priority_concerns}}
|
||||
|
||||
### 🟡 Medium Priority Observations
|
||||
|
||||
_Consider addressing for smoother implementation_
|
||||
|
||||
{{medium_priority_observations}}
|
||||
|
||||
### 🟢 Low Priority Notes
|
||||
|
||||
_Minor items for consideration_
|
||||
|
||||
{{low_priority_notes}}
|
||||
|
||||
---
|
||||
|
||||
## Positive Findings
|
||||
|
||||
### ✅ Well-Executed Areas
|
||||
|
||||
{{positive_findings}}
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Immediate Actions Required
|
||||
|
||||
{{immediate_actions}}
|
||||
|
||||
### Suggested Improvements
|
||||
|
||||
{{suggested_improvements}}
|
||||
|
||||
### Sequencing Adjustments
|
||||
|
||||
{{sequencing_adjustments}}
|
||||
|
||||
---
|
||||
|
||||
## Readiness Decision
|
||||
|
||||
### Overall Assessment: {{overall_readiness_status}}
|
||||
|
||||
{{readiness_rationale}}
|
||||
|
||||
### Conditions for Proceeding (if applicable)
|
||||
|
||||
{{conditions_for_proceeding}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
{{recommended_next_steps}}
|
||||
|
||||
### Workflow Status Update
|
||||
|
||||
{{status_update_result}}
|
||||
|
||||
---
|
||||
|
||||
## Appendices
|
||||
|
||||
### A. Validation Criteria Applied
|
||||
|
||||
{{validation_criteria_used}}
|
||||
|
||||
### B. Traceability Matrix
|
||||
|
||||
{{traceability_matrix}}
|
||||
|
||||
### C. Risk Mitigation Strategies
|
||||
|
||||
{{risk_mitigation_strategies}}
|
||||
|
||||
---
|
||||
|
||||
_This readiness assessment was generated using the BMad Method Implementation Ready Check workflow (v6-alpha)_
|
||||
@@ -0,0 +1,189 @@
|
||||
# Implementation Readiness Validation Criteria
|
||||
# Defines systematic validation rules by project level
|
||||
|
||||
validation_rules:
|
||||
# Level 0-1 Projects (Simple, minimal planning)
|
||||
level_0_1:
|
||||
required_documents:
|
||||
- tech_spec
|
||||
- stories_or_tasks
|
||||
|
||||
validations:
|
||||
- name: "Tech Spec Completeness"
|
||||
checks:
|
||||
- "All features defined with implementation approach"
|
||||
- "Technical dependencies identified"
|
||||
- "API contracts defined if applicable"
|
||||
- "Data models specified"
|
||||
|
||||
- name: "Story Coverage"
|
||||
checks:
|
||||
- "All tech spec features have corresponding stories"
|
||||
- "Stories are sequenced logically"
|
||||
- "Technical tasks are defined"
|
||||
- "No critical gaps in coverage"
|
||||
|
||||
# Level 2 Projects (PRD + Tech Spec, no separate architecture)
|
||||
level_2:
|
||||
required_documents:
|
||||
- prd
|
||||
- tech_spec # Includes architecture decisions
|
||||
- epics_and_stories
|
||||
|
||||
validations:
|
||||
- name: "PRD to Tech Spec Alignment"
|
||||
checks:
|
||||
- "All PRD requirements addressed in tech spec"
|
||||
- "Architecture embedded in tech spec covers PRD needs"
|
||||
- "Non-functional requirements are specified"
|
||||
- "Technical approach supports business goals"
|
||||
|
||||
- name: "Story Coverage and Alignment"
|
||||
checks:
|
||||
- "Every PRD requirement has story coverage"
|
||||
- "Stories align with tech spec approach"
|
||||
- "Epic breakdown is complete"
|
||||
- "Acceptance criteria match PRD success criteria"
|
||||
|
||||
- name: "Sequencing Validation"
|
||||
checks:
|
||||
- "Foundation stories come first"
|
||||
- "Dependencies are properly ordered"
|
||||
- "Iterative delivery is possible"
|
||||
- "No circular dependencies"
|
||||
|
||||
# Level 3-4 Projects (Full planning with separate architecture)
|
||||
level_3_4:
|
||||
required_documents:
|
||||
- prd
|
||||
- architecture
|
||||
- epics_and_stories
|
||||
|
||||
validations:
|
||||
- name: "PRD Completeness"
|
||||
checks:
|
||||
- "User requirements fully documented"
|
||||
- "Success criteria are measurable"
|
||||
- "Scope boundaries clearly defined"
|
||||
- "Priorities are assigned"
|
||||
|
||||
- name: "Architecture Coverage"
|
||||
checks:
|
||||
- "All PRD requirements have architectural support"
|
||||
- "System design is complete"
|
||||
- "Integration points defined"
|
||||
- "Security architecture specified"
|
||||
- "Performance considerations addressed"
|
||||
- "If architecture.md: Implementation patterns defined"
|
||||
- "If architecture.md: Technology versions verified and current"
|
||||
- "If architecture.md: Starter template command documented (if applicable)"
|
||||
|
||||
- name: "PRD-Architecture Alignment"
|
||||
checks:
|
||||
- "No architecture gold-plating beyond PRD"
|
||||
- "NFRs from PRD reflected in architecture"
|
||||
- "Technology choices support requirements"
|
||||
- "Scalability matches expected growth"
|
||||
- "If UX spec exists: Architecture supports UX requirements"
|
||||
- "If UX spec exists: Component library supports interaction patterns"
|
||||
|
||||
- name: "Story Implementation Coverage"
|
||||
checks:
|
||||
- "All architectural components have stories"
|
||||
- "Infrastructure setup stories exist"
|
||||
- "Integration implementation planned"
|
||||
- "Security implementation stories present"
|
||||
|
||||
- name: "Comprehensive Sequencing"
|
||||
checks:
|
||||
- "Infrastructure before features"
|
||||
- "Authentication before protected resources"
|
||||
- "Core features before enhancements"
|
||||
- "Dependencies properly ordered"
|
||||
- "Allows for iterative releases"
|
||||
|
||||
# Special validation contexts
|
||||
special_contexts:
|
||||
greenfield:
|
||||
additional_checks:
|
||||
- "Project initialization stories exist"
|
||||
- "If using architecture.md: First story is starter template initialization"
|
||||
- "Development environment setup documented"
|
||||
- "CI/CD pipeline stories included"
|
||||
- "Initial data/schema setup planned"
|
||||
- "Deployment infrastructure stories present"
|
||||
|
||||
ux_workflow_active:
|
||||
additional_checks:
|
||||
- "UX requirements in PRD"
|
||||
- "UX implementation stories exist"
|
||||
- "Accessibility requirements covered"
|
||||
- "Responsive design addressed"
|
||||
- "User flow continuity maintained"
|
||||
|
||||
api_heavy:
|
||||
additional_checks:
|
||||
- "API contracts fully defined"
|
||||
- "Versioning strategy documented"
|
||||
- "Authentication/authorization specified"
|
||||
- "Rate limiting considered"
|
||||
- "API documentation stories included"
|
||||
|
||||
# Severity definitions
|
||||
severity_levels:
|
||||
critical:
|
||||
description: "Must be resolved before implementation"
|
||||
examples:
|
||||
- "Missing stories for core requirements"
|
||||
- "Conflicting technical approaches"
|
||||
- "No infrastructure setup for greenfield"
|
||||
- "Security requirements not addressed"
|
||||
|
||||
high:
|
||||
description: "Should be addressed to reduce risk"
|
||||
examples:
|
||||
- "Incomplete acceptance criteria"
|
||||
- "Unclear story dependencies"
|
||||
- "Missing error handling coverage"
|
||||
- "Performance requirements not validated"
|
||||
|
||||
medium:
|
||||
description: "Consider addressing for smoother implementation"
|
||||
examples:
|
||||
- "Documentation gaps"
|
||||
- "Test strategy not defined"
|
||||
- "Monitoring approach unclear"
|
||||
- "Minor sequencing improvements possible"
|
||||
|
||||
low:
|
||||
description: "Minor improvements for consideration"
|
||||
examples:
|
||||
- "Formatting inconsistencies"
|
||||
- "Optional enhancements identified"
|
||||
- "Style guide compliance"
|
||||
- "Nice-to-have features noted"
|
||||
|
||||
# Readiness decision criteria
|
||||
readiness_decisions:
|
||||
ready:
|
||||
criteria:
|
||||
- "No critical issues found"
|
||||
- "All required documents present"
|
||||
- "Core alignments validated"
|
||||
- "Story sequencing logical"
|
||||
- "Team can begin implementation"
|
||||
|
||||
ready_with_conditions:
|
||||
criteria:
|
||||
- "Only high/medium issues found"
|
||||
- "Mitigation plans identified"
|
||||
- "Core path to MVP clear"
|
||||
- "Issues won't block initial stories"
|
||||
|
||||
not_ready:
|
||||
criteria:
|
||||
- "Critical issues identified"
|
||||
- "Major gaps in coverage"
|
||||
- "Conflicting approaches found"
|
||||
- "Required documents missing"
|
||||
- "Blocking dependencies unresolved"
|
||||
@@ -0,0 +1,64 @@
|
||||
# Implementation Ready Check - Workflow Configuration
|
||||
name: solutioning-gate-check
|
||||
description: "Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions."
|
||||
author: "BMad Builder"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
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"
|
||||
date: system-generated
|
||||
|
||||
# Workflow status integration
|
||||
workflow_status_workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
workflow_paths_dir: "{project-root}/bmad/bmm/workflows/workflow-status/paths"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check"
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
|
||||
|
||||
# Expected input documents (varies by project level)
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/prd*.md"
|
||||
- architecture: "{output_folder}/architecture*.md or {output_folder}/architecture*.md"
|
||||
- tech_spec: "{output_folder}/tech-spec*.md"
|
||||
- epics_stories: "{output_folder}/epic*.md"
|
||||
- ux_artifacts: "{output_folder}/ux*.md"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
|
||||
architecture:
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
|
||||
ux_design:
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
|
||||
tech_spec:
|
||||
whole: "{output_folder}/*tech-spec*.md"
|
||||
sharded: "{output_folder}/*tech-spec*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Validation criteria data
|
||||
validation_criteria: "{installed_path}/validation-criteria.yaml"
|
||||
|
||||
standalone: true
|
||||
221
bmad/bmm/workflows/4-implementation/README.md
Normal file
221
bmad/bmm/workflows/4-implementation/README.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# Phase 4: Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 4 is where planning transitions into actual development. This phase manages the iterative implementation of stories defined in the epic files, tracking their progress through a well-defined status workflow.
|
||||
|
||||
## Status Definitions
|
||||
|
||||
### Epic Status
|
||||
|
||||
Epics progress through a simple two-state flow:
|
||||
|
||||
| Status | Description | Next Status |
|
||||
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
||||
| **backlog** | Epic exists in epic file but technical context has not been created | contexted |
|
||||
| **contexted** | Epic technical context has been created via `epic-tech-context` workflow. This is a prerequisite before any stories in the epic can be drafted. | - |
|
||||
|
||||
**File Indicators:**
|
||||
|
||||
- `backlog`: No `epic-{n}-context.md` file exists
|
||||
- `contexted`: `{output_folder}/epic-{n}-context.md` file exists
|
||||
|
||||
### Story Status
|
||||
|
||||
Stories progress through a six-state flow representing their journey from idea to implementation:
|
||||
|
||||
| Status | Description | Set By | Next Status |
|
||||
| ----------------- | ---------------------------------------------------------------------------------- | ------------- | ------------- |
|
||||
| **backlog** | Story only exists in the epic file, no work has begun | Initial state | drafted |
|
||||
| **drafted** | Story file has been created via `create-story` workflow | SM Agent | ready-for-dev |
|
||||
| **ready-for-dev** | Story has been drafted, approved, and context created via `story-context` workflow | SM Agent | in-progress |
|
||||
| **in-progress** | Developer is actively implementing the story | Dev Agent | review |
|
||||
| **review** | Implementation complete, under SM review via `code-review` workflow | Dev Agent | done |
|
||||
| **done** | Story has been reviewed and completed | Dev Agent | - |
|
||||
|
||||
**File Indicators:**
|
||||
|
||||
- `backlog`: No story file exists
|
||||
- `drafted`: `{story_dir}/{story-key}.md` file exists (e.g., `1-1-user-auth.md`)
|
||||
- `ready-for-dev`: Both story file and context exist (e.g., `1-1-user-auth-context.md`)
|
||||
- `in-progress`, `review`, `done`: Manual status updates in sprint-status.yaml
|
||||
|
||||
### Retrospective Status
|
||||
|
||||
Optional retrospectives can be completed after an epic:
|
||||
|
||||
| Status | Description |
|
||||
| ------------- | -------------------------------------------------- |
|
||||
| **optional** | Retrospective can be completed but is not required |
|
||||
| **completed** | Retrospective has been completed |
|
||||
|
||||
## Status Transitions
|
||||
|
||||
### Epic Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
backlog --> contexted[contexted via epic-tech-context]
|
||||
```
|
||||
|
||||
### Story Flow
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
backlog --> drafted[drafted via create-story]
|
||||
drafted --> ready[ready-for-dev via story-context]
|
||||
ready --> progress[in-progress - dev starts]
|
||||
progress --> review[review via code-review]
|
||||
review --> done[done - dev completes]
|
||||
```
|
||||
|
||||
## Sprint Status Management
|
||||
|
||||
The `sprint-status.yaml` file is the single source of truth for tracking all work items. It contains:
|
||||
|
||||
- All epics with their current status
|
||||
- All stories with their current status
|
||||
- Retrospective placeholders for each epic
|
||||
- Clear documentation of status definitions
|
||||
|
||||
### Example Sprint Status File
|
||||
|
||||
```yaml
|
||||
development_status:
|
||||
epic-1: contexted
|
||||
1-1-project-foundation: done
|
||||
1-2-app-shell: done
|
||||
1-3-user-authentication: in-progress
|
||||
1-4-plant-data-model: ready-for-dev
|
||||
1-5-add-plant-manual: drafted
|
||||
1-6-photo-identification: backlog
|
||||
1-7-plant-naming: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
epic-2: backlog
|
||||
2-1-personality-system: backlog
|
||||
2-2-chat-interface: backlog
|
||||
2-3-llm-integration: backlog
|
||||
epic-2-retrospective: optional
|
||||
```
|
||||
|
||||
## Workflows in Phase 4
|
||||
|
||||
### Core Workflows
|
||||
|
||||
| Workflow | Purpose | Updates Status |
|
||||
| --------------------- | -------------------------------------------------- | ----------------------------------- |
|
||||
| **sprint-planning** | Generate/update sprint-status.yaml from epic files | Auto-detects file-based statuses |
|
||||
| **epic-tech-context** | Create technical context for an epic | epic: backlog → contexted |
|
||||
| **create-story** | Draft a story from epics/PRD | story: backlog → drafted |
|
||||
| **story-context** | Add implementation context to story | story: drafted → ready-for-dev |
|
||||
| **dev-story** | Developer implements the story | story: ready-for-dev → in-progress |
|
||||
| **code-review** | SM reviews implementation | story: in-progress → review |
|
||||
| **retrospective** | Conduct epic retrospective | retrospective: optional → completed |
|
||||
| **correct-course** | Course correction when needed | Various status updates |
|
||||
|
||||
### Sprint Planning Workflow
|
||||
|
||||
The `sprint-planning` workflow is the foundation of Phase 4. It:
|
||||
|
||||
1. **Parses all epic files** (`epic*.md` or `epics.md`)
|
||||
2. **Extracts all epics and stories** maintaining their order
|
||||
3. **Auto-detects current status** based on existing files:
|
||||
- Checks for epic context files
|
||||
- Checks for story files
|
||||
- Checks for story context files
|
||||
4. **Generates sprint-status.yaml** with current reality
|
||||
5. **Preserves manual status updates** (won't downgrade statuses)
|
||||
|
||||
Run this workflow:
|
||||
|
||||
- Initially after Phase 3 completion
|
||||
- After creating epic contexts
|
||||
- Periodically to sync file-based status
|
||||
- To verify current project state
|
||||
|
||||
### Workflow Guidelines
|
||||
|
||||
1. **Epic Context First**: Epics should be contexted before drafting their stories
|
||||
2. **Flexible Parallelism**: Multiple stories can be in-progress based on team capacity
|
||||
3. **Sequential Default**: Stories within an epic are typically worked in order
|
||||
4. **Learning Transfer**: SM drafts next story after previous is done, incorporating learnings
|
||||
5. **Review Flow**: Dev moves to review, SM reviews, Dev moves to done
|
||||
|
||||
## Agent Responsibilities
|
||||
|
||||
### SM (Scrum Master) Agent
|
||||
|
||||
- Run `sprint-planning` to generate initial status
|
||||
- Create epic contexts (`epic-tech-context`)
|
||||
- Draft stories (`create-story`)
|
||||
- Create story contexts (`story-context`)
|
||||
- Review completed work (`code-review`)
|
||||
- Update status in sprint-status.yaml
|
||||
|
||||
### Developer Agent
|
||||
|
||||
- Check sprint-status.yaml for `ready-for-dev` stories
|
||||
- Update status to `in-progress` when starting
|
||||
- Implement stories (`dev-story`)
|
||||
- Move to `review` when complete
|
||||
- Address review feedback
|
||||
- Update to `done` after approval
|
||||
|
||||
### Test Architect
|
||||
|
||||
- Monitor stories entering `review` status
|
||||
- Track epic progress
|
||||
- Identify when retrospectives needed
|
||||
- Validate implementation quality
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always run sprint-planning first** to establish current state
|
||||
2. **Update status immediately** as work progresses
|
||||
3. **Check sprint-status.yaml** before starting any work
|
||||
4. **Preserve learning** by drafting stories sequentially when possible
|
||||
5. **Document decisions** in story and context files
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Story File Naming
|
||||
|
||||
- Format: `{epic}-{story}-{kebab-title}.md`
|
||||
- Example: `1-1-user-authentication.md`
|
||||
- Avoids YAML float parsing issues (1.1 vs 1.10)
|
||||
- Makes files self-descriptive
|
||||
|
||||
### Git Branch Naming
|
||||
|
||||
- Format: `feat/{epic}-{story}-{kebab-title}`
|
||||
- Example: `feat/1-1-user-authentication`
|
||||
- Consistent with story file naming
|
||||
- Clean for branch management
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
{output_folder}/
|
||||
├── sprint-status.yaml # Sprint status tracking
|
||||
├── epic*.md or epics.md # Epic definitions
|
||||
├── epic-1-context.md # Epic technical contexts
|
||||
├── epic-2-context.md
|
||||
└── stories/
|
||||
├── 1-1-user-authentication.md # Story drafts
|
||||
├── 1-1-user-authentication-context.md # Story contexts
|
||||
├── 1-2-account-management.md
|
||||
├── 1-2-account-management-context.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After Phase 4 implementation, projects typically move to:
|
||||
|
||||
- Deployment and release
|
||||
- User acceptance testing
|
||||
- Production monitoring
|
||||
- Maintenance and updates
|
||||
|
||||
The sprint-status.yaml file provides a complete audit trail of the development process and can be used for project reporting and retrospectives.
|
||||
69
bmad/bmm/workflows/4-implementation/code-review/README.md
Normal file
69
bmad/bmm/workflows/4-implementation/code-review/README.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# Review Story (Senior Developer Code Review)
|
||||
|
||||
Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
|
||||
|
||||
## What It Does
|
||||
|
||||
- Auto-discovers the target story or accepts an explicit `story_path`
|
||||
- Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
|
||||
- Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
|
||||
- Locates the epic Tech Spec and relevant architecture/standards docs
|
||||
- Uses MCP servers for best-practices and security references; falls back to web search
|
||||
- Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
|
||||
- Evaluates code quality, security, and test coverage
|
||||
- Appends a "Senior Developer Review (AI)" section to the story with findings and action items
|
||||
- Optionally updates story Status based on outcome
|
||||
|
||||
## How to Invoke
|
||||
|
||||
- Tell the Dev Agent to perform a \*code-review after loading the dev agent. This is a context intensive operation so this should not be done in the same context as a just completed dev session - clear the context, reload the dev, then run code-review!
|
||||
|
||||
## Inputs and Variables
|
||||
|
||||
- `story_path` (optional): Explicit path to a story file
|
||||
- `story_dir` (from config): `{project-root}/bmad/bmm/config.yaml` → `dev_story_location`
|
||||
- `allow_status_values`: Defaults include `Ready for Review`, `Review`
|
||||
- `auto_discover_context` (default: true)
|
||||
- `auto_discover_tech_spec` (default: true)
|
||||
- `tech_spec_glob_template`: `tech-spec-epic-{{epic_num}}*.md`
|
||||
- `arch_docs_search_dirs`: Defaults to `docs/` and `outputs/`
|
||||
- `enable_mcp_doc_search` (default: true)
|
||||
- `enable_web_fallback` (default: true)
|
||||
- `update_status_on_result` (default: false)
|
||||
|
||||
## Story Updates
|
||||
|
||||
- Appends a section titled: `Senior Developer Review (AI)` at the end
|
||||
- Adds a Change Log entry: "Senior Developer Review notes appended"
|
||||
- If enabled, updates `Status` based on outcome
|
||||
|
||||
## Persistence and Backlog
|
||||
|
||||
To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):
|
||||
|
||||
- Story tasks: Inserts unchecked items under `Tasks / Subtasks` in a "Review Follow-ups (AI)" subsection so `dev-story` can pick them up next.
|
||||
- Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
|
||||
- Backlog file: Appends normalized rows to `docs/backlog.md` (created if missing) for cross-cutting or longer-term improvements.
|
||||
- Epic follow-ups: If an epic Tech Spec is found, appends to its `Post-Review Follow-ups` section.
|
||||
|
||||
Configure via `workflow.yaml` variables:
|
||||
|
||||
- `persist_action_items` (default: true)
|
||||
- `persist_targets`: `story_tasks`, `story_review_section`, `backlog_file`, `epic_followups`
|
||||
- `backlog_file` (default: `{project-root}/docs/backlog.md`)
|
||||
- `update_epic_followups` (default: true)
|
||||
- `epic_followups_section_title` (default: `Post-Review Follow-ups`)
|
||||
|
||||
Routing guidance:
|
||||
|
||||
- Put must-fix items to ship the story into the story’s tasks.
|
||||
- Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
|
||||
- Put cross-cutting, future, or refactor work into the backlog file.
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- `dev-story` — Implements tasks/subtasks and can act on review action items
|
||||
- `story-context` — Generates Story Context for a single story
|
||||
- `tech-spec` — Generates epic Tech Spec documents
|
||||
|
||||
_Part of the BMAD Method v6 — Implementation Phase_
|
||||
@@ -0,0 +1,12 @@
|
||||
# Engineering Backlog
|
||||
|
||||
This backlog collects cross-cutting or future action items that emerge from reviews and planning.
|
||||
|
||||
Routing guidance:
|
||||
|
||||
- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics.
|
||||
- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`.
|
||||
- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section.
|
||||
|
||||
| Date | Story | Epic | Type | Severity | Owner | Status | Notes |
|
||||
| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- |
|
||||
22
bmad/bmm/workflows/4-implementation/code-review/checklist.md
Normal file
22
bmad/bmm/workflows/4-implementation/code-review/checklist.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# Senior Developer Review - Validation Checklist
|
||||
|
||||
- [ ] Story file loaded from `{{story_path}}`
|
||||
- [ ] Story Status verified as one of: {{allow_status_values}}
|
||||
- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
|
||||
- [ ] Story Context located or warning recorded
|
||||
- [ ] Epic Tech Spec located or warning recorded
|
||||
- [ ] Architecture/standards docs loaded (as available)
|
||||
- [ ] Tech stack detected and documented
|
||||
- [ ] MCP doc search performed (or web fallback) and references captured
|
||||
- [ ] Acceptance Criteria cross-checked against implementation
|
||||
- [ ] File List reviewed and validated for completeness
|
||||
- [ ] Tests identified and mapped to ACs; gaps noted
|
||||
- [ ] Code quality review performed on changed files
|
||||
- [ ] Security review performed on changed files and dependencies
|
||||
- [ ] Outcome decided (Approve/Changes Requested/Blocked)
|
||||
- [ ] Review notes appended under "Senior Developer Review (AI)"
|
||||
- [ ] Change Log updated with review entry
|
||||
- [ ] Status updated according to settings (if enabled)
|
||||
- [ ] Story saved successfully
|
||||
|
||||
_Reviewer: {{user_name}} on {{date}}_
|
||||
420
bmad/bmm/workflows/4-implementation/code-review/instructions.md
Normal file
420
bmad/bmm/workflows/4-implementation/code-review/instructions.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# Senior Developer Review - Workflow Instructions
|
||||
|
||||
````xml
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>This workflow performs a SYSTEMATIC Senior Developer Review on a story with status "review", validates EVERY acceptance criterion and EVERY completed task, appends structured review notes with evidence, and updates the story status based on outcome.</critical>
|
||||
<critical>If story_path is provided, use it. Otherwise, find the first story in sprint-status.yaml with status "review". If none found, offer ad-hoc review option.</critical>
|
||||
<critical>Ad-hoc review mode: User can specify any files to review and what to review for (quality, security, requirements, etc.). Creates standalone review report.</critical>
|
||||
<critical>SYSTEMATIC VALIDATION REQUIREMENT: For EVERY acceptance criterion, verify implementation with evidence (file:line). For EVERY task marked complete, verify it was actually done. Tasks marked complete but not done = HIGH SEVERITY finding.</critical>
|
||||
<critical>⚠️ ZERO TOLERANCE FOR LAZY VALIDATION ⚠️</critical>
|
||||
<critical>If you FAIL to catch even ONE task marked complete that was NOT actually implemented, or ONE acceptance criterion marked done that is NOT in the code with evidence, you have FAILED YOUR ONLY PURPOSE. This is an IMMEDIATE DISQUALIFICATION. No shortcuts. No assumptions. No "looks good enough." You WILL read every file. You WILL verify every claim. You WILL provide evidence (file:line) for EVERY validation. Failure to catch false completions = you failed humanity and the project. Your job is to be the uncompromising gatekeeper. DO YOUR JOB COMPLETELY OR YOU WILL BE REPLACED.</critical>
|
||||
<critical>Only modify the story file in these areas: Status, Dev Agent Record (Completion Notes), File List (if corrections needed), Change Log, and the appended "Senior Developer Review (AI)" section.</critical>
|
||||
<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
|
||||
|
||||
<critical>DOCUMENT OUTPUT: Technical review reports. Structured findings with severity levels and action items. User skill level ({user_skill_level}) affects conversation style ONLY, not review content.</critical>
|
||||
|
||||
## 📚 Document Discovery - Selective Epic Loading
|
||||
|
||||
**Strategy**: This workflow needs only ONE specific epic and its stories for review context, not all epics. This provides huge efficiency gains when epics are sharded.
|
||||
|
||||
**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
|
||||
|
||||
1. **Determine which epic** you need (epic_num from story being reviewed - e.g., story "3-2-feature-name" needs Epic 3)
|
||||
2. **Check for sharded version**: Look for `epics/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
|
||||
- DO NOT load all epic files - only the one needed!
|
||||
- This is the key efficiency optimization for large multi-epic projects
|
||||
4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
|
||||
|
||||
**Other Documents (architecture, ux-design) - Full Load:**
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat combined content as single document
|
||||
4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for reviewing UI-focused stories.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Find story ready for review" tag="sprint-status">
|
||||
<check if="{{story_path}} is provided">
|
||||
<action>Use {{story_path}} directly</action>
|
||||
<action>Read COMPLETE story file and parse sections</action>
|
||||
<action>Extract story_key from filename or story metadata</action>
|
||||
<action>Verify Status is "review" - if not, HALT with message: "Story status must be 'review' to proceed"</action>
|
||||
</check>
|
||||
|
||||
<check if="{{story_path}} is NOT provided">
|
||||
<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
||||
<action>Parse the development_status section completely</action>
|
||||
|
||||
<action>Find FIRST story (reading in order from top to bottom) where:
|
||||
- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
|
||||
- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
|
||||
- Status value equals "review"
|
||||
</action>
|
||||
|
||||
<check if="no story with status 'review' found">
|
||||
<output>📋 No stories with status "review" found
|
||||
|
||||
**What would you like to do?**
|
||||
1. Run `dev-story` to implement and mark a story ready for review
|
||||
2. Check sprint-status.yaml for current story states
|
||||
3. Tell me what code to review and what to review it for
|
||||
</output>
|
||||
<ask>Select an option (1/2/3):</ask>
|
||||
|
||||
<check if="option 3 selected">
|
||||
<ask>What code would you like me to review?
|
||||
|
||||
Provide:
|
||||
- File path(s) or directory to review
|
||||
- What to review for:
|
||||
• General quality and standards
|
||||
• Requirements compliance
|
||||
• Security concerns
|
||||
• Performance issues
|
||||
• Architecture alignment
|
||||
• Something else (specify)
|
||||
|
||||
Your input:</ask>
|
||||
|
||||
<action>Parse user input to extract:
|
||||
- {{review_files}}: file paths or directories to review
|
||||
- {{review_focus}}: what aspects to focus on
|
||||
- {{review_context}}: any additional context provided
|
||||
</action>
|
||||
|
||||
<action>Set ad_hoc_review_mode = true</action>
|
||||
<action>Skip to step 4 with custom scope</action>
|
||||
</check>
|
||||
|
||||
<check if="option 1 or 2 or no option 3">
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Use the first story found with status "review"</action>
|
||||
<action>Resolve story file path in {{story_dir}}</action>
|
||||
<action>Read the COMPLETE story file</action>
|
||||
</check>
|
||||
|
||||
<action>Extract {{epic_num}} and {{story_num}} from filename (e.g., story-2.3.*.md) and story metadata</action>
|
||||
<action>Parse sections: Status, Story, Acceptance Criteria, Tasks/Subtasks (and completion states), Dev Notes, Dev Agent Record (Context Reference, Completion Notes, File List), Change Log</action>
|
||||
<action if="story cannot be read">HALT with message: "Unable to read story file"</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Resolve story context file and specification inputs">
|
||||
<action>Locate story context file: Under Dev Agent Record → Context Reference, read referenced path(s). If missing, search {{output_folder}} for files matching pattern "story-{{epic_num}}.{{story_num}}*.context.xml" and use the most recent.</action>
|
||||
<action if="no story context file found">Continue but record a WARNING in review notes: "No story context file found"</action>
|
||||
|
||||
<action>Locate Epic Tech Spec: Search {{tech_spec_search_dir}} with glob {{tech_spec_glob_template}} (resolve {{epic_num}})</action>
|
||||
<action if="no tech spec found">Continue but record a WARNING in review notes: "No Tech Spec found for epic {{epic_num}}"</action>
|
||||
|
||||
<action>Load architecture/standards docs: For each file name in {{arch_docs_file_names}} within {{arch_docs_search_dirs}}, read if exists. Collect testing, coding standards, security, and architectural patterns.</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Detect tech stack and establish best-practice reference set">
|
||||
<action>Detect primary ecosystem(s) by scanning for manifests (e.g., package.json, pyproject.toml, go.mod, Dockerfile). Record key frameworks (e.g., Node/Express, React/Vue, Python/FastAPI, etc.).</action>
|
||||
<action>Synthesize a concise "Best-Practices and References" note capturing any updates or considerations that should influence the review (cite links and versions if available).</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Systematic validation of implementation against acceptance criteria and tasks">
|
||||
<check if="ad_hoc_review_mode == true">
|
||||
<action>Use {{review_files}} as the file list to review</action>
|
||||
<action>Focus review on {{review_focus}} aspects specified by user</action>
|
||||
<action>Use {{review_context}} for additional guidance</action>
|
||||
<action>Skip acceptance criteria checking (no story context)</action>
|
||||
<action>If architecture docs exist, verify alignment with architectural constraints</action>
|
||||
</check>
|
||||
|
||||
<check if="ad_hoc_review_mode != true">
|
||||
<critical>SYSTEMATIC VALIDATION - Check EVERY AC and EVERY task marked complete</critical>
|
||||
|
||||
<action>From the story, read Acceptance Criteria section completely - parse into numbered list</action>
|
||||
<action>From the story, read Tasks/Subtasks section completely - parse ALL tasks and subtasks with their completion state ([x] = completed, [ ] = incomplete)</action>
|
||||
<action>From Dev Agent Record → File List, compile list of changed/added files. If File List is missing or clearly incomplete, search repo for recent changes relevant to the story scope (heuristics: filenames matching components/services/routes/tests inferred from ACs/tasks).</action>
|
||||
|
||||
<critical>Step 4A: SYSTEMATIC ACCEPTANCE CRITERIA VALIDATION</critical>
|
||||
<action>Create AC validation checklist with one entry per AC</action>
|
||||
<action>For EACH acceptance criterion (AC1, AC2, AC3, etc.):
|
||||
1. Read the AC requirement completely
|
||||
2. Search changed files for evidence of implementation
|
||||
3. Determine: IMPLEMENTED, PARTIAL, or MISSING
|
||||
4. Record specific evidence (file:line references where AC is satisfied)
|
||||
5. Check for corresponding tests (unit/integration/E2E as applicable)
|
||||
6. If PARTIAL or MISSING: Flag as finding with severity based on AC criticality
|
||||
7. Document in AC validation checklist
|
||||
</action>
|
||||
<action>Generate AC Coverage Summary: "X of Y acceptance criteria fully implemented"</action>
|
||||
|
||||
<critical>Step 4B: SYSTEMATIC TASK COMPLETION VALIDATION</critical>
|
||||
<action>Create task validation checklist with one entry per task/subtask</action>
|
||||
<action>For EACH task/subtask marked as COMPLETED ([x]):
|
||||
1. Read the task description completely
|
||||
2. Search changed files for evidence the task was actually done
|
||||
3. Determine: VERIFIED COMPLETE, QUESTIONABLE, or NOT DONE
|
||||
4. Record specific evidence (file:line references proving task completion)
|
||||
5. **CRITICAL**: If marked complete but NOT DONE → Flag as HIGH SEVERITY finding with message: "Task marked complete but implementation not found: [task description]"
|
||||
6. If QUESTIONABLE → Flag as MEDIUM SEVERITY finding: "Task completion unclear: [task description]"
|
||||
7. Document in task validation checklist
|
||||
</action>
|
||||
<action>For EACH task/subtask marked as INCOMPLETE ([ ]):
|
||||
1. Note it was not claimed to be complete
|
||||
2. Check if it was actually done anyway (sometimes devs forget to check boxes)
|
||||
3. If done but not marked: Note in review (helpful correction, not a finding)
|
||||
</action>
|
||||
<action>Generate Task Completion Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"</action>
|
||||
|
||||
<critical>Step 4C: CROSS-CHECK EPIC TECH-SPEC REQUIREMENTS</critical>
|
||||
<action>Cross-check epic tech-spec requirements and architecture constraints against the implementation intent in files.</action>
|
||||
<action if="critical architecture constraints are violated (e.g., layering, dependency rules)">flag as High Severity finding.</action>
|
||||
|
||||
<critical>Step 4D: COMPILE VALIDATION FINDINGS</critical>
|
||||
<action>Compile all validation findings into structured list:
|
||||
- Missing AC implementations (severity based on AC importance)
|
||||
- Partial AC implementations (MEDIUM severity)
|
||||
- Tasks falsely marked complete (HIGH severity - this is critical)
|
||||
- Questionable task completions (MEDIUM severity)
|
||||
- Missing tests for ACs (severity based on AC criticality)
|
||||
- Architecture violations (HIGH severity)
|
||||
</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Perform code quality and risk review">
|
||||
<action>For each changed file, skim for common issues appropriate to the stack: error handling, input validation, logging, dependency injection, thread-safety/async correctness, resource cleanup, performance anti-patterns.</action>
|
||||
<action>Perform security review: injection risks, authZ/authN handling, secret management, unsafe defaults, un-validated redirects, CORS misconfigured, dependency vulnerabilities (based on manifests).</action>
|
||||
<action>Check tests quality: assertions are meaningful, edge cases covered, deterministic behavior, proper fixtures, no flakiness patterns.</action>
|
||||
<action>Capture concrete, actionable suggestions with severity (High/Med/Low) and rationale. When possible, suggest specific code-level changes (filenames + line ranges) without rewriting large sections.</action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Decide review outcome and prepare comprehensive notes">
|
||||
<action>Determine outcome based on validation results:
|
||||
- BLOCKED: Any HIGH severity finding (AC missing, task falsely marked complete, critical architecture violation)
|
||||
- CHANGES REQUESTED: Any MEDIUM severity findings or multiple LOW severity issues
|
||||
- APPROVE: All ACs implemented, all completed tasks verified, no significant issues
|
||||
</action>
|
||||
|
||||
<action>Prepare a structured review report with sections:
|
||||
1. **Summary**: Brief overview of review outcome and key concerns
|
||||
2. **Outcome**: Approve | Changes Requested | Blocked (with justification)
|
||||
3. **Key Findings** (by severity):
|
||||
- HIGH severity issues first (especially falsely marked complete tasks)
|
||||
- MEDIUM severity issues
|
||||
- LOW severity issues
|
||||
4. **Acceptance Criteria Coverage**:
|
||||
- Include complete AC validation checklist from Step 4A
|
||||
- Show: AC# | Description | Status (IMPLEMENTED/PARTIAL/MISSING) | Evidence (file:line)
|
||||
- Summary: "X of Y acceptance criteria fully implemented"
|
||||
- List any missing or partial ACs with severity
|
||||
5. **Task Completion Validation**:
|
||||
- Include complete task validation checklist from Step 4B
|
||||
- Show: Task | Marked As | Verified As | Evidence (file:line)
|
||||
- **CRITICAL**: Highlight any tasks marked complete but not done in RED/bold
|
||||
- Summary: "X of Y completed tasks verified, Z questionable, W falsely marked complete"
|
||||
6. **Test Coverage and Gaps**:
|
||||
- Which ACs have tests, which don't
|
||||
- Test quality issues found
|
||||
7. **Architectural Alignment**:
|
||||
- Tech-spec compliance
|
||||
- Architecture violations if any
|
||||
8. **Security Notes**: Security findings if any
|
||||
9. **Best-Practices and References**: With links
|
||||
10. **Action Items**:
|
||||
- CRITICAL: ALL action items requiring code changes MUST have checkboxes for tracking
|
||||
- Format for actionable items: `- [ ] [Severity] Description (AC #X) [file: path:line]`
|
||||
- Format for informational notes: `- Note: Description (no action required)`
|
||||
- Imperative phrasing for action items
|
||||
- Map to related ACs or files with specific line references
|
||||
- Include suggested owners if clear
|
||||
- Example format:
|
||||
```
|
||||
### Action Items
|
||||
|
||||
**Code Changes Required:**
|
||||
- [ ] [High] Add input validation on login endpoint (AC #1) [file: src/routes/auth.js:23-45]
|
||||
- [ ] [Med] Add unit test for invalid email format [file: tests/unit/auth.test.js]
|
||||
|
||||
**Advisory Notes:**
|
||||
- Note: Consider adding rate limiting for production deployment
|
||||
- Note: Document the JWT expiration policy in README
|
||||
```
|
||||
</action>
|
||||
|
||||
<critical>The AC validation checklist and task validation checklist MUST be included in the review - this is the evidence trail</critical>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Append review to story and update metadata">
|
||||
<check if="ad_hoc_review_mode == true">
|
||||
<action>Generate review report as a standalone document</action>
|
||||
<action>Save to {{output_folder}}/code-review-{{date}}.md</action>
|
||||
<action>Include sections:
|
||||
- Review Type: Ad-Hoc Code Review
|
||||
- Reviewer: {{user_name}}
|
||||
- Date: {{date}}
|
||||
- Files Reviewed: {{review_files}}
|
||||
- Review Focus: {{review_focus}}
|
||||
- Outcome: (Approve | Changes Requested | Blocked)
|
||||
- Summary
|
||||
- Key Findings
|
||||
- Test Coverage and Gaps
|
||||
- Architectural Alignment
|
||||
- Security Notes
|
||||
- Best-Practices and References (with links)
|
||||
- Action Items
|
||||
</action>
|
||||
<output>Review saved to: {{output_folder}}/code-review-{{date}}.md</output>
|
||||
</check>
|
||||
|
||||
<check if="ad_hoc_review_mode != true">
|
||||
<action>Open {{story_path}} and append a new section at the end titled exactly: "Senior Developer Review (AI)".</action>
|
||||
<action>Insert subsections:
|
||||
- Reviewer: {{user_name}}
|
||||
- Date: {{date}}
|
||||
- Outcome: (Approve | Changes Requested | Blocked) with justification
|
||||
- Summary
|
||||
- Key Findings (by severity - HIGH/MEDIUM/LOW)
|
||||
- **Acceptance Criteria Coverage**:
|
||||
* Include complete AC validation checklist with table format
|
||||
* AC# | Description | Status | Evidence
|
||||
* Summary: X of Y ACs implemented
|
||||
- **Task Completion Validation**:
|
||||
* Include complete task validation checklist with table format
|
||||
* Task | Marked As | Verified As | Evidence
|
||||
* **Highlight falsely marked complete tasks prominently**
|
||||
* Summary: X of Y tasks verified, Z questionable, W false completions
|
||||
- Test Coverage and Gaps
|
||||
- Architectural Alignment
|
||||
- Security Notes
|
||||
- Best-Practices and References (with links)
|
||||
- Action Items:
|
||||
* CRITICAL: Format with checkboxes for tracking resolution
|
||||
* Code changes required: `- [ ] [Severity] Description [file: path:line]`
|
||||
* Advisory notes: `- Note: Description (no action required)`
|
||||
* Group by type: "Code Changes Required" and "Advisory Notes"
|
||||
</action>
|
||||
<action>Add a Change Log entry with date, version bump if applicable, and description: "Senior Developer Review notes appended".</action>
|
||||
<action>If {{update_status_on_result}} is true: update Status to {{status_on_approve}} when approved; to {{status_on_changes_requested}} when changes requested; otherwise leave unchanged.</action>
|
||||
<action>Save the story file.</action>
|
||||
|
||||
<critical>MUST include the complete validation checklists - this is the evidence that systematic review was performed</critical>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Update sprint status based on review outcome" tag="sprint-status">
|
||||
<check if="ad_hoc_review_mode == true">
|
||||
<action>Skip sprint status update (no story context)</action>
|
||||
<output>📋 Ad-hoc review complete - no sprint status to update</output>
|
||||
</check>
|
||||
|
||||
<check if="ad_hoc_review_mode != true">
|
||||
<action>Determine target status based on review outcome:
|
||||
- If {{outcome}} == "Approve" → target_status = "done"
|
||||
- If {{outcome}} == "Changes Requested" → target_status = "in-progress"
|
||||
- If {{outcome}} == "Blocked" → target_status = "review" (stay in review)
|
||||
</action>
|
||||
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read all development_status entries to find {{story_key}}</action>
|
||||
<action>Verify current status is "review" (expected previous state)</action>
|
||||
<action>Update development_status[{{story_key}}] = {{target_status}}</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<check if="update successful">
|
||||
<output>✅ Sprint status updated: review → {{target_status}}</output>
|
||||
</check>
|
||||
|
||||
<check if="story key not found">
|
||||
<output>⚠️ Could not update sprint-status: {{story_key}} not found
|
||||
|
||||
Review was saved to story file, but sprint-status.yaml may be out of sync.
|
||||
</output>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Persist action items to tasks/backlog/epic">
|
||||
<check if="ad_hoc_review_mode == true">
|
||||
<action>All action items are included in the standalone review report</action>
|
||||
<ask if="action items exist">Would you like me to create tracking items for these action items? (backlog/tasks)</ask>
|
||||
<action if="user confirms">
|
||||
If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
|
||||
Append a row per action item with Date={{date}}, Story="Ad-Hoc Review", Epic="N/A", Type, Severity, Owner (or "TBD"), Status="Open", Notes with file refs and context.
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="ad_hoc_review_mode != true">
|
||||
<action>Normalize Action Items into a structured list: description, severity (High/Med/Low), type (Bug/TechDebt/Enhancement), suggested owner (if known), related AC/file references.</action>
|
||||
<ask if="action items exist and 'story_tasks' in {{persist_targets}}">Add {{action_item_count}} follow-up items to story Tasks/Subtasks?</ask>
|
||||
<action if="user confirms or no ask needed">
|
||||
Append under the story's "Tasks / Subtasks" a new subsection titled "Review Follow-ups (AI)", adding each item as an unchecked checkbox in imperative form, prefixed with "[AI-Review]" and severity. Example: "- [ ] [AI-Review][High] Add input validation on server route /api/x (AC #2)".
|
||||
</action>
|
||||
<action if="{{persist_action_items}} == true and 'backlog_file' in {{persist_targets}}">
|
||||
If {{backlog_file}} does not exist, copy {installed_path}/backlog_template.md to {{backlog_file}} location.
|
||||
Append a row per action item with Date={{date}}, Story={{epic_num}}.{{story_num}}, Epic={{epic_num}}, Type, Severity, Owner (or "TBD"), Status="Open", Notes with short context and file refs.
|
||||
</action>
|
||||
<action if="{{persist_action_items}} == true and ('epic_followups' in {{persist_targets}} or {{update_epic_followups}} == true)">
|
||||
If an epic Tech Spec was found: open it and create (if missing) a section titled "{{epic_followups_section_title}}". Append a bullet list of action items scoped to this epic with references back to Story {{epic_num}}.{{story_num}}.
|
||||
</action>
|
||||
<action>Save modified files.</action>
|
||||
<action>Optionally invoke tests or linters to verify quick fixes if any were applied as part of review (requires user approval for any dependency changes).</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Validation and completion">
|
||||
<invoke-task>Run validation checklist at {installed_path}/checklist.md using {project-root}/bmad/core/tasks/validate-workflow.xml</invoke-task>
|
||||
<action>Report workflow completion.</action>
|
||||
|
||||
<check if="ad_hoc_review_mode == true">
|
||||
<output>**✅ Ad-Hoc Code Review Complete, {user_name}!**
|
||||
|
||||
**Review Details:**
|
||||
- Files Reviewed: {{review_files}}
|
||||
- Review Focus: {{review_focus}}
|
||||
- Review Outcome: {{outcome}}
|
||||
- Action Items: {{action_item_count}}
|
||||
- Review Report: {{output_folder}}/code-review-{{date}}.md
|
||||
|
||||
**Next Steps:**
|
||||
1. Review the detailed findings in the review report
|
||||
2. If changes requested: Address action items in the code
|
||||
3. If blocked: Resolve blockers before proceeding
|
||||
4. Re-run review on updated code if needed
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="ad_hoc_review_mode != true">
|
||||
<output>**✅ Story Review Complete, {user_name}!**
|
||||
|
||||
**Story Details:**
|
||||
- Story: {{epic_num}}.{{story_num}}
|
||||
- Story Key: {{story_key}}
|
||||
- Review Outcome: {{outcome}}
|
||||
- Sprint Status: {{target_status}}
|
||||
- Action Items: {{action_item_count}}
|
||||
|
||||
**Next Steps:**
|
||||
1. Review the Senior Developer Review notes appended to story
|
||||
2. If approved: Story is marked done, continue with next story
|
||||
3. If changes requested: Address action items and re-run `dev-story`
|
||||
4. If blocked: Resolve blockers before proceeding
|
||||
</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
````
|
||||
@@ -0,0 +1,74 @@
|
||||
# Review Story Workflow
|
||||
name: code-review
|
||||
description: "Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback. Appends structured review notes to the story."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/code-review"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# This is an action workflow (no output template document)
|
||||
template: false
|
||||
|
||||
# Variables (can be provided by caller)
|
||||
variables:
|
||||
story_path: "" # Optional: Explicit path to story file. If not provided, finds first story with status "review"
|
||||
story_dir: "{config_source}:dev_story_location" # Directory containing story files
|
||||
tech_spec_search_dir: "{project-root}/docs"
|
||||
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
|
||||
arch_docs_search_dirs: |
|
||||
- "{project-root}/docs"
|
||||
- "{output_folder}"
|
||||
arch_docs_file_names: |
|
||||
- architecture.md
|
||||
enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
|
||||
enable_web_fallback: true # Fallback to web search/read-url if MCP not available
|
||||
# Persistence controls for review action items and notes
|
||||
persist_action_items: true
|
||||
# Valid targets: story_tasks, story_review_section, backlog_file, epic_followups
|
||||
persist_targets: |
|
||||
- story_review_section
|
||||
- story_tasks
|
||||
- backlog_file
|
||||
- epic_followups
|
||||
backlog_file: "{project-root}/docs/backlog.md"
|
||||
update_epic_followups: true
|
||||
epic_followups_section_title: "Post-Review Follow-ups"
|
||||
|
||||
# Recommended inputs
|
||||
recommended_inputs:
|
||||
- story: "Path to the story file (auto-discovered if omitted - finds first story with status 'review')"
|
||||
- tech_spec: "Epic technical specification document (auto-discovered)"
|
||||
- story_context_file: "Story context file (.context.xml) (auto-discovered)"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story review
|
||||
input_file_patterns:
|
||||
architecture:
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
|
||||
ux_design:
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded_index: "{output_folder}/*epic*/index.md"
|
||||
sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
standalone: true
|
||||
73
bmad/bmm/workflows/4-implementation/correct-course/README.md
Normal file
73
bmad/bmm/workflows/4-implementation/correct-course/README.md
Normal file
@@ -0,0 +1,73 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Correct Course Workflow
|
||||
|
||||
The correct-course workflow is v6's adaptive response mechanism for stories that encounter issues during development or review, enabling intelligent course correction without restarting from scratch. Run by the Scrum Master (SM) or Team Lead, this workflow analyzes why a story is blocked or has issues, determines whether the story scope needs adjustment, requirements need clarification, technical approach needs revision, or the story needs to be split or reconsidered. This represents the agile principle of embracing change even late in the development cycle, but doing so in a structured way that captures learning and maintains project coherence.
|
||||
|
||||
Unlike simply abandoning failed work or blindly pushing forward, correct-course provides a systematic approach to diagnosing issues and determining appropriate remediation. The workflow examines the original story specification, what was actually implemented, what issues arose during development or review, and the broader epic context to recommend the best path forward. This might involve clarifying requirements, adjusting acceptance criteria, revising technical approach, splitting the story into smaller pieces, or even determining the story should be deprioritized.
|
||||
|
||||
The critical value of this workflow is that it prevents thrashing—endless cycles of implementation and rework without clear direction. By stepping back to analyze what went wrong and charting a clear path forward, the correct-course workflow enables teams to learn from difficulties and adapt intelligently rather than stubbornly proceeding with a flawed approach.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Analyze issues and recommend course correction
|
||||
bmad run correct-course
|
||||
```
|
||||
|
||||
The workflow should be run when:
|
||||
|
||||
- Review identifies critical issues requiring rethinking
|
||||
- Developer encounters blocking issues during implementation
|
||||
- Acceptance criteria prove infeasible or unclear
|
||||
- Technical approach needs significant revision
|
||||
- Story scope needs adjustment based on discoveries
|
||||
|
||||
## Inputs
|
||||
|
||||
**Required Context:**
|
||||
|
||||
- **Story Document**: Original story specification
|
||||
- **Implementation Attempts**: Code changes and approaches tried
|
||||
- **Review Feedback**: Issues and concerns identified
|
||||
- **Epic Context**: Overall epic goals and current progress
|
||||
- **Technical Constraints**: Architecture decisions and limitations discovered
|
||||
|
||||
**Analysis Focus:**
|
||||
|
||||
- Root cause of issues or blockages
|
||||
- Feasibility of current story scope
|
||||
- Clarity of requirements and acceptance criteria
|
||||
- Appropriateness of technical approach
|
||||
- Whether story should be split or revised
|
||||
|
||||
## Outputs
|
||||
|
||||
**Primary Deliverable:**
|
||||
|
||||
- **Course Correction Report** (`[story-id]-correction.md`): Analysis and recommendations including:
|
||||
- Issue root cause analysis
|
||||
- Impact assessment on epic and project
|
||||
- Recommended corrective actions with rationale
|
||||
- Revised story specification if applicable
|
||||
- Updated acceptance criteria if needed
|
||||
- Technical approach adjustments
|
||||
- Timeline and effort implications
|
||||
|
||||
**Possible Outcomes:**
|
||||
|
||||
1. **Clarify Requirements**: Update story with clearer acceptance criteria
|
||||
2. **Revise Scope**: Adjust story scope to be more achievable
|
||||
3. **Split Story**: Break into multiple smaller stories
|
||||
4. **Change Approach**: Recommend different technical approach
|
||||
5. **Deprioritize**: Determine story should be deferred or cancelled
|
||||
6. **Unblock**: Identify and address blocking dependencies
|
||||
|
||||
**Artifacts:**
|
||||
|
||||
- Updated story document if revision needed
|
||||
- New story documents if splitting story
|
||||
- Updated epic backlog reflecting changes
|
||||
- Lessons learned for retrospective
|
||||
279
bmad/bmm/workflows/4-implementation/correct-course/checklist.md
Normal file
279
bmad/bmm/workflows/4-implementation/correct-course/checklist.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Change Navigation Checklist
|
||||
|
||||
<critical>This checklist is executed as part of: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
|
||||
<critical>Work through each section systematically with the user, recording findings and impacts</critical>
|
||||
|
||||
<checklist>
|
||||
|
||||
<section n="1" title="Understand the Trigger and Context">
|
||||
|
||||
<check-item id="1.1">
|
||||
<prompt>Identify the triggering story that revealed this issue</prompt>
|
||||
<action>Document story ID and brief description</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="1.2">
|
||||
<prompt>Define the core problem precisely</prompt>
|
||||
<action>Categorize issue type:</action>
|
||||
- Technical limitation discovered during implementation
|
||||
- New requirement emerged from stakeholders
|
||||
- Misunderstanding of original requirements
|
||||
- Strategic pivot or market change
|
||||
- Failed approach requiring different solution
|
||||
<action>Write clear problem statement</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="1.3">
|
||||
<prompt>Assess initial impact and gather supporting evidence</prompt>
|
||||
<action>Collect concrete examples, error messages, stakeholder feedback, or technical constraints</action>
|
||||
<action>Document evidence for later reference</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<halt-condition>
|
||||
<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
|
||||
<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
|
||||
</halt-condition>
|
||||
|
||||
</section>
|
||||
|
||||
<section n="2" title="Epic Impact Assessment">
|
||||
|
||||
<check-item id="2.1">
|
||||
<prompt>Evaluate current epic containing the trigger story</prompt>
|
||||
<action>Can this epic still be completed as originally planned?</action>
|
||||
<action>If no, what modifications are needed?</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="2.2">
|
||||
<prompt>Determine required epic-level changes</prompt>
|
||||
<action>Check each scenario:</action>
|
||||
- Modify existing epic scope or acceptance criteria
|
||||
- Add new epic to address the issue
|
||||
- Remove or defer epic that's no longer viable
|
||||
- Completely redefine epic based on new understanding
|
||||
<action>Document specific epic changes needed</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="2.3">
|
||||
<prompt>Review all remaining planned epics for required changes</prompt>
|
||||
<action>Check each future epic for impact</action>
|
||||
<action>Identify dependencies that may be affected</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="2.4">
|
||||
<prompt>Check if issue invalidates future epics or necessitates new ones</prompt>
|
||||
<action>Does this change make any planned epics obsolete?</action>
|
||||
<action>Are new epics needed to address gaps created by this change?</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="2.5">
|
||||
<prompt>Consider if epic order or priority should change</prompt>
|
||||
<action>Should epics be resequenced based on this issue?</action>
|
||||
<action>Do priorities need adjustment?</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
</section>
|
||||
|
||||
<section n="3" title="Artifact Conflict and Impact Analysis">
|
||||
|
||||
<check-item id="3.1">
|
||||
<prompt>Check PRD for conflicts</prompt>
|
||||
<action>Does issue conflict with core PRD goals or objectives?</action>
|
||||
<action>Do requirements need modification, addition, or removal?</action>
|
||||
<action>Is the defined MVP still achievable or does scope need adjustment?</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="3.2">
|
||||
<prompt>Review Architecture document for conflicts</prompt>
|
||||
<action>Check each area for impact:</action>
|
||||
- System components and their interactions
|
||||
- Architectural patterns and design decisions
|
||||
- Technology stack choices
|
||||
- Data models and schemas
|
||||
- API designs and contracts
|
||||
- Integration points
|
||||
<action>Document specific architecture sections requiring updates</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="3.3">
|
||||
<prompt>Examine UI/UX specifications for conflicts</prompt>
|
||||
<action>Check for impact on:</action>
|
||||
- User interface components
|
||||
- User flows and journeys
|
||||
- Wireframes or mockups
|
||||
- Interaction patterns
|
||||
- Accessibility considerations
|
||||
<action>Note specific UI/UX sections needing revision</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="3.4">
|
||||
<prompt>Consider impact on other artifacts</prompt>
|
||||
<action>Review additional artifacts for impact:</action>
|
||||
- Deployment scripts
|
||||
- Infrastructure as Code (IaC)
|
||||
- Monitoring and observability setup
|
||||
- Testing strategies
|
||||
- Documentation
|
||||
- CI/CD pipelines
|
||||
<action>Document any secondary artifacts requiring updates</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
</section>
|
||||
|
||||
<section n="4" title="Path Forward Evaluation">
|
||||
|
||||
<check-item id="4.1">
|
||||
<prompt>Evaluate Option 1: Direct Adjustment</prompt>
|
||||
<action>Can the issue be addressed by modifying existing stories?</action>
|
||||
<action>Can new stories be added within the current epic structure?</action>
|
||||
<action>Would this approach maintain project timeline and scope?</action>
|
||||
<action>Effort estimate: [High/Medium/Low]</action>
|
||||
<action>Risk level: [High/Medium/Low]</action>
|
||||
<status>[ ] Viable / [ ] Not viable</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="4.2">
|
||||
<prompt>Evaluate Option 2: Potential Rollback</prompt>
|
||||
<action>Would reverting recently completed stories simplify addressing this issue?</action>
|
||||
<action>Which stories would need to be rolled back?</action>
|
||||
<action>Is the rollback effort justified by the simplification gained?</action>
|
||||
<action>Effort estimate: [High/Medium/Low]</action>
|
||||
<action>Risk level: [High/Medium/Low]</action>
|
||||
<status>[ ] Viable / [ ] Not viable</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="4.3">
|
||||
<prompt>Evaluate Option 3: PRD MVP Review</prompt>
|
||||
<action>Is the original PRD MVP still achievable with this issue?</action>
|
||||
<action>Does MVP scope need to be reduced or redefined?</action>
|
||||
<action>Do core goals need modification based on new constraints?</action>
|
||||
<action>What would be deferred to post-MVP if scope is reduced?</action>
|
||||
<action>Effort estimate: [High/Medium/Low]</action>
|
||||
<action>Risk level: [High/Medium/Low]</action>
|
||||
<status>[ ] Viable / [ ] Not viable</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="4.4">
|
||||
<prompt>Select recommended path forward</prompt>
|
||||
<action>Based on analysis of all options, choose the best path</action>
|
||||
<action>Provide clear rationale considering:</action>
|
||||
- Implementation effort and timeline impact
|
||||
- Technical risk and complexity
|
||||
- Impact on team morale and momentum
|
||||
- Long-term sustainability and maintainability
|
||||
- Stakeholder expectations and business value
|
||||
<action>Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid]</action>
|
||||
<action>Justification: [Document reasoning]</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
</section>
|
||||
|
||||
<section n="5" title="Sprint Change Proposal Components">
|
||||
|
||||
<check-item id="5.1">
|
||||
<prompt>Create identified issue summary</prompt>
|
||||
<action>Write clear, concise problem statement</action>
|
||||
<action>Include context about discovery and impact</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="5.2">
|
||||
<prompt>Document epic impact and artifact adjustment needs</prompt>
|
||||
<action>Summarize findings from Epic Impact Assessment (Section 2)</action>
|
||||
<action>Summarize findings from Artifact Conflict Analysis (Section 3)</action>
|
||||
<action>Be specific about what changes are needed and why</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="5.3">
|
||||
<prompt>Present recommended path forward with rationale</prompt>
|
||||
<action>Include selected approach from Section 4</action>
|
||||
<action>Provide complete justification for recommendation</action>
|
||||
<action>Address trade-offs and alternatives considered</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="5.4">
|
||||
<prompt>Define PRD MVP impact and high-level action plan</prompt>
|
||||
<action>State clearly if MVP is affected</action>
|
||||
<action>Outline major action items needed for implementation</action>
|
||||
<action>Identify dependencies and sequencing</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="5.5">
|
||||
<prompt>Establish agent handoff plan</prompt>
|
||||
<action>Identify which roles/agents will execute the changes:</action>
|
||||
- Development team (for implementation)
|
||||
- Product Owner / Scrum Master (for backlog changes)
|
||||
- Product Manager / Architect (for strategic changes)
|
||||
<action>Define responsibilities for each role</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
</section>
|
||||
|
||||
<section n="6" title="Final Review and Handoff">
|
||||
|
||||
<check-item id="6.1">
|
||||
<prompt>Review checklist completion</prompt>
|
||||
<action>Verify all applicable sections have been addressed</action>
|
||||
<action>Confirm all [Action-needed] items have been documented</action>
|
||||
<action>Ensure analysis is comprehensive and actionable</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="6.2">
|
||||
<prompt>Verify Sprint Change Proposal accuracy</prompt>
|
||||
<action>Review complete proposal for consistency and clarity</action>
|
||||
<action>Ensure all recommendations are well-supported by analysis</action>
|
||||
<action>Check that proposal is actionable and specific</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="6.3">
|
||||
<prompt>Obtain explicit user approval</prompt>
|
||||
<action>Present complete proposal to user</action>
|
||||
<action>Get clear yes/no approval for proceeding</action>
|
||||
<action>Document approval and any conditions</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<check-item id="6.4">
|
||||
<prompt>Confirm next steps and handoff plan</prompt>
|
||||
<action>Review handoff responsibilities with user</action>
|
||||
<action>Ensure all stakeholders understand their roles</action>
|
||||
<action>Confirm timeline and success criteria</action>
|
||||
<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
|
||||
</check-item>
|
||||
|
||||
<halt-condition>
|
||||
<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
|
||||
<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
|
||||
<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
|
||||
</halt-condition>
|
||||
|
||||
</section>
|
||||
|
||||
</checklist>
|
||||
|
||||
<execution-notes>
|
||||
<note>This checklist is for SIGNIFICANT changes affecting project direction</note>
|
||||
<note>Work interactively with user - they make final decisions</note>
|
||||
<note>Be factual, not blame-oriented when analyzing issues</note>
|
||||
<note>Handle changes professionally as opportunities to improve the project</note>
|
||||
<note>Maintain conversation context throughout - this is collaborative work</note>
|
||||
</execution-notes>
|
||||
@@ -0,0 +1,201 @@
|
||||
# Correct Course - Sprint Change Management Instructions
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
|
||||
<critical>DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level ({user_skill_level}) affects conversation style ONLY, not document updates.</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Initialize Change Navigation">
|
||||
<action>Confirm change trigger and gather user description of the issue</action>
|
||||
<action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
|
||||
<action>Verify access to required project documents:</action>
|
||||
- PRD (Product Requirements Document)
|
||||
- Current Epics and Stories
|
||||
- Architecture documentation
|
||||
- UI/UX specifications
|
||||
<action>Ask user for mode preference:</action>
|
||||
- **Incremental** (recommended): Refine each edit collaboratively
|
||||
- **Batch**: Present all changes at once for review
|
||||
<action>Store mode selection for use throughout workflow</action>
|
||||
|
||||
<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
|
||||
|
||||
<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Execute Change Analysis Checklist">
|
||||
<action>Load and execute the systematic analysis from: {checklist}</action>
|
||||
<action>Work through each checklist section interactively with the user</action>
|
||||
<action>Record status for each checklist item:</action>
|
||||
- [x] Done - Item completed successfully
|
||||
- [N/A] Skip - Item not applicable to this change
|
||||
- [!] Action-needed - Item requires attention or follow-up
|
||||
<action>Maintain running notes of findings and impacts discovered</action>
|
||||
<action>Present checklist progress after each major section</action>
|
||||
|
||||
<action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Draft Specific Change Proposals">
|
||||
<action>Based on checklist findings, create explicit edit proposals for each identified artifact</action>
|
||||
|
||||
<action>For Story changes:</action>
|
||||
|
||||
- Show old → new text format
|
||||
- Include story ID and section being modified
|
||||
- Provide rationale for each change
|
||||
- Example format:
|
||||
|
||||
```
|
||||
Story: [STORY-123] User Authentication
|
||||
Section: Acceptance Criteria
|
||||
|
||||
OLD:
|
||||
- User can log in with email/password
|
||||
|
||||
NEW:
|
||||
- User can log in with email/password
|
||||
- User can enable 2FA via authenticator app
|
||||
|
||||
Rationale: Security requirement identified during implementation
|
||||
```
|
||||
|
||||
<action>For PRD modifications:</action>
|
||||
|
||||
- Specify exact sections to update
|
||||
- Show current content and proposed changes
|
||||
- Explain impact on MVP scope and requirements
|
||||
|
||||
<action>For Architecture changes:</action>
|
||||
|
||||
- Identify affected components, patterns, or technology choices
|
||||
- Describe diagram updates needed
|
||||
- Note any ripple effects on other components
|
||||
|
||||
<action>For UI/UX specification updates:</action>
|
||||
|
||||
- Reference specific screens or components
|
||||
- Show wireframe or flow changes needed
|
||||
- Connect changes to user experience impact
|
||||
|
||||
<check if="mode is Incremental">
|
||||
<action>Present each edit proposal individually</action>
|
||||
<ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
|
||||
<action>Iterate on each proposal based on user feedback</action>
|
||||
</check>
|
||||
|
||||
<action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Generate Sprint Change Proposal">
|
||||
<action>Compile comprehensive Sprint Change Proposal document with following sections:</action>
|
||||
|
||||
<action>Section 1: Issue Summary</action>
|
||||
|
||||
- Clear problem statement describing what triggered the change
|
||||
- Context about when/how the issue was discovered
|
||||
- Evidence or examples demonstrating the issue
|
||||
|
||||
<action>Section 2: Impact Analysis</action>
|
||||
|
||||
- Epic Impact: Which epics are affected and how
|
||||
- Story Impact: Current and future stories requiring changes
|
||||
- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates
|
||||
- Technical Impact: Code, infrastructure, or deployment implications
|
||||
|
||||
<action>Section 3: Recommended Approach</action>
|
||||
|
||||
- Present chosen path forward from checklist evaluation:
|
||||
- Direct Adjustment: Modify/add stories within existing plan
|
||||
- Potential Rollback: Revert completed work to simplify resolution
|
||||
- MVP Review: Reduce scope or modify goals
|
||||
- Provide clear rationale for recommendation
|
||||
- Include effort estimate, risk assessment, and timeline impact
|
||||
|
||||
<action>Section 4: Detailed Change Proposals</action>
|
||||
|
||||
- Include all refined edit proposals from Step 3
|
||||
- Group by artifact type (Stories, PRD, Architecture, UI/UX)
|
||||
- Ensure each change includes before/after and justification
|
||||
|
||||
<action>Section 5: Implementation Handoff</action>
|
||||
|
||||
- Categorize change scope:
|
||||
- Minor: Direct implementation by dev team
|
||||
- Moderate: Backlog reorganization needed (PO/SM)
|
||||
- Major: Fundamental replan required (PM/Architect)
|
||||
- Specify handoff recipients and their responsibilities
|
||||
- Define success criteria for implementation
|
||||
|
||||
<action>Present complete Sprint Change Proposal to user</action>
|
||||
<action>Write Sprint Change Proposal document to {default_output_file}</action>
|
||||
<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Finalize and Route for Implementation">
|
||||
<action>Get explicit user approval for complete proposal</action>
|
||||
<ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
|
||||
|
||||
<check if="no or revise">
|
||||
<action>Gather specific feedback on what needs adjustment</action>
|
||||
<action>Return to appropriate step to address concerns</action>
|
||||
<goto step="3">If changes needed to edit proposals</goto>
|
||||
<goto step="4">If changes needed to overall proposal structure</goto>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="yes the proposal is approved by the user">
|
||||
<action>Finalize Sprint Change Proposal document</action>
|
||||
<action>Determine change scope classification:</action>
|
||||
|
||||
- **Minor**: Can be implemented directly by development team
|
||||
- **Moderate**: Requires backlog reorganization and PO/SM coordination
|
||||
- **Major**: Needs fundamental replan with PM/Architect involvement
|
||||
|
||||
<action>Provide appropriate handoff based on scope:</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="Minor scope">
|
||||
<action>Route to: Development team for direct implementation</action>
|
||||
<action>Deliverables: Finalized edit proposals and implementation tasks</action>
|
||||
</check>
|
||||
|
||||
<check if="Moderate scope">
|
||||
<action>Route to: Product Owner / Scrum Master agents</action>
|
||||
<action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
|
||||
</check>
|
||||
|
||||
<check if="Major scope">
|
||||
<action>Route to: Product Manager / Solution Architect</action>
|
||||
<action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
|
||||
|
||||
<action>Confirm handoff completion and next steps with user</action>
|
||||
<action>Document handoff in workflow execution log</action>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Workflow Completion">
|
||||
<action>Summarize workflow execution:</action>
|
||||
- Issue addressed: {{change_trigger}}
|
||||
- Change scope: {{scope_classification}}
|
||||
- Artifacts modified: {{list_of_artifacts}}
|
||||
- Routed to: {{handoff_recipients}}
|
||||
|
||||
<action>Confirm all deliverables produced:</action>
|
||||
|
||||
- Sprint Change Proposal document
|
||||
- Specific edit proposals with before/after
|
||||
- Implementation handoff plan
|
||||
|
||||
<action>Report workflow completion to user with personalized message: "✅ Correct Course workflow complete, {user_name}!"</action>
|
||||
<action>Remind user of success criteria and next steps for implementation team</action>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,43 @@
|
||||
# Correct Course - Sprint Change Management Workflow
|
||||
name: "correct-course"
|
||||
description: "Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation"
|
||||
author: "BMad Method"
|
||||
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
date: system-generated
|
||||
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
|
||||
template: false
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
checklist: "{installed_path}/checklist.md"
|
||||
default_output_file: "{output_folder}/sprint-change-proposal-{date}.md"
|
||||
|
||||
# Workflow execution mode (interactive: step-by-step with user, non-interactive: automated)
|
||||
mode: interactive
|
||||
|
||||
required_inputs:
|
||||
- change_trigger: "Description of the issue or change that triggered this workflow"
|
||||
- project_documents: "Access to PRD, Epics/Stories, Architecture, UI/UX specs"
|
||||
|
||||
output_artifacts:
|
||||
- sprint_change_proposal: "Comprehensive proposal documenting issue, impact, and recommended changes"
|
||||
- artifact_edits: "Specific before/after edits for affected documents"
|
||||
- handoff_plan: "Clear routing for implementation based on change scope"
|
||||
|
||||
halt_conditions:
|
||||
- "Change trigger unclear or undefined"
|
||||
- "Core project documents unavailable"
|
||||
- "Impact analysis incomplete"
|
||||
- "User approval not obtained"
|
||||
|
||||
execution_modes:
|
||||
- incremental: "Recommended - Refine each edit with user collaboration"
|
||||
- batch: "Present all changes at once for review"
|
||||
|
||||
standalone: true
|
||||
146
bmad/bmm/workflows/4-implementation/create-story/README.md
Normal file
146
bmad/bmm/workflows/4-implementation/create-story/README.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 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](#usage)
|
||||
- [Key Features](#key-features)
|
||||
- [Inputs & Outputs](#inputs--outputs)
|
||||
- [Workflow Behavior](#workflow-behavior)
|
||||
- [Integration](#integration)
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
# 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](./instructions.md) and [checklist.md](./checklist.md).
|
||||
240
bmad/bmm/workflows/4-implementation/create-story/checklist.md
Normal file
240
bmad/bmm/workflows/4-implementation/create-story/checklist.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Create Story Quality Validation Checklist
|
||||
|
||||
```xml
|
||||
<critical>This validation runs in a FRESH CONTEXT by an independent validator agent</critical>
|
||||
<critical>The validator audits story quality and offers to improve if issues are found</critical>
|
||||
<critical>Load only the story file and necessary source documents - do NOT load workflow instructions</critical>
|
||||
|
||||
<validation-checklist>
|
||||
|
||||
<expectations>
|
||||
**What create-story workflow should have accomplished:**
|
||||
|
||||
1. **Previous Story Continuity:** If a previous story exists (status: done/review/in-progress), current story should have "Learnings from Previous Story" subsection in Dev Notes that references: new files created, completion notes, architectural decisions, unresolved review items
|
||||
2. **Source Document Coverage:** Story should cite tech spec (if exists), epics, PRD, and relevant architecture docs (architecture.md, testing-strategy.md, coding-standards.md, unified-project-structure.md)
|
||||
3. **Requirements Traceability:** ACs sourced from tech spec (preferred) or epics, not invented
|
||||
4. **Dev Notes Quality:** Specific guidance with citations, not generic advice
|
||||
5. **Task-AC Mapping:** Every AC has tasks, every task references AC, testing subtasks present
|
||||
6. **Structure:** Status="drafted", proper story statement, Dev Agent Record sections initialized
|
||||
</expectations>
|
||||
|
||||
## Validation Steps
|
||||
|
||||
### 1. Load Story and Extract Metadata
|
||||
- [ ] Load story file: {{story_file_path}}
|
||||
- [ ] Parse sections: Status, Story, ACs, Tasks, Dev Notes, Dev Agent Record, Change Log
|
||||
- [ ] Extract: epic_num, story_num, story_key, story_title
|
||||
- [ ] Initialize issue tracker (Critical/Major/Minor)
|
||||
|
||||
### 2. Previous Story Continuity Check
|
||||
|
||||
**Find previous story:**
|
||||
- [ ] Load {output_folder}/sprint-status.yaml
|
||||
- [ ] Find current {{story_key}} in development_status
|
||||
- [ ] Identify story entry immediately above (previous story)
|
||||
- [ ] Check previous story status
|
||||
|
||||
**If previous story status is done/review/in-progress:**
|
||||
- [ ] Load previous story file: {story_dir}/{{previous_story_key}}.md
|
||||
- [ ] Extract: Dev Agent Record (Completion Notes, File List with NEW/MODIFIED)
|
||||
- [ ] Extract: Senior Developer Review section if present
|
||||
- [ ] Count unchecked [ ] items in Review Action Items
|
||||
- [ ] Count unchecked [ ] items in Review Follow-ups (AI)
|
||||
|
||||
**Validate current story captured continuity:**
|
||||
- [ ] Check: "Learnings from Previous Story" subsection exists in Dev Notes
|
||||
- If MISSING and previous story has content → **CRITICAL ISSUE**
|
||||
- [ ] If subsection exists, verify it includes:
|
||||
- [ ] References to NEW files from previous story → If missing → **MAJOR ISSUE**
|
||||
- [ ] Mentions completion notes/warnings → If missing → **MAJOR ISSUE**
|
||||
- [ ] Calls out unresolved review items (if any exist) → If missing → **CRITICAL ISSUE**
|
||||
- [ ] Cites previous story: [Source: stories/{{previous_story_key}}.md]
|
||||
|
||||
**If previous story status is backlog/drafted:**
|
||||
- [ ] No continuity expected (note this)
|
||||
|
||||
**If no previous story exists:**
|
||||
- [ ] First story in epic, no continuity expected
|
||||
|
||||
### 3. Source Document Coverage Check
|
||||
|
||||
**Build available docs list:**
|
||||
- [ ] Check exists: tech-spec-epic-{{epic_num}}*.md in {tech_spec_search_dir}
|
||||
- [ ] Check exists: {output_folder}/epics.md
|
||||
- [ ] Check exists: {output_folder}/PRD.md
|
||||
- [ ] Check exists in {output_folder}/ or {project-root}/docs/:
|
||||
- architecture.md, testing-strategy.md, coding-standards.md
|
||||
- unified-project-structure.md, tech-stack.md
|
||||
- backend-architecture.md, frontend-architecture.md, data-models.md
|
||||
|
||||
**Validate story references available docs:**
|
||||
- [ ] Extract all [Source: ...] citations from story Dev Notes
|
||||
- [ ] Tech spec exists but not cited → **CRITICAL ISSUE**
|
||||
- [ ] Epics exists but not cited → **CRITICAL ISSUE**
|
||||
- [ ] Architecture.md exists → Read for relevance → If relevant but not cited → **MAJOR ISSUE**
|
||||
- [ ] Testing-strategy.md exists → Check Dev Notes mentions testing standards → If not → **MAJOR ISSUE**
|
||||
- [ ] Testing-strategy.md exists → Check Tasks have testing subtasks → If not → **MAJOR ISSUE**
|
||||
- [ ] Coding-standards.md exists → Check Dev Notes references standards → If not → **MAJOR ISSUE**
|
||||
- [ ] Unified-project-structure.md exists → Check Dev Notes has "Project Structure Notes" subsection → If not → **MAJOR ISSUE**
|
||||
|
||||
**Validate citation quality:**
|
||||
- [ ] Verify cited file paths are correct and files exist → Bad citations → **MAJOR ISSUE**
|
||||
- [ ] Check citations include section names, not just file paths → Vague citations → **MINOR ISSUE**
|
||||
|
||||
### 4. Acceptance Criteria Quality Check
|
||||
|
||||
- [ ] Extract Acceptance Criteria from story
|
||||
- [ ] Count ACs: {{ac_count}} (if 0 → **CRITICAL ISSUE** and halt)
|
||||
- [ ] Check story indicates AC source (tech spec, epics, PRD)
|
||||
|
||||
**If tech spec exists:**
|
||||
- [ ] Load tech spec
|
||||
- [ ] Search for this story number
|
||||
- [ ] Extract tech spec ACs for this story
|
||||
- [ ] Compare story ACs vs tech spec ACs → If mismatch → **MAJOR ISSUE**
|
||||
|
||||
**If no tech spec but epics.md exists:**
|
||||
- [ ] Load epics.md
|
||||
- [ ] Search for Epic {{epic_num}}, Story {{story_num}}
|
||||
- [ ] Story not found in epics → **CRITICAL ISSUE** (should have halted)
|
||||
- [ ] Extract epics ACs
|
||||
- [ ] Compare story ACs vs epics ACs → If mismatch without justification → **MAJOR ISSUE**
|
||||
|
||||
**Validate AC quality:**
|
||||
- [ ] Each AC is testable (measurable outcome)
|
||||
- [ ] Each AC is specific (not vague)
|
||||
- [ ] Each AC is atomic (single concern)
|
||||
- [ ] Vague ACs found → **MINOR ISSUE**
|
||||
|
||||
### 5. Task-AC Mapping Check
|
||||
|
||||
- [ ] Extract Tasks/Subtasks from story
|
||||
- [ ] For each AC: Search tasks for "(AC: #{{ac_num}})" reference
|
||||
- [ ] AC has no tasks → **MAJOR ISSUE**
|
||||
- [ ] For each task: Check if references an AC number
|
||||
- [ ] Tasks without AC refs (and not testing/setup) → **MINOR ISSUE**
|
||||
- [ ] Count tasks with testing subtasks
|
||||
- [ ] Testing subtasks < ac_count → **MAJOR ISSUE**
|
||||
|
||||
### 6. Dev Notes Quality Check
|
||||
|
||||
**Check required subsections exist:**
|
||||
- [ ] Architecture patterns and constraints
|
||||
- [ ] References (with citations)
|
||||
- [ ] Project Structure Notes (if unified-project-structure.md exists)
|
||||
- [ ] Learnings from Previous Story (if previous story has content)
|
||||
- [ ] Missing required subsections → **MAJOR ISSUE**
|
||||
|
||||
**Validate content quality:**
|
||||
- [ ] Architecture guidance is specific (not generic "follow architecture docs") → If generic → **MAJOR ISSUE**
|
||||
- [ ] Count citations in References subsection
|
||||
- [ ] No citations → **MAJOR ISSUE**
|
||||
- [ ] < 3 citations and multiple arch docs exist → **MINOR ISSUE**
|
||||
- [ ] Scan for suspicious specifics without citations:
|
||||
- API endpoints, schema details, business rules, tech choices
|
||||
- [ ] Likely invented details found → **MAJOR ISSUE**
|
||||
|
||||
### 7. Story Structure Check
|
||||
|
||||
- [ ] Status = "drafted" → If not → **MAJOR ISSUE**
|
||||
- [ ] Story section has "As a / I want / so that" format → If malformed → **MAJOR ISSUE**
|
||||
- [ ] Dev Agent Record has required sections:
|
||||
- Context Reference, Agent Model Used, Debug Log References, Completion Notes List, File List
|
||||
- [ ] Missing sections → **MAJOR ISSUE**
|
||||
- [ ] Change Log initialized → If missing → **MINOR ISSUE**
|
||||
- [ ] File in correct location: {story_dir}/{{story_key}}.md → If not → **MAJOR ISSUE**
|
||||
|
||||
### 8. Unresolved Review Items Alert
|
||||
|
||||
**CRITICAL CHECK for incomplete review items from previous story:**
|
||||
|
||||
- [ ] If previous story has "Senior Developer Review (AI)" section:
|
||||
- [ ] Count unchecked [ ] items in "Action Items"
|
||||
- [ ] Count unchecked [ ] items in "Review Follow-ups (AI)"
|
||||
- [ ] If unchecked items > 0:
|
||||
- [ ] Check current story "Learnings from Previous Story" mentions these
|
||||
- [ ] If NOT mentioned → **CRITICAL ISSUE** with details:
|
||||
- List all unchecked items with severity
|
||||
- Note: "These may represent epic-wide concerns"
|
||||
- Required: Add to Learnings section with note about pending items
|
||||
|
||||
## Validation Report Generation
|
||||
|
||||
**Calculate severity counts:**
|
||||
- Critical: {{critical_count}}
|
||||
- Major: {{major_count}}
|
||||
- Minor: {{minor_count}}
|
||||
|
||||
**Determine outcome:**
|
||||
- Critical > 0 OR Major > 3 → **FAIL**
|
||||
- Major ≤ 3 and Critical = 0 → **PASS with issues**
|
||||
- All = 0 → **PASS**
|
||||
|
||||
**Generate report:**
|
||||
```
|
||||
|
||||
# Story Quality Validation Report
|
||||
|
||||
Story: {{story_key}} - {{story_title}}
|
||||
Outcome: {{outcome}} (Critical: {{critical_count}}, Major: {{major_count}}, Minor: {{minor_count}})
|
||||
|
||||
## Critical Issues (Blockers)
|
||||
|
||||
{{list_each_with_description_and_evidence}}
|
||||
|
||||
## Major Issues (Should Fix)
|
||||
|
||||
{{list_each_with_description_and_evidence}}
|
||||
|
||||
## Minor Issues (Nice to Have)
|
||||
|
||||
{{list_each_with_description}}
|
||||
|
||||
## Successes
|
||||
|
||||
{{list_what_was_done_well}}
|
||||
|
||||
```
|
||||
|
||||
## User Alert and Remediation
|
||||
|
||||
**If FAIL:**
|
||||
- Show issues summary and top 3 issues
|
||||
- Offer options: (1) Auto-improve story, (2) Show detailed findings, (3) Fix manually, (4) Accept as-is
|
||||
- If option 1: Re-load source docs, regenerate affected sections, re-run validation
|
||||
|
||||
**If PASS with issues:**
|
||||
- Show issues list
|
||||
- Ask: "Improve story? (y/n)"
|
||||
- If yes: Enhance story with missing items
|
||||
|
||||
**If PASS:**
|
||||
- Confirm: All quality standards met
|
||||
- List successes
|
||||
- Ready for story-context generation
|
||||
|
||||
</validation-checklist>
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Validation runs in fresh context and checks:**
|
||||
|
||||
1. ✅ Previous story continuity captured (files, notes, **unresolved review items**)
|
||||
2. ✅ All relevant source docs discovered and cited
|
||||
3. ✅ ACs match tech spec/epics exactly
|
||||
4. ✅ Tasks cover all ACs with testing
|
||||
5. ✅ Dev Notes have specific guidance with citations (not generic)
|
||||
6. ✅ Structure and metadata complete
|
||||
|
||||
**Severity Levels:**
|
||||
|
||||
- **CRITICAL** = Missing previous story reference, missing tech spec cite, unresolved review items not called out, story not in epics
|
||||
- **MAJOR** = Missing arch docs, missing files from previous story, vague Dev Notes, ACs don't match source, no testing subtasks
|
||||
- **MINOR** = Vague citations, orphan tasks, missing Change Log
|
||||
|
||||
**Outcome Triggers:**
|
||||
|
||||
- **FAIL** = Any critical OR >3 major issues
|
||||
- **PASS with issues** = ≤3 major issues, no critical
|
||||
- **PASS** = All checks passed
|
||||
283
bmad/bmm/workflows/4-implementation/create-story/instructions.md
Normal file
283
bmad/bmm/workflows/4-implementation/create-story/instructions.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# Create Story - Workflow Instructions (Spec-compliant, non-interactive by default)
|
||||
|
||||
````xml
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>This workflow creates or updates the next user story from epics/PRD and architecture context, saving to the configured stories directory and optionally invoking Story Context.</critical>
|
||||
<critical>DOCUMENT OUTPUT: Concise, technical, actionable story specifications. Use tables/lists for acceptance criteria and tasks.</critical>
|
||||
|
||||
## 📚 Document Discovery - Selective Epic Loading
|
||||
|
||||
**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
|
||||
|
||||
**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
|
||||
|
||||
1. **Determine which epic** you need (epic_num from story context - e.g., story "3-2-feature-name" needs Epic 3)
|
||||
2. **Check for sharded version**: Look for `epics/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
|
||||
- DO NOT load all epic files - only the one needed!
|
||||
- This is the key efficiency optimization for large multi-epic projects
|
||||
4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
|
||||
|
||||
**Other Documents (prd, architecture, ux-design) - Full Load:**
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat combined content as single document
|
||||
4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Load config and initialize">
|
||||
<action>Resolve variables from config_source: story_dir (dev_story_location), output_folder, user_name, communication_language. If story_dir missing and {{non_interactive}} == false → ASK user to provide a stories directory and update variable. If {{non_interactive}} == true and missing, HALT with a clear message.</action>
|
||||
<action>Create {{story_dir}} if it does not exist</action>
|
||||
<action>Resolve installed component paths from workflow.yaml: template, instructions, validation</action>
|
||||
<action>Resolve recommended inputs if present: epics_file, prd_file, architecture_file</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover and load source documents">
|
||||
<critical>PREVIOUS STORY CONTINUITY: Essential for maintaining context and learning from prior development</critical>
|
||||
|
||||
<action>Find the previous completed story to extract dev agent learnings and review findings:
|
||||
1. Load {{output_folder}}/sprint-status.yaml COMPLETELY
|
||||
2. Find current {{story_key}} in development_status section
|
||||
3. Identify the story entry IMMEDIATELY ABOVE current story (previous row in file order)
|
||||
4. If previous story exists:
|
||||
- Extract {{previous_story_key}}
|
||||
- Check previous story status (done, in-progress, review, etc.)
|
||||
- If status is "done", "review", or "in-progress" (has some completion):
|
||||
* Construct path: {{story_dir}}/{{previous_story_key}}.md
|
||||
* Load the COMPLETE previous story file
|
||||
* Parse ALL sections comprehensively:
|
||||
|
||||
A) Dev Agent Record → Completion Notes List:
|
||||
- New patterns/services created (to reuse, not recreate)
|
||||
- Architectural deviations or decisions made
|
||||
- Technical debt deferred to future stories
|
||||
- Warnings or recommendations for next story
|
||||
- Interfaces/methods created for reuse
|
||||
|
||||
B) Dev Agent Record → Debug Log References:
|
||||
- Issues encountered and solutions
|
||||
- Gotchas or unexpected challenges
|
||||
- Workarounds applied
|
||||
|
||||
C) Dev Agent Record → File List:
|
||||
- Files created (NEW) - understand new capabilities
|
||||
- Files modified (MODIFIED) - track evolving components
|
||||
- Files deleted (DELETED) - removed functionality
|
||||
|
||||
D) Dev Notes:
|
||||
- Any "future story" notes or TODOs
|
||||
- Patterns established
|
||||
- Constraints discovered
|
||||
|
||||
E) Senior Developer Review (AI) section (if present):
|
||||
- Review outcome (Approve/Changes Requested/Blocked)
|
||||
- Unresolved action items (unchecked [ ] items)
|
||||
- Key findings that might affect this story
|
||||
- Architectural concerns raised
|
||||
|
||||
F) Senior Developer Review → Action Items (if present):
|
||||
- Check for unchecked [ ] items still pending
|
||||
- Note any systemic issues that apply to multiple stories
|
||||
|
||||
G) Review Follow-ups (AI) tasks (if present):
|
||||
- Check for unchecked [ ] review tasks still pending
|
||||
- Determine if they're epic-wide concerns
|
||||
|
||||
H) Story Status:
|
||||
- If "review" or "in-progress" - incomplete, note what's pending
|
||||
- If "done" - confirmed complete
|
||||
* Store ALL findings as {{previous_story_learnings}} with structure:
|
||||
- new_files: [list]
|
||||
- modified_files: [list]
|
||||
- new_services: [list with descriptions]
|
||||
- architectural_decisions: [list]
|
||||
- technical_debt: [list]
|
||||
- warnings_for_next: [list]
|
||||
- review_findings: [list if review exists]
|
||||
- pending_items: [list of unchecked action items]
|
||||
- If status is "backlog" or "drafted":
|
||||
* Set {{previous_story_learnings}} = "Previous story not yet implemented"
|
||||
5. If no previous story exists (first story in epic):
|
||||
- Set {{previous_story_learnings}} = "First story in epic - no predecessor context"
|
||||
</action>
|
||||
|
||||
<action>If {{tech_spec_file}} empty: derive from {{tech_spec_glob_template}} with {{epic_num}} and search {{tech_spec_search_dir}} recursively. If multiple, pick most recent by modified time.</action>
|
||||
<action>Build a prioritized document set for this epic:
|
||||
1) tech_spec_file (epic-scoped)
|
||||
2) epics_file (acceptance criteria and breakdown)
|
||||
3) prd_file (business requirements and constraints)
|
||||
4) architecture_file (architecture constraints)
|
||||
5) Architecture docs under docs/ and output_folder/: tech-stack.md, unified-project-structure.md, coding-standards.md, testing-strategy.md, backend-architecture.md, frontend-architecture.md, data-models.md, database-schema.md, rest-api-spec.md, external-apis.md (include if present)
|
||||
</action>
|
||||
<action>READ COMPLETE FILES for all items found in the prioritized set. Store content and paths for citation.</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Find next backlog story to draft" tag="sprint-status">
|
||||
<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
||||
<action>Parse the development_status section completely to understand story order</action>
|
||||
|
||||
<action>Find the FIRST story (by reading in order from top to bottom) where:
|
||||
- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
|
||||
- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
|
||||
- Status value equals "backlog"
|
||||
</action>
|
||||
|
||||
<check if="no backlog story found">
|
||||
<output>📋 No backlog stories found in sprint-status.yaml
|
||||
|
||||
All stories are either already drafted or completed.
|
||||
|
||||
**Options:**
|
||||
1. Run sprint-planning to refresh story tracking
|
||||
2. Load PM agent and run correct-course to add more stories
|
||||
3. Check if current sprint is complete
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<action>Extract from found story key (e.g., "1-2-user-authentication"):
|
||||
- epic_num: first number before dash (e.g., "1")
|
||||
- story_num: second number after first dash (e.g., "2")
|
||||
- story_title: remainder after second dash (e.g., "user-authentication")
|
||||
</action>
|
||||
<action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
|
||||
<action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
|
||||
|
||||
<action>Verify story is enumerated in {{epics_file}}. If not found, HALT with message:</action>
|
||||
<action>"Story {{story_key}} not found in epics.md. Please load PM agent and run correct-course to sync epics, then rerun create-story."</action>
|
||||
|
||||
<action>Check if story file already exists at expected path in {{story_dir}}</action>
|
||||
<check if="story file exists">
|
||||
<output>ℹ️ Story file already exists: {{story_file_path}}
|
||||
|
||||
Will update existing story file rather than creating new one.
|
||||
</output>
|
||||
<action>Set update_mode = true</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Extract requirements and derive story statement">
|
||||
<action>From tech_spec_file (preferred) or epics_file: extract epic {{epic_num}} title/summary, acceptance criteria for the next story, and any component references. If not present, fall back to PRD sections mapping to this epic/story.</action>
|
||||
<action>From architecture and architecture docs: extract constraints, patterns, component boundaries, and testing guidance relevant to the extracted ACs. ONLY capture information that directly informs implementation of this story.</action>
|
||||
<action>Derive a clear user story statement (role, action, benefit) grounded strictly in the above sources. If ambiguous and {{non_interactive}} == false → ASK user to clarify. If {{non_interactive}} == true → generate the best grounded statement WITHOUT inventing domain facts.</action>
|
||||
<template-output file="{default_output_file}">requirements_context_summary</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Project structure alignment and lessons learned">
|
||||
<action>Review {{previous_story_learnings}} and extract actionable intelligence:
|
||||
- New patterns/services created → Note for reuse (DO NOT recreate)
|
||||
- Architectural deviations → Understand and maintain consistency
|
||||
- Technical debt items → Assess if this story should address them
|
||||
- Files modified → Understand current state of evolving components
|
||||
- Warnings/recommendations → Apply to this story's approach
|
||||
- Review findings → Learn from issues found in previous story
|
||||
- Pending action items → Determine if epic-wide concerns affect this story
|
||||
</action>
|
||||
|
||||
<action>If unified-project-structure.md present: align expected file paths, module names, and component locations; note any potential conflicts.</action>
|
||||
|
||||
<action>Cross-reference {{previous_story_learnings}}.new_files with project structure to understand where new capabilities are located.</action>
|
||||
|
||||
<template-output file="{default_output_file}">structure_alignment_summary</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Assemble acceptance criteria and tasks">
|
||||
<action>Assemble acceptance criteria list from tech_spec or epics. If gaps exist, derive minimal, testable criteria from PRD verbatim phrasing (NO invention).</action>
|
||||
<action>Create tasks/subtasks directly mapped to ACs. Include explicit testing subtasks per testing-strategy and existing tests framework. Cite architecture/source documents for any technical mandates.</action>
|
||||
<template-output file="{default_output_file}">acceptance_criteria</template-output>
|
||||
<template-output file="{default_output_file}">tasks_subtasks</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Create or update story document">
|
||||
<action>Resolve output path: {default_output_file} using current {{epic_num}} and {{story_num}}. If targeting an existing story for update, use its path.</action>
|
||||
<action>Initialize from template.md if creating a new file; otherwise load existing file for edit.</action>
|
||||
<action>Compute a concise story_title from epic/story context; if missing, synthesize from PRD feature name and epic number.</action>
|
||||
<template-output file="{default_output_file}">story_header</template-output>
|
||||
<template-output file="{default_output_file}">story_body</template-output>
|
||||
<template-output file="{default_output_file}">dev_notes_with_citations</template-output>
|
||||
|
||||
<action>If {{previous_story_learnings}} contains actionable items (not "First story" or "not yet implemented"):
|
||||
- Add "Learnings from Previous Story" subsection to Dev Notes
|
||||
- Include relevant completion notes, new files/patterns, deviations
|
||||
- Cite previous story file as reference [Source: stories/{{previous_story_key}}.md]
|
||||
- Highlight interfaces/services to REUSE (not recreate)
|
||||
- Note any technical debt to address in this story
|
||||
- List pending review items that affect this story (if any)
|
||||
- Reference specific files created: "Use {{file_path}} for {{purpose}}"
|
||||
- Format example:
|
||||
```
|
||||
### Learnings from Previous Story
|
||||
|
||||
**From Story {{previous_story_key}} (Status: {{previous_status}})**
|
||||
|
||||
- **New Service Created**: `AuthService` base class available at `src/services/AuthService.js` - use `AuthService.register()` method
|
||||
- **Architectural Change**: Switched from session-based to JWT authentication
|
||||
- **Schema Changes**: User model now includes `passwordHash` field, migration applied
|
||||
- **Technical Debt**: Email verification skipped, should be included in this or subsequent story
|
||||
- **Testing Setup**: Auth test suite initialized at `tests/integration/auth.test.js` - follow patterns established there
|
||||
- **Pending Review Items**: Rate limiting mentioned in review - consider for this story
|
||||
|
||||
[Source: stories/{{previous_story_key}}.md#Dev-Agent-Record]
|
||||
```
|
||||
</action>
|
||||
|
||||
<template-output file="{default_output_file}">change_log</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Validate, save, and mark story drafted" tag="sprint-status">
|
||||
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
|
||||
<action>Save document unconditionally (non-interactive default). In interactive mode, allow user confirmation.</action>
|
||||
|
||||
<!-- Mark story as drafted in sprint status -->
|
||||
<action>Update {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Load the FULL file and read all development_status entries</action>
|
||||
<action>Find development_status key matching {{story_key}}</action>
|
||||
<action>Verify current status is "backlog" (expected previous state)</action>
|
||||
<action>Update development_status[{{story_key}}] = "drafted"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<check if="story key not found in file">
|
||||
<output>⚠️ Could not update story status: {{story_key}} not found in sprint-status.yaml
|
||||
|
||||
Story file was created successfully, but sprint-status.yaml was not updated.
|
||||
You may need to run sprint-planning to refresh tracking, or manually set the story row status to `drafted`.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<action>Report created/updated story path</action>
|
||||
<output>**✅ Story Created Successfully, {user_name}!**
|
||||
|
||||
**Story Details:**
|
||||
|
||||
- Story ID: {{story_id}}
|
||||
- Story Key: {{story_key}}
|
||||
- File: {{story_file}}
|
||||
- Status: drafted (was backlog)
|
||||
|
||||
**⚠️ Important:** The following workflows are context-intensive. It's recommended to clear context and restart the SM agent before running the next command.
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Review the drafted story in {{story_file}}
|
||||
2. **[RECOMMENDED]** Run `story-context` to generate technical context XML and mark story ready for development (combines context + ready in one step)
|
||||
3. Or run `story-ready` to manually mark the story ready without generating technical context
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
````
|
||||
51
bmad/bmm/workflows/4-implementation/create-story/template.md
Normal file
51
bmad/bmm/workflows/4-implementation/create-story/template.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Story {{epic_num}}.{{story_num}}: {{story_title}}
|
||||
|
||||
Status: drafted
|
||||
|
||||
## Story
|
||||
|
||||
As a {{role}},
|
||||
I want {{action}},
|
||||
so that {{benefit}}.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. [Add acceptance criteria from epics/PRD]
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [ ] Task 1 (AC: #)
|
||||
- [ ] Subtask 1.1
|
||||
- [ ] Task 2 (AC: #)
|
||||
- [ ] Subtask 2.1
|
||||
|
||||
## Dev Notes
|
||||
|
||||
- Relevant architecture patterns and constraints
|
||||
- Source tree components to touch
|
||||
- Testing standards summary
|
||||
|
||||
### Project Structure Notes
|
||||
|
||||
- Alignment with unified project structure (paths, modules, naming)
|
||||
- Detected conflicts or variances (with rationale)
|
||||
|
||||
### References
|
||||
|
||||
- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Context Reference
|
||||
|
||||
<!-- Path(s) to story context XML will be added here by context workflow -->
|
||||
|
||||
### Agent Model Used
|
||||
|
||||
{{agent_model_name_version}}
|
||||
|
||||
### Debug Log References
|
||||
|
||||
### Completion Notes List
|
||||
|
||||
### File List
|
||||
@@ -0,0 +1,74 @@
|
||||
name: create-story
|
||||
description: "Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/create-story"
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Variables and inputs
|
||||
variables:
|
||||
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
|
||||
epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
|
||||
prd_file: "{output_folder}/PRD.md" # Fallback for requirements
|
||||
architecture_file: "{output_folder}/architecture.md" # Optional architecture context
|
||||
tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
|
||||
tech_spec_search_dir: "{project-root}/docs"
|
||||
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
|
||||
arch_docs_search_dirs: |
|
||||
- "{project-root}/docs"
|
||||
- "{output_folder}"
|
||||
arch_docs_file_names: |
|
||||
- architecture.md
|
||||
- infrastructure-architecture.md
|
||||
story_title: "" # Will be elicited if not derivable
|
||||
epic_num: 1
|
||||
story_num: 1
|
||||
non_interactive: true # Generate without elicitation; avoid interactive prompts
|
||||
|
||||
# Output configuration
|
||||
# Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")
|
||||
default_output_file: "{story_dir}/{{story_key}}.md"
|
||||
|
||||
recommended_inputs:
|
||||
- epics: "Epic breakdown (epics.md)"
|
||||
- prd: "PRD document"
|
||||
- architecture: "Architecture (optional)"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: SELECTIVE LOAD - only load the specific epic needed for this story
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
tech_spec:
|
||||
whole: "{output_folder}/tech-spec.md"
|
||||
|
||||
architecture:
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
|
||||
ux_design:
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded_index: "{output_folder}/*epic*/index.md"
|
||||
sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
standalone: true
|
||||
367
bmad/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md
Normal file
367
bmad/bmm/workflows/4-implementation/dev-story/AUDIT-REPORT.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Workflow Audit Report
|
||||
|
||||
**Workflow:** dev-story
|
||||
**Audit Date:** 2025-10-25
|
||||
**Auditor:** Audit Workflow (BMAD v6)
|
||||
**Workflow Type:** Action Workflow
|
||||
**Module:** BMM (BMad Method)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Overall Status:** GOOD - Minor issues to address
|
||||
|
||||
- Critical Issues: 0
|
||||
- Important Issues: 3
|
||||
- Cleanup Recommendations: 2
|
||||
|
||||
The dev-story workflow is well-structured and follows most BMAD v6 standards. The workflow correctly sets `web_bundle: false` as expected for implementation workflows. However, there are several config variable usage issues and some variables referenced in instructions that are not defined in the YAML.
|
||||
|
||||
---
|
||||
|
||||
## 1. Standard Config Block Validation
|
||||
|
||||
**Status:** PASS ✓
|
||||
|
||||
The workflow.yaml contains all required standard config variables:
|
||||
|
||||
- ✓ `config_source: "{project-root}/bmad/bmm/config.yaml"` - Correctly defined
|
||||
- ✓ `output_folder: "{config_source}:output_folder"` - Pulls from config_source
|
||||
- ✓ `user_name: "{config_source}:user_name"` - Pulls from config_source
|
||||
- ✓ `communication_language: "{config_source}:communication_language"` - Pulls from config_source
|
||||
- ✓ `date: system-generated` - Correctly set
|
||||
|
||||
All standard config variables are present and properly formatted using {project-root} variable syntax.
|
||||
|
||||
---
|
||||
|
||||
## 2. YAML/Instruction/Template Alignment
|
||||
|
||||
**Variables Analyzed:** 9 (excluding standard config)
|
||||
**Used in Instructions:** 6
|
||||
**Unused (Bloat):** 3
|
||||
|
||||
### YAML Variables Defined
|
||||
|
||||
1. `story_dir` - USED in instructions (file paths)
|
||||
2. `context_path` - UNUSED (appears to duplicate story_dir)
|
||||
3. `story_file` - USED in instructions
|
||||
4. `context_file` - USED in instructions
|
||||
5. `installed_path` - USED in instructions (workflow.xml reference)
|
||||
6. `instructions` - USED in instructions (self-reference in critical tag)
|
||||
7. `validation` - USED in instructions (checklist reference)
|
||||
8. `web_bundle` - CONFIGURATION (correctly set to false)
|
||||
9. `date` - USED in instructions (config variable)
|
||||
|
||||
### Variables Used in Instructions But NOT Defined in YAML
|
||||
|
||||
**IMPORTANT ISSUE:** The following variables are referenced in instructions.md but are NOT defined in workflow.yaml:
|
||||
|
||||
1. `{user_skill_level}` - Used 4 times (lines 6, 13, 173, 182)
|
||||
2. `{document_output_language}` - Used 1 time (line 7)
|
||||
3. `{run_until_complete}` - Used 1 time (line 108)
|
||||
4. `{run_tests_command}` - Used 1 time (line 120)
|
||||
|
||||
These variables appear to be pulling from config.yaml but are not explicitly defined in the workflow.yaml file. While the config_source mechanism may provide these, workflow.yaml should document all variables used in the workflow for clarity.
|
||||
|
||||
### Unused Variables (Bloat)
|
||||
|
||||
1. **context_path** - Defined as `"{config_source}:dev_story_location"` but never used. This duplicates `story_dir` functionality.
|
||||
|
||||
---
|
||||
|
||||
## 3. Config Variable Usage
|
||||
|
||||
**Communication Language:** PASS ✓
|
||||
**User Name:** PASS ✓
|
||||
**Output Folder:** PASS ✓
|
||||
**Date:** PASS ✓
|
||||
|
||||
### Detailed Analysis
|
||||
|
||||
**Communication Language:**
|
||||
|
||||
- ✓ Used in line 6: "Communicate all responses in {communication_language}"
|
||||
- ✓ Properly used as agent instruction variable (not in template)
|
||||
|
||||
**User Name:**
|
||||
|
||||
- ✓ Used in line 169: "Communicate to {user_name} that story implementation is complete"
|
||||
- ✓ Appropriately used for personalization
|
||||
|
||||
**Output Folder:**
|
||||
|
||||
- ✓ Used multiple times for sprint-status.yaml file paths
|
||||
- ✓ All file operations target {output_folder} correctly
|
||||
- ✓ No hardcoded paths detected
|
||||
|
||||
**Date:**
|
||||
|
||||
- ✓ Available for agent use (system-generated)
|
||||
- ✓ Used appropriately in context of workflow execution
|
||||
|
||||
### Additional Config Variables
|
||||
|
||||
**IMPORTANT ISSUE:** The workflow uses additional variables that appear to come from config but are not explicitly documented:
|
||||
|
||||
1. `{user_skill_level}` - Used to tailor communication style
|
||||
2. `{document_output_language}` - Used for document generation
|
||||
3. `{run_until_complete}` - Used for execution control
|
||||
4. `{run_tests_command}` - Used for test execution
|
||||
|
||||
These should either be:
|
||||
|
||||
- Added to workflow.yaml with proper config_source references, OR
|
||||
- Documented as optional config variables with defaults
|
||||
|
||||
---
|
||||
|
||||
## 4. Web Bundle Validation
|
||||
|
||||
**Web Bundle Present:** No (Intentional)
|
||||
**Status:** EXPECTED ✓
|
||||
|
||||
The workflow correctly sets `web_bundle: false`. This is the expected configuration for implementation workflows that:
|
||||
|
||||
- Run locally in the development environment
|
||||
- Don't need to be bundled for web deployment
|
||||
- Are IDE-integrated workflows
|
||||
|
||||
**No issues found** - This is the correct configuration for dev-story.
|
||||
|
||||
---
|
||||
|
||||
## 5. Bloat Detection
|
||||
|
||||
**Bloat Percentage:** 11% (1 unused field / 9 total fields)
|
||||
**Cleanup Potential:** Low
|
||||
|
||||
### Unused YAML Fields
|
||||
|
||||
1. **context_path** (line 11 in workflow.yaml)
|
||||
- Defined as: `"{config_source}:dev_story_location"`
|
||||
- Never referenced in instructions.md
|
||||
- Duplicates functionality of `story_dir` variable
|
||||
- **Recommendation:** Remove this variable as `story_dir` serves the same purpose
|
||||
|
||||
### Hardcoded Values
|
||||
|
||||
No significant hardcoded values that should be variables were detected. The workflow properly uses variables for:
|
||||
|
||||
- File paths ({output_folder}, {story_dir})
|
||||
- User personalization ({user_name})
|
||||
- Communication style ({communication_language}, {user_skill_level})
|
||||
|
||||
### Calculation
|
||||
|
||||
- Total yaml fields: 9 (excluding standard config and metadata)
|
||||
- Used fields: 8
|
||||
- Unused fields: 1 (context_path)
|
||||
- Bloat percentage: 11%
|
||||
|
||||
**Status:** Acceptable (under 15% threshold)
|
||||
|
||||
---
|
||||
|
||||
## 6. Template Variable Mapping
|
||||
|
||||
**Not Applicable** - This is an action workflow, not a document workflow.
|
||||
|
||||
No template.md file exists, which is correct for action-type workflows.
|
||||
|
||||
---
|
||||
|
||||
## 7. Instructions Quality Analysis
|
||||
|
||||
### Structure
|
||||
|
||||
- ✓ Steps numbered sequentially (1, 1.5, 2-7)
|
||||
- ✓ Each step has clear goal attributes
|
||||
- ✓ Proper use of XML tags (<action>, <check>, <goto>, <anchor>, <output>)
|
||||
- ✓ Logical flow control with anchors and conditional checks
|
||||
- ✓ Repeat patterns used appropriately (step 2-5 loop)
|
||||
|
||||
### Critical Tags
|
||||
|
||||
- ✓ Critical blocks present and well-defined
|
||||
- ✓ Clear references to workflow execution engine
|
||||
- ✓ Workflow.yaml load requirement specified
|
||||
- ✓ Communication preferences documented
|
||||
|
||||
### Variable Usage Consistency
|
||||
|
||||
**ISSUE:** Inconsistent variable syntax found:
|
||||
|
||||
1. Lines 4, 5 use `{project_root}` (underscore)
|
||||
2. Line 166 uses `{project-root}` (hyphen)
|
||||
|
||||
**Recommendation:** Standardize to `{project-root}` throughout (hyphen is the standard in BMAD v6)
|
||||
|
||||
### Step Quality
|
||||
|
||||
**Excellent:**
|
||||
|
||||
- Steps are focused and single-purpose
|
||||
- Clear HALT conditions defined
|
||||
- Comprehensive validation checks
|
||||
- Good error handling patterns
|
||||
- Iterative execution model well-structured
|
||||
|
||||
**Areas for improvement:**
|
||||
|
||||
- Step 1 is complex and could potentially be split
|
||||
- Some <action if="..."> conditionals could be clearer with <check> blocks
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Critical (Fix Immediately)
|
||||
|
||||
None - No critical issues detected.
|
||||
|
||||
### Important (Address Soon)
|
||||
|
||||
1. **Document or Define Missing Variables**
|
||||
- Add explicit definitions in workflow.yaml for: `user_skill_level`, `document_output_language`, `run_until_complete`, `run_tests_command`
|
||||
- OR document these as optional config variables with defaults
|
||||
- These variables are used in instructions but not defined in YAML
|
||||
- **Impact:** Reduces clarity and may cause confusion about variable sources
|
||||
|
||||
2. **Standardize project-root Variable Syntax**
|
||||
- Change line 4 `{project_root}` to `{project-root}` (hyphen)
|
||||
- Ensure consistency with BMAD v6 standard naming convention
|
||||
- **Impact:** Maintains consistency with framework standards
|
||||
|
||||
3. **Remove or Use context_path Variable**
|
||||
- Variable `context_path` is defined but never used
|
||||
- Since `story_dir` serves the same purpose, remove `context_path`
|
||||
- OR if there's a semantic difference, document why both exist
|
||||
- **Impact:** Reduces bloat and potential confusion
|
||||
|
||||
### Cleanup (Nice to Have)
|
||||
|
||||
1. **Consider Splitting Step 1**
|
||||
- Step 1 handles both story discovery AND file loading
|
||||
- Could be split into "1. Find Story" and "2. Load Story Files"
|
||||
- Would improve clarity and maintainability
|
||||
- **Impact:** Minor improvement to workflow structure
|
||||
|
||||
2. **Add Variable Documentation Comment**
|
||||
- Add a comment block in workflow.yaml listing all variables used by this workflow
|
||||
- Include both explicit YAML variables and config-pulled variables
|
||||
- Example format:
|
||||
```yaml
|
||||
# Workflow-specific variables
|
||||
# - story_file: Path to story markdown
|
||||
# - story_dir: Directory containing stories
|
||||
#
|
||||
# Config-pulled variables (from bmm/config.yaml)
|
||||
# - user_skill_level: User's technical skill level
|
||||
# - document_output_language: Language for generated docs
|
||||
```
|
||||
- **Impact:** Improves developer understanding and maintenance
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
### Structure ✓
|
||||
|
||||
- [x] workflow.yaml loads without YAML syntax errors
|
||||
- [x] instructions.md exists and is properly formatted
|
||||
- [x] No template.md (correct for action workflow)
|
||||
- [x] All critical headers present in instructions
|
||||
- [x] Workflow type correctly identified (action)
|
||||
- [x] All referenced files exist
|
||||
- [x] No placeholder text remains
|
||||
|
||||
### Standard Config Block ✓
|
||||
|
||||
- [x] config_source points to correct module config
|
||||
- [x] output_folder pulls from config_source
|
||||
- [x] user_name pulls from config_source
|
||||
- [x] communication_language pulls from config_source
|
||||
- [x] date is system-generated
|
||||
- [x] Config source uses {project-root} variable
|
||||
- [x] Standard config comment present
|
||||
|
||||
### Config Variable Usage ✓
|
||||
|
||||
- [x] Instructions communicate in {communication_language}
|
||||
- [x] Instructions address {user_name}
|
||||
- [x] All file outputs use {output_folder}
|
||||
- [x] No hardcoded paths
|
||||
- [x] Date available for agent awareness
|
||||
|
||||
### YAML/Instruction/Template Alignment ⚠️
|
||||
|
||||
- [⚠️] Some variables used in instructions not defined in YAML
|
||||
- [x] Template variables N/A (action workflow)
|
||||
- [x] Variable names are descriptive
|
||||
- [⚠️] One unused yaml field (context_path)
|
||||
|
||||
### Web Bundle Validation ✓
|
||||
|
||||
- [x] web_bundle: false is correct for this workflow
|
||||
- [x] No web_bundle section needed
|
||||
- [x] Workflow is local/IDE-integrated only
|
||||
|
||||
### Instructions Quality ✓
|
||||
|
||||
- [x] Steps numbered sequentially
|
||||
- [x] Clear goal attributes
|
||||
- [x] Proper XML tag usage
|
||||
- [x] Logical flow control
|
||||
- [⚠️] Minor inconsistency: {project_root} vs {project-root}
|
||||
|
||||
### Bloat Detection ✓
|
||||
|
||||
- [x] Bloat percentage: 11% (acceptable, under 15%)
|
||||
- [x] No significant hardcoded values
|
||||
- [x] No redundant configuration
|
||||
- [x] One cleanup recommendation (context_path)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Define missing variables** - Add explicit YAML definitions or document as config-pulled variables
|
||||
2. **Standardize variable syntax** - Change `{project_root}` to `{project-root}`
|
||||
3. **Remove context_path** - Clean up unused variable
|
||||
4. **Re-run audit** - Verify improvements after fixes
|
||||
|
||||
---
|
||||
|
||||
## Additional Notes
|
||||
|
||||
### Strengths
|
||||
|
||||
1. **Comprehensive Workflow Logic:** The dev-story workflow is well-thought-out with proper error handling, validation gates, and iterative execution
|
||||
2. **Config Integration:** Excellent use of config variables for user personalization and output management
|
||||
3. **Clear Documentation:** Instructions are detailed with specific HALT conditions and validation checkpoints
|
||||
4. **Proper Web Bundle Setting:** Correctly identifies this as a local-only workflow with web_bundle: false
|
||||
5. **Step Flow:** Excellent use of anchors, goto, and conditional checks for complex flow control
|
||||
|
||||
### Workflow Purpose
|
||||
|
||||
This workflow executes user stories by:
|
||||
|
||||
- Finding ready-for-dev stories from sprint status
|
||||
- Implementing tasks and subtasks incrementally
|
||||
- Writing comprehensive tests
|
||||
- Validating against acceptance criteria
|
||||
- Updating story status through sprint lifecycle
|
||||
- Supporting different user skill levels with adaptive communication
|
||||
|
||||
The workflow is a critical part of the BMM implementation phase and shows mature design patterns.
|
||||
|
||||
---
|
||||
|
||||
**Audit Complete** - Generated by audit-workflow v1.0
|
||||
|
||||
**Pass Rate:** 89% (62 passed / 70 total checks)
|
||||
**Recommendation:** Good - Minor fixes needed
|
||||
|
||||
The dev-story workflow is production-ready with minor improvements recommended. The issues identified are primarily documentation and consistency improvements rather than functional problems.
|
||||
206
bmad/bmm/workflows/4-implementation/dev-story/README.md
Normal file
206
bmad/bmm/workflows/4-implementation/dev-story/README.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Dev Story Workflow
|
||||
|
||||
The dev-story workflow is where v6's just-in-time context approach delivers its primary value, enabling the Developer (DEV) agent to implement stories with expert-level guidance injected directly into their context. This workflow is run EXCLUSIVELY by the DEV agent and operates on a single story that has been prepared by the SM through create-story and enhanced with story-context. The DEV loads both the story specification and the dynamically-generated story context XML, then proceeds through implementation with the combined knowledge of requirements and domain-specific expertise.
|
||||
|
||||
The workflow operates with two critical inputs: the story file (created by SM's create-story) containing acceptance criteria, tasks, and requirements; and the story-context XML (generated by SM's story-context) providing just-in-time expertise injection tailored to the story's technical needs. This dual-input approach ensures the developer has both the "what" (from the story) and the "how" (from the context) needed for successful implementation. The workflow iterates through tasks sequentially, implementing code, writing tests, and updating the story document's allowed sections until all tasks are complete.
|
||||
|
||||
A critical aspect of v6 flow is that dev-story may be run multiple times for the same story. Initially run to implement the story, it may be run again after code-review identifies issues that need correction. The workflow intelligently resumes from incomplete tasks, making it ideal for both initial implementation and post-review fixes. The DEV agent maintains strict boundaries on what can be modified in the story file—only Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, and Status may be updated, preserving the story's requirements integrity.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Developer implements the story with injected context
|
||||
bmad dev *develop
|
||||
|
||||
# Or if returning to fix review issues
|
||||
bmad dev *develop # Will resume from incomplete tasks
|
||||
```
|
||||
|
||||
The DEV runs this workflow:
|
||||
|
||||
- After SM completes both create-story and story-context
|
||||
- When a story status is "Draft" or "Approved" (ready for development)
|
||||
- After code-review identifies issues requiring fixes
|
||||
- To resume work on a partially completed story
|
||||
|
||||
## Inputs
|
||||
|
||||
**Required Files:**
|
||||
|
||||
- **Story Document** (`{story_dir}/story-{epic}.{story}.md`): Complete specification including:
|
||||
- User story statement
|
||||
- Acceptance criteria (immutable during dev)
|
||||
- Tasks and subtasks (checkable during implementation)
|
||||
- Dev Notes section (for context and guidance)
|
||||
- Status field (Draft → In Progress → Ready for Review)
|
||||
|
||||
- **Story Context XML** (`{story_dir}/story-{epic}.{story}-context.xml`): Domain expertise including:
|
||||
- Technical patterns and best practices
|
||||
- Gotchas and common pitfalls
|
||||
- Testing strategies
|
||||
- Relevant code references
|
||||
- Architecture constraints
|
||||
|
||||
**Configuration:**
|
||||
|
||||
- `dev_story_location`: Directory containing story files (from bmm/config.yaml)
|
||||
- `story_selection_limit`: Number of recent stories to show (default: 10)
|
||||
- `run_tests_command`: Test command (default: auto-detected)
|
||||
- `strict`: Whether to halt on test failures (default: true)
|
||||
|
||||
## Outputs
|
||||
|
||||
**Code Implementation:**
|
||||
|
||||
- Production code satisfying acceptance criteria
|
||||
- Unit, integration, and E2E tests as appropriate
|
||||
- Documentation updates
|
||||
- Migration scripts if needed
|
||||
|
||||
**Story File Updates (allowed sections only):**
|
||||
|
||||
- **Tasks/Subtasks**: Checkboxes marked complete as work progresses
|
||||
- **Dev Agent Record**: Debug log and completion notes
|
||||
- **File List**: All files created or modified
|
||||
- **Change Log**: Summary of implementation changes
|
||||
- **Status**: Updated to "Ready for Review" when complete
|
||||
|
||||
**Validation:**
|
||||
|
||||
- All tests passing (existing + new)
|
||||
- Acceptance criteria verified
|
||||
- Code quality checks passed
|
||||
- No regression in existing functionality
|
||||
|
||||
## Key Features
|
||||
|
||||
**Story-Context Integration**: The workflow loads and leverages the story-context XML throughout implementation, providing expert guidance without cluttering the main conversation. This ensures best practices are followed while maintaining developer autonomy.
|
||||
|
||||
**Task-by-Task Iteration**: Implements one task at a time, marking completion before moving to the next. This granular approach enables progress tracking and clean resumption if interrupted or after review feedback.
|
||||
|
||||
**Strict File Boundaries**: Only specific sections of the story file may be modified, preserving requirement integrity. The story's acceptance criteria, main description, and other planning sections remain immutable during development.
|
||||
|
||||
**Test-Driven Approach**: For each task, the workflow emphasizes writing tests that verify acceptance criteria before or alongside implementation, ensuring requirements are actually met.
|
||||
|
||||
**Resumable Implementation**: If the workflow is run again on a story with incomplete tasks (e.g., after code-review finds issues), it intelligently resumes from where it left off rather than starting over.
|
||||
|
||||
## Integration with v6 Flow
|
||||
|
||||
The dev-story workflow is step 3 in the v6 implementation cycle:
|
||||
|
||||
1. SM: create-story (generates the story specification)
|
||||
2. SM: story-context (adds JIT technical expertise)
|
||||
3. **DEV: dev-story** ← You are here (initial implementation)
|
||||
4. DEV/SR: code-review (validates completion)
|
||||
5. If issues found: **DEV: dev-story** ← May return here for fixes
|
||||
6. After epic: retrospective (captures learnings)
|
||||
|
||||
This workflow may be executed multiple times for the same story as part of the review-fix cycle. Each execution picks up from incomplete tasks, making it efficient for iterative improvement.
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Story Selection
|
||||
|
||||
- If `story_path` provided: Use that story directly
|
||||
- Otherwise: List recent stories from `dev_story_location`
|
||||
- Parse story structure and validate format
|
||||
- Load corresponding story-context XML
|
||||
|
||||
### Phase 2: Task Implementation Loop
|
||||
|
||||
For each incomplete task:
|
||||
|
||||
1. **Plan**: Log approach in Dev Agent Record
|
||||
2. **Implement**: Write code following story-context guidance
|
||||
3. **Test**: Create tests verifying acceptance criteria
|
||||
4. **Validate**: Run tests and quality checks
|
||||
5. **Update**: Mark task complete, update File List
|
||||
|
||||
### Phase 3: Completion
|
||||
|
||||
- Verify all tasks completed
|
||||
- Run full test suite
|
||||
- Update Status to "Ready for Review"
|
||||
- Add completion notes to Dev Agent Record
|
||||
|
||||
## Story File Structure
|
||||
|
||||
The workflow expects stories with this structure:
|
||||
|
||||
```markdown
|
||||
# Story {epic}.{story}: {Title}
|
||||
|
||||
**Status**: Draft|In Progress|Ready for Review|Done
|
||||
**Epic**: {epic_number}
|
||||
**Estimated Effort**: {estimate}
|
||||
|
||||
## Story
|
||||
|
||||
As a {role}, I want to {action} so that {benefit}
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] AC1...
|
||||
- [ ] AC2...
|
||||
|
||||
## Tasks and Subtasks
|
||||
|
||||
- [ ] Task 1
|
||||
- [ ] Subtask 1.1
|
||||
- [ ] Task 2
|
||||
|
||||
## Dev Notes
|
||||
|
||||
{Context and guidance from story creation}
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Debug Log
|
||||
|
||||
{Implementation notes added during development}
|
||||
|
||||
### Completion Notes
|
||||
|
||||
{Summary added when complete}
|
||||
|
||||
## File List
|
||||
|
||||
{Files created/modified}
|
||||
|
||||
## Change Log
|
||||
|
||||
{Implementation summary}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Load Context First**: Always ensure the story-context XML is loaded at the start. This provides the expert guidance needed throughout implementation.
|
||||
|
||||
**Follow Task Order**: Implement tasks in the order listed. Dependencies are typically structured in the task sequence.
|
||||
|
||||
**Test Each Task**: Don't wait until the end to write tests. Test each task as you complete it to ensure it meets acceptance criteria.
|
||||
|
||||
**Update Incrementally**: Update the story file after each task completion rather than batching updates at the end.
|
||||
|
||||
**Respect Boundaries**: Never modify acceptance criteria or story description. If they seem wrong, that's a code-review or correct-course issue, not a dev-story fix.
|
||||
|
||||
**Use Context Guidance**: Actively reference the story-context for patterns, gotchas, and best practices. It's there to help you succeed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Story Not Found**: Ensure story exists in `dev_story_location` and follows naming pattern `story-{epic}.{story}.md`
|
||||
|
||||
**Context XML Missing**: The story-context workflow must be run first. Check for `story-{epic}.{story}-context.xml`
|
||||
|
||||
**Tests Failing**: If strict mode is on, the workflow halts. Fix tests before continuing or set strict=false for development iteration.
|
||||
|
||||
**Can't Modify Story Section**: Remember only Tasks, Dev Agent Record, File List, Change Log, and Status can be modified. Other sections are immutable.
|
||||
|
||||
**Resuming After Review**: If code-review found issues, the workflow automatically picks up from incomplete tasks when run again.
|
||||
|
||||
## Related Workflows
|
||||
|
||||
- **create-story**: Creates the story specification (run by SM)
|
||||
- **story-context**: Generates the context XML (run by SM)
|
||||
- **code-review**: Validates implementation (run by SR/DEV)
|
||||
- **correct-course**: Handles major issues or scope changes (run by SM)
|
||||
38
bmad/bmm/workflows/4-implementation/dev-story/checklist.md
Normal file
38
bmad/bmm/workflows/4-implementation/dev-story/checklist.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: 'Dev Story Completion Checklist'
|
||||
validation-target: 'Story markdown ({{story_path}})'
|
||||
required-inputs:
|
||||
- 'Story markdown file with Tasks/Subtasks, Acceptance Criteria'
|
||||
optional-inputs:
|
||||
- 'Test results output (if saved)'
|
||||
- 'CI logs (if applicable)'
|
||||
validation-rules:
|
||||
- 'Only permitted sections in story were modified: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status'
|
||||
---
|
||||
|
||||
# Dev Story Completion Checklist
|
||||
|
||||
## Tasks Completion
|
||||
|
||||
- [ ] All tasks and subtasks for this story are marked complete with [x]
|
||||
- [ ] Implementation aligns with every Acceptance Criterion in the story
|
||||
|
||||
## Tests and Quality
|
||||
|
||||
- [ ] Unit tests added/updated for core functionality changed by this story
|
||||
- [ ] Integration tests added/updated when component interactions are affected
|
||||
- [ ] End-to-end tests created for critical user flows, if applicable
|
||||
- [ ] All tests pass locally (no regressions introduced)
|
||||
- [ ] Linting and static checks (if configured) pass
|
||||
|
||||
## Story File Updates
|
||||
|
||||
- [ ] File List section includes every new/modified/deleted file (paths relative to repo root)
|
||||
- [ ] Dev Agent Record contains relevant Debug Log and/or Completion Notes for this work
|
||||
- [ ] Change Log includes a brief summary of what changed
|
||||
- [ ] Only permitted sections of the story file were modified
|
||||
|
||||
## Final Status
|
||||
|
||||
- [ ] Regression suite executed successfully
|
||||
- [ ] Story Status is set to "Ready for Review"
|
||||
262
bmad/bmm/workflows/4-implementation/dev-story/instructions.md
Normal file
262
bmad/bmm/workflows/4-implementation/dev-story/instructions.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Develop Story - Workflow Instructions
|
||||
|
||||
```xml
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
|
||||
<critical>Generate all documents in {document_output_language}</critical>
|
||||
<critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status</critical>
|
||||
<critical>Execute ALL steps in exact order; do NOT skip steps</critical>
|
||||
<critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.</critical>
|
||||
<critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
|
||||
|
||||
<critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Find next ready story and load it" tag="sprint-status">
|
||||
<check if="{{story_path}} is provided">
|
||||
<action>Use {{story_path}} directly</action>
|
||||
<action>Read COMPLETE story file</action>
|
||||
<action>Extract story_key from filename or metadata</action>
|
||||
<goto>task_check</goto>
|
||||
</check>
|
||||
|
||||
<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read ALL lines from beginning to end - do not skip any content</action>
|
||||
<action>Parse the development_status section completely to understand story order</action>
|
||||
|
||||
<action>Find the FIRST story (by reading in order from top to bottom) where:
|
||||
- Key matches pattern: number-number-name (e.g., "1-2-user-auth")
|
||||
- NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
|
||||
- Status value equals "ready-for-dev"
|
||||
</action>
|
||||
|
||||
<check if="no ready-for-dev or in-progress story found">
|
||||
<output>📋 No ready-for-dev stories found in sprint-status.yaml
|
||||
**Options:**
|
||||
1. Run `story-context` to generate context file and mark drafted stories as ready
|
||||
2. Run `story-ready` to quickly mark drafted stories as ready without generating context
|
||||
3. Run `create-story` if no incomplete stories are drafted yet
|
||||
4. Check {output-folder}/sprint-status.yaml to see current sprint status
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
|
||||
<action>Find matching story file in {{story_dir}} using story_key pattern: {{story_key}}.md</action>
|
||||
<action>Read COMPLETE story file from discovered path</action>
|
||||
|
||||
<anchor id="task_check" />
|
||||
|
||||
<action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
|
||||
|
||||
<action>Check if context file exists at: {{story_dir}}/{{story_key}}.context.xml</action>
|
||||
<check if="context file exists">
|
||||
<action>Read COMPLETE context file</action>
|
||||
<action>Parse all sections: story details, artifacts (docs, code, dependencies), interfaces, constraints, tests</action>
|
||||
<action>Use this context to inform implementation decisions and approaches</action>
|
||||
</check>
|
||||
<check if="context file does NOT exist">
|
||||
<output>ℹ️ No context file found for {{story_key}}
|
||||
|
||||
Proceeding with story file only. For better context, consider running `story-context` workflow first.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
|
||||
|
||||
<action if="no incomplete tasks"><goto step="6">Completion sequence</goto></action>
|
||||
<action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
|
||||
<action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
|
||||
</step>
|
||||
|
||||
<step n="1.5" goal="Detect review continuation and extract review context">
|
||||
<critical>Determine if this is a fresh start or continuation after code review</critical>
|
||||
|
||||
<action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
|
||||
<action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
|
||||
|
||||
<check if="Senior Developer Review section exists">
|
||||
<action>Set review_continuation = true</action>
|
||||
<action>Extract from "Senior Developer Review (AI)" section:
|
||||
- Review outcome (Approve/Changes Requested/Blocked)
|
||||
- Review date
|
||||
- Total action items with checkboxes (count checked vs unchecked)
|
||||
- Severity breakdown (High/Med/Low counts)
|
||||
</action>
|
||||
<action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
|
||||
<action>Store list of unchecked review items as {{pending_review_items}}</action>
|
||||
|
||||
<output>⏯️ **Resuming Story After Code Review** ({{review_date}})
|
||||
|
||||
**Review Outcome:** {{review_outcome}}
|
||||
**Action Items:** {{unchecked_review_count}} remaining to address
|
||||
**Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
|
||||
|
||||
**Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="Senior Developer Review section does NOT exist">
|
||||
<action>Set review_continuation = false</action>
|
||||
<action>Set {{pending_review_items}} = empty</action>
|
||||
|
||||
<output>🚀 **Starting Fresh Implementation**
|
||||
|
||||
Story: {{story_key}}
|
||||
Context file: {{context_available}}
|
||||
First incomplete task: {{first_task_description}}
|
||||
</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="1.6" goal="Mark story in-progress" tag="sprint-status">
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read all development_status entries to find {{story_key}}</action>
|
||||
<action>Get current status value for development_status[{{story_key}}]</action>
|
||||
|
||||
<check if="current status == 'ready-for-dev'">
|
||||
<action>Update the story in the sprint status report to = "in-progress"</action>
|
||||
<output>🚀 Starting work on story {{story_key}}
|
||||
Status updated: ready-for-dev → in-progress
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="current status == 'in-progress'">
|
||||
<output>⏯️ Resuming work on story {{story_key}}
|
||||
Story is already marked in-progress
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="current status is neither ready-for-dev nor in-progress">
|
||||
<output>⚠️ Unexpected story status: {{current_status}}
|
||||
Expected ready-for-dev or in-progress. Continuing anyway...
|
||||
</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Plan and implement task">
|
||||
<action>Review acceptance criteria and dev notes for the selected task</action>
|
||||
<action>Plan implementation steps and edge cases; write down a brief plan in Dev Agent Record → Debug Log</action>
|
||||
<action>Implement the task COMPLETELY including all subtasks, critically following best practices, coding patterns and coding standards in this repo you have learned about from the story and context file or your own critical agent instructions</action>
|
||||
<action>Handle error conditions and edge cases appropriately</action>
|
||||
<action if="new or different than what is documented dependencies are needed">ASK user for approval before adding</action>
|
||||
<action if="3 consecutive implementation failures occur">HALT and request guidance</action>
|
||||
<action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
|
||||
<critical>Do not stop after partial progress; continue iterating tasks until all ACs are satisfied and tested or a HALT condition triggers</critical>
|
||||
<critical>Do NOT propose to pause for review, stand-ups, or validation until Step 6 gates are satisfied</critical>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Author comprehensive tests">
|
||||
<action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
|
||||
<action>Add integration tests for component interactions where desired by test plan or story notes</action>
|
||||
<action>Include end-to-end tests for critical user flows where desired by test plan or story notes</action>
|
||||
<action>Cover edge cases and error handling scenarios noted in the test plan or story notes</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Run validations and tests">
|
||||
<action>Determine how to run tests for this repo (infer or use {{run_tests_command}} if provided)</action>
|
||||
<action>Run all existing tests to ensure no regressions</action>
|
||||
<action>Run the new tests to verify implementation correctness</action>
|
||||
<action>Run linting and code quality checks if configured</action>
|
||||
<action>Validate implementation meets ALL story acceptance criteria; if ACs include quantitative thresholds (e.g., test pass rate), ensure they are met before marking complete</action>
|
||||
<action if="regression tests fail">STOP and fix before continuing, consider how current changes made broke regression</action>
|
||||
<action if="new tests fail">STOP and fix before continuing</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Mark task complete, track review resolutions, and update story">
|
||||
<critical>If task is a review follow-up, must mark BOTH the task checkbox AND the corresponding action item in the review section</critical>
|
||||
|
||||
<action>Check if completed task has [AI-Review] prefix (indicates review follow-up task)</action>
|
||||
|
||||
<check if="task is review follow-up">
|
||||
<action>Extract review item details (severity, description, related AC/file)</action>
|
||||
<action>Add to resolution tracking list: {{resolved_review_items}}</action>
|
||||
|
||||
<!-- Mark task in Review Follow-ups section -->
|
||||
<action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
|
||||
|
||||
<!-- CRITICAL: Also mark corresponding action item in review section -->
|
||||
<action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
|
||||
<action>Mark that action item checkbox [x] as resolved</action>
|
||||
|
||||
<action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
|
||||
</check>
|
||||
|
||||
<action>ONLY mark the task (and subtasks) checkbox with [x] if ALL tests pass and validation succeeds</action>
|
||||
<action>Update File List section with any new, modified, or deleted files (paths relative to repo root)</action>
|
||||
<action>Add completion notes to Dev Agent Record if significant changes were made (summarize intent, approach, and any follow-ups)</action>
|
||||
|
||||
<check if="review_continuation == true and {{resolved_review_items}} is not empty">
|
||||
<action>Count total resolved review items in this session</action>
|
||||
<action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
|
||||
</check>
|
||||
|
||||
<action>Save the story file</action>
|
||||
<action>Determine if more incomplete tasks remain</action>
|
||||
<action if="more tasks remain"><goto step="2">Next task</goto></action>
|
||||
<action if="no tasks remain"><goto step="6">Completion</goto></action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Story completion and mark for review" tag="sprint-status">
|
||||
<action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
|
||||
<action>Run the full regression suite (do not skip)</action>
|
||||
<action>Confirm File List includes every changed file</action>
|
||||
<action>Execute story definition-of-done checklist, if the story includes one</action>
|
||||
<action>Update the story Status to: review</action>
|
||||
|
||||
<!-- Mark story ready for review -->
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Find development_status key matching {{story_key}}</action>
|
||||
<action>Verify current status is "in-progress" (expected previous state)</action>
|
||||
<action>Update development_status[{{story_key}}] = "review"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<check if="story key not found in file">
|
||||
<output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
|
||||
|
||||
Story is marked Ready for Review in file, but sprint-status.yaml may be out of sync.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<action if="any task is incomplete">Return to step 1 to complete remaining work (Do NOT finish with partial progress)</action>
|
||||
<action if="regression failures exist">STOP and resolve before completing</action>
|
||||
<action if="File List is incomplete">Update it before completing</action>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Completion communication and user support">
|
||||
<action>Optionally run the workflow validation task against the story using {project-root}/bmad/core/tasks/validate-workflow.xml</action>
|
||||
<action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
|
||||
|
||||
<action>Communicate to {user_name} that story implementation is complete and ready for review</action>
|
||||
<action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
|
||||
<action>Provide the story file path and current status (now "review", was "in-progress")</action>
|
||||
|
||||
<action>Based on {user_skill_level}, ask if user needs any explanations about:
|
||||
- What was implemented and how it works
|
||||
- Why certain technical decisions were made
|
||||
- How to test or verify the changes
|
||||
- Any patterns, libraries, or approaches used
|
||||
- Anything else they'd like clarified
|
||||
</action>
|
||||
|
||||
<check if="user asks for explanations">
|
||||
<action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
|
||||
<action>Use examples and references to specific code when helpful</action>
|
||||
</check>
|
||||
|
||||
<action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
|
||||
<action>Common next steps to suggest (but allow user flexibility):
|
||||
- Review the implemented story yourself and test the changes
|
||||
- Verify all acceptance criteria are met
|
||||
- Ensure deployment readiness if applicable
|
||||
- Run `code-review` workflow for peer review
|
||||
- Check sprint-status.yaml to see project progress
|
||||
</action>
|
||||
<action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
26
bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml
Normal file
26
bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml
Normal file
@@ -0,0 +1,26 @@
|
||||
name: dev-story
|
||||
description: "Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
story_dir: "{config_source}:dev_story_location"
|
||||
run_until_complete: "{config_source}:run_until_complete"
|
||||
run_tests_command: "{config_source}:run_tests_command"
|
||||
date: system-generated
|
||||
|
||||
story_file: "" # Explicit story path; auto-discovered if empty
|
||||
# Context file uses same story_key as story file (e.g., "1-2-user-authentication.context.xml")
|
||||
context_file: "{story_dir}/{{story_key}}.context.xml"
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
standalone: true
|
||||
195
bmad/bmm/workflows/4-implementation/epic-tech-context/README.md
Normal file
195
bmad/bmm/workflows/4-implementation/epic-tech-context/README.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Technical Specification Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Generate a comprehensive Technical Specification for a single epic from PRD, Epics file and Architecture to produce a document with full acceptance criteria and traceability mapping. Creates detailed implementation guidance that bridges business requirements with technical execution.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **PRD-Architecture Integration** - Synthesizes business requirements with technical constraints
|
||||
- **Traceability Mapping** - Links acceptance criteria to technical components and tests
|
||||
- **Multi-Input Support** - Leverages PRD, architecture, front-end specs, and brownfield notes
|
||||
- **Implementation Focus** - Provides concrete technical guidance for development teams
|
||||
- **Testing Integration** - Includes test strategy aligned with acceptance criteria
|
||||
- **Validation Ready** - Generates specifications suitable for architectural review
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow tech-spec
|
||||
```
|
||||
|
||||
### With Input Documents
|
||||
|
||||
```bash
|
||||
# With specific PRD and architecture
|
||||
workflow tech-spec --input PRD.md --input architecture.md
|
||||
|
||||
# With comprehensive inputs
|
||||
workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec.md
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **output_folder**: Location for generated technical specification
|
||||
- **epic_id**: Used in output filename (extracted from PRD or prompted)
|
||||
- **recommended_inputs**: PRD, architecture, front-end spec, brownfield notes
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
tech-spec/
|
||||
├── workflow.yaml # Configuration and metadata
|
||||
├── instructions.md # Step-by-step execution guide
|
||||
├── template.md # Technical specification structure
|
||||
├── checklist.md # Validation criteria
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Input Collection and Analysis (Steps 1-2)
|
||||
|
||||
- **Document Discovery**: Locates PRD and Architecture documents
|
||||
- **Epic Extraction**: Identifies epic title and ID from PRD content
|
||||
- **Template Initialization**: Creates tech-spec document from template
|
||||
- **Context Analysis**: Reviews complete PRD and architecture for alignment
|
||||
|
||||
### Phase 2: Technical Design Specification (Step 3)
|
||||
|
||||
- **Service Architecture**: Defines services/modules with responsibilities and interfaces
|
||||
- **Data Modeling**: Specifies entities, schemas, and relationships
|
||||
- **API Design**: Documents endpoints, request/response models, and error handling
|
||||
- **Workflow Definition**: Details sequence flows and data processing patterns
|
||||
|
||||
### Phase 3: Non-Functional Requirements (Step 4)
|
||||
|
||||
- **Performance Specs**: Defines measurable latency, throughput, and scalability targets
|
||||
- **Security Requirements**: Specifies authentication, authorization, and data protection
|
||||
- **Reliability Standards**: Documents availability, recovery, and degradation behavior
|
||||
- **Observability Framework**: Defines logging, metrics, and tracing requirements
|
||||
|
||||
### Phase 4: Dependencies and Integration (Step 5)
|
||||
|
||||
- **Dependency Analysis**: Scans repository for package manifests and frameworks
|
||||
- **Integration Mapping**: Identifies external systems and API dependencies
|
||||
- **Version Management**: Documents version constraints and compatibility requirements
|
||||
- **Infrastructure Needs**: Specifies deployment and runtime dependencies
|
||||
|
||||
### Phase 5: Acceptance and Testing (Step 6)
|
||||
|
||||
- **Criteria Normalization**: Extracts and refines acceptance criteria from PRD
|
||||
- **Traceability Matrix**: Maps acceptance criteria to technical components
|
||||
- **Test Strategy**: Defines testing approach for each acceptance criterion
|
||||
- **Component Mapping**: Links requirements to specific APIs and modules
|
||||
|
||||
### Phase 6: Risk and Validation (Steps 7-8)
|
||||
|
||||
- **Risk Assessment**: Identifies technical risks, assumptions, and open questions
|
||||
- **Mitigation Planning**: Provides strategies for addressing identified risks
|
||||
- **Quality Validation**: Ensures specification meets completeness criteria
|
||||
- **Checklist Verification**: Validates against workflow quality standards
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: tech-spec-{epic_id}-{date}.md
|
||||
- **Traceability data**: Embedded mapping tables linking requirements to implementation
|
||||
|
||||
### Output Structure
|
||||
|
||||
1. **Overview and Scope** - Project context and boundaries
|
||||
2. **System Architecture Alignment** - Connection to architecture
|
||||
3. **Detailed Design** - Services, data models, APIs, and workflows
|
||||
4. **Non-Functional Requirements** - Performance, security, reliability, observability
|
||||
5. **Dependencies and Integrations** - External systems and technical dependencies
|
||||
6. **Acceptance Criteria** - Testable requirements from PRD
|
||||
7. **Traceability Mapping** - Requirements-to-implementation mapping
|
||||
8. **Test Strategy** - Testing approach and framework alignment
|
||||
9. **Risks and Assumptions** - Technical risks and mitigation strategies
|
||||
|
||||
## Requirements
|
||||
|
||||
- **PRD Document**: Product Requirements Document with clear acceptance criteria
|
||||
- **Architecture Document**: architecture or technical design
|
||||
- **Repository Access**: For dependency analysis and framework detection
|
||||
- **Epic Context**: Clear epic identification and scope definition
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Validate Inputs**: Ensure PRD and architecture documents are complete and current
|
||||
2. **Review Requirements**: Confirm acceptance criteria are specific and testable
|
||||
3. **Check Dependencies**: Verify repository structure supports automated dependency analysis
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Maintain Traceability**: Ensure every acceptance criterion maps to implementation
|
||||
2. **Be Implementation-Specific**: Provide concrete technical guidance, not high-level concepts
|
||||
3. **Consider Constraints**: Factor in existing system limitations and brownfield challenges
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Architect Review**: Have technical lead validate design decisions
|
||||
2. **Developer Walkthrough**: Ensure implementation team understands specifications
|
||||
3. **Test Planning**: Use traceability matrix for test case development
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Missing or incomplete technical details
|
||||
|
||||
- **Solution**: Review architecture document for implementation specifics
|
||||
- **Check**: Ensure PRD contains sufficient functional requirements detail
|
||||
|
||||
**Issue**: Acceptance criteria don't map cleanly to technical components
|
||||
|
||||
- **Solution**: Break down complex criteria into atomic, testable statements
|
||||
- **Check**: Verify PRD acceptance criteria are properly structured
|
||||
|
||||
**Issue**: Dependency analysis fails or is incomplete
|
||||
|
||||
- **Solution**: Check repository structure and manifest file locations
|
||||
- **Check**: Verify repository contains standard dependency files (package.json, etc.)
|
||||
|
||||
**Issue**: Non-functional requirements are too vague
|
||||
|
||||
- **Solution**: Extract specific performance and quality targets from architecture
|
||||
- **Check**: Ensure architecture document contains measurable NFR specifications
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Template**: Update template.md to match organizational technical spec standards
|
||||
2. **Extend Dependencies**: Add support for additional package managers or frameworks
|
||||
3. **Enhance Validation**: Extend checklist.md with company-specific technical criteria
|
||||
4. **Add Sections**: Include additional technical concerns like DevOps or monitoring
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - Comprehensive technical specification with traceability
|
||||
- PRD-Architecture integration
|
||||
- Automated dependency detection
|
||||
- Traceability mapping
|
||||
- Test strategy alignment
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Ensure PRD and architecture documents are complete before starting
|
||||
- Consult BMAD documentation for technical specification standards
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
@@ -0,0 +1,17 @@
|
||||
# Tech Spec Validation Checklist
|
||||
|
||||
```xml
|
||||
<checklist id="bmad/bmm/workflows/4-implementation/epic-tech-context/checklist">
|
||||
<item>Overview clearly ties to PRD goals</item>
|
||||
<item>Scope explicitly lists in-scope and out-of-scope</item>
|
||||
<item>Design lists all services/modules with responsibilities</item>
|
||||
<item>Data models include entities, fields, and relationships</item>
|
||||
<item>APIs/interfaces are specified with methods and schemas</item>
|
||||
<item>NFRs: performance, security, reliability, observability addressed</item>
|
||||
<item>Dependencies/integrations enumerated with versions where known</item>
|
||||
<item>Acceptance criteria are atomic and testable</item>
|
||||
<item>Traceability maps AC → Spec → Components → Tests</item>
|
||||
<item>Risks/assumptions/questions listed with mitigation/next steps</item>
|
||||
<item>Test strategy covers all ACs and critical paths</item>
|
||||
</checklist>
|
||||
```
|
||||
@@ -0,0 +1,189 @@
|
||||
<!-- BMAD BMM Tech Spec Workflow Instructions (v6) -->
|
||||
|
||||
```xml
|
||||
<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
|
||||
<critical>Communicate all responses in {communication_language}</critical>
|
||||
<critical>This workflow generates a comprehensive Technical Specification from PRD and Architecture, including detailed design, NFRs, acceptance criteria, and traceability mapping.</critical>
|
||||
<critical>If required inputs cannot be auto-discovered HALT with a clear message listing missing documents, allow user to provide them to proceed.</critical>
|
||||
|
||||
## 📚 Document Discovery - Selective Epic Loading
|
||||
|
||||
**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
|
||||
|
||||
**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
|
||||
|
||||
1. **Determine which epic** you need (epic_num from workflow context or user input)
|
||||
2. **Check for sharded version**: Look for `epics/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
|
||||
- DO NOT load all epic files - only the one needed!
|
||||
- This is the key efficiency optimization for large multi-epic projects
|
||||
4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
|
||||
|
||||
**Other Documents (prd, gdd, architecture, ux-design) - Full Load:**
|
||||
|
||||
1. **Search for whole document first** - Use fuzzy file matching
|
||||
2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand structure
|
||||
- Read ALL section files listed in the index
|
||||
- Treat combined content as single document
|
||||
4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
|
||||
|
||||
**Priority**: If both whole and sharded versions exist, use the whole document.
|
||||
|
||||
**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused epics and stories.
|
||||
|
||||
<workflow>
|
||||
<step n="1" goal="Collect inputs and discover next epic" tag="sprint-status">
|
||||
<action>Identify PRD and Architecture documents from recommended_inputs. Attempt to auto-discover at default paths.</action>
|
||||
<ask if="inputs are missing">ask the user for file paths. HALT and wait for docs to proceed</ask>
|
||||
|
||||
<!-- Intelligent Epic Discovery -->
|
||||
<critical>MUST read COMPLETE sprint-status.yaml file to discover next epic</critical>
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Read ALL development_status entries</action>
|
||||
<action>Find all epics with status "backlog" (not yet contexted)</action>
|
||||
<action>Identify the FIRST backlog epic as the suggested default</action>
|
||||
|
||||
<check if="backlog epics found">
|
||||
<output>📋 **Next Epic Suggested:** Epic {{suggested_epic_id}}: {{suggested_epic_title}}</output>
|
||||
<ask>Use this epic?
|
||||
- [y] Yes, use {{suggested_epic_id}}
|
||||
- [n] No, let me specify a different epic_id
|
||||
</ask>
|
||||
|
||||
<check if="user selects 'n'">
|
||||
<ask>Enter the epic_id you want to context</ask>
|
||||
<action>Store user-provided epic_id as {{epic_id}}</action>
|
||||
</check>
|
||||
|
||||
<check if="user selects 'y'">
|
||||
<action>Use {{suggested_epic_id}} as {{epic_id}}</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="no backlog epics found">
|
||||
<output>✅ All epics are already contexted!
|
||||
|
||||
No epics with status "backlog" found in sprint-status.yaml.
|
||||
</output>
|
||||
<ask>Do you want to re-context an existing epic? Enter epic_id or [q] to quit:</ask>
|
||||
|
||||
<check if="user enters epic_id">
|
||||
<action>Store as {{epic_id}}</action>
|
||||
</check>
|
||||
|
||||
<check if="user enters 'q'">
|
||||
<action>HALT - No work needed</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Extract {{epic_title}} from PRD based on {{epic_id}}.</action>
|
||||
<action>Resolve output file path using workflow variables and initialize by writing the template.</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Validate epic exists in sprint status" tag="sprint-status">
|
||||
<action>Look for epic key "epic-{{epic_id}}" in development_status (already loaded from step 1)</action>
|
||||
<action>Get current status value if epic exists</action>
|
||||
|
||||
<check if="epic not found">
|
||||
<output>⚠️ Epic {{epic_id}} not found in sprint-status.yaml
|
||||
|
||||
This epic hasn't been registered in the sprint plan yet.
|
||||
Run sprint-planning workflow to initialize epic tracking.
|
||||
</output>
|
||||
<action>HALT</action>
|
||||
</check>
|
||||
|
||||
<check if="epic status == 'contexted'">
|
||||
<output>ℹ️ Epic {{epic_id}} already marked as contexted
|
||||
|
||||
Continuing to regenerate tech spec...
|
||||
</output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Overview and scope">
|
||||
<action>Read COMPLETE found {recommended_inputs}.</action>
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{overview}} with a concise 1-2 paragraph summary referencing PRD context and goals
|
||||
Replace {{objectives_scope}} with explicit in-scope and out-of-scope bullets
|
||||
Replace {{system_arch_alignment}} with a short alignment summary to the architecture (components referenced, constraints)
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Detailed design">
|
||||
<action>Derive concrete implementation specifics from all {recommended_inputs} (CRITICAL: NO invention). If a epic tech spec precedes this one and exists, maintain consistency where appropriate.</action>
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{services_modules}} with a table or bullets listing services/modules with responsibilities, inputs/outputs, and owners
|
||||
Replace {{data_models}} with normalized data model definitions (entities, fields, types, relationships); include schema snippets where available
|
||||
Replace {{apis_interfaces}} with API endpoint specs or interface signatures (method, path, request/response models, error codes)
|
||||
Replace {{workflows_sequencing}} with sequence notes or diagrams-as-text (steps, actors, data flow)
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Non-functional requirements">
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{nfr_performance}} with measurable targets (latency, throughput); link to any performance requirements in PRD/Architecture
|
||||
Replace {{nfr_security}} with authn/z requirements, data handling, threat notes; cite source sections
|
||||
Replace {{nfr_reliability}} with availability, recovery, and degradation behavior
|
||||
Replace {{nfr_observability}} with logging, metrics, tracing requirements; name required signals
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Dependencies and integrations">
|
||||
<action>Scan repository for dependency manifests (e.g., package.json, pyproject.toml, go.mod, Unity Packages/manifest.json).</action>
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{dependencies_integrations}} with a structured list of dependencies and integration points with version or commit constraints when known
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Acceptance criteria and traceability">
|
||||
<action>Extract acceptance criteria from PRD; normalize into atomic, testable statements.</action>
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{acceptance_criteria}} with a numbered list of testable acceptance criteria
|
||||
Replace {{traceability_mapping}} with a table mapping: AC → Spec Section(s) → Component(s)/API(s) → Test Idea
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Risks and test strategy">
|
||||
<template-output file="{default_output_file}">
|
||||
Replace {{risks_assumptions_questions}} with explicit list (each item labeled as Risk/Assumption/Question) with mitigation or next step
|
||||
Replace {{test_strategy}} with a brief plan (test levels, frameworks, coverage of ACs, edge cases)
|
||||
</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Validate and mark epic contexted" tag="sprint-status">
|
||||
<invoke-task>Validate against checklist at {installed_path}/checklist.md using bmad/core/tasks/validate-workflow.xml</invoke-task>
|
||||
|
||||
<!-- Mark epic as contexted -->
|
||||
<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
|
||||
<action>Find development_status key "epic-{{epic_id}}"</action>
|
||||
<action>Verify current status is "backlog" (expected previous state)</action>
|
||||
<action>Update development_status["epic-{{epic_id}}"] = "contexted"</action>
|
||||
<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
|
||||
|
||||
<check if="epic key not found in file">
|
||||
<output>⚠️ Could not update epic status: epic-{{epic_id}} not found</output>
|
||||
</check>
|
||||
|
||||
<output>**✅ Tech Spec Generated Successfully, {user_name}!**
|
||||
|
||||
**Epic Details:**
|
||||
- Epic ID: {{epic_id}}
|
||||
- Epic Title: {{epic_title}}
|
||||
- Tech Spec File: {{default_output_file}}
|
||||
- Epic Status: contexted (was backlog)
|
||||
|
||||
**Note:** This is a JIT (Just-In-Time) workflow - run again for other epics as needed.
|
||||
|
||||
**Next Steps:**
|
||||
1. Load SM agent and run `create-story` to begin implementing the first story under this epic.
|
||||
</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
```
|
||||
@@ -0,0 +1,76 @@
|
||||
# Epic Technical Specification: {{epic_title}}
|
||||
|
||||
Date: {{date}}
|
||||
Author: {{user_name}}
|
||||
Epic ID: {{epic_id}}
|
||||
Status: Draft
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
{{overview}}
|
||||
|
||||
## Objectives and Scope
|
||||
|
||||
{{objectives_scope}}
|
||||
|
||||
## System Architecture Alignment
|
||||
|
||||
{{system_arch_alignment}}
|
||||
|
||||
## Detailed Design
|
||||
|
||||
### Services and Modules
|
||||
|
||||
{{services_modules}}
|
||||
|
||||
### Data Models and Contracts
|
||||
|
||||
{{data_models}}
|
||||
|
||||
### APIs and Interfaces
|
||||
|
||||
{{apis_interfaces}}
|
||||
|
||||
### Workflows and Sequencing
|
||||
|
||||
{{workflows_sequencing}}
|
||||
|
||||
## Non-Functional Requirements
|
||||
|
||||
### Performance
|
||||
|
||||
{{nfr_performance}}
|
||||
|
||||
### Security
|
||||
|
||||
{{nfr_security}}
|
||||
|
||||
### Reliability/Availability
|
||||
|
||||
{{nfr_reliability}}
|
||||
|
||||
### Observability
|
||||
|
||||
{{nfr_observability}}
|
||||
|
||||
## Dependencies and Integrations
|
||||
|
||||
{{dependencies_integrations}}
|
||||
|
||||
## Acceptance Criteria (Authoritative)
|
||||
|
||||
{{acceptance_criteria}}
|
||||
|
||||
## Traceability Mapping
|
||||
|
||||
{{traceability_mapping}}
|
||||
|
||||
## Risks, Assumptions, Open Questions
|
||||
|
||||
{{risks_assumptions_questions}}
|
||||
|
||||
## Test Strategy Summary
|
||||
|
||||
{{test_strategy}}
|
||||
@@ -0,0 +1,58 @@
|
||||
name: tech-spec
|
||||
description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
|
||||
author: "BMAD BMM"
|
||||
|
||||
# Critical variables
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
date: system-generated
|
||||
|
||||
# Inputs expected (check output_folder or ask user if missing)
|
||||
recommended_inputs:
|
||||
- prd
|
||||
- gdd
|
||||
- architecture
|
||||
- ux_design
|
||||
- epics (only the specific epic needed for this tech spec)
|
||||
- prior epic tech-specs for model, style and consistency reference
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: SELECTIVE LOAD - only load the specific epic needed (epic_num from context)
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
gdd:
|
||||
whole: "{output_folder}/*gdd*.md"
|
||||
sharded: "{output_folder}/*gdd*/index.md"
|
||||
|
||||
architecture:
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
|
||||
ux_design:
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded_index: "{output_folder}/*epic*/index.md"
|
||||
sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context"
|
||||
template: "{installed_path}/template.md"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/tech-spec-epic-{{epic_id}}.md"
|
||||
|
||||
standalone: true
|
||||
77
bmad/bmm/workflows/4-implementation/retrospective/README.md
Normal file
77
bmad/bmm/workflows/4-implementation/retrospective/README.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
last-redoc-date: 2025-10-01
|
||||
---
|
||||
|
||||
# Retrospective Workflow
|
||||
|
||||
The retrospective workflow is v6's learning capture mechanism, run by the Scrum Master (SM) after epic completion to systematically harvest insights, patterns, and improvements discovered during implementation. Unlike traditional retrospectives that focus primarily on process and team dynamics, this workflow performs deep technical and methodological analysis of the entire epic journey—from story creation through implementation to review—identifying what worked well, what could improve, and what patterns emerged. The retrospective produces actionable intelligence that informs future epics, improves workflow templates, and evolves the team's shared knowledge.
|
||||
|
||||
This workflow represents a critical feedback loop in the v6 methodology. Each epic is an experiment in adaptive software development, and the retrospective is where we analyze the results of that experiment. The SM examines completed stories, review feedback, course corrections made, story-context effectiveness, technical decisions, and team collaboration patterns to extract transferable learning. This learning manifests as updates to workflow templates, new story-context patterns, refined estimation approaches, and documented best practices.
|
||||
|
||||
The retrospective is not just a compliance ritual but a genuine opportunity for continuous improvement. By systematically analyzing what happened during the epic, the team builds institutional knowledge that makes each subsequent epic smoother, faster, and higher quality. The insights captured here directly improve future story creation, context generation, development efficiency, and review effectiveness.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Conduct retrospective after epic completion
|
||||
bmad run retrospective
|
||||
```
|
||||
|
||||
The SM should run this workflow:
|
||||
|
||||
- After all stories in an epic are completed
|
||||
- Before starting the next major epic
|
||||
- When significant learning has accumulated
|
||||
- As preparation for improving future epic execution
|
||||
|
||||
## Inputs
|
||||
|
||||
**Required Context:**
|
||||
|
||||
- **Epic Document**: Complete epic specification and goals
|
||||
- **All Story Documents**: Every story created for the epic
|
||||
- **Review Reports**: All review feedback and findings
|
||||
- **Course Corrections**: Any correct-course actions taken
|
||||
- **Story Contexts**: Generated expert guidance for each story
|
||||
- **Implementation Artifacts**: Code commits, test results, deployment records
|
||||
|
||||
**Analysis Targets:**
|
||||
|
||||
- Story creation accuracy and sizing
|
||||
- Story-context effectiveness and relevance
|
||||
- Implementation challenges and solutions
|
||||
- Review findings and patterns
|
||||
- Technical decisions and outcomes
|
||||
- Estimation accuracy
|
||||
- Team collaboration and communication
|
||||
- Workflow effectiveness
|
||||
|
||||
## Outputs
|
||||
|
||||
**Primary Deliverable:**
|
||||
|
||||
- **Retrospective Report** (`[epic-id]-retrospective.xml`): Comprehensive analysis including:
|
||||
- Executive summary of epic outcomes
|
||||
- Story-by-story analysis of what was learned
|
||||
- Technical insights and architecture learnings
|
||||
- Story-context effectiveness assessment
|
||||
- Process improvements identified
|
||||
- Patterns discovered (good and bad)
|
||||
- Recommendations for future epics
|
||||
- Metrics and statistics (velocity, cycle time, etc.)
|
||||
|
||||
**Actionable Outputs:**
|
||||
|
||||
- **Template Updates**: Improvements to workflow templates based on learning
|
||||
- **Pattern Library**: New story-context patterns for common scenarios
|
||||
- **Best Practices**: Documented approaches that worked well
|
||||
- **Gotchas**: Issues to avoid in future work
|
||||
- **Estimation Refinements**: Better story sizing guidance
|
||||
- **Process Changes**: Workflow adjustments for next epic
|
||||
|
||||
**Artifacts:**
|
||||
|
||||
- Epic marked as complete with retrospective attached
|
||||
- Knowledge base updated with new patterns
|
||||
- Workflow templates updated if needed
|
||||
- Team learning captured for onboarding
|
||||
1460
bmad/bmm/workflows/4-implementation/retrospective/instructions.md
Normal file
1460
bmad/bmm/workflows/4-implementation/retrospective/instructions.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,71 @@
|
||||
# Retrospective - Epic Completion Review Workflow
|
||||
name: "retrospective"
|
||||
description: "Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic"
|
||||
author: "BMad"
|
||||
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
date: system-generated
|
||||
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
|
||||
template: false
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
|
||||
mode: interactive
|
||||
trigger: "Run AFTER completing an epic"
|
||||
|
||||
required_inputs:
|
||||
- agent_manifest: "{project-root}/bmad/_cfg/agent-manifest.csv"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: SELECTIVE LOAD - only load the completed epic and relevant retrospectives
|
||||
input_file_patterns:
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded_index: "{output_folder}/*epic*/index.md"
|
||||
sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
|
||||
|
||||
previous_retrospective:
|
||||
pattern: "{output_folder}/retrospectives/epic-{{prev_epic_num}}-retro-*.md"
|
||||
|
||||
architecture:
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
|
||||
prd:
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
|
||||
document_project:
|
||||
sharded: "{output_folder}/docs/index.md"
|
||||
|
||||
# Required files
|
||||
sprint_status_file: "{output_folder}/sprint-status.yaml"
|
||||
story_directory: "{config_source}:dev_story_location"
|
||||
retrospectives_folder: "{output_folder}/retrospectives"
|
||||
|
||||
output_artifacts:
|
||||
- retrospective_summary: "Comprehensive review of what went well and what could improve"
|
||||
- lessons_learned: "Key insights for future epics"
|
||||
- action_items: "Specific improvements with ownership"
|
||||
- next_epic_preparation: "Dependencies, gaps, and preparation tasks for next epic"
|
||||
- critical_path: "Blockers or prerequisites that must be addressed"
|
||||
|
||||
facilitation:
|
||||
facilitator: "Bob (Scrum Master)"
|
||||
tone: "Psychological safety - no blame, focus on systems and processes"
|
||||
format: "Two-part: (1) Review completed epic + (2) Preview next epic preparation"
|
||||
|
||||
validation_required:
|
||||
- testing_complete: "Has full regression testing been completed?"
|
||||
- deployment_status: "Has epic been deployed to production?"
|
||||
- business_validation: "Have stakeholders reviewed and accepted deliverables?"
|
||||
- technical_health: "Is codebase in stable, maintainable state?"
|
||||
- blocker_resolution: "Any unresolved blockers that will impact next epic?"
|
||||
|
||||
standalone: true
|
||||
156
bmad/bmm/workflows/4-implementation/sprint-planning/README.md
Normal file
156
bmad/bmm/workflows/4-implementation/sprint-planning/README.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# Sprint Planning Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
The sprint-planning workflow generates and manages the sprint status tracking file that serves as the single source of truth for Phase 4 implementation. It extracts all epics and stories from epic files and tracks their progress through the development lifecycle.
|
||||
|
||||
In Agile terminology, this workflow facilitates **Sprint Planning** or **Sprint 0 Kickoff** - the transition from planning/architecture into actual development execution.
|
||||
|
||||
## Purpose
|
||||
|
||||
This workflow creates a `sprint-status.yaml` file that:
|
||||
|
||||
- Lists all epics, stories, and retrospectives in order
|
||||
- Tracks the current status of each item
|
||||
- Provides a clear view of what needs to be worked on next
|
||||
- Ensures only one story is in progress at a time
|
||||
- Maintains the development flow from backlog to done
|
||||
|
||||
## When to Use
|
||||
|
||||
Run this workflow:
|
||||
|
||||
1. **Initially** - After Phase 3 (solutioning) is complete and epics are finalized
|
||||
2. **After epic context creation** - To update epic status to 'contexted'
|
||||
3. **Periodically** - To auto-detect newly created story files
|
||||
4. **For status checks** - To see overall project progress
|
||||
|
||||
## Status State Machine
|
||||
|
||||
### Epic Flow
|
||||
|
||||
```
|
||||
backlog → contexted
|
||||
```
|
||||
|
||||
### Story Flow
|
||||
|
||||
```
|
||||
backlog → drafted → ready-for-dev → in-progress → review → done
|
||||
```
|
||||
|
||||
### Retrospective Flow
|
||||
|
||||
```
|
||||
optional ↔ completed
|
||||
```
|
||||
|
||||
## Key Guidelines
|
||||
|
||||
1. **Epic Context Recommended**: Epics should be `contexted` before their stories can be `drafted`
|
||||
2. **Flexible Parallelism**: Multiple stories can be `in-progress` based on team capacity
|
||||
3. **Sequential Default**: Stories within an epic are typically worked in order, but parallel work is supported
|
||||
4. **Review Flow**: Stories should go through `review` before `done`
|
||||
5. **Learning Transfer**: SM typically drafts next story after previous is `done`, incorporating learnings
|
||||
|
||||
## File Locations
|
||||
|
||||
### Input Files
|
||||
|
||||
- **Epic Files**: `{output_folder}/epic*.md` or `{output_folder}/epics.md`
|
||||
- **Epic Context**: `{output_folder}/epic-{n}-context.md`
|
||||
- **Story Files**: `{story_dir}/{epic}-{story}-{title}.md`
|
||||
- Example: `stories/1-1-user-authentication.md`
|
||||
- **Story Context**: `{story_dir}/{epic}-{story}-{title}-context.md`
|
||||
- Example: `stories/1-1-user-authentication-context.md`
|
||||
|
||||
### Output File
|
||||
|
||||
- **Status File**: `{output_folder}/sprint-status.yaml`
|
||||
|
||||
## Usage by Agents
|
||||
|
||||
### SM (Scrum Master) Agent
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Check sprint-status.yaml for stories in 'done' status
|
||||
- Identify next 'backlog' story to draft
|
||||
- Run create-story workflow
|
||||
- Update status to 'drafted'
|
||||
- Create story context
|
||||
- Update status to 'ready-for-dev'
|
||||
```
|
||||
|
||||
### Developer Agent
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Find stories with 'ready-for-dev' status
|
||||
- Update to 'in-progress' when starting
|
||||
- Implement the story
|
||||
- Update to 'review' when complete
|
||||
- Address review feedback
|
||||
- Update to 'done' after review
|
||||
```
|
||||
|
||||
### Test Architect
|
||||
|
||||
```yaml
|
||||
Tasks:
|
||||
- Monitor stories entering 'review'
|
||||
- Track epic progress
|
||||
- Identify when retrospectives are needed
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
```yaml
|
||||
# Sprint Status
|
||||
# Generated: 2025-01-20
|
||||
# Project: MyPlantFamily
|
||||
|
||||
development_status:
|
||||
epic-1: contexted
|
||||
1-1-project-foundation: done
|
||||
1-2-app-shell: done
|
||||
1-3-user-authentication: in-progress
|
||||
1-4-plant-data-model: ready-for-dev
|
||||
1-5-add-plant-manual: drafted
|
||||
1-6-photo-identification: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
epic-2: contexted
|
||||
2-1-personality-system: in-progress
|
||||
2-2-chat-interface: drafted
|
||||
2-3-llm-integration: backlog
|
||||
2-4-reminder-system: backlog
|
||||
epic-2-retrospective: optional
|
||||
```
|
||||
|
||||
## Integration with BMM Workflow
|
||||
|
||||
This workflow is part of Phase 4 (Implementation) and integrates with:
|
||||
|
||||
1. **epic-tech-context** - Creates technical context for epics
|
||||
2. **create-story** - Drafts individual story files
|
||||
3. **story-context** - Adds implementation context to stories
|
||||
4. **dev-story** - Developer implements the story
|
||||
5. **code-review** - SM reviews implementation
|
||||
6. **retrospective** - Optional epic retrospective
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Clear Visibility**: Everyone knows what's being worked on
|
||||
- **Flexible Capacity**: Supports both sequential and parallel work patterns
|
||||
- **Learning Transfer**: SM can incorporate learnings when drafting next story
|
||||
- **Progress Tracking**: Easy to see overall project status
|
||||
- **Automation Friendly**: Simple YAML format for agent updates
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Initial Generation**: Run immediately after epics are finalized
|
||||
2. **Regular Updates**: Agents should update status as they work
|
||||
3. **Manual Override**: You can manually edit the file if needed
|
||||
4. **Backup First**: The workflow backs up existing status before regenerating
|
||||
5. **Validation**: The workflow validates legal status transitions
|
||||
@@ -0,0 +1,33 @@
|
||||
# Sprint Planning Validation Checklist
|
||||
|
||||
## Core Validation
|
||||
|
||||
### Complete Coverage Check
|
||||
|
||||
- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
|
||||
- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
|
||||
- [ ] Every epic has a corresponding retrospective entry
|
||||
- [ ] No items in sprint-status.yaml that don't exist in epic files
|
||||
|
||||
### Parsing Verification
|
||||
|
||||
Compare epic files against generated sprint-status.yaml:
|
||||
|
||||
```
|
||||
Epic Files Contains: Sprint Status Contains:
|
||||
✓ Epic 1 ✓ epic-1: [status]
|
||||
✓ Story 1.1: User Auth ✓ 1-1-user-auth: [status]
|
||||
✓ Story 1.2: Account Mgmt ✓ 1-2-account-mgmt: [status]
|
||||
✓ Story 1.3: Plant Naming ✓ 1-3-plant-naming: [status]
|
||||
✓ epic-1-retrospective: [status]
|
||||
✓ Epic 2 ✓ epic-2: [status]
|
||||
✓ Story 2.1: Personality Model ✓ 2-1-personality-model: [status]
|
||||
✓ Story 2.2: Chat Interface ✓ 2-2-chat-interface: [status]
|
||||
✓ epic-2-retrospective: [status]
|
||||
```
|
||||
|
||||
### Final Check
|
||||
|
||||
- [ ] Total count of epics matches
|
||||
- [ ] Total count of stories matches
|
||||
- [ ] All items are in the expected order (epic, stories, retrospective)
|
||||
@@ -0,0 +1,238 @@
|
||||
# Sprint Planning - Sprint Status Generator
|
||||
|
||||
<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
|
||||
<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml</critical>
|
||||
|
||||
## 📚 Document Discovery - Full Epic Loading
|
||||
|
||||
**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
|
||||
|
||||
**Epic Discovery Process:**
|
||||
|
||||
1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
|
||||
2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
|
||||
3. **If sharded version found**:
|
||||
- Read `index.md` to understand the document structure
|
||||
- Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
|
||||
- Process all epics and their stories from the combined content
|
||||
- This ensures complete sprint status coverage
|
||||
4. **Priority**: If both whole and sharded versions exist, use the whole document
|
||||
|
||||
**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Parse epic files and extract all work items">
|
||||
<action>Communicate in {communication_language} with {user_name}</action>
|
||||
<action>Look for all files matching `{epics_pattern}` in {epics_location}</action>
|
||||
<action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>
|
||||
|
||||
<action>For each epic file found, extract:</action>
|
||||
|
||||
- Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
|
||||
- Story IDs and titles from patterns like `### Story 1.1: User Authentication`
|
||||
- Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title`
|
||||
|
||||
**Story ID Conversion Rules:**
|
||||
|
||||
- Original: `### Story 1.1: User Authentication`
|
||||
- Replace period with dash: `1-1`
|
||||
- Convert title to kebab-case: `user-authentication`
|
||||
- Final key: `1-1-user-authentication`
|
||||
|
||||
<action>Build complete inventory of all epics and stories from all epic files</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Build sprint status structure">
|
||||
<action>For each epic found, create entries in this order:</action>
|
||||
|
||||
1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog`
|
||||
2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog`
|
||||
3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional`
|
||||
|
||||
**Example structure:**
|
||||
|
||||
```yaml
|
||||
development_status:
|
||||
epic-1: backlog
|
||||
1-1-user-authentication: backlog
|
||||
1-2-account-management: backlog
|
||||
epic-1-retrospective: optional
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Apply intelligent status detection">
|
||||
<action>For each epic, check if tech context file exists:</action>
|
||||
|
||||
- Check: `{output_folder}/epic-{num}-context.md`
|
||||
- If exists → set epic status to `contexted`
|
||||
- Else → keep as `backlog`
|
||||
|
||||
<action>For each story, detect current status by checking files:</action>
|
||||
|
||||
**Story file detection:**
|
||||
|
||||
- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
|
||||
- If exists → upgrade status to at least `drafted`
|
||||
|
||||
**Story context detection:**
|
||||
|
||||
- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.md`)
|
||||
- If exists → upgrade status to at least `ready-for-dev`
|
||||
|
||||
**Preservation rule:**
|
||||
|
||||
- If existing `{status_file}` exists and has more advanced status, preserve it
|
||||
- Never downgrade status (e.g., don't change `done` to `drafted`)
|
||||
|
||||
**Status Flow Reference:**
|
||||
|
||||
- Epic: `backlog` → `contexted`
|
||||
- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
|
||||
- Retrospective: `optional` ↔ `completed`
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Generate sprint status file">
|
||||
<action>Create or update {status_file} with:</action>
|
||||
|
||||
**File Structure:**
|
||||
|
||||
```yaml
|
||||
# generated: {date}
|
||||
# project: {project_name}
|
||||
# project_key: {project_key}
|
||||
# tracking_system: {tracking_system}
|
||||
# story_location: {story_location}
|
||||
|
||||
# STATUS DEFINITIONS:
|
||||
# ==================
|
||||
# Epic Status:
|
||||
# - backlog: Epic exists in epic file but not contexted
|
||||
# - contexted: Epic tech context created (required before drafting stories)
|
||||
#
|
||||
# Story Status:
|
||||
# - backlog: Story only exists in epic file
|
||||
# - drafted: Story file created in stories folder
|
||||
# - ready-for-dev: Draft approved and story context created
|
||||
# - in-progress: Developer actively working on implementation
|
||||
# - review: Under SM review (via code-review workflow)
|
||||
# - done: Story completed
|
||||
#
|
||||
# Retrospective Status:
|
||||
# - optional: Can be completed but not required
|
||||
# - completed: Retrospective has been done
|
||||
#
|
||||
# WORKFLOW NOTES:
|
||||
# ===============
|
||||
# - Epics should be 'contexted' before stories can be 'drafted'
|
||||
# - Stories can be worked in parallel if team capacity allows
|
||||
# - SM typically drafts next story after previous one is 'done' to incorporate learnings
|
||||
# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
|
||||
|
||||
generated: { date }
|
||||
project: { project_name }
|
||||
project_key: { project_key }
|
||||
tracking_system: { tracking_system }
|
||||
story_location: { story_location }
|
||||
|
||||
development_status:
|
||||
# All epics, stories, and retrospectives in order
|
||||
```
|
||||
|
||||
<action>Write the complete sprint status YAML to {status_file}</action>
|
||||
<action>CRITICAL: For story_location field, write the variable value EXACTLY as defined in workflow.yaml: "{project-root}/docs/stories"</action>
|
||||
<action>CRITICAL: Do NOT resolve {project-root} to an absolute path - keep it as the literal string "{project-root}/docs/stories"</action>
|
||||
<action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
|
||||
<action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Validate and report">
|
||||
<action>Perform validation checks:</action>
|
||||
|
||||
- [ ] Every epic in epic files appears in sprint-status.yaml
|
||||
- [ ] Every story in epic files appears in sprint-status.yaml
|
||||
- [ ] Every epic has a corresponding retrospective entry
|
||||
- [ ] No items in sprint-status.yaml that don't exist in epic files
|
||||
- [ ] All status values are legal (match state machine definitions)
|
||||
- [ ] File is valid YAML syntax
|
||||
|
||||
<action>Count totals:</action>
|
||||
|
||||
- Total epics: {{epic_count}}
|
||||
- Total stories: {{story_count}}
|
||||
- Epics contexted: {{contexted_count}}
|
||||
- Stories in progress: {{in_progress_count}}
|
||||
- Stories done: {{done_count}}
|
||||
|
||||
<action>Display completion summary to {user_name} in {communication_language}:</action>
|
||||
|
||||
**Sprint Status Generated Successfully**
|
||||
|
||||
- **File Location:** {status_file}
|
||||
- **Total Epics:** {{epic_count}}
|
||||
- **Total Stories:** {{story_count}}
|
||||
- **Contexted Epics:** {{contexted_count}}
|
||||
- **Stories In Progress:** {{in_progress_count}}
|
||||
- **Stories Completed:** {{done_count}}
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Review the generated sprint-status.yaml
|
||||
2. Use this file to track development progress
|
||||
3. Agents will update statuses as they work
|
||||
4. Re-run this workflow to refresh auto-detected statuses
|
||||
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
## Additional Documentation
|
||||
|
||||
### Status State Machine
|
||||
|
||||
**Epic Status Flow:**
|
||||
|
||||
```
|
||||
backlog → contexted
|
||||
```
|
||||
|
||||
- **backlog**: Epic exists in epic file but tech context not created
|
||||
- **contexted**: Epic tech context has been generated (prerequisite for story drafting)
|
||||
|
||||
**Story Status Flow:**
|
||||
|
||||
```
|
||||
backlog → drafted → ready-for-dev → in-progress → review → done
|
||||
```
|
||||
|
||||
- **backlog**: Story only exists in epic file
|
||||
- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
|
||||
- **ready-for-dev**: Draft approved + story context created
|
||||
- **in-progress**: Developer actively working
|
||||
- **review**: Under SM review (via code-review workflow)
|
||||
- **done**: Completed
|
||||
|
||||
**Retrospective Status:**
|
||||
|
||||
```
|
||||
optional ↔ completed
|
||||
```
|
||||
|
||||
- **optional**: Can be done but not required
|
||||
- **completed**: Retrospective has been completed
|
||||
|
||||
### Guidelines
|
||||
|
||||
1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted`
|
||||
2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported
|
||||
3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
|
||||
4. **Review Before Done**: Stories should pass through `review` before `done`
|
||||
5. **Learning Transfer**: SM typically drafts next story after previous one is `done` to incorporate learnings
|
||||
|
||||
### Error Handling
|
||||
|
||||
- If epic file can't be parsed, report specific file and continue with others
|
||||
- If existing status file is malformed, backup and regenerate
|
||||
- Log warnings for duplicate story IDs across epics
|
||||
- Validate status transitions are legal (can't go from `backlog` to `done`)
|
||||
@@ -0,0 +1,55 @@
|
||||
# Sprint Status Template
|
||||
# This is an EXAMPLE showing the expected format
|
||||
# The actual file will be generated with all epics/stories from your epic files
|
||||
|
||||
# generated: {date}
|
||||
# project: {project_name}
|
||||
# project_key: {project_key}
|
||||
# tracking_system: {tracking_system}
|
||||
# story_location: {story_location}
|
||||
|
||||
# STATUS DEFINITIONS:
|
||||
# ==================
|
||||
# Epic Status:
|
||||
# - backlog: Epic exists in epic file but not contexted
|
||||
# - contexted: Next epic tech context created by *epic-tech-context (required)
|
||||
#
|
||||
# Story Status:
|
||||
# - backlog: Story only exists in epic file
|
||||
# - drafted: Story file created in stories folder by *create-story
|
||||
# - ready-for-dev: Draft approved and story context created by *story-ready
|
||||
# - in-progress: Developer actively working on implementation by *dev-story
|
||||
# - review: Implementation complete, ready for review by *code-review
|
||||
# - done: Story completed by *story-done
|
||||
#
|
||||
# Retrospective Status:
|
||||
# - optional: Can be completed but not required
|
||||
# - completed: Retrospective has been done by *retrospective
|
||||
#
|
||||
# WORKFLOW NOTES:
|
||||
# ===============
|
||||
# - Epics should be 'contexted' before stories can be 'drafted'
|
||||
# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
|
||||
# - Dev moves story to 'review', dev reviews, then Dev moves to 'done'
|
||||
|
||||
# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
|
||||
|
||||
generated: 05-06-2-2025 21:30
|
||||
project: My Awesome Project
|
||||
project_key: jira-1234
|
||||
tracking_system: file-system
|
||||
story_location: "{project-root}/docs/stories"
|
||||
|
||||
development_status:
|
||||
epic-1: contexted
|
||||
1-1-user-authentication: done
|
||||
1-2-account-management: drafted
|
||||
1-3-plant-data-model: backlog
|
||||
1-4-add-plant-manual: backlog
|
||||
epic-1-retrospective: optional
|
||||
|
||||
epic-2: backlog
|
||||
2-1-personality-system: backlog
|
||||
2-2-chat-interface: backlog
|
||||
2-3-llm-integration: backlog
|
||||
epic-2-retrospective: optional
|
||||
@@ -0,0 +1,47 @@
|
||||
name: sprint-planning
|
||||
description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/bmad/bmm/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/sprint-status-template.yaml"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
|
||||
# Variables and inputs
|
||||
variables:
|
||||
# Project identification
|
||||
project_name: "{config_source}:project_name"
|
||||
project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
|
||||
|
||||
# Tracking system configuration
|
||||
tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
|
||||
story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
|
||||
story_location_absolute: "{config_source}:dev_story_location" # Absolute path for file operations
|
||||
|
||||
# Source files (file-system only)
|
||||
epics_location: "{output_folder}" # Directory containing epic*.md files
|
||||
epics_pattern: "epic*.md" # Pattern to find epic files
|
||||
|
||||
# Output configuration
|
||||
status_file: "{output_folder}/sprint-status.yaml"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: FULL LOAD - sprint planning needs ALL epics to build complete status
|
||||
input_file_patterns:
|
||||
epics:
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{status_file}"
|
||||
|
||||
standalone: true
|
||||
234
bmad/bmm/workflows/4-implementation/story-context/README.md
Normal file
234
bmad/bmm/workflows/4-implementation/story-context/README.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# Story Context Assembly Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
Assembles a dynamic Story Context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story. Creates comprehensive development context for AI agents and developers working on specific stories.
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Automated Context Discovery** - Scans documentation and codebase for relevant artifacts
|
||||
- **XML Output Format** - Structured context optimized for LLM consumption
|
||||
- **Dependency Detection** - Identifies frameworks, packages, and technical dependencies
|
||||
- **Interface Mapping** - Locates existing APIs and interfaces to reuse
|
||||
- **Testing Integration** - Includes testing standards and generates test ideas
|
||||
- **Status Tracking** - Updates story status and maintains context references
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Invocation
|
||||
|
||||
```bash
|
||||
workflow story-context
|
||||
```
|
||||
|
||||
### With Specific Story
|
||||
|
||||
```bash
|
||||
# Process specific story file
|
||||
workflow story-context --input /path/to/story.md
|
||||
|
||||
# Using story path variable
|
||||
workflow story-context --story_path "docs/stories/1.2.feature-name.md"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
- **story_path**: Path to target story markdown file (defaults to latest.md)
|
||||
- **auto_update_status**: Whether to automatically update story status (default: false)
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
### Files Included
|
||||
|
||||
```
|
||||
story-context/
|
||||
├── workflow.yaml # Configuration and metadata
|
||||
├── instructions.md # Step-by-step execution guide
|
||||
├── context-template.xml # XML structure template
|
||||
├── checklist.md # Validation criteria
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Workflow Process
|
||||
|
||||
### Phase 1: Story Analysis (Steps 1-2)
|
||||
|
||||
- **Story Location**: Finds and loads target story markdown file
|
||||
- **Content Parsing**: Extracts epic ID, story ID, title, acceptance criteria, and tasks
|
||||
- **Template Initialization**: Creates initial XML context structure
|
||||
- **User Story Extraction**: Parses "As a... I want... So that..." components
|
||||
|
||||
### Phase 2: Documentation Discovery (Step 3)
|
||||
|
||||
- **Keyword Analysis**: Identifies relevant terms from story content
|
||||
- **Document Scanning**: Searches docs and module documentation
|
||||
- **Authority Prioritization**: Prefers PRDs, architecture docs, and specs
|
||||
- **Context Extraction**: Captures relevant sections with snippets
|
||||
|
||||
### Phase 3: Code Analysis (Step 4)
|
||||
|
||||
- **Symbol Search**: Finds relevant modules, functions, and components
|
||||
- **Interface Identification**: Locates existing APIs and interfaces
|
||||
- **Constraint Extraction**: Identifies development patterns and requirements
|
||||
- **Reuse Opportunities**: Highlights existing code to leverage
|
||||
|
||||
### Phase 4: Dependency Analysis (Step 5)
|
||||
|
||||
- **Manifest Detection**: Scans for package.json, requirements.txt, go.mod, etc.
|
||||
- **Framework Identification**: Identifies Unity, Node.js, Python, Go ecosystems
|
||||
- **Version Tracking**: Captures dependency versions where available
|
||||
- **Configuration Discovery**: Finds relevant project configurations
|
||||
|
||||
### Phase 5: Testing Context (Step 6)
|
||||
|
||||
- **Standards Extraction**: Identifies testing frameworks and patterns
|
||||
- **Location Mapping**: Documents where tests should be placed
|
||||
- **Test Ideas**: Generates initial test concepts for acceptance criteria
|
||||
- **Framework Integration**: Links to existing test infrastructure
|
||||
|
||||
### Phase 6: Validation and Updates (Steps 7-8)
|
||||
|
||||
- **XML Validation**: Ensures proper structure and completeness
|
||||
- **Status Updates**: Changes story status from Draft to ContextReadyDraft
|
||||
- **Reference Tracking**: Adds context file reference to story document
|
||||
- **Quality Assurance**: Validates against workflow checklist
|
||||
|
||||
## Output
|
||||
|
||||
### Generated Files
|
||||
|
||||
- **Primary output**: story-context-{epic_id}.{story_id}-{date}.xml
|
||||
- **Story updates**: Modified original story file with context references
|
||||
|
||||
### Output Structure
|
||||
|
||||
```xml
|
||||
<storyContext>
|
||||
<story>
|
||||
<basicInfo>
|
||||
<epicId>...</epicId>
|
||||
<storyId>...</storyId>
|
||||
<title>...</title>
|
||||
<status>...</status>
|
||||
</basicInfo>
|
||||
<userStory>
|
||||
<asA>...</asA>
|
||||
<iWant>...</iWant>
|
||||
<soThat>...</soThat>
|
||||
</userStory>
|
||||
<acceptanceCriteria>
|
||||
<criterion id="1">...</criterion>
|
||||
</acceptanceCriteria>
|
||||
<tasks>
|
||||
<task>...</task>
|
||||
</tasks>
|
||||
</story>
|
||||
|
||||
<artifacts>
|
||||
<docs>
|
||||
<doc path="..." title="..." section="..." snippet="..."/>
|
||||
</docs>
|
||||
<code>
|
||||
<file path="..." kind="..." symbol="..." lines="..." reason="..."/>
|
||||
</code>
|
||||
<dependencies>
|
||||
<node>
|
||||
<package name="..." version="..."/>
|
||||
</node>
|
||||
</dependencies>
|
||||
</artifacts>
|
||||
|
||||
<interfaces>
|
||||
<interface name="..." kind="..." signature="..." path="..."/>
|
||||
</interfaces>
|
||||
|
||||
<constraints>
|
||||
<constraint>...</constraint>
|
||||
</constraints>
|
||||
|
||||
<tests>
|
||||
<standards>...</standards>
|
||||
<locations>
|
||||
<location>...</location>
|
||||
</locations>
|
||||
<ideas>
|
||||
<idea ac="1">...</idea>
|
||||
</ideas>
|
||||
</tests>
|
||||
</storyContext>
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Story File**: Valid story markdown with proper structure (epic.story.title.md format)
|
||||
- **Repository Access**: Ability to scan documentation and source code
|
||||
- **Documentation**: Project documentation in standard locations (docs/, src/, etc.)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Starting
|
||||
|
||||
1. **Ensure Story Quality**: Verify story has clear acceptance criteria and tasks
|
||||
2. **Update Documentation**: Ensure relevant docs are current and discoverable
|
||||
3. **Clean Repository**: Remove obsolete code that might confuse context assembly
|
||||
|
||||
### During Execution
|
||||
|
||||
1. **Review Extracted Context**: Verify that discovered artifacts are actually relevant
|
||||
2. **Check Interface Accuracy**: Ensure identified APIs and interfaces are current
|
||||
3. **Validate Dependencies**: Confirm dependency information matches project state
|
||||
|
||||
### After Completion
|
||||
|
||||
1. **Review XML Output**: Validate the generated context makes sense
|
||||
2. **Test with Developer**: Have a developer review context usefulness
|
||||
3. **Update Story Status**: Verify story status was properly updated
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Issue**: Context contains irrelevant or outdated information
|
||||
|
||||
- **Solution**: Review keyword extraction and document filtering logic
|
||||
- **Check**: Ensure story title and acceptance criteria are specific and clear
|
||||
|
||||
**Issue**: Missing relevant code or interfaces
|
||||
|
||||
- **Solution**: Verify code search patterns and symbol extraction
|
||||
- **Check**: Ensure relevant code follows project naming conventions
|
||||
|
||||
**Issue**: Dependency information is incomplete or wrong
|
||||
|
||||
- **Solution**: Check for multiple package manifests or unusual project structure
|
||||
- **Check**: Verify dependency files are in expected locations and formats
|
||||
|
||||
## Customization
|
||||
|
||||
To customize this workflow:
|
||||
|
||||
1. **Modify Search Patterns**: Update instructions.md to adjust code and doc discovery
|
||||
2. **Extend XML Schema**: Customize context-template.xml for additional context types
|
||||
3. **Add Validation**: Extend checklist.md with project-specific quality criteria
|
||||
4. **Configure Dependencies**: Adjust dependency detection for specific tech stacks
|
||||
|
||||
## Version History
|
||||
|
||||
- **v6.0.0** - XML-based context assembly with comprehensive artifact discovery
|
||||
- Multi-ecosystem dependency detection
|
||||
- Interface and constraint extraction
|
||||
- Testing context integration
|
||||
- Story status management
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
|
||||
- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
|
||||
- Validate output using `checklist.md`
|
||||
- Ensure story files follow expected markdown structure
|
||||
- Check that repository structure supports automated discovery
|
||||
|
||||
---
|
||||
|
||||
_Part of the BMad Method v6 - BMM (Method) Module_
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user