From 2a6eb7161249107cd956360c5bcd2831b4b81763 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 19 Oct 2025 23:28:38 -0500 Subject: [PATCH] massive architecture creation overhaul --- .claude/commands/foo.md | 3 + README.md | 2 +- ...module-config.yaml => install-config.yaml} | 0 docs/technical-decisions-template.md | 4 +- ...l-menu-config.yaml => install-config.yaml} | 0 ...l-menu-config.yaml => install-config.yaml} | 0 ...l-menu-config.yaml => install-config.yaml} | 0 .../assets/technical-decisions.md | 4 +- ...l-menu-config.yaml => install-config.yaml} | 0 src/modules/bmm/agents/architect.agent.yaml | 6 +- .../bmm/agents/game-architect.agent.yaml | 6 +- src/modules/bmm/agents/sm.agent.yaml | 2 +- src/modules/bmm/testarch/README.md | 18 +- .../workflows/1-analysis/research/README.md | 2 +- .../bmm/workflows/2-plan-workflows/README.md | 2 +- .../workflows/2-plan-workflows/gdd/README.md | 2 +- .../2-plan-workflows/gdd/instructions-gdd.md | 6 +- .../2-plan-workflows/ux/instructions-ux.md | 2 +- .../architecture/ADR-template.md | 74 -- .../architecture/architecture-patterns.yaml | 347 +++++++ .../architecture/architecture-template.md | 103 ++ .../3-solutioning/architecture/checklist.md | 261 +++++ .../architecture/decision-catalog.yaml | 701 +++++++++++++ .../architecture/instructions.md | 933 +++++++++++------- .../architecture/pattern-categories.csv | 13 + .../project-types/backend-instructions.md | 162 --- .../project-types/backend-template.md | 66 -- .../project-types/cli-instructions.md | 149 --- .../project-types/cli-template.md | 66 -- .../project-types/data-instructions.md | 193 ---- .../project-types/data-template.md | 66 -- .../project-types/desktop-instructions.md | 182 ---- .../project-types/desktop-template.md | 66 -- .../project-types/embedded-instructions.md | 191 ---- .../project-types/embedded-template.md | 66 -- .../project-types/extension-instructions.md | 193 ---- .../project-types/extension-template.md | 67 -- .../project-types/game-instructions.md | 225 ----- .../project-types/game-template.md | 283 ------ .../infrastructure-instructions.md | 198 ---- .../project-types/infrastructure-template.md | 66 -- .../project-types/library-instructions.md | 185 ---- .../project-types/library-template.md | 66 -- .../project-types/mobile-instructions.md | 181 ---- .../project-types/mobile-template.md | 66 -- .../project-types/project-types.csv | 12 - .../project-types/web-instructions.md | 158 --- .../project-types/web-template.md | 277 ------ .../3-solutioning/architecture/readme.md | 318 ++++++ .../3-solutioning/architecture/workflow.yaml | 105 +- .../solutioning-gate-check/README.md | 11 +- .../solutioning-gate-check/checklist.md | 6 +- .../solutioning-gate-check/instructions.md | 11 +- .../validation-criteria.yaml | 9 +- .../solutioning-gate-check/workflow.yaml | 2 +- .../create-story/workflow.yaml | 4 +- .../epic-tech-context/README.md | 4 +- .../epic-tech-context/checklist.md | 0 .../epic-tech-context/instructions.md | 0 .../epic-tech-context/template.md | 0 .../epic-tech-context/workflow.yaml | 0 .../review-story/workflow.yaml | 2 +- src/modules/bmm/workflows/README.md | 14 +- .../workflows/testarch/framework/README.md | 2 +- .../testarch/framework/instructions.md | 2 +- .../testarch/test-design/instructions.md | 2 +- .../testarch/test-design/workflow.yaml | 2 +- .../workflow-status/INTEGRATION-EXAMPLE.md | 317 ------ .../paths/brownfield-level-3.yaml | 4 +- .../paths/brownfield-level-4.yaml | 4 +- .../workflow-status/paths/game-design.yaml | 4 +- .../paths/greenfield-level-2.yaml | 4 +- .../paths/greenfield-level-3.yaml | 4 +- .../paths/greenfield-level-4.yaml | 4 +- ...l-menu-config.yaml => install-config.yaml} | 0 75 files changed, 2440 insertions(+), 4070 deletions(-) create mode 100644 .claude/commands/foo.md rename bmad/bmb/workflows/create-module/installer-templates/{install-module-config.yaml => install-config.yaml} (100%) rename src/core/_module-installer/{install-menu-config.yaml => install-config.yaml} (100%) rename src/modules/bmb/_module-installer/{install-menu-config.yaml => install-config.yaml} (100%) rename src/modules/bmb/workflows/create-module/installer-templates/{install-menu-config.yaml => install-config.yaml} (100%) rename src/modules/bmm/_module-installer/{install-menu-config.yaml => install-config.yaml} (100%) delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/ADR-template.md create mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml create mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md create mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/checklist.md create mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml create mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/pattern-categories.csv delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md delete mode 100644 src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-template.md rename src/modules/bmm/workflows/{3-solutioning => 4-implementation}/epic-tech-context/README.md (97%) rename src/modules/bmm/workflows/{3-solutioning => 4-implementation}/epic-tech-context/checklist.md (100%) rename src/modules/bmm/workflows/{3-solutioning => 4-implementation}/epic-tech-context/instructions.md (100%) rename src/modules/bmm/workflows/{3-solutioning => 4-implementation}/epic-tech-context/template.md (100%) rename src/modules/bmm/workflows/{3-solutioning => 4-implementation}/epic-tech-context/workflow.yaml (100%) delete mode 100644 src/modules/bmm/workflows/workflow-status/INTEGRATION-EXAMPLE.md rename src/modules/cis/_module-installer/{install-menu-config.yaml => install-config.yaml} (100%) diff --git a/.claude/commands/foo.md b/.claude/commands/foo.md new file mode 100644 index 00000000..bff5cc79 --- /dev/null +++ b/.claude/commands/foo.md @@ -0,0 +1,3 @@ +# foo task + +The user just said foo, respond with bar. diff --git a/README.md b/README.md index a7ccf3b0..167cae0b 100644 --- a/README.md +++ b/README.md @@ -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)_ diff --git a/bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml b/bmad/bmb/workflows/create-module/installer-templates/install-config.yaml similarity index 100% rename from bmad/bmb/workflows/create-module/installer-templates/install-module-config.yaml rename to bmad/bmb/workflows/create-module/installer-templates/install-config.yaml diff --git a/docs/technical-decisions-template.md b/docs/technical-decisions-template.md index 5f813239..ceac48fb 100644 --- a/docs/technical-decisions-template.md +++ b/docs/technical-decisions-template.md @@ -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. diff --git a/src/core/_module-installer/install-menu-config.yaml b/src/core/_module-installer/install-config.yaml similarity index 100% rename from src/core/_module-installer/install-menu-config.yaml rename to src/core/_module-installer/install-config.yaml diff --git a/src/modules/bmb/_module-installer/install-menu-config.yaml b/src/modules/bmb/_module-installer/install-config.yaml similarity index 100% rename from src/modules/bmb/_module-installer/install-menu-config.yaml rename to src/modules/bmb/_module-installer/install-config.yaml diff --git a/src/modules/bmb/workflows/create-module/installer-templates/install-menu-config.yaml b/src/modules/bmb/workflows/create-module/installer-templates/install-config.yaml similarity index 100% rename from src/modules/bmb/workflows/create-module/installer-templates/install-menu-config.yaml rename to src/modules/bmb/workflows/create-module/installer-templates/install-config.yaml diff --git a/src/modules/bmm/_module-installer/assets/technical-decisions.md b/src/modules/bmm/_module-installer/assets/technical-decisions.md index 5f813239..ceac48fb 100644 --- a/src/modules/bmm/_module-installer/assets/technical-decisions.md +++ b/src/modules/bmm/_module-installer/assets/technical-decisions.md @@ -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. diff --git a/src/modules/bmm/_module-installer/install-menu-config.yaml b/src/modules/bmm/_module-installer/install-config.yaml similarity index 100% rename from src/modules/bmm/_module-installer/install-menu-config.yaml rename to src/modules/bmm/_module-installer/install-config.yaml diff --git a/src/modules/bmm/agents/architect.agent.yaml b/src/modules/bmm/agents/architect.agent.yaml index 3413b888..02f2e4e0 100644 --- a/src/modules/bmm/agents/architect.agent.yaml +++ b/src/modules/bmm/agents/architect.agent.yaml @@ -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) diff --git a/src/modules/bmm/agents/game-architect.agent.yaml b/src/modules/bmm/agents/game-architect.agent.yaml index 7cf807ae..7f2c741f 100644 --- a/src/modules/bmm/agents/game-architect.agent.yaml +++ b/src/modules/bmm/agents/game-architect.agent.yaml @@ -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) diff --git a/src/modules/bmm/agents/sm.agent.yaml b/src/modules/bmm/agents/sm.agent.yaml index b4cb6246..2fde9ea5 100644 --- a/src/modules/bmm/agents/sm.agent.yaml +++ b/src/modules/bmm/agents/sm.agent.yaml @@ -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 diff --git a/src/modules/bmm/testarch/README.md b/src/modules/bmm/testarch/README.md index 8dee829e..6c25f08f 100644 --- a/src/modules/bmm/testarch/README.md +++ b/src/modules/bmm/testarch/README.md @@ -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) |
Execution Notes diff --git a/src/modules/bmm/workflows/1-analysis/research/README.md b/src/modules/bmm/workflows/1-analysis/research/README.md index 33657113..c3359593 100644 --- a/src/modules/bmm/workflows/1-analysis/research/README.md +++ b/src/modules/bmm/workflows/1-analysis/research/README.md @@ -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 ``` diff --git a/src/modules/bmm/workflows/2-plan-workflows/README.md b/src/modules/bmm/workflows/2-plan-workflows/README.md index 983904d7..9728e579 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/README.md +++ b/src/modules/bmm/workflows/2-plan-workflows/README.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 diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/README.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/README.md index 3be0b5dc..6a084cd6 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/gdd/README.md +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/README.md @@ -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: diff --git a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md index 4c7d1418..ad737ff7 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md +++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/instructions-gdd.md @@ -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 diff --git a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md index dc388ec6..10bf8a73 100644 --- a/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md +++ b/src/modules/bmm/workflows/2-plan-workflows/ux/instructions-ux.md @@ -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) diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/ADR-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/ADR-template.md deleted file mode 100644 index 1b2a1afe..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/ADR-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml b/src/modules/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml new file mode 100644 index 00000000..247e7af8 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/architecture/architecture-patterns.yaml @@ -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" diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md new file mode 100644 index 00000000..ee97859a --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/architecture/architecture-template.md @@ -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}}_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/checklist.md b/src/modules/bmm/workflows/3-solutioning/architecture/checklist.md new file mode 100644 index 00000000..2002e03c --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/architecture/checklist.md @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml b/src/modules/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml new file mode 100644 index 00000000..a44b0149 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/architecture/decision-catalog.yaml @@ -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" diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md index 0317c583..84cc0923 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md @@ -1,461 +1,694 @@ -# Solution Architecture Workflow Instructions +# Decision Architecture Workflow Instructions - + -The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml +The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml -Communicate all responses in {communication_language} and language MUSt be tailored to {user_skill_level} +This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level} +The goal is ARCHITECTURAL DECISIONS that prevent AI agent conflicts, not detailed implementation specs +Communicate all responses in {communication_language} and tailor to {user_skill_level} Generate all documents in {document_output_language} -DOCUMENT OUTPUT: Concise, technical, LLM-optimized. Use tables/lists over prose. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not documented output content. +This workflow replaces solution-architecture with a conversation-driven approach - - mode: data - data_request: project_config - - - **⚠️ No Workflow Status File Found** + + mode: data + data_request: project_config + - Please run `workflow-init` first to: + + **⚠️ No Workflow Status File Found** - - Define your project type and level - - Map out your workflow journey - - Create the status file +The Decision Architecture workflow requires a status file to understand your project context. - Run: `workflow-init` +Please run `workflow-init` first to: - After setup, return here to run solution-architecture. - - Exit workflow - cannot proceed without status file +- Define your project type and level +- Map out your workflow journey +- Create the status file - +Run: `workflow-init` - - Store {{status_file_path}} for later updates - Use extracted project configuration: - - project_level: {{project_level}} - - field_type: {{field_type}} - - project_type: {{project_type}} - - has_user_interface: {{has_user_interface}} - - ui_complexity: {{ui_complexity}} - - ux_spec_path: {{ux_spec_path}} - - prd_status: {{prd_status}} - +After setup, return here to create your decision architecture. + +Exit workflow - cannot proceed without status file + + + + Store {{status_file_path}} for later updates + + + **Note: Level {{project_level}} Project** + +Decision Architecture is typically for Level 3-4 projects, but can be used for any project that needs architectural planning. + +For Level {{project_level}}, we'll keep the architecture appropriately scoped. + + + - + mode: validate - calling_workflow: solution-architecture + calling_workflow: architecture {{warning}} - Continue with solution-architecture anyway? (y/n) + Continue with Decision Architecture anyway? (y/n) {{suggestion}} Exit workflow -Validate Prerequisites (BLOCKING): +Check for existing PRD and epics files using fuzzy matching -Check 1: PRD complete? -IF prd_status != complete: -❌ STOP WORKFLOW -Output: "PRD is required before solution architecture. +Fuzzy match PRD file: {prd_file} + +**PRD Not Found** - REQUIRED: Complete PRD with FRs, NFRs, epics, and stories. +Decision Architecture works from your Product Requirements Document (PRD). - Run: workflow plan-project +Looking for: bmm-PRD.md, PRD.md, or product-requirements.md in {output_folder} - After PRD is complete, return here to run solution-architecture workflow." - END +Please run the PRD workflow first to define your requirements. -Check 2: UX Spec complete (if UI project)? -IF has_user_interface == true AND ux_spec_missing: -❌ STOP WORKFLOW -Output: "UX Spec is required before solution architecture for UI projects. +Run: `workflow prd` + +Exit workflow - PRD required + - REQUIRED: Complete UX specification before proceeding. - - Run: workflow ux-spec - - The UX spec will define: - - Screen/page structure - - Navigation flows - - Key user journeys - - UI/UX patterns and components - - Responsive requirements - - Accessibility requirements - - Once complete, the UX spec will inform: - - Frontend architecture and component structure - - API design (driven by screen data needs) - - State management strategy - - Technology choices (component libraries, animation, etc.) - - Performance requirements (lazy loading, code splitting) - - After UX spec is complete at /docs/ux-spec.md, return here to run solution-architecture workflow." - END - -Check 3: All prerequisites met? -IF all prerequisites met: -✅ Prerequisites validated - PRD: complete - UX Spec: {{complete | not_applicable}} -Proceeding with solution architecture workflow... - -1. Determine workflow path: - IF project_level == 0: - Skip solution architecture entirely - Output: "Level 0 project - validate/update tech-spec.md only" - STOP WORKFLOW - ELSE: - Proceed with full solution architecture workflow - - prerequisites_and_scale_assessment - - - - -Load and deeply understand the requirements documents (PRD/GDD), epics and the stories to complete them and any UX specifications. - -Intelligently determine the true nature of this project by analyzing: - -- The primary document type (PRD for software, GDD for games) -- Core functionality and features described -- Technical constraints and requirements mentioned -- User interface complexity and interaction patterns -- Performance and scalability requirements -- Integration needs with external services - - -Extract and synthesize the essential architectural drivers: - -- What type of system is being built (web, mobile, game, library, etc.) -- What are the critical quality attributes (performance, security, usability) -- What constraints exist (technical, business, regulatory) -- What integrations are required -- What scale is expected - - -If UX specifications exist, understand the user experience requirements and how they drive technical architecture: - -- Screen/page inventory and complexity -- Navigation patterns and user flows -- Real-time vs. static interactions -- Accessibility and responsive design needs -- Performance expectations from a user perspective - - -Identify gaps between requirements and technical specifications: - -- What architectural decisions are already made vs. what needs determination -- Misalignments between UX designs and functional requirements -- Missing enabler requirements that will be needed for implementation - - -requirements_analysis - - + + Load the PRD using fuzzy matching: {prd_file} + Load epics file using fuzzy matching: {epics_file} -Engage with the user to understand their technical context and preferences: - -- Note: User skill level is {user_skill_level} (from config) -- Learn about any existing technical decisions or constraints -- Understand team capabilities and preferences -- Identify any existing infrastructure or systems to integrate with - - -Based on {user_skill_level}, adapt YOUR CONVERSATIONAL STYLE: - - - - Explain architectural concepts as you discuss them - - Be patient and educational in your responses - - Clarify technical terms when introducing them +Check for UX specification using fuzzy matching: +Attempt to locate: {ux_spec_file} + +Load UX spec and extract architectural implications: - Component complexity (simple forms vs rich interactions) - Animation/transition requirements - Real-time update needs (live data, collaborative features) - Platform-specific UI requirements - Accessibility standards (WCAG compliance level) - Responsive design breakpoints - Offline capability requirements - Performance expectations (load times, interaction responsiveness) + - - - - Balance explanations with efficiency - - Assume familiarity with common concepts - - Explain only complex or unusual patterns - - - - - Be direct and technical in discussions - - Skip basic explanations - - Focus on advanced considerations and edge cases - - -NOTE: This affects only how you TALK to the user, NOT the documents you generate. -The architecture document itself should always be concise and technical. -user_context +Extract and understand from PRD: - Functional Requirements (what it must do) - Non-Functional Requirements (performance, security, compliance, etc.) - Epic structure and user stories - Acceptance criteria - Any technical constraints mentioned + + +Count and assess project scale: - Number of epics: {{epic_count}} - Number of stories: {{story_count}} - Complexity indicators (real-time, multi-tenant, regulated, etc.) - UX complexity level (if UX spec exists) + + +Reflect understanding back to {user_name}: +"I'm reviewing your project documentation for {{project_name}}. +I see {{epic_count}} epics with {{story_count}} total stories. +{{if_ux_spec}}I also found your UX specification which defines the user experience requirements.{{/if_ux_spec}} + + Key aspects I notice: + - [Summarize core functionality] + - [Note critical NFRs] + {{if_ux_spec}}- [Note UX complexity and requirements]{{/if_ux_spec}} + - [Identify unique challenges] + + This will help me guide you through the architectural decisions needed + to ensure AI agents implement this consistently." + + + +Does this match your understanding of the project? +project_context_understanding - + + Modern starter templates make many good architectural decisions by default -Based on the requirements analysis, determine the most appropriate architectural patterns: +Based on PRD analysis, identify the primary technology domain: - Web application → Look for Next.js, Vite, Remix starters - Mobile app → Look for React Native, Expo, Flutter starters - API/Backend → Look for NestJS, Express, Fastify starters - CLI tool → Look for CLI framework starters - Full-stack → Look for T3, RedwoodJS, Blitz starters + -- Consider the scale, complexity, and team size to choose between monolith, microservices, or serverless -- Evaluate whether a single repository or multiple repositories best serves the project needs -- Think about deployment and operational complexity vs. development simplicity - + + Consider UX requirements when selecting starter: + - Rich animations → Framer Motion compatible starter + - Complex forms → React Hook Form included starter + - Real-time features → Socket.io or WebSocket ready starter + - Accessibility focus → WCAG-compliant component library starter + - Design system → Storybook-enabled starter + + -Guide the user through architectural pattern selection by discussing trade-offs and implications rather than presenting a menu of options. Help them understand what makes sense for their specific context. +Search for relevant starter templates: +{{primary_technology}} starter template CLI create command latest 2024 +{{primary_technology}} boilerplate generator latest options + -architecture_patterns + + Investigate what each starter provides: + {{starter_name}} default setup technologies included latest + {{starter_name}} project structure file organization + + + + Present starter options concisely: + "Found {{starter_name}} which provides: + {{quick_decision_list}} + + This would establish our base architecture. Use it?" + + + + + Explain starter benefits: + "I found {{starter_name}}, which is like a pre-built foundation for your project. + + Think of it like buying a prefab house frame instead of cutting each board yourself. + + It makes these decisions for you: + {{friendly_decision_list}} + + This is a great starting point that follows best practices. Should we use it?" + + + + Use {{starter_name}} as the foundation? (recommended) [y/n] + + + Get current starter command and options: + {{starter_name}} CLI command options flags latest 2024 + + + Document the initialization command: + Store command: {{full_starter_command_with_options}} + Example: "npx create-next-app@latest my-app --typescript --tailwind --app" + + + Extract and document starter-provided decisions: + Starter provides these architectural decisions: + - Language/TypeScript: {{provided_or_not}} + - Styling solution: {{provided_or_not}} + - Testing framework: {{provided_or_not}} + - Linting/Formatting: {{provided_or_not}} + - Build tooling: {{provided_or_not}} + - Project structure: {{provided_pattern}} + + + Mark these decisions as "PROVIDED BY STARTER" in our decision tracking + + Note for first implementation story: + "Project initialization using {{starter_command}} should be the first implementation story" + + + + + Any specific reason to avoid the starter? (helps me understand constraints) + Note: Manual setup required, all decisions need to be made explicitly + + + + + + Note: No standard starter template found for this project type. + Will need to make all architectural decisions explicitly. + + +starter_template_decision - + + Based on {user_skill_level} from config, set facilitation approach: -Analyze the epics and requirements to identify natural boundaries for components or services: + + Set mode: EXPERT + - Use technical terminology freely + - Move quickly through decisions + - Assume familiarity with patterns and tools + - Focus on edge cases and advanced concerns + -- Group related functionality that changes together -- Identify shared infrastructure needs (authentication, logging, monitoring) -- Consider data ownership and consistency boundaries -- Think about team structure and ownership + + Set mode: INTERMEDIATE + - Balance technical accuracy with clarity + - Explain complex patterns briefly + - Confirm understanding at key points + - Provide context for non-obvious choices + + + + Set mode: BEGINNER + - Use analogies and real-world examples + - Explain technical concepts in simple terms + - Provide education about why decisions matter + - Protect from complexity overload + -Map epics to architectural components, ensuring each epic has a clear home and the overall structure supports the planned functionality. +Load decision catalog: {decision_catalog} +Load architecture patterns: {architecture_patterns} -component_structure +Analyze PRD against patterns to identify needed decisions: - Match functional requirements to known patterns - Identify which categories of decisions are needed - Flag any novel/unique aspects requiring special attention - Consider which decisions the starter template already made (if applicable) + + +Create decision priority list: +CRITICAL (blocks everything): - {{list_of_critical_decisions}} + + IMPORTANT (shapes architecture): + - {{list_of_important_decisions}} + + NICE-TO-HAVE (can defer): + - {{list_of_optional_decisions}} + + + +Announce plan to {user_name} based on mode: + +"Based on your PRD, we need to make {{total_decision_count}} architectural decisions. +{{starter_covered_count}} are covered by the starter template. +Let's work through the remaining {{remaining_count}} decisions." + + + + "Great! I've analyzed your requirements and found {{total_decision_count}} technical + choices we need to make. Don't worry - I'll guide you through each one and explain + why it matters. {{if_starter}}The starter template handles {{starter_covered_count}} + of these automatically.{{/if_starter}}" + + + + +decision_identification - + + Each decision must be made WITH the user, not FOR them + ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions -Use intent-based decision making, not prescriptive checklists. +For each decision in priority order: -Based on requirements analysis, identify the project domain(s). -Note: Projects can be hybrid (e.g., web + mobile, game + backend service). +Present the decision based on mode: + +"{{Decision_Category}}: {{Specific_Decision}} +Options: {{concise_option_list_with_tradeoffs}} +Recommendation: {{recommendation}} for {{reason}}" + -Use the simplified project types mapping: -{{installed_path}}/project-types/project-types.csv + + "Next decision: {{Human_Friendly_Category}} -This contains ~11 core project types that cover 99% of software projects. + We need to choose {{Specific_Decision}}. -For identified domains, reference the intent-based instructions: -{{installed_path}}/project-types/{{type}}-instructions.md + Common options: + {{option_list_with_brief_explanations}} -These are guidance files, not prescriptive checklists. + For your project, {{recommendation}} would work well because {{reason}}." + -IMPORTANT: Instructions are guidance, not checklists. + + "Let's talk about {{Human_Friendly_Category}}. + + {{Educational_Context_About_Why_This_Matters}} + + Think of it like {{real_world_analogy}}. + + Your main options: + {{friendly_options_with_pros_cons}} + + My suggestion: {{recommendation}} + This is good for you because {{beginner_friendly_reason}}." + -- Use your knowledge to identify what matters for THIS project -- Consider emerging technologies not in any list -- Address unique requirements from the PRD/GDD -- Focus on decisions that affect implementation consistency -Engage with the user to make all necessary technical decisions: + + Verify current stable version: + {{technology}} latest stable version 2024 + {{technology}} current LTS version + -- Use the question files to ensure coverage of common areas -- Go beyond the standard questions to address project-specific needs -- Focus on decisions that will affect implementation consistency -- Get specific versions for all technology choices -- Document clear rationale for non-obvious decisions - + Update decision record with verified version: + Technology: {{technology}} + Verified Version: {{version_from_search}} + Verification Date: {{today}} + -Remember: The goal is to make enough definitive decisions that future implementation agents can work autonomously without architectural ambiguity. + -technical_decisions +What's your preference? (or 'explain more' for details) + + + Provide deeper explanation appropriate to skill level + + Consider using advanced elicitation: + "Would you like to explore innovative approaches to this decision? + I can help brainstorm unconventional solutions if you have specific goals." + + + + +Record decision: +Category: {{category}} +Decision: {{user_choice}} +Version: {{verified_version_if_applicable}} +Affects Epics: {{list_of_affected_epics}} +Rationale: {{user_reasoning_or_default}} +Provided by Starter: {{yes_if_from_starter}} + + +Check for cascading implications: +"This choice means we'll also need to {{related_decisions}}" + + +decision_record - + + These decisions affect EVERY epic and story -Select the appropriate adaptive template: -{{installed_path}}/project-types/{{type}}-template.md +Facilitate decisions for consistency patterns: - Error handling strategy (How will all agents handle errors?) - Logging approach (Structured? Format? Levels?) - Date/time handling (Timezone? Format? Library?) - Authentication pattern (Where? How? Token format?) - API response format (Structure? Status codes? Errors?) - Testing strategy (Unit? Integration? E2E?) + -Template selection follows the naming convention: + + Explain why these matter: + "These are rules that EVERY part of your app must follow. + If we don't decide now, each AI agent will do it differently, + and your app won't work properly when the pieces come together." + + -- Web project → web-template.md -- Mobile app → mobile-template.md -- Game project → game-template.md (adapts heavily based on game type) -- Backend service → backend-template.md -- Data pipeline → data-template.md -- CLI tool → cli-template.md -- Library/SDK → library-template.md -- Desktop app → desktop-template.md -- Embedded system → embedded-template.md -- Extension → extension-template.md -- Infrastructure → infrastructure-template.md - -For hybrid projects, choose the primary domain or intelligently merge relevant sections from multiple templates. - -Adapt the template heavily based on actual requirements. -Templates are starting points, not rigid structures. - -Generate a comprehensive yet concise architecture document that includes: - -MANDATORY SECTIONS (all projects): - -1. Executive Summary (1-2 paragraphs max) -2. Technology Decisions Table - SPECIFIC versions for everything -3. Repository Structure and Source Tree -4. Component Architecture -5. Data Architecture (if applicable) -6. API/Interface Contracts (if applicable) -7. Key Architecture Decision Records - -The document MUST be optimized for LLM consumption: - -- Use tables over prose wherever possible -- List specific versions, not generic technology names -- Include complete source tree structure -- Define clear interfaces and contracts -- NO verbose explanations (even for beginners - they get help in conversation, not docs) -- Technical and concise throughout - - -Ensure the document provides enough technical specificity that implementation agents can: - -- Set up the development environment correctly -- Implement features consistently with the architecture -- Make minor technical decisions within the established framework -- Understand component boundaries and responsibilities - - -solution_architecture +cross_cutting_decisions - + + Based on all decisions made, define the project structure -Quality gate to ensure the architecture is ready for implementation. +Create comprehensive source tree: - Root configuration files - Source code organization - Test file locations - Build/dist directories - Documentation structure + -Perform a comprehensive validation of the architecture document: +Map epics to architectural boundaries: +"Epic: {{epic_name}} → Lives in {{module/directory/service}}" + -- Verify every requirement has a technical solution -- Ensure all technology choices have specific versions -- Check that the document is free of ambiguous language -- Validate that each epic can be implemented with the defined architecture -- Confirm the source tree structure is complete and logical - +Define integration points: - Where do components communicate? - What are the API boundaries? - How do services interact? + -Generate an Epic Alignment Matrix showing how each epic maps to: - -- Architectural components -- Data models -- APIs and interfaces -- External integrations - This matrix helps validate coverage and identify gaps. - -If issues are found, work with the user to resolve them before proceeding. The architecture must be definitive enough for autonomous implementation. - -cohesion_validation +project_structure - + + Some projects require INVENTING new patterns, not just choosing existing ones -Assess the complexity of specialist areas (DevOps, Security, Testing) based on the project requirements: +Scan PRD for concepts that don't have standard solutions: - Novel interaction patterns (e.g., "swipe to match" before Tinder existed) - Unique multi-component workflows (e.g., "viral invitation system") - New data relationships (e.g., "social graph" before Facebook) - Unprecedented user experiences (e.g., "ephemeral messages" before Snapchat) - Complex state machines crossing multiple epics + -- For simple deployments and standard security, include brief inline guidance -- For complex requirements (compliance, multi-region, extensive testing), create placeholders for specialist workflows - + + For each novel pattern identified: -Engage with the user to understand their needs in these specialist areas and determine whether to address them now or defer to specialist agents. + Engage user in design collaboration: + + "The {{pattern_name}} concept requires architectural innovation. -specialist_guidance + Core challenge: {{challenge_description}} + + Let's design the component interaction model:" + + + + "Your idea about {{pattern_name}} is unique - there isn't a standard way to build this yet! + + This is exciting - we get to invent the architecture together. + + Let me help you think through how this should work:" + + + + Facilitate pattern design: + 1. Identify core components involved + 2. Map data flow between components + 3. Design state management approach + 4. Create sequence diagrams for complex flows + 5. Define API contracts for the pattern + 6. Consider edge cases and failure modes + + + Use advanced elicitation for innovation: + "What if we approached this differently? + - What would the ideal user experience look like? + - Are there analogies from other domains we could apply? + - What constraints can we challenge?" + + + Document the novel pattern: + Pattern Name: {{pattern_name}} + Purpose: {{what_problem_it_solves}} + Components: + {{component_list_with_responsibilities}} + Data Flow: + {{sequence_description_or_diagram}} + Implementation Guide: + {{how_agents_should_build_this}} + Affects Epics: + {{epics_that_use_this_pattern}} + + + Validate pattern completeness: + "Does this {{pattern_name}} design cover all the use cases in your epics? + - {{use_case_1}}: ✓ Handled by {{component}} + - {{use_case_2}}: ✓ Handled by {{component}} + ..." + + + + + + Note: All patterns in this project have established solutions. + Proceeding with standard architectural patterns. + + +novel_pattern_designs - + + These patterns ensure multiple AI agents write compatible code + Focus on what agents could decide DIFFERENTLY if not specified -If the architecture design revealed gaps or needed clarifications in the requirements: +Load pattern categories: {pattern_categories} + +Based on chosen technologies, identify potential conflict points: +"Given that we're using {{tech_stack}}, agents need consistency rules for:" + + +For each relevant pattern category, facilitate decisions: + + NAMING PATTERNS (How things are named): + + - REST endpoint naming: /users or /user? Plural or singular? + - Route parameter format: :id or {id}? + + + - Table naming: users or Users or user? + - Column naming: user_id or userId? + - Foreign key format: user_id or fk_user? + + + - Component naming: UserCard or user-card? + - File naming: UserCard.tsx or user-card.tsx? + + + STRUCTURE PATTERNS (How things are organized): + - Where do tests live? __tests__/ or *.test.ts co-located? + - How are components organized? By feature or by type? + - Where do shared utilities go? + + FORMAT PATTERNS (Data exchange formats): + + - API response wrapper? {data: ..., error: ...} or direct response? + - Error format? {message, code} or {error: {type, detail}}? + - Date format in JSON? ISO strings or timestamps? + + + COMMUNICATION PATTERNS (How components interact): + + - Event naming convention? + - Event payload structure? + + + - State update pattern? + - Action naming convention? + + + LIFECYCLE PATTERNS (State and flow): + - How are loading states handled? + - What's the error recovery pattern? + - How are retries implemented? + + LOCATION PATTERNS (Where things go): + - API route structure? + - Static asset organization? + - Config file locations? + + CONSISTENCY PATTERNS (Cross-cutting): + - How are dates formatted in the UI? + - What's the logging format? + - How are user-facing errors written? -- Identify missing enabler epics (e.g., infrastructure setup, monitoring) -- Clarify ambiguous stories based on technical decisions -- Add any newly discovered non-functional requirements -Work with the user to update the PRD if necessary, ensuring alignment between requirements and architecture. + + Rapid-fire through patterns: + "Quick decisions on implementation patterns: + - {{pattern}}: {{suggested_convention}} OK? [y/n/specify]" + + + + + Explain each pattern's importance: + "Let me explain why this matters: + If one AI agent names database tables 'users' and another names them 'Users', + your app will crash. We need to pick one style and make sure everyone follows it." + + + +Document implementation patterns: +Category: {{pattern_category}} +Pattern: {{specific_pattern}} +Convention: {{decided_convention}} +Example: {{concrete_example}} +Enforcement: "All agents MUST follow this pattern" + + +implementation_patterns - + + Run coherence checks: -For each epic, create a focused technical specification that extracts only the relevant parts of the architecture: +Check decision compatibility: - Do all decisions work together? - Are there any conflicting choices? - Do the versions align properly? + -- Technologies specific to that epic -- Component details for that epic's functionality -- Data models and APIs used by that epic -- Implementation guidance specific to the epic's stories - +Verify epic coverage: - Does every epic have architectural support? - Are all user stories implementable with these decisions? - Are there any gaps? + -These epic-specific specs provide focused context for implementation without overwhelming detail. +Validate pattern completeness: - Are there any patterns we missed that agents would need? - Do novel patterns integrate with standard architecture? - Are implementation patterns comprehensive enough? + -epic_tech_specs + + Address issues with {user_name}: + "I notice {{issue_description}}. + We should {{suggested_resolution}}." + + How would you like to resolve this? + Update decisions based on resolution + + +coherence_validation - + + The document must be complete, specific, and validation-ready + This is the consistency contract for all AI agents -If this is a polyrepo project, ensure each repository has access to the complete architectural context: +Load template: {architecture_template} -- Copy the full architecture documentation to each repository -- This ensures every repo has the complete picture for autonomous development - - +Generate sections: 1. Executive Summary (2-3 sentences about the architecture approach) 2. Project Initialization (starter command if applicable) 3. Decision Summary Table (with verified versions and epic mapping) 4. Complete Project Structure (full tree, no placeholders) 5. Epic to Architecture Mapping (every epic placed) 6. Technology Stack Details (versions, configurations) 7. Integration Points (how components connect) 8. Novel Pattern Designs (if any were created) 9. Implementation Patterns (all consistency rules) 10. Consistency Rules (naming, organization, formats) 11. Data Architecture (models and relationships) 12. API Contracts (request/response formats) 13. Security Architecture (auth, authorization, data protection) 14. Performance Considerations (from NFRs) 15. Deployment Architecture (where and how) 16. Development Environment (setup and prerequisites) 17. Architecture Decision Records (key decisions with rationale) + - +Fill template with all collected decisions and patterns -Validate that the architecture package is complete: +Ensure starter command is first implementation story: + +"## Project Initialization + + First implementation story should execute: + ```bash + {{starter_command_with_options}} + ``` + + This establishes the base architecture with these decisions: + {{starter_provided_decisions}}" + -- Solution architecture document with all technical decisions -- Epic-specific technical specifications -- Cohesion validation report -- Clear source tree structure -- Definitive technology choices with versions -Prepare the story backlog from the PRD/epics for Phase 4 implementation. +architecture_document + + + + Load validation checklist: {installed_path}/checklist.md + +Run validation checklist from {installed_path}/checklist.md + +Verify MANDATORY items: +□ Decision table has Version column with specific versions +□ Every epic is mapped to architecture components +□ Source tree is complete, not generic +□ No placeholder text remains +□ All FRs from PRD have architectural support +□ All NFRs from PRD are addressed +□ Implementation patterns cover all potential conflicts +□ Novel patterns are fully documented (if applicable) + + + + Fix missing items automatically + Regenerate document section + + +validation_results + + + + Present completion summary: + + + "Architecture complete. {{decision_count}} decisions documented. + Ready for implementation phase." + + + + "Excellent! Your architecture is complete. You made {{decision_count}} important + decisions that will keep AI agents consistent as they build your app. + + What happens next: + 1. AI agents will read this architecture before implementing each story + 2. They'll follow your technical choices exactly + 3. Your app will be built with consistent patterns throughout + + You're ready to move to the implementation phase!" + + + +Save document to {output_folder}/architecture.md + + + mode: update + action: complete_workflow + workflow_name: architecture + + + + ✅ Decision Architecture workflow complete! + + Status updated. Next steps: + - Review the architecture.md document + - {{next_workflow_suggestion}} ({{next_agent}} agent) + + + + +**Deliverables Created:** + +- ✅ architecture.md - Complete architectural decisions document + {{if_novel_patterns}} +- ✅ Novel pattern designs for unique concepts + {{/if_novel_patterns}} + {{if_starter_template}} +- ✅ Project initialization command documented + {{/if_starter_template}} + +The architecture is ready to guide AI agents through consistent implementation. + completion_summary - - - - mode: update - action: complete_workflow - workflow_name: solution-architecture - populate_stories_from: {epics_file} - - - - ✅ Status updated! Loaded {{total_stories}} stories from epics. - Next: {{next_workflow}} ({{next_agent}} agent) - Phase 3 complete! - - - - ⚠️ Status update failed: {{error}} - - -**✅ Solution Architecture Complete, {user_name}!** - -**Architecture Documents:** - -- bmm-solution-architecture.md (main architecture document) -- bmm-cohesion-check-report.md (validation report) -- bmm-tech-spec-epic-1.md through bmm-tech-spec-epic-{{epic_count}}.md ({{epic_count}} specs) - -**Story Backlog:** - -- {{total_story_count}} stories populated in status file -- First story: {{first_story_id}} ready for drafting - -**Status Updated:** - -- Phase 3 (Solutioning) complete ✓ -- Progress: {{new_progress_percentage}}% -- Ready for Phase 4 (Implementation) - -**Next Steps:** - -1. Load SM agent to draft story {{first_story_id}} -2. Run `create-story` workflow -3. Review drafted story -4. Run `story-ready` to approve for development - -Check status anytime with: `workflow-status` - - - diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/pattern-categories.csv b/src/modules/bmm/workflows/3-solutioning/architecture/pattern-categories.csv new file mode 100644 index 00000000..bad699b1 --- /dev/null +++ b/src/modules/bmm/workflows/3-solutioning/architecture/pattern-categories.csv @@ -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. \ No newline at end of file diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md deleted file mode 100644 index e2017a67..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-instructions.md +++ /dev/null @@ -1,162 +0,0 @@ -# Backend/API Service Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/backend-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md deleted file mode 100644 index 0053842d..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-instructions.md +++ /dev/null @@ -1,149 +0,0 @@ -# CLI Tool Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/cli-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md deleted file mode 100644 index 5ba5ee4a..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-instructions.md +++ /dev/null @@ -1,193 +0,0 @@ -# Data Pipeline/Analytics Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/data-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md deleted file mode 100644 index 59f96624..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-instructions.md +++ /dev/null @@ -1,182 +0,0 @@ -# Desktop Application Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/desktop-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md deleted file mode 100644 index edf1c067..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-instructions.md +++ /dev/null @@ -1,191 +0,0 @@ -# Embedded/IoT System Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/embedded-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md deleted file mode 100644 index 6399772d..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-instructions.md +++ /dev/null @@ -1,193 +0,0 @@ -# Browser/Editor Extension Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md deleted file mode 100644 index fb372b20..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/extension-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md deleted file mode 100644 index 273c74b3..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-instructions.md +++ /dev/null @@ -1,225 +0,0 @@ -# Game Development Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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 - - -The architecture MUST adapt to the game type identified in the GDD. -Load the specific game type considerations and merge with general guidance. - - -### 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-template.md deleted file mode 100644 index 5e78469a..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/game-template.md +++ /dev/null @@ -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}} - - -This architecture adapts to {{game_type}} requirements. -Sections are included/excluded based on game needs. - - -## 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 - - -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 - - -{{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 - - -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 - - -### 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 - - -Adapt to game data needs: -- Simple puzzle: JSON level files -- RPG: Complex relational data -- Multiplayer: Server-authoritative state -- Roguelike: Seed-based generation - - -{{data_management}} - -### 4.2 Save System - -{{save_system}} - -### 4.3 Content Pipeline - -{{content_pipeline}} - -## 5. Scene/Level Architecture - - -Structure varies by game type: -- Linear: Sequential level loading -- Open World: Streaming and chunks -- Stage-based: Level selection and unlocking -- Procedural: Generation pipeline - - -{{scene_architecture}} - -## 6. Gameplay Implementation - - -ONLY include subsections relevant to the game. -A racing game doesn't need an inventory system. -A puzzle game doesn't need combat mechanics. - - -{{gameplay_systems}} - -## 7. Presentation Layer - - -Adapt to visual style: -- 3D: Rendering pipeline, lighting, LOD -- 2D: Sprite management, layers -- Text: Minimal visual architecture -- Hybrid: Both 2D and 3D considerations - - -### 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 - - -Only for games with multiplayer features - - -### 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 - - -Platform-specific considerations: -- Mobile: Touch controls, battery, performance -- Console: Achievements, controllers, certification -- PC: Wide hardware range, settings -- Web: Download size, browser compatibility - - -{{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 - - -Adapt to platform and game type: -- Mobile: Strict size limits -- Web: Download optimization -- Console: Memory constraints -- PC: Balance quality vs. performance - - -{{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 - - -Testing needs vary by game: -- Multiplayer: Network testing, load testing -- Procedural: Seed testing, generation validation -- Physics: Determinism testing -- Narrative: Story branch testing - - -{{testing_strategy}} - -## 17. Key Architecture Decisions - -### Decision Records - -{{architecture_decisions}} - -### Risk Mitigation - -{{risk_mitigation}} - -{{#if_complex_project}} - -## 18. Specialist Considerations - - -Only for complex projects needing specialist input - - -{{specialist_notes}} -{{/if_complex_project}} - ---- - -## Implementation Roadmap - -{{implementation_roadmap}} - ---- - -_Architecture optimized for {{game_type}} game on {{platforms}}_ -_Generated using BMad Method Solution Architecture workflow_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md deleted file mode 100644 index 4fd46f6e..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-instructions.md +++ /dev/null @@ -1,198 +0,0 @@ -# Infrastructure/DevOps Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/infrastructure-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md deleted file mode 100644 index e18c776b..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-instructions.md +++ /dev/null @@ -1,185 +0,0 @@ -# Library/SDK Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/library-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md deleted file mode 100644 index 2cee3d0d..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-instructions.md +++ /dev/null @@ -1,181 +0,0 @@ -# Mobile Application Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md deleted file mode 100644 index 8d58e102..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/mobile-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv deleted file mode 100644 index 74aef1b3..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv +++ /dev/null @@ -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 \ No newline at end of file diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md deleted file mode 100644 index 4299818a..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-instructions.md +++ /dev/null @@ -1,158 +0,0 @@ -# Web Project Architecture Instructions - -## Intent-Based Technical Decision Guidance - - -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 - - -## 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 - - -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. - - -## 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. diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-template.md b/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-template.md deleted file mode 100644 index 4c92ff67..00000000 --- a/src/modules/bmm/workflows/3-solutioning/architecture/project-types/web-template.md +++ /dev/null @@ -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_ diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/readme.md b/src/modules/bmm/workflows/3-solutioning/architecture/readme.md index e69de29b..48d0d916 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/readme.md +++ b/src/modules/bmm/workflows/3-solutioning/architecture/readme.md @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml index b2c30aad..6a7ba819 100644 --- a/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/architecture/workflow.yaml @@ -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" diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/README.md b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/README.md index 3fd89877..98c90788 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/README.md +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/README.md @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/checklist.md b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/checklist.md index 24195338..3da84522 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/checklist.md +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/checklist.md @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md index b7cb3067..620bf6e4 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/instructions.md @@ -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 The validation approach must adapt to the project level - don't look for documents that shouldn't exist at lower levels @@ -54,7 +54,7 @@ After setup, return here to validate implementation readiness. 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. 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 PRD ↔ Stories Coverage (Level 2-4): diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml index 7bfab81f..adda383b 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml @@ -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" diff --git a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml index 7c48c315..a2c99249 100644 --- a/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml +++ b/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml @@ -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" diff --git a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml index dd06909a..9d75a7e7 100644 --- a/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/create-story/workflow.yaml @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/README.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/README.md similarity index 97% rename from src/modules/bmm/workflows/3-solutioning/epic-tech-context/README.md rename to src/modules/bmm/workflows/4-implementation/epic-tech-context/README.md index c0cef79a..64e47cd1 100644 --- a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/README.md +++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/README.md @@ -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 diff --git a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/checklist.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/checklist.md similarity index 100% rename from src/modules/bmm/workflows/3-solutioning/epic-tech-context/checklist.md rename to src/modules/bmm/workflows/4-implementation/epic-tech-context/checklist.md diff --git a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/instructions.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md similarity index 100% rename from src/modules/bmm/workflows/3-solutioning/epic-tech-context/instructions.md rename to src/modules/bmm/workflows/4-implementation/epic-tech-context/instructions.md diff --git a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/template.md b/src/modules/bmm/workflows/4-implementation/epic-tech-context/template.md similarity index 100% rename from src/modules/bmm/workflows/3-solutioning/epic-tech-context/template.md rename to src/modules/bmm/workflows/4-implementation/epic-tech-context/template.md diff --git a/src/modules/bmm/workflows/3-solutioning/epic-tech-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml similarity index 100% rename from src/modules/bmm/workflows/3-solutioning/epic-tech-context/workflow.yaml rename to src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml diff --git a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml index 321c3683..dfcfb4f8 100644 --- a/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml +++ b/src/modules/bmm/workflows/4-implementation/review-story/workflow.yaml @@ -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 diff --git a/src/modules/bmm/workflows/README.md b/src/modules/bmm/workflows/README.md index ca8cbba9..e7d8df72 100644 --- a/src/modules/bmm/workflows/README.md +++ b/src/modules/bmm/workflows/README.md @@ -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 diff --git a/src/modules/bmm/workflows/testarch/framework/README.md b/src/modules/bmm/workflows/testarch/framework/README.md index 20426e29..6db8553e 100644 --- a/src/modules/bmm/workflows/testarch/framework/README.md +++ b/src/modules/bmm/workflows/testarch/framework/README.md @@ -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:** diff --git a/src/modules/bmm/workflows/testarch/framework/instructions.md b/src/modules/bmm/workflows/testarch/framework/instructions.md index 32967776..47cc9922 100644 --- a/src/modules/bmm/workflows/testarch/framework/instructions.md +++ b/src/modules/bmm/workflows/testarch/framework/instructions.md @@ -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 diff --git a/src/modules/bmm/workflows/testarch/test-design/instructions.md b/src/modules/bmm/workflows/testarch/test-design/instructions.md index 803f5226..551e30fb 100644 --- a/src/modules/bmm/workflows/testarch/test-design/instructions.md +++ b/src/modules/bmm/workflows/testarch/test-design/instructions.md @@ -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 diff --git a/src/modules/bmm/workflows/testarch/test-design/workflow.yaml b/src/modules/bmm/workflows/testarch/test-design/workflow.yaml index 662a42b0..a124127b 100644 --- a/src/modules/bmm/workflows/testarch/test-design/workflow.yaml +++ b/src/modules/bmm/workflows/testarch/test-design/workflow.yaml @@ -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: diff --git a/src/modules/bmm/workflows/workflow-status/INTEGRATION-EXAMPLE.md b/src/modules/bmm/workflows/workflow-status/INTEGRATION-EXAMPLE.md deleted file mode 100644 index 54810df5..00000000 --- a/src/modules/bmm/workflows/workflow-status/INTEGRATION-EXAMPLE.md +++ /dev/null @@ -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 - - -Search {output_folder}/ for files matching pattern: bmm-workflow-status.md -Find the most recent file... - - -``` - -With the new service call: - -```xml - - - - mode: validate - calling_workflow: product-brief - - - - {{suggestion}} - Note: Status tracking is optional. You can continue without it. - - - - {{warning}} - Continue anyway? (y/n) - - Exit workflow - - - -Store {{status_file_path}} for later updates if needed - -``` - -### Example 2: Getting Story Data (create-story workflow) - -Replace the complex Step 2.5: - -```xml - - -Read {output_folder}/bmm-workflow-status.md (if exists) -Navigate to "### Implementation Progress (Phase 4 Only)" section -Find "#### TODO (Needs Drafting)" section - - -``` - -With the new service call: - -```xml - - - - mode: data - data_request: next_story - - - - Fall back to legacy story discovery - - - - Use {{todo_story_id}} as story to draft - Use {{todo_story_title}} for validation - Create file: {{todo_story_file}} - Drafting story {{todo_story_id}}: {{todo_story_title}} - - -``` - -### Example 3: Getting Project Configuration (solution-architecture workflow) - -```xml - - - mode: data - data_request: project_config - - - - No status file. Run standalone or create status first? - - - - Use {{project_level}} to determine architecture complexity - Use {{project_type}} to select appropriate templates - Use {{field_type}} to know if brownfield constraints apply - - -``` - -### Example 4: Quick Init Check (any workflow) - -```xml - - - mode: init-check - - - - {{suggestion}} - Proceeding without status tracking... - - -``` - -## 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 - - mode: update - action: complete_workflow - workflow_name: prd - populate_stories_from: {output_folder}/bmm-epics.md - - - - PRD complete! Next: {{next_workflow}} ({{next_agent}} agent) - -``` - -**2. populate_stories** - Load story queue from epics.md - -```xml - - mode: update - action: populate_stories - epics_file: {output_folder}/bmm-epics.md - - - - Loaded {{total_stories}} stories. First: {{first_story}} - -``` - -**3. start_story** - Move TODO → IN PROGRESS - -```xml - - mode: update - action: start_story - - - - Started: {{in_progress_story}}. Next TODO: {{next_todo}} - -``` - -**4. complete_story** - Move IN PROGRESS → DONE, advance queue - -```xml - - mode: update - action: complete_story - - - - Completed: {{completed_story}}. {{stories_remaining}} remaining. - - 🎉 All stories complete! - - -``` - -**5. set_current_workflow** - Manual override (rarely needed) - -```xml - - mode: update - action: set_current_workflow - workflow_name: tech-spec - -``` - ---- - -### `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 - - Load {{status_file_path}} - - current_workflow - Set to: "prd - Complete" - - phase_2_complete - Set to: true - - decisions_log - Add entry: "- **{{date}}**: Completed PRD workflow..." - - Populate STORIES_SEQUENCE from epics.md story list - Count total stories and update story counts - - Save {{status_file_path}} - -``` - -### NEW WAY - 6 clean lines: - -```xml - - - mode: update - action: complete_workflow - workflow_name: prd - populate_stories_from: {output_folder}/bmm-epics.md - - - PRD complete! Next: {{next_workflow}} - -``` - -**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 🎉 diff --git a/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml b/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml index a4c6831a..7f0b9150 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml @@ -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 diff --git a/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml b/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml index 01112e74..145e8ea3 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml @@ -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" diff --git a/src/modules/bmm/workflows/workflow-status/paths/game-design.yaml b/src/modules/bmm/workflows/workflow-status/paths/game-design.yaml index bd647cb1..7e33a3de 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/game-design.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/game-design.yaml @@ -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 diff --git a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml index 0fa150a6..3349b40f 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml @@ -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 diff --git a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml index 05a1f4c8..64e1b2d2 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml @@ -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 diff --git a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml index 46b05002..fe27bf6d 100644 --- a/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml +++ b/src/modules/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml @@ -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 diff --git a/src/modules/cis/_module-installer/install-menu-config.yaml b/src/modules/cis/_module-installer/install-config.yaml similarity index 100% rename from src/modules/cis/_module-installer/install-menu-config.yaml rename to src/modules/cis/_module-installer/install-config.yaml