BMAD v6 architecture.md are not as good as they were in v4 - In depth analysis

[cloudconsultants]

BMAD v4 vs v6 Architecture Workflow: In-Depth Analysis

Executive Summary

I noticed that: v4 provides a superior guided architecture experience compared to v6's current implementation. After analyzing the complete execution engines, instructions, and supporting files, I've identified the specific mechanisms that made v4 feel like working with a "dedicated expert agent" versus v6's "generic quick output."

Root Cause: v6 adopted a "conversation-driven" philosophy but lost the structured scaffolding that made v4 comprehensive. v6 can be adapted to preserve v4's quality while gaining v6's modern features.

The Core Problem: What v6 Lost from v4

1. Document Generation Philosophy

v4 Approach:

• Template-First: YAML template with 16+ predefined sections drives the entire flow
• Comprehensive Documentation: Produces detailed architecture documents with all sections
• Step-by-Step Processing: Each section rendered sequentially with user interaction
• Mandatory Elicitation: At elicit: true sections, HARD STOP with 1-9 numbered menu
• Guided Exploration: Detailed instructions in each section tell AI exactly what to consider

v6 Approach:

• Conversation-First: Adaptive facilitation based on PRD analysis
• Decision-Focused: Emphasizes architectural decisions that prevent agent conflicts
• Minimal Output: Produces leaner decision architecture documents
• Optional Elicitation: Checkpoints offer elicitation but don't enforce it
• Intent-Based: AI interprets goals and adapts approach based on context

Impact: v4 produces more comprehensive, structured documents because the template explicitly defines all required sections. v6 may skip sections if they don't emerge from the conversation.

2. Template Structure

v4 Template (architecture-tmpl.yaml):

sections:
  - id: high-level-architecture
    elicit: true
    sections:
      - id: technical-summary
        instruction: "Provide 3-5 sentences overview..."
      - id: high-level-overview
        instruction: "Based on PRD Technical Assumptions..."
      - id: project-diagram
        type: mermaid
        mermaid_type: graph
      - id: architectural-patterns
        template: "- **{{pattern_name}}:** {{pattern_description}}"

v6 Template (architecture-template.md):

## Decision Summary

| Category | Decision | Version | Affects Epics | Rationale |
| -------- | -------- | ------- | ------------- | --------- |

{{decision_table_rows}}

Impact: v4 templates are prescriptive with nested structures, examples, and templates. v6 templates are placeholder-based expecting the workflow to populate them through conversation.

3. Execution Control

v4 Execution (create-doc.md):

1. Load YAML template
2. For each section:
   • Check conditions
   • Generate content using detailed instructions
   • If elicit=true: Display 1-9 menu, WAIT for user selection
   • Execute selected elicitation method (2-9)
   • Continue to next section
3. Save complete document

v6 Execution (workflow.xml + instructions.md):

1. Load workflow.yaml configuration
2. Execute 12 steps in instructions.md:
   • Step 1: Understand PRD
   • Step 2: Discover starter templates
   • Step 3: Adapt facilitation
   • Step 4: Facilitate decisions
   • ...
   • Step 10: Generate document from template
3. At <template-output> tags: Save → Checkpoint → Options (not mandatory)

Impact: v4 enforces section-by-section progression with mandatory stops. v6 allows continuous flow with optional checkpoints.

4. Elicitation Integration

v4 Advanced Elicitation:

• Mandatory at sections marked elicit: true
• Intelligent method selection (20+ methods)
• Numbered menu: 1=Proceed, 2-9=Elicitation methods
• Methods categorized: Reflective, Structural, Risk, Creative, Multi-Persona, Advanced
• Results presented with "Apply changes?" option

v6 Advanced Elicitation:

• Optional at checkpoint prompts
• User selects [a]dvanced elicitation option
• 5 methods selected based on context
• Similar execution but not enforced

Impact: v4 forces deeper thinking at critical sections. v6 relies on user initiative.

5. Section Coverage

v4 Sections (architecture-tmpl.yaml):

