marked sm menu items as optional that are optional

* fix: add CommonMark-compliant markdown formatting rules to workflow

Problem:
--------
BMAD generates markdown that violates CommonMark specification by omitting
required blank lines around lists, tables, and code blocks. While GitHub's
renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app
break completely, rendering lists as plain text and losing document structure.

Solution:
---------
Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that
enforce proper spacing and consistency:

1. ALWAYS add blank line before and after bullet lists
2. ALWAYS add blank line before and after numbered lists
3. ALWAYS add blank line before and after tables
4. ALWAYS add blank line before and after code blocks
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences

Impact:
-------
- Makes BMAD output CommonMark compliant
- Ensures compatibility with ALL markdown parsers, not just GitHub
- Follows industry best practices for professional documentation
- Future-proofs against stricter parser implementations
- Zero content changes - only formatting improved

Testing:
--------
Comprehensive three-phase testing completed:
- Phase 1: Synthetic test validating fix mechanism
- Phase 2: Fresh install end-to-end test (API Gateway project)
- Phase 3: GitHub validation with visual proof

Results: 1,112 lines of formatting improvements, 0 content changes,
100% CommonMark compliance achieved.

Test Evidence:
--------------
Complete test repository with before/after comparison, Mac Markdown.app
screenshot proving the issue, and comprehensive documentation:
https://github.com/jheyworth/bmad-markdown-formatting-test

See TEST.md for full documentation, test methodology, and evidence.

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove TEST.md per maintainer feedback

As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

bmad/core/tasks/workflow.xml

@@ -70,6 +70,14 @@
       <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}/src/core/workflows/party-mode/instructions.md"
+instructions: "{project-root}/bmad/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}/src/core/workflows/party-mode/instructions.md"
+instructions: "{project-root}/bmad/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/1-analysis/document-project/workflow.yaml"
+      workflow: "{project-root}/bmad/bmm/workflows/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
+    - trigger: develop-story
       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 review on a story flagged Ready for Review, and appends review notes to story file"
+      description: "Perform a thorough clean context QA code review on a story flagged Ready for Review"

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: Use the PRD and Architecture to create a Tech-Spec for a specific epic
+      description: (Optional) 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: Validate latest Tech Spec against checklist
+      description: (Optional) 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: Validate Story Draft with Independent Review
+      description: (Optional) Validate Story Draft with Independent Review
 
     - trigger: story-context
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/story-context/workflow.yaml"
-      description: Assemble dynamic Story Context (XML) from latest docs and code and mark story ready for dev
+      description: (Optional) 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: Validate latest Story Context XML against checklist
+      description: (Optional) 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: Mark drafted story ready for dev without generating Story Context
+      description: (Optional) 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: Facilitate team retrospective after an epic is completed
+      description: (Optional) Facilitate team retrospective after an epic is completed
 
     - trigger: correct-course
       workflow: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
-      description: Execute correct-course task
+      description: (Optional) Execute correct-course task

src/modules/bmm/workflows/README.md

@@ -16,14 +16,15 @@ 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 Five Phases
+## The Four Phases (Plus Documentation Prerequisite)
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│              PHASE 0: DOCUMENTATION (Brownfield)             │
+│       PREREQUISITE: PROJECT DOCUMENTATION (Conditional)      │
-│                  (Conditional - if undocumented)             │
+│        For brownfield projects without adequate docs         │
+│                     OR post-completion cleanup               │
 ├──────────────────────────────────────────────────────────────┤
-│  document-project ──→ Codebase documentation                 │
+│  document-project ──→ Comprehensive project documentation    │
 └────────────────────────────────────────────────────────┼─────┘
                                                          ↓
 ┌──────────────────────────────────────────────────────────────┐
@@ -102,23 +103,46 @@ The `workflow-status` workflow is the **universal entry point** for all BMM work
 
 ---
 
