bmad-method 6.0.0-alpha.9 → 6.0.2

package/src/bmm/workflows/document-project/instructions.md

@@ -0,0 +1,130 @@
+# Document Project Workflow Router
+
+<critical>The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/document-project/workflow.yaml</critical>
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
+
+<step n="1" goal="Check for ability to resume and determine workflow mode">
+<action>Check for existing state file at: {project_knowledge}/project-scan-report.json</action>
+
+<check if="project-scan-report.json exists">
+  <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
+  <action>Extract cached project_type_id(s) from state file if present</action>
+  <action>Calculate age of state file (current time - last_updated)</action>
+
+<ask>I found an in-progress workflow state from {{last_updated}}.
+
+    **Current Progress:**
+
+    - Mode: {{mode}}
+    - Scan Level: {{scan_level}}
+    - Completed Steps: {{completed_steps_count}}/{{total_steps}}
+    - Last Step: {{current_step}}
+    - Project Type(s): {{cached_project_types}}
+
+    Would you like to:
+
+    1. **Resume from where we left off** - Continue from step {{current_step}}
+    2. **Start fresh** - Archive old state and begin new scan
+    3. **Cancel** - Exit without changes
+
+    Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set resume_mode = true</action>
+    <action>Set workflow_mode = {{mode}}</action>
+    <action>Load findings summaries from state file</action>
+    <action>Load cached project_type_id(s) from state file</action>
+
+    <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
+    <action>For each cached project_type_id, load ONLY the corresponding row from: {documentation_requirements_csv}</action>
+    <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
+    <action>Store loaded doc requirements for use in remaining steps</action>
+
+    <action>Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
+
+    <check if="workflow_mode == deep_dive">
+      <action>Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md with resume context</action>
+    </check>
+
+    <check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
+      <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md with resume context</action>
+    </check>
+
+  </check>
+
+  <check if="user selects 2">
+    <action>Create archive directory: {project_knowledge}/.archive/</action>
+    <action>Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display: "Exiting workflow without changes."</action>
+    <action>Exit workflow</action>
+  </check>
+
+  <check if="state file age >= 24 hours">
+    <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
+    <action>Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+</step>
+
+<step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">
+<action>Check if {project_knowledge}/index.md exists</action>
+
+<check if="index.md exists">
+  <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
+  <action>Store as {{existing_doc_date}}, {{existing_structure}}</action>
+
+<ask>I found existing documentation generated on {{existing_doc_date}}.
+
+What would you like to do?
+
+1. **Re-scan entire project** - Update all documentation with latest changes
+2. **Deep-dive into specific area** - Generate detailed documentation for a particular feature/module/folder
+3. **Cancel** - Keep existing documentation as-is
+
+Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set workflow_mode = "full_rescan"</action>
+    <action>Display: "Starting full project rescan..."</action>
+    <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 2">
+    <action>Set workflow_mode = "deep_dive"</action>
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Display: "Starting deep-dive documentation mode..."</action>
+    <action>Read fully and follow: {installed_path}/workflows/deep-dive-instructions.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="index.md does not exist">
+  <action>Set workflow_mode = "initial_scan"</action>
+  <action>Display: "No existing documentation found. Starting initial project scan..."</action>
+  <action>Read fully and follow: {installed_path}/workflows/full-scan-instructions.md</action>
+  <action>After sub-workflow completes, continue to Step 4</action>
+</check>
+
+</step>
+
+</workflow>

package/src/bmm/workflows/document-project/templates/project-scan-report-schema.json

