Claude-Code-Workflow/.claude/commands/workflow/docs.md

name: docs description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control usage: /workflow:docs [scope] argument-hint: "architecture"|"api"|"all" examples: - /workflow:docs all - /workflow:docs architecture src/modules - /workflow:docs api --scope api/

Workflow Documentation Command

Usage

/workflow:docs <type> [scope]

Input Detection

• Document Types: architecture, api, all → Creates appropriate documentation tasks
• Scope: Optional module/directory filtering → Focuses documentation generation
• Default: all → Complete documentation suite

Core Workflow

Planning & Task Creation Process

The command performs structured planning and task creation:

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

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

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

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
│   ├── module-map.md
│   ├── data-flow.md
│   └── tech-stack.md
└── api/                   # Level 2: Unified API docs
    ├── unified-api.md
    └── 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):

"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):

"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

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

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

Usage Examples

Complete Documentation Workflow

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