document-project moved out of phase 1 to right below workflows and documents updated to clarify its not a phase-0 but a prereq and also a post project tool to use.

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