1. Introduction (starter template check, changelog)
2. High-Level Architecture (summary, overview, diagrams, patterns)
3. Tech Stack (cloud infrastructure, technology table)
4. Data Models (entities, relationships)
5. Components (services, interfaces, dependencies, diagrams)
6. External APIs (integration specs)
7. Core Workflows (sequence diagrams)
8. REST API Spec (OpenAPI 3.0)
9. Database Schema (DDL/schema definitions)
10. Source Tree (folder structure)
11. Infrastructure & Deployment (IaC, CI/CD, environments)
12. Error Handling Strategy (logging, patterns)
13. Coding Standards (mandatory rules for AI)
14. Test Strategy (unit, integration, e2e)
15. Security (input validation, auth, secrets, API security, data protection)
16. Checklist Results
17. Next Steps

v6 Sections (architecture-template.md):

1. Executive Summary
2. Project Initialization (starter commands)
3. Decision Summary (table)
4. Project Structure (source tree)
5. Epic to Architecture Mapping
6. Technology Stack Details
7. Integration Points
8. Novel Pattern Designs (optional)
9. Implementation Patterns
10. Consistency Rules (naming, organization, error handling, logging)
11. Data Architecture
12. API Contracts
13. Security Architecture
14. Performance Considerations
15. Deployment Architecture
16. Development Environment
17. Architecture Decision Records

Impact: v4 has more explicit technical sections (REST API Spec, Database Schema, Test Strategy details). v6 combines sections and focuses on decisions/patterns.

6. Tech Stack Selection Process

v4 Process:

• Presents 2-3 options for each technology category
• Provides pros/cons for each option
• Makes clear recommendation with rationale
• Gets explicit user approval
• Documents exact versions (pins specific versions)
• Creates detailed technology table with Category | Technology | Version | Purpose | Rationale

v6 Process:

• Analyzes PRD for technology requirements
• Discovers modern starter templates (new in v6)
• Uses WebSearch to verify current stable versions
• Documents decisions in simplified Decision Summary table
• Focuses on decisions that affect epic implementation

Impact: v4 produces more thorough technology selection documentation. v6 assumes starters handle many decisions.

7. Knowledge Base Integration

v4 Knowledge:

• technical-preferences.md: User/project tech preferences
• elicitation-methods.md: 20+ structured elicitation techniques
• bmad-kb.md: 31KB comprehensive BMAD Method knowledge base
• architect-checklist.md: Architecture validation framework
• po-master-checklist.md: Final validation before development

v6 Knowledge:

• decision-catalog.yaml: Architectural decision categories with triggers and compatibility
• architecture-patterns.yaml: Requirement patterns and technology heuristics
• pattern-categories.csv: Meta-knowledge about pattern types
• checklist.md: Document validation requirements

Impact: v4 knowledge is documentation-focused. v6 knowledge is decision-focused.

8. Agent Orchestration

v4 Orchestration:

• bmad-orchestrator.md: Master agent routes to specialized agents
• architect.md: Winston (The Architect) agent with 8 commands
• greenfield-fullstack.yaml: 18-step workflow sequence
• Clear agent handoff prompts between phases
• Feedback loops route back to appropriate agents

v6 Orchestration:

• workflow.xml: Universal workflow execution engine
• architect.md: Architect agent that invokes architecture workflow
• bmm-workflow-status.yaml: Tracks workflow sequence and completion
• Workflow integration with Phase 1 (Analysis) → Phase 2 (Plan) → Phase 3 (Solutioning) → Phase 4 (Implementation)

Impact: v4 uses agent-centric orchestration. v6 uses workflow-centric orchestration.

In-Depth Mechanical Analysis: v4 vs v6

1. Execution Engine Comparison

v4: create-doc.md (104 lines)

Philosophy: Template-driven with enforced interaction

Critical Mandates:

Line 14-15: MANDATORY STEP-BY-STEP EXECUTION - Each section must be processed sequentially with user feedback
Line 13: ELICITATION IS REQUIRED - When `elicit: true`, you MUST use the 1-9 format and wait for user response

Processing Flow:

