massive architecture creation overhaul
This commit is contained in:
Brian Madison
3
.claude/commands/foo.md
Normal file
3
.claude/commands/foo.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# foo task
|
||||
|
||||
The user just said foo, respond with bar.
|
||||
@@ -220,7 +220,7 @@ The planning workflow adapts to:
|
||||
|
||||
**Architect / Game Architect Agent**:
|
||||
|
||||
- `solution-architecture` - Creates adaptive architecture based on project type
|
||||
- `architecture` - Creates adaptive architecture based on project type
|
||||
- No more document sharding
|
||||
- Adapts sections to your project (web, mobile, embedded, game, etc.)
|
||||
- Beyond basic concerns (complex testing, DevOps, security), specialized agents assist _(coming soon)_
|
||||
|
||||
@@ -4,7 +4,7 @@ _Auto-updated during discovery and planning sessions - you can also add informat
|
||||
|
||||
## Purpose
|
||||
|
||||
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for solution-architecture.md and solution design documents.
|
||||
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
|
||||
|
||||
## Confirmed Decisions
|
||||
|
||||
@@ -26,5 +26,5 @@ This document captures technical decisions, preferences, and constraints discove
|
||||
|
||||
- This file is automatically updated when technical information is mentioned
|
||||
- Decisions here are inputs, not final architecture
|
||||
- Final technical decisions belong in solution-architecture.md
|
||||
- Final technical decisions belong in architecture.md
|
||||
- Implementation details belong in solutions/\*.md and story context or dev notes.
|
||||
|
||||
@@ -4,7 +4,7 @@ _Auto-updated during discovery and planning sessions - you can also add informat
|
||||
|
||||
## Purpose
|
||||
|
||||
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for solution-architecture.md and solution design documents.
|
||||
This document captures technical decisions, preferences, and constraints discovered during project discussions. It serves as input for architecture.md and solution design documents.
|
||||
|
||||
## Confirmed Decisions
|
||||
|
||||
@@ -26,5 +26,5 @@ This document captures technical decisions, preferences, and constraints discove
|
||||
|
||||
- This file is automatically updated when technical information is mentioned
|
||||
- Decisions here are inputs, not final architecture
|
||||
- Final technical decisions belong in solution-architecture.md
|
||||
- Final technical decisions belong in architecture.md
|
||||
- Implementation details belong in solutions/\*.md and story context or dev notes.
|
||||
|
||||
@@ -26,14 +26,10 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: solution-architecture
|
||||
- trigger: create-architecture
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
||||
@@ -26,14 +26,10 @@ agent:
|
||||
workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
|
||||
description: Course Correction Analysis
|
||||
|
||||
- trigger: solution-architecture
|
||||
- trigger: create-architecture
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Produce a Scale Adaptive Architecture
|
||||
|
||||
- trigger: validate-architecture
|
||||
validate-workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/workflow.yaml"
|
||||
description: Validate latest Tech Spec against checklist
|
||||
|
||||
- trigger: solutioning-gate-check
|
||||
workflow: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml"
|
||||
description: Validate solutioning complete, ready for Phase 4 (Level 2-4 only)
|
||||
|
||||
@@ -18,7 +18,7 @@ agent:
|
||||
- I never cross into implementation territory, focusing entirely on creating developer-ready specifications that eliminate ambiguity and enable efficient sprint execution.
|
||||
|
||||
critical_actions:
|
||||
- "When running *create-story, run non-interactively: use solution-architecture, PRD, Tech Spec, and epics to generate a complete draft without elicitation."
|
||||
- "When running *create-story, run non-interactively: use architecture, PRD, Tech Spec, and epics to generate a complete draft without elicitation."
|
||||
|
||||
menu:
|
||||
- trigger: workflow-status
|
||||
|
||||
@@ -106,7 +106,7 @@ This complexity **requires specialized documentation** (this guide), **extensive
|
||||
1. Run the core planning workflows first:
|
||||
- Analyst `*product-brief`
|
||||
- Product Manager `*plan-project`
|
||||
- Architect `*solution-architecture`
|
||||
- Architect `*create-architecture`
|
||||
2. Confirm `bmad/bmm/config.yaml` defines `project_name`, `output_folder`, `dev_story_location`, and language settings.
|
||||
3. Ensure a test test framework setup exists; if not, use `*framework` command to create a test framework setup, prior to development.
|
||||
4. Skim supporting references (knowledge under `testarch/`, command workflows under `workflows/testarch/`).
|
||||
@@ -116,14 +116,14 @@ This complexity **requires specialized documentation** (this guide), **extensive
|
||||
|
||||
### Greenfield Feature Launch (Level 2)
|
||||
|
||||
| Phase | Test Architect | Dev / Team | Outputs |
|
||||
| ------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| Setup | - | Analyst `*product-brief`, PM `*plan-project`, Architect `*solution-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`, `epics.md`, `solution-architecture.md` |
|
||||
| Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design` | Review risk/design/CI guidance, align backlog | Test scaffold, CI pipeline, risk and coverage strategy |
|
||||
| Story Prep | - | Scrum Master `*create-story`, `*story-context` | Story markdown + context XML |
|
||||
| Implementation | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist | Failing acceptance tests + implementation checklist |
|
||||
| Post-Dev | Execute `*automate`, (Optional) `*test-review`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, quality report, refreshed coverage matrix |
|
||||
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary (owners, waivers) |
|
||||
| Phase | Test Architect | Dev / Team | Outputs |
|
||||
| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
||||
| Setup | - | Analyst `*product-brief`, PM `*plan-project`, Architect `*create-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`, `epics.md`, `architecture.md` |
|
||||
| Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design` | Review risk/design/CI guidance, align backlog | Test scaffold, CI pipeline, risk and coverage strategy |
|
||||
| Story Prep | - | Scrum Master `*create-story`, `*story-context` | Story markdown + context XML |
|
||||
| Implementation | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist | Failing acceptance tests + implementation checklist |
|
||||
| Post-Dev | Execute `*automate`, (Optional) `*test-review`, re-run `*trace` | Address recommendations, update code/tests | Regression specs, quality report, refreshed coverage matrix |
|
||||
| Release | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary (owners, waivers) |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
|
||||
@@ -104,7 +104,7 @@ workflow research --type domain
|
||||
|
||||
```bash
|
||||
workflow research --type market --input product-brief.md --input competitor-list.md
|
||||
workflow research --type technical --input requirements.md --input solution-architecture.md
|
||||
workflow research --type technical --input requirements.md --input architecture.md
|
||||
workflow research --type deep_prompt --input research-question.md
|
||||
```
|
||||
|
||||
|
||||
@@ -178,7 +178,7 @@ The workflow adapts automatically based on project assessment, but key configura
|
||||
- `PRD.md` - Comprehensive product specification
|
||||
- `epics.md` - Complete epic/story breakdown
|
||||
- Hands off to solution-architecture workflow (Phase 3)
|
||||
- `solution-architecture.md` - Generated by architect workflow
|
||||
- `architecture.md` - Generated by architect workflow
|
||||
- Then to implementation
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -198,7 +198,7 @@ When a game project completes the GDD and moves to solutioning:
|
||||
2. Loads GDD.md instead of PRD.md
|
||||
3. Matches game platforms to solutioning `registry.csv` game-\* entries
|
||||
4. Provides engine-specific guidance (Unity, Godot, Phaser, etc.)
|
||||
5. Generates solution-architecture.md with platform decisions
|
||||
5. Generates architecture.md with platform decisions
|
||||
6. Creates per-epic tech specs
|
||||
|
||||
Example solutioning registry entries:
|
||||
|
||||
@@ -382,7 +382,7 @@ Since this is a Level {{project_level}} game project, you need solutioning for p
|
||||
**The solutioning workflow will:**
|
||||
|
||||
- Determine game engine/platform (Unity, Godot, Phaser, custom, etc.)
|
||||
- Generate solution-architecture.md with engine-specific decisions
|
||||
- Generate architecture.md with engine-specific decisions
|
||||
- Create per-epic tech specs
|
||||
- Handle platform-specific architecture (from registry.csv game-\* entries)
|
||||
|
||||
@@ -395,7 +395,7 @@ Since this is a Level {{project_level}} game project, you need solutioning for p
|
||||
- [ ] **Run solutioning workflow** (REQUIRED)
|
||||
- Command: `workflow solution-architecture`
|
||||
- Input: GDD.md, bmm-workflow-status.md
|
||||
- Output: solution-architecture.md with engine/platform specifics
|
||||
- Output: architecture.md with engine/platform specifics
|
||||
- Note: Registry.csv will provide engine-specific guidance
|
||||
|
||||
### Phase 2: Prototype and Playtesting
|
||||
@@ -426,7 +426,7 @@ Since this is a Level {{project_level}} game project, you need solutioning for p
|
||||
|
||||
- [ ] **Generate detailed user stories**
|
||||
- Command: `workflow generate-stories`
|
||||
- Input: GDD.md + solution-architecture.md
|
||||
- Input: GDD.md + architecture.md
|
||||
|
||||
- [ ] **Sprint planning**
|
||||
- Vertical slices
|
||||
|
||||
@@ -58,7 +58,7 @@ If no: We'll gather basic requirements to create the UX spec
|
||||
- PRD.md (primary source for requirements and user journeys)
|
||||
- epics.md (helps understand feature grouping)
|
||||
- tech-spec.md (understand technical constraints)
|
||||
- solution-architecture.md (if Level 3-4 project)
|
||||
- architecture.md (if Level 3-4 project)
|
||||
- bmm-workflow-status.md (understand project level and scope)
|
||||
|
||||
</check>
|
||||
|
||||
@@ -1,74 +0,0 @@
|
||||
# Architecture Decision Records
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document captures all architectural decisions made during the solution architecture process. Each decision includes the context, options considered, chosen solution, and rationale.
|
||||
|
||||
---
|
||||
|
||||
## Decision Format
|
||||
|
||||
Each decision follows this structure:
|
||||
|
||||
### ADR-NNN: [Decision Title]
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Status:** [Proposed | Accepted | Rejected | Superseded]
|
||||
**Decider:** [User | Agent | Collaborative]
|
||||
|
||||
**Context:**
|
||||
What is the issue we're trying to solve?
|
||||
|
||||
**Options Considered:**
|
||||
|
||||
1. Option A - [brief description]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
2. Option B - [brief description]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
3. Option C - [brief description]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
|
||||
**Decision:**
|
||||
We chose [Option X]
|
||||
|
||||
**Rationale:**
|
||||
Why we chose this option over others.
|
||||
|
||||
**Consequences:**
|
||||
|
||||
- Positive: ...
|
||||
- Negative: ...
|
||||
- Neutral: ...
|
||||
|
||||
**Rejected Options:**
|
||||
|
||||
- Option A rejected because: ...
|
||||
- Option B rejected because: ...
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
{{decisions_list}}
|
||||
|
||||
---
|
||||
|
||||
## Decision Index
|
||||
|
||||
| ID | Title | Status | Date | Decider |
|
||||
| --- | ----- | ------ | ---- | ------- |
|
||||
|
||||
{{decisions_index}}
|
||||
|
||||
---
|
||||
|
||||
_This document is generated and updated during the solution-architecture workflow_
|
||||
@@ -0,0 +1,347 @@
|
||||
# Architecture Patterns - Common patterns identified from requirements
|
||||
|
||||
requirement_patterns:
|
||||
realtime_collaboration:
|
||||
triggers:
|
||||
- "real-time"
|
||||
- "collaborative"
|
||||
- "live updates"
|
||||
- "multi-user"
|
||||
- "simultaneous editing"
|
||||
decisions_needed:
|
||||
- websocket_solution
|
||||
- conflict_resolution
|
||||
- state_synchronization
|
||||
- presence_tracking
|
||||
- optimistic_updates
|
||||
suggested_stack:
|
||||
- "Socket.io or WebSocket native"
|
||||
- "Redis for pub/sub"
|
||||
- "Operational Transforms or CRDTs for conflict resolution"
|
||||
- "PostgreSQL for persistence"
|
||||
|
||||
ecommerce:
|
||||
triggers:
|
||||
- "shopping cart"
|
||||
- "checkout"
|
||||
- "payments"
|
||||
- "inventory"
|
||||
- "product catalog"
|
||||
decisions_needed:
|
||||
- payment_processor
|
||||
- cart_persistence
|
||||
- inventory_management
|
||||
- order_workflow
|
||||
- tax_calculation
|
||||
suggested_stack:
|
||||
- "Stripe or PayPal for payments"
|
||||
- "PostgreSQL for products and orders"
|
||||
- "Redis for cart sessions"
|
||||
- "BullMQ for order processing"
|
||||
|
||||
saas_platform:
|
||||
triggers:
|
||||
- "multi-tenant"
|
||||
- "subscription"
|
||||
- "billing"
|
||||
- "team management"
|
||||
- "roles and permissions"
|
||||
decisions_needed:
|
||||
- tenancy_model
|
||||
- subscription_billing
|
||||
- permission_system
|
||||
- team_collaboration
|
||||
- usage_tracking
|
||||
suggested_stack:
|
||||
- "PostgreSQL with Row Level Security"
|
||||
- "Stripe Billing for subscriptions"
|
||||
- "RBAC or ABAC for permissions"
|
||||
- "NextAuth or Clerk for auth"
|
||||
|
||||
content_platform:
|
||||
triggers:
|
||||
- "CMS"
|
||||
- "blog"
|
||||
- "publishing"
|
||||
- "content management"
|
||||
- "editorial workflow"
|
||||
decisions_needed:
|
||||
- content_storage
|
||||
- rich_text_editor
|
||||
- media_handling
|
||||
- version_control
|
||||
- publishing_workflow
|
||||
suggested_stack:
|
||||
- "PostgreSQL for structured content"
|
||||
- "S3 or Cloudinary for media"
|
||||
- "Tiptap or Slate for rich text"
|
||||
- "Algolia for search"
|
||||
|
||||
data_analytics:
|
||||
triggers:
|
||||
- "dashboards"
|
||||
- "reporting"
|
||||
- "metrics"
|
||||
- "analytics"
|
||||
- "data visualization"
|
||||
decisions_needed:
|
||||
- data_warehouse
|
||||
- etl_pipeline
|
||||
- visualization_library
|
||||
- query_optimization
|
||||
- caching_strategy
|
||||
suggested_stack:
|
||||
- "PostgreSQL or ClickHouse"
|
||||
- "Apache Airflow or Temporal for ETL"
|
||||
- "Chart.js or D3 for visualization"
|
||||
- "Redis for query caching"
|
||||
|
||||
social_platform:
|
||||
triggers:
|
||||
- "social network"
|
||||
- "feed"
|
||||
- "following"
|
||||
- "likes"
|
||||
- "comments"
|
||||
decisions_needed:
|
||||
- graph_relationships
|
||||
- feed_algorithm
|
||||
- notification_system
|
||||
- content_moderation
|
||||
- privacy_controls
|
||||
suggested_stack:
|
||||
- "PostgreSQL with graph extensions or Neo4j"
|
||||
- "Redis for feed caching"
|
||||
- "Elasticsearch for user search"
|
||||
- "WebSockets for notifications"
|
||||
|
||||
marketplace:
|
||||
triggers:
|
||||
- "marketplace"
|
||||
- "vendors"
|
||||
- "buyers and sellers"
|
||||
- "transactions"
|
||||
- "escrow"
|
||||
decisions_needed:
|
||||
- payment_splitting
|
||||
- escrow_handling
|
||||
- vendor_management
|
||||
- dispute_resolution
|
||||
- commission_model
|
||||
suggested_stack:
|
||||
- "Stripe Connect for payments"
|
||||
- "PostgreSQL for transactions"
|
||||
- "BullMQ for async processing"
|
||||
- "S3 for vendor assets"
|
||||
|
||||
streaming_platform:
|
||||
triggers:
|
||||
- "video streaming"
|
||||
- "live streaming"
|
||||
- "media delivery"
|
||||
- "broadcast"
|
||||
decisions_needed:
|
||||
- video_encoding
|
||||
- cdn_strategy
|
||||
- streaming_protocol
|
||||
- bandwidth_optimization
|
||||
- drm_protection
|
||||
suggested_stack:
|
||||
- "AWS MediaConvert or Mux"
|
||||
- "CloudFront or Fastly CDN"
|
||||
- "HLS or DASH protocol"
|
||||
- "S3 for video storage"
|
||||
|
||||
iot_platform:
|
||||
triggers:
|
||||
- "IoT"
|
||||
- "sensors"
|
||||
- "device management"
|
||||
- "telemetry"
|
||||
- "edge computing"
|
||||
decisions_needed:
|
||||
- message_protocol
|
||||
- time_series_database
|
||||
- device_authentication
|
||||
- data_ingestion
|
||||
- edge_processing
|
||||
suggested_stack:
|
||||
- "MQTT or CoAP protocol"
|
||||
- "TimescaleDB or InfluxDB"
|
||||
- "Apache Kafka for ingestion"
|
||||
- "Grafana for monitoring"
|
||||
|
||||
ai_application:
|
||||
triggers:
|
||||
- "machine learning"
|
||||
- "AI features"
|
||||
- "LLM integration"
|
||||
- "computer vision"
|
||||
- "NLP"
|
||||
decisions_needed:
|
||||
- model_serving
|
||||
- vector_database
|
||||
- prompt_management
|
||||
- token_optimization
|
||||
- fallback_strategy
|
||||
suggested_stack:
|
||||
- "OpenAI or Anthropic API"
|
||||
- "Pinecone or pgvector for embeddings"
|
||||
- "Redis for prompt caching"
|
||||
- "Langchain or LlamaIndex"
|
||||
|
||||
# Quality attribute patterns
|
||||
quality_attributes:
|
||||
high_availability:
|
||||
triggers:
|
||||
- "99.9% uptime"
|
||||
- "high availability"
|
||||
- "fault tolerance"
|
||||
- "disaster recovery"
|
||||
architectural_needs:
|
||||
- load_balancing
|
||||
- database_replication
|
||||
- health_checks
|
||||
- circuit_breakers
|
||||
- graceful_degradation
|
||||
|
||||
high_performance:
|
||||
triggers:
|
||||
- "millisecond response"
|
||||
- "high throughput"
|
||||
- "low latency"
|
||||
- "performance critical"
|
||||
architectural_needs:
|
||||
- caching_layers
|
||||
- database_optimization
|
||||
- cdn_strategy
|
||||
- code_splitting
|
||||
- lazy_loading
|
||||
|
||||
high_security:
|
||||
triggers:
|
||||
- "compliance"
|
||||
- "HIPAA"
|
||||
- "GDPR"
|
||||
- "financial data"
|
||||
- "PCI DSS"
|
||||
architectural_needs:
|
||||
- encryption_at_rest
|
||||
- encryption_in_transit
|
||||
- audit_logging
|
||||
- access_controls
|
||||
- data_isolation
|
||||
|
||||
scalability:
|
||||
triggers:
|
||||
- "millions of users"
|
||||
- "elastic scale"
|
||||
- "global reach"
|
||||
- "viral growth"
|
||||
architectural_needs:
|
||||
- horizontal_scaling
|
||||
- database_sharding
|
||||
- microservices
|
||||
- queue_systems
|
||||
- auto_scaling
|
||||
|
||||
# Integration patterns
|
||||
integration_requirements:
|
||||
payment_processing:
|
||||
common_choices:
|
||||
- "Stripe - most developer friendly"
|
||||
- "PayPal - widest consumer adoption"
|
||||
- "Square - best for in-person + online"
|
||||
considerations:
|
||||
- transaction_fees
|
||||
- international_support
|
||||
- subscription_handling
|
||||
- marketplace_capabilities
|
||||
|
||||
email_service:
|
||||
common_choices:
|
||||
- "Resend - modern, developer friendly"
|
||||
- "SendGrid - mature, scalable"
|
||||
- "Amazon SES - cost effective at scale"
|
||||
- "Postmark - transactional focus"
|
||||
considerations:
|
||||
- deliverability
|
||||
- template_management
|
||||
- analytics_needs
|
||||
- cost_per_email
|
||||
|
||||
sms_notifications:
|
||||
common_choices:
|
||||
- "Twilio - most comprehensive"
|
||||
- "Amazon SNS - AWS integrated"
|
||||
- "Vonage - competitive pricing"
|
||||
considerations:
|
||||
- international_coverage
|
||||
- delivery_rates
|
||||
- two_way_messaging
|
||||
- cost_per_message
|
||||
|
||||
authentication_providers:
|
||||
social_providers:
|
||||
- "Google - highest adoption"
|
||||
- "GitHub - developer focused"
|
||||
- "Microsoft - enterprise"
|
||||
- "Apple - iOS users"
|
||||
enterprise_providers:
|
||||
- "SAML 2.0"
|
||||
- "OAuth 2.0"
|
||||
- "OpenID Connect"
|
||||
- "Active Directory"
|
||||
|
||||
# Decision heuristics
|
||||
decision_rules:
|
||||
database_selection:
|
||||
if_requirements_include:
|
||||
- complex_relationships: "PostgreSQL"
|
||||
- flexible_schema: "MongoDB"
|
||||
- time_series: "TimescaleDB"
|
||||
- graph_data: "Neo4j or PostgreSQL with extensions"
|
||||
- key_value: "Redis"
|
||||
- wide_column: "Cassandra"
|
||||
|
||||
api_pattern_selection:
|
||||
if_requirements_include:
|
||||
- simple_crud: "REST"
|
||||
- complex_queries: "GraphQL"
|
||||
- type_safety_critical: "tRPC"
|
||||
- microservices: "gRPC"
|
||||
- public_api: "REST with OpenAPI"
|
||||
|
||||
deployment_selection:
|
||||
if_requirements_include:
|
||||
- nextjs_only: "Vercel"
|
||||
- complex_infrastructure: "AWS"
|
||||
- quick_prototype: "Railway"
|
||||
- global_edge: "Fly.io"
|
||||
- kubernetes_needed: "GCP or AWS EKS"
|
||||
|
||||
# Anti-patterns to avoid
|
||||
anti_patterns:
|
||||
overengineering:
|
||||
signs:
|
||||
- "Microservices for < 10k users"
|
||||
- "Kubernetes for single app"
|
||||
- "GraphQL for 5 endpoints"
|
||||
- "Event sourcing for CRUD app"
|
||||
recommendation: "Start simple, evolve as needed"
|
||||
|
||||
underengineering:
|
||||
signs:
|
||||
- "No authentication strategy"
|
||||
- "No error handling plan"
|
||||
- "No monitoring approach"
|
||||
- "No backup strategy"
|
||||
recommendation: "Cover the fundamentals"
|
||||
|
||||
technology_soup:
|
||||
signs:
|
||||
- "5+ different databases"
|
||||
- "Multiple frontend frameworks"
|
||||
- "Inconsistent patterns"
|
||||
- "Too many languages"
|
||||
recommendation: "Maintain consistency"
|
||||
@@ -0,0 +1,103 @@
|
||||
# Decision 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,261 @@
|
||||
# Decision Architecture Validation Checklist
|
||||
|
||||
## Critical Requirements (MUST PASS)
|
||||
|
||||
### Decision Completeness
|
||||
|
||||
- [ ] Every functional requirement from PRD has architectural support
|
||||
- [ ] Every non-functional requirement from PRD is addressed
|
||||
- [ ] All critical decision categories have been resolved
|
||||
- [ ] No placeholder text like "TBD", "[choose]", or "{TODO}" remains
|
||||
|
||||
### Version Specificity
|
||||
|
||||
- [ ] 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
|
||||
|
||||
### Starter Template Integration (if applicable)
|
||||
|
||||
- [ ] Project initialization command documented with exact flags
|
||||
- [ ] Starter-provided decisions marked as "PROVIDED BY STARTER"
|
||||
- [ ] First implementation story references starter initialization
|
||||
- [ ] Starter template version is current and specified
|
||||
|
||||
### Epic Coverage
|
||||
|
||||
- [ ] Every epic from PRD is explicitly mapped to architectural components
|
||||
- [ ] Decision summary table shows which epics each decision affects
|
||||
- [ ] No orphan epics without architectural support
|
||||
- [ ] Novel patterns mapped to affected epics
|
||||
|
||||
### Document Structure
|
||||
|
||||
- [ ] Executive summary is present and concise (2-3 sentences maximum)
|
||||
- [ ] Project initialization section present (if using starter template)
|
||||
- [ ] Decision summary table has ALL required columns:
|
||||
- Category
|
||||
- Decision
|
||||
- Version
|
||||
- Affects Epics
|
||||
- Rationale
|
||||
- [ ] Project structure section shows complete source tree
|
||||
- [ ] Source tree reflects actual technology decisions (not generic)
|
||||
|
||||
## 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
|
||||
|
||||
- [ ] Pattern name and purpose clearly defined
|
||||
- [ ] Component interactions specified
|
||||
- [ ] Data flow documented (with sequence diagrams if complex)
|
||||
- [ ] Implementation guide provided for agents
|
||||
- [ ] Affected epics listed
|
||||
- [ ] Edge cases and failure modes considered
|
||||
|
||||
## 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
|
||||
|
||||
## Consistency Validation
|
||||
|
||||
### Technology Compatibility
|
||||
|
||||
- [ ] 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
|
||||
|
||||
### Pattern Consistency
|
||||
|
||||
- [ ] Single source of truth for each data type
|
||||
- [ ] Consistent error handling approach across components
|
||||
- [ ] Uniform authentication/authorization pattern
|
||||
- [ ] Implementation patterns don't conflict with each other
|
||||
|
||||
### AI Agent Clarity
|
||||
|
||||
- [ ] 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
|
||||
|
||||
## Quality Checks
|
||||
|
||||
### Documentation Quality
|
||||
|
||||
- [ ] 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)
|
||||
|
||||
### Practical Implementation
|
||||
|
||||
- [ ] 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 Considerations
|
||||
|
||||
- [ ] Architecture can handle expected user load from PRD
|
||||
- [ ] 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
|
||||
|
||||
## Completeness by Section
|
||||
|
||||
### Executive Summary
|
||||
|
||||
- [ ] States what is being built in one sentence
|
||||
- [ ] Identifies primary architectural pattern
|
||||
- [ ] Notes any unique or critical decisions
|
||||
|
||||
### Project Initialization (if using starter)
|
||||
|
||||
- [ ] Exact command with all flags documented
|
||||
- [ ] Lists what the starter provides
|
||||
- [ ] Notes what decisions remain to be made
|
||||
|
||||
### Decision Summary Table
|
||||
|
||||
- [ ] Contains all major technology decisions
|
||||
- [ ] Each row has complete information
|
||||
- [ ] Versions are specific and current
|
||||
- [ ] Rationales are brief but clear
|
||||
- [ ] Epic mapping is specific (epic IDs, not descriptions)
|
||||
- [ ] Starter-provided decisions marked appropriately
|
||||
|
||||
### Project Structure
|
||||
|
||||
- [ ] Shows actual directory structure
|
||||
- [ ] Follows conventions of chosen framework/starter
|
||||
- [ ] Maps epics to directories
|
||||
- [ ] Includes configuration files
|
||||
- [ ] Reflects starter template structure (if applicable)
|
||||
|
||||
### Novel Pattern Designs (if present)
|
||||
|
||||
- [ ] Each pattern fully documented
|
||||
- [ ] Component interactions clear
|
||||
- [ ] Implementation guidance specific
|
||||
- [ ] Integration with standard patterns defined
|
||||
|
||||
### Implementation Patterns
|
||||
|
||||
- [ ] All 7 pattern categories addressed
|
||||
- [ ] Examples provided for each pattern
|
||||
- [ ] No ambiguity in conventions
|
||||
- [ ] Covers all potential agent decision points
|
||||
|
||||
### Integration Points
|
||||
|
||||
- [ ] External service integrations documented
|
||||
- [ ] API contracts or patterns defined
|
||||
- [ ] Authentication flow specified
|
||||
- [ ] Data flow between components clear
|
||||
- [ ] Novel patterns integrated properly
|
||||
|
||||
### Consistency Rules
|
||||
|
||||
- [ ] Naming conventions specified with examples
|
||||
- [ ] Code organization patterns defined
|
||||
- [ ] Error handling approach documented
|
||||
- [ ] Logging strategy defined
|
||||
- [ ] All implementation patterns included
|
||||
|
||||
## Final Validation
|
||||
|
||||
### Ready for Implementation
|
||||
|
||||
- [ ] An AI agent could start implementing any epic with this document
|
||||
- [ ] First story can initialize project (if using starter)
|
||||
- [ ] No critical decisions left undefined
|
||||
- [ ] No conflicting guidance present
|
||||
- [ ] Document provides clear constraints for agents
|
||||
- [ ] Novel patterns implementable by agents
|
||||
|
||||
### PRD Alignment
|
||||
|
||||
- [ ] All must-have features architecturally supported
|
||||
- [ ] Performance requirements achievable with chosen stack
|
||||
- [ ] Security requirements addressed
|
||||
- [ ] Compliance requirements (if any) met by architecture
|
||||
- [ ] Novel concepts from PRD have architectural solutions
|
||||
|
||||
### UX Specification Alignment (if applicable)
|
||||
|
||||
- [ ] UI component library supports required interaction patterns
|
||||
- [ ] Animation/transition requirements achievable with chosen stack
|
||||
- [ ] Accessibility standards (WCAG level) met by component choices
|
||||
- [ ] Responsive design approach supports all specified breakpoints
|
||||
- [ ] Real-time update requirements addressed in architecture
|
||||
- [ ] Offline capability architecture defined (if required)
|
||||
- [ ] Performance targets from UX spec achievable
|
||||
- [ ] Platform-specific UI requirements supported
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
- [ ] Single points of failure identified and addressed
|
||||
- [ ] Backup and recovery approach defined (if critical)
|
||||
- [ ] Monitoring and observability approach included
|
||||
- [ ] Rollback strategy considered for deployments
|
||||
- [ ] Novel patterns don't introduce unmanageable risks
|
||||
|
||||
## Common Issues to Check
|
||||
|
||||
### Beginner Protection
|
||||
|
||||
- [ ] Not overengineered for the 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
|
||||
|
||||
### Document Usability
|
||||
|
||||
- [ ] Can be consumed by AI agents without human interpretation
|
||||
- [ ] Provides sufficient detail for consistent implementation
|
||||
- [ ] Free from internal contradictions
|
||||
- [ ] Complete enough to prevent agent "creativity" in critical areas
|
||||
- [ ] Implementation patterns leave no room for conflicting interpretations
|
||||
|
||||
## Version Verification
|
||||
|
||||
- [ ] All versions verified to be current (not relying on potentially outdated catalogs)
|
||||
- [ ] WebSearch used to verify versions during workflow execution
|
||||
- [ ] No hardcoded versions from knowledge bases trusted without verification
|
||||
- [ ] Starter template version checked for latest
|
||||
@@ -0,0 +1,701 @@
|
||||
# Decision Catalog - Knowledge base for architectural decisions
|
||||
# This replaces rigid project-type templates with intelligent, composable decisions
|
||||
|
||||
# ⚠️ CRITICAL WARNING ABOUT VERSIONS ⚠️
|
||||
# =====================================
|
||||
# Version numbers in this file are EXAMPLES ONLY and will become outdated!
|
||||
# The workflow MUST use WebSearch to verify current versions during execution.
|
||||
#
|
||||
# During facilitation, the AI should:
|
||||
# 1. Use this file for patterns and relationships
|
||||
# 2. Search for "{{technology}} latest stable version 2024" (or current year)
|
||||
# 3. Present the current version found, not the version in this file
|
||||
# 4. Document the verified current version in the architecture
|
||||
#
|
||||
# Versions listed here are for understanding compatibility relationships only.
|
||||
# NEVER trust these version numbers - ALWAYS verify current versions!
|
||||
|
||||
decision_categories:
|
||||
data_persistence:
|
||||
triggers: ["database", "storage", "data model", "persistence", "state management"]
|
||||
importance: "critical"
|
||||
affects: "most epics"
|
||||
options:
|
||||
postgresql:
|
||||
name: "PostgreSQL"
|
||||
current_version: "15.4"
|
||||
lts_version: "14.9"
|
||||
good_for: ["relational data", "complex queries", "ACID compliance", "JSON support"]
|
||||
not_ideal_for: ["massive scale writes", "unstructured data"]
|
||||
pairs_with:
|
||||
- "Prisma ORM 5.6"
|
||||
- "TypeORM 0.3"
|
||||
- "Drizzle 0.29"
|
||||
- "node-postgres 8.11"
|
||||
beginner_friendly: true
|
||||
|
||||
mongodb:
|
||||
name: "MongoDB"
|
||||
current_version: "7.0"
|
||||
lts_version: "6.0"
|
||||
good_for: ["document storage", "flexible schema", "horizontal scaling", "real-time"]
|
||||
not_ideal_for: ["complex relationships", "transactions", "strong consistency"]
|
||||
pairs_with:
|
||||
- "Mongoose 8.0"
|
||||
- "Prisma 5.6"
|
||||
- "MongoDB driver 6.3"
|
||||
beginner_friendly: true
|
||||
|
||||
redis:
|
||||
name: "Redis"
|
||||
current_version: "7.2"
|
||||
good_for: ["caching", "sessions", "pub/sub", "real-time", "leaderboards"]
|
||||
not_ideal_for: ["primary data store", "complex queries"]
|
||||
pairs_with:
|
||||
- "ioredis 5.3"
|
||||
- "node-redis 4.6"
|
||||
beginner_friendly: false
|
||||
|
||||
supabase:
|
||||
name: "Supabase"
|
||||
current_version: "2.39"
|
||||
good_for: ["PostgreSQL with batteries", "real-time", "auth included", "rapid development"]
|
||||
not_ideal_for: ["custom infrastructure", "specific compliance needs"]
|
||||
pairs_with:
|
||||
- "@supabase/supabase-js 2.39"
|
||||
beginner_friendly: true
|
||||
|
||||
firebase:
|
||||
name: "Firebase Firestore"
|
||||
current_version: "10.7"
|
||||
good_for: ["real-time sync", "offline-first", "serverless", "rapid prototyping"]
|
||||
not_ideal_for: ["complex queries", "data migrations", "cost at scale"]
|
||||
pairs_with:
|
||||
- "firebase-admin 12.0"
|
||||
beginner_friendly: true
|
||||
|
||||
api_pattern:
|
||||
triggers: ["API", "client communication", "frontend backend", "service communication"]
|
||||
importance: "critical"
|
||||
affects: "all client-facing epics"
|
||||
options:
|
||||
rest:
|
||||
name: "REST API"
|
||||
specification: "OpenAPI 3.0"
|
||||
good_for: ["standard CRUD", "caching", "simple patterns", "wide support"]
|
||||
not_ideal_for: ["complex queries", "real-time updates", "over/under fetching"]
|
||||
pairs_with:
|
||||
- "Express 4.18"
|
||||
- "Fastify 4.25"
|
||||
- "NestJS 10.3"
|
||||
- "Hono 3.12"
|
||||
beginner_friendly: true
|
||||
|
||||
graphql:
|
||||
name: "GraphQL"
|
||||
specification: "GraphQL"
|
||||
current_version: "16.8"
|
||||
good_for: ["flexible queries", "type safety", "avoiding over-fetching", "aggregation"]
|
||||
not_ideal_for: ["simple CRUD", "file uploads", "caching complexity"]
|
||||
pairs_with:
|
||||
- "Apollo Server 4.10"
|
||||
- "GraphQL Yoga 5.1"
|
||||
- "Mercurius 14.0"
|
||||
beginner_friendly: false
|
||||
|
||||
trpc:
|
||||
name: "tRPC"
|
||||
current_version: "10.45"
|
||||
good_for: ["type safety", "TypeScript projects", "full-stack type sharing"]
|
||||
not_ideal_for: ["non-TypeScript clients", "public APIs"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "React Query 5.17"
|
||||
beginner_friendly: false
|
||||
|
||||
grpc:
|
||||
name: "gRPC"
|
||||
current_version: "1.60"
|
||||
good_for: ["microservices", "binary protocol", "streaming", "performance"]
|
||||
not_ideal_for: ["browser clients", "debugging", "REST ecosystem"]
|
||||
pairs_with:
|
||||
- "@grpc/grpc-js 1.9"
|
||||
- "protobufjs 7.2"
|
||||
beginner_friendly: false
|
||||
|
||||
authentication:
|
||||
triggers: ["auth", "login", "user management", "security", "identity"]
|
||||
importance: "critical"
|
||||
affects: "security and user epics"
|
||||
options:
|
||||
nextauth:
|
||||
name: "NextAuth.js"
|
||||
current_version: "4.24"
|
||||
good_for: ["Next.js projects", "OAuth providers", "database sessions", "JWT"]
|
||||
not_ideal_for: ["non-Next.js", "complex RBAC", "native mobile"]
|
||||
pairs_with:
|
||||
- "Next.js 14"
|
||||
- "Prisma 5.6"
|
||||
beginner_friendly: true
|
||||
|
||||
auth0:
|
||||
name: "Auth0"
|
||||
good_for: ["enterprise", "compliance", "multi-tenant", "social login"]
|
||||
not_ideal_for: ["cost sensitive", "custom requirements"]
|
||||
pairs_with:
|
||||
- "@auth0/nextjs-auth0 3.5"
|
||||
- "auth0 4.2"
|
||||
beginner_friendly: true
|
||||
|
||||
clerk:
|
||||
name: "Clerk"
|
||||
current_version: "4.29"
|
||||
good_for: ["modern stack", "user management UI", "React/Next.js"]
|
||||
not_ideal_for: ["custom UI requirements", "legacy systems"]
|
||||
pairs_with:
|
||||
- "@clerk/nextjs 4.29"
|
||||
beginner_friendly: true
|
||||
|
||||
supertokens:
|
||||
name: "SuperTokens"
|
||||
current_version: "16.6"
|
||||
good_for: ["open source", "self-hosted", "customizable"]
|
||||
not_ideal_for: ["quick setup", "managed service"]
|
||||
pairs_with:
|
||||
- "supertokens-node 16.6"
|
||||
beginner_friendly: false
|
||||
|
||||
frontend_framework:
|
||||
triggers: ["UI", "frontend", "client", "web app", "user interface"]
|
||||
importance: "critical"
|
||||
affects: "all UI epics"
|
||||
options:
|
||||
nextjs:
|
||||
name: "Next.js"
|
||||
current_version: "14.0"
|
||||
good_for: ["full-stack", "SSR/SSG", "React ecosystem", "SEO"]
|
||||
not_ideal_for: ["pure SPA", "non-React", "simple sites"]
|
||||
pairs_with:
|
||||
- "React 18.2"
|
||||
- "TypeScript 5.3"
|
||||
- "Tailwind CSS 3.4"
|
||||
beginner_friendly: true
|
||||
|
||||
react_spa:
|
||||
name: "React SPA"
|
||||
current_version: "18.2"
|
||||
good_for: ["complex interactions", "existing APIs", "flexibility"]
|
||||
not_ideal_for: ["SEO critical", "initial load time"]
|
||||
pairs_with:
|
||||
- "Vite 5.0"
|
||||
- "React Router 6.21"
|
||||
- "TypeScript 5.3"
|
||||
beginner_friendly: true
|
||||
|
||||
vue:
|
||||
name: "Vue.js"
|
||||
current_version: "3.4"
|
||||
good_for: ["progressive enhancement", "simple mental model", "template syntax"]
|
||||
not_ideal_for: ["React ecosystem needs", "hiring pool"]
|
||||
pairs_with:
|
||||
- "Nuxt 3.9"
|
||||
- "Vite 5.0"
|
||||
- "Pinia 2.1"
|
||||
beginner_friendly: true
|
||||
|
||||
solidjs:
|
||||
name: "SolidJS"
|
||||
current_version: "1.8"
|
||||
good_for: ["performance", "fine-grained reactivity", "small bundle"]
|
||||
not_ideal_for: ["ecosystem size", "learning resources"]
|
||||
pairs_with:
|
||||
- "SolidStart 0.4"
|
||||
- "Vite 5.0"
|
||||
beginner_friendly: false
|
||||
|
||||
state_management:
|
||||
triggers: ["state", "store", "client state", "data flow", "redux"]
|
||||
importance: "high"
|
||||
affects: "frontend epics"
|
||||
options:
|
||||
zustand:
|
||||
name: "Zustand"
|
||||
current_version: "4.4"
|
||||
good_for: ["simplicity", "TypeScript", "small bundle", "React"]
|
||||
not_ideal_for: ["time-travel debugging", "Redux ecosystem"]
|
||||
beginner_friendly: true
|
||||
|
||||
redux_toolkit:
|
||||
name: "Redux Toolkit"
|
||||
current_version: "2.0"
|
||||
good_for: ["complex state", "debugging", "ecosystem", "predictable"]
|
||||
not_ideal_for: ["simple apps", "boilerplate"]
|
||||
beginner_friendly: false
|
||||
|
||||
tanstack_query:
|
||||
name: "TanStack Query"
|
||||
current_version: "5.17"
|
||||
good_for: ["server state", "caching", "synchronization", "mutations"]
|
||||
not_ideal_for: ["pure client state", "offline-heavy"]
|
||||
beginner_friendly: true
|
||||
|
||||
jotai:
|
||||
name: "Jotai"
|
||||
current_version: "2.6"
|
||||
good_for: ["atomic state", "React Suspense", "TypeScript"]
|
||||
not_ideal_for: ["debugging tools", "ecosystem size"]
|
||||
beginner_friendly: false
|
||||
|
||||
realtime:
|
||||
triggers: ["real-time", "websocket", "live", "push", "streaming", "collaborative"]
|
||||
importance: "high"
|
||||
affects: "real-time feature epics"
|
||||
options:
|
||||
socketio:
|
||||
name: "Socket.io"
|
||||
current_version: "4.6"
|
||||
good_for: ["fallbacks", "rooms", "namespaces", "reliability"]
|
||||
not_ideal_for: ["raw performance", "simple needs"]
|
||||
pairs_with:
|
||||
- "socket.io-client 4.6"
|
||||
beginner_friendly: true
|
||||
|
||||
websocket_native:
|
||||
name: "Native WebSocket"
|
||||
good_for: ["performance", "simple needs", "no dependencies"]
|
||||
not_ideal_for: ["fallbacks", "reconnection", "complex patterns"]
|
||||
pairs_with:
|
||||
- "ws 8.16"
|
||||
beginner_friendly: false
|
||||
|
||||
pusher:
|
||||
name: "Pusher"
|
||||
good_for: ["managed service", "quick setup", "global infrastructure"]
|
||||
not_ideal_for: ["cost at scale", "self-hosted needs"]
|
||||
pairs_with:
|
||||
- "pusher-js 8.4"
|
||||
beginner_friendly: true
|
||||
|
||||
ably:
|
||||
name: "Ably"
|
||||
current_version: "1.2"
|
||||
good_for: ["guaranteed delivery", "presence", "history", "managed"]
|
||||
not_ideal_for: ["cost sensitive", "simple needs"]
|
||||
pairs_with:
|
||||
- "ably 1.2"
|
||||
beginner_friendly: true
|
||||
|
||||
file_storage:
|
||||
triggers: ["file upload", "images", "documents", "media", "blob storage", "assets"]
|
||||
importance: "medium"
|
||||
affects: "content epics"
|
||||
options:
|
||||
s3:
|
||||
name: "AWS S3"
|
||||
good_for: ["scale", "durability", "ecosystem", "CDN integration"]
|
||||
not_ideal_for: ["simple needs", "cost optimization"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-s3 3.478"
|
||||
- "multer-s3 3.0"
|
||||
beginner_friendly: false
|
||||
|
||||
cloudinary:
|
||||
name: "Cloudinary"
|
||||
good_for: ["image optimization", "transformations", "CDN", "easy setup"]
|
||||
not_ideal_for: ["raw files", "cost at scale"]
|
||||
pairs_with:
|
||||
- "cloudinary 1.41"
|
||||
beginner_friendly: true
|
||||
|
||||
uploadthing:
|
||||
name: "UploadThing"
|
||||
current_version: "6.0"
|
||||
good_for: ["Next.js", "type safety", "simple setup"]
|
||||
not_ideal_for: ["non-Next.js", "complex requirements"]
|
||||
pairs_with:
|
||||
- "uploadthing 6.0"
|
||||
beginner_friendly: true
|
||||
|
||||
local_storage:
|
||||
name: "Local File System"
|
||||
good_for: ["development", "on-premise", "simple needs"]
|
||||
not_ideal_for: ["scale", "CDN", "distributed systems"]
|
||||
pairs_with:
|
||||
- "multer 1.4"
|
||||
beginner_friendly: true
|
||||
|
||||
search:
|
||||
triggers: ["search", "full text", "elasticsearch", "algolia", "fuzzy"]
|
||||
importance: "medium"
|
||||
affects: "search and discovery epics"
|
||||
options:
|
||||
postgres_fts:
|
||||
name: "PostgreSQL Full Text Search"
|
||||
good_for: ["simple search", "no extra infrastructure", "cost effective"]
|
||||
not_ideal_for: ["complex relevance", "fuzzy matching", "facets"]
|
||||
beginner_friendly: true
|
||||
|
||||
elasticsearch:
|
||||
name: "Elasticsearch"
|
||||
current_version: "8.11"
|
||||
good_for: ["complex search", "analytics", "aggregations", "scale"]
|
||||
not_ideal_for: ["simple needs", "operational overhead"]
|
||||
pairs_with:
|
||||
- "@elastic/elasticsearch 8.11"
|
||||
beginner_friendly: false
|
||||
|
||||
algolia:
|
||||
name: "Algolia"
|
||||
good_for: ["instant search", "typo tolerance", "managed service", "speed"]
|
||||
not_ideal_for: ["cost at scale", "data sovereignty"]
|
||||
pairs_with:
|
||||
- "algoliasearch 4.22"
|
||||
beginner_friendly: true
|
||||
|
||||
typesense:
|
||||
name: "Typesense"
|
||||
current_version: "1.7"
|
||||
good_for: ["open source alternative to Algolia", "typo tolerance", "self-hosted"]
|
||||
not_ideal_for: ["managed service needs", "small projects"]
|
||||
pairs_with:
|
||||
- "typesense 1.7"
|
||||
beginner_friendly: false
|
||||
|
||||
background_jobs:
|
||||
triggers: ["queue", "jobs", "workers", "async", "background processing", "scheduled"]
|
||||
importance: "medium"
|
||||
affects: "async processing epics"
|
||||
options:
|
||||
bullmq:
|
||||
name: "BullMQ"
|
||||
current_version: "5.1"
|
||||
good_for: ["Redis-based", "reliable", "dashboard", "Node.js"]
|
||||
not_ideal_for: ["multi-language", "serverless"]
|
||||
pairs_with:
|
||||
- "Redis 7.2"
|
||||
beginner_friendly: true
|
||||
|
||||
sqs:
|
||||
name: "AWS SQS"
|
||||
good_for: ["managed service", "scale", "AWS ecosystem", "serverless"]
|
||||
not_ideal_for: ["local development", "complex patterns"]
|
||||
pairs_with:
|
||||
- "@aws-sdk/client-sqs 3.478"
|
||||
beginner_friendly: false
|
||||
|
||||
temporal:
|
||||
name: "Temporal"
|
||||
current_version: "1.22"
|
||||
good_for: ["complex workflows", "durability", "long-running", "saga pattern"]
|
||||
not_ideal_for: ["simple jobs", "quick setup"]
|
||||
pairs_with:
|
||||
- "@temporalio/client 1.9"
|
||||
beginner_friendly: false
|
||||
|
||||
inngest:
|
||||
name: "Inngest"
|
||||
current_version: "3.8"
|
||||
good_for: ["serverless", "event-driven", "TypeScript", "retries"]
|
||||
not_ideal_for: ["self-hosted", "complex workflows"]
|
||||
pairs_with:
|
||||
- "inngest 3.8"
|
||||
beginner_friendly: true
|
||||
|
||||
deployment_target:
|
||||
triggers: ["deployment", "hosting", "infrastructure", "cloud", "server"]
|
||||
importance: "high"
|
||||
affects: "all epics"
|
||||
options:
|
||||
vercel:
|
||||
name: "Vercel"
|
||||
good_for: ["Next.js", "edge functions", "preview deployments", "simplicity"]
|
||||
not_ideal_for: ["complex backends", "cost at scale", "non-JS"]
|
||||
beginner_friendly: true
|
||||
|
||||
aws:
|
||||
name: "AWS"
|
||||
good_for: ["everything", "scale", "compliance", "flexibility"]
|
||||
not_ideal_for: ["simplicity", "predictable costs", "small projects"]
|
||||
beginner_friendly: false
|
||||
|
||||
railway:
|
||||
name: "Railway"
|
||||
good_for: ["simplicity", "databases included", "quick setup"]
|
||||
not_ideal_for: ["enterprise needs", "complex requirements"]
|
||||
beginner_friendly: true
|
||||
|
||||
fly_io:
|
||||
name: "Fly.io"
|
||||
good_for: ["edge deployment", "global distribution", "containers"]
|
||||
not_ideal_for: ["managed databases", "enterprise support"]
|
||||
beginner_friendly: false
|
||||
|
||||
# Pattern combinations that work well together
|
||||
common_stacks:
|
||||
modern_fullstack:
|
||||
name: "Modern Full-Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "PostgreSQL 15 or Supabase"
|
||||
- "Prisma ORM 5.6"
|
||||
- "NextAuth.js 4.24"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "TypeScript 5.3"
|
||||
- "Vercel deployment"
|
||||
good_for: "Most web applications"
|
||||
|
||||
enterprise_stack:
|
||||
name: "Enterprise Stack"
|
||||
components:
|
||||
- "NestJS 10.3"
|
||||
- "PostgreSQL 15"
|
||||
- "TypeORM 0.3"
|
||||
- "Auth0"
|
||||
- "React 18.2 + TypeScript"
|
||||
- "AWS deployment"
|
||||
good_for: "Large scale, compliance needs"
|
||||
|
||||
startup_stack:
|
||||
name: "Rapid Development Stack"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Supabase"
|
||||
- "Clerk Auth"
|
||||
- "Tailwind CSS 3.4"
|
||||
- "Vercel deployment"
|
||||
good_for: "MVPs and rapid prototyping"
|
||||
|
||||
realtime_stack:
|
||||
name: "Real-time Collaboration"
|
||||
components:
|
||||
- "Next.js 14"
|
||||
- "Socket.io 4.6"
|
||||
- "Redis 7.2"
|
||||
- "PostgreSQL 15"
|
||||
- "Railway deployment"
|
||||
good_for: "Collaborative applications"
|
||||
|
||||
# WARNING: Version numbers are illustrative - actual versions should be verified
|
||||
# during workflow execution via web search for current stable versions
|
||||
|
||||
# Starter templates that make architectural decisions
|
||||
starter_templates:
|
||||
create_next_app:
|
||||
name: "Create Next App"
|
||||
command_search: "npx create-next-app@latest options"
|
||||
base_command: "npx create-next-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "TypeScript vs JavaScript (--typescript flag)"
|
||||
- "ESLint configuration (--eslint flag)"
|
||||
- "Tailwind CSS setup (--tailwind flag)"
|
||||
- "App Router vs Pages Router (--app flag)"
|
||||
- "src/ directory structure (--src-dir flag)"
|
||||
- "Import alias (@/* default)"
|
||||
project_structure: "Standard Next.js structure with app/ or pages/"
|
||||
good_for: ["Web applications", "SSR/SSG needs", "Full-stack React"]
|
||||
|
||||
create_t3_app:
|
||||
name: "Create T3 App"
|
||||
command_search: "create t3 app latest CLI options"
|
||||
base_command: "npm create t3-app@latest"
|
||||
interactive: true
|
||||
decisions_provided:
|
||||
- "Next.js framework (always)"
|
||||
- "TypeScript (always)"
|
||||
- "tRPC for type-safe APIs"
|
||||
- "Prisma ORM"
|
||||
- "NextAuth.js authentication"
|
||||
- "Tailwind CSS"
|
||||
- "Drizzle ORM (alternative to Prisma)"
|
||||
project_structure: "Opinionated full-stack structure"
|
||||
good_for: ["Type-safe full-stack", "Rapid development", "Best practices"]
|
||||
|
||||
create_vite:
|
||||
name: "Create Vite"
|
||||
command_search: "npm create vite templates options"
|
||||
base_command: "npm create vite@latest"
|
||||
interactive: true
|
||||
templates_available:
|
||||
- "vanilla"
|
||||
- "vanilla-ts"
|
||||
- "react"
|
||||
- "react-ts"
|
||||
- "react-swc"
|
||||
- "react-swc-ts"
|
||||
- "vue"
|
||||
- "vue-ts"
|
||||
- "svelte"
|
||||
- "svelte-ts"
|
||||
decisions_provided:
|
||||
- "Build tool (Vite)"
|
||||
- "Framework choice"
|
||||
- "TypeScript setup"
|
||||
- "HMR configuration"
|
||||
- "Development server"
|
||||
project_structure: "Minimal, framework-specific"
|
||||
good_for: ["SPAs", "Fast development", "Modern tooling"]
|
||||
|
||||
create_react_app:
|
||||
name: "Create React App"
|
||||
status: "DEPRECATED - Use Vite or Next.js instead"
|
||||
note: "No longer recommended by React team"
|
||||
|
||||
create_remix:
|
||||
name: "Create Remix"
|
||||
command_search: "npx create-remix latest options"
|
||||
base_command: "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 options"
|
||||
base_command: "nest new"
|
||||
decisions_provided:
|
||||
- "TypeScript (always)"
|
||||
- "Package manager"
|
||||
- "Testing framework (Jest)"
|
||||
- "Linting (ESLint)"
|
||||
- "Project structure (modules/controllers/services)"
|
||||
project_structure: "Enterprise Angular-style backend"
|
||||
good_for: ["Enterprise APIs", "Microservices", "GraphQL APIs"]
|
||||
|
||||
create_expo_app:
|
||||
name: "Create Expo App"
|
||||
command_search: "create-expo-app templates latest"
|
||||
base_command: "npx create-expo-app"
|
||||
decisions_provided:
|
||||
- "React Native setup"
|
||||
- "TypeScript option"
|
||||
- "Navigation library option"
|
||||
- "Expo SDK version"
|
||||
good_for: ["Cross-platform mobile", "React Native apps"]
|
||||
|
||||
create_vue:
|
||||
name: "Create Vue"
|
||||
command_search: "npm create vue latest options"
|
||||
base_command: "npm create vue@latest"
|
||||
decisions_provided:
|
||||
- "Vue 3"
|
||||
- "TypeScript option"
|
||||
- "JSX support"
|
||||
- "Vue Router"
|
||||
- "Pinia state management"
|
||||
- "Vitest for testing"
|
||||
- "ESLint + Prettier"
|
||||
good_for: ["Vue applications", "Progressive web apps"]
|
||||
|
||||
create_astro:
|
||||
name: "Create Astro"
|
||||
command_search: "npm create astro latest templates"
|
||||
base_command: "npm create astro@latest"
|
||||
decisions_provided:
|
||||
- "Astro framework"
|
||||
- "TypeScript strictness"
|
||||
- "Template choice"
|
||||
- "Framework integrations"
|
||||
good_for: ["Content sites", "Static sites", "Islands architecture"]
|
||||
|
||||
create_svelte:
|
||||
name: "Create Svelte"
|
||||
command_search: "npm create svelte latest options"
|
||||
base_command: "npm create svelte@latest"
|
||||
decisions_provided:
|
||||
- "SvelteKit framework"
|
||||
- "TypeScript option"
|
||||
- "ESLint"
|
||||
- "Prettier"
|
||||
- "Testing setup"
|
||||
good_for: ["Svelte applications", "Compiled frameworks"]
|
||||
|
||||
cargo_new:
|
||||
name: "Cargo New (Rust)"
|
||||
command_search: "cargo new options binary library"
|
||||
base_command: "cargo new"
|
||||
decisions_provided:
|
||||
- "Binary vs Library (--bin or --lib)"
|
||||
- "Project structure"
|
||||
- "Cargo.toml setup"
|
||||
good_for: ["Rust CLI tools", "Systems programming", "Performance critical"]
|
||||
|
||||
dotnet_new:
|
||||
name: ".NET CLI"
|
||||
command_search: "dotnet new templates list"
|
||||
base_command: "dotnet new"
|
||||
templates_available:
|
||||
- "webapi"
|
||||
- "webapp"
|
||||
- "blazor"
|
||||
- "console"
|
||||
- "classlib"
|
||||
decisions_provided:
|
||||
- "Project type"
|
||||
- ".NET version"
|
||||
- "Authentication option"
|
||||
- "HTTPS configuration"
|
||||
good_for: ["C# applications", "Enterprise", "Windows development"]
|
||||
|
||||
rails_new:
|
||||
name: "Rails New"
|
||||
command_search: "rails new options latest"
|
||||
base_command: "rails new"
|
||||
decisions_provided:
|
||||
- "Database (PostgreSQL/MySQL/SQLite)"
|
||||
- "CSS framework"
|
||||
- "JavaScript approach"
|
||||
- "Testing framework"
|
||||
- "API-only mode"
|
||||
good_for: ["Ruby web apps", "Rapid prototyping", "Convention over configuration"]
|
||||
|
||||
django_startproject:
|
||||
name: "Django Start Project"
|
||||
command_search: "django-admin startproject structure"
|
||||
base_command: "django-admin startproject"
|
||||
decisions_provided:
|
||||
- "Django framework"
|
||||
- "Project structure"
|
||||
- "Settings configuration"
|
||||
- "Database (SQLite default)"
|
||||
good_for: ["Python web apps", "Admin interfaces", "Content management"]
|
||||
|
||||
create_redwood_app:
|
||||
name: "Create RedwoodJS App"
|
||||
command_search: "yarn create redwood-app latest"
|
||||
base_command: "yarn create redwood-app"
|
||||
decisions_provided:
|
||||
- "RedwoodJS framework"
|
||||
- "TypeScript (default)"
|
||||
- "Prisma ORM"
|
||||
- "GraphQL API"
|
||||
- "Storybook"
|
||||
- "Testing setup"
|
||||
project_structure: "Monorepo with api/ and web/"
|
||||
good_for: ["Full-stack JAMstack", "Startups", "Rapid development"]
|
||||
|
||||
# Starter template selection heuristics
|
||||
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", "react_native_cli"]
|
||||
considerations: "Need native modules? → React Native CLI. Simpler setup? → Expo"
|
||||
|
||||
api_backend:
|
||||
recommended: ["nest_new", "express_generator", "fastify_cli"]
|
||||
considerations: "Enterprise? → NestJS. Simple? → Express. Performance? → Fastify"
|
||||
|
||||
cli_tool:
|
||||
recommended: ["cargo_new", "go_mod_init", "npm_init"]
|
||||
considerations: "Performance critical? → Rust/Go. Quick script? → Node.js/Python"
|
||||
|
||||
full_stack:
|
||||
recommended: ["create_t3_app", "create_redwood_app", "rails_new"]
|
||||
considerations: "Type safety? → T3. JAMstack? → Redwood. Ruby? → Rails"
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
|
@@ -1,162 +0,0 @@
|
||||
# Backend/API Service Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for backend/API architecture decisions.
|
||||
The LLM should:
|
||||
- Analyze the PRD to understand data flows, performance needs, and integrations
|
||||
- Guide decisions based on scale, team size, and operational complexity
|
||||
- Focus only on relevant architectural areas
|
||||
- Make intelligent recommendations that align with project requirements
|
||||
- Keep explanations concise and decision-focused
|
||||
</critical>
|
||||
|
||||
## Service Architecture Pattern
|
||||
|
||||
**Determine the Right Architecture**
|
||||
Based on the requirements, guide toward the appropriate pattern:
|
||||
|
||||
- **Monolith**: For most projects starting out, single deployment, simple operations
|
||||
- **Microservices**: Only when there's clear domain separation, large teams, or specific scaling needs
|
||||
- **Serverless**: For event-driven workloads, variable traffic, or minimal operations
|
||||
- **Modular Monolith**: Best of both worlds for growing projects
|
||||
|
||||
Don't default to microservices - most projects benefit from starting simple.
|
||||
|
||||
## Language and Framework Selection
|
||||
|
||||
**Choose Based on Context**
|
||||
Consider these factors intelligently:
|
||||
|
||||
- Team expertise (use what the team knows unless there's a compelling reason)
|
||||
- Performance requirements (Go/Rust for high performance, Python/Node for rapid development)
|
||||
- Ecosystem needs (Python for ML/data, Node for full-stack JS, Java for enterprise)
|
||||
- Hiring pool and long-term maintenance
|
||||
|
||||
For beginners: Suggest mainstream options with good documentation.
|
||||
For experts: Let them specify preferences, discuss specific trade-offs only if asked.
|
||||
|
||||
## API Design Philosophy
|
||||
|
||||
**Match API Style to Client Needs**
|
||||
|
||||
- REST: Default for public APIs, simple CRUD, wide compatibility
|
||||
- GraphQL: Multiple clients with different data needs, complex relationships
|
||||
- gRPC: Service-to-service communication, high performance binary protocols
|
||||
- WebSocket/SSE: Real-time requirements
|
||||
|
||||
Don't ask about API paradigm if it's obvious from requirements (e.g., real-time chat needs WebSocket).
|
||||
|
||||
## Data Architecture
|
||||
|
||||
**Database Decisions Based on Data Characteristics**
|
||||
Analyze the data requirements to suggest:
|
||||
|
||||
- **Relational** (PostgreSQL/MySQL): Structured data, ACID requirements, complex queries
|
||||
- **Document** (MongoDB): Flexible schemas, hierarchical data, rapid prototyping
|
||||
- **Key-Value** (Redis/DynamoDB): Caching, sessions, simple lookups
|
||||
- **Time-series**: IoT, metrics, event data
|
||||
- **Graph**: Social networks, recommendation engines
|
||||
|
||||
Consider polyglot persistence only for clear, distinct use cases.
|
||||
|
||||
**Data Access Layer**
|
||||
|
||||
- ORMs for developer productivity and type safety
|
||||
- Query builders for flexibility with some safety
|
||||
- Raw SQL only when performance is critical
|
||||
|
||||
Match to team expertise and project complexity.
|
||||
|
||||
## Security and Authentication
|
||||
|
||||
**Security Appropriate to Risk**
|
||||
|
||||
- Internal tools: Simple API keys might suffice
|
||||
- B2C applications: Managed auth services (Auth0, Firebase Auth)
|
||||
- B2B/Enterprise: SAML, SSO, advanced RBAC
|
||||
- Financial/Healthcare: Compliance-driven requirements
|
||||
|
||||
Don't over-engineer security for prototypes, don't under-engineer for production.
|
||||
|
||||
## Messaging and Events
|
||||
|
||||
**Only If Required by the Architecture**
|
||||
Determine if async processing is actually needed:
|
||||
|
||||
- Message queues for decoupling, reliability, buffering
|
||||
- Event streaming for event sourcing, real-time analytics
|
||||
- Pub/sub for fan-out scenarios
|
||||
|
||||
Skip this entirely for simple request-response APIs.
|
||||
|
||||
## Operational Considerations
|
||||
|
||||
**Observability Based on Criticality**
|
||||
|
||||
- Development: Basic logging might suffice
|
||||
- Production: Structured logging, metrics, tracing
|
||||
- Mission-critical: Full observability stack
|
||||
|
||||
**Scaling Strategy**
|
||||
|
||||
- Start with vertical scaling (simpler)
|
||||
- Plan for horizontal scaling if needed
|
||||
- Consider auto-scaling for variable loads
|
||||
|
||||
## Performance Requirements
|
||||
|
||||
**Right-Size Performance Decisions**
|
||||
|
||||
- Don't optimize prematurely
|
||||
- Identify actual bottlenecks from requirements
|
||||
- Consider caching strategically, not everywhere
|
||||
- Database optimization before adding complexity
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
**External Service Integration**
|
||||
Based on the PRD's integration requirements:
|
||||
|
||||
- Circuit breakers for resilience
|
||||
- Rate limiting for API consumption
|
||||
- Webhook patterns for event reception
|
||||
- SDK vs. API direct calls
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
**Match Deployment to Team Capability**
|
||||
|
||||
- Small teams: Managed platforms (Heroku, Railway, Fly.io)
|
||||
- DevOps teams: Kubernetes, cloud-native
|
||||
- Enterprise: Consider existing infrastructure
|
||||
|
||||
**CI/CD Complexity**
|
||||
|
||||
- Start simple: Platform auto-deploy
|
||||
- Add complexity as needed: testing stages, approvals, rollback
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a REST API serving a mobile app:**
|
||||
Focus on response times, offline support, versioning, and push notifications.
|
||||
|
||||
**For a data processing pipeline:**
|
||||
Emphasize batch vs. stream processing, data validation, error handling, and monitoring.
|
||||
|
||||
**For a microservices migration:**
|
||||
Discuss service boundaries, data consistency, service discovery, and distributed tracing.
|
||||
|
||||
**For an enterprise integration:**
|
||||
Focus on security, compliance, audit logging, and existing system compatibility.
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure decisions as:
|
||||
|
||||
- **Choice**: [Specific technology with version]
|
||||
- **Rationale**: [One sentence why this fits the requirements]
|
||||
- **Trade-off**: [What we're optimizing for vs. what we're accepting]
|
||||
|
||||
Keep technical decisions definitive and version-specific for LLM consumption.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,149 +0,0 @@
|
||||
# CLI Tool Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for CLI tool architecture decisions.
|
||||
The LLM should:
|
||||
- Understand the tool's purpose and target users from requirements
|
||||
- Guide framework choice based on distribution needs and complexity
|
||||
- Focus on CLI-specific UX patterns
|
||||
- Consider packaging and distribution strategy
|
||||
- Keep it simple unless complexity is justified
|
||||
</critical>
|
||||
|
||||
## Language and Framework Selection
|
||||
|
||||
**Choose Based on Distribution and Users**
|
||||
|
||||
- **Node.js**: NPM distribution, JavaScript ecosystem, cross-platform
|
||||
- **Go**: Single binary distribution, excellent performance
|
||||
- **Python**: Data/science tools, rich ecosystem, pip distribution
|
||||
- **Rust**: Performance-critical, memory-safe, growing ecosystem
|
||||
- **Bash**: Simple scripts, Unix-only, no dependencies
|
||||
|
||||
Consider your users: Developers might have Node/Python, but end users need standalone binaries.
|
||||
|
||||
## CLI Framework Choice
|
||||
|
||||
**Match Complexity to Needs**
|
||||
Based on the tool's requirements:
|
||||
|
||||
- **Simple scripts**: Use built-in argument parsing
|
||||
- **Command-based**: Commander.js, Click, Cobra, Clap
|
||||
- **Interactive**: Inquirer, Prompt, Dialoguer
|
||||
- **Full TUI**: Blessed, Bubble Tea, Ratatui
|
||||
|
||||
Don't use a heavy framework for a simple script, but don't parse args manually for complex CLIs.
|
||||
|
||||
## Command Architecture
|
||||
|
||||
**Command Structure Design**
|
||||
|
||||
- Single command vs. sub-commands
|
||||
- Flag and argument patterns
|
||||
- Configuration file support
|
||||
- Environment variable integration
|
||||
|
||||
Follow platform conventions (POSIX-style flags, standard exit codes).
|
||||
|
||||
## User Experience Patterns
|
||||
|
||||
**CLI UX Best Practices**
|
||||
|
||||
- Help text and usage examples
|
||||
- Progress indicators for long operations
|
||||
- Colored output for clarity
|
||||
- Machine-readable output options (JSON, quiet mode)
|
||||
- Sensible defaults with override options
|
||||
|
||||
## Configuration Management
|
||||
|
||||
**Settings Strategy**
|
||||
Based on tool complexity:
|
||||
|
||||
- Command-line flags for one-off changes
|
||||
- Config files for persistent settings
|
||||
- Environment variables for deployment config
|
||||
- Cascading configuration (defaults → config → env → flags)
|
||||
|
||||
## Error Handling
|
||||
|
||||
**User-Friendly Errors**
|
||||
|
||||
- Clear error messages with actionable fixes
|
||||
- Exit codes following conventions
|
||||
- Verbose/debug modes for troubleshooting
|
||||
- Graceful handling of common issues
|
||||
|
||||
## Installation and Distribution
|
||||
|
||||
**Packaging Strategy**
|
||||
|
||||
- **NPM/PyPI**: For developer tools
|
||||
- **Homebrew/Snap/Chocolatey**: For end-user tools
|
||||
- **Binary releases**: GitHub releases with multiple platforms
|
||||
- **Docker**: For complex dependencies
|
||||
- **Shell script**: For simple Unix tools
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**CLI Testing Approach**
|
||||
|
||||
- Unit tests for core logic
|
||||
- Integration tests for commands
|
||||
- Snapshot testing for output
|
||||
- Cross-platform testing if targeting multiple OS
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
**Optimization Where Needed**
|
||||
|
||||
- Startup time for frequently-used commands
|
||||
- Streaming for large data processing
|
||||
- Parallel execution where applicable
|
||||
- Efficient file system operations
|
||||
|
||||
## Plugin Architecture
|
||||
|
||||
**Extensibility** (if needed)
|
||||
|
||||
- Plugin system design
|
||||
- Hook mechanisms
|
||||
- API for extensions
|
||||
- Plugin discovery and loading
|
||||
|
||||
Only if the PRD indicates extensibility requirements.
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Build Tool:**
|
||||
Focus on performance, watch mode, configuration management, and plugin system.
|
||||
|
||||
**For a Dev Utility:**
|
||||
Emphasize developer experience, integration with existing tools, and clear output.
|
||||
|
||||
**For a Data Processing Tool:**
|
||||
Focus on streaming, progress reporting, error recovery, and format conversion.
|
||||
|
||||
**For a System Admin Tool:**
|
||||
Emphasize permission handling, logging, dry-run mode, and safety checks.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Follow platform conventions** - Users expect familiar patterns
|
||||
2. **Fail fast with clear errors** - Don't leave users guessing
|
||||
3. **Provide escape hatches** - Debug mode, verbose output, dry runs
|
||||
4. **Document through examples** - Show, don't just tell
|
||||
5. **Respect user time** - Fast startup, helpful defaults
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Language**: [Choice with version]
|
||||
- **Framework**: [CLI framework if applicable]
|
||||
- **Distribution**: [How users will install]
|
||||
- **Key commands**: [Primary user interactions]
|
||||
|
||||
Keep focus on user-facing behavior and implementation simplicity.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,193 +0,0 @@
|
||||
# Data Pipeline/Analytics Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for data pipeline and analytics architecture decisions.
|
||||
The LLM should:
|
||||
- Understand data volume, velocity, and variety from requirements
|
||||
- Guide tool selection based on scale and latency needs
|
||||
- Consider data governance and quality requirements
|
||||
- Balance batch vs. stream processing needs
|
||||
- Focus on maintainability and observability
|
||||
</critical>
|
||||
|
||||
## Processing Architecture
|
||||
|
||||
**Batch vs. Stream vs. Hybrid**
|
||||
Based on requirements:
|
||||
|
||||
- **Batch**: For periodic processing, large volumes, complex transformations
|
||||
- **Stream**: For real-time requirements, event-driven, continuous processing
|
||||
- **Lambda Architecture**: Both batch and stream for different use cases
|
||||
- **Kappa Architecture**: Stream-only with replay capability
|
||||
|
||||
Don't use streaming for daily reports, or batch for real-time alerts.
|
||||
|
||||
## Technology Stack
|
||||
|
||||
**Choose Based on Scale and Complexity**
|
||||
|
||||
- **Small Scale**: Python scripts, Pandas, PostgreSQL
|
||||
- **Medium Scale**: Airflow, Spark, Redshift/BigQuery
|
||||
- **Large Scale**: Databricks, Snowflake, custom Kubernetes
|
||||
- **Real-time**: Kafka, Flink, ClickHouse, Druid
|
||||
|
||||
Start simple and evolve - don't build for imaginary scale.
|
||||
|
||||
## Orchestration Platform
|
||||
|
||||
**Workflow Management**
|
||||
Based on complexity:
|
||||
|
||||
- **Simple**: Cron jobs, Python scripts
|
||||
- **Medium**: Apache Airflow, Prefect, Dagster
|
||||
- **Complex**: Kubernetes Jobs, Argo Workflows
|
||||
- **Managed**: Cloud Composer, AWS Step Functions
|
||||
|
||||
Consider team expertise and operational overhead.
|
||||
|
||||
## Data Storage Architecture
|
||||
|
||||
**Storage Layer Design**
|
||||
|
||||
- **Data Lake**: Raw data in object storage (S3, GCS)
|
||||
- **Data Warehouse**: Structured, optimized for analytics
|
||||
- **Data Lakehouse**: Hybrid approach (Delta Lake, Iceberg)
|
||||
- **Operational Store**: For serving layer
|
||||
|
||||
**File Formats**
|
||||
|
||||
- Parquet for columnar analytics
|
||||
- Avro for row-based streaming
|
||||
- JSON for flexibility
|
||||
- CSV for simplicity
|
||||
|
||||
## ETL/ELT Strategy
|
||||
|
||||
**Transformation Approach**
|
||||
|
||||
- **ETL**: Transform before loading (traditional)
|
||||
- **ELT**: Transform in warehouse (modern, scalable)
|
||||
- **Streaming ETL**: Continuous transformation
|
||||
|
||||
Consider compute costs and transformation complexity.
|
||||
|
||||
## Data Quality Framework
|
||||
|
||||
**Quality Assurance**
|
||||
|
||||
- Schema validation
|
||||
- Data profiling and anomaly detection
|
||||
- Completeness and freshness checks
|
||||
- Lineage tracking
|
||||
- Quality metrics and monitoring
|
||||
|
||||
Build quality checks appropriate to data criticality.
|
||||
|
||||
## Schema Management
|
||||
|
||||
**Schema Evolution**
|
||||
|
||||
- Schema registry for streaming
|
||||
- Version control for schemas
|
||||
- Backward compatibility strategy
|
||||
- Schema inference vs. strict schemas
|
||||
|
||||
## Processing Frameworks
|
||||
|
||||
**Computation Engines**
|
||||
|
||||
- **Spark**: General-purpose, batch and stream
|
||||
- **Flink**: Low-latency streaming
|
||||
- **Beam**: Portable, multi-runtime
|
||||
- **Pandas/Polars**: Small-scale, in-memory
|
||||
- **DuckDB**: Local analytical processing
|
||||
|
||||
Match framework to processing patterns.
|
||||
|
||||
## Data Modeling
|
||||
|
||||
**Analytical Modeling**
|
||||
|
||||
- Star schema for BI tools
|
||||
- Data vault for flexibility
|
||||
- Wide tables for performance
|
||||
- Time-series modeling for metrics
|
||||
|
||||
Consider query patterns and tool requirements.
|
||||
|
||||
## Monitoring and Observability
|
||||
|
||||
**Pipeline Monitoring**
|
||||
|
||||
- Job success/failure tracking
|
||||
- Data quality metrics
|
||||
- Processing time and throughput
|
||||
- Cost monitoring
|
||||
- Alerting strategy
|
||||
|
||||
## Security and Governance
|
||||
|
||||
**Data Governance**
|
||||
|
||||
- Access control and permissions
|
||||
- Data encryption at rest and transit
|
||||
- PII handling and masking
|
||||
- Audit logging
|
||||
- Compliance requirements (GDPR, HIPAA)
|
||||
|
||||
Scale governance to regulatory requirements.
|
||||
|
||||
## Development Practices
|
||||
|
||||
**DataOps Approach**
|
||||
|
||||
- Version control for code and configs
|
||||
- Testing strategy (unit, integration, data)
|
||||
- CI/CD for pipelines
|
||||
- Environment management
|
||||
- Documentation standards
|
||||
|
||||
## Serving Layer
|
||||
|
||||
**Data Consumption**
|
||||
|
||||
- BI tool integration
|
||||
- API for programmatic access
|
||||
- Export capabilities
|
||||
- Caching strategy
|
||||
- Query optimization
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For Real-time Analytics:**
|
||||
Focus on streaming infrastructure, low-latency storage, and real-time dashboards.
|
||||
|
||||
**For ML Feature Store:**
|
||||
Emphasize feature computation, versioning, serving latency, and training/serving skew.
|
||||
|
||||
**For Business Intelligence:**
|
||||
Focus on dimensional modeling, semantic layer, and self-service analytics.
|
||||
|
||||
**For Log Analytics:**
|
||||
Emphasize ingestion scale, retention policies, and search capabilities.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Start with the end in mind** - Know how data will be consumed
|
||||
2. **Design for failure** - Pipelines will break, plan recovery
|
||||
3. **Monitor everything** - You can't fix what you can't see
|
||||
4. **Version and test** - Data pipelines are code
|
||||
5. **Keep it simple** - Complexity kills maintainability
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Processing**: [Batch/Stream/Hybrid approach]
|
||||
- **Stack**: [Core technologies with versions]
|
||||
- **Storage**: [Lake/Warehouse strategy]
|
||||
- **Orchestration**: [Workflow platform]
|
||||
|
||||
Focus on data flow and transformation logic.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,182 +0,0 @@
|
||||
# Desktop Application Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for desktop application architecture decisions.
|
||||
The LLM should:
|
||||
- Understand the application's purpose and target OS from requirements
|
||||
- Balance native performance with development efficiency
|
||||
- Consider distribution and update mechanisms
|
||||
- Focus on desktop-specific UX patterns
|
||||
- Plan for OS-specific integrations
|
||||
</critical>
|
||||
|
||||
## Framework Selection
|
||||
|
||||
**Choose Based on Requirements and Team**
|
||||
|
||||
- **Electron**: Web technologies, cross-platform, rapid development
|
||||
- **Tauri**: Rust + Web frontend, smaller binaries, better performance
|
||||
- **Qt**: C++/Python, native performance, extensive widgets
|
||||
- **.NET MAUI/WPF**: Windows-focused, C# teams
|
||||
- **SwiftUI/AppKit**: Mac-only, native experience
|
||||
- **JavaFX/Swing**: Java teams, enterprise apps
|
||||
- **Flutter Desktop**: Dart, consistent cross-platform UI
|
||||
|
||||
Don't use Electron for performance-critical apps, or Qt for simple utilities.
|
||||
|
||||
## Architecture Pattern
|
||||
|
||||
**Application Structure**
|
||||
Based on complexity:
|
||||
|
||||
- **MVC/MVVM**: For data-driven applications
|
||||
- **Component-Based**: For complex UIs
|
||||
- **Plugin Architecture**: For extensible apps
|
||||
- **Document-Based**: For editors/creators
|
||||
|
||||
Match pattern to application type and team experience.
|
||||
|
||||
## Native Integration
|
||||
|
||||
**OS-Specific Features**
|
||||
Based on requirements:
|
||||
|
||||
- System tray/menu bar integration
|
||||
- File associations and protocol handlers
|
||||
- Native notifications
|
||||
- OS-specific shortcuts and gestures
|
||||
- Dark mode and theme detection
|
||||
- Native menus and dialogs
|
||||
|
||||
Plan for platform differences in UX expectations.
|
||||
|
||||
## Data Management
|
||||
|
||||
**Local Data Strategy**
|
||||
|
||||
- **SQLite**: For structured data
|
||||
- **LevelDB/RocksDB**: For key-value storage
|
||||
- **JSON/XML files**: For simple configuration
|
||||
- **OS-specific stores**: Windows Registry, macOS Defaults
|
||||
|
||||
**Settings and Preferences**
|
||||
|
||||
- User vs. application settings
|
||||
- Portable vs. installed mode
|
||||
- Settings sync across devices
|
||||
|
||||
## Window Management
|
||||
|
||||
**Multi-Window Strategy**
|
||||
|
||||
- Single vs. multi-window architecture
|
||||
- Window state persistence
|
||||
- Multi-monitor support
|
||||
- Workspace/session management
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
**Desktop Performance**
|
||||
|
||||
- Startup time optimization
|
||||
- Memory usage monitoring
|
||||
- Background task management
|
||||
- GPU acceleration usage
|
||||
- Native vs. web rendering trade-offs
|
||||
|
||||
## Update Mechanism
|
||||
|
||||
**Application Updates**
|
||||
|
||||
- **Auto-update**: Electron-updater, Sparkle, Squirrel
|
||||
- **Store-based**: Mac App Store, Microsoft Store
|
||||
- **Manual**: Download from website
|
||||
- **Package manager**: Homebrew, Chocolatey, APT/YUM
|
||||
|
||||
Consider code signing and notarization requirements.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Desktop Security**
|
||||
|
||||
- Code signing certificates
|
||||
- Secure storage for credentials
|
||||
- Process isolation
|
||||
- Network security
|
||||
- Input validation
|
||||
- Automatic security updates
|
||||
|
||||
## Distribution Strategy
|
||||
|
||||
**Packaging and Installation**
|
||||
|
||||
- **Installers**: MSI, DMG, DEB/RPM
|
||||
- **Portable**: Single executable
|
||||
- **App stores**: Platform stores
|
||||
- **Package managers**: OS-specific
|
||||
|
||||
Consider installation permissions and user experience.
|
||||
|
||||
## IPC and Extensions
|
||||
|
||||
**Inter-Process Communication**
|
||||
|
||||
- Main/renderer process communication (Electron)
|
||||
- Plugin/extension system
|
||||
- CLI integration
|
||||
- Automation/scripting support
|
||||
|
||||
## Accessibility
|
||||
|
||||
**Desktop Accessibility**
|
||||
|
||||
- Screen reader support
|
||||
- Keyboard navigation
|
||||
- High contrast themes
|
||||
- Zoom/scaling support
|
||||
- OS accessibility APIs
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Desktop Testing**
|
||||
|
||||
- Unit tests for business logic
|
||||
- Integration tests for OS interactions
|
||||
- UI automation testing
|
||||
- Multi-OS testing matrix
|
||||
- Performance profiling
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Development IDE:**
|
||||
Focus on performance, plugin system, workspace management, and syntax highlighting.
|
||||
|
||||
**For a Media Player:**
|
||||
Emphasize codec support, hardware acceleration, media keys, and playlist management.
|
||||
|
||||
**For a Business Application:**
|
||||
Focus on data grids, reporting, printing, and enterprise integration.
|
||||
|
||||
**For a Creative Tool:**
|
||||
Emphasize canvas rendering, tool palettes, undo/redo, and file format support.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Respect platform conventions** - Mac != Windows != Linux
|
||||
2. **Optimize startup time** - Desktop users expect instant launch
|
||||
3. **Handle offline gracefully** - Desktop != always online
|
||||
4. **Integrate with OS** - Use native features appropriately
|
||||
5. **Plan distribution early** - Signing/notarization takes time
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Framework**: [Specific framework and version]
|
||||
- **Target OS**: [Primary and secondary platforms]
|
||||
- **Distribution**: [How users will install]
|
||||
- **Update strategy**: [How updates are delivered]
|
||||
|
||||
Focus on desktop-specific architectural decisions.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,191 +0,0 @@
|
||||
# Embedded/IoT System Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for embedded/IoT architecture decisions.
|
||||
The LLM should:
|
||||
- Understand hardware constraints and real-time requirements
|
||||
- Guide platform and RTOS selection based on use case
|
||||
- Consider power consumption and resource limitations
|
||||
- Balance features with memory/processing constraints
|
||||
- Focus on reliability and update mechanisms
|
||||
</critical>
|
||||
|
||||
## Hardware Platform Selection
|
||||
|
||||
**Choose Based on Requirements**
|
||||
|
||||
- **Microcontroller**: For simple, low-power, real-time tasks
|
||||
- **SoC/SBC**: For complex processing, Linux-capable
|
||||
- **FPGA**: For parallel processing, custom logic
|
||||
- **Hybrid**: MCU + application processor
|
||||
|
||||
Consider power budget, processing needs, and peripheral requirements.
|
||||
|
||||
## Operating System/RTOS
|
||||
|
||||
**OS Selection**
|
||||
Based on complexity:
|
||||
|
||||
- **Bare Metal**: Simple control loops, minimal overhead
|
||||
- **RTOS**: FreeRTOS, Zephyr for real-time requirements
|
||||
- **Embedded Linux**: Complex applications, networking
|
||||
- **Android Things/Windows IoT**: For specific ecosystems
|
||||
|
||||
Don't use Linux for battery-powered sensors, or bare metal for complex networking.
|
||||
|
||||
## Development Framework
|
||||
|
||||
**Language and Tools**
|
||||
|
||||
- **C/C++**: Maximum control, minimal overhead
|
||||
- **Rust**: Memory safety, modern tooling
|
||||
- **MicroPython/CircuitPython**: Rapid prototyping
|
||||
- **Arduino**: Beginner-friendly, large community
|
||||
- **Platform-specific SDKs**: ESP-IDF, STM32Cube
|
||||
|
||||
Match to team expertise and performance requirements.
|
||||
|
||||
## Communication Protocols
|
||||
|
||||
**Connectivity Strategy**
|
||||
Based on use case:
|
||||
|
||||
- **Local**: I2C, SPI, UART for sensor communication
|
||||
- **Wireless**: WiFi, Bluetooth, LoRa, Zigbee, cellular
|
||||
- **Industrial**: Modbus, CAN bus, MQTT
|
||||
- **Cloud**: HTTPS, MQTT, CoAP
|
||||
|
||||
Consider range, power consumption, and data rates.
|
||||
|
||||
## Power Management
|
||||
|
||||
**Power Optimization**
|
||||
|
||||
- Sleep modes and wake triggers
|
||||
- Dynamic frequency scaling
|
||||
- Peripheral power management
|
||||
- Battery monitoring and management
|
||||
- Energy harvesting considerations
|
||||
|
||||
Critical for battery-powered devices.
|
||||
|
||||
## Memory Architecture
|
||||
|
||||
**Memory Management**
|
||||
|
||||
- Static vs. dynamic allocation
|
||||
- Flash wear leveling
|
||||
- RAM optimization techniques
|
||||
- External storage options
|
||||
- Bootloader and OTA partitioning
|
||||
|
||||
Plan memory layout early - hard to change later.
|
||||
|
||||
## Firmware Architecture
|
||||
|
||||
**Code Organization**
|
||||
|
||||
- HAL (Hardware Abstraction Layer)
|
||||
- Modular driver architecture
|
||||
- Task/thread design
|
||||
- Interrupt handling strategy
|
||||
- State machine implementation
|
||||
|
||||
## Update Mechanism
|
||||
|
||||
**OTA Updates**
|
||||
|
||||
- Update delivery method
|
||||
- Rollback capability
|
||||
- Differential updates
|
||||
- Security and signing
|
||||
- Factory reset capability
|
||||
|
||||
Plan for field updates from day one.
|
||||
|
||||
## Security Architecture
|
||||
|
||||
**Embedded Security**
|
||||
|
||||
- Secure boot
|
||||
- Encrypted storage
|
||||
- Secure communication (TLS)
|
||||
- Hardware security modules
|
||||
- Attack surface minimization
|
||||
|
||||
Security is harder to add later.
|
||||
|
||||
## Data Management
|
||||
|
||||
**Local and Cloud Data**
|
||||
|
||||
- Edge processing vs. cloud processing
|
||||
- Local storage and buffering
|
||||
- Data compression
|
||||
- Time synchronization
|
||||
- Offline operation handling
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Embedded Testing**
|
||||
|
||||
- Unit testing on host
|
||||
- Hardware-in-the-loop testing
|
||||
- Integration testing
|
||||
- Environmental testing
|
||||
- Certification requirements
|
||||
|
||||
## Debugging and Monitoring
|
||||
|
||||
**Development Tools**
|
||||
|
||||
- Debug interfaces (JTAG, SWD)
|
||||
- Serial console
|
||||
- Logic analyzers
|
||||
- Remote debugging
|
||||
- Field diagnostics
|
||||
|
||||
## Production Considerations
|
||||
|
||||
**Manufacturing and Deployment**
|
||||
|
||||
- Provisioning process
|
||||
- Calibration requirements
|
||||
- Production testing
|
||||
- Device identification
|
||||
- Configuration management
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Smart Sensor:**
|
||||
Focus on ultra-low power, wireless communication, and edge processing.
|
||||
|
||||
**For an Industrial Controller:**
|
||||
Emphasize real-time performance, reliability, safety systems, and industrial protocols.
|
||||
|
||||
**For a Consumer IoT Device:**
|
||||
Focus on user experience, cloud integration, OTA updates, and cost optimization.
|
||||
|
||||
**For a Wearable:**
|
||||
Emphasize power efficiency, small form factor, BLE, and sensor fusion.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Design for constraints** - Memory, power, and processing are limited
|
||||
2. **Plan for failure** - Hardware fails, design for recovery
|
||||
3. **Security from the start** - Retrofitting is difficult
|
||||
4. **Test on real hardware** - Simulation has limits
|
||||
5. **Design for production** - Prototype != product
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Platform**: [MCU/SoC selection with part numbers]
|
||||
- **OS/RTOS**: [Operating system choice]
|
||||
- **Connectivity**: [Communication protocols and interfaces]
|
||||
- **Power**: [Power budget and management strategy]
|
||||
|
||||
Focus on hardware/software co-design decisions.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,193 +0,0 @@
|
||||
# Browser/Editor Extension Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for extension architecture decisions.
|
||||
The LLM should:
|
||||
- Understand the host platform (browser, VS Code, IDE, etc.)
|
||||
- Focus on extension-specific constraints and APIs
|
||||
- Consider distribution through official stores
|
||||
- Balance functionality with performance impact
|
||||
- Plan for permission models and security
|
||||
</critical>
|
||||
|
||||
## Extension Type and Platform
|
||||
|
||||
**Identify Target Platform**
|
||||
|
||||
- **Browser**: Chrome, Firefox, Safari, Edge
|
||||
- **VS Code**: Most popular code editor
|
||||
- **JetBrains IDEs**: IntelliJ, WebStorm, etc.
|
||||
- **Other Editors**: Sublime, Atom, Vim, Emacs
|
||||
- **Application-specific**: Figma, Sketch, Adobe
|
||||
|
||||
Each platform has unique APIs and constraints.
|
||||
|
||||
## Architecture Pattern
|
||||
|
||||
**Extension Architecture**
|
||||
Based on platform:
|
||||
|
||||
- **Browser**: Content scripts, background workers, popup UI
|
||||
- **VS Code**: Extension host, language server, webview
|
||||
- **IDE**: Plugin architecture, service providers
|
||||
- **Application**: Native API, JavaScript bridge
|
||||
|
||||
Follow platform-specific patterns and guidelines.
|
||||
|
||||
## Manifest and Configuration
|
||||
|
||||
**Extension Declaration**
|
||||
|
||||
- Manifest version and compatibility
|
||||
- Permission requirements
|
||||
- Activation events
|
||||
- Command registration
|
||||
- Context menu integration
|
||||
|
||||
Request minimum necessary permissions for user trust.
|
||||
|
||||
## Communication Architecture
|
||||
|
||||
**Inter-Component Communication**
|
||||
|
||||
- Message passing between components
|
||||
- Storage sync across instances
|
||||
- Native messaging (if needed)
|
||||
- WebSocket for external services
|
||||
|
||||
Design for async communication patterns.
|
||||
|
||||
## UI Integration
|
||||
|
||||
**User Interface Approach**
|
||||
|
||||
- **Popup/Panel**: For quick interactions
|
||||
- **Sidebar**: For persistent tools
|
||||
- **Content Injection**: Modify existing UI
|
||||
- **Custom Pages**: Full page experiences
|
||||
- **Statusbar**: For ambient information
|
||||
|
||||
Match UI to user workflow and platform conventions.
|
||||
|
||||
## State Management
|
||||
|
||||
**Data Persistence**
|
||||
|
||||
- Local storage for user preferences
|
||||
- Sync storage for cross-device
|
||||
- IndexedDB for large data
|
||||
- File system access (if permitted)
|
||||
|
||||
Consider storage limits and sync conflicts.
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
**Extension Performance**
|
||||
|
||||
- Lazy loading of features
|
||||
- Minimal impact on host performance
|
||||
- Efficient DOM manipulation
|
||||
- Memory leak prevention
|
||||
- Background task optimization
|
||||
|
||||
Extensions must not degrade host application performance.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
**Extension Security**
|
||||
|
||||
- Content Security Policy
|
||||
- Input sanitization
|
||||
- Secure communication
|
||||
- API key management
|
||||
- User data protection
|
||||
|
||||
Follow platform security best practices.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
**Development Tools**
|
||||
|
||||
- Hot reload during development
|
||||
- Debugging setup
|
||||
- Testing framework
|
||||
- Build pipeline
|
||||
- Version management
|
||||
|
||||
## Distribution Strategy
|
||||
|
||||
**Publishing and Updates**
|
||||
|
||||
- Official store submission
|
||||
- Review process requirements
|
||||
- Update mechanism
|
||||
- Beta testing channel
|
||||
- Self-hosting options
|
||||
|
||||
Plan for store review times and policies.
|
||||
|
||||
## API Integration
|
||||
|
||||
**External Service Communication**
|
||||
|
||||
- Authentication methods
|
||||
- CORS handling
|
||||
- Rate limiting
|
||||
- Offline functionality
|
||||
- Error handling
|
||||
|
||||
## Monetization
|
||||
|
||||
**Revenue Model** (if applicable)
|
||||
|
||||
- Free with premium features
|
||||
- Subscription model
|
||||
- One-time purchase
|
||||
- Enterprise licensing
|
||||
|
||||
Consider platform policies on monetization.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Extension Testing**
|
||||
|
||||
- Unit tests for logic
|
||||
- Integration tests with host API
|
||||
- Cross-browser/platform testing
|
||||
- Performance testing
|
||||
- User acceptance testing
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Password Manager Extension:**
|
||||
Focus on security, autofill integration, secure storage, and cross-browser sync.
|
||||
|
||||
**For a Developer Tool Extension:**
|
||||
Emphasize debugging capabilities, performance profiling, and workspace integration.
|
||||
|
||||
**For a Content Blocker:**
|
||||
Focus on performance, rule management, whitelist handling, and minimal overhead.
|
||||
|
||||
**For a Productivity Extension:**
|
||||
Emphasize keyboard shortcuts, quick access, sync, and workflow integration.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Respect the host** - Don't break or slow down the host application
|
||||
2. **Request minimal permissions** - Users are permission-aware
|
||||
3. **Fast activation** - Extensions should load instantly
|
||||
4. **Fail gracefully** - Handle API changes and errors
|
||||
5. **Follow guidelines** - Store policies are strictly enforced
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Platform**: [Specific platform and version support]
|
||||
- **Architecture**: [Component structure]
|
||||
- **Permissions**: [Required permissions and justification]
|
||||
- **Distribution**: [Store and update strategy]
|
||||
|
||||
Focus on platform-specific requirements and constraints.
|
||||
@@ -1,67 +0,0 @@
|
||||
# Extension Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Platform:** {{target_platform}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Category | Technology | Version | Justification |
|
||||
| ---------- | -------------- | -------------------- | -------------------------- |
|
||||
| Platform | {{platform}} | {{platform_version}} | {{platform_justification}} |
|
||||
| Language | {{language}} | {{language_version}} | {{language_justification}} |
|
||||
| Build Tool | {{build_tool}} | {{build_version}} | {{build_justification}} |
|
||||
|
||||
## Extension Architecture
|
||||
|
||||
### Manifest Configuration
|
||||
|
||||
{{manifest_config}}
|
||||
|
||||
### Permission Model
|
||||
|
||||
{{permissions_required}}
|
||||
|
||||
### Component Architecture
|
||||
|
||||
{{component_structure}}
|
||||
|
||||
## Communication Architecture
|
||||
|
||||
{{communication_patterns}}
|
||||
|
||||
## State Management
|
||||
|
||||
{{state_management}}
|
||||
|
||||
## User Interface
|
||||
|
||||
{{ui_architecture}}
|
||||
|
||||
## API Integration
|
||||
|
||||
{{api_integration}}
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
{{development_guidelines}}
|
||||
|
||||
## Distribution Strategy
|
||||
|
||||
{{distribution_strategy}}
|
||||
|
||||
## Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
_Architecture optimized for {{target_platform}} extension_
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,225 +0,0 @@
|
||||
# Game Development Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for game project architecture decisions.
|
||||
The LLM should:
|
||||
- FIRST understand the game type from the GDD (RPG, puzzle, shooter, etc.)
|
||||
- Check if engine preference is already mentioned in GDD or by user
|
||||
- Adapt architecture heavily based on game type and complexity
|
||||
- Consider that each game type has VASTLY different needs
|
||||
- Keep beginner-friendly suggestions for those without preferences
|
||||
</critical>
|
||||
|
||||
## Engine Selection Strategy
|
||||
|
||||
**Intelligent Engine Guidance**
|
||||
|
||||
First, check if the user has already indicated an engine preference in the GDD or conversation.
|
||||
|
||||
If no engine specified, ask directly:
|
||||
"Do you have a game engine preference? If you're unsure, I can suggest options based on your [game type] and team experience."
|
||||
|
||||
**For Beginners Without Preference:**
|
||||
Based on game type, suggest the most approachable option:
|
||||
|
||||
- **2D Games**: Godot (free, beginner-friendly) or GameMaker (visual scripting)
|
||||
- **3D Games**: Unity (huge community, learning resources)
|
||||
- **Web Games**: Phaser (JavaScript) or Godot (exports to web)
|
||||
- **Visual Novels**: Ren'Py (purpose-built) or Twine (for text-based)
|
||||
- **Mobile Focus**: Unity or Godot (both export well to mobile)
|
||||
|
||||
Always explain: "I'm suggesting [Engine] because it's beginner-friendly for [game type] and has [specific advantages]. Other viable options include [alternatives]."
|
||||
|
||||
**For Experienced Teams:**
|
||||
Let them state their preference, then ensure architecture aligns with engine capabilities.
|
||||
|
||||
## Game Type Adaptive Architecture
|
||||
|
||||
<critical>
|
||||
The architecture MUST adapt to the game type identified in the GDD.
|
||||
Load the specific game type considerations and merge with general guidance.
|
||||
</critical>
|
||||
|
||||
### Architecture by Game Type Examples
|
||||
|
||||
**Visual Novel / Text-Based:**
|
||||
|
||||
- Focus on narrative data structures, save systems, branching logic
|
||||
- Minimal physics/rendering considerations
|
||||
- Emphasis on dialogue systems and choice tracking
|
||||
- Simple scene management
|
||||
|
||||
**RPG:**
|
||||
|
||||
- Complex data architecture for stats, items, quests
|
||||
- Save system with extensive state
|
||||
- Character progression systems
|
||||
- Inventory and equipment management
|
||||
- World state persistence
|
||||
|
||||
**Multiplayer Shooter:**
|
||||
|
||||
- Network architecture is PRIMARY concern
|
||||
- Client prediction and server reconciliation
|
||||
- Anti-cheat considerations
|
||||
- Matchmaking and lobby systems
|
||||
- Weapon ballistics and hit registration
|
||||
|
||||
**Puzzle Game:**
|
||||
|
||||
- Level data structures and progression
|
||||
- Hint/solution validation systems
|
||||
- Minimal networking (unless multiplayer)
|
||||
- Focus on content pipeline for level creation
|
||||
|
||||
**Roguelike:**
|
||||
|
||||
- Procedural generation architecture
|
||||
- Run persistence vs. meta progression
|
||||
- Seed-based reproducibility
|
||||
- Death and restart systems
|
||||
|
||||
**MMO/MOBA:**
|
||||
|
||||
- Massive multiplayer architecture
|
||||
- Database design for persistence
|
||||
- Server cluster architecture
|
||||
- Real-time synchronization
|
||||
- Economy and balance systems
|
||||
|
||||
## Core Architecture Decisions
|
||||
|
||||
**Determine Based on Game Requirements:**
|
||||
|
||||
### Data Architecture
|
||||
|
||||
Adapt to game type:
|
||||
|
||||
- **Simple Puzzle**: Level data in JSON/XML files
|
||||
- **RPG**: Complex relational data, possibly SQLite
|
||||
- **Multiplayer**: Server authoritative state
|
||||
- **Procedural**: Seed and generation systems
|
||||
|
||||
### Multiplayer Architecture (if applicable)
|
||||
|
||||
Only discuss if game has multiplayer:
|
||||
|
||||
- **Casual Party Game**: P2P might suffice
|
||||
- **Competitive**: Dedicated servers required
|
||||
- **Turn-Based**: Simple request/response
|
||||
- **Real-Time Action**: Complex netcode, interpolation
|
||||
|
||||
Skip entirely for single-player games.
|
||||
|
||||
### Content Pipeline
|
||||
|
||||
Based on team structure and game scope:
|
||||
|
||||
- **Solo Dev**: Simple, file-based
|
||||
- **Small Team**: Version controlled assets, clear naming
|
||||
- **Large Team**: Asset database, automated builds
|
||||
|
||||
### Performance Strategy
|
||||
|
||||
Varies WILDLY by game type:
|
||||
|
||||
- **Mobile Puzzle**: Battery life > raw performance
|
||||
- **VR Game**: Consistent 90+ FPS critical
|
||||
- **Strategy Game**: CPU optimization for AI/simulation
|
||||
- **MMO**: Server scalability primary concern
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
**Adapt to Target Platform from GDD:**
|
||||
|
||||
- **Mobile**: Touch input, performance constraints, monetization
|
||||
- **Console**: Certification requirements, controller input, achievements
|
||||
- **PC**: Wide hardware range, modding support potential
|
||||
- **Web**: Download size, browser limitations, instant play
|
||||
|
||||
## System-Specific Architecture
|
||||
|
||||
### For Games with Heavy Systems
|
||||
|
||||
**Only include systems relevant to the game type:**
|
||||
|
||||
**Physics System** (for physics-based games)
|
||||
|
||||
- 2D vs 3D physics engine
|
||||
- Deterministic requirements
|
||||
- Custom vs. built-in
|
||||
|
||||
**AI System** (for games with NPCs/enemies)
|
||||
|
||||
- Behavior trees vs. state machines
|
||||
- Pathfinding requirements
|
||||
- Group behaviors
|
||||
|
||||
**Procedural Generation** (for roguelikes, infinite runners)
|
||||
|
||||
- Generation algorithms
|
||||
- Seed management
|
||||
- Content validation
|
||||
|
||||
**Inventory System** (for RPGs, survival)
|
||||
|
||||
- Item database design
|
||||
- Stack management
|
||||
- Equipment slots
|
||||
|
||||
**Dialogue System** (for narrative games)
|
||||
|
||||
- Dialogue tree structure
|
||||
- Localization support
|
||||
- Voice acting integration
|
||||
|
||||
**Combat System** (for action games)
|
||||
|
||||
- Damage calculation
|
||||
- Hitbox/hurtbox system
|
||||
- Combo system
|
||||
|
||||
## Development Workflow Optimization
|
||||
|
||||
**Based on Team and Scope:**
|
||||
|
||||
- **Rapid Prototyping**: Focus on quick iteration
|
||||
- **Long Development**: Emphasize maintainability
|
||||
- **Live Service**: Built-in analytics and update systems
|
||||
- **Jam Game**: Absolute minimum viable architecture
|
||||
|
||||
## Adaptive Guidance Framework
|
||||
|
||||
When processing game requirements:
|
||||
|
||||
1. **Identify Game Type** from GDD
|
||||
2. **Determine Complexity Level**:
|
||||
- Simple (jam game, prototype)
|
||||
- Medium (indie release)
|
||||
- Complex (commercial, multiplayer)
|
||||
3. **Check Engine Preference** or guide selection
|
||||
4. **Load Game-Type Specific Needs**
|
||||
5. **Merge with Platform Requirements**
|
||||
6. **Output Focused Architecture**
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Game type drives architecture** - RPG != Puzzle != Shooter
|
||||
2. **Don't over-engineer** - Match complexity to scope
|
||||
3. **Prototype the core loop first** - Architecture serves gameplay
|
||||
4. **Engine choice affects everything** - Align architecture with engine
|
||||
5. **Performance requirements vary** - Mobile puzzle != PC MMO
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure decisions as:
|
||||
|
||||
- **Engine**: [Specific engine and version, with rationale for beginners]
|
||||
- **Core Systems**: [Only systems needed for this game type]
|
||||
- **Architecture Pattern**: [Appropriate for game complexity]
|
||||
- **Platform Optimizations**: [Specific to target platforms]
|
||||
- **Development Pipeline**: [Scaled to team size]
|
||||
|
||||
IMPORTANT: Focus on architecture that enables the specific game type's core mechanics and requirements. Don't include systems the game doesn't need.
|
||||
@@ -1,283 +0,0 @@
|
||||
# Game Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Game Type:** {{game_type}}
|
||||
**Platform(s):** {{target_platforms}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
<critical>
|
||||
This architecture adapts to {{game_type}} requirements.
|
||||
Sections are included/excluded based on game needs.
|
||||
</critical>
|
||||
|
||||
## 1. Core Technology Decisions
|
||||
|
||||
### 1.1 Essential Technology Stack
|
||||
|
||||
| Category | Technology | Version | Justification |
|
||||
| ----------- | --------------- | -------------------- | -------------------------- |
|
||||
| Game Engine | {{game_engine}} | {{engine_version}} | {{engine_justification}} |
|
||||
| Language | {{language}} | {{language_version}} | {{language_justification}} |
|
||||
| Platform(s) | {{platforms}} | - | {{platform_justification}} |
|
||||
|
||||
### 1.2 Game-Specific Technologies
|
||||
|
||||
<intent>
|
||||
Only include rows relevant to this game type:
|
||||
- Physics: Only for physics-based games
|
||||
- Networking: Only for multiplayer games
|
||||
- AI: Only for games with NPCs/enemies
|
||||
- Procedural: Only for roguelikes/procedural games
|
||||
</intent>
|
||||
|
||||
{{game_specific_tech_table}}
|
||||
|
||||
## 2. Architecture Pattern
|
||||
|
||||
### 2.1 High-Level Architecture
|
||||
|
||||
{{architecture_pattern}}
|
||||
|
||||
**Pattern Justification for {{game_type}}:**
|
||||
{{pattern_justification}}
|
||||
|
||||
### 2.2 Code Organization Strategy
|
||||
|
||||
{{code_organization}}
|
||||
|
||||
## 3. Core Game Systems
|
||||
|
||||
<intent>
|
||||
This section should be COMPLETELY different based on game type:
|
||||
- Visual Novel: Dialogue system, save states, branching
|
||||
- RPG: Stats, inventory, quests, progression
|
||||
- Puzzle: Level data, hint system, solution validation
|
||||
- Shooter: Weapons, damage, physics
|
||||
- Racing: Vehicle physics, track system, lap timing
|
||||
- Strategy: Unit management, resource system, AI
|
||||
</intent>
|
||||
|
||||
### 3.1 Core Game Loop
|
||||
|
||||
{{core_game_loop}}
|
||||
|
||||
### 3.2 Primary Game Systems
|
||||
|
||||
{{#for_game_type}}
|
||||
Include ONLY systems this game needs
|
||||
{{/for_game_type}}
|
||||
|
||||
{{primary_game_systems}}
|
||||
|
||||
## 4. Data Architecture
|
||||
|
||||
### 4.1 Data Management Strategy
|
||||
|
||||
<intent>
|
||||
Adapt to game data needs:
|
||||
- Simple puzzle: JSON level files
|
||||
- RPG: Complex relational data
|
||||
- Multiplayer: Server-authoritative state
|
||||
- Roguelike: Seed-based generation
|
||||
</intent>
|
||||
|
||||
{{data_management}}
|
||||
|
||||
### 4.2 Save System
|
||||
|
||||
{{save_system}}
|
||||
|
||||
### 4.3 Content Pipeline
|
||||
|
||||
{{content_pipeline}}
|
||||
|
||||
## 5. Scene/Level Architecture
|
||||
|
||||
<intent>
|
||||
Structure varies by game type:
|
||||
- Linear: Sequential level loading
|
||||
- Open World: Streaming and chunks
|
||||
- Stage-based: Level selection and unlocking
|
||||
- Procedural: Generation pipeline
|
||||
</intent>
|
||||
|
||||
{{scene_architecture}}
|
||||
|
||||
## 6. Gameplay Implementation
|
||||
|
||||
<intent>
|
||||
ONLY include subsections relevant to the game.
|
||||
A racing game doesn't need an inventory system.
|
||||
A puzzle game doesn't need combat mechanics.
|
||||
</intent>
|
||||
|
||||
{{gameplay_systems}}
|
||||
|
||||
## 7. Presentation Layer
|
||||
|
||||
<intent>
|
||||
Adapt to visual style:
|
||||
- 3D: Rendering pipeline, lighting, LOD
|
||||
- 2D: Sprite management, layers
|
||||
- Text: Minimal visual architecture
|
||||
- Hybrid: Both 2D and 3D considerations
|
||||
</intent>
|
||||
|
||||
### 7.1 Visual Architecture
|
||||
|
||||
{{visual_architecture}}
|
||||
|
||||
### 7.2 Audio Architecture
|
||||
|
||||
{{audio_architecture}}
|
||||
|
||||
### 7.3 UI/UX Architecture
|
||||
|
||||
{{ui_architecture}}
|
||||
|
||||
## 8. Input and Controls
|
||||
|
||||
{{input_controls}}
|
||||
|
||||
{{#if_multiplayer}}
|
||||
|
||||
## 9. Multiplayer Architecture
|
||||
|
||||
<critical>
|
||||
Only for games with multiplayer features
|
||||
</critical>
|
||||
|
||||
### 9.1 Network Architecture
|
||||
|
||||
{{network_architecture}}
|
||||
|
||||
### 9.2 State Synchronization
|
||||
|
||||
{{state_synchronization}}
|
||||
|
||||
### 9.3 Matchmaking and Lobbies
|
||||
|
||||
{{matchmaking}}
|
||||
|
||||
### 9.4 Anti-Cheat Strategy
|
||||
|
||||
{{anticheat}}
|
||||
{{/if_multiplayer}}
|
||||
|
||||
## 10. Platform Optimizations
|
||||
|
||||
<intent>
|
||||
Platform-specific considerations:
|
||||
- Mobile: Touch controls, battery, performance
|
||||
- Console: Achievements, controllers, certification
|
||||
- PC: Wide hardware range, settings
|
||||
- Web: Download size, browser compatibility
|
||||
</intent>
|
||||
|
||||
{{platform_optimizations}}
|
||||
|
||||
## 11. Performance Strategy
|
||||
|
||||
### 11.1 Performance Targets
|
||||
|
||||
{{performance_targets}}
|
||||
|
||||
### 11.2 Optimization Approach
|
||||
|
||||
{{optimization_approach}}
|
||||
|
||||
## 12. Asset Pipeline
|
||||
|
||||
### 12.1 Asset Workflow
|
||||
|
||||
{{asset_workflow}}
|
||||
|
||||
### 12.2 Asset Budget
|
||||
|
||||
<intent>
|
||||
Adapt to platform and game type:
|
||||
- Mobile: Strict size limits
|
||||
- Web: Download optimization
|
||||
- Console: Memory constraints
|
||||
- PC: Balance quality vs. performance
|
||||
</intent>
|
||||
|
||||
{{asset_budget}}
|
||||
|
||||
## 13. Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
**Key Directories:**
|
||||
{{key_directories}}
|
||||
|
||||
## 14. Development Guidelines
|
||||
|
||||
### 14.1 Coding Standards
|
||||
|
||||
{{coding_standards}}
|
||||
|
||||
### 14.2 Engine-Specific Best Practices
|
||||
|
||||
{{engine_best_practices}}
|
||||
|
||||
## 15. Build and Deployment
|
||||
|
||||
### 15.1 Build Configuration
|
||||
|
||||
{{build_configuration}}
|
||||
|
||||
### 15.2 Distribution Strategy
|
||||
|
||||
{{distribution_strategy}}
|
||||
|
||||
## 16. Testing Strategy
|
||||
|
||||
<intent>
|
||||
Testing needs vary by game:
|
||||
- Multiplayer: Network testing, load testing
|
||||
- Procedural: Seed testing, generation validation
|
||||
- Physics: Determinism testing
|
||||
- Narrative: Story branch testing
|
||||
</intent>
|
||||
|
||||
{{testing_strategy}}
|
||||
|
||||
## 17. Key Architecture Decisions
|
||||
|
||||
### Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
{{risk_mitigation}}
|
||||
|
||||
{{#if_complex_project}}
|
||||
|
||||
## 18. Specialist Considerations
|
||||
|
||||
<intent>
|
||||
Only for complex projects needing specialist input
|
||||
</intent>
|
||||
|
||||
{{specialist_notes}}
|
||||
{{/if_complex_project}}
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
{{implementation_roadmap}}
|
||||
|
||||
---
|
||||
|
||||
_Architecture optimized for {{game_type}} game on {{platforms}}_
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,198 +0,0 @@
|
||||
# Infrastructure/DevOps Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for infrastructure and DevOps architecture decisions.
|
||||
The LLM should:
|
||||
- Understand scale, reliability, and compliance requirements
|
||||
- Guide cloud vs. on-premise vs. hybrid decisions
|
||||
- Focus on automation and infrastructure as code
|
||||
- Consider team size and DevOps maturity
|
||||
- Balance complexity with operational overhead
|
||||
</critical>
|
||||
|
||||
## Cloud Strategy
|
||||
|
||||
**Platform Selection**
|
||||
Based on requirements and constraints:
|
||||
|
||||
- **Public Cloud**: AWS, GCP, Azure for scalability
|
||||
- **Private Cloud**: OpenStack, VMware for control
|
||||
- **Hybrid**: Mix of public and on-premise
|
||||
- **Multi-cloud**: Avoid vendor lock-in
|
||||
- **On-premise**: Regulatory or latency requirements
|
||||
|
||||
Consider existing contracts, team expertise, and geographic needs.
|
||||
|
||||
## Infrastructure as Code
|
||||
|
||||
**IaC Approach**
|
||||
Based on team and complexity:
|
||||
|
||||
- **Terraform**: Cloud-agnostic, declarative
|
||||
- **CloudFormation/ARM/GCP Deployment Manager**: Cloud-native
|
||||
- **Pulumi/CDK**: Programmatic infrastructure
|
||||
- **Ansible/Chef/Puppet**: Configuration management
|
||||
- **GitOps**: Flux, ArgoCD for Kubernetes
|
||||
|
||||
Start with declarative approaches unless programmatic benefits are clear.
|
||||
|
||||
## Container Strategy
|
||||
|
||||
**Containerization Approach**
|
||||
|
||||
- **Docker**: Standard for containerization
|
||||
- **Kubernetes**: For complex orchestration needs
|
||||
- **ECS/Cloud Run**: Managed container services
|
||||
- **Docker Compose/Swarm**: Simple orchestration
|
||||
- **Serverless**: Skip containers entirely
|
||||
|
||||
Don't use Kubernetes for simple applications - complexity has a cost.
|
||||
|
||||
## CI/CD Architecture
|
||||
|
||||
**Pipeline Design**
|
||||
|
||||
- Source control strategy (GitFlow, GitHub Flow, trunk-based)
|
||||
- Build automation and artifact management
|
||||
- Testing stages (unit, integration, e2e)
|
||||
- Deployment strategies (blue-green, canary, rolling)
|
||||
- Environment promotion process
|
||||
|
||||
Match complexity to release frequency and risk tolerance.
|
||||
|
||||
## Monitoring and Observability
|
||||
|
||||
**Observability Stack**
|
||||
Based on scale and requirements:
|
||||
|
||||
- **Metrics**: Prometheus, CloudWatch, Datadog
|
||||
- **Logging**: ELK, Loki, CloudWatch Logs
|
||||
- **Tracing**: Jaeger, X-Ray, Datadog APM
|
||||
- **Synthetic Monitoring**: Pingdom, New Relic
|
||||
- **Incident Management**: PagerDuty, Opsgenie
|
||||
|
||||
Build observability appropriate to SLA requirements.
|
||||
|
||||
## Security Architecture
|
||||
|
||||
**Security Layers**
|
||||
|
||||
- Network security (VPC, security groups, NACLs)
|
||||
- Identity and access management
|
||||
- Secrets management (Vault, AWS Secrets Manager)
|
||||
- Vulnerability scanning
|
||||
- Compliance automation
|
||||
|
||||
Security must be automated and auditable.
|
||||
|
||||
## Backup and Disaster Recovery
|
||||
|
||||
**Resilience Strategy**
|
||||
|
||||
- Backup frequency and retention
|
||||
- RTO/RPO requirements
|
||||
- Multi-region/multi-AZ design
|
||||
- Disaster recovery testing
|
||||
- Data replication strategy
|
||||
|
||||
Design for your actual recovery requirements, not theoretical disasters.
|
||||
|
||||
## Network Architecture
|
||||
|
||||
**Network Design**
|
||||
|
||||
- VPC/network topology
|
||||
- Load balancing strategy
|
||||
- CDN implementation
|
||||
- Service mesh (if microservices)
|
||||
- Zero trust networking
|
||||
|
||||
Keep networking as simple as possible while meeting requirements.
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
**Cost Management**
|
||||
|
||||
- Resource right-sizing
|
||||
- Reserved instances/savings plans
|
||||
- Spot instances for appropriate workloads
|
||||
- Auto-scaling policies
|
||||
- Cost monitoring and alerts
|
||||
|
||||
Build cost awareness into the architecture.
|
||||
|
||||
## Database Operations
|
||||
|
||||
**Data Layer Management**
|
||||
|
||||
- Managed vs. self-hosted databases
|
||||
- Backup and restore procedures
|
||||
- Read replica configuration
|
||||
- Connection pooling
|
||||
- Performance monitoring
|
||||
|
||||
## Service Mesh and API Gateway
|
||||
|
||||
**API Management** (if applicable)
|
||||
|
||||
- API Gateway for external APIs
|
||||
- Service mesh for internal communication
|
||||
- Rate limiting and throttling
|
||||
- Authentication and authorization
|
||||
- API versioning strategy
|
||||
|
||||
## Development Environments
|
||||
|
||||
**Environment Strategy**
|
||||
|
||||
- Local development setup
|
||||
- Development/staging/production parity
|
||||
- Environment provisioning automation
|
||||
- Data anonymization for non-production
|
||||
|
||||
## Compliance and Governance
|
||||
|
||||
**Regulatory Requirements**
|
||||
|
||||
- Compliance frameworks (SOC 2, HIPAA, PCI DSS)
|
||||
- Audit logging and retention
|
||||
- Change management process
|
||||
- Access control and segregation of duties
|
||||
|
||||
Build compliance in, don't bolt it on.
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Startup MVP:**
|
||||
Focus on managed services, simple CI/CD, and basic monitoring.
|
||||
|
||||
**For Enterprise Migration:**
|
||||
Emphasize hybrid cloud, phased migration, and compliance requirements.
|
||||
|
||||
**For High-Traffic Service:**
|
||||
Focus on auto-scaling, CDN, caching layers, and performance monitoring.
|
||||
|
||||
**For Regulated Industry:**
|
||||
Emphasize compliance automation, audit trails, and data residency.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Automate everything** - Manual processes don't scale
|
||||
2. **Design for failure** - Everything fails eventually
|
||||
3. **Secure by default** - Security is not optional
|
||||
4. **Monitor proactively** - Don't wait for users to report issues
|
||||
5. **Document as code** - Infrastructure documentation gets stale
|
||||
|
||||
## Output Format
|
||||
|
||||
Document as:
|
||||
|
||||
- **Platform**: [Cloud/on-premise choice]
|
||||
- **IaC Tool**: [Primary infrastructure tool]
|
||||
- **Container/Orchestration**: [If applicable]
|
||||
- **CI/CD**: [Pipeline tools and strategy]
|
||||
- **Monitoring**: [Observability stack]
|
||||
|
||||
Focus on automation and operational excellence.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,185 +0,0 @@
|
||||
# Library/SDK Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for library/SDK architecture decisions.
|
||||
The LLM should:
|
||||
- Understand the library's purpose and target developers
|
||||
- Consider API design and developer experience heavily
|
||||
- Focus on versioning, compatibility, and distribution
|
||||
- Balance flexibility with ease of use
|
||||
- Document decisions that affect consumers
|
||||
</critical>
|
||||
|
||||
## Language and Ecosystem
|
||||
|
||||
**Choose Based on Target Users**
|
||||
|
||||
- Consider what language your users are already using
|
||||
- Factor in cross-language needs (FFI, bindings, REST wrapper)
|
||||
- Think about ecosystem conventions and expectations
|
||||
- Performance vs. ease of integration trade-offs
|
||||
|
||||
Don't create a Rust library for JavaScript developers unless performance is critical.
|
||||
|
||||
## API Design Philosophy
|
||||
|
||||
**Developer Experience First**
|
||||
Based on library complexity:
|
||||
|
||||
- **Simple**: Minimal API surface, sensible defaults
|
||||
- **Flexible**: Builder pattern, configuration objects
|
||||
- **Powerful**: Layered API (simple + advanced)
|
||||
- **Framework**: Inversion of control, plugin architecture
|
||||
|
||||
Follow language idioms - Pythonic for Python, functional for FP languages.
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
**Internal Structure**
|
||||
|
||||
- **Facade Pattern**: Hide complexity behind simple interface
|
||||
- **Strategy Pattern**: For pluggable implementations
|
||||
- **Factory Pattern**: For object creation flexibility
|
||||
- **Dependency Injection**: For testability and flexibility
|
||||
|
||||
Don't over-engineer simple utility libraries.
|
||||
|
||||
## Versioning Strategy
|
||||
|
||||
**Semantic Versioning and Compatibility**
|
||||
|
||||
- Breaking change policy
|
||||
- Deprecation strategy
|
||||
- Migration path planning
|
||||
- Backward compatibility approach
|
||||
|
||||
Consider the maintenance burden of supporting multiple versions.
|
||||
|
||||
## Distribution and Packaging
|
||||
|
||||
**Package Management**
|
||||
|
||||
- **NPM**: For JavaScript/TypeScript
|
||||
- **PyPI**: For Python
|
||||
- **Maven/Gradle**: For Java/Kotlin
|
||||
- **NuGet**: For .NET
|
||||
- **Cargo**: For Rust
|
||||
- Multiple registries for cross-language
|
||||
|
||||
Include CDN distribution for web libraries.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Library Testing Approach**
|
||||
|
||||
- Unit tests for all public APIs
|
||||
- Integration tests with common use cases
|
||||
- Property-based testing for complex logic
|
||||
- Example projects as tests
|
||||
- Cross-version compatibility tests
|
||||
|
||||
## Documentation Strategy
|
||||
|
||||
**Developer Documentation**
|
||||
|
||||
- API reference (generated from code)
|
||||
- Getting started guide
|
||||
- Common use cases and examples
|
||||
- Migration guides for major versions
|
||||
- Troubleshooting section
|
||||
|
||||
Good documentation is critical for library adoption.
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Developer-Friendly Errors**
|
||||
|
||||
- Clear error messages with context
|
||||
- Error codes for programmatic handling
|
||||
- Stack traces that point to user code
|
||||
- Validation with helpful messages
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
**Library Performance**
|
||||
|
||||
- Lazy loading where appropriate
|
||||
- Tree-shaking support for web
|
||||
- Minimal dependencies
|
||||
- Memory efficiency
|
||||
- Benchmark suite for performance regression
|
||||
|
||||
## Type Safety
|
||||
|
||||
**Type Definitions**
|
||||
|
||||
- TypeScript definitions for JavaScript libraries
|
||||
- Generic types where appropriate
|
||||
- Type inference optimization
|
||||
- Runtime type checking options
|
||||
|
||||
## Dependency Management
|
||||
|
||||
**External Dependencies**
|
||||
|
||||
- Minimize external dependencies
|
||||
- Pin vs. range versioning
|
||||
- Security audit process
|
||||
- License compatibility
|
||||
|
||||
Zero dependencies is ideal for utility libraries.
|
||||
|
||||
## Extension Points
|
||||
|
||||
**Extensibility Design** (if needed)
|
||||
|
||||
- Plugin architecture
|
||||
- Middleware pattern
|
||||
- Hook system
|
||||
- Custom implementations
|
||||
|
||||
Balance flexibility with complexity.
|
||||
|
||||
## Platform Support
|
||||
|
||||
**Cross-Platform Considerations**
|
||||
|
||||
- Browser vs. Node.js for JavaScript
|
||||
- OS-specific functionality
|
||||
- Mobile platform support
|
||||
- WebAssembly compilation
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a UI Component Library:**
|
||||
Focus on theming, accessibility, tree-shaking, and framework integration.
|
||||
|
||||
**For a Data Processing Library:**
|
||||
Emphasize streaming APIs, memory efficiency, and format support.
|
||||
|
||||
**For an API Client SDK:**
|
||||
Focus on authentication, retry logic, rate limiting, and code generation.
|
||||
|
||||
**For a Testing Framework:**
|
||||
Emphasize assertion APIs, runner architecture, and reporting.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Make simple things simple** - Common cases should be easy
|
||||
2. **Make complex things possible** - Don't limit advanced users
|
||||
3. **Fail fast and clearly** - Help developers debug quickly
|
||||
4. **Version thoughtfully** - Breaking changes hurt adoption
|
||||
5. **Document by example** - Show real-world usage
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure as:
|
||||
|
||||
- **Language**: [Primary language and version]
|
||||
- **API Style**: [Design pattern and approach]
|
||||
- **Distribution**: [Package registries and methods]
|
||||
- **Versioning**: [Strategy and compatibility policy]
|
||||
|
||||
Focus on decisions that affect library consumers.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,181 +0,0 @@
|
||||
# Mobile Application Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for mobile app architecture decisions.
|
||||
The LLM should:
|
||||
- Understand platform requirements from the PRD (iOS, Android, or both)
|
||||
- Guide framework choice based on team expertise and project needs
|
||||
- Focus on mobile-specific concerns (offline, performance, battery)
|
||||
- Adapt complexity to project scale and team size
|
||||
- Keep decisions concrete and implementation-focused
|
||||
</critical>
|
||||
|
||||
## Platform Strategy
|
||||
|
||||
**Determine the Right Approach**
|
||||
Analyze requirements to recommend:
|
||||
|
||||
- **Native** (Swift/Kotlin): When platform-specific features and performance are critical
|
||||
- **Cross-platform** (React Native/Flutter): For faster development across platforms
|
||||
- **Hybrid** (Ionic/Capacitor): When web expertise exists and native features are minimal
|
||||
- **PWA**: For simple apps with basic device access needs
|
||||
|
||||
Consider team expertise heavily - don't suggest Flutter to an iOS team unless there's strong justification.
|
||||
|
||||
## Framework and Technology Selection
|
||||
|
||||
**Match Framework to Project Needs**
|
||||
Based on the requirements and team:
|
||||
|
||||
- **React Native**: JavaScript teams, code sharing with web, large ecosystem
|
||||
- **Flutter**: Consistent UI across platforms, high performance animations
|
||||
- **Native**: Platform-specific UX, maximum performance, full API access
|
||||
- **.NET MAUI**: C# teams, enterprise environments
|
||||
|
||||
For beginners: Recommend based on existing web experience.
|
||||
For experts: Focus on specific trade-offs relevant to their use case.
|
||||
|
||||
## Application Architecture
|
||||
|
||||
**Architectural Pattern**
|
||||
Guide toward appropriate patterns:
|
||||
|
||||
- **MVVM/MVP**: For testability and separation of concerns
|
||||
- **Redux/MobX**: For complex state management
|
||||
- **Clean Architecture**: For larger teams and long-term maintenance
|
||||
|
||||
Don't over-architect simple apps - a basic MVC might suffice for simple utilities.
|
||||
|
||||
## Data Management
|
||||
|
||||
**Local Storage Strategy**
|
||||
Based on data requirements:
|
||||
|
||||
- **SQLite**: Structured data, complex queries, offline-first apps
|
||||
- **Realm**: Object database for simpler data models
|
||||
- **AsyncStorage/SharedPreferences**: Simple key-value storage
|
||||
- **Core Data**: iOS-specific with iCloud sync
|
||||
|
||||
**Sync and Offline Strategy**
|
||||
Only if offline capability is required:
|
||||
|
||||
- Conflict resolution approach
|
||||
- Sync triggers and frequency
|
||||
- Data compression and optimization
|
||||
|
||||
## API Communication
|
||||
|
||||
**Network Layer Design**
|
||||
|
||||
- RESTful APIs for simple CRUD operations
|
||||
- GraphQL for complex data requirements
|
||||
- WebSocket for real-time features
|
||||
- Consider bandwidth optimization for mobile networks
|
||||
|
||||
**Security Considerations**
|
||||
|
||||
- Certificate pinning for sensitive apps
|
||||
- Token storage in secure keychain
|
||||
- Biometric authentication integration
|
||||
|
||||
## UI/UX Architecture
|
||||
|
||||
**Design System Approach**
|
||||
|
||||
- Platform-specific (Material Design, Human Interface Guidelines)
|
||||
- Custom design system for brand consistency
|
||||
- Component library selection
|
||||
|
||||
**Navigation Pattern**
|
||||
Based on app complexity:
|
||||
|
||||
- Tab-based for simple apps with clear sections
|
||||
- Drawer navigation for many features
|
||||
- Stack navigation for linear flows
|
||||
- Hybrid for complex apps
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
**Mobile-Specific Performance**
|
||||
Focus on what matters for mobile:
|
||||
|
||||
- App size (consider app thinning, dynamic delivery)
|
||||
- Startup time optimization
|
||||
- Memory management
|
||||
- Battery efficiency
|
||||
- Network optimization
|
||||
|
||||
Only dive deep into performance if the PRD indicates performance-critical requirements.
|
||||
|
||||
## Native Features Integration
|
||||
|
||||
**Device Capabilities**
|
||||
Based on PRD requirements, plan for:
|
||||
|
||||
- Camera/Gallery access patterns
|
||||
- Location services and geofencing
|
||||
- Push notifications architecture
|
||||
- Biometric authentication
|
||||
- Payment integration (Apple Pay, Google Pay)
|
||||
|
||||
Don't list all possible features - focus on what's actually needed.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Mobile Testing Approach**
|
||||
|
||||
- Unit testing for business logic
|
||||
- UI testing for critical flows
|
||||
- Device testing matrix (OS versions, screen sizes)
|
||||
- Beta testing distribution (TestFlight, Play Console)
|
||||
|
||||
Scale testing complexity to project risk and team size.
|
||||
|
||||
## Distribution and Updates
|
||||
|
||||
**App Store Strategy**
|
||||
|
||||
- Release cadence and versioning
|
||||
- Update mechanisms (CodePush for React Native, OTA updates)
|
||||
- A/B testing and feature flags
|
||||
- Crash reporting and analytics
|
||||
|
||||
**Compliance and Guidelines**
|
||||
|
||||
- App Store/Play Store guidelines
|
||||
- Privacy requirements (ATT, data collection)
|
||||
- Content ratings and age restrictions
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a Social Media App:**
|
||||
Focus on real-time updates, media handling, offline caching, and push notification strategy.
|
||||
|
||||
**For an Enterprise App:**
|
||||
Emphasize security, MDM integration, SSO, and offline data sync.
|
||||
|
||||
**For a Gaming App:**
|
||||
Focus on performance, graphics framework, monetization, and social features.
|
||||
|
||||
**For a Utility App:**
|
||||
Keep it simple - basic UI, minimal backend, focus on core functionality.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Platform conventions matter** - Don't fight the platform
|
||||
2. **Performance is felt immediately** - Mobile users are sensitive to lag
|
||||
3. **Offline-first when appropriate** - But don't over-engineer
|
||||
4. **Test on real devices** - Simulators hide real issues
|
||||
5. **Plan for app store review** - Build in buffer time
|
||||
|
||||
## Output Format
|
||||
|
||||
Document decisions as:
|
||||
|
||||
- **Technology**: [Specific framework/library with version]
|
||||
- **Justification**: [Why this fits the requirements]
|
||||
- **Platform-specific notes**: [iOS/Android differences if applicable]
|
||||
|
||||
Keep mobile-specific considerations prominent in the architecture document.
|
||||
@@ -1,66 +0,0 @@
|
||||
# {{TITLE}} Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
{{technology_table}}
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
{{architecture_overview}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
{{data_architecture}}
|
||||
|
||||
## 4. Component and Integration Overview
|
||||
|
||||
{{component_overview}}
|
||||
|
||||
## 5. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
## 6. Implementation Guidance
|
||||
|
||||
{{implementation_guidance}}
|
||||
|
||||
## 7. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
## 8. Testing Strategy
|
||||
|
||||
{{testing_strategy}}
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 9. Deployment and Operations
|
||||
|
||||
{{deployment_operations}}
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 10. Security
|
||||
|
||||
{{security}}
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -1,12 +0,0 @@
|
||||
type,name
|
||||
web,Web Application
|
||||
mobile,Mobile Application
|
||||
game,Game Development
|
||||
backend,Backend Service
|
||||
data,Data Pipeline
|
||||
cli,CLI Tool
|
||||
library,Library/SDK
|
||||
desktop,Desktop Application
|
||||
embedded,Embedded System
|
||||
extension,Browser/Editor Extension
|
||||
infrastructure,Infrastructure
|
||||
|
@@ -1,158 +0,0 @@
|
||||
# Web Project Architecture Instructions
|
||||
|
||||
## Intent-Based Technical Decision Guidance
|
||||
|
||||
<critical>
|
||||
This is a STARTING POINT for web project architecture decisions.
|
||||
The LLM should:
|
||||
- Understand the project requirements deeply before making suggestions
|
||||
- Adapt questions based on user skill level
|
||||
- Skip irrelevant areas based on project scope
|
||||
- Add project-specific decisions not covered here
|
||||
- Make intelligent recommendations users can correct
|
||||
</critical>
|
||||
|
||||
## Frontend Architecture
|
||||
|
||||
**Framework Selection**
|
||||
Guide the user to choose a frontend framework based on their project needs. Consider factors like:
|
||||
|
||||
- Server-side rendering requirements (SEO, initial load performance)
|
||||
- Team expertise and learning curve
|
||||
- Project complexity and timeline
|
||||
- Community support and ecosystem maturity
|
||||
|
||||
For beginners: Suggest mainstream options like Next.js or plain React based on their needs.
|
||||
For experts: Discuss trade-offs between frameworks briefly, let them specify preferences.
|
||||
|
||||
**Styling Strategy**
|
||||
Determine the CSS approach that aligns with their team and project:
|
||||
|
||||
- Consider maintainability, performance, and developer experience
|
||||
- Factor in design system requirements and component reusability
|
||||
- Think about build complexity and tooling
|
||||
|
||||
Adapt based on skill level - beginners may benefit from utility-first CSS, while teams with strong CSS expertise might prefer CSS Modules or styled-components.
|
||||
|
||||
**State Management**
|
||||
Only explore if the project has complex client-side state requirements:
|
||||
|
||||
- For simple apps, Context API or server state might suffice
|
||||
- For complex apps, discuss lightweight vs. comprehensive solutions
|
||||
- Consider data flow patterns and debugging needs
|
||||
|
||||
## Backend Strategy
|
||||
|
||||
**Backend Architecture**
|
||||
Intelligently determine backend needs:
|
||||
|
||||
- If it's a static site, skip backend entirely
|
||||
- For full-stack apps, consider integrated vs. separate backend
|
||||
- Factor in team structure (full-stack vs. specialized teams)
|
||||
- Consider deployment and operational complexity
|
||||
|
||||
Make smart defaults based on frontend choice (e.g., Next.js API routes for Next.js apps).
|
||||
|
||||
**API Design**
|
||||
Based on client needs and team expertise:
|
||||
|
||||
- REST for simplicity and wide compatibility
|
||||
- GraphQL for complex data requirements with multiple clients
|
||||
- tRPC for type-safe full-stack TypeScript projects
|
||||
- Consider hybrid approaches when appropriate
|
||||
|
||||
## Data Layer
|
||||
|
||||
**Database Selection**
|
||||
Guide based on data characteristics and requirements:
|
||||
|
||||
- Relational for structured data with relationships
|
||||
- Document stores for flexible schemas
|
||||
- Consider managed services vs. self-hosted based on team capacity
|
||||
- Factor in existing infrastructure and expertise
|
||||
|
||||
For beginners: Suggest managed solutions like Supabase or Firebase.
|
||||
For experts: Discuss specific database trade-offs if relevant.
|
||||
|
||||
**Data Access Patterns**
|
||||
Determine ORM/query builder needs based on:
|
||||
|
||||
- Type safety requirements
|
||||
- Team SQL expertise
|
||||
- Performance requirements
|
||||
- Migration and schema management needs
|
||||
|
||||
## Authentication & Authorization
|
||||
|
||||
**Auth Strategy**
|
||||
Assess security requirements and implementation complexity:
|
||||
|
||||
- For MVPs: Suggest managed auth services
|
||||
- For enterprise: Discuss compliance and customization needs
|
||||
- Consider user experience requirements (SSO, social login, etc.)
|
||||
|
||||
Skip detailed auth discussion if it's an internal tool or public site without user accounts.
|
||||
|
||||
## Deployment & Operations
|
||||
|
||||
**Hosting Platform**
|
||||
Make intelligent suggestions based on:
|
||||
|
||||
- Framework choice (Vercel for Next.js, Netlify for static sites)
|
||||
- Budget and scale requirements
|
||||
- DevOps expertise
|
||||
- Geographic distribution needs
|
||||
|
||||
**CI/CD Pipeline**
|
||||
Adapt to team maturity:
|
||||
|
||||
- For small teams: Platform-provided CI/CD
|
||||
- For larger teams: Discuss comprehensive pipelines
|
||||
- Consider existing tooling and workflows
|
||||
|
||||
## Additional Services
|
||||
|
||||
<intent>
|
||||
Only discuss these if relevant to the project requirements:
|
||||
- Email service (for transactional emails)
|
||||
- Payment processing (for e-commerce)
|
||||
- File storage (for user uploads)
|
||||
- Search (for content-heavy sites)
|
||||
- Caching (for performance-critical apps)
|
||||
- Monitoring (based on uptime requirements)
|
||||
|
||||
Don't present these as a checklist - intelligently determine what's needed based on the PRD/requirements.
|
||||
</intent>
|
||||
|
||||
## Adaptive Guidance Examples
|
||||
|
||||
**For a marketing website:**
|
||||
Focus on static site generation, CDN, SEO, and analytics. Skip complex backend discussions.
|
||||
|
||||
**For a SaaS application:**
|
||||
Emphasize authentication, subscription management, multi-tenancy, and monitoring.
|
||||
|
||||
**For an internal tool:**
|
||||
Prioritize rapid development, simple deployment, and integration with existing systems.
|
||||
|
||||
**For an e-commerce platform:**
|
||||
Focus on payment processing, inventory management, performance, and security.
|
||||
|
||||
## Key Principles
|
||||
|
||||
1. **Start with requirements**, not technology choices
|
||||
2. **Adapt to user expertise** - don't overwhelm beginners or bore experts
|
||||
3. **Make intelligent defaults** the user can override
|
||||
4. **Focus on decisions that matter** for this specific project
|
||||
5. **Document definitive choices** with specific versions
|
||||
6. **Keep rationale concise** unless explanation is needed
|
||||
|
||||
## Output Format
|
||||
|
||||
Generate architecture decisions as:
|
||||
|
||||
- **Decision**: [Specific technology with version]
|
||||
- **Brief Rationale**: [One sentence if needed]
|
||||
- **Configuration**: [Key settings if non-standard]
|
||||
|
||||
Avoid lengthy explanations unless the user is a beginner or asks for clarification.
|
||||
@@ -1,277 +0,0 @@
|
||||
# Solution Architecture Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
|
||||
## Executive Summary
|
||||
|
||||
{{executive_summary}}
|
||||
|
||||
## 1. Technology Stack and Decisions
|
||||
|
||||
### 1.1 Technology and Library Decision Table
|
||||
|
||||
| Category | Technology | Version | Justification |
|
||||
| ---------------- | -------------- | ---------------------- | ---------------------------- |
|
||||
| Framework | {{framework}} | {{framework_version}} | {{framework_justification}} |
|
||||
| Language | {{language}} | {{language_version}} | {{language_justification}} |
|
||||
| Database | {{database}} | {{database_version}} | {{database_justification}} |
|
||||
| Authentication | {{auth}} | {{auth_version}} | {{auth_justification}} |
|
||||
| Hosting | {{hosting}} | {{hosting_version}} | {{hosting_justification}} |
|
||||
| State Management | {{state_mgmt}} | {{state_mgmt_version}} | {{state_mgmt_justification}} |
|
||||
| Styling | {{styling}} | {{styling_version}} | {{styling_justification}} |
|
||||
| Testing | {{testing}} | {{testing_version}} | {{testing_justification}} |
|
||||
|
||||
{{additional_tech_stack_rows}}
|
||||
|
||||
## 2. Application Architecture
|
||||
|
||||
### 2.1 Architecture Pattern
|
||||
|
||||
{{architecture_pattern_description}}
|
||||
|
||||
### 2.2 Server-Side Rendering Strategy
|
||||
|
||||
{{ssr_strategy}}
|
||||
|
||||
### 2.3 Page Routing and Navigation
|
||||
|
||||
{{routing_navigation}}
|
||||
|
||||
### 2.4 Data Fetching Approach
|
||||
|
||||
{{data_fetching}}
|
||||
|
||||
## 3. Data Architecture
|
||||
|
||||
### 3.1 Database Schema
|
||||
|
||||
{{database_schema}}
|
||||
|
||||
### 3.2 Data Models and Relationships
|
||||
|
||||
{{data_models}}
|
||||
|
||||
### 3.3 Data Migrations Strategy
|
||||
|
||||
{{migrations_strategy}}
|
||||
|
||||
## 4. API Design
|
||||
|
||||
### 4.1 API Structure
|
||||
|
||||
{{api_structure}}
|
||||
|
||||
### 4.2 API Routes
|
||||
|
||||
{{api_routes}}
|
||||
|
||||
### 4.3 Form Actions and Mutations
|
||||
|
||||
{{form_actions}}
|
||||
|
||||
## 5. Authentication and Authorization
|
||||
|
||||
### 5.1 Auth Strategy
|
||||
|
||||
{{auth_strategy}}
|
||||
|
||||
### 5.2 Session Management
|
||||
|
||||
{{session_management}}
|
||||
|
||||
### 5.3 Protected Routes
|
||||
|
||||
{{protected_routes}}
|
||||
|
||||
### 5.4 Role-Based Access Control
|
||||
|
||||
{{rbac}}
|
||||
|
||||
## 6. State Management
|
||||
|
||||
### 6.1 Server State
|
||||
|
||||
{{server_state}}
|
||||
|
||||
### 6.2 Client State
|
||||
|
||||
{{client_state}}
|
||||
|
||||
### 6.3 Form State
|
||||
|
||||
{{form_state}}
|
||||
|
||||
### 6.4 Caching Strategy
|
||||
|
||||
{{caching_strategy}}
|
||||
|
||||
## 7. UI/UX Architecture
|
||||
|
||||
### 7.1 Component Structure
|
||||
|
||||
{{component_structure}}
|
||||
|
||||
### 7.2 Styling Approach
|
||||
|
||||
{{styling_approach}}
|
||||
|
||||
### 7.3 Responsive Design
|
||||
|
||||
{{responsive_design}}
|
||||
|
||||
### 7.4 Accessibility
|
||||
|
||||
{{accessibility}}
|
||||
|
||||
## 8. Performance Optimization
|
||||
|
||||
### 8.1 SSR Caching
|
||||
|
||||
{{ssr_caching}}
|
||||
|
||||
### 8.2 Static Generation
|
||||
|
||||
{{static_generation}}
|
||||
|
||||
### 8.3 Image Optimization
|
||||
|
||||
{{image_optimization}}
|
||||
|
||||
### 8.4 Code Splitting
|
||||
|
||||
{{code_splitting}}
|
||||
|
||||
## 9. SEO and Meta Tags
|
||||
|
||||
### 9.1 Meta Tag Strategy
|
||||
|
||||
{{meta_tag_strategy}}
|
||||
|
||||
### 9.2 Sitemap
|
||||
|
||||
{{sitemap}}
|
||||
|
||||
### 9.3 Structured Data
|
||||
|
||||
{{structured_data}}
|
||||
|
||||
## 10. Deployment Architecture
|
||||
|
||||
### 10.1 Hosting Platform
|
||||
|
||||
{{hosting_platform}}
|
||||
|
||||
### 10.2 CDN Strategy
|
||||
|
||||
{{cdn_strategy}}
|
||||
|
||||
### 10.3 Edge Functions
|
||||
|
||||
{{edge_functions}}
|
||||
|
||||
### 10.4 Environment Configuration
|
||||
|
||||
{{environment_config}}
|
||||
|
||||
## 11. Component and Integration Overview
|
||||
|
||||
### 11.1 Major Modules
|
||||
|
||||
{{major_modules}}
|
||||
|
||||
### 11.2 Page Structure
|
||||
|
||||
{{page_structure}}
|
||||
|
||||
### 11.3 Shared Components
|
||||
|
||||
{{shared_components}}
|
||||
|
||||
### 11.4 Third-Party Integrations
|
||||
|
||||
{{third_party_integrations}}
|
||||
|
||||
## 12. Architecture Decision Records
|
||||
|
||||
{{architecture_decisions}}
|
||||
|
||||
**Key decisions:**
|
||||
|
||||
- Why this framework? {{framework_decision}}
|
||||
- SSR vs SSG? {{ssr_vs_ssg_decision}}
|
||||
- Database choice? {{database_decision}}
|
||||
- Hosting platform? {{hosting_decision}}
|
||||
|
||||
## 13. Implementation Guidance
|
||||
|
||||
### 13.1 Development Workflow
|
||||
|
||||
{{development_workflow}}
|
||||
|
||||
### 13.2 File Organization
|
||||
|
||||
{{file_organization}}
|
||||
|
||||
### 13.3 Naming Conventions
|
||||
|
||||
{{naming_conventions}}
|
||||
|
||||
### 13.4 Best Practices
|
||||
|
||||
{{best_practices}}
|
||||
|
||||
## 14. Proposed Source Tree
|
||||
|
||||
```
|
||||
{{source_tree}}
|
||||
```
|
||||
|
||||
**Critical folders:**
|
||||
|
||||
- {{critical_folder_1}}: {{critical_folder_1_description}}
|
||||
- {{critical_folder_2}}: {{critical_folder_2_description}}
|
||||
- {{critical_folder_3}}: {{critical_folder_3_description}}
|
||||
|
||||
## 15. Testing Strategy
|
||||
|
||||
### 15.1 Unit Tests
|
||||
|
||||
{{unit_tests}}
|
||||
|
||||
### 15.2 Integration Tests
|
||||
|
||||
{{integration_tests}}
|
||||
|
||||
### 15.3 E2E Tests
|
||||
|
||||
{{e2e_tests}}
|
||||
|
||||
### 15.4 Coverage Goals
|
||||
|
||||
{{coverage_goals}}
|
||||
|
||||
{{testing_specialist_section}}
|
||||
|
||||
## 16. DevOps and CI/CD
|
||||
|
||||
{{devops_section}}
|
||||
|
||||
{{devops_specialist_section}}
|
||||
|
||||
## 17. Security
|
||||
|
||||
{{security_section}}
|
||||
|
||||
{{security_specialist_section}}
|
||||
|
||||
---
|
||||
|
||||
## Specialist Sections
|
||||
|
||||
{{specialist_sections_summary}}
|
||||
|
||||
---
|
||||
|
||||
_Generated using BMad Method Solution Architecture workflow_
|
||||
@@ -0,0 +1,318 @@
|
||||
# Decision Architecture Workflow
|
||||
|
||||
## Overview
|
||||
|
||||
The Decision Architecture workflow is a complete reimagining of how architectural decisions are made in the BMAD Method. Instead of template-driven documentation, this workflow facilitates an intelligent conversation that produces a **decision-focused architecture document** optimized for preventing AI agent conflicts during implementation.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
**The Problem**: When multiple AI agents implement different parts of a system, they make conflicting technical decisions leading to incompatible implementations.
|
||||
|
||||
**The Solution**: A "consistency contract" that documents all critical technical decisions upfront, ensuring every agent follows the same patterns and uses the same technologies.
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Starter Template Intelligence ⭐ NEW
|
||||
|
||||
- Discovers relevant starter templates (create-next-app, create-t3-app, etc.)
|
||||
- Considers UX requirements when selecting templates (animations, accessibility, etc.)
|
||||
- Searches for current CLI options and defaults
|
||||
- Documents decisions made BY the starter template
|
||||
- Makes remaining architectural decisions around the starter foundation
|
||||
- First implementation story becomes "initialize with starter command"
|
||||
|
||||
### 2. Adaptive Facilitation
|
||||
|
||||
- Adjusts conversation style based on user skill level (beginner/intermediate/expert)
|
||||
- Experts get rapid, technical discussions
|
||||
- Beginners receive education and protection from complexity
|
||||
- Everyone produces the same high-quality output
|
||||
|
||||
### 3. Dynamic Version Verification
|
||||
|
||||
- NEVER trusts hardcoded version numbers
|
||||
- Uses WebSearch to find current stable versions
|
||||
- Verifies versions during the conversation
|
||||
- Documents only verified, current versions
|
||||
|
||||
### 4. Intelligent Discovery
|
||||
|
||||
- No rigid project type templates
|
||||
- Analyzes PRD to identify which decisions matter for THIS project
|
||||
- Uses knowledge base of decisions and patterns
|
||||
- Scales to infinite project types
|
||||
|
||||
### 5. Collaborative Decision Making
|
||||
|
||||
- Facilitates discussion for each critical decision
|
||||
- Presents options with trade-offs
|
||||
- Integrates advanced elicitation for innovative approaches
|
||||
- Ensures decisions are coherent and compatible
|
||||
|
||||
### 6. Consistent Output
|
||||
|
||||
- Structured decision collection during conversation
|
||||
- Strict document generation from collected decisions
|
||||
- Validated against hard requirements
|
||||
- Optimized for AI agent consumption
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
```
|
||||
Step 0: Validate workflow and extract project configuration
|
||||
Step 0.5: Validate workflow sequencing
|
||||
Step 1: Load PRD and understand project context
|
||||
Step 2: Discover and evaluate starter templates ⭐ NEW
|
||||
Step 3: Adapt facilitation style and identify remaining decisions
|
||||
Step 4: Facilitate collaborative decision making (with version verification)
|
||||
Step 5: Address cross-cutting concerns
|
||||
Step 6: Define project structure and boundaries
|
||||
Step 7: Design novel architectural patterns (when needed) ⭐ NEW
|
||||
Step 8: Define implementation patterns to prevent agent conflicts
|
||||
Step 9: Validate architectural coherence
|
||||
Step 10: Generate decision architecture document (with initialization commands)
|
||||
Step 11: Validate document completeness
|
||||
Step 12: Final review and update workflow status
|
||||
```
|
||||
|
||||
## Files in This Workflow
|
||||
|
||||
- **workflow.yaml** - Configuration and metadata
|
||||
- **instructions.md** - The adaptive facilitation flow
|
||||
- **decision-catalog.yaml** - Knowledge base of all architectural decisions
|
||||
- **architecture-patterns.yaml** - Common patterns identified from requirements
|
||||
- **pattern-categories.csv** - Pattern principles that teach LLM what needs defining
|
||||
- **checklist.md** - Validation requirements for the output document
|
||||
- **architecture-template.md** - Strict format for the final document
|
||||
|
||||
## How It's Different from Old Solution-Architecture
|
||||
|
||||
| Aspect | Old Workflow | New Workflow |
|
||||
| -------------------- | -------------------------------------------- | ----------------------------------------------- |
|
||||
| **Approach** | Template-driven | Conversation-driven |
|
||||
| **Project Types** | 11 rigid types with 22+ files | Infinite flexibility with intelligent discovery |
|
||||
| **User Interaction** | Output sections with "Continue?" | Collaborative decision facilitation |
|
||||
| **Skill Adaptation** | One-size-fits-all | Adapts to beginner/intermediate/expert |
|
||||
| **Decision Making** | Late in process (Step 5) | Upfront and central focus |
|
||||
| **Output** | Multiple documents including faux tech-specs | Single decision-focused architecture |
|
||||
| **Time** | Confusing and slow | 30-90 minutes depending on skill level |
|
||||
| **Elicitation** | Never used | Integrated at decision points |
|
||||
|
||||
## Expected Inputs
|
||||
|
||||
- **PRD** (Product Requirements Document) with:
|
||||
- Functional Requirements
|
||||
- Non-Functional Requirements
|
||||
- Performance and compliance needs
|
||||
|
||||
- **Epics** file with:
|
||||
- User stories
|
||||
- Acceptance criteria
|
||||
- Dependencies
|
||||
|
||||
- **UX Spec** (Optional but valuable) with:
|
||||
- Interface designs and interaction patterns
|
||||
- Accessibility requirements (WCAG levels)
|
||||
- Animation and transition needs
|
||||
- Platform-specific UI requirements
|
||||
- Performance expectations for interactions
|
||||
|
||||
## Output Document
|
||||
|
||||
A single `architecture.md` file containing:
|
||||
|
||||
- Executive summary (2-3 sentences)
|
||||
- Project initialization command (if using starter template)
|
||||
- Decision summary table with verified versions and epic mapping
|
||||
- Complete project structure
|
||||
- Integration specifications
|
||||
- Consistency rules for AI agents
|
||||
|
||||
## How Novel Pattern Design Works
|
||||
|
||||
Step 7 handles unique or complex patterns that need to be INVENTED:
|
||||
|
||||
1. **Detection**:
|
||||
The workflow analyzes the PRD for concepts that don't have standard solutions:
|
||||
- Novel interaction patterns (e.g., "swipe to match" when Tinder doesn't exist)
|
||||
- Complex multi-epic workflows (e.g., "viral invitation system")
|
||||
- Unique data relationships (e.g., "social graph" before Facebook)
|
||||
- New paradigms (e.g., "ephemeral messages" before Snapchat)
|
||||
|
||||
2. **Design Collaboration**:
|
||||
Instead of just picking technologies, the workflow helps DESIGN the solution:
|
||||
- Identifies the core problem to solve
|
||||
- Explores different approaches with the user
|
||||
- Documents how components interact
|
||||
- Creates sequence diagrams for complex flows
|
||||
- Uses elicitation to find innovative solutions
|
||||
|
||||
3. **Documentation**:
|
||||
Novel patterns become part of the architecture with:
|
||||
- Pattern name and purpose
|
||||
- Component interactions
|
||||
- Data flow diagrams
|
||||
- Which epics/stories are affected
|
||||
- Implementation guidance for agents
|
||||
|
||||
4. **Example**:
|
||||
```
|
||||
PRD: "Users can create 'circles' of friends with overlapping membership"
|
||||
↓
|
||||
Workflow detects: This is a novel social structure pattern
|
||||
↓
|
||||
Designs with user: Circle membership model, permission cascading, UI patterns
|
||||
↓
|
||||
Documents: "Circle Pattern" with component design and data flow
|
||||
↓
|
||||
All agents understand how to implement circle-related features consistently
|
||||
```
|
||||
|
||||
## How Implementation Patterns Work
|
||||
|
||||
Step 8 prevents agent conflicts by defining patterns for consistency:
|
||||
|
||||
1. **The Core Principle**:
|
||||
|
||||
> "Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture"
|
||||
|
||||
The LLM asks: "What could an agent encounter where they'd have to guess?"
|
||||
|
||||
2. **Pattern Categories** (principles, not prescriptions):
|
||||
- **Naming**: How things are named (APIs, database fields, files)
|
||||
- **Structure**: How things are organized (folders, modules, layers)
|
||||
- **Format**: How data is formatted (JSON structures, responses)
|
||||
- **Communication**: How components talk (events, messages, protocols)
|
||||
- **Lifecycle**: How states change (workflows, transitions)
|
||||
- **Location**: Where things go (URLs, paths, storage)
|
||||
- **Consistency**: Cross-cutting concerns (dates, errors, logs)
|
||||
|
||||
3. **LLM Intelligence**:
|
||||
- Uses the principle to identify patterns beyond the 7 categories
|
||||
- Figures out what specific patterns matter for chosen tech
|
||||
- Only asks about patterns that could cause conflicts
|
||||
- Skips obvious patterns that the tech choice determines
|
||||
|
||||
4. **Example**:
|
||||
```
|
||||
Tech chosen: REST API + PostgreSQL + React
|
||||
↓
|
||||
LLM identifies needs:
|
||||
- REST: URL structure, response format, status codes
|
||||
- PostgreSQL: table naming, column naming, FK patterns
|
||||
- React: component structure, state management, test location
|
||||
↓
|
||||
Facilitates each with user
|
||||
↓
|
||||
Documents as Implementation Patterns in architecture
|
||||
```
|
||||
|
||||
## How Starter Templates Work
|
||||
|
||||
When the workflow detects a project type that has a starter template:
|
||||
|
||||
1. **Discovery**: Searches for relevant starter templates based on PRD
|
||||
2. **Investigation**: Looks up current CLI options and defaults
|
||||
3. **Presentation**: Shows user what the starter provides
|
||||
4. **Integration**: Documents starter decisions as "PROVIDED BY STARTER"
|
||||
5. **Continuation**: Only asks about decisions NOT made by starter
|
||||
6. **Documentation**: Includes exact initialization command in architecture
|
||||
|
||||
### Example Flow
|
||||
|
||||
```
|
||||
PRD says: "Next.js web application with authentication"
|
||||
↓
|
||||
Workflow finds: create-next-app and create-t3-app
|
||||
↓
|
||||
User chooses: create-t3-app (includes auth setup)
|
||||
↓
|
||||
Starter provides: Next.js, TypeScript, tRPC, Prisma, NextAuth, Tailwind
|
||||
↓
|
||||
Workflow only asks about: Database choice, deployment target, additional services
|
||||
↓
|
||||
First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# In your BMAD-enabled project
|
||||
workflow architecture
|
||||
```
|
||||
|
||||
The AI agent will:
|
||||
|
||||
1. Load your PRD and epics
|
||||
2. Identify critical decisions needed
|
||||
3. Facilitate discussion on each decision
|
||||
4. Generate a comprehensive architecture document
|
||||
5. Validate completeness
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates
|
||||
2. **Intelligence over Templates** - Use AI understanding rather than rigid structures
|
||||
3. **Decisions over Details** - Focus on what prevents agent conflicts, not implementation minutiae
|
||||
4. **Adaptation over Uniformity** - Meet users where they are while ensuring quality output
|
||||
5. **Collaboration over Output** - The conversation matters as much as the document
|
||||
|
||||
## For Developers
|
||||
|
||||
This workflow assumes:
|
||||
|
||||
- Single developer + AI agents (not teams)
|
||||
- Speed matters (decisions in minutes, not days)
|
||||
- AI agents need clear constraints to prevent conflicts
|
||||
- The architecture document is for agents, not humans
|
||||
|
||||
## Migration from solution-architecture
|
||||
|
||||
Projects using the old `solution-architecture` workflow should:
|
||||
|
||||
1. Complete any in-progress architecture work
|
||||
2. Use `architecture` for new projects
|
||||
3. The old workflow remains available but is deprecated
|
||||
|
||||
## Version
|
||||
|
||||
1.3.2 - UX specification integration and fuzzy file matching
|
||||
|
||||
- Added UX spec as optional input with fuzzy file matching
|
||||
- Updated workflow.yaml with input file references
|
||||
- Starter template selection now considers UX requirements
|
||||
- Added UX alignment validation to checklist
|
||||
- Instructions use variable references for flexible file names
|
||||
|
||||
1.3.1 - Workflow refinement and standardization
|
||||
|
||||
- Added workflow status checking at start (Steps 0 and 0.5)
|
||||
- Added workflow status updating at end (Step 12)
|
||||
- Reorganized step numbering for clarity (removed fractional steps)
|
||||
- Enhanced with intent-based approach throughout
|
||||
- Improved cohesiveness across all workflow components
|
||||
|
||||
1.3.0 - Novel pattern design for unique architectures
|
||||
|
||||
- Added novel pattern design (now Step 7, formerly Step 5.3)
|
||||
- Detects novel concepts in PRD that need architectural invention
|
||||
- Facilitates design collaboration with sequence diagrams
|
||||
- Uses elicitation for innovative approaches
|
||||
- Documents custom patterns for multi-epic consistency
|
||||
|
||||
1.2.0 - Implementation patterns for agent consistency
|
||||
|
||||
- Added implementation patterns (now Step 8, formerly Step 5.5)
|
||||
- Created principle-based pattern-categories.csv (7 principles, not 118 prescriptions)
|
||||
- Core principle: "What could agents decide differently?"
|
||||
- LLM uses principle to identify patterns beyond the categories
|
||||
- Prevents agent conflicts through intelligent pattern discovery
|
||||
|
||||
1.1.0 - Enhanced with starter template discovery and version verification
|
||||
|
||||
- Added intelligent starter template detection and integration (now Step 2)
|
||||
- Added dynamic version verification via web search
|
||||
- Starter decisions are documented as "PROVIDED BY STARTER"
|
||||
- First implementation story uses starter initialization command
|
||||
|
||||
1.0.0 - Initial release replacing solution-architecture workflow
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Solution Architecture Workflow Configuration
|
||||
name: solution-architecture
|
||||
description: "Scale-adaptive solution architecture generation."
|
||||
# Architecture Workflow Configuration
|
||||
name: architecture
|
||||
description: "Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts."
|
||||
author: "BMad"
|
||||
|
||||
# Critical variables
|
||||
@@ -12,84 +12,41 @@ document_output_language: "{config_source}:document_output_language"
|
||||
user_skill_level: "{config_source}:user_skill_level"
|
||||
date: system-generated
|
||||
|
||||
# Inputs expected ( check output_folder or ask user if missing)
|
||||
# Input requirements - We work from PRD, Epics, and optionally UX Spec
|
||||
recommended_inputs:
|
||||
- prd
|
||||
- gdd
|
||||
- spec
|
||||
- architecture
|
||||
- epics
|
||||
- ux_spec
|
||||
- prd: "Product Requirements Document with FRs and NFRs"
|
||||
- epics: "Epic definitions with user stories and acceptance criteria"
|
||||
- ux_spec: "UX specification with interface designs and interaction patterns (optional)"
|
||||
|
||||
# Input requirements
|
||||
inputs:
|
||||
- name: project_workflow_analysis_path
|
||||
description: "Path to bmm-workflow-status.md from plan-project workflow"
|
||||
default: "{output_folder}/bmm-workflow-status.md"
|
||||
required: true
|
||||
- name: project_level
|
||||
description: "Project level (0-4) from analysis file"
|
||||
type: integer
|
||||
required: true
|
||||
|
||||
# Output artifacts
|
||||
outputs:
|
||||
- name: architecture.md
|
||||
description: "Complete solution architecture document"
|
||||
default: "{output_folder}/solution-architecture.md"
|
||||
- name: architecture_decisions.md
|
||||
description: "Architecture Decision Records (ADRs)"
|
||||
default: "{output_folder}/architecture-decisions.md"
|
||||
# Input file references (fuzzy matched from output folder)
|
||||
prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
|
||||
epics_file: "{output_folder}/bmm-epics.md or epics.md or user-stories.md"
|
||||
ux_spec_file: "{output_folder}/ux-spec.md or ux-specification.md or user-experience.md"
|
||||
|
||||
# Module path and component files
|
||||
installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
template: "{installed_path}/architecture-template.md"
|
||||
|
||||
# Reference data files
|
||||
project_types: "{installed_path}/project-types/project-types.csv"
|
||||
# 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"
|
||||
|
||||
# Default output location
|
||||
default_output_file: "{output_folder}/solution-architecture.md"
|
||||
# Output configuration
|
||||
default_output_file: "{output_folder}/architecture.md"
|
||||
|
||||
web_bundle:
|
||||
name: "solution-architecture"
|
||||
description: "Scale-adaptive solution architecture generation with dynamic template sections. Replaces legacy HLA workflow with modern BMAD Core compliance."
|
||||
author: "BMad Builder"
|
||||
instructions: "bmad/bmm/workflows/3-solutioning/architecture/instructions.md"
|
||||
validation: "bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
tech_spec_workflow: "bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
|
||||
# Reference data files
|
||||
project_types: "bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
|
||||
# Workflow dependencies
|
||||
existing_workflows:
|
||||
- workflow_status: "bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
web_bundle_files:
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/checklist.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/ADR-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
|
||||
# Instructions files
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md"
|
||||
# Template files
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/web-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/game-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/data-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/library-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md"
|
||||
- "bmad/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md"
|
||||
# Workflow metadata
|
||||
version: "1.3.2"
|
||||
replaces: "solution-architecture"
|
||||
paradigm: "facilitation-driven"
|
||||
execution_time: "30-90 minutes depending on user skill level"
|
||||
features:
|
||||
- "Starter template discovery and integration"
|
||||
- "Dynamic version verification via web search"
|
||||
- "Adaptive facilitation by skill level"
|
||||
- "Decision-focused architecture"
|
||||
- "Novel pattern design for unique concepts"
|
||||
- "Intelligent pattern identification - LLM figures out what patterns matter"
|
||||
- "Implementation patterns for agent consistency"
|
||||
|
||||
@@ -41,7 +41,7 @@ The workflow adapts its validation based on project level:
|
||||
|
||||
### Level 3-4 Projects
|
||||
|
||||
- Full validation of PRD, solution architecture, and comprehensive stories
|
||||
- Full validation of PRD, architecture document, and comprehensive stories
|
||||
- Deep cross-reference checking across all artifacts
|
||||
- Validates architectural decisions don't introduce scope creep
|
||||
- Checks UX artifacts if applicable
|
||||
@@ -65,7 +65,7 @@ workflow solutioning-gate-check
|
||||
The workflow will automatically search your project's output folder for:
|
||||
|
||||
- Product Requirements Documents (PRD)
|
||||
- Solution Architecture documents
|
||||
- Architecture documents
|
||||
- Technical Specifications
|
||||
- Epic and Story breakdowns
|
||||
- UX artifacts (if applicable)
|
||||
@@ -108,6 +108,13 @@ The workflow uses systematic validation rules adapted to each project level:
|
||||
- **Greenfield project setup coverage**
|
||||
- **Risk identification and mitigation**
|
||||
|
||||
For projects using the new architecture workflow (decision-architecture.md), additional validations include:
|
||||
|
||||
- **Implementation patterns defined for consistency**
|
||||
- **Technology versions verified and current**
|
||||
- **Starter template initialization as first story**
|
||||
- **UX specification alignment (if provided)**
|
||||
|
||||
## Special Features
|
||||
|
||||
### Intelligent Adaptation
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
- [ ] PRD exists and is complete (Level 2-4 projects)
|
||||
- [ ] PRD contains measurable success criteria
|
||||
- [ ] PRD defines clear scope boundaries and exclusions
|
||||
- [ ] Solution Architecture document exists (Level 3-4 projects)
|
||||
- [ ] Architecture document exists (architecture\*.md) (Level 3-4 projects)
|
||||
- [ ] Technical Specification exists with implementation details
|
||||
- [ ] Epic and story breakdown document exists
|
||||
- [ ] All documents are dated and versioned
|
||||
@@ -29,6 +29,9 @@
|
||||
- [ ] Architecture doesn't introduce features beyond PRD scope
|
||||
- [ ] Performance requirements from PRD match architecture capabilities
|
||||
- [ ] Security requirements from PRD are fully addressed in architecture
|
||||
- [ ] If architecture.md: Implementation patterns are defined for consistency
|
||||
- [ ] If architecture.md: All technology choices have verified versions
|
||||
- [ ] If UX spec exists: Architecture supports UX requirements
|
||||
|
||||
### PRD to Stories Coverage (Level 2-4)
|
||||
|
||||
@@ -67,6 +70,7 @@
|
||||
### Greenfield Project Specifics
|
||||
|
||||
- [ ] Initial project setup and configuration stories exist
|
||||
- [ ] If using architecture.md: First story is starter template initialization command
|
||||
- [ ] Development environment setup is documented
|
||||
- [ ] CI/CD pipeline stories are included early in sequence
|
||||
- [ ] Database/storage initialization stories are properly placed
|
||||
|
||||
@@ -32,7 +32,7 @@ After setup, return here to validate implementation readiness.
|
||||
|
||||
- Level 0-1: Tech spec and simple stories only (no PRD, minimal solutioning)
|
||||
- Level 2: PRD, tech spec, epics/stories (no separate architecture doc)
|
||||
- Level 3-4: Full suite - PRD, solution architecture, epics/stories, possible UX artifacts
|
||||
- Level 3-4: Full suite - PRD, architecture document, epics/stories, possible UX artifacts
|
||||
</action>
|
||||
|
||||
<critical>The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels</critical>
|
||||
@@ -54,7 +54,7 @@ After setup, return here to validate implementation readiness.
|
||||
<action>For Level 2-4 projects, locate:
|
||||
|
||||
- Product Requirements Document (PRD)
|
||||
- Solution Architecture document (Level 3-4 only)
|
||||
- Architecture document (architecture.md) (Level 3-4 only)
|
||||
- Technical Specification (Level 2 includes architecture within)
|
||||
- Epic and story breakdowns
|
||||
- UX artifacts if the active path includes UX workflow
|
||||
@@ -119,9 +119,10 @@ After setup, return here to validate implementation readiness.
|
||||
<action>PRD ↔ Architecture Alignment (Level 3-4):
|
||||
|
||||
- Verify every PRD requirement has corresponding architectural support
|
||||
- Check that architecture decisions don't contradict PRD constraints
|
||||
- Identify any architecture additions beyond PRD scope (potential gold-plating)
|
||||
- Ensure non-functional requirements from PRD are addressed in architecture
|
||||
- Check that architectural decisions don't contradict PRD constraints
|
||||
- Identify any architectural additions beyond PRD scope (potential gold-plating)
|
||||
- Ensure non-functional requirements from PRD are addressed in architecture document
|
||||
- If using new architecture workflow: verify implementation patterns are defined
|
||||
</action>
|
||||
|
||||
<action>PRD ↔ Stories Coverage (Level 2-4):
|
||||
|
||||
@@ -56,9 +56,8 @@ validation_rules:
|
||||
level_3_4:
|
||||
required_documents:
|
||||
- prd
|
||||
- solution_architecture
|
||||
- architecture
|
||||
- epics_and_stories
|
||||
- tech_spec # Optional at Level 4
|
||||
|
||||
validations:
|
||||
- name: "PRD Completeness"
|
||||
@@ -75,6 +74,9 @@ validation_rules:
|
||||
- "Integration points defined"
|
||||
- "Security architecture specified"
|
||||
- "Performance considerations addressed"
|
||||
- "If architecture.md: Implementation patterns defined"
|
||||
- "If architecture.md: Technology versions verified and current"
|
||||
- "If architecture.md: Starter template command documented (if applicable)"
|
||||
|
||||
- name: "PRD-Architecture Alignment"
|
||||
checks:
|
||||
@@ -82,6 +84,8 @@ validation_rules:
|
||||
- "NFRs from PRD reflected in architecture"
|
||||
- "Technology choices support requirements"
|
||||
- "Scalability matches expected growth"
|
||||
- "If UX spec exists: Architecture supports UX requirements"
|
||||
- "If UX spec exists: Component library supports interaction patterns"
|
||||
|
||||
- name: "Story Implementation Coverage"
|
||||
checks:
|
||||
@@ -103,6 +107,7 @@ special_contexts:
|
||||
greenfield:
|
||||
additional_checks:
|
||||
- "Project initialization stories exist"
|
||||
- "If using architecture.md: First story is starter template initialization"
|
||||
- "Development environment setup documented"
|
||||
- "CI/CD pipeline stories included"
|
||||
- "Initial data/schema setup planned"
|
||||
|
||||
@@ -27,7 +27,7 @@ default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.m
|
||||
# Expected input documents (varies by project level)
|
||||
recommended_inputs:
|
||||
- prd: "{output_folder}/prd*.md"
|
||||
- architecture: "{output_folder}/solution-architecture*.md"
|
||||
- architecture: "{output_folder}/architecture*.md or {output_folder}/architecture*.md"
|
||||
- tech_spec: "{output_folder}/tech-spec*.md"
|
||||
- epics_stories: "{output_folder}/epic*.md"
|
||||
- ux_artifacts: "{output_folder}/ux*.md"
|
||||
|
||||
@@ -22,7 +22,7 @@ variables:
|
||||
story_dir: "{config_source}:dev_story_location" # Directory where stories are stored
|
||||
epics_file: "{output_folder}/epics.md" # Preferred source for epic/story breakdown
|
||||
prd_file: "{output_folder}/PRD.md" # Fallback for requirements
|
||||
solution-architecture_file: "{output_folder}/solution-architecture.md" # Optional architecture context
|
||||
solution-architecture_file: "{output_folder}/architecture.md" # Optional architecture context
|
||||
tech_spec_file: "" # Will be auto-discovered from docs as tech-spec-epic-{{epic_num}}-*.md
|
||||
tech_spec_search_dir: "{project-root}/docs"
|
||||
tech_spec_glob_template: "tech-spec-epic-{{epic_num}}*.md"
|
||||
@@ -30,7 +30,7 @@ variables:
|
||||
- "{project-root}/docs"
|
||||
- "{output_folder}"
|
||||
arch_docs_file_names: |
|
||||
- solution-architecture.md
|
||||
- architecture.md
|
||||
- infrastructure-architecture.md
|
||||
story_title: "" # Will be elicited if not derivable
|
||||
epic_num: 1
|
||||
|
||||
@@ -25,10 +25,10 @@ workflow tech-spec
|
||||
|
||||
```bash
|
||||
# With specific PRD and architecture
|
||||
workflow tech-spec --input PRD.md --input solution-architecture.md
|
||||
workflow tech-spec --input PRD.md --input architecture.md
|
||||
|
||||
# With comprehensive inputs
|
||||
workflow tech-spec --input PRD.md --input solution-architecture.md --input front-end-spec.md
|
||||
workflow tech-spec --input PRD.md --input architecture.md --input front-end-spec.md
|
||||
```
|
||||
|
||||
### Configuration
|
||||
@@ -36,7 +36,7 @@ variables:
|
||||
- "{project-root}/docs"
|
||||
- "{output_folder}"
|
||||
arch_docs_file_names: |
|
||||
- solution-architecture.md
|
||||
- architecture.md
|
||||
enable_mcp_doc_search: true # Prefer enabled MCP servers for doc/best-practice lookup
|
||||
enable_web_fallback: true # Fallback to web search/read-url if MCP not available
|
||||
update_status_on_result: true # If true, update story Status based on review outcome
|
||||
|
||||
@@ -43,7 +43,7 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
|
||||
│ PHASE 3: SOLUTIONING │
|
||||
│ (Software Levels 3-4 / Complex Games) │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 3-solutioning ──→ solution-architecture.md │
|
||||
│ 3-solutioning ──→ architecture.md │
|
||||
│ ↓ │
|
||||
│ tech-spec (per epic, JIT during implementation) │
|
||||
└────────────────────────────────────────────────────────────┬─┘
|
||||
@@ -202,10 +202,10 @@ Architecture and technical design phase for complex projects.
|
||||
|
||||
### Workflows
|
||||
|
||||
| Workflow | Owner | Purpose | Output | Timing |
|
||||
| ----------------- | --------- | ------------------------------ | ---------------------------------- | ----------------- |
|
||||
| **3-solutioning** | Architect | Create overall architecture | solution-architecture.md with ADRs | Once per project |
|
||||
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT |
|
||||
| Workflow | Owner | Purpose | Output | Timing |
|
||||
| ----------------- | --------- | ------------------------------ | ------------------------- | ----------------- |
|
||||
| **3-solutioning** | Architect | Create overall architecture | architecture.md with ADRs | Once per project |
|
||||
| **tech-spec** | Architect | Create epic-specific tech spec | tech-spec-epic-N.md | One per epic, JIT |
|
||||
|
||||
### Just-In-Time Tech Specs
|
||||
|
||||
@@ -411,8 +411,8 @@ plan-project (Phase 2)
|
||||
- Level 0: tech-spec.md + story-{slug}.md
|
||||
- Level 1: tech-spec.md + epic-stories.md + story-{slug}-N.md files
|
||||
- Level 2: PRD.md + epics.md (then tech-spec.md in Phase 3)
|
||||
- Level 3-4: PRD.md + epics.md (then solution-architecture.md in Phase 3)
|
||||
- **Phase 3**: solution-architecture.md, epic-specific tech specs
|
||||
- Level 3-4: PRD.md + epics.md (then architecture.md in Phase 3)
|
||||
- **Phase 3**: architecture.md, epic-specific tech specs
|
||||
- **Phase 4**: Story files, context XMLs, implemented code
|
||||
|
||||
## Best Practices
|
||||
|
||||
@@ -23,7 +23,7 @@ The TEA agent runs this workflow when:
|
||||
|
||||
**Optional Context Files:**
|
||||
|
||||
- **Architecture docs** (solution-architecture.md, tech-spec.md): Informs framework configuration decisions
|
||||
- **Architecture docs** (architecture.md, tech-spec.md): Informs framework configuration decisions
|
||||
- **Existing tests**: Detects current framework to avoid conflicts
|
||||
|
||||
**Workflow Variables:**
|
||||
|
||||
@@ -39,7 +39,7 @@ Initialize a production-ready test framework architecture (Playwright or Cypress
|
||||
- If found, HALT with message: "Existing test framework detected. Use workflow `upgrade-framework` instead."
|
||||
|
||||
3. **Gather Context**
|
||||
- Look for architecture documents (`solution-architecture.md`, `tech-spec*.md`)
|
||||
- Look for architecture documents (`architecture.md`, `tech-spec*.md`)
|
||||
- Check for API documentation or endpoint lists
|
||||
- Identify authentication requirements
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ Plans comprehensive test coverage strategy with risk assessment, priority classi
|
||||
- Identify all testable requirements
|
||||
|
||||
2. **Load Architecture Context**
|
||||
- Read solution-architecture.md for system design
|
||||
- Read architecture.md for system design
|
||||
- Read tech-spec for implementation details
|
||||
- Identify technical constraints and dependencies
|
||||
- Note integration points and external systems
|
||||
|
||||
@@ -36,7 +36,7 @@ recommended_inputs:
|
||||
- prd: "Product Requirements Document for context"
|
||||
- epics: "Epic documentation (epics.md or specific epic)"
|
||||
- story: "Story markdown with acceptance criteria"
|
||||
- architecture: "Architecture documents (solution-architecture.md, tech-spec)"
|
||||
- architecture: "Architecture documents (architecture.md, tech-spec)"
|
||||
- existing_tests: "Current test coverage for gap analysis"
|
||||
|
||||
tags:
|
||||
|
||||
@@ -1,317 +0,0 @@
|
||||
# Workflow Status Service - Integration Examples
|
||||
|
||||
## How Other Workflows Can Use the Enhanced workflow-status Service
|
||||
|
||||
### Example 1: Simple Validation (product-brief workflow)
|
||||
|
||||
Replace the old Step 0:
|
||||
|
||||
```xml
|
||||
<!-- OLD WAY - 35+ lines of duplicate code -->
|
||||
<step n="0" goal="Check and load workflow status file">
|
||||
<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
|
||||
<action>Find the most recent file...</action>
|
||||
<!-- ... 30+ more lines of checking logic ... -->
|
||||
</step>
|
||||
```
|
||||
|
||||
With the new service call:
|
||||
|
||||
```xml
|
||||
<!-- NEW WAY - Clean and simple -->
|
||||
<step n="0" goal="Validate workflow readiness">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: validate</param>
|
||||
<param>calling_workflow: product-brief</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<output>{{suggestion}}</output>
|
||||
<output>Note: Status tracking is optional. You can continue without it.</output>
|
||||
</check>
|
||||
|
||||
<check if="warning != ''">
|
||||
<output>{{warning}}</output>
|
||||
<ask>Continue anyway? (y/n)</ask>
|
||||
<check if="n">
|
||||
<action>Exit workflow</action>
|
||||
</check>
|
||||
</check>
|
||||
|
||||
<action>Store {{status_file_path}} for later updates if needed</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
### Example 2: Getting Story Data (create-story workflow)
|
||||
|
||||
Replace the complex Step 2.5:
|
||||
|
||||
```xml
|
||||
<!-- OLD WAY - Complex parsing logic -->
|
||||
<step n="2.5" goal="Check status file TODO section for story to draft">
|
||||
<action>Read {output_folder}/bmm-workflow-status.md (if exists)</action>
|
||||
<action>Navigate to "### Implementation Progress (Phase 4 Only)" section</action>
|
||||
<action>Find "#### TODO (Needs Drafting)" section</action>
|
||||
<!-- ... 40+ lines of parsing and extraction ... -->
|
||||
</step>
|
||||
```
|
||||
|
||||
With the new service call:
|
||||
|
||||
```xml
|
||||
<!-- NEW WAY - Let workflow-status handle the complexity -->
|
||||
<step n="2.5" goal="Get next story to draft">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: data</param>
|
||||
<param>data_request: next_story</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<action>Fall back to legacy story discovery</action>
|
||||
</check>
|
||||
|
||||
<check if="todo_story_id exists">
|
||||
<action>Use {{todo_story_id}} as story to draft</action>
|
||||
<action>Use {{todo_story_title}} for validation</action>
|
||||
<action>Create file: {{todo_story_file}}</action>
|
||||
<output>Drafting story {{todo_story_id}}: {{todo_story_title}}</output>
|
||||
</check>
|
||||
</step>
|
||||
```
|
||||
|
||||
### Example 3: Getting Project Configuration (solution-architecture workflow)
|
||||
|
||||
```xml
|
||||
<step n="0" goal="Load project configuration">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: data</param>
|
||||
<param>data_request: project_config</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<ask>No status file. Run standalone or create status first?</ask>
|
||||
</check>
|
||||
|
||||
<check if="status_exists == true">
|
||||
<action>Use {{project_level}} to determine architecture complexity</action>
|
||||
<action>Use {{project_type}} to select appropriate templates</action>
|
||||
<action>Use {{field_type}} to know if brownfield constraints apply</action>
|
||||
</check>
|
||||
</step>
|
||||
```
|
||||
|
||||
### Example 4: Quick Init Check (any workflow)
|
||||
|
||||
```xml
|
||||
<step n="0" goal="Check if status exists">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: init-check</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="status_exists == false">
|
||||
<output>{{suggestion}}</output>
|
||||
<output>Proceeding without status tracking...</output>
|
||||
</check>
|
||||
</step>
|
||||
```
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
1. **DRY Principle**: No more duplicating status check logic across 50+ workflows
|
||||
2. **Centralized Logic**: Bug fixes and improvements happen in one place
|
||||
3. **Backward Compatible**: Old workflows continue to work, can migrate gradually
|
||||
4. **Advisory Not Blocking**: Workflows can proceed even without status file
|
||||
5. **Flexible Data Access**: Get just what you need (next_story, project_config, etc.)
|
||||
6. **Cleaner Workflows**: Focus on core logic, not status management
|
||||
|
||||
## Available Modes
|
||||
|
||||
### `update` Mode ⭐ NEW - Centralized Status Updates
|
||||
|
||||
- **Purpose**: Centralized status file updates - **NO MORE manual template-output hackery!**
|
||||
- **Parameters**: `action` + action-specific params
|
||||
- **Returns**: `success`, action-specific outputs
|
||||
|
||||
#### Available Actions:
|
||||
|
||||
**1. complete_workflow** - Mark workflow done, advance to next in path
|
||||
|
||||
```xml
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: prd</param>
|
||||
<param>populate_stories_from: {output_folder}/bmm-epics.md</param> <!-- optional -->
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>PRD complete! Next: {{next_workflow}} ({{next_agent}} agent)</output>
|
||||
</check>
|
||||
```
|
||||
|
||||
**2. populate_stories** - Load story queue from epics.md
|
||||
|
||||
```xml
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: populate_stories</param>
|
||||
<param>epics_file: {output_folder}/bmm-epics.md</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>Loaded {{total_stories}} stories. First: {{first_story}}</output>
|
||||
</check>
|
||||
```
|
||||
|
||||
**3. start_story** - Move TODO → IN PROGRESS
|
||||
|
||||
```xml
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: start_story</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>Started: {{in_progress_story}}. Next TODO: {{next_todo}}</output>
|
||||
</check>
|
||||
```
|
||||
|
||||
**4. complete_story** - Move IN PROGRESS → DONE, advance queue
|
||||
|
||||
```xml
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_story</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<check if="success == true">
|
||||
<output>Completed: {{completed_story}}. {{stories_remaining}} remaining.</output>
|
||||
<check if="all_complete == true">
|
||||
<output>🎉 All stories complete!</output>
|
||||
</check>
|
||||
</check>
|
||||
```
|
||||
|
||||
**5. set_current_workflow** - Manual override (rarely needed)
|
||||
|
||||
```xml
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: set_current_workflow</param>
|
||||
<param>workflow_name: tech-spec</param>
|
||||
</invoke-workflow>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `validate` Mode
|
||||
|
||||
- **Purpose**: Check if this workflow should run
|
||||
- **Returns**:
|
||||
- `status_exists`: true/false
|
||||
- `should_proceed`: true (always - advisory only)
|
||||
- `warning`: Any sequence warnings
|
||||
- `suggestion`: What to do
|
||||
- `project_level`, `project_type`, `field_type`: For workflow decisions
|
||||
- `status_file_path`: For later updates
|
||||
|
||||
### `data` Mode
|
||||
|
||||
- **Purpose**: Extract specific information
|
||||
- **Parameters**: `data_request` = one of:
|
||||
- `next_story`: Get TODO story details
|
||||
- `project_config`: Get project configuration
|
||||
- `phase_status`: Get phase completion status
|
||||
- `all`: Get everything
|
||||
- **Returns**: Requested fields as template outputs
|
||||
|
||||
### `init-check` Mode
|
||||
|
||||
- **Purpose**: Simple existence check
|
||||
- **Returns**:
|
||||
- `status_exists`: true/false
|
||||
- `suggestion`: Brief message
|
||||
|
||||
### `interactive` Mode (default)
|
||||
|
||||
- **Purpose**: User-facing status check
|
||||
- **Shows**: Current status, options menu
|
||||
- **Returns**: User proceeds with selected action
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
1. Start with high-value workflows that have complex Step 0s
|
||||
2. Test with a few workflows first
|
||||
3. Gradually migrate others as they're updated
|
||||
4. Old workflows continue to work unchanged
|
||||
|
||||
## Before & After: The Power of Update Mode
|
||||
|
||||
### OLD WAY (PRD workflow) - 40+ lines of pollution:
|
||||
|
||||
```xml
|
||||
<step n="10" goal="Update status and complete">
|
||||
<action>Load {{status_file_path}}</action>
|
||||
|
||||
<template-output file="{{status_file_path}}">current_workflow</template-output>
|
||||
<action>Set to: "prd - Complete"</action>
|
||||
|
||||
<template-output file="{{status_file_path}}">phase_2_complete</template-output>
|
||||
<action>Set to: true</action>
|
||||
|
||||
<template-output file="{{status_file_path}}">decisions_log</template-output>
|
||||
<action>Add entry: "- **{{date}}**: Completed PRD workflow..."</action>
|
||||
|
||||
<action>Populate STORIES_SEQUENCE from epics.md story list</action>
|
||||
<action>Count total stories and update story counts</action>
|
||||
|
||||
<action>Save {{status_file_path}}</action>
|
||||
</step>
|
||||
```
|
||||
|
||||
### NEW WAY - 6 clean lines:
|
||||
|
||||
```xml
|
||||
<step n="10" goal="Mark PRD complete">
|
||||
<invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
|
||||
<param>mode: update</param>
|
||||
<param>action: complete_workflow</param>
|
||||
<param>workflow_name: prd</param>
|
||||
<param>populate_stories_from: {output_folder}/bmm-epics.md</param>
|
||||
</invoke-workflow>
|
||||
|
||||
<output>PRD complete! Next: {{next_workflow}}</output>
|
||||
</step>
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- ✅ No manual file manipulation
|
||||
- ✅ No template-output pollution
|
||||
- ✅ Centralized logic handles path navigation
|
||||
- ✅ Story population happens automatically
|
||||
- ✅ Status file stays clean (just key-value pairs)
|
||||
|
||||
---
|
||||
|
||||
## Migration Priority
|
||||
|
||||
**High Priority (Complex Status Updates):**
|
||||
|
||||
1. Phase 2: prd, gdd, tech-spec - populate stories + complete workflow
|
||||
2. Phase 4: story-approved, story-ready - complex queue management
|
||||
|
||||
**Medium Priority (Simple Completions):** 3. Phase 1: product-brief, brainstorm-project, research 4. Phase 3: solution-architecture, tech-spec
|
||||
|
||||
**Low Priority (Minimal/No Updates):** 5. Phase 4: create-story, dev-story - mostly just read status
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
To migrate a workflow:
|
||||
|
||||
1. **Step 0**: Keep `validate` or `data` mode calls (for reading)
|
||||
2. **Final Step**: Replace all `template-output` with single `update` mode call
|
||||
3. **Test**: Verify status file stays clean (no prose pollution)
|
||||
4. **Delete**: Remove 30-100 lines of status manipulation code 🎉
|
||||
@@ -64,10 +64,10 @@ phases:
|
||||
agent: "architect"
|
||||
command: "integration-planning"
|
||||
output: "Integration strategy document"
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
note: "Extension of existing architecture"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
|
||||
@@ -56,10 +56,10 @@ phases:
|
||||
name: "Solutioning"
|
||||
required: true
|
||||
workflows:
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
output: "Architecture for system expansion"
|
||||
note: "Must maintain backward compatibility"
|
||||
- id: "solutioning-gate-check"
|
||||
|
||||
@@ -45,10 +45,10 @@ phases:
|
||||
name: "Solutioning"
|
||||
conditional: "if_level_3_4"
|
||||
workflows:
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
note: "Engine architecture, networking, systems"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
|
||||
@@ -48,10 +48,10 @@ phases:
|
||||
name: "Solutioning"
|
||||
required: true
|
||||
workflows:
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
output: "System-wide architecture document"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
|
||||
@@ -43,10 +43,10 @@ phases:
|
||||
name: "Solutioning"
|
||||
required: true
|
||||
workflows:
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
output: "System-wide architecture document"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
|
||||
@@ -45,10 +45,10 @@ phases:
|
||||
name: "Solutioning"
|
||||
required: true
|
||||
workflows:
|
||||
- id: "solution-architecture"
|
||||
- id: "create-architecture"
|
||||
required: true
|
||||
agent: "architect"
|
||||
command: "solution-architecture"
|
||||
command: "create-architecture"
|
||||
output: "Enterprise architecture documentation"
|
||||
- id: "solutioning-gate-check"
|
||||
required: true
|
||||
|
||||
Reference in New Issue
Block a user