mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
Refactor documentation workflow and templates
- Updated `/workflow:docs` command to enhance documentation planning and orchestration. - Introduced new parameters for tool selection and scope filtering. - Separated documentation planning from content generation, clarifying roles of docs.md and doc-generator.md. - Added detailed planning process phases, including session initialization, project structure analysis, and task decomposition. - Created new templates for API, module, and project-level documentation, ensuring comprehensive coverage and consistency. - Enhanced output structure for better organization of generated documentation. - Implemented error handling and completion checklist for improved user experience.
This commit is contained in:
catlog22
@@ -1,256 +1,564 @@
|
||||
---
|
||||
name: docs
|
||||
description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
|
||||
usage: /workflow:docs <type> [scope]
|
||||
argument-hint: "architecture"|"api"|"all"
|
||||
description: Documentation planning and orchestration - creates structured documentation tasks for execution
|
||||
usage: /workflow:docs <type> [options]
|
||||
argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||
examples:
|
||||
- /workflow:docs all
|
||||
- /workflow:docs architecture src/modules
|
||||
- /workflow:docs api --scope api/
|
||||
- /workflow:docs all # Complete documentation (gemini default)
|
||||
- /workflow:docs all --tool qwen # Use Qwen for architecture focus
|
||||
- /workflow:docs architecture --scope src/modules
|
||||
- /workflow:docs api --tool gemini --scope api/
|
||||
---
|
||||
|
||||
# Workflow Documentation Command
|
||||
|
||||
## Purpose
|
||||
|
||||
**`/workflow:docs` is a pure planner/orchestrator** - it analyzes project structure, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself.
|
||||
|
||||
**Key Principle**: Separation of Concerns
|
||||
- **docs.md** → Planning, session creation, task generation
|
||||
- **doc-generator.md** → Execution, content generation, quality assurance
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:docs <type> [scope]
|
||||
/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||
```
|
||||
|
||||
## Input Detection
|
||||
- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
|
||||
- **Scope**: Optional module/directory filtering → Focuses documentation generation
|
||||
- **Default**: `all` → Complete documentation suite
|
||||
### Parameters
|
||||
- **type**: `architecture` | `api` | `all` (required)
|
||||
- `architecture`: System design, module interactions, patterns
|
||||
- `api`: Endpoint documentation, API specifications
|
||||
- `all`: Complete documentation suite
|
||||
- **--tool**: `gemini` | `qwen` | `codex` (optional, default: gemini)
|
||||
- `gemini`: Comprehensive documentation, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design focus
|
||||
- `codex`: Implementation validation, code quality
|
||||
- **--scope**: Directory path filter (optional)
|
||||
|
||||
## Core Workflow
|
||||
## Planning Process
|
||||
|
||||
### Planning & Task Creation Process
|
||||
The command performs structured planning and task creation:
|
||||
### Phase 1: Session Initialization
|
||||
```bash
|
||||
# 1. Parse user input
|
||||
doc_type="all" # architecture|api|all
|
||||
tool="gemini" # gemini|qwen|codex (default: gemini)
|
||||
scope="" # optional path filter
|
||||
|
||||
**0. Pre-Planning Architecture Analysis** ⚠️ MANDATORY FIRST STEP
|
||||
- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
|
||||
- **Module Boundary Identification**: Understand module organization and dependencies
|
||||
- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
|
||||
- **Foundation for documentation**: Use structure analysis to guide task decomposition
|
||||
# Extract from command arguments
|
||||
[[ "$*" == *"architecture"* ]] && doc_type="architecture"
|
||||
[[ "$*" == *"api"* ]] && doc_type="api"
|
||||
[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
|
||||
[[ "$*" == *"--tool codex"* ]] && tool="codex"
|
||||
[[ "$*" =~ --scope[[:space:]]+([^[:space:]]+) ]] && scope="${BASH_REMATCH[1]}"
|
||||
|
||||
**1. Documentation Planning**
|
||||
- **Type Analysis**: Determine documentation scope (architecture/api/all)
|
||||
- **Module Discovery**: Use architecture analysis results to identify components
|
||||
- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
|
||||
- **Session Management**: Create or use existing documentation session
|
||||
# 2. Create session structure
|
||||
timestamp=$(date +%Y%m%d-%H%M%S)
|
||||
session_dir=".workflow/WFS-docs-${timestamp}"
|
||||
mkdir -p "${session_dir}"/{.task,.process,.summaries}
|
||||
|
||||
**2. Task Generation**
|
||||
- **Create session**: `.workflow/WFS-docs-[timestamp]/`
|
||||
- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
|
||||
- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
|
||||
- **Create task.json files**: Individual documentation tasks with flow_control
|
||||
- **Setup TODO_LIST.md**: Progress tracking for documentation generation
|
||||
# 3. Create active marker
|
||||
touch ".workflow/.active-WFS-docs-${timestamp}"
|
||||
```
|
||||
|
||||
### Session Management ⚠️ CRITICAL
|
||||
- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
|
||||
- **Marker naming**: Active marker must exactly match session folder name
|
||||
- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
|
||||
- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
|
||||
- **Session isolation**: Each documentation session maintains independent context and state
|
||||
### Phase 2: Project Structure Analysis (MANDATORY)
|
||||
```bash
|
||||
# Run get_modules_by_depth.sh for module hierarchy
|
||||
module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
|
||||
# Parse module information
|
||||
# Format: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no
|
||||
```
|
||||
|
||||
### Phase 3: Pre-Planning Analysis (Optional)
|
||||
Uses selected tool to analyze existing documentation and suggest improvements:
|
||||
|
||||
```bash
|
||||
if [[ "$tool" == "codex" ]]; then
|
||||
# Codex: Direct exec
|
||||
codex -C . --full-auto exec "
|
||||
PURPOSE: Analyze documentation strategy
|
||||
TASK: Review existing docs and suggest improvements for ${doc_type}
|
||||
MODE: analysis
|
||||
CONTEXT: @{CLAUDE.md,**/*CLAUDE.md,docs/**/*}
|
||||
EXPECTED: Gap analysis and recommendations
|
||||
RULES: Focus on clarity, completeness, architectural alignment
|
||||
" --skip-git-repo-check > "${session_dir}/.process/pre-analysis.md"
|
||||
else
|
||||
# Gemini/Qwen: Wrapper
|
||||
cd .workflow && ~/.claude/scripts/${tool}-wrapper -p "
|
||||
PURPOSE: Analyze documentation strategy
|
||||
TASK: Review existing docs and suggest improvements for ${doc_type}
|
||||
MODE: analysis
|
||||
CONTEXT: @{../CLAUDE.md,../**/*CLAUDE.md,../docs/**/*}
|
||||
EXPECTED: Gap analysis and recommendations
|
||||
RULES: Focus on clarity, completeness, architectural alignment
|
||||
" > "${session_dir}/.process/pre-analysis.md"
|
||||
fi
|
||||
```
|
||||
|
||||
### Phase 4: Task Decomposition
|
||||
|
||||
**Decomposition Strategy**:
|
||||
1. **Always create**: System Overview task (IMPL-001)
|
||||
2. **If architecture/all**: Architecture Documentation task
|
||||
3. **If api/all**: Unified API Documentation task
|
||||
4. **For each module**: Module Documentation task (grouped for efficiency)
|
||||
|
||||
**Grouping Rules**:
|
||||
- Max 3 modules per task
|
||||
- Max 30 files per task
|
||||
- Group by dependency depth and functional similarity
|
||||
|
||||
**Task Count Formula**:
|
||||
```
|
||||
base_tasks = 1 (system overview)
|
||||
+ (doc_type includes "architecture" ? 1 : 0)
|
||||
+ (doc_type includes "api" ? 1 : 0)
|
||||
+ ceil(module_count / 3)
|
||||
```
|
||||
|
||||
### Phase 5: Task JSON Generation
|
||||
|
||||
Each task follows the 5-field schema with detailed flow_control.
|
||||
|
||||
#### Command Generation Logic
|
||||
|
||||
At planning time, commands are built based on the `$tool` variable:
|
||||
|
||||
```bash
|
||||
# Build tool-specific command for pre_analysis step
|
||||
build_analysis_command() {
|
||||
local step_name="$1"
|
||||
local context_path="$2"
|
||||
local template_path="$3"
|
||||
local output_var="$4"
|
||||
|
||||
if [[ "$tool" == "codex" ]]; then
|
||||
# Codex: direct exec with -C directory
|
||||
echo "codex -C ${context_path} --full-auto exec \"PURPOSE: ...\\nTASK: ...\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: ...\\nRULES: \$(cat ${template_path})\" --skip-git-repo-check"
|
||||
else
|
||||
# Gemini/Qwen: wrapper with -p
|
||||
echo "bash(cd ${context_path} && ~/.claude/scripts/${tool}-wrapper -p \"PURPOSE: ...\\nTASK: ...\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: ...\\nRULES: \$(cat ${template_path})\")"
|
||||
fi
|
||||
}
|
||||
|
||||
# Usage in task JSON generation
|
||||
analyze_cmd=$(build_analysis_command "analyze_module" "src/auth" \
|
||||
"~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt" \
|
||||
"module_analysis")
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- **Default tool**: `gemini`
|
||||
- **Template reference**: Use `$(cat template_path.txt)` to embed template content
|
||||
- **One command per step**: No conditional blocks, command is concrete
|
||||
- **Tool selection happens at planning time**, not execution time
|
||||
|
||||
#### IMPL-001: System Overview Task
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate Project Overview Documentation",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "project-overview"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document project purpose, architecture, and getting started guide",
|
||||
"Create navigation structure for all documentation",
|
||||
"Use Project-Level Documentation Template"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/README.md following template",
|
||||
"All template sections populated with accurate information",
|
||||
"Navigation links to module and API documentation"
|
||||
],
|
||||
"scope": "Project root and overall structure"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "discover_project_structure",
|
||||
"action": "Analyze project structure and modules",
|
||||
"command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_structure"
|
||||
},
|
||||
{
|
||||
"step": "discover_project_files",
|
||||
"action": "Identify key project files",
|
||||
"command": "bash(find . -maxdepth 2 -type f \\( -name '*.json' -o -name '*.md' -o -name '*.yml' -o -name '*.yaml' \\) | head -30)",
|
||||
"output_to": "project_files"
|
||||
},
|
||||
{
|
||||
"step": "analyze_tech_stack",
|
||||
"action": "Analyze technology stack and dependencies",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack, architecture patterns, design principles\\nMODE: analysis\\nCONTEXT: System structure: [system_structure]\\n Project files: [project_files]\\nEXPECTED: Technology analysis with architecture style\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt)\")",
|
||||
"output_to": "tech_analysis",
|
||||
"note": "Command is built at planning time based on $tool variable (gemini/qwen/codex)"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use tech_analysis to populate Project-Level Documentation Template",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt",
|
||||
"Parse tech_analysis for: purpose, architecture, tech stack, design principles",
|
||||
"Fill template sections with extracted information",
|
||||
"Generate navigation links to module/API docs",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [".workflow/docs/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### IMPL-002+: Module Documentation Tasks
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Document Module: 'auth'",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "module-documentation"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document module purpose, internal architecture, public API",
|
||||
"Include dependencies and usage examples",
|
||||
"Use Module-Level Documentation Template"
|
||||
],
|
||||
"focus_paths": ["src/auth"],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/modules/auth/README.md",
|
||||
"All exported functions/classes documented",
|
||||
"Working code examples included"
|
||||
],
|
||||
"scope": "auth module only"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_system_context",
|
||||
"action": "Load system architecture from IMPL-001",
|
||||
"command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_context"
|
||||
},
|
||||
{
|
||||
"step": "analyze_module_structure",
|
||||
"action": "Deep analysis of module structure and API",
|
||||
"command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\n System: [system_context]\\nEXPECTED: Complete module analysis for documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
|
||||
"output_to": "module_analysis",
|
||||
"note": "For qwen: qwen-wrapper | For codex: codex -C src/auth --full-auto exec \"...\" --skip-git-repo-check"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use module_analysis to populate Module-Level Documentation Template",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt",
|
||||
"Parse module_analysis for: purpose, components, API, dependencies",
|
||||
"Fill template sections with extracted information",
|
||||
"Generate code examples from actual usage",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [".workflow/docs/modules/auth/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Architecture Documentation Task (if requested)
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N-1",
|
||||
"title": "Generate Architecture Documentation",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "qwen",
|
||||
"template": "architecture"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document system design patterns and architectural decisions",
|
||||
"Create module interaction diagrams",
|
||||
"Explain data flow and component relationships"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"acceptance": [
|
||||
"Complete architecture documentation in .workflow/docs/architecture/",
|
||||
"Diagrams explaining system design",
|
||||
"Clear explanation of architectural patterns"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_module_docs",
|
||||
"action": "Aggregate all module documentation",
|
||||
"command": "bash(find .workflow/docs/modules -name 'README.md' -exec cat {} \\;)",
|
||||
"output_to": "module_docs"
|
||||
},
|
||||
{
|
||||
"step": "analyze_architecture",
|
||||
"action": "Synthesize system architecture from modules",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create architecture documentation from module docs\\nMODE: analysis\\nCONTEXT: [module_docs]\\nEXPECTED: Architecture documentation with patterns\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt) | Focus on design patterns, data flow, component interactions\")",
|
||||
"output_to": "architecture_analysis",
|
||||
"note": "Command varies: gemini-wrapper (default) | qwen-wrapper | codex exec"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Create architecture documentation from synthesis",
|
||||
"logic_flow": [
|
||||
"Parse architecture_analysis for patterns and design decisions",
|
||||
"Create text-based diagrams (mermaid/ASCII) for module interactions",
|
||||
"Document data flow between components",
|
||||
"Explain architectural decisions and trade-offs",
|
||||
"Format as structured documentation"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
".workflow/docs/architecture/system-design.md",
|
||||
".workflow/docs/architecture/module-map.md",
|
||||
".workflow/docs/architecture/data-flow.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### API Documentation Task (if requested)
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N",
|
||||
"title": "Generate Unified API Documentation",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "api-reference"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document all API endpoints with request/response formats",
|
||||
"Include authentication and error handling",
|
||||
"Generate OpenAPI specification if applicable",
|
||||
"Use API-Level Documentation Template"
|
||||
],
|
||||
"focus_paths": ["src/api", "src/routes", "src/controllers"],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/api/README.md following template",
|
||||
"All endpoints documented with examples",
|
||||
"OpenAPI spec generated if REST API detected"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "discover_api_endpoints",
|
||||
"action": "Find all API routes and endpoints",
|
||||
"command": "bash(rg -t ts -t js '(router\\.|app\\.|@(Get|Post|Put|Delete|Patch))' src/ --no-heading | head -100)",
|
||||
"output_to": "endpoint_discovery"
|
||||
},
|
||||
{
|
||||
"step": "analyze_api_structure",
|
||||
"action": "Analyze API structure and patterns",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\n Endpoints: [endpoint_discovery]\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")",
|
||||
"output_to": "api_analysis",
|
||||
"note": "Tool-specific: gemini-wrapper | qwen-wrapper | codex -C src/api exec"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use api_analysis to populate API-Level Documentation Template",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt",
|
||||
"Parse api_analysis for: endpoints, auth, request/response",
|
||||
"Fill template sections with extracted information",
|
||||
"Generate OpenAPI spec if REST API detected",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
".workflow/docs/api/README.md",
|
||||
".workflow/docs/api/openapi.yaml"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 6: Generate Planning Documents
|
||||
|
||||
#### IMPL_PLAN.md
|
||||
```markdown
|
||||
# Documentation Implementation Plan
|
||||
|
||||
**Session**: WFS-docs-[timestamp]
|
||||
**Type**: [architecture|api|all]
|
||||
**Tool**: [gemini|qwen|codex]
|
||||
**Scope**: [scope or "Full project"]
|
||||
|
||||
## Documentation Strategy
|
||||
|
||||
### Pre-Analysis Findings
|
||||
[Summary from .process/pre-analysis.md]
|
||||
|
||||
### Documentation Scope
|
||||
- System Overview: Yes
|
||||
- Module Documentation: [N] modules
|
||||
- Architecture Documentation: [Yes/No]
|
||||
- API Documentation: [Yes/No]
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
### IMPL-001: System Overview
|
||||
- **Purpose**: Project-level documentation
|
||||
- **Template**: project-overview.txt
|
||||
- **Output**: .workflow/docs/README.md
|
||||
|
||||
### IMPL-002 to IMPL-[M]: Module Documentation
|
||||
[For each module or module group]
|
||||
- **Module(s)**: [module-name(s)]
|
||||
- **Template**: module-documentation.txt
|
||||
- **Output**: .workflow/docs/modules/[module]/README.md
|
||||
|
||||
### IMPL-[M+1]: Architecture Documentation (if requested)
|
||||
- **Purpose**: System design and patterns
|
||||
- **Output**: .workflow/docs/architecture/
|
||||
|
||||
### IMPL-[N]: API Documentation (if requested)
|
||||
- **Purpose**: API reference and specifications
|
||||
- **Template**: api-reference.txt
|
||||
- **Output**: .workflow/docs/api/README.md
|
||||
|
||||
## Execution Order
|
||||
1. IMPL-001 (Foundation - provides system context)
|
||||
2. IMPL-002 to IMPL-[M] (Modules - can be parallelized)
|
||||
3. IMPL-[M+1] (Architecture - requires module docs)
|
||||
4. IMPL-[N] (API - can run after IMPL-001)
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All template sections populated
|
||||
- [ ] Code examples tested and working
|
||||
- [ ] Navigation links functional
|
||||
- [ ] Documentation follows project standards
|
||||
- [ ] No broken references
|
||||
```
|
||||
|
||||
#### TODO_LIST.md
|
||||
```markdown
|
||||
# Documentation Progress Tracker
|
||||
|
||||
**Session**: WFS-docs-[timestamp]
|
||||
**Created**: [timestamp]
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] **IMPL-001**: Generate Project Overview Documentation
|
||||
- [ ] **IMPL-002**: Document Module: 'auth'
|
||||
- [ ] **IMPL-003**: Document Module: 'api'
|
||||
- [ ] **IMPL-004**: Generate Architecture Documentation
|
||||
- [ ] **IMPL-005**: Generate Unified API Documentation
|
||||
|
||||
## Execution Instructions
|
||||
|
||||
```bash
|
||||
# Execute tasks in order (or parallelize modules)
|
||||
/workflow:execute IMPL-001 # System overview (run first)
|
||||
/workflow:execute IMPL-002 # Module: auth
|
||||
/workflow:execute IMPL-003 # Module: api
|
||||
/workflow:execute IMPL-004 # Architecture (after modules)
|
||||
/workflow:execute IMPL-005 # API docs
|
||||
```
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
After all tasks complete:
|
||||
- [ ] Review all generated documentation
|
||||
- [ ] Test all code examples
|
||||
- [ ] Verify navigation links
|
||||
- [ ] Check for consistency
|
||||
- [ ] Update main project README.md with docs link
|
||||
```
|
||||
|
||||
## Output Structure
|
||||
|
||||
After planning, the session structure is:
|
||||
|
||||
```
|
||||
.workflow/
|
||||
├── .active-WFS-docs-20240120-143022 # Active session marker
|
||||
└── WFS-docs-20240120-143022/ # Documentation session
|
||||
├── IMPL_PLAN.md # Implementation plan
|
||||
├── TODO_LIST.md # Progress tracker
|
||||
├── .process/
|
||||
│ └── pre-analysis.md # Pre-planning analysis
|
||||
└── .task/
|
||||
├── IMPL-001.json # System overview task
|
||||
├── IMPL-002.json # Module: auth task
|
||||
├── IMPL-003.json # Module: api task
|
||||
├── IMPL-004.json # Architecture task
|
||||
└── IMPL-005.json # API docs task
|
||||
```
|
||||
|
||||
Documentation output structure:
|
||||
```
|
||||
.workflow/docs/
|
||||
├── README.md # System navigation
|
||||
├── modules/ # Level 1: Module documentation
|
||||
│ ├── [module-1]/
|
||||
│ │ ├── overview.md
|
||||
│ │ ├── api.md
|
||||
│ │ ├── dependencies.md
|
||||
│ │ └── examples.md
|
||||
│ └── [module-n]/...
|
||||
├── architecture/ # Level 2: System architecture
|
||||
│ ├── system-design.md
|
||||
├── README.md # From IMPL-001
|
||||
├── modules/
|
||||
│ ├── auth/
|
||||
│ │ └── README.md # From IMPL-002
|
||||
│ └── api/
|
||||
│ └── README.md # From IMPL-003
|
||||
├── architecture/
|
||||
│ ├── system-design.md # From IMPL-004
|
||||
│ ├── module-map.md
|
||||
│ ├── data-flow.md
|
||||
│ └── tech-stack.md
|
||||
└── api/ # Level 2: Unified API docs
|
||||
├── unified-api.md
|
||||
│ └── data-flow.md
|
||||
└── api/
|
||||
├── README.md # From IMPL-005
|
||||
└── openapi.yaml
|
||||
```
|
||||
|
||||
## Task Decomposition Standards
|
||||
|
||||
### Dynamic Task Planning Rules
|
||||
**Module Grouping**: Max 3 modules per task, max 30 files per task
|
||||
**Task Count**: Calculate based on `total_modules ÷ 3 (rounded up) + base_tasks`
|
||||
**File Limits**: Split tasks when file count exceeds 30 in any module group
|
||||
**Base Tasks**: System overview (1) + Architecture (1) + API consolidation (1)
|
||||
**Module Tasks**: Group related modules by dependency depth and functional similarity
|
||||
|
||||
### Documentation Task Types
|
||||
**IMPL-001**: System Overview Documentation
|
||||
- Project structure analysis
|
||||
- Technology stack documentation
|
||||
- Main navigation creation
|
||||
|
||||
**IMPL-002**: Module Documentation (per module)
|
||||
- Individual module analysis
|
||||
- API surface documentation
|
||||
- Dependencies and relationships
|
||||
- Usage examples
|
||||
|
||||
**IMPL-003**: Architecture Documentation
|
||||
- System design patterns
|
||||
- Module interaction mapping
|
||||
- Data flow documentation
|
||||
- Design principles
|
||||
|
||||
**IMPL-004**: API Documentation
|
||||
- Endpoint discovery and analysis
|
||||
- OpenAPI specification generation
|
||||
- Authentication documentation
|
||||
- Integration examples
|
||||
|
||||
### Task JSON Schema (5-Field Architecture)
|
||||
Each documentation task uses the workflow-architecture.md 5-field schema:
|
||||
- **id**: IMPL-N format
|
||||
- **title**: Documentation task name
|
||||
- **status**: pending|active|completed|blocked
|
||||
- **meta**: { type: "documentation", agent: "@doc-generator" }
|
||||
- **context**: { requirements, focus_paths, acceptance, scope }
|
||||
- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }
|
||||
|
||||
## Document Generation
|
||||
|
||||
### Workflow Process
|
||||
**Input Analysis** → **Session Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** → **Execute Tasks**
|
||||
|
||||
**Always Created**:
|
||||
- **IMPL_PLAN.md**: Documentation requirements and task breakdown
|
||||
- **Session state**: Task references and documentation paths
|
||||
|
||||
**Auto-Created (based on scope)**:
|
||||
- **TODO_LIST.md**: Progress tracking for documentation tasks
|
||||
- **.task/IMPL-*.json**: Individual documentation tasks with flow_control
|
||||
- **.process/ANALYSIS_RESULTS.md**: Documentation analysis artifacts
|
||||
|
||||
**Document Structure**:
|
||||
```
|
||||
.workflow/
|
||||
├── .active-WFS-docs-20231201-143022 # Active session marker (matches folder name)
|
||||
└── WFS-docs-20231201-143022/ # Documentation session folder
|
||||
├── IMPL_PLAN.md # Main documentation plan
|
||||
├── TODO_LIST.md # Progress tracking
|
||||
├── .process/
|
||||
│ └── ANALYSIS_RESULTS.md # Documentation analysis
|
||||
└── .task/
|
||||
├── IMPL-001.json # System overview task
|
||||
├── IMPL-002.json # Module documentation task
|
||||
├── IMPL-003.json # Architecture documentation task
|
||||
└── IMPL-004.json # API documentation task
|
||||
```
|
||||
|
||||
### Task Flow Control Templates
|
||||
|
||||
**System Overview Task (IMPL-001)**:
|
||||
```json
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "system_architecture_analysis",
|
||||
"action": "Discover system architecture and module hierarchy",
|
||||
"command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_structure"
|
||||
},
|
||||
{
|
||||
"step": "project_discovery",
|
||||
"action": "Discover project structure and entry points",
|
||||
"command": "bash(find . -type f -name '*.json' -o -name '*.md' -o -name 'package.json' | head -20)",
|
||||
"output_to": "project_structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_tech_stack",
|
||||
"action": "Analyze technology stack and dependencies using structure analysis",
|
||||
"command": "~/.claude/scripts/gemini-wrapper -p \"Analyze project technology stack and dependencies based on: [system_structure]\"",
|
||||
"output_to": "tech_analysis"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/README.md"]
|
||||
}
|
||||
```
|
||||
|
||||
**Module Documentation Task (IMPL-002)**:
|
||||
```json
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_system_structure",
|
||||
"action": "Load system architecture analysis from previous task",
|
||||
"command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_context"
|
||||
},
|
||||
{
|
||||
"step": "module_analysis",
|
||||
"action": "Analyze specific module structure and API within system context",
|
||||
"command": "~/.claude/scripts/gemini-wrapper -p \"Analyze module [MODULE_NAME] structure and exported API within system: [system_context]\"",
|
||||
"output_to": "module_context"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
|
||||
}
|
||||
```
|
||||
|
||||
## Analysis Templates
|
||||
|
||||
### Project Structure Analysis Rules
|
||||
- Identify main modules and purposes
|
||||
- Map directory organization patterns
|
||||
- Extract entry points and configuration files
|
||||
- Recognize architectural styles and design patterns
|
||||
- Analyze module relationships and dependencies
|
||||
- Document technology stack and requirements
|
||||
|
||||
### Module Analysis Rules
|
||||
- Identify module boundaries and entry points
|
||||
- Extract exported functions, classes, interfaces
|
||||
- Document internal organization and structure
|
||||
- Analyze API surfaces with types and parameters
|
||||
- Map dependencies within and between modules
|
||||
- Extract usage patterns and examples
|
||||
|
||||
### API Analysis Rules
|
||||
- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
|
||||
- Extract request/response parameters and schemas
|
||||
- Document authentication and authorization requirements
|
||||
- Generate OpenAPI 3.0 specification structure
|
||||
- Create comprehensive endpoint documentation
|
||||
- Provide usage examples and integration guides
|
||||
|
||||
## Error Handling
|
||||
- **Invalid document type**: Clear error message with valid options
|
||||
- **Module not found**: Skip missing modules with warning
|
||||
- **Analysis failures**: Fall back to file-based analysis
|
||||
- **Permission issues**: Clear guidance on directory access
|
||||
|
||||
- **No modules found**: Create only IMPL-001 (system overview)
|
||||
- **Scope path invalid**: Show error and exit
|
||||
- **Active session exists**: Prompt user to complete or pause current session
|
||||
- **Tool unavailable**: Fall back to gemini
|
||||
|
||||
## Next Steps
|
||||
|
||||
After running `/workflow:docs`:
|
||||
1. Review generated `IMPL_PLAN.md` and `TODO_LIST.md`
|
||||
2. Execute tasks using `/workflow:execute IMPL-NNN`
|
||||
3. Tasks can be parallelized (modules) or run sequentially
|
||||
4. Review completed documentation in `.workflow/docs/`
|
||||
|
||||
## Key Benefits
|
||||
|
||||
### Structured Documentation Process
|
||||
- **Task-based approach**: Documentation broken into manageable, trackable tasks
|
||||
- **Flow control integration**: Systematic analysis ensures completeness
|
||||
- **Progress visibility**: TODO_LIST.md provides clear completion status
|
||||
- **Quality assurance**: Each task has defined acceptance criteria
|
||||
### Clear Separation of Concerns
|
||||
- **Planning** (docs.md): Session creation, task decomposition, no content generation
|
||||
- **Execution** (doc-generator.md): Content generation, template application, quality assurance
|
||||
|
||||
### Workflow Integration
|
||||
- **Planning foundation**: Documentation provides context for implementation planning
|
||||
- **Execution consistency**: Same task execution model as implementation
|
||||
- **Context accumulation**: Documentation builds comprehensive project understanding
|
||||
### Scalable Task Management
|
||||
- Each documentation task is independent and self-contained
|
||||
- Tasks can be parallelized for faster completion
|
||||
- Clear dependencies (e.g., architecture requires module docs)
|
||||
|
||||
## Usage Examples
|
||||
### Template-Driven Consistency
|
||||
- All documentation follows standard templates
|
||||
- Templates are reusable and maintainable
|
||||
- Easy to update documentation standards
|
||||
|
||||
### Complete Documentation Workflow
|
||||
```bash
|
||||
# Step 1: Create documentation plan and tasks
|
||||
/workflow:docs all
|
||||
|
||||
# Step 2: Execute documentation tasks (after planning)
|
||||
/workflow:execute IMPL-001 # System overview
|
||||
/workflow:execute IMPL-002 # Module documentation
|
||||
/workflow:execute IMPL-003 # Architecture documentation
|
||||
/workflow:execute IMPL-004 # API documentation
|
||||
```
|
||||
The system creates structured documentation tasks with proper session management, task.json files, and integration with the broader workflow system for systematic and trackable documentation generation.
|
||||
### Full Context for Execution
|
||||
- Each task JSON contains complete instructions
|
||||
- flow_control defines exact analysis steps
|
||||
- Conditional tool selection for flexibility
|
||||
|
||||
Reference in New Issue
Block a user