bmad/core/tasks/workflow.xml

@@ -70,14 +70,6 @@
       <substep n="2c" title="Handle Special Output Tags">
         <if tag="template-output">
           <mandate>Generate content for this section</mandate>
-          <mandate critical="true">MARKDOWN FORMATTING RULES - Critical for proper rendering across all markdown parsers:
-            1. ALWAYS add blank line before and after bullet lists (-, *, +)
-            2. ALWAYS add blank line before and after numbered lists (1., 2., etc.)
-            3. ALWAYS add blank line before and after tables (| header |)
-            4. ALWAYS add blank line before and after code blocks (```)
-            5. Use - for bullets consistently (not * or +)
-            6. Use language identifier for code fences (```bash, ```javascript, etc.)
-          </mandate>
           <mandate>Save to file (Write first time, Edit subsequent)</mandate>
           <action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action>
           <action>Display generated content</action>

bmad/core/workflows/party-mode/workflow.yaml

@@ -10,7 +10,7 @@ date: system-generated
 
 # This is an interactive action workflow - no template output
 template: false
-instructions: "{project-root}/bmad/core/workflows/party-mode/instructions.md"
+instructions: "{project-root}/src/core/workflows/party-mode/instructions.md"
 
 # Exit conditions
 exit_triggers:

src/core/workflows/party-mode/workflow.yaml

@@ -10,7 +10,7 @@ date: system-generated
 
 # This is an interactive action workflow - no template output
 template: false
-instructions: "{project-root}/bmad/core/workflows/party-mode/instructions.md"
+instructions: "{project-root}/src/core/workflows/party-mode/instructions.md"
 
 # Exit conditions
 exit_triggers:

src/modules/bmm/agents/analyst.agent.yaml

@@ -35,7 +35,7 @@ agent:
       description: Produce Project Brief
 
     - trigger: document-project
-      workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml"
       description: Generate comprehensive documentation of an existing Project
 
     - trigger: research

src/modules/bmm/agents/dev.agent.yaml

@@ -28,16 +28,16 @@ agent:
   menu:
     - trigger: workflow-status
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
-      description: "Check workflow status and get recommendations"
+      description: Check workflow status and get recommendations
 
-    - trigger: develop-story
+    - trigger: develop
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
       description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
 
     - trigger: story-done
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-done/workflow.yaml"
-      description: "Mark story done after DoD complete"
+      description: Mark story done after DoD complete
 
     - trigger: code-review
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
-      description: "Perform a thorough clean context QA code review on a story flagged Ready for Review"
+      description: "Perform a thorough clean context review on a story flagged Ready for Review, and appends review notes to story file"

src/modules/bmm/agents/sm.agent.yaml

@@ -31,11 +31,11 @@ agent:
 
     - trigger: epic-tech-context
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
-      description: (Optional) Use the PRD and Architecture to create a Tech-Spec for a specific epic
+      description: Use the PRD and Architecture to create a Tech-Spec for a specific epic
 
     - trigger: validate-epic-tech-context
       validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml"
-      description: (Optional) Validate latest Tech Spec against checklist
+      description: Validate latest Tech Spec against checklist
 
     - trigger: create-story
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
@@ -43,25 +43,25 @@ agent:
 
     - trigger: validate-create-story
       validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
-      description: (Optional) Validate Story Draft with Independent Review
+      description: Validate Story Draft with Independent Review
 
     - trigger: story-context
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
-      description: (Optional) Assemble dynamic Story Context (XML) from latest docs and code and mark story ready for dev
+      description: Assemble dynamic Story Context (XML) from latest docs and code and mark story ready for dev
 
     - trigger: validate-story-context
       validate-workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
-      description: (Optional) Validate latest Story Context XML against checklist
+      description: Validate latest Story Context XML against checklist
 
     - trigger: story-ready-for-dev
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-ready/workflow.yaml"
-      description: (Optional) Mark drafted story ready for dev without generating Story Context
+      description: Mark drafted story ready for dev without generating Story Context
 
     - trigger: epic-retrospective
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
       data: "{project-root}/bmad/_cfg/agent-manifest.csv"
-      description: (Optional) Facilitate team retrospective after an epic is completed
+      description: Facilitate team retrospective after an epic is completed
 
     - trigger: correct-course
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: (Optional) Execute correct-course task
+      description: Execute correct-course task

src/modules/bmm/workflows/1-analysis/document-project/README.md

@@ -162,18 +162,19 @@ Your choice [1/2/3]:
 
 ## Data Files
 
-The workflow uses a single comprehensive CSV file:
+The workflow uses three CSV files:
 
-**documentation-requirements.csv** - Complete project analysis guide
+1. **project-types.csv** - Project type detection and classification
+   - Location: `/bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv`
+   - 12 project types with detection keywords
 
-- Location: `/bmad/bmm/workflows/document-project/documentation-requirements.csv`
-- 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
-- 24 columns combining:
-  - **Detection columns**: `project_type_id`, `key_file_patterns` (identifies project type from codebase)
-  - **Requirement columns**: `requires_api_scan`, `requires_data_models`, `requires_ui_components`, etc.
-  - **Pattern columns**: `critical_directories`, `test_file_patterns`, `config_patterns`, etc.
-- Self-contained: All project detection AND scanning requirements in one file
-- Architecture patterns inferred from tech stack (no external registry needed)
+2. **registry.csv** - Architecture template matching
+   - Location: `/bmad/bmm/workflows/3-solutioning/templates/registry.csv`
+   - 170+ architecture patterns
+
+3. **documentation-requirements.csv** - Scanning requirements per project type
+   - Location: `/bmad/bmm/workflows/document-project/documentation-requirements.csv`
+   - 24 columns of analysis patterns and requirements
 
 ## Use Cases
 

src/modules/bmm/workflows/1-analysis/document-project/workflow.yaml

@@ -20,8 +20,13 @@ instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
 
 # Required data files - CRITICAL for project type detection and documentation requirements
+project_types_csv: "{project-root}/bmad/bmm/workflows/3-solutioning/architecture/project-types/project-types.csv"
+architecture_registry_csv: "{project-root}/bmad/bmm/workflows/3-solutioning/templates/registry.csv"
 documentation_requirements_csv: "{installed_path}/documentation-requirements.csv"
 
+# Architecture template references
+architecture_templates_path: "{project-root}/bmad/bmm/workflows/3-solutioning/templates"
+
 # Optional input - project root to scan (defaults to current working directory)
 recommended_inputs:
   - project_root: "User will specify or use current directory"
@@ -33,4 +38,4 @@ recommended_inputs:
 
 standalone: true
 
-web_bundle: false
+web_bundle: false # BMM workflows run locally in BMAD-METHOD project

src/modules/bmm/workflows/1-analysis/document-project/workflows/deep-dive.yaml

@@ -4,7 +4,7 @@ description: "Exhaustive deep-dive documentation of specific project areas"
 author: "BMad"
 
 # This is a sub-workflow called by document-project/workflow.yaml
-parent_workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+parent_workflow: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml"
 
 # Critical variables inherited from parent
 config_source: "{project-root}/bmad/bmb/config.yaml"
@@ -13,13 +13,13 @@ user_name: "{config_source}:user_name"
 date: system-generated
 
 # Module path and component files
-installed_path: "{project-root}/bmad/bmm/workflows/document-project/workflows"
+installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflows"
 template: false # Action workflow
 instructions: "{installed_path}/deep-dive-instructions.md"
-validation: "{project-root}/bmad/bmm/workflows/document-project/checklist.md"
+validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
 
 # Templates
-deep_dive_template: "{project-root}/bmad/bmm/workflows/document-project/templates/deep-dive-template.md"
+deep_dive_template: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/templates/deep-dive-template.md"
 
 # Runtime inputs (passed from parent workflow)
 workflow_mode: "deep_dive"

src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan-instructions.md

@@ -6,40 +6,54 @@
 <critical>Called by: document-project/instructions.md router</critical>
 <critical>Handles: initial_scan and full_rescan modes</critical>
 
-<step n="0.5" goal="Load documentation requirements data for fresh starts (not needed for resume)" if="resume_mode == false">
-<critical>DATA LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>
+<step n="0.5" goal="Load CSV data files for fresh starts (not needed for resume)" if="resume_mode == false">
+<critical>CSV LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>
 
 <action>Display explanation to user:
 
 **How Project Type Detection Works:**
 
-This workflow uses a single comprehensive CSV file to intelligently document your project:
+This workflow uses 3 CSV files to intelligently document your project:
 
-**documentation-requirements.csv** ({documentation_requirements_csv})
+1. **project-types.csv** ({project_types_csv})
+   - Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
+   - Each type has detection_keywords used to identify project type from codebase
+   - Used ONLY during initial project classification (Step 1)
 
-- Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
-- 24-column schema combining project type detection AND documentation requirements
-- **Detection columns**: project_type_id, key_file_patterns (used to identify project type from codebase)
-- **Requirement columns**: requires_api_scan, requires_data_models, requires_ui_components, etc.
-- **Pattern columns**: critical_directories, test_file_patterns, config_patterns, etc.
-- Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
-- Example: For project_type_id="web", key_file_patterns includes "package.json;tsconfig.json;\*.config.js" and requires_api_scan=true
+2. **documentation-requirements.csv** ({documentation_requirements_csv})
+   - 24-column schema that defines what to look for in each project type
+   - Columns include: requires_api_scan, requires_data_models, requires_ui_components, etc.
+   - Contains file patterns (key_file_patterns, critical_directories, test_file_patterns, etc.)
+   - Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
+   - Example: For project_type_id="web", requires_api_scan=true, so workflow scans api/ folder
 
-**When Documentation Requirements are Loaded:**
+3. **architecture-registry.csv** ({architecture_registry_csv})
+   - Maps detected tech stacks to architecture templates
+   - Used to select appropriate architecture document template
+   - Only loaded when generating architecture documentation (Step 8)
 
-- **Fresh Start (initial_scan)**: Load all 12 rows → detect type using key_file_patterns → use that row's requirements
+**When Each CSV is Loaded:**
+
+- **Fresh Start (initial_scan)**: Load project-types.csv → detect type → load corresponding doc requirements row
 - **Resume**: Load ONLY the doc requirements row(s) for cached project_type_id(s)
 - **Full Rescan**: Same as fresh start (may re-detect project type)
 - **Deep Dive**: Load ONLY doc requirements for the part being deep-dived
   </action>
 
-<action>Now loading documentation requirements data for fresh start...</action>
+<action>Now loading CSV files for fresh start...</action>
+<action>Load project-types.csv from: {project_types_csv}</action>
+<action>Store all 12 project types with their detection_keywords for use in Step 1</action>
+<action>Display: "Loaded 12 project type definitions"</action>
 
 <action>Load documentation-requirements.csv from: {documentation_requirements_csv}</action>
-<action>Store all 12 rows indexed by project_type_id for project detection and requirements lookup</action>
-<action>Display: "Loaded documentation requirements for 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)"</action>
+<action>Store all rows indexed by project_type_id for later lookup</action>
+<action>Display: "Loaded documentation requirements for 12 project types"</action>
 
-<action>Display: "✓ Documentation requirements loaded successfully. Ready to begin project analysis."</action>
+<action>Load architecture-registry.csv from: {architecture_registry_csv}</action>
+<action>Store architecture templates for later matching in Step 3</action>
+<action>Display: "Loaded architecture template registry"</action>
+
+<action>Display: "✓ CSV data files loaded successfully. Ready to begin project analysis."</action>
 </step>
 
 <step n="0.6" goal="Check for existing documentation and determine workflow mode">
@@ -175,7 +189,7 @@ Is this correct? Should I document each part separately? [y/n]
 </ask>
 
 <action if="user confirms">Set repository_type = "monorepo" or "multi-part"</action>
-<action if="user confirms">For each detected part: - Identify root path - Run project type detection using key_file_patterns from documentation-requirements.csv - Store as part in project_parts array
+<action if="user confirms">For each detected part: - Identify root path - Run project type detection against project-types.csv - Store as part in project_parts array
 </action>
 
 <action if="user denies or corrects">Ask user to specify correct parts and their paths</action>
@@ -184,10 +198,10 @@ Is this correct? Should I document each part separately? [y/n]
 <check if="single cohesive project detected">
   <action>Set repository_type = "monolith"</action>
   <action>Create single part in project_parts array with root_path = {{project_root_path}}</action>
-  <action>Run project type detection using key_file_patterns from documentation-requirements.csv</action>
+  <action>Run project type detection against project-types.csv</action>
 </check>
 
-<action>For each part, match detected technologies and file patterns against key_file_patterns column in documentation-requirements.csv</action>
+<action>For each part, match detected technologies and keywords against project-types.csv</action>
 <action>Assign project_type_id to each part</action>
 <action>Load corresponding documentation_requirements row for each part</action>
 
@@ -261,16 +275,15 @@ Are there any other important documents or key areas I should focus on while ana
   - Build technology_table with columns: Category, Technology, Version, Justification
 </action>
 
-<action>Determine architecture pattern based on detected tech stack:
+<action>Match detected tech stack against architecture_registry_csv:
 
-- Use project_type_id as primary indicator (e.g., "web" → layered/component-based, "backend" → service/API-centric)
-- Consider framework patterns (e.g., React → component hierarchy, Express → middleware pipeline)
-- Note architectural style in technology table
-- Store as {{architecture_pattern}} for each part
+- Use project_type_id + languages + architecture_style tags
+- Find closest matching architecture template
+- Store as {{architecture_match}} for each part
   </action>
 
 <template-output>technology_stack</template-output>
-<template-output>architecture_patterns</template-output>
+<template-output>architecture_template_matches</template-output>
 
 <action>Update state file:
 

src/modules/bmm/workflows/1-analysis/document-project/workflows/full-scan.yaml

@@ -4,7 +4,7 @@ description: "Complete project documentation workflow (initial scan or full resc
 author: "BMad"
 
 # This is a sub-workflow called by document-project/workflow.yaml
-parent_workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+parent_workflow: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflow.yaml"
 
 # Critical variables inherited from parent
 config_source: "{project-root}/bmad/bmb/config.yaml"
@@ -13,13 +13,15 @@ user_name: "{config_source}:user_name"
 date: system-generated
 
 # Data files
-documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/document-project/documentation-requirements.csv"
+project_types_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/project-types.csv"
+documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/documentation-requirements.csv"
+architecture_registry_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/architecture-registry.csv"
 
 # Module path and component files
-installed_path: "{project-root}/bmad/bmm/workflows/document-project/workflows"
+installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/workflows"
 template: false # Action workflow
 instructions: "{installed_path}/full-scan-instructions.md"
-validation: "{project-root}/bmad/bmm/workflows/document-project/checklist.md"
+validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
 
 # Runtime inputs (passed from parent workflow)
 workflow_mode: "" # "initial_scan" or "full_rescan"

src/modules/bmm/workflows/README.md

@@ -16,15 +16,14 @@ The BMM (BMAD Method Module) orchestrates software development through four dist
 
 **Continuous Learning Loop**: Retrospectives feed improvements back into workflows, making each epic smoother than the last.
 
-## The Four Phases (Plus Documentation Prerequisite)
+## The Five Phases
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│       PREREQUISITE: PROJECT DOCUMENTATION (Conditional)      │
-│        For brownfield projects without adequate docs         │
-│                     OR post-completion cleanup               │
+│              PHASE 0: DOCUMENTATION (Brownfield)             │
+│                  (Conditional - if undocumented)             │
 ├──────────────────────────────────────────────────────────────┤
-│  document-project ──→ Comprehensive project documentation    │
+│  document-project ──→ Codebase documentation                 │
 └────────────────────────────────────────────────────────┼─────┘
                                                          ↓
 ┌──────────────────────────────────────────────────────────────┐
@@ -103,46 +102,23 @@ The `workflow-status` workflow is the **universal entry point** for all BMM work
 
 ---
 
-## Documentation Prerequisite (Brownfield Projects)
+## Phase 0: Documentation (Brownfield Only)
 
-**NOT a numbered phase** - this is a prerequisite workflow for brownfield projects without adequate documentation, OR a post-completion tool for creating clean source-of-truth documentation after Phases 1-4 are complete.
-
-### Purpose
-
-The `document-project` workflow serves TWO critical purposes:
-
-1. **Pre-Phase 1 Prerequisite (Brownfield)**: Run BEFORE planning to understand existing codebases
-2. **Post-Phase 4 Documentation (Any Project)**: Run AFTER completion to create superior documentation that replaces scattered PRD/architecture/story artifacts
+Required for undocumented brownfield projects before planning can begin.
 
 ### Workflows
 
-| Workflow             | Agent   | Purpose                             | Output                              | When to Use                                                    |
-| -------------------- | ------- | ----------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
-| **document-project** | Analyst | Analyze and document entire project | Comprehensive project documentation | Brownfield without docs OR post-completion cleanup (any scale) |
+| Workflow             | Agent   | Purpose                    | Output                | When to Use                      |
+| -------------------- | ------- | -------------------------- | --------------------- | -------------------------------- |
+| **document-project** | Analyst | Document existing codebase | Project documentation | Brownfield without adequate docs |
 
-### Use Cases
-
-**Use Case 1: Brownfield Prerequisite**
+### Flow
 
 ```
-workflow-init detects undocumented brownfield
-    ↓
-document-project (generates index.md, architecture.md, etc.)
-    ↓
-Phase 1 (optional) → Phase 2 (planning with full context)
+Brownfield Check → document-project → Analysis/Planning (Phase 1/2)
 ```
 
-**Use Case 2: Post-Completion Documentation**
-
-```
-Phase 4 Implementation Complete
-    ↓
-document-project (scans final codebase)
-    ↓
-Produces clean, LLM-optimized docs > scattered phase artifacts
-```
-
-**Why it's superior**: Creates comprehensive, consistent documentation that both humans and LLMs can use to understand projects of any size or complexity - often better than manually-maintained PRDs, architecture docs, and story files.
+**Critical**: Brownfield projects require adequate documentation before planning. If workflow-init detects an undocumented brownfield project, it will direct you to run document-project first.
 
 ---
 
@@ -373,21 +349,20 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 
 ### Brownfield Projects (Existing Code)
 
-**Path:** Documentation Prerequisite (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
+**Path:** Phase 0 (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
 
-**Documentation Prerequisite (Conditional):**
+**Phase 0 - Documentation (Conditional):**
 
 ```
 workflow-status/workflow-init
     ├─→ Check: Is existing codebase documented?
     │   ├─→ YES: Proceed to Phase 1 or 2
-    │   └─→ NO: REQUIRED - Run document-project workflow first
+    │   └─→ NO: REQUIRED - Run document-project workflow
     │       ├─→ Analyzes existing code
     │       ├─→ Documents current architecture
     │       ├─→ Identifies technical debt
-    │       ├─→ Creates comprehensive baseline documentation
-    │       └─→ Produces superior docs for LLM + human understanding
-    └─→ Continue with scale-adaptive planning (Phases 1-4)
+    │       └─→ Creates baseline documentation
+    └─→ Continue with scale-adaptive planning
 ```
 
 **Critical for Brownfield**:
@@ -397,18 +372,15 @@ workflow-status/workflow-init
 - Technical debt must be visible in planning
 - Constraints from existing system affect scale decisions
 
-**Post-Completion Option**: After Phase 4 completes, run `document-project` again to create clean source-of-truth documentation that supersedes scattered phase artifacts.
-
 ## Agent Participation by Phase
 
-| Phase/Step                         | Primary Agents         | Supporting Agents    | Key Workflows                               |
-| ---------------------------------- | ---------------------- | -------------------- | ------------------------------------------- |
-| **Prerequisite: Documentation**    | Analyst                | -                    | document-project (conditional)              |
-| **Phase 1: Analysis**              | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
-| **Phase 2: Planning**              | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
-| **Phase 3: Solutioning**           | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
-| **Phase 4: Implementation**        | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
-| **Post-Completion: Documentation** | Analyst                | -                    | document-project (optional cleanup)         |
+| Phase                 | Primary Agents         | Supporting Agents    | Key Workflows                               |
+| --------------------- | ---------------------- | -------------------- | ------------------------------------------- |
+| **0: Documentation**  | Analyst                | -                    | document-project                            |
+| **1: Analysis**       | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
+| **2: Planning**       | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
+| **3: Solutioning**    | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
+| **4: Implementation** | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
 
 ## Key Files and Artifacts
 
@@ -430,9 +402,8 @@ workflow-status/workflow-init
 
 ### Phase Outputs
 
-- **Documentation Prerequisite (if run)**:
-  - Comprehensive project documentation (index.md, architecture.md, source-tree-analysis.md, component-inventory.md, etc.)
-  - Superior to manually-maintained docs for LLM understanding
+- **Phase 0**:
+  - Codebase documentation (project overview, architecture, source tree)
 
 - **Phase 1**:
   - Product briefs, game briefs, research documents
@@ -477,13 +448,12 @@ workflow-status/workflow-init
 - Create story context before implementation
 - Each phase completes before the next begins
 
-### 4. Document Brownfield First (Prerequisite)
+### 4. Document Brownfield First
 
 - Never plan without understanding existing code
-- Run document-project if codebase is undocumented (PREREQUISITE, not Phase 0)
+- Run document-project if codebase is undocumented
 - Technical debt must be visible in planning
 - Integration points need documentation
-- Can also run post-Phase 4 for superior final documentation
 
 ### 5. Learn Continuously
 
@@ -511,7 +481,7 @@ workflow-status/workflow-init
 # Universal Entry Point (Start Here!)
 bmad analyst workflow-status  # Check status and get recommendations
 
-# Documentation Prerequisite (Brownfield without docs OR post-completion cleanup)
+# Phase 0: Documentation (Brownfield if needed)
 bmad analyst document-project
 
 # Phase 1: Analysis (Optional)

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-0.yaml

@@ -7,17 +7,15 @@ field_type: "brownfield"
 description: "Single atomic change to existing codebase"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
     workflows:
       - id: "document-project"
         required: true
         agent: "analyst"
         command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+        output: "Codebase documentation"
 
   - phase: 1
     name: "Analysis"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-1.yaml

@@ -7,17 +7,15 @@ field_type: "brownfield"
 description: "Small feature addition to existing codebase"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
     workflows:
       - id: "document-project"
         required: true
         agent: "analyst"
         command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+        output: "Codebase documentation"
 
   - phase: 1
     name: "Analysis"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-2.yaml

@@ -7,17 +7,15 @@ field_type: "brownfield"
 description: "Medium project adding multiple features to existing codebase"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
     workflows:
       - id: "document-project"
         required: true
         agent: "analyst"
         command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+        output: "Codebase documentation"
 
   - phase: 1
     name: "Analysis"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml

@@ -7,17 +7,15 @@ field_type: "brownfield"
 description: "Complex integration with existing system architecture"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
     workflows:
       - id: "document-project"
         required: true
         agent: "analyst"
         command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+        output: "Comprehensive codebase documentation"
 
   - phase: 1
     name: "Analysis"

src/modules/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml

@@ -7,17 +7,16 @@ field_type: "brownfield"
 description: "Enterprise scale expansion of existing system"
 
 phases:
-  - prerequisite: true
+  - phase: 0
     name: "Documentation"
     conditional: "if_undocumented"
-    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup. Critical for enterprise-scale changes"
     workflows:
       - id: "document-project"
         required: true
         agent: "analyst"
         command: "document-project"
-        output: "Comprehensive project documentation"
-        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+        output: "Comprehensive codebase documentation"
+        note: "Critical for enterprise-scale changes"
 
   - phase: 1
     name: "Analysis"

tools/cli/README.md

@@ -130,23 +130,23 @@ The installer supports **15 IDE environments** through a base-derived architectu
 
 **Supported IDEs** (as of v6-alpha):
 
-| Code             | Name              | Artifact Location        |
-| ---------------- | ----------------- | ------------------------ |
-| `codex`          | Claude Code       | `.claude/commands/`      |
-| `claude-code`    | Claude Code (alt) | `.claude/commands/`      |
-| `opencode`       | OpenCode          | `.opencode`              |
-| `windsurf`       | Windsurf          | `.windsurf/workflows/`   |
-| `cursor`         | Cursor            | `.cursor/rules/`         |
-| `cline`          | Cline             | `.clinerules/workflows/` |
-| `github-copilot` | GitHub Copilot    | `.github/copilot/`       |
-| `crush`          | Crush             | `.crush/`                |
-| `auggie`         | Auggie            | `.auggie/`               |
-| `gemini`         | Google Gemini     | `.gemini/`               |
-| `qwen`           | Qwen              | `.qwen/`                 |
-| `roo`            | Roo               | `.roo/`                  |
-| `trae`           | Trae              | `.trae/`                 |
-| `iflow`          | iFlow             | `.iflow/`                |
-| `kilo`           | Kilo              | `.kilo/`                 |
+| Code             | Name              | Artifact Location      |
+| ---------------- | ----------------- | ---------------------- |
+| `codex`          | Claude Code       | `.claude/commands/`    |
+| `claude-code`    | Claude Code (alt) | `.claude/commands/`    |
+| `opencode`       | OpenCode          | `.opencode`            |
+| `windsurf`       | Windsurf          | `.windsurf/workflows/` |
+| `cursor`         | Cursor            | `.cursor/rules/`       |
+| `cline`          | Cline             | `.clinerules/`         |
+| `github-copilot` | GitHub Copilot    | `.github/copilot/`     |
+| `crush`          | Crush             | `.crush/`              |
+| `auggie`         | Auggie            | `.auggie/`             |
+| `gemini`         | Google Gemini     | `.gemini/`             |
+| `qwen`           | Qwen              | `.qwen/`               |
+| `roo`            | Roo               | `.roo/`                |
+| `trae`           | Trae              | `.trae/`               |
+| `iflow`          | iFlow             | `.iflow/`              |
+| `kilo`           | Kilo              | `.kilo/`               |
 
 **Handler Architecture**:
 

tools/cli/installers/lib/ide/cline.js

@@ -1,19 +1,46 @@
 const path = require('node:path');
-const fs = require('fs-extra');
-const chalk = require('chalk');
 const { BaseIdeSetup } = require('./_base-ide');
-const { WorkflowCommandGenerator } = require('./workflow-command-generator');
-const { getAgentsFromBmad, getTasksFromBmad } = require('./shared/bmad-artifacts');
+const chalk = require('chalk');
+const inquirer = require('inquirer');
 
 /**
  * Cline IDE setup handler
- * Installs BMAD artifacts to .clinerules/workflows with flattened naming
+ * Creates rules in .clinerules directory with ordering support
  */
 class ClineSetup extends BaseIdeSetup {
   constructor() {
-    super('cline', 'Cline', true); // preferred IDE
+    super('cline', 'Cline');
     this.configDir = '.clinerules';
-    this.workflowsDir = 'workflows';
+    this.defaultOrder = {
+      core: 10,
+      bmm: 20,
+      cis: 30,
+      other: 99,
+    };
+  }
+
+  /**
+   * Collect configuration choices before installation
+   * @param {Object} options - Configuration options
+   * @returns {Object} Collected configuration
+   */
+  async collectConfiguration(options = {}) {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'ordering',
+        message: 'How should BMAD rules be ordered in Cline?',
+        choices: [
+          { name: 'By module (core first, then modules)', value: 'module' },
+          { name: 'By importance (dev agents first)', value: 'importance' },
+          { name: 'Alphabetical (simple A-Z ordering)', value: 'alphabetical' },
+          { name: "Custom (I'll reorder manually)", value: 'custom' },
+        ],
+        default: 'module',
+      },
+    ]);
+
+    return { ordering: response.ordering };
   }
 
   /**
@@ -25,198 +52,249 @@ class ClineSetup extends BaseIdeSetup {
   async setup(projectDir, bmadDir, options = {}) {
     console.log(chalk.cyan(`Setting up ${this.name}...`));
 
-    // Create .clinerules/workflows directory
-    const clineDir = path.join(projectDir, this.configDir);
-    const workflowsDir = path.join(clineDir, this.workflowsDir);
+    // Create .clinerules directory
+    const clineRulesDir = path.join(projectDir, this.configDir);
+    await this.ensureDir(clineRulesDir);
 
-    await this.ensureDir(workflowsDir);
+    // Get agents and tasks
+    const agents = await this.getAgents(bmadDir);
+    const tasks = await this.getTasks(bmadDir);
 
-    // Clear old BMAD files
-    await this.clearOldBmadFiles(workflowsDir);
+    // Use pre-collected configuration if available
+    const config = options.preCollectedConfig || {};
+    const orderingStrategy = config.ordering || options.ordering || 'module';
 
-    // Collect all artifacts
-    const { artifacts, counts } = await this.collectClineArtifacts(projectDir, bmadDir, options);
+    // Process agents as rules with ordering
+    let ruleCount = 0;
+    for (const agent of agents) {
+      const content = await this.readFile(agent.path);
+      const order = this.getOrder(agent, orderingStrategy);
+      const processedContent = this.createAgentRule(agent, content, projectDir);
 
-    // Write flattened files
-    const written = await this.flattenAndWriteArtifacts(artifacts, workflowsDir);
+      // Use numeric prefix for ordering
+      const prefix = order.toString().padStart(2, '0');
+      const targetPath = path.join(clineRulesDir, `${prefix}-${agent.module}-${agent.name}.md`);
+
+      await this.writeFile(targetPath, processedContent);
+      ruleCount++;
+    }
+
+    // Process tasks with ordering
+    for (const task of tasks) {
+      const content = await this.readFile(task.path);
+      const order = this.getTaskOrder(task, orderingStrategy);
+      const processedContent = this.createTaskRule(task, content);
+
+      // Tasks get higher order numbers to appear after agents
+      const prefix = (order + 50).toString().padStart(2, '0');
+      const targetPath = path.join(clineRulesDir, `${prefix}-task-${task.module}-${task.name}.md`);
+
+      await this.writeFile(targetPath, processedContent);
+      ruleCount++;
+    }
 
     console.log(chalk.green(`✓ ${this.name} configured:`));
-    console.log(chalk.dim(`  - ${counts.agents} agents installed`));
-    console.log(chalk.dim(`  - ${counts.tasks} tasks installed`));
-    console.log(chalk.dim(`  - ${counts.workflows} workflow commands installed`));
-    if (counts.workflowLaunchers > 0) {
-      console.log(chalk.dim(`  - ${counts.workflowLaunchers} workflow launchers installed`));
-    }
-    console.log(chalk.dim(`  - ${written} files written to ${path.relative(projectDir, workflowsDir)}`));
+    console.log(chalk.dim(`  - ${ruleCount} rules created in ${path.relative(projectDir, clineRulesDir)}`));
+    console.log(chalk.dim(`  - Ordering: ${orderingStrategy}`));
 
-    // Usage instructions
-    console.log(chalk.yellow('\n  ⚠️  How to Use Cline Workflows'));
-    console.log(chalk.cyan('  BMAD workflows are available as slash commands in Cline'));
-    console.log(chalk.dim('  Usage:'));
-    console.log(chalk.dim('    - Type / to see available commands'));
-    console.log(chalk.dim('    - All BMAD items start with "bmad-"'));
-    console.log(chalk.dim('    - Example: /bmad-bmm-agents-pm'));
+    // Important message about toggle system
+    console.log(chalk.yellow('\n  ⚠️  IMPORTANT: Cline Toggle System'));
+    console.log(chalk.cyan('  Rules are OFF by default to avoid context pollution'));
+    console.log(chalk.dim('  To use BMAD agents:'));
+    console.log(chalk.dim('    1. Click rules icon below chat input'));
+    console.log(chalk.dim('    2. Toggle ON the specific agent you need'));
+    console.log(chalk.dim('    3. Type @{agent-name} to activate'));
+    console.log(chalk.dim('    4. Toggle OFF when done to free context'));
+    console.log(chalk.dim('\n  💡 Best practice: Only enable 1-2 agents at a time'));
 
     return {
       success: true,
-      agents: counts.agents,
-      tasks: counts.tasks,
-      workflows: counts.workflows,
-      workflowLaunchers: counts.workflowLaunchers,
-      written,
+      rules: ruleCount,
+      ordering: orderingStrategy,
     };
   }
 
   /**
-   * Detect Cline installation by checking for .clinerules/workflows directory
+   * Ask user about rule ordering strategy
    */
-  async detect(projectDir) {
-    const workflowsDir = path.join(projectDir, this.configDir, this.workflowsDir);
-
-    if (!(await fs.pathExists(workflowsDir))) {
-      return false;
-    }
-
-    const entries = await fs.readdir(workflowsDir);
-    return entries.some((entry) => entry.startsWith('bmad-'));
-  }
-
-  /**
-   * Collect all artifacts for Cline export
-   */
-  async collectClineArtifacts(projectDir, bmadDir, options = {}) {
-    const selectedModules = options.selectedModules || [];
-    const artifacts = [];
-
-    // Get agents
-    const agents = await getAgentsFromBmad(bmadDir, selectedModules);
-    for (const agent of agents) {
-      const content = await this.readAndProcessWithProject(
-        agent.path,
-        {
-          module: agent.module,
-          name: agent.name,
-        },
-        projectDir,
-      );
-
-      artifacts.push({
-        type: 'agent',
-        module: agent.module,
-        sourcePath: agent.path,
-        relativePath: path.join(agent.module, 'agents', `${agent.name}.md`),
-        content,
-      });
-    }
-
-    // Get tasks
-    const tasks = await getTasksFromBmad(bmadDir, selectedModules);
-    for (const task of tasks) {
-      const content = await this.readAndProcessWithProject(
-        task.path,
-        {
-          module: task.module,
-          name: task.name,
-        },
-        projectDir,
-      );
-
-      artifacts.push({
-        type: 'task',
-        module: task.module,
-        sourcePath: task.path,
-        relativePath: path.join(task.module, 'tasks', `${task.name}.md`),
-        content,
-      });
-    }
-
-    // Get workflows
-    const workflowGenerator = new WorkflowCommandGenerator();
-    const { artifacts: workflowArtifacts, counts: workflowCounts } = await workflowGenerator.collectWorkflowArtifacts(bmadDir);
-    artifacts.push(...workflowArtifacts);
-
-    return {
-      artifacts,
-      counts: {
-        agents: agents.length,
-        tasks: tasks.length,
-        workflows: workflowCounts.commands,
-        workflowLaunchers: workflowCounts.launchers,
+  async askOrderingStrategy() {
+    const response = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'ordering',
+        message: 'How should BMAD rules be ordered in Cline?',
+        choices: [
+          { name: 'By module (core first, then modules)', value: 'module' },
+          { name: 'By importance (dev agents first)', value: 'importance' },
+          { name: 'Alphabetical (simple A-Z ordering)', value: 'alphabetical' },
+          { name: "Custom (I'll reorder manually)", value: 'custom' },
+        ],
+        default: 'module',
       },
-    };
+    ]);
+
+    return response.ordering;
   }
 
   /**
-   * Flatten file path to bmad-module-type-name.md format
+   * Get order number for an agent based on strategy
    */
-  flattenFilename(relativePath) {
-    const sanitized = relativePath.replaceAll(/[\\/]/g, '-');
-    return `bmad-${sanitized}`;
-  }
-
-  /**
-   * Write all artifacts with flattened names
-   */
-  async flattenAndWriteArtifacts(artifacts, destDir) {
-    let written = 0;
-
-    for (const artifact of artifacts) {
-      const flattenedName = this.flattenFilename(artifact.relativePath);
-      const targetPath = path.join(destDir, flattenedName);
-      await fs.writeFile(targetPath, artifact.content);
-      written++;
-    }
-
-    return written;
-  }
-
-  /**
-   * Clear old BMAD files from the workflows directory
-   */
-  async clearOldBmadFiles(destDir) {
-    if (!(await fs.pathExists(destDir))) {
-      return;
-    }
-
-    const entries = await fs.readdir(destDir);
-
-    for (const entry of entries) {
-      if (!entry.startsWith('bmad-')) {
-        continue;
+  getOrder(agent, strategy) {
+    switch (strategy) {
+      case 'module': {
+        return this.defaultOrder[agent.module] || this.defaultOrder.other;
       }
 
-      const entryPath = path.join(destDir, entry);
-      const stat = await fs.stat(entryPath);
-      if (stat.isFile()) {
-        await fs.remove(entryPath);
-      } else if (stat.isDirectory()) {
-        await fs.remove(entryPath);
+      case 'importance': {
+        // Prioritize certain agent types
+        if (agent.name.includes('dev') || agent.name.includes('code')) return 10;
+        if (agent.name.includes('architect') || agent.name.includes('design')) return 15;
+        if (agent.name.includes('test') || agent.name.includes('qa')) return 20;
+        if (agent.name.includes('doc') || agent.name.includes('write')) return 25;
+        if (agent.name.includes('review')) return 30;
+        return 40;
+      }
+
+      case 'alphabetical': {
+        // Use a fixed number, files will sort alphabetically by name
+        return 50;
+      }
+
+      default: {
+        // 'custom' or any other value - user will reorder manually
+        return 99;
       }
     }
   }
 
   /**
-   * Read and process file with project-specific paths
+   * Get order number for a task
    */
-  async readAndProcessWithProject(filePath, metadata, projectDir) {
-    const content = await fs.readFile(filePath, 'utf8');
-    return super.processContent(content, metadata, projectDir);
+  getTaskOrder(task, strategy) {
+    // Tasks always come after agents
+    return this.getOrder(task, strategy) + 50;
+  }
+
+  /**
+   * Create rule content for an agent
+   */
+  createAgentRule(agent, content, projectDir) {
+    // Extract metadata
+    const titleMatch = content.match(/title="([^"]+)"/);
+    const title = titleMatch ? titleMatch[1] : this.formatTitle(agent.name);
+
+    // Extract YAML content
+    const yamlMatch = content.match(/```ya?ml\r?\n([\s\S]*?)```/);
+    const yamlContent = yamlMatch ? yamlMatch[1] : content;
+
+    // Get relative path
+    const relativePath = path.relative(projectDir, agent.path).replaceAll('\\', '/');
+
+    let ruleContent = `# ${title} Agent
+
+This rule defines the ${title} persona and project standards.
+
+## Role Definition
+
+When the user types \`@${agent.name}\`, adopt this persona and follow these guidelines:
+
+\`\`\`yaml
+${yamlContent}
+\`\`\`
+
+## Project Standards
+
+- Always maintain consistency with project documentation in BMAD directories
+- Follow the agent's specific guidelines and constraints
+- Update relevant project files when making changes
+- Reference the complete agent definition in [${relativePath}](${relativePath})
+
+## Usage
+
+Type \`@${agent.name}\` to activate this ${title} persona.
+
+## Module
+
+Part of the BMAD ${agent.module.toUpperCase()} module.
+`;
+
+    return ruleContent;
+  }
+
+  /**
+   * Create rule content for a task
+   */
+  createTaskRule(task, content) {
+    // Extract task name
+    const nameMatch = content.match(/<name>([^<]+)<\/name>/);
+    const taskName = nameMatch ? nameMatch[1] : this.formatTitle(task.name);
+
+    let ruleContent = `# ${taskName} Task
+
+This rule defines the ${taskName} task workflow.
+
+## Task Workflow
+
+When this task is referenced, execute the following steps:
+
+${content}
+
+## Project Integration
+
+- This task follows BMAD Method standards
+- Ensure all outputs align with project conventions
+- Update relevant documentation after task completion
+
+## Usage
+
+Reference with \`@task-${task.name}\` to access this workflow.
+
+## Module
+
+Part of the BMAD ${task.module.toUpperCase()} module.
+`;
+
+    return ruleContent;
+  }
+
+  /**
+   * Format name as title
+   */
+  formatTitle(name) {
+    return name
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
   }
 
   /**
    * Cleanup Cline configuration
    */
   async cleanup(projectDir) {
-    const workflowsDir = path.join(projectDir, this.configDir, this.workflowsDir);
-    await this.clearOldBmadFiles(workflowsDir);
-    console.log(chalk.dim(`Removed ${this.name} BMAD configuration`));
-  }
+    const fs = require('fs-extra');
+    const clineRulesDir = path.join(projectDir, this.configDir);
 
