Bmad Document Project

Document Project Workflow

Goal: Document brownfield projects for AI context.

Your Role: Project documentation specialist.

Conventions

• Bare paths (e.g. instructions.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. {skill-root}/customize.toml — defaults 2. {project-root}/_bmad/custom/{skill-name}.toml — team overrides 3. {project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

• Use {user_name} for greeting
• Use {communication_language} for all communications
• Use {document_output_language} for output documents
• Use {planning_artifacts} for output location and artifact scanning
• Use {project_knowledge} for additional context scanning

Step 5: Greet the User

Greet {user_name} (if you have not already), speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. If activation_steps_prepend or activation_steps_append were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

Execution

Read fully and follow: ./instructions.md

Document Project Workflow - Validation Checklist

Scan Level and Resumability

• [ ] Scan level selection offered (quick/deep/exhaustive) for initial_scan and full_rescan modes
• [ ] Deep-dive mode automatically uses exhaustive scan (no choice given)
• [ ] Quick scan does NOT read source files (only patterns, configs, manifests)
• [ ] Deep scan reads files in critical directories per project type
• [ ] Exhaustive scan reads ALL source files (excluding node_modules, dist, build)
• [ ] State file (project-scan-report.json) created at workflow start
• [ ] State file updated after each step completion
• [ ] State file contains all required fields per schema
• [ ] Resumability prompt shown if state file exists and is <24 hours old
• [ ] Old state files (>24 hours) automatically archived
• [ ] Resume functionality loads previous state correctly
• [ ] Workflow can jump to correct step when resuming

Write-as-you-go Architecture

• [ ] Each document written to disk IMMEDIATELY after generation
• [ ] Document validation performed right after writing (section-level)
• [ ] State file updated after each document is written
• [ ] Detailed findings purged from context after writing (only summaries kept)
• [ ] Context contains only high-level summaries (1-2 sentences per section)
• [ ] No accumulation of full project analysis in memory

Batching Strategy (Deep/Exhaustive Scans)

• [ ] Batching applied for deep and exhaustive scan levels
• [ ] Batches organized by SUBFOLDER (not arbitrary file count)
• [ ] Large files (>5000 LOC) handled with appropriate judgment
• [ ] Each batch: read files, extract info, write output, validate, purge context
• [ ] Batch completion tracked in state file (batches_completed array)
• [ ] Batch summaries kept in context (1-2 sentences max)

Project Detection and Classification

• [ ] Project type correctly identified and matches actual technology stack
• [ ] Multi-part vs single-part structure accurately detected
• [ ] All project parts identified if multi-part (no missing client/server/etc.)
• [ ] Documentation requirements loaded for each part type
• [ ] Architecture registry match is appropriate for detected stack

Technology Stack Analysis

• [ ] All major technologies identified (framework, language, database, etc.)
• [ ] Versions captured where available
• [ ] Technology decision table is complete and accurate
• [ ] Dependencies and libraries documented
• [ ] Build tools and package managers identified

Codebase Scanning Completeness

• [ ] All critical directories scanned based on project type
• [ ] API endpoints documented (if requires_api_scan = true)
• [ ] Data models captured (if requires_data_models = true)
• [ ] State management patterns identified (if requires_state_management = true)
• [ ] UI components inventoried (if requires_ui_components = true)
• [ ] Configuration files located and documented
• [ ] Authentication/security patterns identified
• [ ] Entry points correctly identified
• [ ] Integration points mapped (for multi-part projects)
• [ ] Test files and patterns documented

Source Tree Analysis

• [ ] Complete directory tree generated with no major omissions
• [ ] Critical folders highlighted and described
• [ ] Entry points clearly marked
• [ ] Integration paths noted (for multi-part)
• [ ] Asset locations identified (if applicable)
• [ ] File organization patterns explained

Architecture Documentation Quality

• [ ] Architecture document uses appropriate template from registry
• [ ] All template sections filled with relevant information (no placeholders)
• [ ] Technology stack section is comprehensive
• [ ] Architecture pattern clearly explained
• [ ] Data architecture documented (if applicable)
• [ ] API design documented (if applicable)
• [ ] Component structure explained (if applicable)
• [ ] Source tree included and annotated
• [ ] Testing strategy documented
• [ ] Deployment architecture captured (if config found)

Development and Operations Documentation

• [ ] Prerequisites clearly listed
• [ ] Installation steps documented
• [ ] Environment setup instructions provided
• [ ] Local run commands specified
• [ ] Build process documented
• [ ] Test commands and approach explained
• [ ] Deployment process documented (if applicable)
• [ ] CI/CD pipeline details captured (if found)
• [ ] Contribution guidelines extracted (if found)

Multi-Part Project Specific (if applicable)

• [ ] Each part documented separately
• [ ] Part-specific architecture files created (architecture-{part_id}.md)
• [ ] Part-specific component inventories created (if applicable)
• [ ] Part-specific development guides created
• [ ] Integration architecture document created
• [ ] Integration points clearly defined with type and details
• [ ] Data flow between parts explained
• [ ] project-parts.json metadata file created

Index and Navigation

• [ ] index.md created as master entry point
• [ ] Project structure clearly summarized in index
• [ ] Quick reference section complete and accurate
• [ ] All generated docs linked from index
• [ ] All existing docs linked from index (if found)
• [ ] Getting started section provides clear next steps
• [ ] AI-assisted development guidance included
• [ ] Navigation structure matches project complexity (simple for single-part, detailed for multi-part)

File Completeness

• [ ] index.md generated
• [ ] project-overview.md generated
• [ ] source-tree-analysis.md generated
• [ ] architecture.md (or per-part) generated
• [ ] component-inventory.md (or per-part) generated if UI components exist
• [ ] development-guide.md (or per-part) generated
• [ ] api-contracts.md (or per-part) generated if APIs documented
• [ ] data-models.md (or per-part) generated if data models found
• [ ] deployment-guide.md generated if deployment config found
• [ ] contribution-guide.md generated if guidelines found
• [ ] integration-architecture.md generated if multi-part
• [ ] project-parts.json generated if multi-part

Content Quality

• [ ] Technical information is accurate and specific
• [ ] No generic placeholders or "TODO" items remain
• [ ] Examples and code snippets are relevant to actual project
• [ ] File paths and directory references are correct
• [ ] Technology names and versions are accurate
• [ ] Terminology is consistent across all documents
• [ ] Descriptions are clear and actionable

Brownfield PRD Readiness

• [ ] Documentation provides enough context for AI to understand existing system
• [ ] Integration points are clear for planning new features
• [ ] Reusable components are identified for leveraging in new work
• [ ] Data models are documented for schema extension planning
• [ ] API contracts are documented for endpoint expansion
• [ ] Code conventions and patterns are captured for consistency
• [ ] Architecture constraints are clear for informed decision-making

Output Validation

• [ ] All files saved to correct output folder
• [ ] File naming follows convention (no part suffix for single-part, with suffix for multi-part)
• [ ] No broken internal links between documents
• [ ] Markdown formatting is correct and renders properly
• [ ] JSON files are valid (project-parts.json if applicable)

Final Validation

• [ ] User confirmed project classification is accurate
• [ ] User provided any additional context needed
• [ ] All requested areas of focus addressed
• [ ] Documentation is immediately usable for brownfield PRD workflow
• [ ] No critical information gaps identified

Issues Found

Critical Issues (must fix before completion)

-

Minor Issues (can be addressed later)

-

Missing Information (to note for user)

-

Deep-Dive Mode Validation (if deep-dive was performed)

• [ ] Deep-dive target area correctly identified and scoped
• [ ] All files in target area read completely (no skipped files)
• [ ] File inventory includes all exports with complete signatures
• [ ] Dependencies mapped for all files
• [ ] Dependents identified (who imports each file)
• [ ] Code snippets included for key implementation details
• [ ] Patterns and design approaches documented
• [ ] State management strategy explained
• [ ] Side effects documented (API calls, DB queries, etc.)
• [ ] Error handling approaches captured
• [ ] Testing files and coverage documented
• [ ] TODOs and comments extracted
• [ ] Dependency graph created showing relationships
• [ ] Data flow traced through the scanned area
• [ ] Integration points with rest of codebase identified
• [ ] Related code and similar patterns found outside scanned area
• [ ] Reuse opportunities documented
• [ ] Implementation guidance provided
• [ ] Modification instructions clear
• [ ] Index.md updated with deep-dive link
• [ ] Deep-dive documentation is immediately useful for implementation

---

State File Quality

• [ ] State file is valid JSON (no syntax errors)
• [ ] State file is optimized (no pretty-printing, minimal whitespace)
• [ ] State file contains all completed steps with timestamps
• [ ] State file outputs_generated list is accurate and complete
• [ ] State file resume_instructions are clear and actionable
• [ ] State file findings contain only high-level summaries (not detailed data)
• [ ] State file can be successfully loaded for resumption

Completion Criteria

All items in the following sections must be checked:

• ✓ Scan Level and Resumability
• ✓ Write-as-you-go Architecture
• ✓ Batching Strategy (if deep/exhaustive scan)
• ✓ Project Detection and Classification
• ✓ Technology Stack Analysis
• ✓ Architecture Documentation Quality
• ✓ Index and Navigation
• ✓ File Completeness
• ✓ Brownfield PRD Readiness
• ✓ State File Quality
• ✓ Deep-Dive Mode Validation (if applicable)

The workflow is complete when:

1. All critical checklist items are satisfied 2. No critical issues remain 3. User has reviewed and approved the documentation 4. Generated docs are ready for use in brownfield PRD workflow 5. Deep-dive docs (if any) are comprehensive and implementation-ready 6. State file is valid and can enable resumption if interrupted

Document Project Workflow Router

<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: ./workflows/deep-dive-workflow.md with resume context</action> </check>

<check if="workflow_mode == initial_scan OR workflow_mode == full_rescan"> <action>Read fully and follow: ./workflows/full-scan-workflow.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: ./workflows/full-scan-workflow.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: ./workflows/deep-dive-workflow.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: ./workflows/full-scan-workflow.md</action> <action>After sub-workflow completes, continue to Step 4</action> </check>

</step>

</workflow>

{{target_name}} - Deep Dive Documentation

Generated: {{date}} Scope: {{target_path}} Files Analyzed: {{file_count}} Lines of Code: {{total_loc}} Workflow Mode: Exhaustive Deep-Dive

Overview

{{target_description}}

Purpose: {{target_purpose}} Key Responsibilities: {{responsibilities}} Integration Points: {{integration_summary}}

Complete File Inventory

{{#each files_in_inventory}}

{{file_path}}

Purpose: {{purpose}} Lines of Code: {{loc}} File Type: {{file_type}}

What Future Contributors Must Know: {{contributor_note}}

Exports: {{#each exports}}

• {{signature}} - {{description}}

{{/each}}

Dependencies: {{#each imports}}

• {{import_path}} - {{reason}}

{{/each}}

Used By: {{#each dependents}}

• {{dependent_path}}

{{/each}}

Key Implementation Details:

```{{language}} {{key_code_snippet}}

{{implementation_notes}}

**Patterns Used:**
{{#each patterns}}

- {{pattern_name}}: {{pattern_description}}
  {{/each}}

**State Management:** {{state_approach}}

**Side Effects:**
{{#each side_effects}}

- {{effect_type}}: {{effect_description}}
  {{/each}}

**Error Handling:** {{error_handling_approach}}

**Testing:**

- Test File: {{test_file_path}}
- Coverage: {{coverage_percentage}}%
- Test Approach: {{test_approach}}

**Comments/TODOs:**
{{#each todos}}

- Line {{line_number}}: {{todo_text}}
  {{/each}}

---

{{/each}}

## Contributor Checklist

- **Risks & Gotchas:** {{risks_notes}}
- **Pre-change Verification Steps:** {{verification_steps}}
- **Suggested Tests Before PR:** {{suggested_tests}}

## Architecture & Design Patterns

### Code Organization

{{organization_approach}}

### Design Patterns

{{#each design_patterns}}

- **{{pattern_name}}**: {{usage_description}}
  {{/each}}

### State Management Strategy

{{state_management_details}}

### Error Handling Philosophy

{{error_handling_philosophy}}

### Testing Strategy

{{testing_strategy}}

## Data Flow

{{data_flow_diagram}}

### Data Entry Points

{{#each entry_points}}

- **{{entry_name}}**: {{entry_description}}
  {{/each}}

### Data Transformations

{{#each transformations}}

- **{{transformation_name}}**: {{transformation_description}}
  {{/each}}

### Data Exit Points

{{#each exit_points}}

- **{{exit_name}}**: {{exit_description}}
  {{/each}}

## Integration Points

### APIs Consumed

{{#each apis_consumed}}

- **{{api_endpoint}}**: {{api_description}}
  - Method: {{method}}
  - Authentication: {{auth_requirement}}
  - Response: {{response_schema}}
    {{/each}}

### APIs Exposed

{{#each apis_exposed}}

- **{{api_endpoint}}**: {{api_description}}
  - Method: {{method}}
  - Request: {{request_schema}}
  - Response: {{response_schema}}
    {{/each}}

### Shared State

{{#each shared_state}}

- **{{state_name}}**: {{state_description}}
  - Type: {{state_type}}
  - Accessed By: {{accessors}}
    {{/each}}

### Events

{{#each events}}

- **{{event_name}}**: {{event_description}}
  - Type: {{publish_or_subscribe}}
  - Payload: {{payload_schema}}
    {{/each}}

### Database Access

{{#each database_operations}}

- **{{table_name}}**: {{operation_type}}
  - Queries: {{query_patterns}}
  - Indexes Used: {{indexes}}
    {{/each}}

## Dependency Graph

{{dependency_graph_visualization}}

### Entry Points (Not Imported by Others in Scope)

{{#each entry_point_files}}

- {{file_path}}
  {{/each}}

### Leaf Nodes (Don't Import Others in Scope)

{{#each leaf_files}}

- {{file_path}}
  {{/each}}

### Circular Dependencies

{{#if has_circular_dependencies}}
⚠️ Circular dependencies detected:
{{#each circular_deps}}

- {{cycle_description}}
  {{/each}}
  {{else}}
  ✓ No circular dependencies detected
  {{/if}}

## Testing Analysis

### Test Coverage Summary

- **Statements:** {{statements_coverage}}%
- **Branches:** {{branches_coverage}}%
- **Functions:** {{functions_coverage}}%
- **Lines:** {{lines_coverage}}%

### Test Files

{{#each test_files}}

- **{{test_file_path}}**
  - Tests: {{test_count}}
  - Approach: {{test_approach}}
  - Mocking Strategy: {{mocking_strategy}}
    {{/each}}

### Test Utilities Available

{{#each test_utilities}}

- `{{utility_name}}`: {{utility_description}}
  {{/each}}

### Testing Gaps

{{#each testing_gaps}}

- {{gap_description}}
  {{/each}}

## Related Code & Reuse Opportunities

### Similar Features Elsewhere

{{#each similar_features}}

- **{{feature_name}}** (`{{feature_path}}`)
  - Similarity: {{similarity_description}}
  - Can Reference For: {{reference_use_case}}
    {{/each}}

### Reusable Utilities Available

{{#each reusable_utilities}}

- **{{utility_name}}** (`{{utility_path}}`)
  - Purpose: {{utility_purpose}}
  - How to Use: {{usage_example}}
    {{/each}}

### Patterns to Follow

{{#each patterns_to_follow}}

- **{{pattern_name}}**: Reference `{{reference_file}}` for implementation
  {{/each}}

## Implementation Notes

### Code Quality Observations

{{#each quality_observations}}

- {{observation}}
  {{/each}}

### TODOs and Future Work

{{#each all_todos}}

- **{{file_path}}:{{line_number}}**: {{todo_text}}
  {{/each}}

### Known Issues

{{#each known_issues}}

- {{issue_description}}
  {{/each}}

### Optimization Opportunities

{{#each optimizations}}

- {{optimization_suggestion}}
  {{/each}}

### Technical Debt

{{#each tech_debt_items}}

- {{debt_description}}
  {{/each}}

## Modification Guidance

### To Add New Functionality

{{modification_guidance_add}}

### To Modify Existing Functionality

{{modification_guidance_modify}}

### To Remove/Deprecate

{{modification_guidance_remove}}

### Testing Checklist for Changes

{{#each testing_checklist_items}}

- [ ] {{checklist_item}}
      {{/each}}

---

_Generated by `document-project` workflow (deep-dive mode)_
_Base Documentation: docs/index.md_
_Scan Date: {{date}}_
_Analysis Mode: Exhaustive_

{{project_name}} Documentation Index

Type: {{repository_type}}{{#if is_multi_part}} with {{parts_count}} parts{{/if}} Primary Language: {{primary_language}} Architecture: {{architecture_type}} Last Updated: {{date}}

Project Overview

{{project_description}}

{{#if is_multi_part}}

Project Structure

This project consists of {{parts_count}} parts:

{{#each project_parts}}

{{part_name}} ({{part_id}})

• Type: {{project_type}}
• Location: {{root_path}}
• Tech Stack: {{tech_stack_summary}}
• Entry Point: {{entry_point}}

{{/each}}

Cross-Part Integration

{{integration_summary}}

{{/if}}

Quick Reference

{{#if is_single_part}}

• Tech Stack: {{tech_stack_summary}}
• Entry Point: {{entry_point}}
• Architecture Pattern: {{architecture_pattern}}
• Database: {{database}}
• Deployment: {{deployment_platform}}

{{else}} {{#each project_parts}}

{{part_name}} Quick Ref

• Stack: {{tech_stack_summary}}
• Entry: {{entry_point}}
• Pattern: {{architecture_pattern}}

{{/each}} {{/if}}

Generated Documentation

Core Documentation

• Project Overview - Executive summary and high-level architecture
• Source Tree Analysis - Annotated directory structure

{{#if is_single_part}}

• Architecture - Detailed technical architecture
• Component Inventory - Catalog of major components{{#if has_ui_components}} and UI elements{{/if}}
• Development Guide - Local setup and development workflow

{{#if has_api_docs}}- API Contracts - API endpoints and schemas{{/if}} {{#if has_data_models}}- Data Models - Database schema and models{{/if}} {{else}}

Part-Specific Documentation

{{#each project_parts}}

{{part_name}} ({{part_id}})

• Architecture - Technical architecture for {{part_name}}

{{#if has_components}}- Components - Component catalog{{/if}}

• Development Guide - Setup and dev workflow

{{#if has_api}}- API Contracts - API documentation{{/if}} {{#if has_data}}- Data Models - Data architecture{{/if}} {{/each}}

Integration

• Integration Architecture - How parts communicate
• Project Parts Metadata - Machine-readable structure

{{/if}}

Optional Documentation

{{#if has_deployment_guide}}- Deployment Guide - Deployment process and infrastructure{{/if}} {{#if has_contribution_guide}}- Contribution Guide - Contributing guidelines and standards{{/if}}

Existing Documentation

{{#if has_existing_docs}} {{#each existing_docs}}

• {{title}} - {{description}}

{{/each}} {{else}} No existing documentation files were found in the project. {{/if}}

Getting Started

{{#if is_single_part}}

Prerequisites

{{prerequisites}}

Setup

{{setup_commands}}

Run Locally

{{run_commands}}

Run Tests

{{test_commands}}

{{else}} {{#each project_parts}}

{{part_name}} Setup

Prerequisites: {{prerequisites}}

Install & Run:

cd {{root_path}}
{{setup_command}}
{{run_command}}

{{/each}} {{/if}}

For AI-Assisted Development

This documentation was generated specifically to enable AI agents to understand and extend this codebase.

When Planning New Features:

UI-only features: {{#if is_multi_part}}→ Reference: architecture-{{ui_part_id}}.md, component-inventory-{{ui_part_id}}.md{{else}}→ Reference: architecture.md, component-inventory.md{{/if}}

API/Backend features: {{#if is_multi_part}}→ Reference: architecture-{{api_part_id}}.md, api-contracts-{{api_part_id}}.md, data-models-{{api_part_id}}.md{{else}}→ Reference: architecture.md{{#if has_api_docs}}, api-contracts.md{{/if}}{{#if has_data_models}}, data-models.md{{/if}}{{/if}}

Full-stack features: → Reference: All architecture docs{{#if is_multi_part}} + integration-architecture.md{{/if}}

Deployment changes: {{#if has_deployment_guide}}→ Reference: deployment-guide.md{{else}}→ Review CI/CD configs in project{{/if}}

---

_Documentation generated by BMAD Method document-project workflow_

{{project_name}} - Project Overview

Date: {{date}} Type: {{project_type}} Architecture: {{architecture_type}}

Executive Summary

{{executive_summary}}

Project Classification

• Repository Type: {{repository_type}}
• Project Type(s): {{project_types_list}}
• Primary Language(s): {{primary_languages}}
• Architecture Pattern: {{architecture_pattern}}

{{#if is_multi_part}}

Multi-Part Structure

This project consists of {{parts_count}} distinct parts:

{{#each project_parts}}

{{part_name}}

• Type: {{project_type}}
• Location: {{root_path}}
• Purpose: {{purpose}}
• Tech Stack: {{tech_stack}}

{{/each}}

How Parts Integrate

{{integration_description}} {{/if}}

Technology Stack Summary

{{#if is_single_part}} {{technology_table}} {{else}} {{#each project_parts}}

{{part_name}} Stack

{{technology_table}} {{/each}} {{/if}}

Key Features

{{key_features}}

Architecture Highlights

{{architecture_highlights}}

Development Overview

Prerequisites

{{prerequisites}}

Getting Started

{{getting_started_summary}}

Key Commands

{{#if is_single_part}}

• Install: {{install_command}}
• Dev: {{dev_command}}
• Build: {{build_command}}
• Test: {{test_command}}

{{else}} {{#each project_parts}}

{{part_name}}

• Install: {{install_command}}
• Dev: {{dev_command}}

{{/each}} {{/if}}

Repository Structure

{{repository_structure_summary}}

Documentation Map

For detailed information, see:

• index.md - Master documentation index
• [architecture.md](./architecture{{#if is_multi_part}}-{part_id}{{/if}}.md) - Detailed architecture
• source-tree-analysis.md - Directory structure
• [development-guide.md](./development-guide{{#if is_multi_part}}-{part_id}{{/if}}.md) - Development workflow

---

_Generated using BMAD Method document-project workflow_

{{project_name}} - Source Tree Analysis

Date: {{date}}

Overview

{{source_tree_overview}}

{{#if is_multi_part}}

Multi-Part Structure

This project is organized into {{parts_count}} distinct parts:

{{#each project_parts}}

• {{part_name}} ({{root_path}}): {{purpose}}

{{/each}} {{/if}}

Complete Directory Structure

{{complete_source_tree}}

Critical Directories

{{#each critical_folders}}

{{folder_path}}

{{description}}

Purpose: {{purpose}} Contains: {{contents_summary}} {{#if entry_points}}Entry Points: {{entry_points}}{{/if}} {{#if integration_note}}Integration: {{integration_note}}{{/if}}

{{/each}}

{{#if is_multi_part}}

Part-Specific Trees

{{#each project_parts}}

{{part_name}} Structure

{{source_tree}}

Key Directories: {{#each critical_directories}}

• `{{path}}`: {{description}}

{{/each}}

{{/each}}

Integration Points

{{#each integration_points}}

{{from_part}} → {{to_part}}

• Location: {{integration_path}}
• Type: {{integration_type}}
• Details: {{details}}

{{/each}}

{{/if}}

Entry Points

{{#if is_single_part}}

• Main Entry: {{main_entry_point}}

{{#if additional_entry_points}}

• Additional:

{{#each additional_entry_points}}

• {{path}}: {{description}}

{{/each}} {{/if}} {{else}} {{#each project_parts}}

{{part_name}}

• Entry Point: {{entry_point}}
• Bootstrap: {{bootstrap_description}}

{{/each}} {{/if}}

File Organization Patterns

{{file_organization_patterns}}

Key File Types

{{#each file_type_patterns}}

{{file_type}}

• Pattern: {{pattern}}
• Purpose: {{purpose}}
• Examples: {{examples}}

{{/each}}

Asset Locations

{{#if has_assets}} {{#each asset_locations}}

• {{asset_type}}: {{location}} ({{file_count}} files, {{total_size}})

{{/each}} {{else}} No significant assets detected. {{/if}}

Configuration Files

{{#each config_files}}

• `{{path}}`: {{description}}

{{/each}}

Notes for Development

{{development_notes}}

---

_Generated using BMAD Method document-project workflow_

Deep-Dive Documentation Instructions

<workflow>

<critical>This workflow performs exhaustive deep-dive documentation of specific areas</critical> <critical>Handles: deep_dive mode only</critical> <critical>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured {communication_language}</critical> <critical>YOU MUST ALWAYS WRITE all artifact and document content in {document_output_language}</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: ../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 - 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>Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action> <action>Exit workflow</action> </action> </step> </step>

</workflow>

Deep-Dive Documentation Sub-Workflow

Goal: Exhaustive deep-dive documentation of specific project areas.

Your Role: Deep-dive documentation specialist.

• Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.

---

INITIALIZATION

Configuration Loading

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

• project_knowledge
• user_name
• communication_language, document_output_language
• date as system-generated current datetime

✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured {communication_language}. ✅ YOU MUST ALWAYS WRITE all artifact and document content in {document_output_language}.

Runtime Inputs

• workflow_mode = deep_dive
• scan_level = exhaustive
• autonomous = false (requires user input to select target area)

---

EXECUTION

Read fully and follow: ./deep-dive-instructions.md

Full Project Scan Instructions

<workflow>

<critical>This workflow performs complete project documentation (Steps 1-12)</critical> <critical>Handles: initial_scan and full_rescan modes</critical> <critical>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured {communication_language}</critical> <critical>YOU MUST ALWAYS WRITE all artifact and document content in {document_output_language}</critical>

<step n="0.5" goal="Load documentation requirements data for fresh starts (not needed for resume)" if="resume_mode == false"> <critical>DATA LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>

<action>Display explanation to user:

How Project Type Detection Works:

This workflow uses a single comprehensive CSV file to intelligently document your project:

documentation-requirements.csv (../documentation-requirements.csv)

• Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
• 24-column schema combining project type detection AND documentation requirements
• Detection columns: project_type_id, key_file_patterns (used to identify project type from codebase)
• Requirement columns: requires_api_scan, requires_data_models, requires_ui_components, etc.
• Pattern columns: critical_directories, test_file_patterns, config_patterns, etc.
• Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
• Example: For project_type_id="web", key_file_patterns includes "package.json;tsconfig.json;\*.config.js" and requires_api_scan=true

When Documentation Requirements are Loaded:

• Fresh Start (initial_scan): Load all 12 rows → detect type using key_file_patterns → use that row's requirements
• Resume: Load ONLY the doc requirements row(s) for cached project_type_id(s)
• Full Rescan: Same as fresh start (may re-detect project type)
• Deep Dive: Load ONLY doc requirements for the part being deep-dived

</action>

<action>Now loading documentation requirements data for fresh start...</action>

<action>Load documentation-requirements.csv from: ../documentation-requirements.csv</action> <action>Store all 12 rows indexed by project_type_id for project detection and requirements lookup</action> <action>Display: "Loaded documentation requirements for 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)"</action>

<action>Display: "✓ Documentation requirements loaded successfully. Ready to begin project analysis."</action> </step>

<step n="0.6" goal="Check for existing documentation and determine workflow mode"> <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>Continue to scan level selection below</action> </check>

<check if="user selects 2"> <action>Set workflow_mode = "deep_dive"</action> <action>Set scan_level = "exhaustive"</action> <action>Initialize state file with mode=deep_dive, scan_level=exhaustive</action> <action>Jump to Step 13</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>Continue to scan level selection below</action> </check>

<action if="workflow_mode != deep_dive">Select Scan Level</action>

<check if="workflow_mode == initial_scan OR workflow_mode == full_rescan"> <ask>Choose your scan depth level:

1. Quick Scan (2-5 minutes) [DEFAULT]

• Pattern-based analysis without reading source files
• Scans: Config files, package manifests, directory structure
• Best for: Quick project overview, initial understanding
• File reading: Minimal (configs, README, package.json, etc.)

2. Deep Scan (10-30 minutes)

• Reads files in critical directories based on project type
• Scans: All critical paths from documentation requirements
• Best for: Comprehensive documentation for brownfield PRD
• File reading: Selective (key files in critical directories)

3. Exhaustive Scan (30-120 minutes)

• Reads ALL source files in project
• Scans: Every source file (excludes node_modules, dist, build)
• Best for: Complete analysis, migration planning, detailed audit
• File reading: Complete (all source files)

Your choice [1/2/3] (default: 1): </ask>

<action if="user selects 1 OR user presses enter"> <action>Set scan_level = "quick"</action> <action>Display: "Using Quick Scan (pattern-based, no source file reading)"</action> </action>

<action if="user selects 2"> <action>Set scan_level = "deep"</action> <action>Display: "Using Deep Scan (reading critical files per project type)"</action> </action>

<action if="user selects 3"> <action>Set scan_level = "exhaustive"</action> <action>Display: "Using Exhaustive Scan (reading all source files)"</action> </action>

<action>Initialize state file: {project_knowledge}/project-scan-report.json</action> <critical>Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable.</critical> <action>Write initial state: { "workflow_version": "1.2.0", "timestamps": {"started": "{{current_timestamp}}", "last_updated": "{{current_timestamp}}"}, "mode": "{{workflow_mode}}", "scan_level": "{{scan_level}}", "project_root": "{{project_root_path}}", "project_knowledge": "{{project_knowledge}}", "completed_steps": [], "current_step": "step_1", "findings": {}, "outputs_generated": ["project-scan-report.json"], "resume_instructions": "Starting from step 1" } </action> <action>Continue with standard workflow from Step 1</action> </check> </step>

<step n="1" goal="Detect project structure and classify project type" if="workflow_mode != deep_dive"> <action>Ask user: "What is the root directory of the project to document?" (default: current working directory)</action> <action>Store as {{project_root_path}}</action>

<action>Scan {{project_root_path}} for key indicators:

• Directory structure (presence of client/, server/, api/, src/, app/, etc.)
• Key files (package.json, go.mod, requirements.txt, etc.)
• Technology markers matching detection_keywords from project-types.csv

</action>

<action>Detect if project is:

• Monolith: Single cohesive codebase
• Monorepo: Multiple parts in one repository
• Multi-part: Separate client/server or similar architecture

</action>

<check if="multiple distinct parts detected (e.g., client/ and server/ folders)"> <action>List detected parts with their paths</action> <ask>I detected multiple parts in this project: {{detected_parts_list}}

Is this correct? Should I document each part separately? [y/n] </ask>

<action if="user confirms">Set repository_type = "monorepo" or "multi-part"</action> <action if="user confirms">For each detected part: - Identify root path - Run project type detection using key_file_patterns from documentation-requirements.csv - Store as part in project_parts array </action>

<action if="user denies or corrects">Ask user to specify correct parts and their paths</action> </check>

<check if="single cohesive project detected"> <action>Set repository_type = "monolith"</action> <action>Create single part in project_parts array with root_path = {{project_root_path}}</action> <action>Run project type detection using key_file_patterns from documentation-requirements.csv</action> </check>

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

<ask>I've classified this project: {{project_classification_summary}}

Does this look correct? [y/n/edit] </ask>

<template-output>project_structure</template-output> <template-output>project_parts_metadata</template-output>

<action>IMMEDIATELY update state file with step completion:

• Add to completed_steps: {"step": "step_1", "status": "completed", "timestamp": "{{now}}", "summary": "Classified as {{repository_type}} with {{parts_count}} parts"}
• Update current_step = "step_2"
• Update findings.project_classification with high-level summary only
• CACHE project_type_id(s): Add project_types array: [{"part_id": "{{part_id}}", "project_type_id": "{{project_type_id}}", "display_name": "{{display_name}}"}]
• This cached data prevents reloading all CSV files on resume - we can load just the needed documentation_requirements row(s)
• Update last_updated timestamp
• Write state file

</action>

<action>PURGE detailed scan results from memory, keep only summary: "{{repository_type}}, {{parts_count}} parts, {{primary_tech}}"</action> </step>

<step n="2" goal="Discover existing documentation and gather user context" if="workflow_mode != deep_dive"> <action>For each part, scan for existing documentation using patterns:

• README.md, README.rst, README.txt
• CONTRIBUTING.md, CONTRIBUTING.rst
• ARCHITECTURE.md, ARCHITECTURE.txt, docs/architecture/
• DEPLOYMENT.md, DEPLOY.md, docs/deployment/
• API.md, docs/api/
• Any files in docs/, documentation/, .github/ folders

</action>

<action>Create inventory of existing_docs with:

• File path
• File type (readme, architecture, api, etc.)
• Which part it belongs to (if multi-part)

</action>

<ask>I found these existing documentation files: {{existing_docs_list}}

Are there any other important documents or key areas I should focus on while analyzing this project? [Provide paths or guidance, or type 'none'] </ask>

<action>Store user guidance as {{user_context}}</action>

<template-output>existing_documentation_inventory</template-output> <template-output>user_provided_context</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_2", "status": "completed", "timestamp": "{{now}}", "summary": "Found {{existing_docs_count}} existing docs"}
• Update current_step = "step_3"
• Update last_updated timestamp

</action>

<action>PURGE detailed doc contents from memory, keep only: "{{existing_docs_count}} docs found"</action> </step>

<step n="3" goal="Analyze technology stack for each part" if="workflow_mode != deep_dive"> <action>For each part in project_parts:

• Load key_file_patterns from documentation_requirements
• Scan part root for these patterns
• Parse technology manifest files (package.json, go.mod, requirements.txt, etc.)
• Extract: framework, language, version, database, dependencies
• Build technology_table with columns: Category, Technology, Version, Justification

</action>

<action>Determine architecture pattern based on detected tech stack:

• Use project_type_id as primary indicator (e.g., "web" → layered/component-based, "backend" → service/API-centric)
• Consider framework patterns (e.g., React → component hierarchy, Express → middleware pipeline)
• Note architectural style in technology table
• Store as {{architecture_pattern}} for each part

</action>

<template-output>technology_stack</template-output> <template-output>architecture_patterns</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_3", "status": "completed", "timestamp": "{{now}}", "summary": "Tech stack: {{primary_framework}}"}
• Update current_step = "step_4"
• Update findings.technology_stack with summary per part
• Update last_updated timestamp

</action>

<action>PURGE detailed tech analysis from memory, keep only: "{{framework}} on {{language}}"</action> </step>

<step n="4" goal="Perform conditional analysis based on project type requirements" if="workflow_mode != deep_dive">

<critical>BATCHING STRATEGY FOR DEEP/EXHAUSTIVE SCANS</critical>

<check if="scan_level == deep OR scan_level == exhaustive"> <action>This step requires file reading. Apply batching strategy:</action>

<action>Identify subfolders to process based on: - scan_level == "deep": Use critical_directories from documentation_requirements - scan_level == "exhaustive": Get ALL subfolders recursively (excluding node_modules, .git, dist, build, coverage) </action>

<action>For each subfolder to scan: 1. Read all files in subfolder (consider file size - use judgment for files >5000 LOC) 2. Extract required information based on conditional flags below 3. IMMEDIATELY write findings to appropriate output file 4. Validate written document (section-level validation) 5. Update state file with batch completion 6. PURGE detailed findings from context, keep only 1-2 sentence summary 7. Move to next subfolder </action>

<action>Track batches in state file: findings.batches_completed: [ {"path": "{{subfolder_path}}", "files_scanned": {{count}}, "summary": "{{brief_summary}}"} ] </action> </check>

<check if="scan_level == quick"> <action>Use pattern matching only - do NOT read source files</action> <action>Use glob/grep to identify file locations and patterns</action> <action>Extract information from filenames, directory structure, and config files only</action> </check>

<action>For each part, check documentation_requirements boolean flags and execute corresponding scans:</action>

<check if="requires_api_scan == true"> <action>Scan for API routes and endpoints using integration_scan_patterns</action> <action>Look for: controllers/, routes/, api/, handlers/, endpoints/</action>

<check if="scan_level == quick"> <action>Use glob to find route files, extract patterns from filenames and folder structure</action> </check>

<check if="scan_level == deep OR scan_level == exhaustive"> <action>Read files in batches (one subfolder at a time)</action> <action>Extract: HTTP methods, paths, request/response types from actual code</action> </check>

<action>Build API contracts catalog</action> <action>IMMEDIATELY write to: {project_knowledge}/api-contracts-{part_id}.md</action> <action>Validate document has all required sections</action> <action>Update state file with output generated</action> <action>PURGE detailed API data, keep only: "{{api_count}} endpoints documented"</action> <template-output>api_contracts\*{part_id}</template-output> </check>

<check if="requires_data_models == true"> <action>Scan for data models using schema_migration_patterns</action> <action>Look for: models/, schemas/, entities/, migrations/, prisma/, ORM configs</action>

<check if="scan_level == quick"> <action>Identify schema files via glob, parse migration file names for table discovery</action> </check>

<check if="scan_level == deep OR scan_level == exhaustive"> <action>Read model files in batches (one subfolder at a time)</action> <action>Extract: table names, fields, relationships, constraints from actual code</action> </check>

<action>Build database schema documentation</action> <action>IMMEDIATELY write to: {project_knowledge}/data-models-{part_id}.md</action> <action>Validate document completeness</action> <action>Update state file with output generated</action> <action>PURGE detailed schema data, keep only: "{{table_count}} tables documented"</action> <template-output>data_models\*{part_id}</template-output> </check>

<check if="requires_state_management == true"> <action>Analyze state management patterns</action> <action>Look for: Redux, Context API, MobX, Vuex, Pinia, Provider patterns</action> <action>Identify: stores, reducers, actions, state structure</action> <template-output>state_management_patterns_{part_id}</template-output> </check>

<check if="requires_ui_components == true"> <action>Inventory UI component library</action> <action>Scan: components/, ui/, widgets/, views/ folders</action> <action>Categorize: Layout, Form, Display, Navigation, etc.</action> <action>Identify: Design system, component patterns, reusable elements</action> <template-output>ui_component_inventory_{part_id}</template-output> </check>

<check if="requires_hardware_docs == true"> <action>Look for hardware schematics using hardware_interface_patterns</action> <ask>This appears to be an embedded/hardware project. Do you have:

• Pinout diagrams
• Hardware schematics
• PCB layouts
• Hardware documentation

If yes, please provide paths or links. [Provide paths or type 'none'] </ask> <action>Store hardware docs references</action> <template-output>hardwaredocumentation{part_id}</template-output> </check>

<check if="requires_asset_inventory == true"> <action>Scan and catalog assets using asset_patterns</action> <action>Categorize by: Images, Audio, 3D Models, Sprites, Textures, etc.</action> <action>Calculate: Total size, file counts, formats used</action> <template-output>asset_inventory_{part_id}</template-output> </check>

<action>Scan for additional patterns based on doc requirements:

• config_patterns → Configuration management
• auth_security_patterns → Authentication/authorization approach
• entry_point_patterns → Application entry points and bootstrap
• shared_code_patterns → Shared libraries and utilities
• async_event_patterns → Event-driven architecture
• ci_cd_patterns → CI/CD pipeline details
• localization_patterns → i18n/l10n support

</action>

<action>Apply scan_level strategy to each pattern scan (quick=glob only, deep/exhaustive=read files)</action>

<template-output>comprehensiveanalysis{part_id}</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_4", "status": "completed", "timestamp": "{{now}}", "summary": "Conditional analysis complete, {{files_generated}} files written"}
• Update current_step = "step_5"
• Update last_updated timestamp
• List all outputs_generated

</action>

<action>PURGE all detailed scan results from context. Keep only summaries:

• "APIs: {{api_count}} endpoints"
• "Data: {{table_count}} tables"
• "Components: {{component_count}} components"

</action> </step>

<step n="5" goal="Generate source tree analysis with annotations" if="workflow_mode != deep_dive"> <action>For each part, generate complete directory tree using critical_directories from doc requirements</action>

<action>Annotate the tree with:

• Purpose of each critical directory
• Entry points marked
• Key file locations highlighted
• Integration points noted (for multi-part projects)

</action>

<action if="multi-part project">Show how parts are organized and where they interface</action>

<action>Create formatted source tree with descriptions:

project-root/
├── client/          # React frontend (Part: client)
│   ├── src/
│   │   ├── components/  # Reusable UI components
│   │   ├── pages/       # Route-based pages
│   │   └── api/         # API client layer → Calls server/
├── server/          # Express API backend (Part: api)
│   ├── src/
│   │   ├── routes/      # REST API endpoints
│   │   ├── models/      # Database models
│   │   └── services/    # Business logic

</action>

<template-output>source_tree_analysis</template-output> <template-output>critical_folders_summary</template-output>

<action>IMMEDIATELY write source-tree-analysis.md to disk</action> <action>Validate document structure</action> <action>Update state file:

• Add to completed_steps: {"step": "step_5", "status": "completed", "timestamp": "{{now}}", "summary": "Source tree documented"}
• Update current_step = "step_6"
• Add output: "source-tree-analysis.md"

</action> <action>PURGE detailed tree from context, keep only: "Source tree with {{folder_count}} critical folders"</action> </step>

<step n="6" goal="Extract development and operational information" if="workflow_mode != deep_dive"> <action>Scan for development setup using key_file_patterns and existing docs:

• Prerequisites (Node version, Python version, etc.)
• Installation steps (npm install, etc.)
• Environment setup (.env files, config)
• Build commands (npm run build, make, etc.)
• Run commands (npm start, go run, etc.)
• Test commands using test_file_patterns

</action>

<action>Look for deployment configuration using ci_cd_patterns:

• Dockerfile, docker-compose.yml
• Kubernetes configs (k8s/, helm/)
• CI/CD pipelines (.github/workflows/, .gitlab-ci.yml)
• Deployment scripts
• Infrastructure as Code (terraform/, pulumi/)

</action>

<action if="CONTRIBUTING.md or similar found"> <action>Extract contribution guidelines:

• Code style rules
• PR process
• Commit conventions
• Testing requirements

</action> </action>

<template-output>development_instructions</template-output> <template-output>deployment_configuration</template-output> <template-output>contribution_guidelines</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_6", "status": "completed", "timestamp": "{{now}}", "summary": "Dev/deployment guides written"}
• Update current_step = "step_7"
• Add generated outputs to list

</action> <action>PURGE detailed instructions, keep only: "Dev setup and deployment documented"</action> </step>

<step n="7" goal="Detect multi-part integration architecture" if="workflow_mode != deep_dive and project has multiple parts"> <action>Analyze how parts communicate:

• Scan integration_scan_patterns across parts
• Identify: REST calls, GraphQL queries, gRPC, message queues, shared databases
• Document: API contracts between parts, data flow, authentication flow

</action>

<action>Create integration_points array with:

• from: source part
• to: target part
• type: REST API, GraphQL, gRPC, Event Bus, etc.
• details: Endpoints, protocols, data formats

</action>

<action>IMMEDIATELY write integration-architecture.md to disk</action> <action>Validate document completeness</action>

<template-output>integration_architecture</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_7", "status": "completed", "timestamp": "{{now}}", "summary": "Integration architecture documented"}
• Update current_step = "step_8"

</action> <action>PURGE integration details, keep only: "{{integration_count}} integration points"</action> </step>

<step n="8" goal="Generate architecture documentation for each part" if="workflow_mode != deep_dive"> <action>For each part in project_parts:

• Use matched architecture template from Step 3 as base structure
• Fill in all sections with discovered information:
• Executive Summary
• Technology Stack (from Step 3)
• Architecture Pattern (from registry match)
• Data Architecture (from Step 4 data models scan)
• API Design (from Step 4 API scan if applicable)
• Component Overview (from Step 4 component scan if applicable)
• Source Tree (from Step 5)
• Development Workflow (from Step 6)
• Deployment Architecture (from Step 6)
• Testing Strategy (from test patterns)

</action>

<action if="single part project">

• Generate: architecture.md (no part suffix)

</action>

<action if="multi-part project">

• Generate: architecture-{part_id}.md for each part

</action>

<action>For each architecture file generated:

• IMMEDIATELY write architecture file to disk
• Validate against architecture template schema
• Update state file with output
• PURGE detailed architecture from context, keep only: "Architecture for {{part_id}} written"

</action>

<template-output>architecture_document</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_8", "status": "completed", "timestamp": "{{now}}", "summary": "Architecture docs written for {{parts_count}} parts"}
• Update current_step = "step_9"

</action> </step>

<step n="9" goal="Generate supporting documentation files" if="workflow_mode != deep_dive"> <action>Generate project-overview.md with:

• Project name and purpose (from README or user input)
• Executive summary
• Tech stack summary table
• Architecture type classification
• Repository structure (monolith/monorepo/multi-part)
• Links to detailed docs

</action>

<action>Generate source-tree-analysis.md with:

• Full annotated directory tree from Step 5
• Critical folders explained
• Entry points documented
• Multi-part structure (if applicable)

</action>

<action>IMMEDIATELY write project-overview.md to disk</action> <action>Validate document sections</action>

<action>Generate source-tree-analysis.md (if not already written in Step 5)</action> <action>IMMEDIATELY write to disk and validate</action>

<action>Generate component-inventory.md (or per-part versions) with:

• All discovered components from Step 4
• Categorized by type
• Reusable vs specific components
• Design system elements (if found)

</action> <action>IMMEDIATELY write each component inventory to disk and validate</action>

<action>Generate development-guide.md (or per-part versions) with:

• Prerequisites and dependencies
• Environment setup instructions
• Local development commands
• Build process
• Testing approach and commands
• Common development tasks

</action> <action>IMMEDIATELY write each development guide to disk and validate</action>

<action if="deployment configuration found"> <action>Generate deployment-guide.md with:

• Infrastructure requirements
• Deployment process
• Environment configuration
• CI/CD pipeline details

</action> <action>IMMEDIATELY write to disk and validate</action> </action>

<action if="contribution guidelines found"> <action>Generate contribution-guide.md with:

• Code style and conventions
• PR process
• Testing requirements
• Documentation standards

</action> <action>IMMEDIATELY write to disk and validate</action> </action>

<action if="API contracts documented"> <action>Generate api-contracts.md (or per-part) with:

• All API endpoints
• Request/response schemas
• Authentication requirements
• Example requests

</action> <action>IMMEDIATELY write to disk and validate</action> </action>

<action if="Data models documented"> <action>Generate data-models.md (or per-part) with:

• Database schema
• Table relationships
• Data models and entities
• Migration strategy

</action> <action>IMMEDIATELY write to disk and validate</action> </action>

<action if="multi-part project"> <action>Generate integration-architecture.md with:

• How parts communicate
• Integration points diagram/description
• Data flow between parts
• Shared dependencies

</action> <action>IMMEDIATELY write to disk and validate</action>

<action>Generate project-parts.json metadata file: json { "repository_type": "monorepo", "parts": [ ... ], "integration_points": [ ... ] } </action> <action>IMMEDIATELY write to disk</action> </action>

<template-output>supporting_documentation</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_9", "status": "completed", "timestamp": "{{now}}", "summary": "All supporting docs written"}
• Update current_step = "step_10"
• List all newly generated outputs

</action>

<action>PURGE all document contents from context, keep only list of files generated</action> </step>

<step n="10" goal="Generate master index as primary AI retrieval source" if="workflow_mode != deep_dive">

<critical>INCOMPLETE DOCUMENTATION MARKER CONVENTION: When a document SHOULD be generated but wasn't (due to quick scan, missing data, conditional requirements not met):

• Use EXACTLY this marker: _(To be generated)_
• Place it at the end of the markdown link line
• Example: - API Contracts - Server _(To be generated)_
• This allows Step 11 to detect and offer to complete these items
• ALWAYS use this exact format for consistency and automated detection

</critical>

<action>Create index.md with intelligent navigation based on project structure</action>

<action if="single part project"> <action>Generate simple index with:

• Project name and type
• Quick reference (tech stack, architecture type)
• Links to all generated docs
• Links to discovered existing docs
• Getting started section

</action> </action>

<action if="multi-part project"> <action>Generate comprehensive index with:

• Project overview and structure summary
• Part-based navigation section
• Quick reference by part
• Cross-part integration links
• Links to all generated and existing docs
• Getting started per part

</action> </action>

<action>Include in index.md:

Project Documentation Index

Project Overview

• Type: {{repository_type}} {{#if multi-part}}with {{parts.length}} parts{{/if}}
• Primary Language: {{primary_language}}
• Architecture: {{architecture_type}}

Quick Reference

{{#if single_part}}

• Tech Stack: {{tech_stack_summary}}
• Entry Point: {{entry_point}}
• Architecture Pattern: {{architecture_pattern}}

{{else}} {{#each parts}}

{{part_name}} ({{part_id}})

• Type: {{project_type}}
• Tech Stack: {{tech_stack}}
• Root: {{root_path}}

{{/each}} {{/if}}

Generated Documentation

• Project Overview
• [Architecture](./architecture{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless architecture_file_exists}} (To be generated) {{/unless}}
• Source Tree Analysis
• [Component Inventory](./component-inventory{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless component_inventory_exists}} (To be generated) {{/unless}}
• [Development Guide](./development-guide{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless dev_guide_exists}} (To be generated) {{/unless}}

{{#if deployment_found}}- Deployment Guide{{#unless deployment_guide_exists}} (To be generated) {{/unless}}{{/if}} {{#if contribution_found}}- Contribution Guide{{/if}} {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{#unless api_contracts_exists}} (To be generated) {{/unless}}{{/if}} {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{#unless data_models_exists}} (To be generated) {{/unless}}{{/if}} {{#if multi-part}}- Integration Architecture{{#unless integration_arch_exists}} (To be generated) {{/unless}}{{/if}}

Existing Documentation

{{#each existing_docs}}

• {{title}} - {{description}}

{{/each}}

Getting Started

{{getting_started_instructions}} </action>

<action>Before writing index.md, check which expected files actually exist:

• For each document that should have been generated, check if file exists on disk
• Set existence flags: architecture_file_exists, component_inventory_exists, dev_guide_exists, etc.
• These flags determine whether to add the _(To be generated)_ marker
• Track which files are missing in {{missing_docs_list}} for reporting

</action>

<action>IMMEDIATELY write index.md to disk with appropriate _(To be generated)_ markers for missing files</action> <action>Validate index has all required sections and links are valid</action>

<template-output>index</template-output>

<action>Update state file:

• Add to completed_steps: {"step": "step_10", "status": "completed", "timestamp": "{{now}}", "summary": "Master index generated"}
• Update current_step = "step_11"
• Add output: "index.md"

</action>

<action>PURGE index content from context</action> </step>

<step n="11" goal="Validate and review generated documentation" if="workflow_mode != deep_dive"> <action>Show summary of all generated files: Generated in {{project_knowledge}}/: {{file_list_with_sizes}} </action>

<action>Run validation checklist from ../checklist.md</action>

<critical>INCOMPLETE DOCUMENTATION DETECTION:

1. PRIMARY SCAN: Look for exact marker: _(To be generated)_ 2. FALLBACK SCAN: Look for fuzzy patterns (in case agent was lazy):

• _(TBD)_
• _(TODO)_
• _(Coming soon)_
• _(Not yet generated)_
• _(Pending)_

3. Extract document metadata from each match for user selection </critical>

<action>Read {project_knowledge}/index.md</action>

<action>Scan for incomplete documentation markers: Step 1: Search for exact pattern "_(To be generated)_" (case-sensitive) Step 2: For each match found, extract the entire line Step 3: Parse line to extract:

• Document title (text within [brackets] or bold)
• File path (from markdown link or inferable from title)
• Document type (infer from filename: architecture, api-contracts, data-models, component-inventory, development-guide, deployment-guide, integration-architecture)
• Part ID if applicable (extract from filename like "architecture-server.md" → part_id: "server")

Step 4: Add to {{incomplete_docs_strict}} array </action>

<action>Fallback fuzzy scan for alternate markers: Search for patterns: _(TBD)_, _(TODO)_, _(Coming soon)_, _(Not yet generated)_, _(Pending)_ For each fuzzy match:

• Extract same metadata as strict scan
• Add to {{incomplete_docs_fuzzy}} array with fuzzy_match flag

</action>

<action>Combine results: Set {{incomplete_docs_list}} = {{incomplete_docs_strict}} + {{incomplete_docs_fuzzy}} For each item store structure: { "title": "Architecture – Server", "file\*path": "./architecture-server.md", "doc_type": "architecture", "part_id": "server", "line_text": "- Architecture – Server (To be generated)", "fuzzy_match": false } </action>

<ask>Documentation generation complete!

Summary:

• Project Type: {{project_type_summary}}
• Parts Documented: {{parts_count}}
• Files Generated: {{files_count}}
• Total Lines: {{total_lines}}

{{#if incomplete_docs_list.length > 0}} ⚠️ Incomplete Documentation Detected:

I found {{incomplete_docs_list.length}} item(s) marked as incomplete:

{{#each incomplete_docs_list}} {{@index + 1}}. {{title}} ({{doc_type}}{{#if part_id}} for {{part_id}}{{/if}}){{#if fuzzy_match}} ⚠️ [non-standard marker]{{/if}} {{/each}}

{{/if}}

Would you like to:

{{#if incomplete_docs_list.length > 0}}

1. Generate incomplete documentation - Complete any of the {{incomplete_docs_list.length}} items above 2. Review any specific section [type section name] 3. Add more detail to any area [type area name] 4. Generate additional custom documentation [describe what] 5. Finalize and complete [type 'done'] {{else}} 6. Review any specific section [type section name] 7. Add more detail to any area [type area name] 8. Generate additional documentation [describe what] 9. Finalize and complete [type 'done'] {{/if}}

Your choice: </ask>

<check if="user selects option 1 (generate incomplete)"> <ask>Which incomplete items would you like to generate?

{{#each incomplete_docs_list}} {{@index + 1}}. {{title}} ({{doc_type}}{{#if part_id}} - {{part_id}}{{/if}}) {{/each}} {{incomplete_docs_list.length + 1}}. All of them

Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all': </ask>

<action>Parse user selection:

• If "all", set {{selected_items}} = all items in {{incomplete_docs_list}}
• If comma-separated numbers, extract selected items by index
• Store result in {{selected_items}} array

</action>

<action>Display: "Generating {{selected_items.length}} document(s)..."</action>

<action>For each item in {{selected_items}}:

1. Identify the part and requirements:

• Extract part_id from item (if exists)
• Look up part data in project_parts array from state file
• Load documentation_requirements for that part's project_type_id

2. Route to appropriate generation substep based on doc_type:

If doc_type == "architecture":

• Display: "Generating architecture documentation for {{part_id}}..."
• Load architecture_match for this part from state file (Step 3 cache)
• Re-run Step 8 architecture generation logic ONLY for this specific part
• Use matched template and fill with cached data from state file
• Write architecture-{{part_id}}.md to disk
• Validate completeness

If doc_type == "api-contracts":

• Display: "Generating API contracts for {{part_id}}..."
• Load part data and documentation_requirements
• Re-run Step 4 API scan substep targeting ONLY this part
• Use scan_level from state file (quick/deep/exhaustive)
• Generate api-contracts-{{part_id}}.md
• Validate document structure

If doc_type == "data-models":

• Display: "Generating data models documentation for {{part_id}}..."
• Re-run Step 4 data models scan substep targeting ONLY this part
• Use schema_migration_patterns from documentation_requirements
• Generate data-models-{{part_id}}.md
• Validate completeness

If doc_type == "component-inventory":

• Display: "Generating component inventory for {{part_id}}..."
• Re-run Step 9 component inventory generation for this specific part
• Scan components/, ui/, widgets/ folders
• Generate component-inventory-{{part_id}}.md
• Validate structure

If doc_type == "development-guide":

• Display: "Generating development guide for {{part_id}}..."
• Re-run Step 9 development guide generation for this specific part
• Use key_file_patterns and test_file_patterns from documentation_requirements
• Generate development-guide-{{part_id}}.md
• Validate completeness

If doc_type == "deployment-guide":

• Display: "Generating deployment guide..."
• Re-run Step 6 deployment configuration scan
• Re-run Step 9 deployment guide generation
• Generate deployment-guide.md
• Validate structure

If doc_type == "integration-architecture":

• Display: "Generating integration architecture..."
• Re-run Step 7 integration analysis for all parts
• Generate integration-architecture.md
• Validate completeness

3. Post-generation actions:

• Confirm file was written successfully
• Update state file with newly generated output
• Add to {{newly_generated_docs}} tracking list
• Display: "✓ Generated: {{file_path}}"

4. Handle errors:

• If generation fails, log error and continue with next item
• Track failed items in {{failed_generations}} list

</action>

<action>After all selected items are processed:

Update index.md to remove markers:

1. Read current index.md content 2. For each item in {{newly_generated_docs}}:

• Find the line containing the file link and marker
• Remove the _(To be generated)_ or fuzzy marker text
• Leave the markdown link intact

3. Write updated index.md back to disk 4. Update state file to record index.md modification </action>

<action>Display generation summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Documentation Generation Complete!

Successfully Generated: {{#each newly_generated_docs}}

• {{title}} → {{file_path}}

{{/each}}

{{#if failed_generations.length > 0}} Failed to Generate: {{#each failed_generations}}

• {{title}} ({{error_message}})

{{/each}} {{/if}}

Updated: index.md (removed incomplete markers)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ </action>

<action>Update state file with all generation activities</action>

<action>Return to Step 11 menu (loop back to check for any remaining incomplete items)</action> </check>

<action if="user requests other changes (options 2-3)">Make requested modifications and regenerate affected files</action> <action if="user selects finalize (option 4 or 5)">Proceed to Step 12 completion</action>

<check if="not finalizing"> <action>Update state file:

• Add to completed_steps: {"step": "step_11_iteration", "status": "completed", "timestamp": "{{now}}", "summary": "Review iteration complete"}
• Keep current_step = "step_11" (for loop back)
• Update last_updated timestamp

</action> <action>Loop back to beginning of Step 11 (re-scan for remaining incomplete docs)</action> </check>

<check if="finalizing"> <action>Update state file:

• Add to completed_steps: {"step": "step_11", "status": "completed", "timestamp": "{{now}}", "summary": "Validation and review complete"}
• Update current_step = "step_12"

</action> <action>Proceed to Step 12</action> </check> </step>

<step n="12" goal="Finalize and provide next steps" if="workflow_mode != deep_dive"> <action>Create final summary report</action> <action>Compile verification recap variables:

• Set {{verification_summary}} to the concrete tests, validations, or scripts you executed (or "none run").
• Set {{open_risks}} to any remaining risks or TODO follow-ups (or "none").
• Set {{next_checks}} to recommended actions before merging/deploying (or "none").

</action>

<action>Display completion message:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project Documentation Complete! ✓

Location: {{project_knowledge}}/

Master Index: {{project_knowledge}}/index.md 👆 This is your primary entry point for AI-assisted development

Generated Documentation: {{generated_files_list}}

Next Steps:

1. Review the index.md to familiarize yourself with the documentation structure 2. When creating a brownfield PRD, point the PRD workflow to: {{project_knowledge}}/index.md 3. For UI-only features: Reference {{project_knowledge}}/architecture-{{ui_part_id}}.md 4. For API-only features: Reference {{project_knowledge}}/architecture-{{api_part_id}}.md 5. For full-stack features: Reference both part architectures + integration-architecture.md

Verification Recap:

• Tests/extractions executed: {{verification_summary}}
• Outstanding risks or follow-ups: {{open_risks}}
• Recommended next checks before PR: {{next_checks}}

Brownfield PRD Command: When ready to plan new features, run the PRD workflow and provide this index as input.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ </action>

<action>FINALIZE state file:

• Add to completed_steps: {"step": "step_12", "status": "completed", "timestamp": "{{now}}", "summary": "Workflow complete"}
• Update timestamps.completed = "{{now}}"
• Update current_step = "completed"
• Write final state file

</action>

<action>Display: "State file saved: {{project_knowledge}}/project-scan-report.json"</action> <action>Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action>

</workflow>

Full Project Scan Sub-Workflow

Goal: Complete project documentation (initial scan or full rescan).

Your Role: Full project scan documentation specialist.

---

INITIALIZATION

Configuration Loading

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

• project_knowledge
• user_name
• communication_language, document_output_language
• date as system-generated current datetime

✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured {communication_language}. ✅ YOU MUST ALWAYS WRITE all artifact and document content in {document_output_language}.

Runtime Inputs

• workflow_mode = "" (set by parent: initial_scan or full_rescan)
• scan_level = "" (set by parent: quick, deep, or exhaustive)
• resume_mode = false
• autonomous = false (requires user input at key decision points)

---

EXECUTION

Read fully and follow: ./full-scan-instructions.md