mirror of
https://github.com/R0m1k3/xtremflow.git
synced 2026-10-21 22:18:04 +02:00
feat: security overhaul (proxy ssrf fix, streaming sanitization, docker optimization)
This commit is contained in:
Michael committed
1 parent
6d87ada2b8
commit
8df9a37baa
810 files changed
+131090
-151
No files matched your search
@@ -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,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
|
||||
|
||||
{ list issues }
|
||||
|
||||
### Recommended Actions Before Implementation
|
||||
|
||||
{ list actions }
|
||||
|
||||
---
|
||||
|
||||
**Next Step**: Run the **implementation-readiness** workflow to validate alignment between PRD, 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,701 @@
|
||||
# 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}/bmgd-workflow-status.yaml exists</action>
|
||||
|
||||
<check if="status file not found">
|
||||
<output>No workflow status file found. Decision Architecture can run standalone or as part of BMM workflow path.</output>
|
||||
<output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
|
||||
<ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
|
||||
<check if="continue">
|
||||
<action>Set standalone_mode = true</action>
|
||||
</check>
|
||||
<check if="exit">
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="status file found">
|
||||
<action>Load the FULL file: {output_folder}/bmgd-workflow-status.yaml</action>
|
||||
<action>Parse workflow_status section</action>
|
||||
<action>Check status of "create-architecture" workflow</action>
|
||||
<action>Get project_level from YAML metadata</action>
|
||||
<action>Find first non-completed workflow (next expected workflow)</action>
|
||||
|
||||
<check if="project_level < 3">
|
||||
<output>**Note: Level {{project_level}} Project**
|
||||
|
||||
The Detailed Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning.
|
||||
|
||||
For Level {{project_level}}, we'll keep the architecture appropriately scoped.
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="create-architecture status is file path (already completed)">
|
||||
<output>⚠️ Architecture already completed: {{create-architecture status}}</output>
|
||||
<ask>Re-running will overwrite the existing architecture. Continue? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Use workflow-status to see your next step.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<check if="create-architecture is not the next expected workflow">
|
||||
<output>⚠️ Next expected workflow: {{next_workflow}}. Architecture is out of sequence.</output>
|
||||
<ask>Continue with Architecture anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<output>Exiting. Run {{next_workflow}} instead.</output>
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Set standalone_mode = false</action>
|
||||
</check>
|
||||
|
||||
<action>Check for existing PRD and epics files using fuzzy matching</action>
|
||||
|
||||
<action>Fuzzy match PRD file: {prd_file}</action>
|
||||
<check if="PRD_not_found">
|
||||
<output>**PRD Not Found**
|
||||
|
||||
Decision Architecture works from your Product Requirements Document (PRD).
|
||||
|
||||
Looking for: `*prd*.md`, or `prd/index.md` + files in {output_folder}
|
||||
|
||||
Please run the PRD workflow first to define your requirements.
|
||||
|
||||
Architect: `create-prd`
|
||||
</output>
|
||||
<action>Exit workflow - PRD required</action>
|
||||
</check>
|
||||
|
||||
</step>
|
||||
|
||||
<step n="1" goal="Load and understand project context">
|
||||
<action>Load the PRD using fuzzy matching: {prd_file}, if the PRD is mulitple files in a folder, load the index file and all files associated with the PRD</action>
|
||||
<action>Load epics file using fuzzy matching: {epics_file}</action>
|
||||
|
||||
<action>Check for UX specification using fuzzy matching:
|
||||
<action>Attempt to locate: {ux_spec_file}</action>
|
||||
<check if="ux_spec_found">
|
||||
<action>Load UX spec and extract architectural implications: - Component complexity (simple forms vs rich interactions) - Animation/transition requirements - Real-time update needs (live data, collaborative features) - Platform-specific UI requirements - Accessibility standards (WCAG compliance level) - Responsive design breakpoints - Offline capability requirements - Performance expectations (load times, interaction responsiveness)
|
||||
</action>
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned
|
||||
</action>
|
||||
|
||||
<action>Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) - Novel features
|
||||
</action>
|
||||
|
||||
<action>Reflect understanding back to {user_name}:
|
||||
"I'm reviewing your project documentation for {{project_name}}.
|
||||
I see {{epic_count}} epics with {{story_count}} total stories.
|
||||
{{if_ux_spec}}I also found your UX specification which defines the user experience requirements.{{/if_ux_spec}}
|
||||
|
||||
Key aspects I notice:
|
||||
- [Summarize core functionality]
|
||||
- [Note critical NFRs]
|
||||
{{if_ux_spec}}- [Note UX complexity and requirements]{{/if_ux_spec}}
|
||||
- [Identify unique challenges]
|
||||
|
||||
This will help me guide you through the architectural decisions needed
|
||||
to ensure AI agents implement this consistently."
|
||||
|
||||
</action>
|
||||
|
||||
<ask>Does this match your understanding of the project?</ask>
|
||||
<template-output>project_context_understanding</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Discover and evaluate starter templates">
|
||||
<critical>Modern starter templates make many good architectural decisions by default</critical>
|
||||
|
||||
<action>Based on PRD analysis, identify the primary technology domain: - Web application → Look for Next.js, Vite, Remix starters - Mobile app → Look for React Native, Expo, Flutter starters - API/Backend → Look for NestJS, Express, Fastify starters - CLI tool → Look for CLI framework starters - Full-stack → Look for T3, RedwoodJS, Blitz starters
|
||||
</action>
|
||||
|
||||
<check if="ux_spec_loaded">
|
||||
<action>Consider UX requirements when selecting starter:
|
||||
- Rich animations → Framer Motion compatible starter
|
||||
- Complex forms → React Hook Form included starter
|
||||
- Real-time features → Socket.io or WebSocket ready starter
|
||||
- Accessibility focus → WCAG-compliant component library starter
|
||||
- Design system → Storybook-enabled starter
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>Search for relevant starter templates with websearch, examples:
|
||||
Search the web: "{{primary_technology}} starter template CLI create command latest"
|
||||
Search the web: "{{primary_technology}} boilerplate generator latest options"
|
||||
</action>
|
||||
|
||||
<check if="starter_templates_found">
|
||||
<action>Investigate what each starter provides:
|
||||
Search the web: "{{starter_name}} default setup technologies included latest"
|
||||
Search the web: "{{starter_name}} project structure file organization"
|
||||
</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:
|
||||
Search the web: "{{starter_name}} CLI command options flags latest"
|
||||
</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 search the web to verify current versions - 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:
|
||||
Search the web: "{{technology}} latest stable version"
|
||||
Search the web: "{{technology}} current LTS version"
|
||||
</action>
|
||||
|
||||
<action>Update decision record with verified version:
|
||||
Technology: {{technology}}
|
||||
Verified Version: {{version_from_search}}
|
||||
Verification Date: {{today}}
|
||||
</action>
|
||||
|
||||
</check>
|
||||
|
||||
<ask>What's your preference? (or 'explain more' for details)</ask>
|
||||
|
||||
<check if="user_wants_more_info">
|
||||
<action>Provide deeper explanation appropriate to skill level</action>
|
||||
<check if="complex_tradeoffs">
|
||||
<action>Consider using advanced elicitation:
|
||||
"Would you like to explore innovative approaches to this decision?
|
||||
I can help brainstorm unconventional solutions if you have specific goals."
|
||||
</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Record decision:
|
||||
Category: {{category}}
|
||||
Decision: {{user_choice}}
|
||||
Version: {{verified_version_if_applicable}}
|
||||
Affects Epics: {{list_of_affected_epics}}
|
||||
Rationale: {{user_reasoning_or_default}}
|
||||
Provided by Starter: {{yes_if_from_starter}}
|
||||
</action>
|
||||
|
||||
<action>Check for cascading implications:
|
||||
"This choice means we'll also need to {{related_decisions}}"
|
||||
</action>
|
||||
|
||||
<template-output>decision_record</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Address cross-cutting concerns">
|
||||
<critical>These decisions affect EVERY epic and story</critical>
|
||||
|
||||
<action>Facilitate decisions for consistency patterns: - Error handling strategy (How will all agents handle errors?) - Logging approach (Structured? Format? Levels?) - Date/time handling (Timezone? Format? Library?) - Authentication pattern (Where? How? Token format?) - API response format (Structure? Status codes? Errors?) - Testing strategy (Unit? Integration? E2E?)
|
||||
</action>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
<action>Explain why these matter why its critical to go through and decide these things now.</action>
|
||||
</check>
|
||||
|
||||
<template-output>cross_cutting_decisions</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Define project structure and boundaries">
|
||||
<action>Based on all decisions made, define the project structure</action>
|
||||
|
||||
<action>Create comprehensive source tree: - Root configuration files - Source code organization - Test file locations - Build/dist directories - Documentation structure
|
||||
</action>
|
||||
|
||||
<action>Map epics to architectural boundaries:
|
||||
"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
|
||||
</action>
|
||||
|
||||
<action>Define integration points: - Where do components communicate? - What are the API boundaries? - How do services interact?
|
||||
</action>
|
||||
|
||||
<template-output>project_structure</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Design novel architectural patterns" optional="true">
|
||||
<critical>Some projects require INVENTING new patterns, not just choosing existing ones</critical>
|
||||
|
||||
<action>Scan PRD for concepts that don't have standard solutions: - Novel interaction patterns (e.g., "swipe to match" before Tinder existed) - Unique multi-component workflows (e.g., "viral invitation system") - New data relationships (e.g., "social graph" before Facebook) - Unprecedented user experiences (e.g., "ephemeral messages" before Snapchat) - Complex state machines crossing multiple epics
|
||||
</action>
|
||||
|
||||
<check if="novel_patterns_detected">
|
||||
<action>For each novel pattern identified:</action>
|
||||
|
||||
<action>Engage user in design collaboration:
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"The {{pattern_name}} concept requires architectural innovation.
|
||||
|
||||
Core challenge: {{challenge_description}}
|
||||
|
||||
Let's design the component interaction model:"
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Your idea about {{pattern_name}} is unique - there isn't a standard way to build this yet!
|
||||
|
||||
This is exciting - we get to invent the architecture together.
|
||||
|
||||
Let me help you think through how this should work:"
|
||||
</check>
|
||||
</action>
|
||||
|
||||
<action>Facilitate pattern design:
|
||||
1. Identify core components involved
|
||||
2. Map data flow between components
|
||||
3. Design state management approach
|
||||
4. Create sequence diagrams for complex flows
|
||||
5. Define API contracts for the pattern
|
||||
6. Consider edge cases and failure modes
|
||||
</action>
|
||||
|
||||
<action>Use advanced elicitation for innovation:
|
||||
"What if we approached this differently?
|
||||
- What would the ideal user experience look like?
|
||||
- Are there analogies from other domains we could apply?
|
||||
- What constraints can we challenge?"
|
||||
</action>
|
||||
|
||||
<action>Document the novel pattern:
|
||||
Pattern Name: {{pattern_name}}
|
||||
Purpose: {{what_problem_it_solves}}
|
||||
Components:
|
||||
{{component_list_with_responsibilities}}
|
||||
Data Flow:
|
||||
{{sequence_description_or_diagram}}
|
||||
Implementation Guide:
|
||||
{{how_agents_should_build_this}}
|
||||
Affects Epics:
|
||||
{{epics_that_use_this_pattern}}
|
||||
</action>
|
||||
|
||||
<action>Validate pattern completeness:
|
||||
"Does this {{pattern_name}} design cover all the use cases in your epics?
|
||||
- {{use_case_1}}: ✓ Handled by {{component}}
|
||||
- {{use_case_2}}: ✓ Handled by {{component}}
|
||||
..."
|
||||
</action>
|
||||
|
||||
</check>
|
||||
|
||||
<check if="no_novel_patterns">
|
||||
<action>Note: All patterns in this project have established solutions.
|
||||
Proceeding with standard architectural patterns.</action>
|
||||
</check>
|
||||
|
||||
<template-output>novel_pattern_designs</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Define implementation patterns to prevent agent conflicts">
|
||||
<critical>These patterns ensure multiple AI agents write compatible code</critical>
|
||||
<critical>Focus on what agents could decide DIFFERENTLY if not specified</critical>
|
||||
|
||||
<action>Load pattern categories: {pattern_categories}</action>
|
||||
|
||||
<action>Based on chosen technologies, identify potential conflict points:
|
||||
"Given that we're using {{tech_stack}}, agents need consistency rules for:"
|
||||
</action>
|
||||
|
||||
<action>For each relevant pattern category, facilitate decisions:
|
||||
|
||||
NAMING PATTERNS (How things are named):
|
||||
<check if="has_api">
|
||||
- REST endpoint naming: /users or /user? Plural or singular?
|
||||
- Route parameter format: :id or {id}?
|
||||
</check>
|
||||
<check if="has_database">
|
||||
- Table naming: users or Users or user?
|
||||
- Column naming: user_id or userId?
|
||||
- Foreign key format: user_id or fk_user?
|
||||
</check>
|
||||
<check if="has_frontend">
|
||||
- Component naming: UserCard or user-card?
|
||||
- File naming: UserCard.tsx or user-card.tsx?
|
||||
</check>
|
||||
|
||||
STRUCTURE PATTERNS (How things are organized):
|
||||
- Where do tests live? __tests__/ or *.test.ts co-located?
|
||||
- How are components organized? By feature or by type?
|
||||
- Where do shared utilities go?
|
||||
|
||||
FORMAT PATTERNS (Data exchange formats):
|
||||
<check if="has_api">
|
||||
- API response wrapper? {data: ..., error: ...} or direct response?
|
||||
- Error format? {message, code} or {error: {type, detail}}?
|
||||
- Date format in JSON? ISO strings or timestamps?
|
||||
</check>
|
||||
|
||||
COMMUNICATION PATTERNS (How components interact):
|
||||
<check if="has_events">
|
||||
- Event naming convention?
|
||||
- Event payload structure?
|
||||
</check>
|
||||
<check if="has_state_management">
|
||||
- State update pattern?
|
||||
- Action naming convention?
|
||||
</check>
|
||||
|
||||
LIFECYCLE PATTERNS (State and flow):
|
||||
- How are loading states handled?
|
||||
- What's the error recovery pattern?
|
||||
- How are retries implemented?
|
||||
|
||||
LOCATION PATTERNS (Where things go):
|
||||
- API route structure?
|
||||
- Static asset organization?
|
||||
- Config file locations?
|
||||
|
||||
CONSISTENCY PATTERNS (Cross-cutting):
|
||||
- How are dates formatted in the UI?
|
||||
- What's the logging format?
|
||||
- How are user-facing errors written?
|
||||
|
||||
</action>
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
<action>Rapid-fire through patterns:
|
||||
"Quick decisions on implementation patterns:
|
||||
- {{pattern}}: {{suggested_convention}} OK? [y/n/specify]"
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
<action>Explain each pattern's importance:
|
||||
"Let me explain why this matters:
|
||||
If one AI agent names database tables 'users' and another names them 'Users',
|
||||
your app will crash. We need to pick one style and make sure everyone follows it."
|
||||
</action>
|
||||
</check>
|
||||
|
||||
<action>Document implementation patterns:
|
||||
Category: {{pattern_category}}
|
||||
Pattern: {{specific_pattern}}
|
||||
Convention: {{decided_convention}}
|
||||
Example: {{concrete_example}}
|
||||
Enforcement: "All agents MUST follow this pattern"
|
||||
</action>
|
||||
|
||||
<template-output>implementation_patterns</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Validate architectural coherence">
|
||||
<action>Run coherence checks:</action>
|
||||
|
||||
<action>Check decision compatibility: - Do all decisions work together? - Are there any conflicting choices? - Do the versions align properly?
|
||||
</action>
|
||||
|
||||
<action>Verify epic coverage: - Does every epic have architectural support? - Are all user stories implementable with these decisions? - Are there any gaps?
|
||||
</action>
|
||||
|
||||
<action>Validate pattern completeness: - Are there any patterns we missed that agents would need? - Do novel patterns integrate with standard architecture? - Are implementation patterns comprehensive enough?
|
||||
</action>
|
||||
|
||||
<check if="issues_found">
|
||||
<action>Address issues with {user_name}:
|
||||
"I notice {{issue_description}}.
|
||||
We should {{suggested_resolution}}."
|
||||
</action>
|
||||
<ask>How would you like to resolve this?</ask>
|
||||
<action>Update decisions based on resolution</action>
|
||||
</check>
|
||||
|
||||
<template-output>coherence_validation</template-output>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Generate decision architecture document">
|
||||
<critical>The document must be complete, specific, and validation-ready</critical>
|
||||
<critical>This is the consistency contract for all AI agents</critical>
|
||||
|
||||
<action>Load template: {architecture_template}</action>
|
||||
|
||||
<action>Generate sections: 1. Executive Summary (2-3 sentences about the architecture approach) 2. Project Initialization (starter command if applicable) 3. Decision Summary Table (with verified versions and epic mapping) 4. Complete Project Structure (full tree, no placeholders) 5. Epic to Architecture Mapping (every epic placed) 6. Technology Stack Details (versions, configurations) 7. Integration Points (how components connect) 8. Novel Pattern Designs (if any were created) 9. Implementation Patterns (all consistency rules) 10. Consistency Rules (naming, organization, formats) 11. Data Architecture (models and relationships) 12. API Contracts (request/response formats) 13. Security Architecture (auth, authorization, data protection) 14. Performance Considerations (from NFRs) 15. Deployment Architecture (where and how) 16. Development Environment (setup and prerequisites) 17. Architecture Decision Records (key decisions with rationale)
|
||||
</action>
|
||||
|
||||
<action>Fill template with all collected decisions and patterns</action>
|
||||
|
||||
<action>Ensure starter command is first implementation story:
|
||||
<check if="using_starter_template">
|
||||
"## Project Initialization
|
||||
|
||||
First implementation story should execute:
|
||||
```bash
|
||||
{{starter_command_with_options}}
|
||||
```
|
||||
|
||||
This establishes the base architecture with these decisions:
|
||||
{{starter_provided_decisions}}"
|
||||
</check>
|
||||
|
||||
</action>
|
||||
|
||||
<template-output>architecture_document</template-output>
|
||||
</step>
|
||||
|
||||
<step n="11" goal="Validate document completeness">
|
||||
<action>Load validation checklist: {installed_path}/checklist.md</action>
|
||||
|
||||
<action>Run validation checklist from {installed_path}/checklist.md</action>
|
||||
|
||||
<action>Verify MANDATORY items:
|
||||
□ Decision table has Version column with specific versions
|
||||
□ Every epic is mapped to architecture components
|
||||
□ Source tree is complete, not generic
|
||||
□ No placeholder text remains
|
||||
□ All FRs from PRD have architectural support
|
||||
□ All NFRs from PRD are addressed
|
||||
□ Implementation patterns cover all potential conflicts
|
||||
□ Novel patterns are fully documented (if applicable)
|
||||
</action>
|
||||
|
||||
<check if="validation_failed">
|
||||
<action>Fix missing items automatically</action>
|
||||
<goto step="10">Regenerate document section</goto>
|
||||
</check>
|
||||
|
||||
<template-output>validation_results</template-output>
|
||||
</step>
|
||||
|
||||
<step n="12" goal="Final review and update workflow status">
|
||||
<action>Present completion summary:</action>
|
||||
|
||||
<check if="{user_skill_level} == 'expert'">
|
||||
"Architecture complete. {{decision_count}} decisions documented.
|
||||
Ready for implementation phase."
|
||||
</check>
|
||||
|
||||
<check if="{user_skill_level} == 'beginner'">
|
||||
"Excellent! Your architecture is complete. You made {{decision_count}} important
|
||||
decisions that will keep AI agents consistent as they build your app.
|
||||
|
||||
What happens next:
|
||||
1. AI agents will read this architecture before implementing each story
|
||||
2. They'll follow your technical choices exactly
|
||||
3. Your app will be built with consistent patterns throughout
|
||||
|
||||
You're ready to move to the implementation phase!"
|
||||
|
||||
</check>
|
||||
|
||||
<action>Save document to {planning_artifacts}/architecture.md</action>
|
||||
|
||||
<check if="standalone_mode != true">
|
||||
<action>Load the FULL file: {output_folder}/bmgd-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,224 @@
|
||||
---
|
||||
name: 'step-01-init'
|
||||
description: 'Initialize the architecture workflow, validate readiness, and discover input documents'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-01-init.md'
|
||||
continueStepFile: '{workflow_path}/steps/step-01b-continue.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-02-context.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
templateFile: '{workflow_path}/templates/architecture-template.md'
|
||||
|
||||
# Knowledge Bases
|
||||
decisionCatalog: '{workflow_path}/decision-catalog.yaml'
|
||||
architecturePatterns: '{workflow_path}/architecture-patterns.yaml'
|
||||
patternCategories: '{workflow_path}/pattern-categories.csv'
|
||||
---
|
||||
|
||||
# Step 1: Initialize Architecture Workflow
|
||||
|
||||
**Progress: Step 1 of 9** - Next: Project Context
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate workflow readiness, check for existing architecture work, discover input documents (GDD, Epics), and initialize the output document with proper frontmatter.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Focus on architectural decisions that prevent AI agent conflicts
|
||||
- This is a decision-focused workflow, not an implementation spec
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Check for existing architecture before starting fresh
|
||||
- Validate that required input documents exist (GDD at minimum)
|
||||
- Initialize document with proper frontmatter for state tracking
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Wait for user confirmation at each checkpoint
|
||||
- Update frontmatter `stepsCompleted: [1]` before loading next step
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Check for Existing Architecture
|
||||
|
||||
**Search for existing architecture document:**
|
||||
|
||||
Look for existing architecture files in {output_folder}:
|
||||
|
||||
- `*architecture*.md`
|
||||
- `*arch*.md`
|
||||
|
||||
**If existing architecture found:**
|
||||
|
||||
"I found an existing architecture document: `{{existing_file}}`
|
||||
|
||||
**Options:**
|
||||
|
||||
1. **Continue** - Resume from where you left off
|
||||
2. **Start Fresh** - Begin a new architecture (will overwrite)
|
||||
3. **Review** - Let me review the existing document first
|
||||
|
||||
Which would you like to do?"
|
||||
|
||||
**Handle user selection:**
|
||||
|
||||
- If **Continue**: Load `{continueStepFile}`
|
||||
- If **Start Fresh**: Continue with step 2 below
|
||||
- If **Review**: Show document summary and return to options
|
||||
|
||||
### 2. Discover Required Input Documents
|
||||
|
||||
**Search for GDD:**
|
||||
|
||||
Look for GDD files using patterns:
|
||||
|
||||
- `{output_folder}/*gdd*.md`
|
||||
- `{output_folder}/*game-design*.md`
|
||||
|
||||
**If GDD not found:**
|
||||
|
||||
"**GDD Not Found**
|
||||
|
||||
The Architecture workflow works from your Game Design Document (GDD).
|
||||
|
||||
The GDD provides:
|
||||
|
||||
- Core mechanics and systems to architect
|
||||
- Technical requirements and constraints
|
||||
- Platform targets and performance needs
|
||||
|
||||
Please run the GDD workflow first: `create-gdd`"
|
||||
|
||||
**Exit workflow - GDD required**
|
||||
|
||||
**If GDD found:**
|
||||
|
||||
"**Input Document Found:**
|
||||
|
||||
- GDD: `{{gdd_file}}`
|
||||
|
||||
I'll analyze this to understand your game's technical requirements."
|
||||
|
||||
### 3. Discover Optional Input Documents
|
||||
|
||||
**Search for additional documents:**
|
||||
|
||||
- **Epics**: `{output_folder}/*epic*.md`
|
||||
- **Game Brief**: `{output_folder}/*brief*.md`
|
||||
- **Narrative**: `{output_folder}/*narrative*.md`
|
||||
|
||||
**Report findings:**
|
||||
|
||||
"**Additional Documents Found:**
|
||||
{{list_of_found_documents}}
|
||||
|
||||
These will provide additional context for architectural decisions."
|
||||
|
||||
### 4. Confirm Workflow Start
|
||||
|
||||
**Present start confirmation:**
|
||||
|
||||
"**Ready to Start Architecture Workflow**
|
||||
|
||||
{{user_name}}, I'm ready to help you create the game architecture for your project.
|
||||
|
||||
**What we'll cover:**
|
||||
|
||||
1. Engine/framework selection and validation
|
||||
2. Core architectural decisions (rendering, physics, networking, etc.)
|
||||
3. Project structure and code organization
|
||||
4. Implementation patterns for AI agent consistency
|
||||
5. Cross-cutting concerns (error handling, logging, etc.)
|
||||
|
||||
**Input documents:**
|
||||
|
||||
- GDD: `{{gdd_file}}`
|
||||
{{additional_documents_list}}
|
||||
|
||||
**The goal:** Create an architecture document that ensures all AI agents implement your game consistently.
|
||||
|
||||
Ready to begin? [Y/N]"
|
||||
|
||||
### 5. Initialize Output Document
|
||||
|
||||
**If user confirms, create the initial document:**
|
||||
|
||||
Create `{outputFile}` with frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 'Game Architecture'
|
||||
project: '{{project_name}}'
|
||||
date: '{{date}}'
|
||||
author: '{{user_name}}'
|
||||
version: '1.0'
|
||||
stepsCompleted: [1]
|
||||
status: 'in-progress'
|
||||
|
||||
# Source Documents
|
||||
gdd: '{{gdd_file}}'
|
||||
epics: '{{epics_file_or_null}}'
|
||||
brief: '{{brief_file_or_null}}'
|
||||
---
|
||||
|
||||
# Game Architecture
|
||||
|
||||
## Document Status
|
||||
|
||||
This architecture document is being created through the BMGD Architecture Workflow.
|
||||
|
||||
**Steps Completed:** 1 of 9 (Initialize)
|
||||
|
||||
---
|
||||
|
||||
_Content will be added as we progress through the workflow._
|
||||
```
|
||||
|
||||
### 6. Proceed to Context Step
|
||||
|
||||
After initialization:
|
||||
|
||||
- Update frontmatter: `stepsCompleted: [1]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Existing architecture check performed
|
||||
- GDD discovered and validated
|
||||
- Optional documents discovered
|
||||
- User confirmed workflow start
|
||||
- Output document initialized with proper frontmatter
|
||||
- Frontmatter updated with stepsCompleted: [1]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Skipping input document discovery
|
||||
- Starting without user confirmation
|
||||
- Not checking for existing architecture
|
||||
- Missing frontmatter initialization
|
||||
- Proceeding without GDD
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,154 @@
|
||||
---
|
||||
name: 'step-01b-continue'
|
||||
description: 'Continue an existing architecture workflow from where it left off'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Step Files (for routing)
|
||||
step02: '{workflow_path}/steps/step-02-context.md'
|
||||
step03: '{workflow_path}/steps/step-03-starter.md'
|
||||
step04: '{workflow_path}/steps/step-04-decisions.md'
|
||||
step05: '{workflow_path}/steps/step-05-crosscutting.md'
|
||||
step06: '{workflow_path}/steps/step-06-structure.md'
|
||||
step07: '{workflow_path}/steps/step-07-patterns.md'
|
||||
step08: '{workflow_path}/steps/step-08-validation.md'
|
||||
step09: '{workflow_path}/steps/step-09-complete.md'
|
||||
---
|
||||
|
||||
# Step 1b: Continue Existing Architecture
|
||||
|
||||
**Resuming Architecture Workflow**
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Load the existing architecture document, determine progress, and route to the appropriate next step.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Parse frontmatter to determine completed steps
|
||||
- Present summary of current progress
|
||||
- Route to correct next step based on state
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Load Existing Architecture
|
||||
|
||||
**Read the existing architecture document:**
|
||||
|
||||
Load `{outputFile}` and parse the frontmatter to extract:
|
||||
|
||||
- `stepsCompleted` array
|
||||
- `status`
|
||||
- `project` name
|
||||
- Source document references
|
||||
|
||||
### 2. Analyze Progress
|
||||
|
||||
**Determine workflow state:**
|
||||
|
||||
Map completed steps to workflow progress:
|
||||
|
||||
- Step 1: Initialize
|
||||
- Step 2: Context
|
||||
- Step 3: Starter/Engine
|
||||
- Step 4: Decisions
|
||||
- Step 5: Cross-cutting
|
||||
- Step 6: Structure
|
||||
- Step 7: Patterns
|
||||
- Step 8: Validation
|
||||
- Step 9: Complete
|
||||
|
||||
**Calculate next step:**
|
||||
|
||||
Find the highest completed step and determine the next step file to load.
|
||||
|
||||
### 3. Present Continuation Summary
|
||||
|
||||
"**Resuming Architecture Workflow**
|
||||
|
||||
{{user_name}}, I found your existing architecture for **{{project_name}}**.
|
||||
|
||||
**Progress:** Steps completed: {{stepsCompleted}}
|
||||
|
||||
**Current Status:**
|
||||
|
||||
- Last completed: {{last_step_name}}
|
||||
- Next step: {{next_step_name}} (Step {{next_step_number}} of 9)
|
||||
|
||||
**Document sections completed:**
|
||||
{{list_of_completed_sections}}
|
||||
|
||||
Would you like to:
|
||||
|
||||
1. **Continue** - Resume from {{next_step_name}}
|
||||
2. **Review** - Show me what we've documented so far
|
||||
3. **Restart Step** - Redo the last completed step
|
||||
|
||||
Select an option:"
|
||||
|
||||
### 4. Handle User Selection
|
||||
|
||||
**If Continue:**
|
||||
|
||||
- Load the next step file based on `stepsCompleted`
|
||||
|
||||
**If Review:**
|
||||
|
||||
- Present summary of all completed sections
|
||||
- Return to continuation options
|
||||
|
||||
**If Restart Step:**
|
||||
|
||||
- Decrement stepsCompleted to remove last step
|
||||
- Load the step file for the step being restarted
|
||||
|
||||
### 5. Route to Next Step
|
||||
|
||||
Based on next step number, load the appropriate step file:
|
||||
|
||||
| Next Step | File |
|
||||
| --------- | -------- |
|
||||
| 2 | {step02} |
|
||||
| 3 | {step03} |
|
||||
| 4 | {step04} |
|
||||
| 5 | {step05} |
|
||||
| 6 | {step06} |
|
||||
| 7 | {step07} |
|
||||
| 8 | {step08} |
|
||||
| 9 | {step09} |
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Existing document loaded and parsed
|
||||
- Progress accurately determined
|
||||
- User presented with clear options
|
||||
- Correct step file loaded based on state
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Failing to parse frontmatter correctly
|
||||
- Loading wrong step file
|
||||
- Not presenting continuation options
|
||||
- Overwriting existing progress without confirmation
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,263 @@
|
||||
---
|
||||
name: 'step-02-context'
|
||||
description: 'Load and understand project context from GDD and supporting documents'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-02-context.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-03-starter.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 2: Project Context
|
||||
|
||||
**Progress: Step 2 of 9** - Next: Engine/Starter Selection
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Load and analyze the GDD and supporting documents to understand the game's technical requirements, systems, and constraints that will drive architectural decisions.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Extract technical implications from game design
|
||||
- Identify complexity drivers and novel requirements
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Load ALL referenced input documents
|
||||
- Identify systems that need architectural support
|
||||
- Flag novel concepts requiring special attention
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after context analysis
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Deep dive into technical requirements
|
||||
- **P (Party Mode)**: Get multiple perspectives on complexity
|
||||
- **C (Continue)**: Confirm understanding and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Load GDD Document
|
||||
|
||||
**Load the full GDD:**
|
||||
|
||||
Read the GDD file identified in initialization. Extract:
|
||||
|
||||
- Game title and core concept
|
||||
- Platform targets
|
||||
- Core mechanics and systems
|
||||
- Technical requirements section
|
||||
- Performance constraints
|
||||
- Multiplayer/networking needs
|
||||
- Any technical risks identified
|
||||
|
||||
### 2. Load Supporting Documents
|
||||
|
||||
**Load any available supporting documents:**
|
||||
|
||||
- **Epics**: User stories and acceptance criteria
|
||||
- **Game Brief**: Vision and scope constraints
|
||||
- **Narrative**: Story-driven technical needs
|
||||
|
||||
### 3. Analyze Technical Requirements
|
||||
|
||||
**Extract and categorize technical needs:**
|
||||
|
||||
**Core Systems Identified:**
|
||||
|
||||
| System | Complexity | GDD Reference |
|
||||
| --------------- | ------------------- | ------------- |
|
||||
| {{system_name}} | {{low/medium/high}} | {{section}} |
|
||||
|
||||
**Platform Requirements:**
|
||||
|
||||
- Primary platform: {{platform}}
|
||||
- Secondary platforms: {{if_any}}
|
||||
- Cross-platform considerations: {{if_applicable}}
|
||||
|
||||
**Performance Constraints:**
|
||||
|
||||
- Frame rate target: {{fps}}
|
||||
- Resolution support: {{resolutions}}
|
||||
- Memory constraints: {{if_specified}}
|
||||
- Load time requirements: {{if_specified}}
|
||||
|
||||
**Networking Requirements:**
|
||||
|
||||
- Multiplayer type: {{none/local/online}}
|
||||
- Network architecture: {{p2p/client-server/hybrid}}
|
||||
- Sync requirements: {{if_applicable}}
|
||||
|
||||
### 4. Identify Complexity Drivers
|
||||
|
||||
**Flag areas requiring architectural attention:**
|
||||
|
||||
"Based on my analysis, these are the complexity drivers:
|
||||
|
||||
**High Complexity:**
|
||||
{{list_of_high_complexity_items}}
|
||||
|
||||
**Novel Concepts:**
|
||||
{{unique_features_without_standard_patterns}}
|
||||
|
||||
**Technical Risks:**
|
||||
{{risks_from_gdd}}"
|
||||
|
||||
### 5. Reflect Understanding
|
||||
|
||||
**Present analysis to user:**
|
||||
|
||||
"{{user_name}}, I've analyzed the technical requirements for **{{game_name}}**.
|
||||
|
||||
**Project Summary:**
|
||||
|
||||
- {{core_concept}}
|
||||
- Platform: {{platform}}
|
||||
- {{key_distinguishing_features}}
|
||||
|
||||
**Key Systems Requiring Architecture:**
|
||||
|
||||
1. {{system_1}} - {{brief_description}}
|
||||
2. {{system_2}} - {{brief_description}}
|
||||
3. {{system_3}} - {{brief_description}}
|
||||
|
||||
**Complexity Assessment:**
|
||||
|
||||
- Overall complexity: {{low/medium/high}}
|
||||
- Novel elements: {{count}} requiring custom patterns
|
||||
- Critical decisions: {{estimated_count}}
|
||||
|
||||
**Technical Constraints:**
|
||||
{{summary_of_constraints}}
|
||||
|
||||
Does this match your understanding of the project?"
|
||||
|
||||
### 6. Generate Context Section
|
||||
|
||||
Based on the analysis, prepare the content:
|
||||
|
||||
```markdown
|
||||
## Project Context
|
||||
|
||||
### Game Overview
|
||||
|
||||
**{{game_name}}** - {{core_concept}}
|
||||
|
||||
### Technical Scope
|
||||
|
||||
**Platform:** {{platform}}
|
||||
**Genre:** {{genre}}
|
||||
**Project Level:** {{complexity_level}}
|
||||
|
||||
### Core Systems
|
||||
|
||||
{{systems_table}}
|
||||
|
||||
### Technical Requirements
|
||||
|
||||
{{requirements_summary}}
|
||||
|
||||
### Complexity Drivers
|
||||
|
||||
{{complexity_analysis}}
|
||||
|
||||
### Technical Risks
|
||||
|
||||
{{identified_risks}}
|
||||
```
|
||||
|
||||
### 7. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've drafted the Project Context section based on my analysis.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 6]
|
||||
|
||||
**Validation Check:**
|
||||
|
||||
- Have I captured all core systems?
|
||||
- Are the complexity assessments accurate?
|
||||
- Any technical constraints I missed?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Deep dive into technical requirements
|
||||
[P] Party Mode - Get multiple perspectives on complexity
|
||||
[C] Continue - Save this and move to Engine Selection (Step 3 of 9)"
|
||||
|
||||
### 8. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [context content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- GDD fully loaded and analyzed
|
||||
- Supporting documents incorporated
|
||||
- Systems and complexity identified
|
||||
- Technical constraints documented
|
||||
- User confirmed understanding accuracy
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Generating analysis without reading documents
|
||||
- Missing critical systems from GDD
|
||||
- Proceeding without user confirmation
|
||||
- Not presenting A/P/C menu after analysis
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,291 @@
|
||||
---
|
||||
name: 'step-03-starter'
|
||||
description: 'Discover and evaluate game engine and starter template options'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-03-starter.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-04-decisions.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 3: Engine & Starter Selection
|
||||
|
||||
**Progress: Step 3 of 9** - Next: Architectural Decisions
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Discover and evaluate game engine options and starter templates based on project requirements. Modern engines/starters make many architectural decisions automatically.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Modern starters/engines provide many architectural decisions out of the box
|
||||
- Verify current versions via web search - NEVER trust hardcoded versions
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- ALWAYS search web for current versions
|
||||
- Document which decisions the engine provides
|
||||
- Help user understand engine trade-offs
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after engine selection
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Explore alternative engines
|
||||
- **P (Party Mode)**: Get perspectives on engine choice
|
||||
- **C (Continue)**: Confirm selection and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Identify Engine Requirements
|
||||
|
||||
**Based on project context, determine engine needs:**
|
||||
|
||||
"Let's determine the right engine/framework for **{{game_name}}**.
|
||||
|
||||
**Your Requirements:**
|
||||
|
||||
- Platform: {{platform}}
|
||||
- Genre: {{genre}}
|
||||
- Key systems: {{key_systems}}
|
||||
|
||||
**Engine Considerations:**
|
||||
|
||||
| Requirement | Implications |
|
||||
| ------------------- | --------------------- |
|
||||
| **2D vs 3D** | {{2d_or_3d}} |
|
||||
| **Performance** | {{performance_needs}} |
|
||||
| **Networking** | {{networking_needs}} |
|
||||
| **Platform Export** | {{platform_targets}} |
|
||||
|
||||
What engine or framework are you considering, or would you like recommendations?"
|
||||
|
||||
### 2. Research Engine Options
|
||||
|
||||
**If user has an engine in mind:**
|
||||
|
||||
Search the web to verify:
|
||||
|
||||
- Current stable version
|
||||
- Platform support status
|
||||
- Recent updates and roadmap
|
||||
|
||||
**If user wants recommendations:**
|
||||
|
||||
Based on requirements, search for appropriate options:
|
||||
|
||||
| Game Type | Recommended Options |
|
||||
| ------------ | --------------------------- |
|
||||
| **2D Indie** | Godot, Unity 2D, Phaser |
|
||||
| **3D Indie** | Godot, Unity, Unreal |
|
||||
| **Web Game** | Phaser, PixiJS, Three.js |
|
||||
| **Mobile** | Unity, Godot, Flutter Flame |
|
||||
| **VR/AR** | Unity, Unreal |
|
||||
|
||||
Search web: "{{recommended_engine}} game engine {{current_year}} version features"
|
||||
|
||||
### 3. Present Engine Options
|
||||
|
||||
**Present findings to user:**
|
||||
|
||||
"Based on your requirements, here are the engine options:
|
||||
|
||||
**Option 1: {{engine_1}}**
|
||||
|
||||
- Version: {{verified_version}}
|
||||
- Strengths: {{strengths}}
|
||||
- Considerations: {{considerations}}
|
||||
- Best for: {{best_use_case}}
|
||||
|
||||
**Option 2: {{engine_2}}**
|
||||
|
||||
- Version: {{verified_version}}
|
||||
- Strengths: {{strengths}}
|
||||
- Considerations: {{considerations}}
|
||||
- Best for: {{best_use_case}}
|
||||
|
||||
**Option 3: {{engine_3}}**
|
||||
|
||||
- Version: {{verified_version}}
|
||||
- Strengths: {{strengths}}
|
||||
- Considerations: {{considerations}}
|
||||
- Best for: {{best_use_case}}
|
||||
|
||||
Which engine would you like to use for {{game_name}}?"
|
||||
|
||||
### 4. Document Engine Selection
|
||||
|
||||
**After user selects engine:**
|
||||
|
||||
"**Engine Selected:** {{selected_engine}} v{{version}}
|
||||
|
||||
**Decisions Provided by Engine:**
|
||||
|
||||
| Category | Decision | Provided By |
|
||||
| -------------------- | ---------------------- | ----------- |
|
||||
| **Rendering** | {{rendering_approach}} | Engine |
|
||||
| **Physics** | {{physics_system}} | Engine |
|
||||
| **Audio** | {{audio_system}} | Engine |
|
||||
| **Input** | {{input_system}} | Engine |
|
||||
| **Scene Management** | {{scene_approach}} | Engine |
|
||||
| **Build System** | {{build_approach}} | Engine |
|
||||
|
||||
**Remaining Decisions:**
|
||||
These architectural decisions still need to be made:
|
||||
{{list_of_remaining_decisions}}
|
||||
|
||||
Does this look correct?"
|
||||
|
||||
### 5. Discover Starter Templates
|
||||
|
||||
**Search for project templates:**
|
||||
|
||||
Search web: "{{engine}} starter template {{game_type}} {{current_year}}"
|
||||
|
||||
**If templates found:**
|
||||
|
||||
"I found some starter templates for {{engine}}:
|
||||
|
||||
**{{template_1}}:**
|
||||
|
||||
- What it provides: {{features}}
|
||||
- Setup command: `{{command}}`
|
||||
|
||||
**{{template_2}}:**
|
||||
|
||||
- What it provides: {{features}}
|
||||
- Setup command: `{{command}}`
|
||||
|
||||
Would you like to use a starter template, or start from scratch?"
|
||||
|
||||
### 6. Generate Engine Section
|
||||
|
||||
Based on the conversation, prepare the content:
|
||||
|
||||
````markdown
|
||||
## Engine & Framework
|
||||
|
||||
### Selected Engine
|
||||
|
||||
**{{engine_name}}** v{{version}}
|
||||
|
||||
**Rationale:** {{why_selected}}
|
||||
|
||||
### Project Initialization
|
||||
|
||||
{{if_starter_template}}
|
||||
|
||||
```bash
|
||||
{{initialization_command}}
|
||||
```
|
||||
````
|
||||
|
||||
{{/if_starter_template}}
|
||||
|
||||
### Engine-Provided Architecture
|
||||
|
||||
| Component | Solution | Notes |
|
||||
| --------- | -------- | ----- |
|
||||
|
||||
{{engine_provided_table}}
|
||||
|
||||
### Remaining Architectural Decisions
|
||||
|
||||
The following decisions must be made explicitly:
|
||||
|
||||
{{remaining_decisions_list}}
|
||||
|
||||
```
|
||||
|
||||
### 7. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've drafted the Engine & Framework section.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 6]
|
||||
|
||||
**Validation Check:**
|
||||
- Is the engine version current?
|
||||
- Are the engine-provided decisions accurate?
|
||||
- Have we identified all remaining decisions?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Explore alternative engines
|
||||
[P] Party Mode - Get perspectives on engine choice
|
||||
[C] Continue - Save this and move to Architectural Decisions (Step 4 of 9)"
|
||||
|
||||
### 8. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [engine content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Engine requirements clearly identified
|
||||
- Current versions verified via web search
|
||||
- Engine-provided decisions documented
|
||||
- Remaining decisions identified
|
||||
- Starter template evaluated if applicable
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Using hardcoded versions without verification
|
||||
- Not documenting engine-provided decisions
|
||||
- Proceeding without user engine selection
|
||||
- Not presenting A/P/C menu after selection
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
```
|
||||
@@ -0,0 +1,301 @@
|
||||
---
|
||||
name: 'step-04-decisions'
|
||||
description: 'Facilitate collaborative architectural decision making for game systems'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-04-decisions.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-05-crosscutting.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Knowledge Bases
|
||||
decisionCatalog: '{workflow_path}/decision-catalog.yaml'
|
||||
architecturePatterns: '{workflow_path}/architecture-patterns.yaml'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 4: Architectural Decisions
|
||||
|
||||
**Progress: Step 4 of 9** - Next: Cross-cutting Concerns
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Facilitate collaborative decision-making for all remaining architectural choices. Each decision must be made WITH the user, not FOR them.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Each decision must be made WITH the user
|
||||
- Present options, explain trade-offs, accept user choice
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Load decision catalog for structured guidance
|
||||
- Verify technology versions via web search
|
||||
- Document rationale for every decision
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after all decisions documented
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Challenge decisions and explore alternatives
|
||||
- **P (Party Mode)**: Get multiple perspectives on choices
|
||||
- **C (Continue)**: Confirm decisions and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Load Decision Framework
|
||||
|
||||
**Load decision catalog if available:**
|
||||
|
||||
Load `{decisionCatalog}` and `{architecturePatterns}` to guide the decision process.
|
||||
|
||||
**Identify required decisions based on game type:**
|
||||
|
||||
| Category | Decisions Needed |
|
||||
| ---------------------- | --------------------------- |
|
||||
| **State Management** | {{if_applicable}} |
|
||||
| **Data Persistence** | Save system, config storage |
|
||||
| **Networking** | {{if_multiplayer}} |
|
||||
| **AI Systems** | {{if_has_ai}} |
|
||||
| **Asset Loading** | Streaming, caching |
|
||||
| **Scene Structure** | Scene graph, loading |
|
||||
| **UI Framework** | In-game, menus |
|
||||
| **Audio Architecture** | Channels, mixing |
|
||||
|
||||
### 2. Prioritize Decisions
|
||||
|
||||
**Create decision priority list:**
|
||||
|
||||
"Based on your project, here are the architectural decisions we need to make:
|
||||
|
||||
**CRITICAL (blocks everything):**
|
||||
{{critical_decisions}}
|
||||
|
||||
**IMPORTANT (shapes architecture):**
|
||||
{{important_decisions}}
|
||||
|
||||
**NICE-TO-HAVE (can defer):**
|
||||
{{optional_decisions}}
|
||||
|
||||
Let's work through these in priority order."
|
||||
|
||||
### 3. Facilitate Each Decision
|
||||
|
||||
**For each decision, follow this pattern:**
|
||||
|
||||
"**Decision: {{decision_name}}**
|
||||
|
||||
{{context_about_why_this_matters}}
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Pros | Cons |
|
||||
| ------------ | -------- | -------- |
|
||||
| {{option_1}} | {{pros}} | {{cons}} |
|
||||
| {{option_2}} | {{pros}} | {{cons}} |
|
||||
| {{option_3}} | {{pros}} | {{cons}} |
|
||||
|
||||
**Recommendation:** {{recommendation}} because {{reason}}
|
||||
|
||||
What's your preference? (or 'explain more' for details)"
|
||||
|
||||
**After user decides:**
|
||||
|
||||
Record:
|
||||
|
||||
- Category: {{category}}
|
||||
- Decision: {{user_choice}}
|
||||
- Version: {{if_applicable}}
|
||||
- Rationale: {{user_reasoning}}
|
||||
|
||||
### 4. Game-Specific Decision Categories
|
||||
|
||||
**State Management:**
|
||||
|
||||
"How should game state be managed?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Singleton Pattern** - Simple, global access, harder to test
|
||||
- **State Machine** - Clear transitions, good for game modes
|
||||
- **ECS (Entity Component System)** - Scalable, decoupled, learning curve
|
||||
- **Redux-style** - Predictable, time travel debugging, more boilerplate
|
||||
|
||||
For {{game_type}}, {{recommendation}} works well because {{reason}}.
|
||||
|
||||
Your choice?"
|
||||
|
||||
**Save System:**
|
||||
|
||||
"How should player progress be saved?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Local files** - JSON/binary, works offline
|
||||
- **Cloud saves** - Cross-device, requires backend
|
||||
- **Hybrid** - Local primary, cloud sync
|
||||
- **Platform-specific** - Steam Cloud, console saves
|
||||
|
||||
Your choice?"
|
||||
|
||||
**Asset Loading:**
|
||||
|
||||
"How should assets be loaded?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Preload all** - Simple, longer initial load
|
||||
- **Lazy loading** - Fast startup, potential hitches
|
||||
- **Streaming** - Seamless, complex implementation
|
||||
- **Scene-based** - Load per scene, clear boundaries
|
||||
|
||||
Your choice?"
|
||||
|
||||
### 5. Handle Version Verification
|
||||
|
||||
**For any technology-specific decisions:**
|
||||
|
||||
Search web: "{{technology}} latest stable version {{current_year}}"
|
||||
|
||||
Document:
|
||||
|
||||
- Technology: {{name}}
|
||||
- Verified Version: {{version}}
|
||||
- Verification Date: {{today}}
|
||||
|
||||
### 6. Generate Decisions Section
|
||||
|
||||
After all decisions are made, prepare the content:
|
||||
|
||||
```markdown
|
||||
## Architectural Decisions
|
||||
|
||||
### Decision Summary
|
||||
|
||||
| Category | Decision | Version | Rationale |
|
||||
| -------- | -------- | ------- | --------- |
|
||||
|
||||
{{decision_table_rows}}
|
||||
|
||||
### State Management
|
||||
|
||||
**Approach:** {{state_management_choice}}
|
||||
|
||||
{{state_management_details}}
|
||||
|
||||
### Data Persistence
|
||||
|
||||
**Save System:** {{save_system_choice}}
|
||||
|
||||
{{save_system_details}}
|
||||
|
||||
### Asset Management
|
||||
|
||||
**Loading Strategy:** {{asset_loading_choice}}
|
||||
|
||||
{{asset_loading_details}}
|
||||
|
||||
### {{Additional_Categories}}
|
||||
|
||||
{{additional_decision_details}}
|
||||
|
||||
### Architecture Decision Records
|
||||
|
||||
{{key_decisions_with_context}}
|
||||
```
|
||||
|
||||
### 7. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've documented all our architectural decisions.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 6]
|
||||
|
||||
**Decisions Made:** {{count}} decisions documented
|
||||
|
||||
**Validation Check:**
|
||||
|
||||
- Are all critical decisions captured?
|
||||
- Are versions current and verified?
|
||||
- Does the rationale reflect your reasoning?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Challenge decisions, explore alternatives
|
||||
[P] Party Mode - Get different perspectives on choices
|
||||
[C] Continue - Save this and move to Cross-cutting Concerns (Step 5 of 9)"
|
||||
|
||||
### 8. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [decisions content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- All required decisions identified
|
||||
- User made each decision (not generated)
|
||||
- Versions verified via web search
|
||||
- Rationale documented for each decision
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3, 4]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Making decisions FOR the user
|
||||
- Using unverified versions
|
||||
- Missing critical decisions
|
||||
- Not documenting rationale
|
||||
- Not presenting A/P/C menu after decisions
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,320 @@
|
||||
---
|
||||
name: 'step-05-crosscutting'
|
||||
description: 'Address cross-cutting concerns that affect all game systems'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-05-crosscutting.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-06-structure.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 5: Cross-cutting Concerns
|
||||
|
||||
**Progress: Step 5 of 9** - Next: Project Structure
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Define patterns for concerns that affect EVERY system in the game: error handling, logging, configuration, events, and debugging. These decisions ensure consistency across all AI agent implementations.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Cross-cutting concerns affect EVERY system
|
||||
- Consistency here prevents major integration issues
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Focus on patterns that prevent AI agent conflicts
|
||||
- Every decision must have a concrete example
|
||||
- These become mandatory rules for all implementations
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after all concerns documented
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Deep dive into specific concerns
|
||||
- **P (Party Mode)**: Get perspectives on patterns
|
||||
- **C (Continue)**: Confirm patterns and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Explain Cross-cutting Importance
|
||||
|
||||
"Now let's define cross-cutting concerns - patterns that apply to EVERY system.
|
||||
|
||||
**Why this matters:**
|
||||
If one AI agent handles errors differently than another, your game breaks.
|
||||
If logging formats vary, debugging becomes impossible.
|
||||
These patterns are the 'constitution' that all code must follow.
|
||||
|
||||
Let's define each one."
|
||||
|
||||
### 2. Error Handling Strategy
|
||||
|
||||
"**Error Handling**
|
||||
|
||||
How should ALL systems handle errors?
|
||||
|
||||
**Options:**
|
||||
|
||||
| Approach | Description | Best For |
|
||||
| ------------------------ | ------------------------------- | ------------------- |
|
||||
| **Try-Catch Everywhere** | Explicit handling at each point | Critical systems |
|
||||
| **Global Handler** | Centralized error management | Consistent recovery |
|
||||
| **Signal/Event Based** | Emit errors as events | Decoupled systems |
|
||||
| **Result Objects** | Return success/failure objects | Functional style |
|
||||
|
||||
**Game-specific considerations:**
|
||||
|
||||
- Should errors pause the game?
|
||||
- How should critical vs recoverable errors differ?
|
||||
- Should errors be visible to players?
|
||||
|
||||
What's your error handling strategy?"
|
||||
|
||||
### 3. Logging Approach
|
||||
|
||||
"**Logging Strategy**
|
||||
|
||||
How should ALL systems log information?
|
||||
|
||||
**Log Levels:**
|
||||
|
||||
- **ERROR**: Something broke
|
||||
- **WARN**: Something unexpected but handled
|
||||
- **INFO**: Normal operation milestones
|
||||
- **DEBUG**: Detailed diagnostic info
|
||||
- **TRACE**: Extremely verbose (development only)
|
||||
|
||||
**Questions:**
|
||||
|
||||
- What format? (structured JSON, plain text, engine-native)
|
||||
- Where do logs go? (console, file, external service)
|
||||
- What should always be logged vs conditional?
|
||||
- How should performance-critical paths handle logging?
|
||||
|
||||
What's your logging approach?"
|
||||
|
||||
### 4. Configuration Management
|
||||
|
||||
"**Configuration Management**
|
||||
|
||||
How will game settings be organized and accessed?
|
||||
|
||||
**Configuration Types:**
|
||||
|
||||
- **Game constants** - Values that never change
|
||||
- **Balancing values** - Tweakable gameplay numbers
|
||||
- **Player settings** - User preferences
|
||||
- **Platform settings** - Per-platform adjustments
|
||||
|
||||
**Storage options:**
|
||||
|
||||
- Hardcoded constants
|
||||
- Configuration files (JSON, YAML)
|
||||
- Engine-native systems
|
||||
- Remote configuration
|
||||
|
||||
How should configuration be managed?"
|
||||
|
||||
### 5. Event/Signal System
|
||||
|
||||
"**Event System**
|
||||
|
||||
How should systems communicate without tight coupling?
|
||||
|
||||
**Options:**
|
||||
|
||||
| Pattern | Description | Complexity |
|
||||
| ----------------- | --------------------- | ---------- |
|
||||
| **Observer** | Direct subscription | Simple |
|
||||
| **Event Bus** | Central dispatcher | Medium |
|
||||
| **Signal/Slot** | Type-safe connections | Medium |
|
||||
| **Message Queue** | Async processing | Complex |
|
||||
|
||||
**Questions:**
|
||||
|
||||
- Typed events or stringly-typed?
|
||||
- Sync or async event processing?
|
||||
- Event history/replay for debugging?
|
||||
|
||||
What's your event system approach?"
|
||||
|
||||
### 6. Debug/Development Tools
|
||||
|
||||
"**Debug & Development Tools**
|
||||
|
||||
What development tools should be built in?
|
||||
|
||||
**Common debug features:**
|
||||
|
||||
- Debug console/command system
|
||||
- Visual debugging overlays
|
||||
- State inspection tools
|
||||
- Performance profiling hooks
|
||||
- Cheat/testing commands
|
||||
|
||||
**Questions:**
|
||||
|
||||
- How are debug features enabled/disabled?
|
||||
- Should they be in release builds?
|
||||
- What's the debug key/activation method?
|
||||
|
||||
What debug tools do you want?"
|
||||
|
||||
### 7. Generate Cross-cutting Section
|
||||
|
||||
Based on the conversation, prepare the content:
|
||||
|
||||
````markdown
|
||||
## Cross-cutting Concerns
|
||||
|
||||
These patterns apply to ALL systems and must be followed by every implementation.
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Strategy:** {{error_strategy}}
|
||||
|
||||
**Error Levels:**
|
||||
{{error_level_definitions}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{error_handling_example}}
|
||||
```
|
||||
````
|
||||
|
||||
### Logging
|
||||
|
||||
**Format:** {{logging_format}}
|
||||
**Destination:** {{log_destination}}
|
||||
|
||||
**Log Levels:**
|
||||
{{log_level_usage}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{logging_example}}
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
**Approach:** {{config_approach}}
|
||||
|
||||
**Configuration Structure:**
|
||||
{{config_structure}}
|
||||
|
||||
### Event System
|
||||
|
||||
**Pattern:** {{event_pattern}}
|
||||
|
||||
**Event Naming:** {{naming_convention}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{event_example}}
|
||||
```
|
||||
|
||||
### Debug Tools
|
||||
|
||||
**Available Tools:**
|
||||
{{debug_tool_list}}
|
||||
|
||||
**Activation:** {{how_to_enable}}
|
||||
|
||||
```
|
||||
|
||||
### 8. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've documented all cross-cutting concerns.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 7]
|
||||
|
||||
**Validation Check:**
|
||||
- Do these patterns cover all systems?
|
||||
- Are the examples clear enough for AI agents?
|
||||
- Any edge cases we missed?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Deep dive into specific concerns
|
||||
[P] Party Mode - Get perspectives on patterns
|
||||
[C] Continue - Save this and move to Project Structure (Step 6 of 9)"
|
||||
|
||||
### 9. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [cross-cutting content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Error handling strategy defined with example
|
||||
- Logging approach documented
|
||||
- Configuration management established
|
||||
- Event system pattern selected
|
||||
- Debug tools identified
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Missing any cross-cutting concern
|
||||
- No concrete examples provided
|
||||
- Patterns too vague for AI agents to follow
|
||||
- Not presenting A/P/C menu after documentation
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
```
|
||||
@@ -0,0 +1,305 @@
|
||||
---
|
||||
name: 'step-06-structure'
|
||||
description: 'Define project structure, directory organization, and architectural boundaries'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-06-structure.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-07-patterns.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 6: Project Structure
|
||||
|
||||
**Progress: Step 6 of 9** - Next: Implementation Patterns
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Define the complete project structure including directory organization, file naming conventions, and architectural boundaries. This ensures all AI agents place code consistently.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Project structure prevents "where does this go?" confusion
|
||||
- Clear boundaries enable parallel development
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Structure must be complete, not generic placeholders
|
||||
- Map every major system to a location
|
||||
- Define naming conventions explicitly
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after structure defined
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Refine structure organization
|
||||
- **P (Party Mode)**: Get perspectives on layout
|
||||
- **C (Continue)**: Confirm structure and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Determine Organization Pattern
|
||||
|
||||
"Let's define how your project will be organized.
|
||||
|
||||
**Organization Patterns:**
|
||||
|
||||
| Pattern | Description | Best For |
|
||||
| ----------------- | -------------------------------- | ------------- |
|
||||
| **By Feature** | All related files together | Feature teams |
|
||||
| **By Type** | Scripts, assets, scenes separate | Traditional |
|
||||
| **Hybrid** | Types at top, features within | Balanced |
|
||||
| **Domain-Driven** | By game domain/system | Complex games |
|
||||
|
||||
**Engine Conventions:**
|
||||
|
||||
- {{engine}} typically uses: {{engine_convention}}
|
||||
|
||||
What organization pattern do you prefer?"
|
||||
|
||||
### 2. Define Root Structure
|
||||
|
||||
"Based on {{selected_pattern}}, let's define your root structure.
|
||||
|
||||
**For {{engine}}, typical root looks like:**
|
||||
|
||||
```
|
||||
{{project_name}}/
|
||||
├── {{source_folder}}/ # Game source code
|
||||
├── {{assets_folder}}/ # Art, audio, data
|
||||
├── {{scenes_folder}}/ # Scene/level files
|
||||
├── {{tests_folder}}/ # Test files
|
||||
├── {{docs_folder}}/ # Documentation
|
||||
└── {{config_files}} # Project config
|
||||
```
|
||||
|
||||
Does this work, or would you like to adjust?"
|
||||
|
||||
### 3. Detail Source Structure
|
||||
|
||||
"Now let's detail the source code organization.
|
||||
|
||||
**Based on your systems:**
|
||||
{{list_of_systems_from_context}}
|
||||
|
||||
**Proposed structure:**
|
||||
|
||||
```
|
||||
{{source_folder}}/
|
||||
├── core/ # Core systems (singletons, managers)
|
||||
│ ├── {{core_systems}}
|
||||
├── gameplay/ # Gameplay mechanics
|
||||
│ ├── {{gameplay_systems}}
|
||||
├── ui/ # User interface
|
||||
│ ├── {{ui_organization}}
|
||||
├── utils/ # Utilities and helpers
|
||||
│ ├── {{util_types}}
|
||||
└── data/ # Data structures and models
|
||||
└── {{data_types}}
|
||||
```
|
||||
|
||||
What adjustments would you make?"
|
||||
|
||||
### 4. Define Asset Structure
|
||||
|
||||
"Let's organize your assets.
|
||||
|
||||
**Asset Categories:**
|
||||
|
||||
- Art (sprites, textures, models)
|
||||
- Audio (music, sfx, voice)
|
||||
- Data (configurations, levels)
|
||||
- UI (interface assets)
|
||||
|
||||
**Proposed asset structure:**
|
||||
|
||||
```
|
||||
{{assets_folder}}/
|
||||
├── art/
|
||||
│ ├── {{art_categories}}
|
||||
├── audio/
|
||||
│ ├── music/
|
||||
│ ├── sfx/
|
||||
│ └── {{audio_categories}}
|
||||
├── data/
|
||||
│ └── {{data_file_types}}
|
||||
└── ui/
|
||||
└── {{ui_asset_types}}
|
||||
```
|
||||
|
||||
How should assets be organized?"
|
||||
|
||||
### 5. Map Systems to Locations
|
||||
|
||||
"Let's map each major system to its location.
|
||||
|
||||
| System | Location | Notes |
|
||||
| ------ | -------- | ----- |
|
||||
|
||||
{{system_location_mapping}}
|
||||
|
||||
Does this mapping make sense for your project?"
|
||||
|
||||
### 6. Define Naming Conventions
|
||||
|
||||
"Finally, let's establish naming conventions.
|
||||
|
||||
**Files:**
|
||||
|
||||
- Scripts: {{script_naming}} (e.g., PlayerController, enemy_spawner)
|
||||
- Scenes: {{scene_naming}} (e.g., Level01, main_menu)
|
||||
- Assets: {{asset_naming}} (e.g., player_idle, btn_play)
|
||||
|
||||
**Code Elements:**
|
||||
|
||||
- Classes: {{class_naming}} (e.g., PascalCase)
|
||||
- Functions: {{function_naming}} (e.g., snake_case, camelCase)
|
||||
- Variables: {{variable_naming}}
|
||||
- Constants: {{constant_naming}} (e.g., UPPER_SNAKE)
|
||||
|
||||
**Game-Specific:**
|
||||
|
||||
- Prefabs/Scenes: {{prefab_naming}}
|
||||
- Animation clips: {{animation_naming}}
|
||||
- Event names: {{event_naming}}
|
||||
|
||||
What are your naming preferences?"
|
||||
|
||||
### 7. Generate Structure Section
|
||||
|
||||
Based on the conversation, prepare the content:
|
||||
|
||||
```markdown
|
||||
## Project Structure
|
||||
|
||||
### Organization Pattern
|
||||
|
||||
**Pattern:** {{organization_pattern}}
|
||||
|
||||
**Rationale:** {{why_this_pattern}}
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
|
||||
{{project_name}}/
|
||||
{{complete_directory_tree}}
|
||||
|
||||
```
|
||||
|
||||
### System Location Mapping
|
||||
|
||||
| System | Location | Responsibility |
|
||||
| ------ | -------- | -------------- |
|
||||
{{system_mapping_table}}
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
#### Files
|
||||
{{file_naming_rules}}
|
||||
|
||||
#### Code Elements
|
||||
| Element | Convention | Example |
|
||||
| ------- | ---------- | ------- |
|
||||
{{code_naming_table}}
|
||||
|
||||
#### Game Assets
|
||||
{{asset_naming_rules}}
|
||||
|
||||
### Architectural Boundaries
|
||||
|
||||
{{boundary_rules}}
|
||||
```
|
||||
|
||||
### 8. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've defined the complete project structure.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 7]
|
||||
|
||||
**Validation Check:**
|
||||
|
||||
- Can every system find its home?
|
||||
- Are naming conventions clear and consistent?
|
||||
- Will AI agents know exactly where to place new code?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Refine structure organization
|
||||
[P] Party Mode - Get perspectives on layout
|
||||
[C] Continue - Save this and move to Implementation Patterns (Step 7 of 9)"
|
||||
|
||||
### 9. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [structure content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Complete directory structure defined
|
||||
- Every system mapped to location
|
||||
- Naming conventions explicit and consistent
|
||||
- No placeholder or generic structures
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5, 6]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Generic structure with placeholders
|
||||
- Systems without clear locations
|
||||
- Vague naming conventions
|
||||
- Not presenting A/P/C menu after structure
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,350 @@
|
||||
---
|
||||
name: 'step-07-patterns'
|
||||
description: 'Design implementation patterns and novel architectural patterns for consistency'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-07-patterns.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-08-validation.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Knowledge Bases
|
||||
patternCategories: '{workflow_path}/pattern-categories.csv'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 7: Implementation Patterns
|
||||
|
||||
**Progress: Step 7 of 9** - Next: Validation
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Define implementation patterns that ensure multiple AI agents write compatible, consistent code. Also identify and design any novel patterns needed for unique game features.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Implementation patterns prevent agent conflicts
|
||||
- Novel patterns require creative collaboration
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Every pattern needs a concrete example
|
||||
- Focus on what agents could decide DIFFERENTLY
|
||||
- Novel patterns need full design documentation
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after patterns defined
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Explore alternative patterns
|
||||
- **P (Party Mode)**: Get perspectives on patterns
|
||||
- **C (Continue)**: Confirm patterns and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Identify Novel Patterns Needed
|
||||
|
||||
"First, let's identify if your game needs any custom architectural patterns.
|
||||
|
||||
**Novel patterns are needed when:**
|
||||
|
||||
- Standard patterns don't fit your gameplay
|
||||
- You have unique mechanics not found in other games
|
||||
- Multiple systems interact in non-standard ways
|
||||
|
||||
**From your GDD, I identified these potentially novel concepts:**
|
||||
{{list_of_unique_features}}
|
||||
|
||||
Do any of these need custom architectural patterns?"
|
||||
|
||||
### 2. Design Novel Patterns (if needed)
|
||||
|
||||
**For each novel pattern:**
|
||||
|
||||
"**Novel Pattern: {{pattern_name}}**
|
||||
|
||||
Let's design this pattern together.
|
||||
|
||||
**The challenge:** {{what_makes_this_unique}}
|
||||
|
||||
**Questions to answer:**
|
||||
|
||||
1. What components are involved?
|
||||
2. How do they communicate?
|
||||
3. What's the data flow?
|
||||
4. How is state managed?
|
||||
5. What are the edge cases?
|
||||
|
||||
Walk me through how you envision {{pattern_name}} working."
|
||||
|
||||
**After user explains:**
|
||||
|
||||
"Based on your description, here's the pattern design:
|
||||
|
||||
**{{pattern_name}} Pattern**
|
||||
|
||||
**Components:**
|
||||
{{component_list_with_responsibilities}}
|
||||
|
||||
**Data Flow:**
|
||||
{{sequence_or_diagram}}
|
||||
|
||||
**State Management:**
|
||||
{{state_approach}}
|
||||
|
||||
**Example Usage:**
|
||||
|
||||
```{{language}}
|
||||
{{code_example}}
|
||||
```
|
||||
|
||||
Does this capture your vision?"
|
||||
|
||||
### 3. Define Standard Implementation Patterns
|
||||
|
||||
"Now let's define standard implementation patterns for consistency.
|
||||
|
||||
**These patterns ensure all AI agents:**
|
||||
|
||||
- Name things the same way
|
||||
- Structure code identically
|
||||
- Handle common situations consistently
|
||||
|
||||
Let's go through each category."
|
||||
|
||||
### 4. Component Communication Pattern
|
||||
|
||||
"**Component Communication**
|
||||
|
||||
How should game objects communicate?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Direct references** - Simple but coupled
|
||||
- **Event-based** - Decoupled but indirect
|
||||
- **Service locator** - Central registry
|
||||
- **Dependency injection** - Explicit dependencies
|
||||
|
||||
For game systems, what's your preferred approach?"
|
||||
|
||||
### 5. Entity Creation Pattern
|
||||
|
||||
"**Entity Creation**
|
||||
|
||||
How should game entities (enemies, items, etc.) be created?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Factory pattern** - Centralized creation
|
||||
- **Prefab instantiation** - Engine-native
|
||||
- **Object pooling** - Performance-focused
|
||||
- **Builder pattern** - Complex configuration
|
||||
|
||||
What's your entity creation approach?"
|
||||
|
||||
### 6. State Transition Pattern
|
||||
|
||||
"**State Transitions**
|
||||
|
||||
How should entities handle state changes?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **State machine** - Explicit states and transitions
|
||||
- **Behavior tree** - AI-focused hierarchy
|
||||
- **Blackboard** - Shared data approach
|
||||
- **Flag-based** - Simple boolean states
|
||||
|
||||
What state management pattern for entities?"
|
||||
|
||||
### 7. Data Access Pattern
|
||||
|
||||
"**Data Access**
|
||||
|
||||
How should systems access game data?
|
||||
|
||||
**Options:**
|
||||
|
||||
- **Direct file access** - Simple but scattered
|
||||
- **Data manager** - Centralized access
|
||||
- **Scriptable objects** - Engine-native (Unity)
|
||||
- **Resources/Autoload** - Engine-native (Godot)
|
||||
|
||||
How should data be accessed?"
|
||||
|
||||
### 8. Generate Patterns Section
|
||||
|
||||
Based on the conversation, prepare the content:
|
||||
|
||||
````markdown
|
||||
## Implementation Patterns
|
||||
|
||||
These patterns ensure consistent implementation across all AI agents.
|
||||
|
||||
{{if_novel_patterns}}
|
||||
|
||||
### Novel Patterns
|
||||
|
||||
#### {{novel_pattern_name}}
|
||||
|
||||
**Purpose:** {{what_it_solves}}
|
||||
|
||||
**Components:**
|
||||
{{component_list}}
|
||||
|
||||
**Data Flow:**
|
||||
{{flow_description}}
|
||||
|
||||
**Implementation Guide:**
|
||||
|
||||
```{{language}}
|
||||
{{implementation_example}}
|
||||
```
|
||||
````
|
||||
|
||||
**Usage:**
|
||||
{{when_to_use}}
|
||||
{{/if_novel_patterns}}
|
||||
|
||||
### Communication Patterns
|
||||
|
||||
**Pattern:** {{communication_pattern}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{communication_example}}
|
||||
```
|
||||
|
||||
### Entity Patterns
|
||||
|
||||
**Creation:** {{creation_pattern}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{creation_example}}
|
||||
```
|
||||
|
||||
### State Patterns
|
||||
|
||||
**Pattern:** {{state_pattern}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{state_example}}
|
||||
```
|
||||
|
||||
### Data Patterns
|
||||
|
||||
**Access:** {{data_pattern}}
|
||||
|
||||
**Example:**
|
||||
|
||||
```{{language}}
|
||||
{{data_example}}
|
||||
```
|
||||
|
||||
### Consistency Rules
|
||||
|
||||
| Pattern | Convention | Enforcement |
|
||||
| ------- | ---------- | ----------- |
|
||||
|
||||
{{consistency_rules_table}}
|
||||
|
||||
```
|
||||
|
||||
### 9. Present Content and Menu
|
||||
|
||||
Show the generated content to the user and present:
|
||||
|
||||
"I've documented all implementation patterns.
|
||||
|
||||
**Here's what I'll add to the document:**
|
||||
|
||||
[Show the complete markdown content from step 8]
|
||||
|
||||
**Patterns Defined:**
|
||||
- {{count}} standard patterns
|
||||
- {{novel_count}} novel patterns
|
||||
|
||||
**Validation Check:**
|
||||
- Are examples clear enough for AI agents?
|
||||
- Do patterns cover all major coding scenarios?
|
||||
- Are novel patterns fully documented?
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Explore alternative patterns
|
||||
[P] Party Mode - Get perspectives on patterns
|
||||
[C] Continue - Save this and move to Validation (Step 8 of 9)"
|
||||
|
||||
### 10. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
- Execute {advancedElicitationTask} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
- Execute {partyModeWorkflow} with the current content
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, return to A/P/C menu
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
- Append the final content to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [patterns content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Novel patterns identified and designed
|
||||
- Standard patterns selected with examples
|
||||
- Every pattern has concrete code examples
|
||||
- Consistency rules documented
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5, 6, 7]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Patterns without concrete examples
|
||||
- Novel patterns missing design documentation
|
||||
- Vague patterns that allow inconsistency
|
||||
- Not presenting A/P/C menu after patterns
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
```
|
||||
@@ -0,0 +1,294 @@
|
||||
---
|
||||
name: 'step-08-validation'
|
||||
description: 'Validate architectural coherence and completeness'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-08-validation.md'
|
||||
nextStepFile: '{workflow_path}/steps/step-09-complete.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
checklistFile: '{workflow_path}/checklist.md'
|
||||
|
||||
# Task References
|
||||
advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
|
||||
partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
|
||||
---
|
||||
|
||||
# Step 8: Validation
|
||||
|
||||
**Progress: Step 8 of 9** - Next: Completion
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Validate that the architecture is coherent, complete, and ready to guide AI agent implementation. Check for conflicts, gaps, and missing coverage.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- Validation ensures document completeness
|
||||
- Catch gaps before implementation begins
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Run through all validation checks
|
||||
- Fix any issues before proceeding
|
||||
- User must confirm document is ready
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Present A/P/C menu after validation complete
|
||||
- ONLY proceed when user chooses C (Continue)
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]` before loading next step
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
- **A (Advanced Elicitation)**: Deep dive into gaps
|
||||
- **P (Party Mode)**: Get perspectives on completeness
|
||||
- **C (Continue)**: Confirm validation and proceed
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Load Validation Checklist
|
||||
|
||||
**Load the checklist if available:**
|
||||
|
||||
Load `{checklistFile}` for structured validation criteria.
|
||||
|
||||
### 2. Decision Compatibility Check
|
||||
|
||||
"**Checking Decision Compatibility...**
|
||||
|
||||
Verifying all architectural decisions work together:
|
||||
|
||||
| Check | Status | Notes |
|
||||
| ------------------------------ | ------------- | --------- |
|
||||
| Engine + patterns compatible | {{pass/fail}} | {{notes}} |
|
||||
| Cross-cutting + engine align | {{pass/fail}} | {{notes}} |
|
||||
| Structure supports all systems | {{pass/fail}} | {{notes}} |
|
||||
| No conflicting decisions | {{pass/fail}} | {{notes}} |
|
||||
|
||||
{{if_issues_found}}
|
||||
**Issues Found:**
|
||||
{{list_of_conflicts}}
|
||||
|
||||
How should we resolve these?
|
||||
{{/if_issues_found}}"
|
||||
|
||||
### 3. GDD Coverage Check
|
||||
|
||||
"**Checking GDD Coverage...**
|
||||
|
||||
Verifying every GDD requirement has architectural support:
|
||||
|
||||
**Core Systems:**
|
||||
| System | Architecture Support | Status |
|
||||
| ------ | -------------------- | ------ |
|
||||
{{systems_coverage_table}}
|
||||
|
||||
**Technical Requirements:**
|
||||
| Requirement | How Addressed | Status |
|
||||
| ----------- | ------------- | ------ |
|
||||
{{requirements_coverage_table}}
|
||||
|
||||
{{if_gaps_found}}
|
||||
**Gaps Found:**
|
||||
{{list_of_gaps}}
|
||||
|
||||
How should we address these?
|
||||
{{/if_gaps_found}}"
|
||||
|
||||
### 4. Pattern Completeness Check
|
||||
|
||||
"**Checking Pattern Completeness...**
|
||||
|
||||
Verifying implementation patterns cover all scenarios:
|
||||
|
||||
| Scenario | Pattern Defined | Status |
|
||||
| ----------------------- | --------------- | ---------- |
|
||||
| Entity creation | {{yes/no}} | {{status}} |
|
||||
| Component communication | {{yes/no}} | {{status}} |
|
||||
| State management | {{yes/no}} | {{status}} |
|
||||
| Error handling | {{yes/no}} | {{status}} |
|
||||
| Data access | {{yes/no}} | {{status}} |
|
||||
| Event handling | {{yes/no}} | {{status}} |
|
||||
|
||||
{{if_missing_patterns}}
|
||||
**Missing Patterns:**
|
||||
{{list_of_missing}}
|
||||
|
||||
Should we define these now?
|
||||
{{/if_missing_patterns}}"
|
||||
|
||||
### 5. Epic Mapping Check
|
||||
|
||||
"**Checking Epic Mapping...**
|
||||
|
||||
Verifying every epic/feature maps to architecture:
|
||||
|
||||
| Epic/Feature | Location | Patterns | Status |
|
||||
| ------------ | -------- | -------- | ------ |
|
||||
|
||||
{{epic_mapping_table}}
|
||||
|
||||
{{if_unmapped_epics}}
|
||||
**Unmapped Features:**
|
||||
{{list_of_unmapped}}
|
||||
|
||||
Where should these live?
|
||||
{{/if_unmapped_epics}}"
|
||||
|
||||
### 6. Document Completeness Check
|
||||
|
||||
"**Checking Document Completeness...**
|
||||
|
||||
Mandatory sections:
|
||||
|
||||
- [ ] Engine/Framework selection with version
|
||||
- [ ] Decision summary table
|
||||
- [ ] Project structure (complete, not placeholder)
|
||||
- [ ] Cross-cutting concerns
|
||||
- [ ] Implementation patterns with examples
|
||||
- [ ] Naming conventions
|
||||
- [ ] No placeholder text ({{placeholders}}, TODO, etc.)
|
||||
|
||||
{{if_incomplete}}
|
||||
**Incomplete Sections:**
|
||||
{{list_of_incomplete}}
|
||||
|
||||
Let's fix these before proceeding.
|
||||
{{/if_incomplete}}"
|
||||
|
||||
### 7. Resolve Any Issues
|
||||
|
||||
**If issues were found in any check:**
|
||||
|
||||
For each issue:
|
||||
|
||||
1. Present the problem clearly
|
||||
2. Propose a solution
|
||||
3. Get user confirmation
|
||||
4. Update the document
|
||||
|
||||
**Repeat validation if significant changes made.**
|
||||
|
||||
### 8. Generate Validation Summary
|
||||
|
||||
Based on the checks, prepare the summary:
|
||||
|
||||
```markdown
|
||||
## Architecture Validation
|
||||
|
||||
### Validation Summary
|
||||
|
||||
| Check | Result | Notes |
|
||||
| ---------------------- | ------------- | --------- |
|
||||
| Decision Compatibility | {{pass/fail}} | {{notes}} |
|
||||
| GDD Coverage | {{pass/fail}} | {{notes}} |
|
||||
| Pattern Completeness | {{pass/fail}} | {{notes}} |
|
||||
| Epic Mapping | {{pass/fail}} | {{notes}} |
|
||||
| Document Completeness | {{pass/fail}} | {{notes}} |
|
||||
|
||||
### Coverage Report
|
||||
|
||||
**Systems Covered:** {{count}}/{{total}}
|
||||
**Patterns Defined:** {{count}}
|
||||
**Decisions Made:** {{count}}
|
||||
|
||||
### Issues Resolved
|
||||
|
||||
{{list_of_resolved_issues}}
|
||||
|
||||
### Validation Date
|
||||
|
||||
{{date}}
|
||||
```
|
||||
|
||||
### 9. Present Validation and Menu
|
||||
|
||||
Show the validation results to the user and present:
|
||||
|
||||
"**Architecture Validation Complete**
|
||||
|
||||
**Results:**
|
||||
|
||||
[Show validation summary]
|
||||
|
||||
**Overall Status:** {{PASS/NEEDS_WORK}}
|
||||
|
||||
{{if_pass}}
|
||||
Your architecture document is complete and ready to guide implementation.
|
||||
{{/if_pass}}
|
||||
|
||||
{{if_needs_work}}
|
||||
Some issues need resolution before the architecture is ready.
|
||||
{{/if_needs_work}}
|
||||
|
||||
**Select an Option:**
|
||||
[A] Advanced Elicitation - Deep dive into any gaps
|
||||
[P] Party Mode - Get perspectives on completeness
|
||||
[C] Continue - Save validation and move to Completion (Step 9 of 9)"
|
||||
|
||||
### 10. Handle Menu Selection
|
||||
|
||||
#### IF A (Advanced Elicitation):
|
||||
|
||||
- Execute {advancedElicitationTask} with validation results
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, re-run validation
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF P (Party Mode):
|
||||
|
||||
- Execute {partyModeWorkflow} with validation results
|
||||
- Ask user: "Accept these changes? (y/n)"
|
||||
- If yes: Update content, re-run validation
|
||||
- If no: Keep original, return to A/P/C menu
|
||||
|
||||
#### IF C (Continue):
|
||||
|
||||
- Append validation summary to `{outputFile}`
|
||||
- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]`
|
||||
- Load `{nextStepFile}`
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN [C continue option] is selected and [validation content saved with frontmatter updated], will you then load and read fully `{nextStepFile}`.
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- All validation checks performed
|
||||
- Issues identified and resolved
|
||||
- GDD coverage verified
|
||||
- Pattern completeness confirmed
|
||||
- Document has no placeholders
|
||||
- A/P/C menu presented and handled correctly
|
||||
- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Skipping validation checks
|
||||
- Proceeding with unresolved issues
|
||||
- Incomplete document going to completion
|
||||
- Not presenting A/P/C menu after validation
|
||||
- Proceeding without user selecting 'C'
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
@@ -0,0 +1,357 @@
|
||||
---
|
||||
name: 'step-09-complete'
|
||||
description: 'Complete the architecture workflow with final review and handoff guidance'
|
||||
|
||||
# Path Definitions
|
||||
workflow_path: '{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture'
|
||||
|
||||
# File References
|
||||
thisStepFile: '{workflow_path}/steps/step-09-complete.md'
|
||||
workflowFile: '{workflow_path}/workflow.md'
|
||||
outputFile: '{output_folder}/game-architecture.md'
|
||||
|
||||
# Handoff References
|
||||
epicWorkflow: '{project-root}/_bmad/bmgd/workflows/4-production/epic-workflow/workflow.yaml'
|
||||
projectContextWorkflow: '{project-root}/_bmad/bmgd/workflows/3-technical/generate-project-context/workflow.md'
|
||||
---
|
||||
|
||||
# Step 9: Completion
|
||||
|
||||
**Progress: Step 9 of 9** - Architecture Complete!
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Generate the executive summary, finalize the document, update workflow status, and provide clear handoff guidance for the next workflow phase.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- NEVER generate content without user input
|
||||
- CRITICAL: Read the complete step file before taking any action
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- NEVER mention time estimates
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- You are a veteran game architect facilitator
|
||||
- This is the final step - ensure completeness
|
||||
- Provide actionable next steps
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- Generate executive summary from all content
|
||||
- Ensure document is ready for AI agent consumption
|
||||
- Provide clear implementation guidance
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Generate final sections
|
||||
- Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9]`
|
||||
- Present completion summary and next steps
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Generate Executive Summary
|
||||
|
||||
**Create summary from all sections:**
|
||||
|
||||
Based on all documented content, synthesize an executive summary:
|
||||
|
||||
```markdown
|
||||
## Executive Summary
|
||||
|
||||
**{{game_name}}** architecture is designed for {{engine}} targeting {{platform}}.
|
||||
|
||||
**Key Architectural Decisions:**
|
||||
|
||||
- {{decision_1_summary}}
|
||||
- {{decision_2_summary}}
|
||||
- {{decision_3_summary}}
|
||||
|
||||
**Project Structure:** {{organization_pattern}} organization with {{system_count}} core systems.
|
||||
|
||||
**Implementation Patterns:** {{pattern_count}} patterns defined ensuring AI agent consistency.
|
||||
|
||||
**Ready for:** Epic implementation phase
|
||||
```
|
||||
|
||||
### 2. Generate Development Setup Section
|
||||
|
||||
"Let me generate the development environment setup section.
|
||||
|
||||
**Development Prerequisites:**
|
||||
|
||||
````markdown
|
||||
## Development Environment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
{{prerequisites_list}}
|
||||
|
||||
### Setup Commands
|
||||
|
||||
```bash
|
||||
{{setup_commands}}
|
||||
```
|
||||
````
|
||||
|
||||
### First Steps
|
||||
|
||||
1. {{first_step}}
|
||||
2. {{second_step}}
|
||||
3. {{third_step}}
|
||||
|
||||
````
|
||||
|
||||
Does this capture the setup process correctly?"
|
||||
|
||||
### 3. Finalize Document
|
||||
|
||||
**Update the document with final content:**
|
||||
|
||||
- Add Executive Summary at the top (after frontmatter)
|
||||
- Add Development Environment section
|
||||
- Update document status to 'complete'
|
||||
- Update frontmatter with all steps completed
|
||||
|
||||
**Final frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: 'Game Architecture'
|
||||
project: '{{project_name}}'
|
||||
date: '{{date}}'
|
||||
author: '{{user_name}}'
|
||||
version: '1.0'
|
||||
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8, 9]
|
||||
status: 'complete'
|
||||
engine: '{{engine}}'
|
||||
platform: '{{platform}}'
|
||||
---
|
||||
````
|
||||
|
||||
### 4. Update Workflow Status
|
||||
|
||||
**If not in standalone mode:**
|
||||
|
||||
Load `{output_folder}/bmgd-workflow-status.yaml` and:
|
||||
|
||||
- Update `create-architecture` status to the output file path
|
||||
- Preserve all comments and structure
|
||||
- Determine next workflow in sequence
|
||||
|
||||
### 5. Present Completion Summary
|
||||
|
||||
"**Architecture Complete!**
|
||||
|
||||
{{user_name}}, the Game Architecture for **{{game_name}}** is now complete!
|
||||
|
||||
**Architecture Summary:**
|
||||
|
||||
- **Engine:** {{engine}} v{{version}}
|
||||
- **Platform:** {{platform}}
|
||||
- **Organization:** {{organization_pattern}}
|
||||
- **Decisions Made:** {{decision_count}}
|
||||
- **Patterns Defined:** {{pattern_count}}
|
||||
|
||||
**Sections Completed:**
|
||||
|
||||
1. Project Context
|
||||
2. Engine & Framework
|
||||
3. Architectural Decisions
|
||||
4. Cross-cutting Concerns
|
||||
5. Project Structure
|
||||
6. Implementation Patterns
|
||||
7. Validation
|
||||
8. Development Setup
|
||||
|
||||
**Document saved to:** `{outputFile}`
|
||||
|
||||
Do you want to review or adjust anything before we finalize?
|
||||
|
||||
**Optional Enhancement: Project Context File**
|
||||
|
||||
Would you like to create a `project-context.md` file? This is a concise, optimized guide for AI agents that captures:
|
||||
|
||||
- Critical engine-specific rules they might miss
|
||||
- Specific patterns and conventions for your game project
|
||||
- Performance and optimization requirements
|
||||
- Anti-patterns and edge cases to avoid
|
||||
|
||||
{if_existing_project_context}
|
||||
I noticed you already have a project context file. Would you like to update it with your new architectural decisions?
|
||||
{else}
|
||||
This file helps ensure AI agents implement game code consistently with your project's unique requirements and patterns.
|
||||
{/if_existing_project_context}
|
||||
|
||||
**Create/Update project context?** [Y/N]"
|
||||
|
||||
### 6. Handle Project Context Creation Choice
|
||||
|
||||
If user responds 'Y' or 'yes' to creating/updating project context:
|
||||
|
||||
"Excellent choice! Let me launch the Generate Project Context workflow to create a comprehensive guide for AI agents.
|
||||
|
||||
This will help ensure consistent implementation by capturing:
|
||||
|
||||
- Engine-specific patterns and rules
|
||||
- Performance and optimization conventions from your architecture
|
||||
- Testing and quality standards
|
||||
- Anti-patterns to avoid
|
||||
|
||||
The workflow will collaborate with you to create an optimized `project-context.md` file that AI agents will read before implementing any game code."
|
||||
|
||||
**Execute the Generate Project Context workflow:**
|
||||
|
||||
- Load and execute: `{projectContextWorkflow}`
|
||||
- The workflow will handle discovery, generation, and completion of the project context file
|
||||
- After completion, return here for final handoff
|
||||
|
||||
If user responds 'N' or 'no':
|
||||
"Understood! Your architecture is complete and ready for implementation. You can always create a project context file later using the Generate Project Context workflow if needed."
|
||||
|
||||
### 7. Handle Review Requests
|
||||
|
||||
**If user wants to review:**
|
||||
|
||||
"Which section would you like to review?
|
||||
|
||||
1. Executive Summary
|
||||
2. Engine & Framework
|
||||
3. Architectural Decisions
|
||||
4. Cross-cutting Concerns
|
||||
5. Project Structure
|
||||
6. Implementation Patterns
|
||||
7. Validation Summary
|
||||
8. Development Setup
|
||||
|
||||
Or type 'all' to see the complete document."
|
||||
|
||||
**Show requested section and allow edits.**
|
||||
|
||||
### 8. Present Next Steps Menu
|
||||
|
||||
**After user confirms completion:**
|
||||
|
||||
"**Recommended Next Steps for {{game_name}}:**
|
||||
|
||||
1. **Initialize Project** - Run the setup commands to create your project
|
||||
- Command: `{{setup_command}}`
|
||||
- This creates the base structure we designed
|
||||
|
||||
2. **Create Epics** - Break down GDD into implementation epics
|
||||
- Workflow: `create-epics`
|
||||
- Input: GDD + Architecture
|
||||
- Output: Implementation-ready epic stories
|
||||
|
||||
3. **Begin Implementation** - Start coding with AI agents
|
||||
- Each agent will read this architecture
|
||||
- Patterns ensure consistency across all code
|
||||
|
||||
**Which would you like to do next?**
|
||||
|
||||
1. Review the completed architecture
|
||||
2. Proceed to Epic creation workflow
|
||||
3. Exit workflow"
|
||||
|
||||
### 9. Handle User Selection
|
||||
|
||||
Based on user choice:
|
||||
|
||||
**If 1 (Review):**
|
||||
|
||||
- Present full document or requested section
|
||||
- Return to next steps menu
|
||||
|
||||
**If 2 (Epic Creation):**
|
||||
|
||||
- Confirm architecture is saved
|
||||
- Provide handoff guidance for epic workflow
|
||||
- Note that architecture document will be input
|
||||
|
||||
**If 3 (Exit):**
|
||||
|
||||
- Confirm document is saved and complete
|
||||
- Exit workflow gracefully
|
||||
|
||||
### 10. Provide Handoff Guidance
|
||||
|
||||
**For Epic Creation handoff:**
|
||||
|
||||
"**Handoff to Epic Creation**
|
||||
|
||||
Your architecture is ready to guide epic creation.
|
||||
|
||||
**What the Epic workflow will do:**
|
||||
|
||||
- Read your architecture document
|
||||
- Break GDD features into implementable stories
|
||||
- Ensure stories align with architectural patterns
|
||||
- Create acceptance criteria referencing architecture
|
||||
|
||||
**Architecture inputs that will be used:**
|
||||
|
||||
- Project structure for file placement
|
||||
- Implementation patterns for code style
|
||||
- Cross-cutting concerns for consistency
|
||||
- System mapping for story assignment
|
||||
|
||||
Ready to proceed to epic creation, or any questions about the architecture?"
|
||||
|
||||
---
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
This is the final step. Ensure:
|
||||
|
||||
- Executive summary is generated
|
||||
- All content is saved to architecture.md
|
||||
- Frontmatter shows all 9 steps completed
|
||||
- User has clear actionable next steps
|
||||
- Handoff to epic workflow is smooth
|
||||
|
||||
---
|
||||
|
||||
## SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### SUCCESS:
|
||||
|
||||
- Executive summary synthesizes all content
|
||||
- Development setup is complete
|
||||
- Document status updated to 'complete'
|
||||
- Frontmatter shows all steps completed
|
||||
- Workflow status updated (if tracking)
|
||||
- User has clear next steps
|
||||
- Document saved and ready for AI agent consumption
|
||||
|
||||
### SYSTEM FAILURE:
|
||||
|
||||
- Missing executive summary
|
||||
- Incomplete development setup
|
||||
- Frontmatter not updated
|
||||
- Status not updated when tracking
|
||||
- No clear next steps provided
|
||||
- User left without actionable guidance
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
|
||||
---
|
||||
|
||||
## Game Architecture Workflow Complete
|
||||
|
||||
The Game Architecture workflow transforms a GDD into a comprehensive architecture document through 9 collaborative steps:
|
||||
|
||||
1. **Initialize** - Validate readiness, discover input documents
|
||||
2. **Context** - Load and understand project requirements
|
||||
3. **Starter** - Select engine and starter templates
|
||||
4. **Decisions** - Make collaborative architectural decisions
|
||||
5. **Cross-cutting** - Define patterns for all systems
|
||||
6. **Structure** - Define project organization
|
||||
7. **Patterns** - Design implementation patterns
|
||||
8. **Validation** - Verify completeness and coherence
|
||||
9. **Complete** - Finalize and provide handoff
|
||||
|
||||
This step-file architecture ensures consistent, thorough architecture creation with user collaboration at every step.
|
||||
+103
@@ -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,56 @@
|
||||
# Game Architecture Workflow
|
||||
|
||||
**Collaborative game architecture workflow for AI-agent consistency**
|
||||
|
||||
## Overview
|
||||
|
||||
This workflow facilitates the creation of a decision-focused game architecture document covering engine selection, systems design, networking, and technical patterns - optimized for game development with AI agents.
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
The workflow uses a step-file architecture for modular, stateful execution:
|
||||
|
||||
1. **Step 1: Initialize** - Validate readiness and discover input documents
|
||||
2. **Step 1b: Continue** - Resume existing architecture work
|
||||
3. **Step 2: Context** - Load and understand project context from GDD/Epics
|
||||
4. **Step 3: Starter** - Discover and evaluate game engine/starter templates
|
||||
5. **Step 4: Decisions** - Facilitate collaborative architectural decisions
|
||||
6. **Step 5: Cross-cutting** - Address cross-cutting concerns
|
||||
7. **Step 6: Structure** - Define project structure and boundaries
|
||||
8. **Step 7: Patterns** - Design novel and implementation patterns
|
||||
9. **Step 8: Validation** - Validate architectural coherence
|
||||
10. **Step 9: Complete** - Final review and workflow completion
|
||||
|
||||
## State Tracking
|
||||
|
||||
Progress is tracked in the architecture document frontmatter:
|
||||
|
||||
```yaml
|
||||
stepsCompleted: [1, 2, 3, ...] # Array of completed step numbers
|
||||
```
|
||||
|
||||
## Starting the Workflow
|
||||
|
||||
To begin, load and execute step-01-init.md:
|
||||
|
||||
```
|
||||
{workflow_path}/steps/step-01-init.md
|
||||
```
|
||||
|
||||
## Critical Rules
|
||||
|
||||
- **NEVER** generate architectural decisions without user input
|
||||
- **ALWAYS** verify current versions via web search
|
||||
- **NEVER** mention time estimates
|
||||
- **ALWAYS** present options and wait for user selection
|
||||
- **FOLLOW** the step sequence exactly - no skipping or optimizing
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## Agent Role
|
||||
|
||||
You are a veteran game architect facilitator:
|
||||
|
||||
- Focus on decisions that prevent AI agent conflicts
|
||||
- Push for specificity in all technical choices
|
||||
- Ensure every epic has architectural support
|
||||
- Document patterns that ensure consistent implementation
|
||||
@@ -0,0 +1,70 @@
|
||||
# Game Architecture Workflow Configuration
|
||||
name: game-architecture
|
||||
description: "Collaborative game architecture workflow for AI-agent consistency. Intelligent, adaptive conversation that produces a decision-focused game architecture document covering engine, systems, networking, and technical design optimized for game development."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables
|
||||
config_source: "{project-root}/_bmad/bmgd/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"
|
||||
game_dev_experience: "{config_source}:game_dev_experience"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components - Step-file architecture
|
||||
installed_path: "{project-root}/_bmad/bmgd/workflows/3-technical/game-architecture"
|
||||
instructions: "{installed_path}/workflow.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/templates/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"
|
||||
|
||||
# Smart input file references - handles both whole docs and sharded docs
|
||||
input_file_patterns:
|
||||
gdd:
|
||||
description: "Game Design Document with mechanics and systems"
|
||||
whole: "{output_folder}/*gdd*.md"
|
||||
sharded: "{output_folder}/*gdd*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
|
||||
epics:
|
||||
description: "Epic definitions with user stories"
|
||||
whole: "{output_folder}/*epic*.md"
|
||||
sharded: "{output_folder}/*epic*/index.md"
|
||||
load_strategy: "FULL_LOAD"
|
||||
|
||||
brief:
|
||||
description: "Game Brief with vision and scope (optional)"
|
||||
whole: "{output_folder}/*brief*.md"
|
||||
sharded: "{output_folder}/*brief*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
|
||||
narrative:
|
||||
description: "Narrative design with story and characters (optional)"
|
||||
whole: "{output_folder}/*narrative*.md"
|
||||
sharded: "{output_folder}/*narrative*/index.md"
|
||||
load_strategy: "INDEX_GUIDED"
|
||||
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/game-architecture.md"
|
||||
|
||||
# Workflow metadata
|
||||
version: "2.0.0"
|
||||
replaces: "architecture"
|
||||
paradigm: "step-file-architecture"
|
||||
features:
|
||||
- "Step-file architecture for modular execution"
|
||||
- "Starter template discovery and integration"
|
||||
- "Dynamic version verification via web search"
|
||||
- "Adaptive facilitation by skill level"
|
||||
- "Decision-focused architecture"
|
||||
- "Novel pattern design for unique concepts"
|
||||
- "Intelligent pattern identification"
|
||||
- "Implementation patterns for agent consistency"
|
||||
- "State tracking via frontmatter"
|
||||
|
||||
standalone: true
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
project_name: '{{project_name}}'
|
||||
user_name: '{{user_name}}'
|
||||
date: '{{date}}'
|
||||
sections_completed: []
|
||||
---
|
||||
|
||||
# Project Context for AI Agents
|
||||
|
||||
_This file contains critical rules and patterns that AI agents must follow when implementing game code in this project. Focus on unobvious details that agents might otherwise miss._
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack & Versions
|
||||
|
||||
_Documented after discovery phase_
|
||||
|
||||
## Critical Implementation Rules
|
||||
|
||||
_Documented after discovery phase_
|
||||
@@ -0,0 +1,202 @@
|
||||
# Step 1: Context Discovery & Initialization
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- NEVER generate content without user input
|
||||
- ALWAYS treat this as collaborative discovery between technical peers
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- FOCUS on discovering existing project context and technology stack
|
||||
- IDENTIFY critical implementation rules that AI agents need
|
||||
- ABSOLUTELY NO TIME ESTIMATES
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Read existing project files to understand current context
|
||||
- Initialize document and update frontmatter
|
||||
- FORBIDDEN to load next step until discovery is complete
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Variables from workflow.md are available in memory
|
||||
- Focus on existing project files and architecture decisions
|
||||
- Look for patterns, conventions, and unique requirements
|
||||
- Prioritize rules that prevent implementation mistakes
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Discover the project's game engine, technology stack, existing patterns, and critical implementation rules that AI agents must follow when writing game code.
|
||||
|
||||
## DISCOVERY SEQUENCE:
|
||||
|
||||
### 1. Check for Existing Project Context
|
||||
|
||||
First, check if project context already exists:
|
||||
|
||||
- Look for file at `{output_folder}/project-context.md`
|
||||
- If exists: Read complete file to understand existing rules
|
||||
- Present to user: "Found existing project context with {number_of_sections} sections. Would you like to update this or create a new one?"
|
||||
|
||||
### 2. Discover Game Engine & Technology Stack
|
||||
|
||||
Load and analyze project files to identify technologies:
|
||||
|
||||
**Architecture Document:**
|
||||
|
||||
- Look for `{output_folder}/game-architecture.md` or `{planning_artifacts}/architecture.md`
|
||||
- Extract engine choice with specific version (Unity, Unreal, Godot, custom)
|
||||
- Note architectural decisions that affect implementation
|
||||
|
||||
**Engine-Specific Files:**
|
||||
|
||||
- Unity: Check for `ProjectSettings/ProjectVersion.txt`, `Packages/manifest.json`
|
||||
- Unreal: Check for `.uproject` files, `Config/DefaultEngine.ini`
|
||||
- Godot: Check for `project.godot`, `export_presets.cfg`
|
||||
- Custom: Check for engine config files, build scripts
|
||||
|
||||
**Package/Dependency Files:**
|
||||
|
||||
- Unity: `Packages/manifest.json`, NuGet packages
|
||||
- Unreal: `.Build.cs` files, plugin configs
|
||||
- Godot: `addons/` directory, GDExtension configs
|
||||
- Web-based: `package.json`, `requirements.txt`
|
||||
|
||||
**Configuration Files:**
|
||||
|
||||
- Build tool configs
|
||||
- Linting and formatting configs
|
||||
- Testing configurations
|
||||
- CI/CD pipeline configs
|
||||
|
||||
### 3. Identify Existing Code Patterns
|
||||
|
||||
Search through existing codebase for patterns:
|
||||
|
||||
**Naming Conventions:**
|
||||
|
||||
- Script/class naming patterns
|
||||
- Asset naming conventions
|
||||
- Scene/level naming patterns
|
||||
- Test file naming patterns
|
||||
|
||||
**Code Organization:**
|
||||
|
||||
- How components/scripts are structured
|
||||
- Where utilities and helpers are placed
|
||||
- How systems are organized
|
||||
- Folder hierarchy patterns
|
||||
|
||||
**Engine-Specific Patterns:**
|
||||
|
||||
- Unity: MonoBehaviour patterns, ScriptableObject usage, serialization rules
|
||||
- Unreal: Actor/Component patterns, Blueprint integration, UE macros
|
||||
- Godot: Node patterns, signal usage, autoload patterns
|
||||
|
||||
### 4. Extract Critical Implementation Rules
|
||||
|
||||
Look for rules that AI agents might miss:
|
||||
|
||||
**Engine-Specific Rules:**
|
||||
|
||||
- Unity: Assembly definitions, Unity lifecycle methods, coroutine patterns
|
||||
- Unreal: UPROPERTY/UFUNCTION usage, garbage collection rules, tick patterns
|
||||
- Godot: `_ready` vs `_enter_tree`, node ownership, scene instancing
|
||||
|
||||
**Performance Rules:**
|
||||
|
||||
- Frame budget constraints
|
||||
- Memory allocation patterns
|
||||
- Hot path optimization requirements
|
||||
- Object pooling patterns
|
||||
|
||||
**Platform-Specific Rules:**
|
||||
|
||||
- Target platform constraints
|
||||
- Input handling conventions
|
||||
- Platform-specific code patterns
|
||||
- Build configuration rules
|
||||
|
||||
**Testing Rules:**
|
||||
|
||||
- Test structure requirements
|
||||
- Mock usage conventions
|
||||
- Integration vs unit test boundaries
|
||||
- Play mode vs edit mode testing
|
||||
|
||||
### 5. Initialize Project Context Document
|
||||
|
||||
Based on discovery, create or update the context document:
|
||||
|
||||
#### A. Fresh Document Setup (if no existing context)
|
||||
|
||||
Copy template from `{installed_path}/project-context-template.md` to `{output_folder}/project-context.md`
|
||||
Initialize frontmatter with:
|
||||
|
||||
```yaml
|
||||
---
|
||||
project_name: '{{project_name}}'
|
||||
user_name: '{{user_name}}'
|
||||
date: '{{date}}'
|
||||
sections_completed: ['technology_stack']
|
||||
existing_patterns_found: { { number_of_patterns_discovered } }
|
||||
---
|
||||
```
|
||||
|
||||
#### B. Existing Document Update
|
||||
|
||||
Load existing context and prepare for updates
|
||||
Set frontmatter `sections_completed` to track what will be updated
|
||||
|
||||
### 6. Present Discovery Summary
|
||||
|
||||
Report findings to user:
|
||||
|
||||
"Welcome {{user_name}}! I've analyzed your game project for {{project_name}} to discover the context that AI agents need.
|
||||
|
||||
**Game Engine & Stack Discovered:**
|
||||
{{engine_and_version}}
|
||||
{{list_of_technologies_with_versions}}
|
||||
|
||||
**Existing Patterns Found:**
|
||||
|
||||
- {{number_of_patterns}} implementation patterns
|
||||
- {{number_of_conventions}} coding conventions
|
||||
- {{number_of_rules}} critical rules
|
||||
|
||||
**Key Areas for Context Rules:**
|
||||
|
||||
- {{area_1}} (e.g., Engine lifecycle and patterns)
|
||||
- {{area_2}} (e.g., Performance and optimization)
|
||||
- {{area_3}} (e.g., Platform-specific requirements)
|
||||
|
||||
{if_existing_context}
|
||||
**Existing Context:** Found {{sections}} sections already defined. We can update or add to these.
|
||||
{/if_existing_context}
|
||||
|
||||
Ready to create/update your project context. This will help AI agents implement game code consistently with your project's standards.
|
||||
|
||||
[C] Continue to context generation"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
- Existing project context properly detected and handled
|
||||
- Game engine and technology stack accurately identified with versions
|
||||
- Critical implementation patterns discovered
|
||||
- Project context document properly initialized
|
||||
- Discovery findings clearly presented to user
|
||||
- User ready to proceed with context generation
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
- Not checking for existing project context before creating new one
|
||||
- Missing critical engine versions or configurations
|
||||
- Overlooking important coding patterns or conventions
|
||||
- Not initializing frontmatter properly
|
||||
- Not presenting clear discovery summary to user
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After user selects [C] to continue, load `./step-02-generate.md` to collaboratively generate the specific project context rules.
|
||||
|
||||
Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and discovery is confirmed!
|
||||
@@ -0,0 +1,374 @@
|
||||
# Step 2: Context Rules Generation
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- NEVER generate content without user input
|
||||
- ALWAYS treat this as collaborative discovery between technical peers
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- FOCUS on unobvious rules that AI agents need to be reminded of
|
||||
- KEEP CONTENT LEAN - optimize for LLM context efficiency
|
||||
- ABSOLUTELY NO TIME ESTIMATES
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Focus on specific, actionable rules rather than general advice
|
||||
- Present A/P/C menu after each major rule category
|
||||
- ONLY save when user chooses C (Continue)
|
||||
- Update frontmatter with completed sections
|
||||
- FORBIDDEN to load next step until all sections are complete
|
||||
|
||||
## COLLABORATION MENUS (A/P/C):
|
||||
|
||||
This step will generate content and present choices for each rule category:
|
||||
|
||||
- **A (Advanced Elicitation)**: Use discovery protocols to explore nuanced implementation rules
|
||||
- **P (Party Mode)**: Bring multiple perspectives to identify critical edge cases
|
||||
- **C (Continue)**: Save the current rules and proceed to next category
|
||||
|
||||
## PROTOCOL INTEGRATION:
|
||||
|
||||
- When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
|
||||
- When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode
|
||||
- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
|
||||
- User accepts/rejects protocol changes before proceeding
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Discovery results from step-1 are available
|
||||
- Game engine and existing patterns are identified
|
||||
- Focus on rules that prevent implementation mistakes
|
||||
- Prioritize unobvious details that AI agents might miss
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Collaboratively generate specific, critical rules that AI agents must follow when implementing game code in this project.
|
||||
|
||||
## CONTEXT GENERATION SEQUENCE:
|
||||
|
||||
### 1. Technology Stack & Versions
|
||||
|
||||
Document the exact technology stack from discovery:
|
||||
|
||||
**Core Technologies:**
|
||||
Based on user skill level, present findings:
|
||||
|
||||
**Expert Mode:**
|
||||
"Technology stack from your architecture and project files:
|
||||
{{exact_technologies_with_versions}}
|
||||
|
||||
Any critical version constraints I should document for agents?"
|
||||
|
||||
**Intermediate Mode:**
|
||||
"I found your technology stack:
|
||||
|
||||
**Game Engine:**
|
||||
{{engine_with_version}}
|
||||
|
||||
**Key Dependencies:**
|
||||
{{important_dependencies_with_versions}}
|
||||
|
||||
Are there any version constraints or compatibility notes agents should know about?"
|
||||
|
||||
**Beginner Mode:**
|
||||
"Here are the technologies you're using:
|
||||
|
||||
**Game Engine:**
|
||||
{{friendly_description_of_engine}}
|
||||
|
||||
**Important Notes:**
|
||||
{{key_things_agents_need_to_know_about_versions}}
|
||||
|
||||
Should I document any special version rules or compatibility requirements?"
|
||||
|
||||
### 2. Engine-Specific Rules
|
||||
|
||||
Focus on unobvious engine patterns agents might miss:
|
||||
|
||||
**Unity Rules (if applicable):**
|
||||
"Based on your Unity project, I notice some specific patterns:
|
||||
|
||||
**Lifecycle Rules:**
|
||||
{{unity_lifecycle_patterns}}
|
||||
|
||||
**Serialization Rules:**
|
||||
{{serialization_requirements}}
|
||||
|
||||
**Assembly Definitions:**
|
||||
{{assembly_definition_rules}}
|
||||
|
||||
**Coroutine/Async Patterns:**
|
||||
{{async_patterns}}
|
||||
|
||||
Are these patterns correct? Any other Unity-specific rules agents should follow?"
|
||||
|
||||
**Unreal Rules (if applicable):**
|
||||
"Based on your Unreal project, I notice some specific patterns:
|
||||
|
||||
**UPROPERTY/UFUNCTION Rules:**
|
||||
{{macro_usage_patterns}}
|
||||
|
||||
**Blueprint Integration:**
|
||||
{{blueprint_rules}}
|
||||
|
||||
**Garbage Collection:**
|
||||
{{gc_patterns}}
|
||||
|
||||
**Tick Patterns:**
|
||||
{{tick_optimization_rules}}
|
||||
|
||||
Are these patterns correct? Any other Unreal-specific rules agents should follow?"
|
||||
|
||||
**Godot Rules (if applicable):**
|
||||
"Based on your Godot project, I notice some specific patterns:
|
||||
|
||||
**Node Lifecycle:**
|
||||
{{node_lifecycle_patterns}}
|
||||
|
||||
**Signal Usage:**
|
||||
{{signal_conventions}}
|
||||
|
||||
**Scene Instancing:**
|
||||
{{scene_patterns}}
|
||||
|
||||
**Autoload Patterns:**
|
||||
{{autoload_rules}}
|
||||
|
||||
Are these patterns correct? Any other Godot-specific rules agents should follow?"
|
||||
|
||||
### 3. Performance Rules
|
||||
|
||||
Document performance-critical patterns:
|
||||
|
||||
**Frame Budget Rules:**
|
||||
"Your game has these performance requirements:
|
||||
|
||||
**Target Frame Rate:**
|
||||
{{target_fps}}
|
||||
|
||||
**Frame Budget:**
|
||||
{{milliseconds_per_frame}}
|
||||
|
||||
**Critical Systems:**
|
||||
{{systems_that_must_meet_budget}}
|
||||
|
||||
**Hot Path Rules:**
|
||||
{{hot_path_patterns}}
|
||||
|
||||
Any other performance rules agents must follow?"
|
||||
|
||||
**Memory Management:**
|
||||
"Memory patterns for your project:
|
||||
|
||||
**Allocation Rules:**
|
||||
{{allocation_patterns}}
|
||||
|
||||
**Pooling Requirements:**
|
||||
{{object_pooling_rules}}
|
||||
|
||||
**Asset Loading:**
|
||||
{{asset_loading_patterns}}
|
||||
|
||||
Are there memory constraints agents should know about?"
|
||||
|
||||
### 4. Code Organization Rules
|
||||
|
||||
Document project structure and organization:
|
||||
|
||||
**Folder Structure:**
|
||||
"Your project organization:
|
||||
|
||||
**Script Organization:**
|
||||
{{script_folder_structure}}
|
||||
|
||||
**Asset Organization:**
|
||||
{{asset_folder_patterns}}
|
||||
|
||||
**Scene/Level Organization:**
|
||||
{{scene_organization}}
|
||||
|
||||
Any organization rules agents must follow?"
|
||||
|
||||
**Naming Conventions:**
|
||||
"Your naming patterns:
|
||||
|
||||
**Script/Class Names:**
|
||||
{{class_naming_patterns}}
|
||||
|
||||
**Asset Names:**
|
||||
{{asset_naming_patterns}}
|
||||
|
||||
**Variable/Method Names:**
|
||||
{{variable_naming_patterns}}
|
||||
|
||||
Any other naming rules?"
|
||||
|
||||
### 5. Testing Rules
|
||||
|
||||
Focus on testing patterns that ensure consistency:
|
||||
|
||||
**Test Structure Rules:**
|
||||
"Your testing setup shows these patterns:
|
||||
|
||||
**Test Organization:**
|
||||
{{test_file_organization}}
|
||||
|
||||
**Test Categories:**
|
||||
{{unit_vs_integration_boundaries}}
|
||||
|
||||
**Mocking Patterns:**
|
||||
{{mock_usage_conventions}}
|
||||
|
||||
**Play Mode Testing:**
|
||||
{{play_mode_test_patterns}}
|
||||
|
||||
Are there testing rules agents should always follow?"
|
||||
|
||||
### 6. Platform & Build Rules
|
||||
|
||||
Document platform-specific requirements:
|
||||
|
||||
**Target Platforms:**
|
||||
"Your platform configuration:
|
||||
|
||||
**Primary Platform:**
|
||||
{{primary_platform}}
|
||||
|
||||
**Platform-Specific Code:**
|
||||
{{platform_conditional_patterns}}
|
||||
|
||||
**Build Configurations:**
|
||||
{{build_config_rules}}
|
||||
|
||||
**Input Handling:**
|
||||
{{input_abstraction_patterns}}
|
||||
|
||||
Any platform rules agents must know?"
|
||||
|
||||
### 7. Critical Don't-Miss Rules
|
||||
|
||||
Identify rules that prevent common mistakes:
|
||||
|
||||
**Anti-Patterns to Avoid:**
|
||||
"Based on your codebase, here are critical things agents must NOT do:
|
||||
|
||||
{{critical_anti_patterns_with_examples}}
|
||||
|
||||
**Edge Cases:**
|
||||
{{specific_edge_cases_agents_should_handle}}
|
||||
|
||||
**Common Gotchas:**
|
||||
{{engine_specific_gotchas}}
|
||||
|
||||
**Performance Traps:**
|
||||
{{performance_patterns_to_avoid}}
|
||||
|
||||
Are there other 'gotchas' agents should know about?"
|
||||
|
||||
### 8. Generate Context Content
|
||||
|
||||
For each category, prepare lean content for the project context file:
|
||||
|
||||
#### Content Structure:
|
||||
|
||||
```markdown
|
||||
## Technology Stack & Versions
|
||||
|
||||
{{concise_technology_list_with_exact_versions}}
|
||||
|
||||
## Critical Implementation Rules
|
||||
|
||||
### Engine-Specific Rules
|
||||
|
||||
{{bullet_points_of_engine_rules}}
|
||||
|
||||
### Performance Rules
|
||||
|
||||
{{bullet_points_of_performance_requirements}}
|
||||
|
||||
### Code Organization Rules
|
||||
|
||||
{{bullet_points_of_organization_patterns}}
|
||||
|
||||
### Testing Rules
|
||||
|
||||
{{bullet_points_of_testing_requirements}}
|
||||
|
||||
### Platform & Build Rules
|
||||
|
||||
{{bullet_points_of_platform_requirements}}
|
||||
|
||||
### Critical Don't-Miss Rules
|
||||
|
||||
{{bullet_points_of_anti_patterns_and_gotchas}}
|
||||
```
|
||||
|
||||
### 9. Present Content and Menu
|
||||
|
||||
After each category, show the generated rules and present choices:
|
||||
|
||||
"I've drafted the {{category_name}} rules for your project context.
|
||||
|
||||
**Here's what I'll add:**
|
||||
|
||||
[Show the complete markdown content for this category]
|
||||
|
||||
**What would you like to do?**
|
||||
[A] Advanced Elicitation - Explore nuanced rules for this category
|
||||
[P] Party Mode - Review from different implementation perspectives
|
||||
[C] Continue - Save these rules and move to next category"
|
||||
|
||||
### 10. Handle Menu Selection
|
||||
|
||||
#### If 'A' (Advanced Elicitation):
|
||||
|
||||
- Execute advanced-elicitation.xml with current category rules
|
||||
- Process enhanced rules that come back
|
||||
- Ask user: "Accept these enhanced rules for {{category}}? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
- If no: Keep original content, then return to A/P/C menu
|
||||
|
||||
#### If 'P' (Party Mode):
|
||||
|
||||
- Execute party-mode workflow with category rules context
|
||||
- Process collaborative insights on implementation patterns
|
||||
- Ask user: "Accept these changes to {{category}} rules? (y/n)"
|
||||
- If yes: Update content, then return to A/P/C menu
|
||||
- If no: Keep original content, then return to A/P/C menu
|
||||
|
||||
#### If 'C' (Continue):
|
||||
|
||||
- Save the current category content to project context file
|
||||
- Update frontmatter: `sections_completed: [...]`
|
||||
- Proceed to next category or step-03 if complete
|
||||
|
||||
## APPEND TO PROJECT CONTEXT:
|
||||
|
||||
When user selects 'C' for a category, append the content directly to `{output_folder}/project-context.md` using the structure from step 8.
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
- All critical technology versions accurately documented
|
||||
- Engine-specific rules cover unobvious patterns
|
||||
- Performance rules capture project-specific requirements
|
||||
- Code organization rules maintain project standards
|
||||
- Testing rules ensure consistent test quality
|
||||
- Platform rules prevent cross-platform issues
|
||||
- Content is lean and optimized for LLM context
|
||||
- A/P/C menu presented and handled correctly for each category
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
- Including obvious rules that agents already know
|
||||
- Making content too verbose for LLM context efficiency
|
||||
- Missing critical anti-patterns or edge cases
|
||||
- Not getting user validation for each rule category
|
||||
- Not documenting exact versions and configurations
|
||||
- Not presenting A/P/C menu after content generation
|
||||
|
||||
## NEXT STEP:
|
||||
|
||||
After completing all rule categories and user selects 'C' for the final category, load `./step-03-complete.md` to finalize the project context file.
|
||||
|
||||
Remember: Do NOT proceed to step-03 until all categories are complete and user explicitly selects 'C' for each!
|
||||
@@ -0,0 +1,280 @@
|
||||
# Step 3: Context Completion & Finalization
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
- NEVER generate content without user input
|
||||
- ALWAYS treat this as collaborative completion between technical peers
|
||||
- YOU ARE A FACILITATOR, not a content generator
|
||||
- FOCUS on finalizing a lean, LLM-optimized project context
|
||||
- ENSURE all critical rules are captured and actionable
|
||||
- ABSOLUTELY NO TIME ESTIMATES
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- Show your analysis before taking any action
|
||||
- Review and optimize content for LLM context efficiency
|
||||
- Update frontmatter with completion status
|
||||
- NO MORE STEPS - this is the final step
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- All rule categories from step-2 are complete
|
||||
- Technology stack and versions are documented
|
||||
- Focus on final review, optimization, and completion
|
||||
- Ensure the context file is ready for AI agent consumption
|
||||
|
||||
## YOUR TASK:
|
||||
|
||||
Complete the project context file, optimize it for LLM efficiency, and provide guidance for usage and maintenance.
|
||||
|
||||
## COMPLETION SEQUENCE:
|
||||
|
||||
### 1. Review Complete Context File
|
||||
|
||||
Read the entire project context file and analyze:
|
||||
|
||||
**Content Analysis:**
|
||||
|
||||
- Total length and readability for LLMs
|
||||
- Clarity and specificity of rules
|
||||
- Coverage of all critical areas
|
||||
- Actionability of each rule
|
||||
|
||||
**Structure Analysis:**
|
||||
|
||||
- Logical organization of sections
|
||||
- Consistency of formatting
|
||||
- Absence of redundant or obvious information
|
||||
- Optimization for quick scanning
|
||||
|
||||
### 2. Optimize for LLM Context
|
||||
|
||||
Ensure the file is lean and efficient:
|
||||
|
||||
**Content Optimization:**
|
||||
|
||||
- Remove any redundant rules or obvious information
|
||||
- Combine related rules into concise bullet points
|
||||
- Use specific, actionable language
|
||||
- Ensure each rule provides unique value
|
||||
|
||||
**Formatting Optimization:**
|
||||
|
||||
- Use consistent markdown formatting
|
||||
- Implement clear section hierarchy
|
||||
- Ensure scannability with strategic use of bolding
|
||||
- Maintain readability while maximizing information density
|
||||
|
||||
### 3. Final Content Structure
|
||||
|
||||
Ensure the final structure follows this optimized format:
|
||||
|
||||
```markdown
|
||||
# Project Context for AI Agents
|
||||
|
||||
_This file contains critical rules and patterns that AI agents must follow when implementing game code in this project. Focus on unobvious details that agents might otherwise miss._
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack & Versions
|
||||
|
||||
{{concise_technology_list}}
|
||||
|
||||
## Critical Implementation Rules
|
||||
|
||||
### Engine-Specific Rules
|
||||
|
||||
{{engine_rules}}
|
||||
|
||||
### Performance Rules
|
||||
|
||||
{{performance_requirements}}
|
||||
|
||||
### Code Organization Rules
|
||||
|
||||
{{organization_patterns}}
|
||||
|
||||
### Testing Rules
|
||||
|
||||
{{testing_requirements}}
|
||||
|
||||
### Platform & Build Rules
|
||||
|
||||
{{platform_requirements}}
|
||||
|
||||
### Critical Don't-Miss Rules
|
||||
|
||||
{{anti_patterns_and_gotchas}}
|
||||
|
||||
---
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
**For AI Agents:**
|
||||
|
||||
- Read this file before implementing any game code
|
||||
- Follow ALL rules exactly as documented
|
||||
- When in doubt, prefer the more restrictive option
|
||||
- Update this file if new patterns emerge
|
||||
|
||||
**For Humans:**
|
||||
|
||||
- Keep this file lean and focused on agent needs
|
||||
- Update when technology stack changes
|
||||
- Review quarterly for outdated rules
|
||||
- Remove rules that become obvious over time
|
||||
|
||||
Last Updated: {{date}}
|
||||
```
|
||||
|
||||
### 4. Present Completion Summary
|
||||
|
||||
Based on user skill level, present the completion:
|
||||
|
||||
**Expert Mode:**
|
||||
"Project context complete. Optimized for LLM consumption with {{rule_count}} critical rules across {{section_count}} sections.
|
||||
|
||||
File saved to: `{output_folder}/project-context.md`
|
||||
|
||||
Ready for AI agent integration."
|
||||
|
||||
**Intermediate Mode:**
|
||||
"Your project context is complete and optimized for AI agents!
|
||||
|
||||
**What we created:**
|
||||
|
||||
- {{rule_count}} critical implementation rules
|
||||
- Technology stack with exact versions
|
||||
- Engine-specific patterns and conventions
|
||||
- Performance and optimization guidelines
|
||||
- Testing and platform requirements
|
||||
|
||||
**Key benefits:**
|
||||
|
||||
- AI agents will implement consistently with your standards
|
||||
- Reduced context switching and implementation errors
|
||||
- Clear guidance for unobvious project requirements
|
||||
|
||||
**Next steps:**
|
||||
|
||||
- AI agents should read this file before implementing
|
||||
- Update as your project evolves
|
||||
- Review periodically for optimization"
|
||||
|
||||
**Beginner Mode:**
|
||||
"Excellent! Your project context guide is ready!
|
||||
|
||||
**What this does:**
|
||||
Think of this as a 'rules of the road' guide for AI agents working on your game. It ensures they all follow the same patterns and avoid common mistakes.
|
||||
|
||||
**What's included:**
|
||||
|
||||
- Exact engine and technology versions to use
|
||||
- Critical coding rules they might miss
|
||||
- Performance and optimization standards
|
||||
- Testing and platform requirements
|
||||
|
||||
**How AI agents use it:**
|
||||
They read this file before writing any code, ensuring everything they create follows your project's standards perfectly.
|
||||
|
||||
Your project context is saved and ready to help agents implement consistently!"
|
||||
|
||||
### 5. Final File Updates
|
||||
|
||||
Update the project context file with completion information:
|
||||
|
||||
**Frontmatter Update:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
project_name: '{{project_name}}'
|
||||
user_name: '{{user_name}}'
|
||||
date: '{{date}}'
|
||||
sections_completed:
|
||||
['technology_stack', 'engine_rules', 'performance_rules', 'organization_rules', 'testing_rules', 'platform_rules', 'anti_patterns']
|
||||
status: 'complete'
|
||||
rule_count: { { total_rules } }
|
||||
optimized_for_llm: true
|
||||
---
|
||||
```
|
||||
|
||||
**Add Usage Section:**
|
||||
Append the usage guidelines from step 3 to complete the document.
|
||||
|
||||
### 6. Completion Validation
|
||||
|
||||
Final checks before completion:
|
||||
|
||||
**Content Validation:**
|
||||
|
||||
- All critical technology versions documented
|
||||
- Engine-specific rules are specific and actionable
|
||||
- Performance rules capture project requirements
|
||||
- Code organization rules maintain standards
|
||||
- Testing rules ensure consistency
|
||||
- Platform rules prevent cross-platform issues
|
||||
- Anti-pattern rules prevent common mistakes
|
||||
|
||||
**Format Validation:**
|
||||
|
||||
- Content is lean and optimized for LLMs
|
||||
- Structure is logical and scannable
|
||||
- No redundant or obvious information
|
||||
- Consistent formatting throughout
|
||||
|
||||
### 7. Completion Message
|
||||
|
||||
Present final completion to user:
|
||||
|
||||
"**Project Context Generation Complete!**
|
||||
|
||||
Your optimized project context file is ready at:
|
||||
`{output_folder}/project-context.md`
|
||||
|
||||
**Context Summary:**
|
||||
|
||||
- {{rule_count}} critical rules for AI agents
|
||||
- {{section_count}} comprehensive sections
|
||||
- Optimized for LLM context efficiency
|
||||
- Ready for immediate agent integration
|
||||
|
||||
**Key Benefits:**
|
||||
|
||||
- Consistent implementation across all AI agents
|
||||
- Reduced common mistakes and edge cases
|
||||
- Clear guidance for project-specific patterns
|
||||
- Minimal LLM context usage
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. AI agents will automatically read this file when implementing
|
||||
2. Update this file when your technology stack or patterns evolve
|
||||
3. Review quarterly to optimize and remove outdated rules
|
||||
|
||||
Your project context will help ensure high-quality, consistent game implementation across all development work. Great work capturing your project's critical implementation requirements!"
|
||||
|
||||
## SUCCESS METRICS:
|
||||
|
||||
- Complete project context file with all critical rules
|
||||
- Content optimized for LLM context efficiency
|
||||
- All technology versions and patterns documented
|
||||
- File structure is logical and scannable
|
||||
- Usage guidelines included for agents and humans
|
||||
- Frontmatter properly updated with completion status
|
||||
- User provided with clear next steps and benefits
|
||||
|
||||
## FAILURE MODES:
|
||||
|
||||
- Final content is too verbose for LLM consumption
|
||||
- Missing critical implementation rules or patterns
|
||||
- Not optimizing content for agent readability
|
||||
- Not providing clear usage guidelines
|
||||
- Frontmatter not properly updated
|
||||
- Not validating file completion before ending
|
||||
|
||||
## WORKFLOW COMPLETE:
|
||||
|
||||
This is the final step of the Generate Project Context workflow. The user now has a comprehensive, optimized project context file that will ensure consistent, high-quality game implementation across all AI agents working on the project.
|
||||
|
||||
The project context file serves as the critical "rules of the road" that agents need to implement game code consistently with the project's standards and patterns.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: generate-project-context
|
||||
description: Creates a concise project-context.md file with critical rules and patterns that AI agents must follow when implementing game code. Optimized for LLM context efficiency.
|
||||
---
|
||||
|
||||
# Generate Project Context Workflow
|
||||
|
||||
**Goal:** Create a concise, optimized `project-context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing game code. This file focuses on unobvious details that LLMs need to be reminded of.
|
||||
|
||||
**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality game code generation across all AI agents working on the project.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **micro-file architecture** for disciplined execution:
|
||||
|
||||
- Each step is a self-contained file with embedded rules
|
||||
- Sequential progression with user control at each step
|
||||
- Document state tracked in frontmatter
|
||||
- Focus on lean, LLM-optimized content generation
|
||||
- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION
|
||||
|
||||
### Configuration Loading
|
||||
|
||||
Load config from `{project-root}/_bmad/bmgd/config.yaml` and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `user_name`
|
||||
- `communication_language`, `document_output_language`, `game_dev_experience`
|
||||
- `date` as system-generated current datetime
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Paths
|
||||
|
||||
- `installed_path` = `{project-root}/_bmad/bmgd/workflows/3-technical/generate-project-context`
|
||||
- `template_path` = `{installed_path}/project-context-template.md`
|
||||
- `output_file` = `{output_folder}/project-context.md`
|
||||
|
||||
---
|
||||
|
||||
## EXECUTION
|
||||
|
||||
Load and execute `steps/step-01-discover.md` to begin the workflow.
|
||||
|
||||
**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.
|
||||
Reference in new issue
Block a user