catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-14 02:42:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Restructure docs command to follow standard workflow pattern

Browse Source 
- Add pre-planning architecture analysis using get_modules_by_depth.sh
- Convert DOC tasks to IMPL naming for consistency with plan.md
- Update task decomposition to follow 5-field JSON schema
- Add structured session management with IMPL_PLAN.md and TODO_LIST.md
- Fix gemini-wrapper command format to use proper CLI syntax
- Integrate with workflow:execute for task-based documentation generation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-18 19:48:01 +08:00
parent f39f1082d7
commit a4dc217a53
1 changed files with 151 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
.claude/commands/workflow/docs.md
View File

@@ -9,24 +9,40 @@ examples:
- /workflow:docs api --scope api/ - /workflow:docs api --scope api/
--- ---
# Hierarchical Documentation Generator # Workflow Documentation Command
## Usage ## Usage
```bash ```bash
/workflow:docs <type> [scope] /workflow:docs <type> [scope]
``` ```
## Document Types ## Input Detection
- **architecture**: System architecture documentation (bottom-up analysis) - **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
- **api**: API interface documentation (module-first approach) - **Scope**: Optional module/directory filtering → Focuses documentation generation
- **all**: Complete documentation suite with full hierarchy (default) - **Default**: `all` → Complete documentation suite
## Generation Strategy ## Core Workflow
Uses **doc-generator agent** with **flow_control** for structured documentation generation:
1. Agent receives task with embedded flow_control structure ### Planning & Task Creation Process
2. Agent executes pre_analysis steps using CLI tools The command performs structured planning and task creation:
3. Agent generates hierarchical documentation (module → system)
4. Agent tracks progress with TodoWrite throughout process **0. Pre-Planning Architecture Analysis** ⚠️ FIRST STEP
- **System Structure Analysis**: Run `bash(~/.claude/scripts/get_modules_by_depth.sh)` to discover project hierarchy
- **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
**1. Documentation Planning**
- **Type Analysis**: Determine documentation scope (architecture/api/all)
- **Module Discovery**: Use architecture analysis results to identify components
- **Task Decomposition**: Break documentation into manageable tasks based on discovered structure
- **Session Management**: Create or use existing documentation session
**2. Task Generation**
- **Create session**: `.workflow/WFS-docs-[timestamp]/`
- **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
## Output Structure ## Output Structure
``` ```
@@ -49,91 +65,119 @@ Uses **doc-generator agent** with **flow_control** for structured documentation
└── openapi.yaml └── openapi.yaml
``` ```
## Complete Documentation Generation (All Types) ## Task Decomposition Standards
### Agent Task Invocation ### Documentation Task Types
```bash **IMPL-001**: System Overview Documentation
Task( - Project structure analysis
description="Generate complete system documentation", - Technology stack documentation
prompt="[FLOW_CONTROL] You are the doc-generator agent tasked with creating comprehensive system documentation. Execute the embedded flow_control structure for hierarchical documentation generation. - Main navigation creation
Your flow_control includes these pre_analysis steps: **IMPL-002**: Module Documentation (per module)
1. Initialize TodoWrite tracking for documentation process - Individual module analysis
2. Discover project modules using bash commands - API surface documentation
3. Analyze project structure with gemini-wrapper - Dependencies and relationships
4. Perform deep module analysis with gemini-wrapper - Usage examples
5. Scan API endpoints using bash/rg commands
6. Analyze API structure with gemini-wrapper
After pre_analysis, generate documentation: **IMPL-003**: Architecture Documentation
- Create module documentation in .workflow/docs/modules/ - System design patterns
- Generate architecture docs in .workflow/docs/architecture/ - Module interaction mapping
- Create unified API docs in .workflow/docs/api/ - Data flow documentation
- Build main navigation in .workflow/docs/README.md - Design principles
Use TodoWrite to track progress and update status as you complete each phase.", **IMPL-004**: API Documentation
subagent_type="doc-generator" - 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/WFS-docs-[timestamp]/
├── 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
``` ```
## Architecture-Only Documentation ### Task Flow Control Templates
### Agent Task for Architecture Focus **System Overview Task (IMPL-001)**:
```bash ```json
Task( "flow_control": {
description="Generate architecture documentation", "pre_analysis": [
prompt="[FLOW_CONTROL] You are the doc-generator agent focused on architecture documentation. {
"step": "system_architecture_analysis",
Execute flow_control with these pre_analysis steps: "action": "Discover system architecture and module hierarchy",
1. Initialize TodoWrite for architecture documentation tracking "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
2. Analyze system architecture with gemini-wrapper using comprehensive architectural analysis rules "output_to": "system_structure"
3. Generate architecture documentation in .workflow/docs/architecture/ },
{
Focus on system design, module relationships, and technology stack documentation.", "step": "project_discovery",
subagent_type="doc-generator" "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"]
}
``` ```
## API-Only Documentation **Module Documentation Task (IMPL-002)**:
```json
### Agent Task for API Focus "flow_control": {
```bash "pre_analysis": [
Task( {
description="Generate API documentation", "step": "load_system_structure",
prompt="[FLOW_CONTROL] You are the doc-generator agent focused on API documentation. "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)",
Execute flow_control with these pre_analysis steps: "output_to": "system_context"
1. Initialize TodoWrite for API documentation tracking },
2. Scan for API endpoints using bash/rg commands {
3. Analyze API patterns with gemini-wrapper for comprehensive documentation "step": "module_analysis",
4. Generate API documentation in .workflow/docs/api/ "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]\"",
Create complete API reference with OpenAPI specifications and usage examples.", "output_to": "module_context"
subagent_type="doc-generator" }
) ],
"target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
}
``` ```
## Flow Control Templates
The doc-generator agent internally uses these flow_control structures:
### Complete Documentation Flow Control
- **initialize_tracking**: Set up TodoWrite progress tracking
- **discover_modules**: Find project modules with bash commands
- **analyze_project_structure**: Comprehensive analysis with gemini-wrapper
- **analyze_individual_modules**: Deep module analysis with gemini-wrapper
- **scan_api_endpoints**: API endpoint discovery with bash/rg
- **analyze_api_structure**: API documentation with gemini-wrapper
### Architecture Flow Control
- **initialize_architecture_tracking**: TodoWrite setup for architecture
- **analyze_architecture**: System architecture analysis with gemini-wrapper
### API Flow Control
- **initialize_api_tracking**: TodoWrite setup for API documentation
- **scan_apis**: API endpoint scanning with bash/rg
- **analyze_api_patterns**: API documentation with gemini-wrapper
## Analysis Templates ## Analysis Templates
### Project Structure Analysis Rules ### Project Structure Analysis Rules
@@ -160,51 +204,36 @@ The doc-generator agent internally uses these flow_control structures:
- Create comprehensive endpoint documentation - Create comprehensive endpoint documentation
- Provide usage examples and integration guides - Provide usage examples and integration guides
## Integration with Workflow System ## Error Handling
- **Invalid document type**: Clear error message with valid options
### Automatic Context Loading - **Module not found**: Skip missing modules with warning
- Generated documentation serves as context for `/workflow:plan` and `/workflow:execute` - **Analysis failures**: Fall back to file-based analysis
- Documentation provides single source of truth for system understanding - **Permission issues**: Clear guidance on directory access
- Other workflow commands automatically reference `.workflow/docs/` for context
### Progressive Enhancement
- Documentation builds incrementally from modules to system
- Individual modules can be re-documented as needed
- System documentation synthesizes from module-level understanding
## Key Benefits ## Key Benefits
### Agent + Flow Control Architecture ### Structured Documentation Process
- **Unified Execution**: All documentation generation through doc-generator agent - **Task-based approach**: Documentation broken into manageable, trackable tasks
- **Structured Analysis**: Flow control ensures systematic context gathering - **Flow control integration**: Systematic analysis ensures completeness
- **CLI Tool Integration**: Agent uses bash, gemini-wrapper, and codex internally - **Progress visibility**: TODO_LIST.md provides clear completion status
- **Progress Tracking**: TodoWrite provides visibility throughout process - **Quality assurance**: Each task has defined acceptance criteria
### Hierarchical Documentation ### Workflow Integration
- **Bottom-up Analysis**: Start with detailed module understanding - **Planning foundation**: Documentation provides context for implementation planning
- **System Synthesis**: Build unified documentation from module knowledge - **Execution consistency**: Same task execution model as implementation
- **Two-level Architecture**: Module-level and system-level documentation - **Context accumulation**: Documentation builds comprehensive project understanding
### Quality and Consistency
- **Flow Control Ensures Completeness**: Structured analysis prevents missing components
- **Agent Expertise**: Specialized doc-generator provides consistent quality
- **Tool Optimization**: Right tool for each analysis phase
- **Error Recovery**: Progress tracking enables recovery from failures
## Usage Examples ## Usage Examples
### Complete Documentation Workflow
```bash ```bash
# Generate complete documentation suite # Step 1: Create documentation plan and tasks
/workflow:docs all /workflow:docs all
# Generate only architecture documentation # Step 2: Execute documentation tasks (after planning)
/workflow:docs architecture /workflow:execute IMPL-001 # System overview
/workflow:execute IMPL-002 # Module documentation
# Generate only API documentation /workflow:execute IMPL-003 # Architecture documentation
/workflow:docs api /workflow:execute IMPL-004 # API documentation
# Generate scoped documentation
/workflow:docs architecture src/core,src/auth
``` ```
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.
The system executes the appropriate agent task with embedded flow_control, ensuring systematic and comprehensive documentation generation.