1. Parse YAML template - Loads architecture-tmpl.yaml with 652 lines of structured guidance
2. For each section:
   • Check conditions (skip if unmet)
   • Check agent permissions
   • Draft content using section instruction ← KEY: Detailed instruction per section
   • Present content + detailed rationale (trade-offs, assumptions, decisions)
   • IF elicit: true → HARD STOP with 1-9 menu (Option 1 = Proceed, 2-9 = Elicitation methods)
   • Execute elicitation if selected
   • Save to file

Rationale Requirement (Lines 53-60):

When presenting section content, ALWAYS include rationale that explains:
- Trade-offs and choices made (what was chosen over alternatives and why)
- Key assumptions made during drafting
- Interesting or questionable decisions that need user attention
- Areas that might need validation

Result: Every section has:

1. Detailed instruction telling AI what to consider
2. Mandatory rationale explaining decisions
3. Optional but easily accessible elicitation for depth
4. Examples showing expected format

v6: workflow.xml (270 lines) + instructions.md (769 lines)

Philosophy: Conversation-driven with optional checkpoints

Critical Mandates:

Line 8: Save to template output file after EVERY "template-output" tag
Line 14 (WORKFLOW-RULES): Template-output tags: Save content → Show user → Get approval before continuing

Processing Flow:

1. Execute 12 numbered steps in instructions.md
2. At <template-output> tags:
   • Save content
   • Show checkpoint separator
   • Display generated content
   • Offer options: [a]Advanced Elicitation / [c]Continue / [p]Party-Mode / [y]YOLO
   • WAIT for user response

No Enforced Rationale: Unlike v4, there's no requirement to explain trade-offs and assumptions at each section. The workflow can proceed without forcing the AI to justify its choices.

Result: Quality depends on:

1. AI's interpretation of step goals
2. User proactively requesting elicitation
3. Adaptive facilitation working as intended

2. Template Structure Comparison

v4: architecture-tmpl.yaml (652 lines)

Section Structure Example:

- id: tech-stack
  title: Tech Stack
  instruction: |
    This is the DEFINITIVE technology selection section. Work with the user to make specific choices:

    1. Review PRD technical assumptions and any preferences from .bmad-core/data/technical-preferences.yaml
    2. For each category, present 2-3 viable options with pros/cons
    3. Make a clear recommendation based on project needs
    4. Get explicit user approval for each selection
    5. Document exact versions (avoid "latest" - pin specific versions)
    6. This table is the single source of truth - all other docs must reference these choices

    Key decisions to finalize:
    - Starter templates (if any)
    - Languages and runtimes with exact versions
    - Frameworks and libraries / packages
    - Cloud provider and key services choices
    - Database and storage solutions
    - Development tools

    Upon render of the table, ensure the user is aware of the importance of this sections choices...
  elicit: true
  sections:
    - id: cloud-infrastructure
      template: |
        - **Provider:** {{cloud_provider}}
        - **Key Services:** {{core_services_list}}
    - id: technology-stack-table
      type: table
      columns: [Category, Technology, Version, Purpose, Rationale]
      examples:
        - "| **Language** | TypeScript | 5.3.3 | Primary development language | Strong typing... |"

Key Features:

• Nested sections with specific sub-topics
• Detailed multi-step instructions (1, 2, 3...)
• Examples showing expected format
• Template strings with variable substitution
• Type hints (table, code, mermaid)
• elicit: true triggering mandatory interaction

Coverage: 17 major sections, many with 3-5 subsections

v6: architecture-template.md (104 lines) + instructions.md (769 lines)

Template Structure:

## Decision Summary

| Category | Decision | Version | Affects Epics | Rationale |
| -------- | -------- | ------- | ------------- | --------- |

{{decision_table_rows}}

## Project Structure

{{project_root}}/
{{source_tree}}

## Implementation Patterns

{{implementation_patterns}}

Instructions Structure (Step 4 example):

