445 lines
14 KiB
Markdown
445 lines
14 KiB
Markdown
# Document Project Workflow
|
|
|
|
**Version:** 1.2.0
|
|
**Module:** BMM (BMAD Method Module)
|
|
**Type:** Action Workflow (Documentation Generator)
|
|
|
|
## Purpose
|
|
|
|
Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development. Generates a master index and multiple documentation files tailored to project structure and type.
|
|
|
|
**NEW in v1.2.0:** Context-safe architecture with scan levels, resumability, and write-as-you-go pattern to prevent context exhaustion.
|
|
|
|
## Key Features
|
|
|
|
- **Multi-Project Type Support**: Handles web, backend, mobile, CLI, game, embedded, data, infra, library, desktop, and extension projects
|
|
- **Multi-Part Detection**: Automatically detects and documents projects with separate client/server or multiple services
|
|
- **Three Scan Levels** (NEW v1.2.0): Quick (2-5 min), Deep (10-30 min), Exhaustive (30-120 min)
|
|
- **Resumability** (NEW v1.2.0): Interrupt and resume workflows without losing progress
|
|
- **Write-as-you-go** (NEW v1.2.0): Documents written immediately to prevent context exhaustion
|
|
- **Intelligent Batching** (NEW v1.2.0): Subfolder-based processing for deep/exhaustive scans
|
|
- **Data-Driven Analysis**: Uses CSV-based project type detection and documentation requirements
|
|
- **Comprehensive Scanning**: Analyzes APIs, data models, UI components, configuration, security patterns, and more
|
|
- **Architecture Matching**: Matches projects to 170+ architecture templates from the solutioning registry
|
|
- **Brownfield PRD Ready**: Generates documentation specifically designed for AI agents planning new features
|
|
|
|
## How to Invoke
|
|
|
|
```bash
|
|
workflow document-project
|
|
```
|
|
|
|
Or from BMAD CLI:
|
|
|
|
```bash
|
|
/bmad:bmm:workflows:document-project
|
|
```
|
|
|
|
## Scan Levels (NEW in v1.2.0)
|
|
|
|
Choose the right scan depth for your needs:
|
|
|
|
### 1. Quick Scan (Default)
|
|
|
|
**Duration:** 2-5 minutes
|
|
**What it does:** Pattern-based analysis without reading source files
|
|
**Reads:** Config files, package manifests, directory structure, README
|
|
**Use when:**
|
|
|
|
- You need a fast project overview
|
|
- Initial understanding of project structure
|
|
- Planning next steps before deeper analysis
|
|
|
|
**Does NOT read:** Source code files (_.js, _.ts, _.py, _.go, etc.)
|
|
|
|
### 2. Deep Scan
|
|
|
|
**Duration:** 10-30 minutes
|
|
**What it does:** Reads files in critical directories based on project type
|
|
**Reads:** Files in critical paths defined by documentation requirements
|
|
**Use when:**
|
|
|
|
- Creating comprehensive documentation for brownfield PRD
|
|
- Need detailed analysis of key areas
|
|
- Want balance between depth and speed
|
|
|
|
**Example:** For a web app, reads controllers/, models/, components/, but not every utility file
|
|
|
|
### 3. Exhaustive Scan
|
|
|
|
**Duration:** 30-120 minutes
|
|
**What it does:** Reads ALL source files in project
|
|
**Reads:** Every source file (excludes node_modules, dist, build, .git)
|
|
**Use when:**
|
|
|
|
- Complete project analysis needed
|
|
- Migration planning requires full understanding
|
|
- Detailed audit of entire codebase
|
|
- Deep technical debt assessment
|
|
|
|
**Note:** Deep-dive mode ALWAYS uses exhaustive scan (no choice)
|
|
|
|
## Resumability (NEW in v1.2.0)
|
|
|
|
The workflow can be interrupted and resumed without losing progress:
|
|
|
|
- **State Tracking:** Progress saved in `project-scan-report.json`
|
|
- **Auto-Detection:** Workflow detects incomplete runs (<24 hours old)
|
|
- **Resume Prompt:** Choose to resume or start fresh
|
|
- **Step-by-Step:** Resume from exact step where interrupted
|
|
- **Archiving:** Old state files automatically archived
|
|
|
|
**Example Resume Flow:**
|
|
|
|
```
|
|
> workflow document-project
|
|
|
|
I found an in-progress workflow state from 2025-10-11 14:32:15.
|
|
|
|
Current Progress:
|
|
- Mode: initial_scan
|
|
- Scan Level: deep
|
|
- Completed Steps: 5/12
|
|
- Last Step: step_5
|
|
|
|
Would you like to:
|
|
1. Resume from where we left off - Continue from step 6
|
|
2. Start fresh - Archive old state and begin new scan
|
|
3. Cancel - Exit without changes
|
|
|
|
Your choice [1/2/3]:
|
|
```
|
|
|
|
## What It Does
|
|
|
|
### Step-by-Step Process
|
|
|
|
1. **Detects Project Structure** - Identifies if project is single-part or multi-part (client/server/etc.)
|
|
2. **Classifies Project Type** - Matches against 12 project types (web, backend, mobile, etc.)
|
|
3. **Discovers Documentation** - Finds existing README, CONTRIBUTING, ARCHITECTURE files
|
|
4. **Analyzes Tech Stack** - Parses package files, identifies frameworks, versions, dependencies
|
|
5. **Conditional Scanning** - Performs targeted analysis based on project type requirements:
|
|
- API routes and endpoints
|
|
- Database models and schemas
|
|
- State management patterns
|
|
- UI component libraries
|
|
- Configuration and security
|
|
- CI/CD and deployment configs
|
|
6. **Generates Source Tree** - Creates annotated directory structure with critical paths
|
|
7. **Extracts Dev Instructions** - Documents setup, build, run, and test commands
|
|
8. **Creates Architecture Docs** - Generates detailed architecture using matched templates
|
|
9. **Builds Master Index** - Creates comprehensive index.md as primary AI retrieval source
|
|
10. **Validates Output** - Runs 140+ point checklist to ensure completeness
|
|
|
|
### Output Files
|
|
|
|
**Single-Part Projects:**
|
|
|
|
- `index.md` - Master index
|
|
- `project-overview.md` - Executive summary
|
|
- `architecture.md` - Detailed architecture
|
|
- `source-tree-analysis.md` - Annotated directory tree
|
|
- `component-inventory.md` - Component catalog (if applicable)
|
|
- `development-guide.md` - Local dev instructions
|
|
- `api-contracts.md` - API documentation (if applicable)
|
|
- `data-models.md` - Database schema (if applicable)
|
|
- `deployment-guide.md` - Deployment process (optional)
|
|
- `contribution-guide.md` - Contributing guidelines (optional)
|
|
- `project-scan-report.json` - State file for resumability (NEW v1.2.0)
|
|
|
|
**Multi-Part Projects (e.g., client + server):**
|
|
|
|
- `index.md` - Master index with part navigation
|
|
- `project-overview.md` - Multi-part summary
|
|
- `architecture-{part_id}.md` - Per-part architecture docs
|
|
- `source-tree-analysis.md` - Full tree with part annotations
|
|
- `component-inventory-{part_id}.md` - Per-part components
|
|
- `development-guide-{part_id}.md` - Per-part dev guides
|
|
- `integration-architecture.md` - How parts communicate
|
|
- `project-parts.json` - Machine-readable metadata
|
|
- `project-scan-report.json` - State file for resumability (NEW v1.2.0)
|
|
- Additional conditional files per part (API, data models, etc.)
|
|
|
|
## Data Files
|
|
|
|
The workflow uses a single comprehensive CSV file:
|
|
|
|
**documentation-requirements.csv** - Complete project analysis guide
|
|
|
|
- Location: `/bmad/bmm/workflows/document-project/documentation-requirements.csv`
|
|
- 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
|
|
- 24 columns combining:
|
|
- **Detection columns**: `project_type_id`, `key_file_patterns` (identifies project type from codebase)
|
|
- **Requirement columns**: `requires_api_scan`, `requires_data_models`, `requires_ui_components`, etc.
|
|
- **Pattern columns**: `critical_directories`, `test_file_patterns`, `config_patterns`, etc.
|
|
- Self-contained: All project detection AND scanning requirements in one file
|
|
- Architecture patterns inferred from tech stack (no external registry needed)
|
|
|
|
## Use Cases
|
|
|
|
### Primary Use Case: Brownfield PRD Creation
|
|
|
|
After running this workflow, use the generated `index.md` as input to brownfield PRD workflows:
|
|
|
|
```
|
|
User: "I want to add a new dashboard feature"
|
|
PRD Workflow: Loads docs/index.md
|
|
→ Understands existing architecture
|
|
→ Identifies reusable components
|
|
→ Plans integration with existing APIs
|
|
→ Creates contextual PRD with epics and stories
|
|
```
|
|
|
|
### Other Use Cases
|
|
|
|
- **Onboarding New Developers** - Comprehensive project documentation
|
|
- **Architecture Review** - Structured analysis of existing system
|
|
- **Technical Debt Assessment** - Identify patterns and anti-patterns
|
|
- **Migration Planning** - Understand current state before refactoring
|
|
|
|
## Requirements
|
|
|
|
### Recommended Inputs (Optional)
|
|
|
|
- Project root directory (defaults to current directory)
|
|
- README.md or similar docs (auto-discovered if present)
|
|
- User guidance on key areas to focus (workflow will ask)
|
|
|
|
### Tools Used
|
|
|
|
- File system scanning (Glob, Read, Grep)
|
|
- Code analysis
|
|
- Git repository analysis (optional)
|
|
|
|
## Configuration
|
|
|
|
### Default Output Location
|
|
|
|
Files are saved to: `{output_folder}` (from config.yaml)
|
|
|
|
Default: `/docs/` folder in project root
|
|
|
|
### Customization
|
|
|
|
- Modify `documentation-requirements.csv` to adjust scanning patterns for project types
|
|
- Add new project types to `project-types.csv`
|
|
- Add new architecture templates to `registry.csv`
|
|
|
|
## Example: Multi-Part Web App
|
|
|
|
**Input:**
|
|
|
|
```
|
|
my-app/
|
|
├── client/ # React frontend
|
|
├── server/ # Express backend
|
|
└── README.md
|
|
```
|
|
|
|
**Detection Result:**
|
|
|
|
- Repository Type: Monorepo
|
|
- Part 1: client (web/React)
|
|
- Part 2: server (backend/Express)
|
|
|
|
**Output (10+ files):**
|
|
|
|
```
|
|
docs/
|
|
├── index.md
|
|
├── project-overview.md
|
|
├── architecture-client.md
|
|
├── architecture-server.md
|
|
├── source-tree-analysis.md
|
|
├── component-inventory-client.md
|
|
├── development-guide-client.md
|
|
├── development-guide-server.md
|
|
├── api-contracts-server.md
|
|
├── data-models-server.md
|
|
├── integration-architecture.md
|
|
└── project-parts.json
|
|
```
|
|
|
|
## Example: Simple CLI Tool
|
|
|
|
**Input:**
|
|
|
|
```
|
|
hello-cli/
|
|
├── main.go
|
|
├── go.mod
|
|
└── README.md
|
|
```
|
|
|
|
**Detection Result:**
|
|
|
|
- Repository Type: Monolith
|
|
- Part 1: main (cli/Go)
|
|
|
|
**Output (4 files):**
|
|
|
|
```
|
|
docs/
|
|
├── index.md
|
|
├── project-overview.md
|
|
├── architecture.md
|
|
└── source-tree-analysis.md
|
|
```
|
|
|
|
## Deep-Dive Mode
|
|
|
|
### What is Deep-Dive Mode?
|
|
|
|
When you run the workflow on a project that already has documentation, you'll be offered a choice:
|
|
|
|
1. **Rescan entire project** - Update all documentation with latest changes
|
|
2. **Deep-dive into specific area** - Generate EXHAUSTIVE documentation for a particular feature/module/folder
|
|
3. **Cancel** - Keep existing documentation
|
|
|
|
Deep-dive mode performs **comprehensive, file-by-file analysis** of a specific area, reading EVERY file completely and documenting:
|
|
|
|
- All exports with complete signatures
|
|
- All imports and dependencies
|
|
- Dependency graphs and data flow
|
|
- Code patterns and implementations
|
|
- Testing coverage and strategies
|
|
- Integration points
|
|
- Reuse opportunities
|
|
|
|
### When to Use Deep-Dive Mode
|
|
|
|
- **Before implementing a feature** - Deep-dive the area you'll be modifying
|
|
- **During architecture review** - Deep-dive complex modules
|
|
- **For code understanding** - Deep-dive unfamiliar parts of codebase
|
|
- **When creating PRDs** - Deep-dive areas affected by new features
|
|
|
|
### Deep-Dive Process
|
|
|
|
1. Workflow detects existing `index.md`
|
|
2. Offers deep-dive option
|
|
3. Suggests areas based on project structure:
|
|
- API route groups
|
|
- Feature modules
|
|
- UI component areas
|
|
- Services/business logic
|
|
4. You select area or specify custom path
|
|
5. Workflow reads EVERY file in that area
|
|
6. Generates `deep-dive-{area-name}.md` with complete analysis
|
|
7. Updates `index.md` with link to deep-dive doc
|
|
8. Offers to deep-dive another area or finish
|
|
|
|
### Deep-Dive Output Example
|
|
|
|
**docs/deep-dive-dashboard-feature.md:**
|
|
|
|
- Complete file inventory (47 files analyzed)
|
|
- Every export with signatures
|
|
- Dependency graph
|
|
- Data flow analysis
|
|
- Integration points
|
|
- Testing coverage
|
|
- Related code references
|
|
- Implementation guidance
|
|
- ~3,000 LOC documented in detail
|
|
|
|
### Incremental Deep-Diving
|
|
|
|
You can deep-dive multiple areas over time:
|
|
|
|
- First run: Scan entire project → generates index.md
|
|
- Second run: Deep-dive dashboard feature
|
|
- Third run: Deep-dive API layer
|
|
- Fourth run: Deep-dive authentication system
|
|
|
|
All deep-dive docs are linked from the master index.
|
|
|
|
## Validation
|
|
|
|
The workflow includes a comprehensive 160+ point checklist covering:
|
|
|
|
- Project detection accuracy
|
|
- Technology stack completeness
|
|
- Codebase scanning thoroughness
|
|
- Architecture documentation quality
|
|
- Multi-part handling (if applicable)
|
|
- Brownfield PRD readiness
|
|
- Deep-dive completeness (if applicable)
|
|
|
|
## Next Steps After Completion
|
|
|
|
1. **Review** `docs/index.md` - Your master documentation index
|
|
2. **Validate** - Check generated docs for accuracy
|
|
3. **Use for PRD** - Point brownfield PRD workflow to index.md
|
|
4. **Maintain** - Re-run workflow when architecture changes significantly
|
|
|
|
## File Structure
|
|
|
|
```
|
|
document-project/
|
|
├── workflow.yaml # Workflow configuration
|
|
├── instructions.md # Step-by-step workflow logic
|
|
├── checklist.md # Validation criteria
|
|
├── documentation-requirements.csv # Project type scanning patterns
|
|
├── templates/ # Output templates
|
|
│ ├── index-template.md
|
|
│ ├── project-overview-template.md
|
|
│ └── source-tree-template.md
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Issue: Project type not detected correctly**
|
|
|
|
- Solution: Workflow will ask for confirmation; manually select correct type
|
|
|
|
**Issue: Missing critical information**
|
|
|
|
- Solution: Provide additional context when prompted; re-run specific analysis steps
|
|
|
|
**Issue: Multi-part detection missed a part**
|
|
|
|
- Solution: When asked to confirm parts, specify the missing part and its path
|
|
|
|
**Issue: Architecture template doesn't match well**
|
|
|
|
- Solution: Check registry.csv; may need to add new template or adjust matching criteria
|
|
|
|
## Architecture Improvements in v1.2.0
|
|
|
|
### Context-Safe Design
|
|
|
|
The workflow now uses a write-as-you-go architecture:
|
|
|
|
- Documents written immediately to disk (not accumulated in memory)
|
|
- Detailed findings purged after writing (only summaries kept)
|
|
- State tracking enables resumption from any step
|
|
- Batching strategy prevents context exhaustion on large projects
|
|
|
|
### Batching Strategy
|
|
|
|
For deep/exhaustive scans:
|
|
|
|
- Process ONE subfolder at a time
|
|
- Read files → Extract info → Write output → Validate → Purge context
|
|
- Primary concern is file SIZE (not count)
|
|
- Track batches in state file for resumability
|
|
|
|
### State File Format
|
|
|
|
Optimized JSON (no pretty-printing):
|
|
|
|
```json
|
|
{
|
|
"workflow_version": "1.2.0",
|
|
"timestamps": {...},
|
|
"mode": "initial_scan",
|
|
"scan_level": "deep",
|
|
"completed_steps": [...],
|
|
"current_step": "step_6",
|
|
"findings": {"summary": "only"},
|
|
"outputs_generated": [...],
|
|
"resume_instructions": "..."
|
|
}
|
|
```
|