@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Project Scan Report Schema",
+  "description": "State tracking file for document-project workflow resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow",
+      "example": "1.2.0"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed (if finished)"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level (deep_dive mode always uses exhaustive)"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "project_knowledge": {
+      "type": "string",
+      "description": "Absolute path to project knowledge folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier (e.g., 'step_1', 'step_2')"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only (detailed findings purged after writing)",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "description": "For deep/exhaustive scans: subfolders processed",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed (for deep_dive mode)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+# Document Project Workflow Configuration
+name: "document-project"
+version: "1.2.0"
+description: "Document brownfield projects for AI context. Use when the user says 'document this project' or 'generate project docs'"
+author: "BMad"
+
+# Critical variables
+config_source: "{project-root}/_bmad/bmm/config.yaml"
+project_knowledge: "{config_source}:project_knowledge"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Module path and component files
+installed_path: "{project-root}/_bmad/bmm/workflows/document-project"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Required data files - CRITICAL for project type detection and documentation requirements
+documentation_requirements_csv: "{installed_path}/documentation-requirements.csv"

package/src/bmm/workflows/document-project/workflows/deep-dive-instructions.md

@@ -0,0 +1,298 @@
+# Deep-Dive Documentation Instructions
+
+<workflow>
+
+<critical>This workflow performs exhaustive deep-dive documentation of specific areas</critical>
+<critical>Called by: ../document-project/instructions.md router</critical>
+<critical>Handles: deep_dive mode only</critical>
+
+<step n="13" goal="Deep-dive documentation of specific area" if="workflow_mode == deep_dive">
+<critical>Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.</critical>
+<action>Load existing project structure from index.md and project-parts.json (if exists)</action>
+<action>Load source tree analysis to understand available areas</action>
+
+<step n="13a" goal="Identify area for deep-dive">
+  <action>Analyze existing documentation to suggest deep-dive options</action>
+
+<ask>What area would you like to deep-dive into?
+
+**Suggested Areas Based on Project Structure:**
+
+{{#if has_api_routes}}
+
+## API Routes ({{api_route_count}} endpoints found)
+
+{{#each api_route_groups}}
+{{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_feature_modules}}
+
+## Feature Modules ({{feature_count}} features)
+
+{{#each feature_modules}}
+{{module_index}}. {{module_name}} - {{file_count}} files in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_ui_components}}
+
+### UI Component Areas
+
+{{#each component_groups}}
+{{group_index}}. {{group_name}} - {{component_count}} components in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_services}}
+
+### Services/Business Logic
+
+{{#each service_groups}}
+{{service_index}}. {{service_name}} - `{{path}}`
+{{/each}}
+{{/if}}
+
+**Or specify custom:**
+
+- Folder path (e.g., "client/src/features/dashboard")
+- File path (e.g., "server/src/api/users.ts")
+- Feature name (e.g., "authentication system")
+
+Enter your choice (number or custom path):
+</ask>
+
+<action>Parse user input to determine: - target_type: "folder" | "file" | "feature" | "api_group" | "component_group" - target_path: Absolute path to scan - target_name: Human-readable name for documentation - target_scope: List of all files to analyze
+</action>
+
+<action>Store as {{deep_dive_target}}</action>
+
+<action>Display confirmation:
+Target: {{target_name}}
+Type: {{target_type}}
+Path: {{target_path}}
+Estimated files to analyze: {{estimated_file_count}}
+
+This will read EVERY file in this area. Proceed? [y/n]
+</action>
+
+<action if="user confirms 'n'">Return to Step 13a (select different area)</action>
+</step>
+
+<step n="13b" goal="Comprehensive exhaustive scan of target area">
+  <action>Set scan_mode = "exhaustive"</action>
+  <action>Initialize file_inventory = []</action>
+  <critical>You must read every line of every file in scope and capture a plain-language explanation (what the file does, side effects, why it matters) that future developer agents can act on. No shortcuts.</critical>
+
+  <check if="target_type == folder">
+    <action>Get complete recursive file list from {{target_path}}</action>
+    <action>Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map</action>
+    <action>For EVERY remaining file in folder:
+      - Read complete file contents (all lines)
+      - Extract all exports (functions, classes, types, interfaces, constants)
+      - Extract all imports (dependencies)
+      - Identify purpose from comments and code structure
+      - Write 1-2 sentences (minimum) in natural language describing behaviour, side effects, assumptions, and anything a developer must know before modifying the file
+      - Extract function signatures with parameter types and return types
+      - Note any TODOs, FIXMEs, or comments
+      - Identify patterns (hooks, components, services, controllers, etc.)
+      - Capture per-file contributor guidance: `contributor_note`, `risks`, `verification_steps`, `suggested_tests`
+      - Store in file_inventory
+    </action>
+  </check>
+
+  <check if="target_type == file">
+    <action>Read complete file at {{target_path}}</action>
+    <action>Extract all information as above</action>
+    <action>Read all files it imports (follow import chain 1 level deep)</action>
+    <action>Find all files that import this file (dependents via grep)</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == api_group">
+    <action>Identify all route/controller files in API group</action>
+    <action>Read all route handlers completely</action>
+    <action>Read associated middleware, controllers, services</action>
+    <action>Read data models and schemas used</action>
+    <action>Extract complete request/response schemas</action>
+    <action>Document authentication and authorization requirements</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == feature">
+    <action>Search codebase for all files related to feature name</action>
+    <action>Include: UI components, API endpoints, models, services, tests</action>
+    <action>Read each file completely</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == component_group">
+    <action>Get all component files in group</action>
+    <action>Read each component completely</action>
+    <action>Extract: Props interfaces, hooks used, child components, state management</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+<action>For each file in file\*inventory, document: - **File Path:** Full path - **Purpose:** What this file does (1-2 sentences) - **Lines of Code:** Total LOC - **Exports:** Complete list with signatures
+
+- Functions: `functionName(param: Type): ReturnType` - Description
+  - Classes: `ClassName` - Description with key methods
+  - Types/Interfaces: `TypeName` - Description
+  - Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
+    </action>
+
+<template-output>comprehensive_file_inventory</template-output>
+</step>
+
+<step n="13c" goal="Analyze relationships and data flow">
+  <action>Build dependency graph for scanned area:
+    - Create graph with files as nodes
+    - Add edges for import relationships
+    - Identify circular dependencies if any
+    - Find entry points (files not imported by others in scope)
+    - Find leaf nodes (files that don't import others in scope)
+  </action>
+
+<action>Trace data flow through the system: - Follow function calls and data transformations - Track API calls and their responses - Document state updates and propagation - Map database queries and mutations
+</action>
+
+<action>Identify integration points: - External APIs consumed - Internal APIs/services called - Shared state accessed - Events published/subscribed - Database tables accessed
+</action>
+
+<template-output>dependency_graph</template-output>
+<template-output>data_flow_analysis</template-output>
+<template-output>integration_points</template-output>
+</step>
+
+<step n="13d" goal="Find related code and similar patterns">
+  <action>Search codebase OUTSIDE scanned area for:
+    - Similar file/folder naming patterns
+    - Similar function signatures
+    - Similar component structures
+    - Similar API patterns
+    - Reusable utilities that could be used
+  </action>
+
+<action>Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply
+</action>
+
+<action>Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere
+</action>
+
+<template-output>related_code_references</template-output>
+<template-output>reuse_opportunities</template-output>
+</step>
+
+<step n="13e" goal="Generate comprehensive deep-dive documentation">
+  <action>Create documentation filename: deep-dive-{{sanitized_target_name}}.md</action>
+  <action>Aggregate contributor insights across files:
+    - Combine unique risk/gotcha notes into {{risks_notes}}
+    - Combine verification steps developers should run before changes into {{verification_steps}}
+    - Combine recommended test commands into {{suggested_tests}}
+  </action>
+
+<action>Load complete deep-dive template from: {installed_path}/templates/deep-dive-template.md</action>
+<action>Fill template with all collected data from steps 13b-13d</action>
+<action>Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md</action>
+<action>Validate deep-dive document completeness</action>
+
+<template-output>deep_dive_documentation</template-output>
+
+<action>Update state file: - Add to deep_dive_targets array: {"target_name": "{{target_name}}", "target_path": "{{target_path}}", "files_analyzed": {{file_count}}, "output_file": "deep-dive-{{sanitized_target_name}}.md", "timestamp": "{{now}}"} - Add output to outputs_generated - Update last_updated timestamp
+</action>
+</step>
+
+<step n="13f" goal="Update master index with deep-dive link">
+  <action>Read existing index.md</action>
+
+<action>Check if "Deep-Dive Documentation" section exists</action>
+
+  <check if="section does not exist">
+    <action>Add new section after "Generated Documentation":
+
+## Deep-Dive Documentation
+
+Detailed exhaustive analysis of specific areas:
+
+    </action>
+
+  </check>
+
+<action>Add link to new deep-dive doc:
+
+- [{{target_name}} Deep-Dive](./deep-dive-{{sanitized_target_name}}.md) - Comprehensive analysis of {{target_description}} ({{file_count}} files, {{total_loc}} LOC) - Generated {{date}}
+  </action>
+
+  <action>Update index metadata:
+  Last Updated: {{date}}
+  Deep-Dives: {{deep_dive_count}}
+  </action>
+
+  <action>Save updated index.md</action>
+
+  <template-output>updated_index</template-output>
+  </step>
+
+<step n="13g" goal="Offer to continue or complete">
+  <action>Display summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Deep-Dive Documentation Complete! ✓
+
+**Generated:** {project_knowledge}/deep-dive-{{target_name}}.md
+**Files Analyzed:** {{file_count}}
+**Lines of Code Scanned:** {{total_loc}}
+**Time Taken:** ~{{duration}}
+
+**Documentation Includes:**
+
+- Complete file inventory with all exports
+- Dependency graph and data flow
+- Integration points and API contracts
+- Testing analysis and coverage
+- Related code and reuse opportunities
+- Implementation guidance
+
+**Index Updated:** {project_knowledge}/index.md now includes link to this deep-dive
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<ask>Would you like to:
+
+1. **Deep-dive another area** - Analyze another feature/module/folder
+2. **Finish** - Complete workflow
+
+Your choice [1/2]:
+</ask>
+
+  <action if="user selects 1">
+    <action>Clear current deep_dive_target</action>
+    <action>Go to Step 13a (select new area)</action>
+  </action>
+
+  <action if="user selects 2">
+    <action>Display final message:
+
+All deep-dive documentation complete!
+
+**Master Index:** {project_knowledge}/index.md
+**Deep-Dives Generated:** {{deep_dive_count}}
+
+These comprehensive docs are now ready for:
+
+- Architecture review
+- Implementation planning
+- Code understanding
+- Brownfield PRD creation
+
+Thank you for using the document-project workflow!
+</action>
+<action>Exit workflow</action>
+</action>
+</step>
+</step>
+
+</workflow>

package/src/bmm/workflows/document-project/workflows/deep-dive.yaml

@@ -0,0 +1,31 @@
+# Deep-Dive Documentation Workflow Configuration
+name: "document-project-deep-dive"
+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"
+
+# Critical variables inherited from parent
+config_source: "{project-root}/_bmad/bmb/config.yaml"
+project_knowledge: "{config_source}:project_knowledge"
+user_name: "{config_source}:user_name"
+date: system-generated
+
+# Module path and component files
+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/document-project/checklist.md"
+
+# Templates
+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"
+scan_level: "exhaustive" # Deep-dive always uses exhaustive scan
+project_root_path: ""
+existing_index_path: "" # Path to existing index.md
+
+# Configuration
+autonomous: false # Requires user input to select target area