bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

package/bmad/bmm/workflows/3-solutioning/architecture/architecture-template.md

@@ -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}}_

package/bmad/bmm/workflows/3-solutioning/architecture/checklist.md

@@ -0,0 +1,244 @@
+# Architecture Document Validation Checklist
+
+**Purpose**: Validate the architecture document itself is complete, implementable, and provides clear guidance for AI agents.
+
+**Note**: This checklist validates the ARCHITECTURE DOCUMENT only. For cross-workflow validation (PRD → Architecture → Stories alignment), use the solutioning-gate-check workflow.
+
+---
+
+## 1. Decision Completeness
+
+### All Decisions Made
+
+- [ ] Every critical decision category has been resolved
+- [ ] All important decision categories addressed
+- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
+- [ ] Optional decisions either resolved or explicitly deferred with rationale
+
+### Decision Coverage
+
+- [ ] Data persistence approach decided
+- [ ] API pattern chosen
+- [ ] Authentication/authorization strategy defined
+- [ ] Deployment target selected
+- [ ] All functional requirements have architectural support
+
+---
+
+## 2. Version Specificity
+
+### Technology Versions
+
+- [ ] Every technology choice includes a specific version number
+- [ ] Version numbers are current (verified via WebSearch, not hardcoded)
+- [ ] Compatible versions selected (e.g., Node.js version supports chosen packages)
+- [ ] Verification dates noted for version checks
+
+### Version Verification Process
+
+- [ ] WebSearch used during workflow to verify current versions
+- [ ] No hardcoded versions from decision catalog trusted without verification
+- [ ] LTS vs. latest versions considered and documented
+- [ ] Breaking changes between versions noted if relevant
+
+---
+
+## 3. Starter Template Integration (if applicable)
+
+### Template Selection
+
+- [ ] Starter template chosen (or "from scratch" decision documented)
+- [ ] Project initialization command documented with exact flags
+- [ ] Starter template version is current and specified
+- [ ] Command search term provided for verification
+
+### Starter-Provided Decisions
+
+- [ ] Decisions provided by starter marked as "PROVIDED BY STARTER"
+- [ ] List of what starter provides is complete
+- [ ] Remaining decisions (not covered by starter) clearly identified
+- [ ] No duplicate decisions that starter already makes
+
+---
+
+## 4. Novel Pattern Design (if applicable)
+
+### Pattern Detection
+
+- [ ] All unique/novel concepts from PRD identified
+- [ ] Patterns that don't have standard solutions documented
+- [ ] Multi-epic workflows requiring custom design captured
+
+### Pattern Documentation Quality
+
+- [ ] Pattern name and purpose clearly defined
+- [ ] Component interactions specified
+- [ ] Data flow documented (with sequence diagrams if complex)
+- [ ] Implementation guide provided for agents
+- [ ] Edge cases and failure modes considered
+- [ ] States and transitions clearly defined
+
+### Pattern Implementability
+
+- [ ] Pattern is implementable by AI agents with provided guidance
+- [ ] No ambiguous decisions that could be interpreted differently
+- [ ] Clear boundaries between components
+- [ ] Explicit integration points with standard patterns
+
+---
+
+## 5. Implementation Patterns
+
+### Pattern Categories Coverage
+
+- [ ] **Naming Patterns**: API routes, database tables, components, files
+- [ ] **Structure Patterns**: Test organization, component organization, shared utilities
+- [ ] **Format Patterns**: API responses, error formats, date handling
+- [ ] **Communication Patterns**: Events, state updates, inter-component messaging
+- [ ] **Lifecycle Patterns**: Loading states, error recovery, retry logic
+- [ ] **Location Patterns**: URL structure, asset organization, config placement
+- [ ] **Consistency Patterns**: UI date formats, logging, user-facing errors
+
+### Pattern Quality
+
+- [ ] Each pattern has concrete examples
+- [ ] Conventions are unambiguous (agents can't interpret differently)
+- [ ] Patterns cover all technologies in the stack
+- [ ] No gaps where agents would have to guess
+- [ ] Implementation patterns don't conflict with each other
+
+---
+
+## 6. Technology Compatibility
+
+### Stack Coherence
+
+- [ ] Database choice compatible with ORM choice
+- [ ] Frontend framework compatible with deployment target
+- [ ] Authentication solution works with chosen frontend/backend
+- [ ] All API patterns consistent (not mixing REST and GraphQL for same data)
+- [ ] Starter template compatible with additional choices
+
+### Integration Compatibility
+
+- [ ] Third-party services compatible with chosen stack
+- [ ] Real-time solutions (if any) work with deployment target
+- [ ] File storage solution integrates with framework
+- [ ] Background job system compatible with infrastructure
+
+---
+
+## 7. Document Structure
+
+### Required Sections Present
+
+- [ ] Executive summary exists (2-3 sentences maximum)
+- [ ] Project initialization section (if using starter template)
+- [ ] Decision summary table with ALL required columns:
+  - Category
+  - Decision
+  - Version
+  - Rationale
+- [ ] Project structure section shows complete source tree
+- [ ] Implementation patterns section comprehensive
+- [ ] Novel patterns section (if applicable)
+
+### Document Quality
+
+- [ ] Source tree reflects actual technology decisions (not generic)
+- [ ] Technical language used consistently
+- [ ] Tables used instead of prose where appropriate
+- [ ] No unnecessary explanations or justifications
+- [ ] Focused on WHAT and HOW, not WHY (rationale is brief)
+
+---
+
+## 8. AI Agent Clarity
+
+### Clear Guidance for Agents
+
+- [ ] No ambiguous decisions that agents could interpret differently
+- [ ] Clear boundaries between components/modules
+- [ ] Explicit file organization patterns
+- [ ] Defined patterns for common operations (CRUD, auth checks, etc.)
+- [ ] Novel patterns have clear implementation guidance
+- [ ] Document provides clear constraints for agents
+- [ ] No conflicting guidance present
+
+### Implementation Readiness
+
+- [ ] Sufficient detail for agents to implement without guessing
+- [ ] File paths and naming conventions explicit
+- [ ] Integration points clearly defined
+- [ ] Error handling patterns specified
+- [ ] Testing patterns documented
+
+---
+
+## 9. Practical Considerations
+
+### Technology Viability
+
+- [ ] Chosen stack has good documentation and community support
+- [ ] Development environment can be set up with specified versions
+- [ ] No experimental or alpha technologies for critical path
+- [ ] Deployment target supports all chosen technologies
+- [ ] Starter template (if used) is stable and well-maintained
+
+### Scalability
+
+- [ ] Architecture can handle expected user load
+- [ ] Data model supports expected growth
+- [ ] Caching strategy defined if performance is critical
+- [ ] Background job processing defined if async work needed
+- [ ] Novel patterns scalable for production use
+
+---
+
+## 10. Common Issues to Check
+
+### Beginner Protection
+
+- [ ] Not overengineered for actual requirements
+- [ ] Standard patterns used where possible (starter templates leveraged)
+- [ ] Complex technologies justified by specific needs
+- [ ] Maintenance complexity appropriate for team size
+
+### Expert Validation
+
+- [ ] No obvious anti-patterns present
+- [ ] Performance bottlenecks addressed
+- [ ] Security best practices followed
+- [ ] Future migration paths not blocked
+- [ ] Novel patterns follow architectural principles
+
+---
+
+## Validation Summary
+
+### Document Quality Score
+
+- Architecture Completeness: [Complete / Mostly Complete / Partial / Incomplete]
+- Version Specificity: [All Verified / Most Verified / Some Missing / Many Missing]
+- Pattern Clarity: [Crystal Clear / Clear / Somewhat Ambiguous / Ambiguous]
+- AI Agent Readiness: [Ready / Mostly Ready / Needs Work / Not Ready]
+
+### Critical Issues Found
+
+- [ ] Issue 1: **\*\***\_\_\_**\*\***
+- [ ] Issue 2: **\*\***\_\_\_**\*\***
+- [ ] Issue 3: **\*\***\_\_\_**\*\***
+
+### Recommended Actions Before Implementation
+
+1. ***
+2. ***
+3. ***
+
+---
+
+**Next Step**: Run the **solutioning-gate-check** workflow to validate alignment between PRD, Architecture, and Stories before beginning implementation.
+
+---
+
+_This checklist validates architecture document quality only. Use solutioning-gate-check for comprehensive readiness validation._

package/bmad/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml

@@ -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"