agentvibes 2.12.4 → 2.12.5

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

@@ -1,103 +0,0 @@
-# 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

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

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

@@ -1,222 +0,0 @@
-# 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"