-  /**
-   * Utility: Ensure directory exists
-   */
-  async ensureDir(dirPath) {
-    await fs.ensureDir(dirPath);
+    if (await fs.pathExists(clineRulesDir)) {
+      // Remove all numbered BMAD rules
+      const files = await fs.readdir(clineRulesDir);
+      let removed = 0;
+
+      for (const file of files) {
+        // Check if it matches our naming pattern (XX-module-name.md)
+        if (/^\d{2}-.*\.md$/.test(file)) {
+          const filePath = path.join(clineRulesDir, file);
+          const content = await fs.readFile(filePath, 'utf8');
+
+          // Verify it's a BMAD rule
+          if (content.includes('BMAD') && content.includes('Module')) {
+            await fs.remove(filePath);
+            removed++;
+          }
+        }
+      }
+
+      console.log(chalk.dim(`Removed ${removed} BMAD rules from Cline`));
+    }
   }
 }
 

tools/cli/lib/ui.js

@@ -27,12 +27,9 @@ class UI {
     const bmadDir = path.join(confirmedDirectory, 'bmad');
     const hasExistingInstall = await fs.pathExists(bmadDir);
 
-    // Track action type (only set if there's an existing installation)
-    let actionType;
-
     // Only show action menu if there's an existing installation
     if (hasExistingInstall) {
-      const promptResult = await inquirer.prompt([
+      const { actionType } = await inquirer.prompt([
         {
           type: 'list',
           name: 'actionType',
@@ -48,9 +45,6 @@ class UI {
         },
       ]);
 
-      // Extract actionType from prompt result
-      actionType = promptResult.actionType;
-
       // Handle quick update separately
       if (actionType === 'quick-update') {
         return {
@@ -75,11 +69,15 @@ class UI {
         };
       }
 
-      // Handle reinstall - DON'T return early, let it flow through configuration collection
-      // The installer will handle deletion when it sees actionType === 'reinstall'
-      // For now, just note that we're in reinstall mode and continue below
+      // Handle reinstall
+      if (actionType === 'reinstall') {
+        return {
+          actionType: 'reinstall',
+          directory: confirmedDirectory,
+        };
+      }
 
-      // If actionType === 'update' or 'reinstall', continue with normal flow below
+      // If actionType === 'update', continue with normal flow below
     }
 
     // Collect IDE tool selection EARLY (before module configuration)
@@ -96,7 +94,7 @@ class UI {
     CLIUtils.displayModuleComplete('core', false); // false = don't clear the screen again
 
     return {
-      actionType: actionType || 'update', // Preserve reinstall or update action
+      actionType: 'update', // User chose to update/modify existing installation
       directory: confirmedDirectory,
       installCore: true, // Always install core
       modules: selectedModules,