BMAD-METHOD/src/modules/bmm/workflows/3-solutioning/architecture/instructions.md

Solution Architecture Workflow Instructions

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} 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.

mode: data data_request: project_config **⚠️ No Workflow Status File Found**

Please run `workflow-init` first to:

- Define your project type and level
- Map out your workflow journey
- Create the status file

Run: `workflow-init`

After setup, return here to run solution-architecture.
</output>
<action>Exit workflow - cannot proceed without status file</action>

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}} mode: validate calling_workflow: solution-architecture {{warning}} Continue with solution-architecture anyway? (y/n) {{suggestion}} Exit workflow

Validate Prerequisites (BLOCKING):

Check 1: PRD complete? IF prd_status != complete: ❌ STOP WORKFLOW Output: "PRD is required before solution architecture.

         REQUIRED: Complete PRD with FRs, NFRs, epics, and stories.

         Run: workflow plan-project

         After PRD is complete, return here to run solution-architecture workflow."
 END

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.

         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

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

Based on the requirements analysis, determine the most appropriate architectural patterns:

• 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

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.

architecture_patterns

Analyze the epics and requirements to identify natural boundaries for components or services:

• 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

Map epics to architectural components, ensuring each epic has a clear home and the overall structure supports the planned functionality.

component_structure

Use intent-based decision making, not prescriptive checklists.

Based on requirements analysis, identify the project domain(s). Note: Projects can be hybrid (e.g., web + mobile, game + backend service).

Use the simplified project types mapping: {{installed_path}}/project-types/project-types.csv

This contains ~11 core project types that cover 99% of software projects.

For identified domains, reference the intent-based instructions: {{installed_path}}/project-types/{{type}}-instructions.md

These are guidance files, not prescriptive checklists.

IMPORTANT: Instructions are guidance, not checklists.

• 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:

• 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

Remember: The goal is to make enough definitive decisions that future implementation agents can work autonomously without architectural ambiguity.

technical_decisions

Select the appropriate adaptive template: {{installed_path}}/project-types/{{type}}-template.md

Template selection follows the naming convention:

• 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

Quality gate to ensure the architecture is ready for implementation.

Perform a comprehensive validation of the architecture document:

• 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

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

Assess the complexity of specialist areas (DevOps, Security, Testing) based on the project requirements:

• For simple deployments and standard security, include brief inline guidance
• For complex requirements (compliance, multi-region, extensive testing), create placeholders for specialist workflows

Engage with the user to understand their needs in these specialist areas and determine whether to address them now or defer to specialist agents.

specialist_guidance

If the architecture design revealed gaps or needed clarifications in the requirements:

• 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.

For each epic, create a focused technical specification that extracts only the relevant parts of the architecture:

• 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

These epic-specific specs provide focused context for implementation without overwhelming detail.

epic_tech_specs

If this is a polyrepo project, ensure each repository has access to the complete architectural context:

• Copy the full architecture documentation to each repository
• This ensures every repo has the complete picture for autonomous development

Validate that the architecture package is complete:

• 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.

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