-## Phase 0: Documentation (Brownfield Only)
+## Documentation Prerequisite (Brownfield Projects)
 
-Required for undocumented brownfield projects before planning can begin.
+**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
 
 ### Workflows
 
-| Workflow             | Agent   | Purpose                    | Output                | When to Use                      |
+| Workflow             | Agent   | Purpose                             | Output                              | When to Use                                                    |
-| -------------------- | ------- | -------------------------- | --------------------- | -------------------------------- |
+| -------------------- | ------- | ----------------------------------- | ----------------------------------- | -------------------------------------------------------------- |
-| **document-project** | Analyst | Document existing codebase | Project documentation | Brownfield without adequate docs |
+| **document-project** | Analyst | Analyze and document entire project | Comprehensive project documentation | Brownfield without docs OR post-completion cleanup (any scale) |
 
-### Flow
+### Use Cases
+
+**Use Case 1: Brownfield Prerequisite**
 
 ```
-Brownfield Check → document-project → Analysis/Planning (Phase 1/2)
+workflow-init detects undocumented brownfield
+    ↓
+document-project (generates index.md, architecture.md, etc.)
+    ↓
+Phase 1 (optional) → Phase 2 (planning with full context)
 ```
 
-**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.
+**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.
 
 ---
 
@@ -349,20 +373,21 @@ Phase Transition (Phase 2 or 3 → Phase 4)
 
 ### Brownfield Projects (Existing Code)
 