<step n="4" goal="Facilitate collaborative decision making" repeat="for-each-decision">
  <critical>Each decision must be made WITH the user, not FOR them</critical>
  <critical>ALWAYS verify current versions using WebSearch - NEVER trust hardcoded versions</critical>

  <action>For each decision in priority order:</action>

  <action>Present the decision based on mode:
    <check if="mode == 'EXPERT'">
      "{{Decision_Category}}: {{Specific_Decision}}
      Options: {{concise_option_list_with_tradeoffs}}
      Recommendation: {{recommendation}} for {{reason}}"
    </check>
  </action>

  <ask>What's your preference? (or 'explain more' for details)</ask>

  <action>Record decision:
    Category: {{category}}
    Decision: {{user_choice}}
    Version: {{verified_version_if_applicable}}
  </action>
</step>

Key Features:

• Placeholder-based template (relies on conversation to populate)
• Step-based instructions with goals
• Adaptive facilitation (expert/intermediate/beginner modes)
• WebSearch integration for version verification
• template-output tags for checkpoints

Coverage: 12 steps covering similar ground but without section-specific scaffolding

3. What v4 Had That v6 Lost

A. Section-Specific Scaffolding

v4: Each of 17 major sections had:

• Dedicated instruction paragraph
• Sub-sections with specific prompts
• Examples showing format
• Type hints (table, code, mermaid)

v6: 12 generic steps that must infer structure from PRD

Impact: v4 forces comprehensive coverage by having pre-defined sections. v6 can skip aspects if they don't emerge from conversation.

B. Mandatory Elicitation Points

v4:

• elicit: true on 8 critical sections
• HARD STOP - workflow cannot continue without user interaction
• 1-9 menu with intelligent method selection
• Advanced elicitation task (120+ lines of sophisticated selection logic)

v6:

• Optional [a] at checkpoints
• User must proactively request it
• Same advanced elicitation backend, but not enforced

Impact: v4 forces deeper thinking at architectural decision points. v6 relies on user initiative.

C. Rationale Requirement

v4 create-doc.md lines 53-60:

When presenting section content, ALWAYS include rationale that explains:
- Trade-offs and choices made (what was chosen over alternatives and why)
- Key assumptions made during drafting
- Interesting or questionable decisions that need user attention
- Areas that might need validation

v6: No equivalent mandate. The "adaptive facilitation" mentions rationale in templates, but it's not enforced.

Impact: v4 makes the AI explain its reasoning, helping users understand trade-offs. v6 can present decisions without justification.

D. Examples and Format Hints

v4 YAML sections include:

examples:
  - "| **Language** | TypeScript | 5.3.3 | Primary development language | Strong typing, excellent tooling, team expertise |"
  - "| **Runtime** | Node.js | 20.11.0 | JavaScript runtime | LTS version, stable performance, wide ecosystem |"

v6: Generic placeholders like {{decision_table_rows}} without format guidance in template

Impact: v4 shows exactly what output should look like. v6 requires AI to infer format.

E. Comprehensive Tech Stack Process

v4 tech-stack section (lines 126-165):

• Instructs AI to present 2-3 options for each category
• Requires pros/cons for each option
• Demands explicit user approval
• Pins specific versions
• Creates detailed 5-column table

v6 Step 4:

• Asks for user preference
• Records decision
• Verifies version via WebSearch (good!)
• But doesn't enforce option presentation

Impact: v4 educates the user by presenting alternatives. v6 can jump to recommendations.

4. What v6 Gained Over v4

A. Starter Template Discovery (NEW)

v6 Step 2 (157-243):

<action>Search for relevant starter templates with websearch:
  <WebSearch>{{primary_technology}} starter template CLI create command latest {date}</WebSearch>
</action>

• Searches for modern starters
• Analyzes what they provide
• Documents initialization command
• Marks decisions as "PROVIDED BY STARTER"

v4: Manual template handling in introduction section, no active discovery

Impact: v6 reduces decision fatigue by leveraging modern tooling

B. Dynamic Version Verification (NEW)

v6 Step 4 (lines 355-367):

<check if="decision_involves_specific_technology">
  <action>Verify current stable version:
    <WebSearch>{{technology}} latest stable version 2024</WebSearch>
    <WebSearch>{{technology}} current LTS version</WebSearch>
  </action>
</check>

v4: Hardcoded versions in templates (risk of staleness)

Impact: v6 ensures current, verified versions

C. Adaptive Skill-Based Communication (NEW)

v6 Step 3 (lines 247-273):

