mirror of
https://github.com/mmahdium/portfolio.git
synced 2026-09-28 10:31:44 +03:30
chore: add BMAD agent workflows and configuration system
- Add comprehensive agent workflow definitions for 8 specialized roles (analyst, architect, developer, product manager, scrum master, technical writer, UX designer, QA engineer) - Add 35+ workflow definitions covering analysis, planning, solutioning, and implementation phases - Add BMAD configuration system with agent, task, tool, workflow, and file manifests - Add BMM (Business Model Methodology) documentation including quick-start guides, architecture references, and workflow analysis - Add test architecture knowledge base with 20+ testing patterns and best practices - Add team configuration templates and party mode setup for collaborative development - Establish foundation for enterprise agentic development framework with adaptive scaling capabilities
This commit is contained in:
mahdiarghyani
@@ -0,0 +1,321 @@
|
||||
# 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"
|
||||
@@ -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}}_
|
||||
@@ -0,0 +1,240 @@
|
||||
# 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 implementation-readiness 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
|
||||
|
||||
<!-- replace with list of critical issues found, or N/A -->
|
||||
|
||||
### Recommended Actions Before Implementation
|
||||
|
||||
<!-- replace with list of recommended actions, or N/A -->
|
||||
|
||||
---
|
||||
|
||||
**Next Step**: Run the **implementation-readiness** workflow to validate alignment between PRD, UX, Architecture, and Stories before beginning implementation.
|
||||
|
||||
---
|
||||
|
||||
_This checklist validates architecture document quality only. Use implementation-readiness 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"
|
||||
@@ -0,0 +1,768 @@
|
||||
# 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>
|
||||
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
|
||||
<critical>ELICITATION POINTS: After completing each major architectural decision area (identified by template-output tags for decision_record, project_structure, novel_pattern_designs, implementation_patterns, and architecture_document), invoke advanced elicitation to refine decisions before proceeding</critical>
|
||||
<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
|
||||
<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
|
||||
|
||||
<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. Create 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>
|
||||
|
||||
<check if="create-architecture status is indicates 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>
|
||||
|
||||
<action>Check for existing PRD file using fuzzy matching</action>
|
||||
|
||||
<action>Fuzzy match PRD file: {prd_file}</action>
|
||||
<check if="PRD_not_found">
|
||||
<output>**PRD Not Found**
|
||||
|
||||
Creation of an Architecture works from your Product Requirements Document (PRD), along with an optional UX Design and other assets.
|
||||
|
||||
Looking for: _prd_.md, or prd/\* + files in {output_folder}
|
||||
|
||||
Please talk to the PM Agent to run the Create PRD workflow first to define your requirements, or if I am mistaken and it does exist, provide the file now.
|
||||
</output>
|
||||
<ask>Would you like to exit, or can you provide a PRD?
|
||||
<action if='yes to exit'>Exit workflow - PRD required</action>
|
||||
<action if='prd provided'>Proceed to Step 1</action>
|
||||
</ask>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="0.5" goal="Discover and load input documents">
|
||||
<invoke-protocol name="discover_inputs" />
|
||||
<note>After discovery, these content variables are available: {prd_content}, {epics_content}, {ux_design_content}, {document_project_content}</note>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load and understand project context">
|
||||
<action>Review loaded PRD: {prd_content} (auto-loaded in Step 0.5 - handles both whole and sharded documents)</action>
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
<action>Review loaded epics: {epics_content}</action>
|
||||
</check>
|
||||
|
||||
<action>Check for UX specification:
|
||||
<check if="{ux_design_content} is not empty">
|
||||
<action>Extract architectural implications from {ux_design_content}: - 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_content}:
|
||||
|
||||
- Functional Requirements (FRs) - the complete list of capabilities
|
||||
- Non-Functional Requirements (performance, security, compliance, etc.)
|
||||
- Any technical constraints mentioned
|
||||
</action>
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
<action>Extract from {epics_content}:
|
||||
- Epic structure and user stories
|
||||
- Acceptance criteria
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>Count and assess project scale:
|
||||
<check if="{epics_content} is not empty">
|
||||
|
||||
- Number of epics: {{epic_count}}
|
||||
- Number of stories: {{story_count}}
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
- Number of functional requirements: {{fr_count}} (from PRD)
|
||||
- FR categories: {{fr_category_list}} (capability groups from PRD)
|
||||
</check>
|
||||
- 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}}.
|
||||
<check if="{epics_content} is not empty">
|
||||
I see {{epic_count}} epics with {{story_count}} total stories.
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
I found {{fr_count}} functional requirements organized into {{fr_category_list}}.
|
||||
</check>
|
||||
{{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}}
|
||||
<check if="{epics_content} is not empty">
|
||||
Affects Epics: {{list_of_affected_epics}}
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
Affects FR Categories: {{list_of_affected_fr_categories}}
|
||||
</check>
|
||||
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>
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
<action>Map epics to architectural boundaries:
|
||||
"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
|
||||
</action>
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
<action>Map FR categories to architectural boundaries:
|
||||
"FR Category: {{fr_category_name}} → Lives in {{module/directory/service}}"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<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)
|
||||
<check if="{epics_content} is not empty">
|
||||
|
||||
- Complex state machines crossing multiple epics
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
- Complex state machines crossing multiple FR categories
|
||||
</check>
|
||||
</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}}
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
Affects Epics:
|
||||
{{epics_that_use_this_pattern}}
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
Affects FR Categories:
|
||||
{{fr_categories_that_use_this_pattern}}
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Validate pattern completeness:
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
"Does this {{pattern_name}} design cover all the use cases in your epics?
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
"Does this {{pattern_name}} design cover all the use cases in your requirements?
|
||||
</check>
|
||||
- {{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>
|
||||
|
||||
<check if="{epics_content} is not empty">
|
||||
<action>Verify epic coverage: - Does every epic have architectural support? - Are all user stories implementable with these decisions? - Are there any gaps?
|
||||
</action>
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
<action>Verify FR coverage: - Does every functional requirement have architectural support? - Are all capabilities implementable with these decisions? - Are there any gaps?
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<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 coverage mapping) 4. Complete Project Structure (full tree, no placeholders)
|
||||
<check if="{epics_content} is not empty"> 5. Epic to Architecture Mapping (every epic placed)
|
||||
</check>
|
||||
<check if="{epics_content} is empty"> 5. FR Category to Architecture Mapping (every FR category placed)
|
||||
</check> 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
|
||||
<check if="{epics_content} is not empty">
|
||||
- [] Every epic is mapped to architecture components
|
||||
</check>
|
||||
<check if="{epics_content} is empty">
|
||||
- [] Every FR category is mapped to architecture components
|
||||
</check>
|
||||
- [] 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.
|
||||
|
@@ -0,0 +1,55 @@
|
||||
# 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
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED)
|
||||
input_file_patterns:
|
||||
prd:
|
||||
description: "Product requirements and features"
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
epics:
|
||||
description: "Epic and story breakdown (optional - uses PRD FRs if not present)"
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
ux_design:
|
||||
description: "UX design specification (optional)"
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
document_project:
|
||||
description: "Brownfield project documentation (optional)"
|
||||
sharded: "{output_folder}/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
|
||||
# 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"
|
||||
|
||||
standalone: true
|
||||
|
||||
# Web bundle configuration for standalone deployment
|
||||
@@ -0,0 +1,80 @@
|
||||
# {{project_name}} - Epic Breakdown
|
||||
|
||||
**Author:** {{user_name}}
|
||||
**Date:** {{date}}
|
||||
**Project Level:** {{project_level}}
|
||||
**Target Scale:** {{target_scale}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the [PRD](./PRD.md) into implementable stories.
|
||||
|
||||
**Living Document Notice:** This is the initial version. It will be updated after UX Design and Architecture workflows add interaction and technical details to stories.
|
||||
|
||||
{{epics_summary}}
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements Inventory
|
||||
|
||||
{{fr_inventory}}
|
||||
|
||||
---
|
||||
|
||||
## FR Coverage Map
|
||||
|
||||
{{fr_coverage_map}}
|
||||
|
||||
---
|
||||
|
||||
<!-- Repeat for each epic (N = 1, 2, 3...) -->
|
||||
|
||||
## Epic {{N}}: {{epic_title_N}}
|
||||
|
||||
{{epic_goal_N}}
|
||||
|
||||
<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
|
||||
|
||||
### Story {{N}}.{{M}}: {{story_title_N_M}}
|
||||
|
||||
As a {{user_type}},
|
||||
I want {{capability}},
|
||||
So that {{value_benefit}}.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** {{precondition}}
|
||||
**When** {{action}}
|
||||
**Then** {{expected_outcome}}
|
||||
|
||||
**And** {{additional_criteria}}
|
||||
|
||||
**Prerequisites:** {{dependencies_on_previous_stories}}
|
||||
|
||||
**Technical Notes:** {{implementation_guidance}}
|
||||
|
||||
<!-- End story repeat -->
|
||||
|
||||
---
|
||||
|
||||
<!-- End epic repeat -->
|
||||
|
||||
---
|
||||
|
||||
## FR Coverage Matrix
|
||||
|
||||
{{fr_coverage_matrix}}
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
{{epic_breakdown_summary}}
|
||||
|
||||
---
|
||||
|
||||
_For implementation: Use the `create-story` workflow to generate individual story implementation plans from this epic breakdown._
|
||||
|
||||
_This document will be updated after UX Design and Architecture workflows to incorporate interaction details and technical decisions._
|
||||
@@ -0,0 +1,616 @@
|
||||
# Epic and Story Decomposition - Intent-Based 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 development agents</critical>
|
||||
<critical>EVERY story must be completable by a single dev agent in one focused session</critical>
|
||||
<critical>⚠️ EPIC STRUCTURE PRINCIPLE: Each epic MUST deliver USER VALUE, not just technical capability. Epics are NOT organized by technical layers (database, API, frontend). Each epic should result in something USERS can actually use or benefit from. Exception: Foundation/setup stories at the start of first epic are acceptable. Another valid exception: API-first epic ONLY when the API itself has standalone value (e.g., will be consumed by third parties or multiple frontends).</critical>
|
||||
<critical>BMAD METHOD WORKFLOW POSITION: This workflow can be invoked at multiple points - after PRD only, after PRD+UX, after PRD+UX+Architecture, or to update existing epics. If epics.md already exists, ASK the user: (1) CONTINUING - previous run was incomplete, (2) REPLACING - starting fresh/discarding old, (3) UPDATING - new planning document created since last epic generation</critical>
|
||||
<critical>This is a LIVING DOCUMENT that evolves through the BMad Method workflow chain</critical>
|
||||
<critical>Phase 4 Implementation pulls context from: PRD + epics.md + UX + Architecture</critical>
|
||||
<critical>Communicate all responses in {communication_language} and adapt 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>
|
||||
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
|
||||
<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
|
||||
<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Detect workflow mode and available context">
|
||||
<action>Determine if this is initial creation or update mode
|
||||
|
||||
**Check for existing epics.md:**
|
||||
</action>
|
||||
|
||||
<action>Check if {default_output_file} exists (epics.md)</action>
|
||||
|
||||
<check if="epics.md exists">
|
||||
<action>Load existing epics.md completely</action>
|
||||
<action>Extract existing:
|
||||
- Epic structure and titles
|
||||
- Story breakdown
|
||||
- FR coverage mapping
|
||||
- Existing acceptance criteria
|
||||
</action>
|
||||
|
||||
<output>📝 **Existing epics.md found!**
|
||||
|
||||
Current structure:
|
||||
|
||||
- {{epic_count}} epics defined
|
||||
- {{story_count}} total stories
|
||||
</output>
|
||||
|
||||
<ask>What would you like to do?
|
||||
|
||||
1. **CONTINUING** - Previous run was incomplete, continue where we left off
|
||||
2. **REPLACING** - Start fresh, discard existing epic structure
|
||||
3. **UPDATING** - New planning document created (UX/Architecture), enhance existing epics
|
||||
|
||||
Enter your choice (1-3):</ask>
|
||||
|
||||
<action>Set mode based on user choice:
|
||||
|
||||
- Choice 1: mode = "CONTINUE" (resume incomplete work)
|
||||
- Choice 2: mode = "CREATE" (start fresh, ignore existing)
|
||||
- Choice 3: mode = "UPDATE" (enhance with new context)
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="epics.md does not exist">
|
||||
<action>Set mode = "CREATE"</action>
|
||||
<output>🆕 **INITIAL CREATION MODE**
|
||||
|
||||
No existing epics found - I'll create the initial epic breakdown.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<action>**Detect available context documents:**</action>
|
||||
|
||||
<action>Check which documents exist:
|
||||
|
||||
- UX Design specification ({ux_design_content})
|
||||
- Architecture document ({architecture_content})
|
||||
- Domain brief ({domain_brief_content})
|
||||
- Product brief ({product_brief_content})
|
||||
</action>
|
||||
|
||||
<check if="mode == 'UPDATE'">
|
||||
<action>Identify what's NEW since last epic update:
|
||||
|
||||
- If UX exists AND not previously incorporated:
|
||||
- Flag: "ADD_UX_DETAILS = true"
|
||||
- Note UX sections to extract (interaction patterns, mockup references, responsive breakpoints)
|
||||
|
||||
- If Architecture exists AND not previously incorporated:
|
||||
- Flag: "ADD_ARCH_DETAILS = true"
|
||||
- Note Architecture sections to extract (tech stack, API contracts, data models)
|
||||
</action>
|
||||
|
||||
<output>**Context Analysis:**
|
||||
{{if ADD_UX_DETAILS}}
|
||||
✅ UX Design found - will add interaction details to stories
|
||||
{{/if}}
|
||||
{{if ADD_ARCH_DETAILS}}
|
||||
✅ Architecture found - will add technical implementation notes
|
||||
{{/if}}
|
||||
{{if !ADD_UX_DETAILS && !ADD_ARCH_DETAILS}}
|
||||
⚠️ No new context documents found - reviewing for any PRD changes
|
||||
{{/if}}
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="mode == 'CREATE'">
|
||||
<output>**Available Context:**
|
||||
- ✅ PRD (required)
|
||||
{{if ux_design_content}}
|
||||
- ✅ UX Design (will incorporate interaction patterns)
|
||||
{{/if}}
|
||||
{{if architecture_content}}
|
||||
- ✅ Architecture (will incorporate technical decisions)
|
||||
{{/if}}
|
||||
{{if !ux_design_content && !architecture_content}}
|
||||
- ℹ️ Creating basic epic structure (can be enhanced later with UX/Architecture)
|
||||
{{/if}}
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<template-output>workflow_mode</template-output>
|
||||
<template-output>available_context</template-output>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load PRD and extract requirements">
|
||||
<action>
|
||||
<check if="mode == 'CREATE'">
|
||||
Welcome {user_name} to epic and story planning
|
||||
</check>
|
||||
<check if="mode == 'UPDATE'">
|
||||
Welcome back {user_name} - let's enhance your epic breakdown with new context
|
||||
</check>
|
||||
|
||||
Load required documents (fuzzy match, handle both whole and sharded):
|
||||
|
||||
- PRD.md (required)
|
||||
- domain-brief.md (if exists)
|
||||
- product-brief.md (if exists)
|
||||
|
||||
**CRITICAL - PRD FRs Are Now Flat and Strategic:**
|
||||
|
||||
The PRD contains FLAT, capability-level functional requirements (FR1, FR2, FR3...).
|
||||
These are STRATEGIC (WHAT capabilities exist), NOT tactical (HOW they're implemented).
|
||||
|
||||
Example PRD FRs:
|
||||
|
||||
- FR1: Users can create accounts with email or social authentication
|
||||
- FR2: Users can log in securely and maintain sessions
|
||||
- FR6: Users can create, edit, and delete content items
|
||||
|
||||
**Your job in THIS workflow:**
|
||||
|
||||
1. Map each FR to one or more epics
|
||||
2. Break each FR into stories with DETAILED acceptance criteria
|
||||
3. Add ALL the implementation details that were intentionally left out of PRD
|
||||
|
||||
Extract from PRD:
|
||||
|
||||
- ALL functional requirements (flat numbered list)
|
||||
- Non-functional requirements
|
||||
- Domain considerations and compliance needs
|
||||
- Project type and complexity
|
||||
- MVP vs growth vs vision scope boundaries
|
||||
- Product differentiator (what makes it special)
|
||||
- Technical constraints
|
||||
- User types and their goals
|
||||
- Success criteria
|
||||
|
||||
**Create FR Inventory:**
|
||||
|
||||
List all FRs to ensure coverage:
|
||||
|
||||
- FR1: [description]
|
||||
- FR2: [description]
|
||||
- ...
|
||||
- FRN: [description]
|
||||
|
||||
This inventory will be used to validate complete coverage in Step 4.
|
||||
</action>
|
||||
|
||||
<template-output>fr_inventory</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Propose epic structure from natural groupings">
|
||||
|
||||
<check if="mode == 'UPDATE'">
|
||||
<action>**MAINTAIN existing epic structure:**
|
||||
|
||||
Use the epic structure already defined in epics.md:
|
||||
|
||||
- Keep all existing epic titles and goals
|
||||
- Preserve epic sequencing
|
||||
- Maintain FR coverage mapping
|
||||
|
||||
Note: We're enhancing stories within existing epics, not restructuring.
|
||||
</action>
|
||||
|
||||
<output>**Using existing epic structure:**
|
||||
{{list_existing_epics_with_titles}}
|
||||
|
||||
Will enhance stories within these epics using new context.
|
||||
</output>
|
||||
|
||||
<template-output>epics_summary</template-output>
|
||||
<template-output>fr_coverage_map</template-output>
|
||||
|
||||
<goto step="3">Skip to story enhancement</goto>
|
||||
</check>
|
||||
|
||||
<check if="mode == 'CREATE'">
|
||||
<action>Analyze requirements and identify natural epic boundaries
|
||||
|
||||
INTENT: Find organic groupings that make sense for THIS product
|
||||
|
||||
Look for natural patterns:
|
||||
|
||||
- Features that work together cohesively
|
||||
- User journeys that connect
|
||||
- Business capabilities that cluster
|
||||
- Domain requirements that relate (compliance, validation, security)
|
||||
- Technical systems that should be built together
|
||||
|
||||
Name epics based on VALUE, not technical layers:
|
||||
|
||||
- Good: "User Onboarding", "Content Discovery", "Compliance Framework"
|
||||
- Avoid: "Database Layer", "API Endpoints", "Frontend"
|
||||
|
||||
**⚠️ ANTI-PATTERN EXAMPLES (DO NOT DO THIS):**
|
||||
|
||||
❌ **WRONG - Technical Layer Breakdown:**
|
||||
|
||||
- Epic 1: Database Schema & Models
|
||||
- Epic 2: API Layer / Backend Services
|
||||
- Epic 3: Frontend UI Components
|
||||
- Epic 4: Integration & Testing
|
||||
|
||||
WHY IT'S WRONG: User gets ZERO value until ALL epics complete. No incremental delivery.
|
||||
|
||||
✅ **CORRECT - User Value Breakdown:**
|
||||
|
||||
- Epic 1: Foundation (project setup - necessary exception)
|
||||
- Epic 2: User Authentication (user can register/login - VALUE DELIVERED)
|
||||
- Epic 3: Content Management (user can create/edit content - VALUE DELIVERED)
|
||||
- Epic 4: Social Features (user can share/interact - VALUE DELIVERED)
|
||||
|
||||
WHY IT'S RIGHT: Each epic delivers something users can USE. Incremental value.
|
||||
|
||||
**Valid Exceptions:**
|
||||
|
||||
1. **Foundation Epic**: First epic CAN be setup/infrastructure (greenfield projects need this)
|
||||
2. **API-First Epic**: ONLY valid if the API has standalone value (third-party consumers, multiple frontends, API-as-product). If it's just "backend for our frontend", that's the WRONG pattern.
|
||||
|
||||
Each epic should:
|
||||
|
||||
- Have clear business goal and user value
|
||||
- Be independently valuable
|
||||
- Contain 3-8 related capabilities
|
||||
- Be deliverable in cohesive phase
|
||||
|
||||
For greenfield projects:
|
||||
|
||||
- First epic MUST establish foundation (project setup, core infrastructure, deployment pipeline)
|
||||
- Foundation enables all subsequent work
|
||||
|
||||
For complex domains:
|
||||
|
||||
- Consider dedicated compliance/regulatory epics
|
||||
- Group validation and safety requirements logically
|
||||
- Note expertise requirements
|
||||
|
||||
Present proposed epic structure showing:
|
||||
|
||||
- Epic titles with clear value statements
|
||||
- High-level scope of each epic
|
||||
- **FR COVERAGE MAP: Which FRs does each epic address?**
|
||||
- Example: "Epic 1 (Foundation): Covers infrastructure needs for all FRs"
|
||||
- Example: "Epic 2 (User Management): FR1, FR2, FR3, FR4, FR5"
|
||||
- Example: "Epic 3 (Content System): FR6, FR7, FR8, FR9"
|
||||
- Suggested sequencing
|
||||
- Why this grouping makes sense
|
||||
|
||||
**Validate FR Coverage:**
|
||||
|
||||
Check that EVERY FR from Step 1 inventory is mapped to at least one epic.
|
||||
If any FRs are unmapped, add them now or explain why they're deferred.
|
||||
</action>
|
||||
|
||||
<template-output>epics_summary</template-output>
|
||||
<template-output>fr_coverage_map</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Decompose each epic into bite-sized stories with DETAILED AC" repeat="for-each-epic">
|
||||
|
||||
<check if="mode == 'UPDATE'">
|
||||
<action>**ENHANCE Epic {{N}} stories with new context:**
|
||||
|
||||
For each existing story in Epic {{N}}:
|
||||
|
||||
1. Preserve core story structure (title, user story statement)
|
||||
2. Add/enhance based on available NEW context:
|
||||
|
||||
<check if="ADD_UX_DETAILS">
|
||||
**Add from UX Design:**
|
||||
- Specific mockup/wireframe references
|
||||
- Exact interaction patterns
|
||||
- Animation/transition specifications
|
||||
- Responsive breakpoints
|
||||
- Component specifications
|
||||
- Error states and feedback patterns
|
||||
- Accessibility requirements (WCAG compliance)
|
||||
|
||||
Example enhancement:
|
||||
BEFORE: "User can log in"
|
||||
AFTER: "User can log in via modal (UX pg 12-15) with email/password fields,
|
||||
password visibility toggle, remember me checkbox,
|
||||
loading state during auth (spinner overlay),
|
||||
error messages below fields (red, 14px),
|
||||
success redirects to dashboard with fade transition"
|
||||
|
||||
</check>
|
||||
|
||||
<check if="ADD_ARCH_DETAILS">
|
||||
**Add from Architecture:**
|
||||
- Specific API endpoints and contracts
|
||||
- Data model references
|
||||
- Tech stack implementation details
|
||||
- Performance requirements
|
||||
- Security implementation notes
|
||||
- Cache strategies
|
||||
- Error handling patterns
|
||||
|
||||
Example enhancement:
|
||||
BEFORE: "System authenticates user"
|
||||
AFTER: "System authenticates user via POST /api/v1/auth/login,
|
||||
validates against users table (see Arch section 6.2),
|
||||
returns JWT token (expires 7d) + refresh token (30d),
|
||||
rate limited to 5 attempts/hour/IP,
|
||||
logs failures to security_events table"
|
||||
|
||||
</check>
|
||||
|
||||
3. Update acceptance criteria with new details
|
||||
4. Preserve existing prerequisites
|
||||
5. Enhance technical notes with new context
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="mode == 'CREATE'">
|
||||
<action>Break down Epic {{N}} into small, implementable stories
|
||||
|
||||
INTENT: Create stories sized for single dev agent completion
|
||||
|
||||
**CRITICAL - ALTITUDE SHIFT FROM PRD:**
|
||||
|
||||
PRD FRs are STRATEGIC (WHAT capabilities):
|
||||
|
||||
- ✅ "Users can create accounts"
|
||||
|
||||
Epic Stories are TACTICAL (HOW it's implemented):
|
||||
|
||||
- Email field with RFC 5322 validation
|
||||
- Password requirements: 8+ chars, 1 uppercase, 1 number, 1 special
|
||||
- Password strength meter with visual feedback
|
||||
- Email verification within 15 minutes
|
||||
- reCAPTCHA v3 integration
|
||||
- Account creation completes in < 2 seconds
|
||||
- Mobile responsive with 44x44px touch targets
|
||||
- WCAG 2.1 AA compliant
|
||||
|
||||
**THIS IS WHERE YOU ADD ALL THE DETAILS LEFT OUT OF PRD:**
|
||||
|
||||
- UI specifics (exact field counts, validation rules, layout details)
|
||||
- Performance targets (< 2s, 60fps, etc.)
|
||||
- Technical implementation hints (libraries, patterns, APIs)
|
||||
- Edge cases (what happens when...)
|
||||
- Validation rules (regex patterns, constraints)
|
||||
- Error handling (specific error messages, retry logic)
|
||||
- Accessibility requirements (ARIA labels, keyboard nav, screen readers)
|
||||
- Platform specifics (mobile responsive, browser support)
|
||||
|
||||
For each epic, generate:
|
||||
|
||||
- Epic title as `epic_title_{{N}}`
|
||||
- Epic goal/value as `epic_goal_{{N}}`
|
||||
- All stories as repeated pattern `story_title_{{N}}_{{M}}` for each story M
|
||||
|
||||
CRITICAL for Epic 1 (Foundation):
|
||||
|
||||
- Story 1.1 MUST be project setup/infrastructure initialization
|
||||
- Sets up: repo structure, build system, deployment pipeline basics, core dependencies
|
||||
- Creates foundation for all subsequent stories
|
||||
- Note: Architecture workflow will flesh out technical details
|
||||
|
||||
Each story should follow BDD-style acceptance criteria:
|
||||
|
||||
**Story Pattern:**
|
||||
As a [user type],
|
||||
I want [specific capability],
|
||||
So that [clear value/benefit].
|
||||
|
||||
**Acceptance Criteria using BDD:**
|
||||
Given [precondition or initial state]
|
||||
When [action or trigger]
|
||||
Then [expected outcome]
|
||||
|
||||
And [additional criteria as needed]
|
||||
|
||||
**Prerequisites:** Only previous stories (never forward dependencies)
|
||||
|
||||
**Technical Notes:** Implementation guidance, affected components, compliance requirements
|
||||
|
||||
Ensure stories are:
|
||||
|
||||
- Vertically sliced (deliver complete functionality, not just one layer)
|
||||
- Sequentially ordered (logical progression, no forward dependencies)
|
||||
- Independently valuable when possible
|
||||
- Small enough for single-session completion
|
||||
- Clear enough for autonomous implementation
|
||||
|
||||
For each story in epic {{N}}, output variables following this pattern:
|
||||
|
||||
- story*title*{{N}}_1, story_title_{{N}}\*2, etc.
|
||||
- Each containing: user story, BDD acceptance criteria, prerequisites, technical notes</action>
|
||||
|
||||
<template-output>epic*title*{{N}}</template-output>
|
||||
<template-output>epic*goal*{{N}}</template-output>
|
||||
|
||||
<action>For each story M in epic {{N}}, generate story content</action>
|
||||
<template-output>story-title-{{N}}-{{M}}</template-output>
|
||||
</check>
|
||||
|
||||
<action>**EPIC {{N}} REVIEW - Present for Checkpoint:**
|
||||
|
||||
Summarize the COMPLETE epic breakdown:
|
||||
|
||||
**Epic {{N}}: {{epic_title}}**
|
||||
Goal: {{epic_goal}}
|
||||
|
||||
Stories ({{count}} total):
|
||||
{{for each story, show:}}
|
||||
|
||||
- Story {{N}}.{{M}}: {{story_title}}
|
||||
- User Story: As a... I want... So that...
|
||||
- Acceptance Criteria: (BDD format summary)
|
||||
- Prerequisites: {{list}}
|
||||
|
||||
**Review Questions to Consider:**
|
||||
|
||||
- Is the story sequence logical?
|
||||
- Are acceptance criteria clear and testable?
|
||||
- Are there any missing stories for the FRs this epic covers?
|
||||
- Are the stories sized appropriately (single dev agent session)?
|
||||
- FRs covered by this epic: {{FR_list}}
|
||||
|
||||
**NOTE:** At the checkpoint prompt, select [a] for Advanced Elicitation if you want to refine stories, add missing ones, or reorder. Select [c] to approve this epic and continue to the next one.
|
||||
</action>
|
||||
|
||||
<template-output>epic\_{{N}}\_complete_breakdown</template-output>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Review epic breakdown and completion">
|
||||
|
||||
<check if="mode == 'UPDATE'">
|
||||
<action>Review the ENHANCED epic breakdown for completeness
|
||||
|
||||
**Validate Enhancements:**
|
||||
|
||||
- All stories now have context-appropriate details
|
||||
- UX references added where applicable
|
||||
- Architecture decisions incorporated where applicable
|
||||
- Acceptance criteria updated with new specifics
|
||||
- Technical notes enhanced with implementation details
|
||||
|
||||
**Quality Check:**
|
||||
|
||||
- Stories remain bite-sized for single dev agent sessions
|
||||
- No forward dependencies introduced
|
||||
- All new context properly integrated
|
||||
</action>
|
||||
|
||||
<template-output>epic_breakdown_summary</template-output>
|
||||
<template-output>enhancement_summary</template-output>
|
||||
|
||||
<output>✅ **Epic Enhancement Complete!**
|
||||
|
||||
**Updated:** epics.md with enhanced context
|
||||
|
||||
**Enhancements Applied:**
|
||||
{{if ADD_UX_DETAILS}}
|
||||
|
||||
- ✅ UX interaction patterns and mockup references added
|
||||
{{/if}}
|
||||
{{if ADD_ARCH_DETAILS}}
|
||||
- ✅ Architecture technical decisions and API contracts added
|
||||
{{/if}}
|
||||
|
||||
The epic breakdown now includes all available context for Phase 4 implementation.
|
||||
|
||||
**Next Steps:**
|
||||
{{if !architecture_content}}
|
||||
|
||||
- Run Architecture workflow for technical decisions
|
||||
{{/if}}
|
||||
{{if architecture_content}}
|
||||
- Ready for Phase 4: Sprint Planning
|
||||
{{/if}}
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="mode == 'CREATE'">
|
||||
<action>Review the complete epic breakdown for quality and completeness
|
||||
|
||||
**Validate Epic Structure (USER VALUE CHECK):**
|
||||
|
||||
For each epic, answer: "What can USERS do after this epic is complete that they couldn't do before?"
|
||||
|
||||
- Epic 1: [Must have clear user value OR be Foundation exception]
|
||||
- Epic 2: [Must deliver user-facing capability]
|
||||
- Epic N: [Must deliver user-facing capability]
|
||||
|
||||
⚠️ RED FLAG: If an epic only delivers technical infrastructure (database layer, API without users, component library without features), RESTRUCTURE IT. Each epic should enable users to accomplish something.
|
||||
|
||||
Exception validation:
|
||||
|
||||
- Foundation epic: Acceptable as first epic for greenfield projects
|
||||
- API-first epic: Acceptable ONLY if API has standalone consumers (third-party integrations, multiple frontends, API-as-product)
|
||||
|
||||
If any epic fails this check, restructure before proceeding.
|
||||
|
||||
**Validate FR Coverage:**
|
||||
|
||||
Create FR Coverage Matrix showing each FR mapped to epic(s) and story(ies):
|
||||
|
||||
- FR1: [description] → Epic X, Story X.Y
|
||||
- FR2: [description] → Epic X, Story X.Z
|
||||
- FR3: [description] → Epic Y, Story Y.A
|
||||
- ...
|
||||
- FRN: [description] → Epic Z, Story Z.B
|
||||
|
||||
Confirm: EVERY FR from Step 1 inventory is covered by at least one story.
|
||||
If any FRs are missing, add stories now.
|
||||
|
||||
**Validate Story Quality:**
|
||||
|
||||
- All functional requirements from PRD are covered by stories
|
||||
- Epic 1 establishes proper foundation (if greenfield)
|
||||
- All stories are vertically sliced (deliver complete functionality, not just one layer)
|
||||
- No forward dependencies exist (only backward references)
|
||||
- Story sizing is appropriate for single-session completion
|
||||
- BDD acceptance criteria are clear and testable
|
||||
- Details added (what was missing from PRD FRs: UI specifics, performance targets, etc.)
|
||||
- Domain/compliance requirements are properly distributed
|
||||
- Sequencing enables incremental value delivery
|
||||
|
||||
Confirm with {user_name}:
|
||||
|
||||
- Epic structure makes sense
|
||||
- All FRs covered by stories (validated via coverage matrix)
|
||||
- Story breakdown is actionable
|
||||
<check if="ux_design_content && architecture_content">
|
||||
- All available context has been incorporated (PRD + UX + Architecture)
|
||||
- Ready for Phase 4 Implementation
|
||||
</check>
|
||||
<check if="ux_design_content && !architecture_content">
|
||||
- UX context has been incorporated
|
||||
- Ready for Architecture workflow (recommended next step)
|
||||
</check>
|
||||
<check if="!ux_design_content && architecture_content">
|
||||
- Architecture context has been incorporated
|
||||
- Consider running UX Design workflow if UI exists
|
||||
</check>
|
||||
<check if="!ux_design_content && !architecture_content">
|
||||
- Basic epic structure created from PRD
|
||||
- Ready for next planning phase (UX Design or Architecture)
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<template-output>epic_breakdown_summary</template-output>
|
||||
<template-output>fr_coverage_matrix</template-output>
|
||||
|
||||
<check if="mode == 'CREATE'">
|
||||
<output>**✅ Epic Breakdown Complete**
|
||||
|
||||
**Created:** epics.md with epic and story breakdown
|
||||
|
||||
**FR Coverage:** All functional requirements from PRD mapped to stories
|
||||
|
||||
**Context Incorporated:**
|
||||
{{if ux_design_content && architecture_content}}
|
||||
|
||||
- ✅ PRD requirements
|
||||
- ✅ UX interaction patterns
|
||||
- ✅ Architecture technical decisions
|
||||
**Status:** COMPLETE - Ready for Phase 4 Implementation!
|
||||
{{/if}}
|
||||
{{if ux_design_content && !architecture_content}}
|
||||
- ✅ PRD requirements
|
||||
- ✅ UX interaction patterns
|
||||
**Next:** Run Architecture workflow for technical decisions
|
||||
{{/if}}
|
||||
{{if !ux_design_content && architecture_content}}
|
||||
- ✅ PRD requirements
|
||||
- ✅ Architecture technical decisions
|
||||
**Next:** Consider UX Design workflow if UI needed
|
||||
{{/if}}
|
||||
{{if !ux_design_content && !architecture_content}}
|
||||
- ✅ PRD requirements (basic structure)
|
||||
**Next:** Run UX Design (if UI) or Architecture workflow
|
||||
**Note:** Epics will be enhanced with additional context later
|
||||
{{/if}}
|
||||
</output>
|
||||
</check>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
@@ -0,0 +1,53 @@
|
||||
# Epic and Story Decomposition Workflow
|
||||
name: create-epics-and-stories
|
||||
description: "Transform PRD requirements into bite-sized stories organized into deliverable functional epics. This workflow takes a Product Requirements Document (PRD) and breaks it down into epics and user stories that can be easily assigned to development teams. It ensures that all functional requirements are captured in a structured format, making it easier for teams to understand and implement the necessary features."
|
||||
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
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
input_file_patterns:
|
||||
prd:
|
||||
description: "Product Requirements Document with FRs and NFRs"
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
product_brief:
|
||||
description: "Product vision and goals (optional)"
|
||||
whole: "{output_folder}/*product*brief*.md"
|
||||
sharded: "{output_folder}/*product*brief*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
domain_brief:
|
||||
description: "Domain-specific requirements and context (optional)"
|
||||
whole: "{output_folder}/*domain*brief*.md"
|
||||
sharded: "{output_folder}/*domain*brief*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
ux_design:
|
||||
description: "UX design specification for interaction patterns (optional)"
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
architecture:
|
||||
description: "Architecture decisions and technical design (optional)"
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/.bmad/bmm/workflows/3-solutioning/create-epics-and-stories"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
template: "{installed_path}/epics-template.md"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/epics.md"
|
||||
|
||||
standalone: true
|
||||
@@ -0,0 +1,169 @@
|
||||
# Implementation Readiness Validation Checklist
|
||||
|
||||
## Document Completeness
|
||||
|
||||
### Core Planning Documents
|
||||
|
||||
- [ ] PRD exists and is complete
|
||||
- [ ] PRD contains measurable success criteria
|
||||
- [ ] PRD defines clear scope boundaries and exclusions
|
||||
- [ ] Architecture document exists (architecture\*.md)
|
||||
- [ ] 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
|
||||
|
||||
- [ ] 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
|
||||
|
||||
- [ ] 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
|
||||
|
||||
<!-- checklist of critical issues or N/A -->
|
||||
|
||||
### High Priority Issues Found
|
||||
|
||||
<!-- checklist of high priority issues or N/A -->
|
||||
|
||||
### Medium Priority Issues Found
|
||||
|
||||
<!-- checklist of medium priority issues or N/A -->
|
||||
|
||||
---
|
||||
|
||||
_Use this checklist to ensure comprehensive validation of implementation readiness_
|
||||
@@ -0,0 +1,332 @@
|
||||
# Implementation Readiness - 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/implementation-readiness/workflow.yaml</critical>
|
||||
<critical>Communicate all findings and analysis in {communication_language} throughout the assessment</critical>
|
||||
<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
|
||||
<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
|
||||
<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="0" goal="Validate workflow readiness" tag="workflow-status">
|
||||
<action>Check if {workflow_status_file} exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Implementation Readiness 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: {workflow_status_file}</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "implementation-readiness" workflow</action>
|
||||
<action>Get {selected_track} (quick-flow, bmad-method, or enterprise-bmad-method)</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<action>Based on the selected_track, understand what artifacts should exist: - quick-flow: Tech spec and simple stories in an epic only (no PRD, minimal solutioning) - bmad-method and enterprise-bmad-method: PRD, UX design, epics/stories, architecture</action>
|
||||
|
||||
<check if="implementation-readiness status is file path (already completed)">
|
||||
<output>⚠️ Implementation readiness check already completed: {{implementation-readiness 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="implementation-readiness is not the next expected workflow">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Implementation readiness check is out of sequence.</output>
|
||||
<ask>Continue with readiness 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>
|
||||
|
||||
<template-output>project_context</template-output>
|
||||
</step>
|
||||
|
||||
<step n="0.5" goal="Discover and load input documents">
|
||||
<invoke-protocol name="discover_inputs" />
|
||||
<note>After discovery, these content variables are available: {prd_content}, {epics_content}, {architecture_content}, {ux_design_content}, {tech_spec_content}, {document_project_content}</note>
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Inventory loaded project artifacts">
|
||||
<action>Review the content loaded by Step 0.5 and create an inventory</action>
|
||||
|
||||
<action>Inventory of available documents:
|
||||
|
||||
- PRD: {prd_content} (loaded if available)
|
||||
- Architecture: {architecture_content} (loaded if available)
|
||||
- Epics: {epics_content} (loaded if available)
|
||||
- UX Design: {ux_design_content} (loaded if available)
|
||||
- Tech Spec: {tech_spec_content} (loaded if available, Quick Flow track)
|
||||
- Brownfield docs: {document_project_content} (loaded via INDEX_GUIDED if available)
|
||||
</action>
|
||||
|
||||
<action>For each loaded document, extract:
|
||||
|
||||
- Document type and purpose
|
||||
- Brief description of what it contains
|
||||
- Flag any expected documents that are missing as potential issues
|
||||
</action>
|
||||
|
||||
<template-output>document_inventory</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Deep analysis of core planning documents">
|
||||
<action>Thoroughly analyze each loaded 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, 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>PRD ↔ Architecture Alignment:
|
||||
|
||||
- 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:
|
||||
|
||||
- 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>
|
||||
|
||||
<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>
|
||||
|
||||
<action>Check Testability Review (if test-design exists in Phase 3):
|
||||
|
||||
**Note:** test-design is recommended for BMad Method, required for Enterprise Method
|
||||
|
||||
- Check if {output_folder}/test-design-system.md exists
|
||||
- If exists: Review testability assessment (Controllability, Observability, Reliability)
|
||||
- If testability concerns documented: Flag for gate decision
|
||||
- If missing AND track is Enterprise: Flag as CRITICAL gap
|
||||
- If missing AND track is Method: Note as recommendation (not blocker)
|
||||
</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: {workflow_status_file}</action>
|
||||
<action>Find workflow_status key "implementation-readiness"</action>
|
||||
<critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
|
||||
<action>Update workflow_status["implementation-readiness"] = "{output_folder}/implementation-readiness-report-{{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>
|
||||
|
||||
<action>Determine overall readiness status from the readiness_assessment (Ready, Ready with Conditions, or Not Ready)</action>
|
||||
|
||||
<output>**✅ Implementation Readiness Check Complete!**
|
||||
|
||||
**Assessment Report:**
|
||||
|
||||
- Readiness assessment saved to: {output_folder}/implementation-readiness-report-{{date}}.md
|
||||
|
||||
{{#if standalone_mode != true}}
|
||||
**Status Updated:**
|
||||
|
||||
- Progress tracking updated: implementation-readiness 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>
|
||||
|
||||
<check if="overall readiness status is Ready OR Ready with Conditions">
|
||||
<output>**🚀 Ready for Implementation!**
|
||||
|
||||
Your project artifacts are aligned and complete. You can now proceed to Phase 4: Implementation.
|
||||
</output>
|
||||
|
||||
<ask>Would you like to run the **sprint-planning** workflow to initialize your sprint tracking and prepare for development? (yes/no)</ask>
|
||||
|
||||
<check if="yes">
|
||||
<action>Inform user that sprint-planning workflow will be invoked</action>
|
||||
<invoke-workflow path="{project-root}/.bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml" />
|
||||
</check>
|
||||
<check if="no">
|
||||
<output>You can run sprint-planning later when ready: `sprint-planning`</output>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="overall readiness status is Not Ready">
|
||||
<output>**⚠️ Not Ready for Implementation**
|
||||
|
||||
Critical issues must be resolved before proceeding. Review the assessment report and address the identified gaps.
|
||||
|
||||
Once issues are resolved, re-run implementation-readiness to validate again.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<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 Readiness workflow (v6-alpha)_
|
||||
@@ -0,0 +1,62 @@
|
||||
# Implementation Readiness - Workflow Configuration
|
||||
name: implementation-readiness
|
||||
description: "Validate that PRD, UX Design, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation. Ensures all artifacts cover the MVP requirements with no gaps or contradictions."
|
||||
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"
|
||||
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"
|
||||
workflow_status_file: "{output_folder}/bmm-workflow-status.yaml"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/.bmad/bmm/workflows/3-solutioning/implementation-readiness"
|
||||
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"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
# Priority: Whole document first, then sharded version
|
||||
# Strategy: How to load sharded documents (FULL_LOAD, SELECTIVE_LOAD, INDEX_GUIDED)
|
||||
input_file_patterns:
|
||||
prd:
|
||||
description: "Product Requirements with FRs and NFRs"
|
||||
whole: "{output_folder}/*prd*.md"
|
||||
sharded: "{output_folder}/*prd*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
epics:
|
||||
description: "Epic breakdown with user stories"
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
architecture:
|
||||
description: "System architecture with decisions and patterns"
|
||||
whole: "{output_folder}/*architecture*.md"
|
||||
sharded: "{output_folder}/*architecture*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
ux_design:
|
||||
description: "UX design specification (if UI components)"
|
||||
whole: "{output_folder}/*ux*.md"
|
||||
sharded: "{output_folder}/*ux*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
tech_spec:
|
||||
description: "Technical specification (for Quick Flow track)"
|
||||
whole: "{output_folder}/*tech-spec*.md"
|
||||
sharded: "{output_folder}/*tech-spec*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
document_project:
|
||||
description: "Brownfield project documentation (optional)"
|
||||
sharded: "{output_folder}/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
|
||||
standalone: true
|
||||
Reference in New Issue
Block a user