-**Path:** Phase 0 (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
+**Path:** Documentation Prerequisite (if undocumented) → Phase 1 (optional) → Phase 2 → Phase 3 (Levels 2-4) → Phase 4
 
-**Phase 0 - Documentation (Conditional):**
+**Documentation Prerequisite (Conditional):**
 
 ```
 workflow-status/workflow-init
     ├─→ Check: Is existing codebase documented?
     │   ├─→ YES: Proceed to Phase 1 or 2
-    │   └─→ NO: REQUIRED - Run document-project workflow
+    │   └─→ NO: REQUIRED - Run document-project workflow first
     │       ├─→ Analyzes existing code
     │       ├─→ Documents current architecture
     │       ├─→ Identifies technical debt
-    │       └─→ Creates baseline documentation
+    │       ├─→ Creates comprehensive baseline documentation
-    └─→ Continue with scale-adaptive planning
+    │       └─→ Produces superior docs for LLM + human understanding
+    └─→ Continue with scale-adaptive planning (Phases 1-4)
 ```
 
 **Critical for Brownfield**:
@@ -372,15 +397,18 @@ 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                 | Primary Agents         | Supporting Agents    | Key Workflows                               |
+| Phase/Step                         | Primary Agents         | Supporting Agents    | Key Workflows                               |
-| --------------------- | ---------------------- | -------------------- | ------------------------------------------- |
+| ---------------------------------- | ---------------------- | -------------------- | ------------------------------------------- |
-| **0: Documentation**  | Analyst                | -                    | document-project                            |
+| **Prerequisite: Documentation**    | Analyst                | -                    | document-project (conditional)              |
-| **1: Analysis**       | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
+| **Phase 1: Analysis**              | Analyst, Game Designer | PM, Researcher       | brainstorm-_, research, _-brief             |
-| **2: Planning**       | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
+| **Phase 2: Planning**              | PM                     | UX Designer, Analyst | prd, tech-spec, gdd, narrative              |
-| **3: Solutioning**    | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
+| **Phase 3: Solutioning**           | Architect              | PM, Tech Lead        | create-architecture, solutioning-gate-check |
-| **4: Implementation** | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
+| **Phase 4: Implementation**        | SM, DEV                | SR (code-review)     | sprint-planning, create-story, dev-story    |
+| **Post-Completion: Documentation** | Analyst                | -                    | document-project (optional cleanup)         |
 
 ## Key Files and Artifacts
 
@@ -402,8 +430,9 @@ workflow-status/workflow-init
 
 ### Phase Outputs
 
-- **Phase 0**:
+- **Documentation Prerequisite (if run)**:
-  - Codebase documentation (project overview, architecture, source tree)
+  - Comprehensive project documentation (index.md, architecture.md, source-tree-analysis.md, component-inventory.md, etc.)
+  - Superior to manually-maintained docs for LLM understanding
 
 - **Phase 1**:
   - Product briefs, game briefs, research documents
@@ -448,12 +477,13 @@ workflow-status/workflow-init
 - Create story context before implementation
 - Each phase completes before the next begins
 
-### 4. Document Brownfield First
+### 4. Document Brownfield First (Prerequisite)
 
 - Never plan without understanding existing code
-- Run document-project if codebase is undocumented
+- Run document-project if codebase is undocumented (PREREQUISITE, not Phase 0)
 - Technical debt must be visible in planning
 - Integration points need documentation
+- Can also run post-Phase 4 for superior final documentation
 
 ### 5. Learn Continuously
 
@@ -481,7 +511,7 @@ workflow-status/workflow-init
 # Universal Entry Point (Start Here!)
 bmad analyst workflow-status  # Check status and get recommendations
 
-# Phase 0: Documentation (Brownfield if needed)
+# Documentation Prerequisite (Brownfield without docs OR post-completion cleanup)
 bmad analyst document-project
 
 # Phase 1: Analysis (Optional)

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

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

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

@@ -20,13 +20,8 @@ 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"
@@ -38,4 +33,4 @@ recommended_inputs:
 
 standalone: true
 
-web_bundle: false # BMM workflows run locally in BMAD-METHOD project
+web_bundle: false

src/modules/bmm/workflows/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/1-analysis/document-project/workflow.yaml"
+parent_workflow: "{project-root}/bmad/bmm/workflows/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/1-analysis/document-project/workflows"
+installed_path: "{project-root}/bmad/bmm/workflows/document-project/workflows"
 template: false # Action workflow
 instructions: "{installed_path}/deep-dive-instructions.md"
-validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
+validation: "{project-root}/bmad/bmm/workflows/document-project/checklist.md"
 
 # Templates
-deep_dive_template: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/templates/deep-dive-template.md"
+deep_dive_template: "{project-root}/bmad/bmm/workflows/document-project/templates/deep-dive-template.md"
 
 # Runtime inputs (passed from parent workflow)
 workflow_mode: "deep_dive"

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

@@ -6,54 +6,40 @@
 <critical>Called by: document-project/instructions.md router</critical>
 <critical>Handles: initial_scan and full_rescan modes</critical>
 
-<step n="0.5" goal="Load CSV data files for fresh starts (not needed for resume)" if="resume_mode == false">
+<step n="0.5" goal="Load documentation requirements data for fresh starts (not needed for resume)" if="resume_mode == false">
-<critical>CSV LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>
+<critical>DATA LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>
 
 <action>Display explanation to user:
 
 **How Project Type Detection Works:**
 
-This workflow uses 3 CSV files to intelligently document your project:
+This workflow uses a single comprehensive CSV file to intelligently document your project:
 
-1. **project-types.csv** ({project_types_csv})
+**documentation-requirements.csv** ({documentation_requirements_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)
 
-2. **documentation-requirements.csv** ({documentation_requirements_csv})
+- Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
-   - 24-column schema that defines what to look for in each project type
+- 24-column schema combining project type detection AND documentation requirements
-   - Columns include: requires_api_scan, requires_data_models, requires_ui_components, etc.
+- **Detection columns**: project_type_id, key_file_patterns (used to identify project type from codebase)
-   - Contains file patterns (key_file_patterns, critical_directories, test_file_patterns, etc.)
+- **Requirement columns**: requires_api_scan, requires_data_models, requires_ui_components, etc.
-   - Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
+- **Pattern columns**: critical_directories, test_file_patterns, config_patterns, etc.
-   - Example: For project_type_id="web", requires_api_scan=true, so workflow scans api/ folder
+- 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
 
-3. **architecture-registry.csv** ({architecture_registry_csv})
+**When Documentation Requirements are Loaded:**
-   - Maps detected tech stacks to architecture templates
-   - Used to select appropriate architecture document template
-   - Only loaded when generating architecture documentation (Step 8)
 
-**When Each CSV is Loaded:**
+- **Fresh Start (initial_scan)**: Load all 12 rows → detect type using key_file_patterns → use that row's requirements
-
-- **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 CSV files for fresh start...</action>
+<action>Now loading documentation requirements data 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 rows indexed by project_type_id for later lookup</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"</action>
+<action>Display: "Loaded documentation requirements for 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)"</action>
 
-<action>Load architecture-registry.csv from: {architecture_registry_csv}</action>
+<action>Display: "✓ Documentation requirements loaded successfully. Ready to begin project analysis."</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">
@@ -189,7 +175,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 against project-types.csv - Store as part in project_parts array
+<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>
 
 <action if="user denies or corrects">Ask user to specify correct parts and their paths</action>
@@ -198,10 +184,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 against project-types.csv</action>
+  <action>Run project type detection using key_file_patterns from documentation-requirements.csv</action>
 </check>
 
-<action>For each part, match detected technologies and keywords against project-types.csv</action>
+<action>For each part, match detected technologies and file patterns against key_file_patterns column in documentation-requirements.csv</action>
 <action>Assign project_type_id to each part</action>
 <action>Load corresponding documentation_requirements row for each part</action>
 
@@ -275,15 +261,16 @@ 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>Match detected tech stack against architecture_registry_csv:
+<action>Determine architecture pattern based on detected tech stack:
 
-- Use project_type_id + languages + architecture_style tags
+- Use project_type_id as primary indicator (e.g., "web" → layered/component-based, "backend" → service/API-centric)
-- Find closest matching architecture template
+- Consider framework patterns (e.g., React → component hierarchy, Express → middleware pipeline)
-- Store as {{architecture_match}} for each part
+- Note architectural style in technology table
+- Store as {{architecture_pattern}} for each part
   </action>
 
 <template-output>technology_stack</template-output>
-<template-output>architecture_template_matches</template-output>
+<template-output>architecture_patterns</template-output>
 
 <action>Update state file:
 

src/modules/bmm/workflows/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/1-analysis/document-project/workflow.yaml"
+parent_workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
 
 # Critical variables inherited from parent
 config_source: "{project-root}/bmad/bmb/config.yaml"
@@ -13,15 +13,13 @@ user_name: "{config_source}:user_name"
 date: system-generated
 
 # Data files
-project_types_csv: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/data/project-types.csv"
+documentation_requirements_csv: "{project-root}/bmad/bmm/workflows/document-project/documentation-requirements.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/1-analysis/document-project/workflows"
+installed_path: "{project-root}/bmad/bmm/workflows/document-project/workflows"
 template: false # Action workflow
 instructions: "{installed_path}/full-scan-instructions.md"
-validation: "{project-root}/bmad/bmm/workflows/1-analysis/document-project/checklist.md"
+validation: "{project-root}/bmad/bmm/workflows/document-project/checklist.md"
 
 # Runtime inputs (passed from parent workflow)
 workflow_mode: "" # "initial_scan" or "full_rescan"

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

@@ -7,15 +7,17 @@ field_type: "brownfield"
 description: "Single atomic change to existing codebase"
 
 phases:
-  - phase: 0
+  - prerequisite: true
     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: "Codebase documentation"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
 
   - phase: 1
     name: "Analysis"

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

@@ -7,15 +7,17 @@ field_type: "brownfield"
 description: "Small feature addition to existing codebase"
 
 phases:
-  - phase: 0
+  - prerequisite: true
     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: "Codebase documentation"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
 
   - phase: 1
     name: "Analysis"

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

@@ -7,15 +7,17 @@ field_type: "brownfield"
 description: "Medium project adding multiple features to existing codebase"
 
 phases:
-  - phase: 0
+  - prerequisite: true
     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: "Codebase documentation"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
 
   - phase: 1
     name: "Analysis"

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

@@ -7,15 +7,17 @@ field_type: "brownfield"
 description: "Complex integration with existing system architecture"
 
 phases:
-  - phase: 0
+  - prerequisite: true
     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 codebase documentation"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
 
   - phase: 1
     name: "Analysis"

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

@@ -7,16 +7,17 @@ field_type: "brownfield"
 description: "Enterprise scale expansion of existing system"
 
 phases:
-  - phase: 0
+  - prerequisite: true
     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 codebase documentation"
+        output: "Comprehensive project documentation"
-        note: "Critical for enterprise-scale changes"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
 
   - 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      |
+| Code             | Name              | Artifact Location        |
-| ---------------- | ----------------- | ---------------------- |
+| ---------------- | ----------------- | ------------------------ |
-| `codex`          | Claude Code       | `.claude/commands/`    |
+| `codex`          | Claude Code       | `.claude/commands/`      |
-| `claude-code`    | Claude Code (alt) | `.claude/commands/`    |
+| `claude-code`    | Claude Code (alt) | `.claude/commands/`      |
-| `opencode`       | OpenCode          | `.opencode`            |
+| `opencode`       | OpenCode          | `.opencode`              |
-| `windsurf`       | Windsurf          | `.windsurf/workflows/` |
+| `windsurf`       | Windsurf          | `.windsurf/workflows/`   |
-| `cursor`         | Cursor            | `.cursor/rules/`       |
+| `cursor`         | Cursor            | `.cursor/rules/`         |
-| `cline`          | Cline             | `.clinerules/`         |
+| `cline`          | Cline             | `.clinerules/workflows/` |
-| `github-copilot` | GitHub Copilot    | `.github/copilot/`     |
+| `github-copilot` | GitHub Copilot    | `.github/copilot/`       |
-| `crush`          | Crush             | `.crush/`              |
+| `crush`          | Crush             | `.crush/`                |
-| `auggie`         | Auggie            | `.auggie/`             |
+| `auggie`         | Auggie            | `.auggie/`               |
-| `gemini`         | Google Gemini     | `.gemini/`             |
+| `gemini`         | Google Gemini     | `.gemini/`               |
-| `qwen`           | Qwen              | `.qwen/`               |
+| `qwen`           | Qwen              | `.qwen/`                 |
-| `roo`            | Roo               | `.roo/`                |
+| `roo`            | Roo               | `.roo/`                  |
-| `trae`           | Trae              | `.trae/`               |
+| `trae`           | Trae              | `.trae/`                 |
-| `iflow`          | iFlow             | `.iflow/`              |
+| `iflow`          | iFlow             | `.iflow/`                |
-| `kilo`           | Kilo              | `.kilo/`               |
+| `kilo`           | Kilo              | `.kilo/`                 |
 
 **Handler Architecture**:
 

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

@@ -1,46 +1,19 @@
 const path = require('node:path');
-const { BaseIdeSetup } = require('./_base-ide');
+const fs = require('fs-extra');
 const chalk = require('chalk');
-const inquirer = require('inquirer');
+const { BaseIdeSetup } = require('./_base-ide');
+const { WorkflowCommandGenerator } = require('./workflow-command-generator');
+const { getAgentsFromBmad, getTasksFromBmad } = require('./shared/bmad-artifacts');
 
 /**
  * Cline IDE setup handler
- * Creates rules in .clinerules directory with ordering support
+ * Installs BMAD artifacts to .clinerules/workflows with flattened naming
  */
 class ClineSetup extends BaseIdeSetup {
   constructor() {
-    super('cline', 'Cline');
+    super('cline', 'Cline', true); // preferred IDE
     this.configDir = '.clinerules';
-    this.defaultOrder = {
+    this.workflowsDir = 'workflows';
-      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 };
   }
 
   /**
@@ -52,249 +25,198 @@ class ClineSetup extends BaseIdeSetup {
   async setup(projectDir, bmadDir, options = {}) {
     console.log(chalk.cyan(`Setting up ${this.name}...`));
 
-    // Create .clinerules directory
+    // Create .clinerules/workflows directory
-    const clineRulesDir = path.join(projectDir, this.configDir);
+    const clineDir = path.join(projectDir, this.configDir);
-    await this.ensureDir(clineRulesDir);
+    const workflowsDir = path.join(clineDir, this.workflowsDir);
 
-    // Get agents and tasks
+    await this.ensureDir(workflowsDir);
-    const agents = await this.getAgents(bmadDir);
-    const tasks = await this.getTasks(bmadDir);
 
-    // Use pre-collected configuration if available
+    // Clear old BMAD files
-    const config = options.preCollectedConfig || {};
+    await this.clearOldBmadFiles(workflowsDir);
-    const orderingStrategy = config.ordering || options.ordering || 'module';
 
-    // Process agents as rules with ordering
+    // Collect all artifacts
-    let ruleCount = 0;
+    const { artifacts, counts } = await this.collectClineArtifacts(projectDir, bmadDir, options);
-    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);
 
-      // Use numeric prefix for ordering
+    // Write flattened files
-      const prefix = order.toString().padStart(2, '0');
+    const written = await this.flattenAndWriteArtifacts(artifacts, workflowsDir);
-      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(`  - ${ruleCount} rules created in ${path.relative(projectDir, clineRulesDir)}`));
+    console.log(chalk.dim(`  - ${counts.agents} agents installed`));
-    console.log(chalk.dim(`  - Ordering: ${orderingStrategy}`));
+    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)}`));
 
-    // Important message about toggle system
+    // Usage instructions
-    console.log(chalk.yellow('\n  ⚠️  IMPORTANT: Cline Toggle System'));
+    console.log(chalk.yellow('\n  ⚠️  How to Use Cline Workflows'));
-    console.log(chalk.cyan('  Rules are OFF by default to avoid context pollution'));
+    console.log(chalk.cyan('  BMAD workflows are available as slash commands in Cline'));
-    console.log(chalk.dim('  To use BMAD agents:'));
+    console.log(chalk.dim('  Usage:'));
-    console.log(chalk.dim('    1. Click rules icon below chat input'));
+    console.log(chalk.dim('    - Type / to see available commands'));
-    console.log(chalk.dim('    2. Toggle ON the specific agent you need'));
+    console.log(chalk.dim('    - All BMAD items start with "bmad-"'));
-    console.log(chalk.dim('    3. Type @{agent-name} to activate'));
+    console.log(chalk.dim('    - Example: /bmad-bmm-agents-pm'));
-    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,
-      rules: ruleCount,
+      agents: counts.agents,
-      ordering: orderingStrategy,
+      tasks: counts.tasks,
+      workflows: counts.workflows,
+      workflowLaunchers: counts.workflowLaunchers,
+      written,
     };
   }
 
   /**
-   * Ask user about rule ordering strategy
+   * Detect Cline installation by checking for .clinerules/workflows directory
    */
-  async askOrderingStrategy() {
+  async detect(projectDir) {
-    const response = await inquirer.prompt([
+    const workflowsDir = path.join(projectDir, this.configDir, this.workflowsDir);
-      {
-        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;
+    if (!(await fs.pathExists(workflowsDir))) {
+      return false;
+    }
+
+    const entries = await fs.readdir(workflowsDir);
+    return entries.some((entry) => entry.startsWith('bmad-'));
   }
 
   /**
-   * Get order number for an agent based on strategy
+   * Collect all artifacts for Cline export
    */
-  getOrder(agent, strategy) {
+  async collectClineArtifacts(projectDir, bmadDir, options = {}) {
-    switch (strategy) {
+    const selectedModules = options.selectedModules || [];
-      case 'module': {
+    const artifacts = [];
-        return this.defaultOrder[agent.module] || this.defaultOrder.other;
+
+    // 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,
+      },
+    };
+  }
+
+  /**
+   * Flatten file path to bmad-module-type-name.md format
+   */
+  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;
       }
 
-      case 'importance': {
+      const entryPath = path.join(destDir, entry);
-        // Prioritize certain agent types
+      const stat = await fs.stat(entryPath);
-        if (agent.name.includes('dev') || agent.name.includes('code')) return 10;
+      if (stat.isFile()) {
-        if (agent.name.includes('architect') || agent.name.includes('design')) return 15;
+        await fs.remove(entryPath);
-        if (agent.name.includes('test') || agent.name.includes('qa')) return 20;
+      } else if (stat.isDirectory()) {
-        if (agent.name.includes('doc') || agent.name.includes('write')) return 25;
+        await fs.remove(entryPath);
-        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;
       }
     }
   }
 
   /**
-   * Get order number for a task
+   * Read and process file with project-specific paths
    */
-  getTaskOrder(task, strategy) {
+  async readAndProcessWithProject(filePath, metadata, projectDir) {
-    // Tasks always come after agents
+    const content = await fs.readFile(filePath, 'utf8');
-    return this.getOrder(task, strategy) + 50;
+    return super.processContent(content, metadata, projectDir);
-  }
-
-  /**
-   * 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 fs = require('fs-extra');
+    const workflowsDir = path.join(projectDir, this.configDir, this.workflowsDir);
-    const clineRulesDir = path.join(projectDir, this.configDir);
+    await this.clearOldBmadFiles(workflowsDir);
+    console.log(chalk.dim(`Removed ${this.name} BMAD configuration`));
+  }
 
-    if (await fs.pathExists(clineRulesDir)) {
+  /**
-      // Remove all numbered BMAD rules
+   * Utility: Ensure directory exists
-      const files = await fs.readdir(clineRulesDir);
+   */
-      let removed = 0;
+  async ensureDir(dirPath) {
-
+    await fs.ensureDir(dirPath);
-      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,9 +27,12 @@ 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 { actionType } = await inquirer.prompt([
+      const promptResult = await inquirer.prompt([
         {
           type: 'list',
           name: 'actionType',
@@ -45,6 +48,9 @@ class UI {
         },
       ]);
 
+      // Extract actionType from prompt result
+      actionType = promptResult.actionType;
+
       // Handle quick update separately
       if (actionType === 'quick-update') {
         return {
@@ -69,15 +75,11 @@ class UI {
         };
       }
 
-      // Handle reinstall
+      // Handle reinstall - DON'T return early, let it flow through configuration collection
-      if (actionType === 'reinstall') {
+      // The installer will handle deletion when it sees actionType === 'reinstall'
-        return {
+      // For now, just note that we're in reinstall mode and continue below
-          actionType: 'reinstall',
-          directory: confirmedDirectory,
-        };
-      }
 
-      // If actionType === 'update', continue with normal flow below
+      // If actionType === 'update' or 'reinstall', continue with normal flow below
     }
 
     // Collect IDE tool selection EARLY (before module configuration)
@@ -94,7 +96,7 @@ class UI {
     CLIUtils.displayModuleComplete('core', false); // false = don't clear the screen again
 
     return {
-      actionType: 'update', // User chose to update/modify existing installation
+      actionType: actionType || 'update', // Preserve reinstall or update action
       directory: confirmedDirectory,
       installCore: true, // Always install core
       modules: selectedModules,