<check if="{user_skill_level} == 'expert'">
  Set mode: EXPERT
  - Use technical terminology freely
  - Move quickly through decisions
  - Assume familiarity with patterns and tools
</check>

<check if="{user_skill_level} == 'beginner'">
  Set mode: BEGINNER
  - Use analogies and real-world examples
  - Explain technical concepts in simple terms
  - Provide education about why decisions matter
</check>

v4: Single communication style

Impact: v6 adapts to user expertise

D. Novel Pattern Design Step (NEW)

v6 Step 7 (lines 438-521):

• Explicitly identifies concepts without standard solutions
• Facilitates pattern invention
• Documents with sequence diagrams
• Maps to affected epics/FRs

v4: No dedicated pattern invention step

Impact: v6 handles unique architectural challenges better

E. Implementation Pattern Focus (NEW)

v6 Step 8 (lines 523-613):

• Loads pattern categories from CSV
• Systematically covers: naming, structure, format, communication, lifecycle, location, consistency
• Explicitly designed to prevent AI agent conflicts

v4: Has "Coding Standards" section but not as systematic

Impact: v6 optimizes for multi-agent consistency

F. Workflow Status Tracking (NEW)

v6 Step 0 & 12:

• Reads bmm-workflow-status.yaml
• Validates sequence (ensures PRD exists first)
• Updates status on completion
• Identifies next workflow

v4: Manual agent-to-agent handoffs

Impact: v6 provides project-wide orchestration

5. Why I Felt v4 Was Better: The Missing Link

In v4 I felt I was guided through a lot of aspects... while v6 just quickly gives me a generic output. I don't feel I am talking with a dedicated expert agent.

The Mechanism:

v4's "Expert Agent" Feel Comes From:

1. Section-by-section scaffolding - You're walked through 17 predefined areas
2. Detailed instructions per section - AI is told exactly what to consider
3. Mandatory rationale - AI must explain its thinking
4. Examples - You see what good output looks like
5. Elicitation stops - You're forced to reflect at key points
6. Options presentation - You see alternatives with pros/cons

Result: Feels like a consultant walking you through a checklist, explaining each decision.

v6's "Generic Quick Output" Problem:

1. Placeholder templates - AI fills in blanks from conversation
2. Step goals - AI interprets broadly ("facilitate decisions")
3. Optional elicitation - Deep exploration requires user initiative
4. Adaptive facilitation - Supposed to help but can skip details
5. Decision-focused - Optimizes for agent consistency, not documentation completeness

Result: Feels like AI rushing through to get a document done.

Key Insights:

• v4's power = Detailed per-section instructions + Mandatory elicitation + Examples
• v6's power = WebSearch verification + Starter discovery + Workflow orchestration + Adaptive communication
• Hybrid = v6 framework + v4 scaffolding = Best of both worlds

Summary

v4 provided superior guidance. The reason is mechanical, not philosophical - v4 had detailed instruction scaffolding per section, mandatory elicitation, and required rationale that v6 abandoned in favor of "adaptive conversation."

The solution is not to abandon v6, but to restore v4's proven scaffolding within v6's superior framework. This gives you:

✅ v4's comprehensive section-by-section guidance
✅ v4's mandatory elicitation at key decisions
✅ v4's rationale requirements
✅ v4's examples and format hints
✅ v6's WebSearch version verification
✅ v6's starter template discovery
✅ v6's workflow status tracking
✅ v6's adaptive skill-based communication
✅ v6's novel pattern design focus
✅ v6's implementation pattern systematization

The implementation is straightforward: Create enhanced instructions.md by porting v4's 17 sections as detailed substeps within v6's 12-step framework, expand the template to include all v4 sections, and make elicitation mandatory at 5 critical points.

[mcgetts]

Sounds useful - is there a step by step guide that new users could follow to implement this?

[refugeesidhar]

Would love to see more focus on the process and less on adding new features into the alpha branch. Would have been better to release a v6 and save some of these things for v7. Gotta keep what worked working...

[dannyspencer100]

@bmadcode Thanks for all your amazing work on BMad! Would love to see these qualities from V4 integrated into V6!!