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

name: docs description: Documentation planning and orchestration - creates structured documentation tasks for execution usage: /workflow:docs [options] argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope ] examples: - /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 lightweight planner/orchestrator - it analyzes project structure using metadata tools, decomposes documentation work into tasks, and generates execution plans. It does NOT generate any documentation content itself.

Key Principle: Lightweight Planning + Targeted Execution

• docs.md → Collect metadata (paths, structure), generate task JSONs with path references
• doc-generator.md → Execute targeted analysis on focus_paths, generate content

Optimization Philosophy:

• Planning phase: Minimal context - only metadata (module paths, file lists via get_modules_by_depth.sh and Code Index MCP)
• Task JSON: Store path references, not content
• Execution phase: Targeted deep analysis within focus_paths scope

Usage

/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]

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)

Planning Workflow

Complete Execution Flow

/workflow:docs [type] [--tool] [--scope]
    ↓
Phase 1: Init Session → Create session dir & active marker
    ↓
Phase 2: Module Analysis → Run get_modules_by_depth.sh
    ↓
Phase 3: Quick Assess → Check existing docs
    ↓
Phase 4: Decompose → Create task list & TodoWrite
    ↓
Phase 5: Generate Tasks → Build IMPL-*.json & plans
    ↓
✅ Planning Complete → Show TodoWrite status

Phase Details

Phase 1: Session Initialization

# Parse arguments and create session structure
doc_type="all"  # architecture|api|all
tool="gemini"   # gemini|qwen|codex (default: gemini)
scope=""        # optional path filter

timestamp=$(date +%Y%m%d-%H%M%S)
session_dir=".workflow/WFS-docs-${timestamp}"
mkdir -p "${session_dir}"/{.task,.process,.summaries}
touch ".workflow/.active-WFS-docs-${timestamp}"

Phase 2: Lightweight Metadata Collection (MANDATORY)

# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only)
module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
# Format: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no

# Step 2: Use Code Index MCP for file discovery (optional, for better precision)
# Example: mcp__code-index__find_files(pattern="src/**/")
# This finds directories without loading content

# IMPORTANT: Do NOT read file contents in planning phase
# Only collect: paths, file counts, module structure

Phase 3: Quick Documentation Assessment

# Lightweight check - no heavy analysis
existing_docs=$(find . -maxdepth 2 -name "*.md" -not -path "./.workflow/*" | wc -l)

if [[ $existing_docs -gt 5 ]]; then
    find . -maxdepth 3 -name "*.md" > "${session_dir}/.process/existing-docs.txt"
fi

# Record strategy
cat > "${session_dir}/.process/strategy.md" <<EOF
**Type**: ${doc_type}
**Tool**: ${tool}
**Scope**: ${scope:-"Full project"}
EOF

Phase 4: Task Decomposition & TodoWrite Setup

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)

Grouping Rules:

• Max 3 modules per task
• Max 30 files per task
• Group by dependency depth and functional similarity

TodoWrite Setup:

✅ Session initialization (completed)
⏳ IMPL-001: Project Overview (pending)
⏳ IMPL-002: Module 'auth' (pending)
⏳ IMPL-003: Module 'api' (pending)
⏳ IMPL-004: Architecture Documentation (pending)
⏳ IMPL-005: API Documentation (pending)

Phase 5: Task JSON Generation

Each task follows the 5-field schema with detailed flow_control.

Command Generation Logic:

# Build tool-specific command at planning time
if [[ "$tool" == "codex" ]]; then
    cmd="codex -C ${dir} --full-auto exec \"...\""
else
    cmd="bash(cd ${dir} && ~/.claude/scripts/${tool}-wrapper -p \"...\")"
fi

Task Templates

1. System Overview (IMPL-001)

Purpose: Project-level documentation Output: .workflow/docs/README.md

Complete JSON Structure:

{
  "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": "Get project module hierarchy metadata",
        "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
        "output_to": "system_structure",
        "on_error": "fail",
        "note": "Lightweight metadata only - no file content"
      },
      {
        "step": "analyze_tech_stack",
        "action": "Analyze technology stack from key config files",
        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack from key config files\\nMODE: analysis\\nCONTEXT: @{package.json,pom.xml,build.gradle,requirements.txt,go.mod,Cargo.toml,CLAUDE.md}\\nEXPECTED: Technology list and architecture style\\nRULES: Be concise, focus on stack only\")",
        "output_to": "tech_stack_analysis",
        "on_error": "skip_optional",
        "note": "Only analyze config files - small, controlled context"
      }
    ],
    "implementation_approach": {
      "task_description": "Use system_structure and tech_stack_analysis to populate Project Overview Template",
      "logic_flow": [
        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt",
        "Fill sections using [system_structure] and [tech_stack_analysis]",
        "Generate navigation links based on module paths",
        "Format output as Markdown"
      ]
    },
    "target_files": [".workflow/docs/README.md"]
  }
}

2. Module Documentation (IMPL-002+)

Purpose: Module-level documentation Output: .workflow/docs/modules/[name]/README.md

Complete JSON Structure:

{
  "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": "analyze_module_content",
        "action": "Perform deep analysis of the specific module's content",
        "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document 'auth' module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: Structured analysis of module content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
        "output_to": "module_analysis",
        "on_error": "fail",
        "note": "Analysis strictly limited to focus_paths ('src/auth') - controlled context"
      }
    ],
    "implementation_approach": {
      "task_description": "Use the detailed [module_analysis] to populate the Module-Level Documentation Template",
      "logic_flow": [
        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt",
        "Fill sections using [module_analysis]",
        "Generate code examples from actual usage",
        "Format output as Markdown"
      ]
    },
    "target_files": [".workflow/docs/modules/auth/README.md"]
  }
}

3. Architecture Documentation (if requested)

Purpose: System design and patterns Output: .workflow/docs/architecture/

Complete JSON Structure:

{
  "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",
        "on_error": "fail"
      },
      {
        "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",
        "on_error": "fail",
        "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"
    ]
  }
}

4. API Documentation (if requested)

Purpose: API reference and specifications Output: .workflow/docs/api/README.md

Complete JSON Structure:

{
  "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 using MCP",
        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|app\\.|@(Get|Post|Put|Delete|Patch)', file_pattern='*.{ts,js}', output_mode='content', head_limit=100)",
        "output_to": "endpoint_discovery",
        "on_error": "skip_optional",
        "note": "Use MCP instead of rg for better structure"
      },
      {
        "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/**/*}\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")",
        "output_to": "api_analysis",
        "on_error": "fail",
        "note": "Analysis limited to API-related paths - controlled context"
      }
    ],
    "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"
    ]
  }
}

Planning Outputs

File Structure

.workflow/
├── .active-WFS-docs-20240120-143022
└── WFS-docs-20240120-143022/
    ├── IMPL_PLAN.md              # Implementation plan
    ├── TODO_LIST.md              # Progress tracker
    ├── .process/
    │   ├── strategy.md           # Doc strategy
    │   └── existing-docs.txt     # Existing docs list
    └── .task/
        ├── IMPL-001.json         # System overview
        ├── IMPL-002.json         # Module: auth
        ├── IMPL-003.json         # Module: api
        ├── IMPL-004.json         # Architecture
        └── IMPL-005.json         # API docs

IMPL_PLAN.md

# Documentation Implementation Plan

**Session**: WFS-docs-[timestamp]
**Type**: [architecture|api|all]
**Tool**: [gemini|qwen|codex]

## Task Breakdown

### IMPL-001: System Overview
- **Output**: .workflow/docs/README.md
- **Template**: project-overview.txt

### IMPL-002+: Module Documentation
- **Modules**: [list]
- **Template**: module-documentation.txt

### IMPL-N: Architecture/API (if requested)
- **Template**: architecture.txt / api-reference.txt

## Execution Order
1. IMPL-001 (Foundation)
2. IMPL-002 to IMPL-[M] (Modules - can parallelize)
3. IMPL-[M+1] (Architecture - needs modules)
4. IMPL-[N] (API - can run after IMPL-001)

TODO_LIST.md

# Documentation Progress Tracker

- [ ] **IMPL-001**: Generate Project Overview
- [ ] **IMPL-002**: Document Module: 'auth'
- [ ] **IMPL-003**: Document Module: 'api'
- [ ] **IMPL-004**: Generate Architecture Documentation
- [ ] **IMPL-005**: Generate Unified API Documentation

## Execution
```bash
/workflow:execute IMPL-001
/workflow:execute IMPL-002
# ...

## Execution Phase

### Via /workflow:execute

For Each Task (IMPL-001, IMPL-002, ...):

/workflow:execute IMPL-NNN ↓ TodoWrite: pending → in_progress ↓ Execute flow_control (pre_analysis steps) ↓ Generate Documentation (apply template) ↓ TodoWrite: in_progress → completed ↓ ✅ Task Complete

### TodoWrite Status Tracking

**Planning Phase**:

✅ Session initialization (completed) ⏳ IMPL-001: Project Overview (pending) ⏳ IMPL-002: Module 'auth' (pending)

**Execution Phase**:

Executing IMPL-001: ✅ Session initialization 🔄 IMPL-001: Project Overview (in_progress) ⏳ IMPL-002: Module 'auth'

After IMPL-001: ✅ Session initialization ✅ IMPL-001: Project Overview (completed) 🔄 IMPL-002: Module 'auth' (in_progress)

## Documentation Output

### Final Structure

.workflow/docs/ ├── README.md # IMPL-001: Project overview ├── modules/ │ ├── auth/README.md # IMPL-002: Auth module │ └── api/README.md # IMPL-003: API module ├── architecture/ # IMPL-004: Architecture │ ├── system-design.md │ ├── module-map.md │ └── data-flow.md └── api/ # IMPL-005: API docs ├── README.md └── openapi.yaml

## Next Steps

### 1. Review Planning Output
```bash
cat .workflow/WFS-docs-*/IMPL_PLAN.md
cat .workflow/WFS-docs-*/TODO_LIST.md

2. Execute Documentation Tasks

# Sequential (recommended)
/workflow:execute IMPL-001  # System overview first
/workflow:execute IMPL-002  # Module docs
/workflow:execute IMPL-003
/workflow:execute IMPL-004  # Architecture
/workflow:execute IMPL-005  # API docs

# Parallel (module docs only)
/workflow:execute IMPL-002 &
/workflow:execute IMPL-003 &
wait

3. Review Generated Documentation

ls -lah .workflow/docs/
cat .workflow/docs/README.md

4. TodoWrite Progress

• Planning: All tasks pending
• Execution: pending → in_progress → completed
• Real-time status updates via TodoWrite

Error Handling

• No modules found: Create only IMPL-001 (system overview)
• Scope path invalid: Show error and exit
• Active session exists: Prompt to complete or pause
• Tool unavailable: Fall back to gemini

Key Benefits

Clear Separation of Concerns

• Planning: Session creation, task decomposition (this command)
• Execution: Content generation, quality assurance (doc-generator agent)

Scalable Task Management

• Independent, self-contained tasks
• Parallelizable module documentation
• Clear dependencies (architecture needs modules)

Template-Driven Consistency

• All documentation follows standard templates
• Reusable and maintainable
• Easy to update standards

Full Context for Execution

• Each task JSON contains complete instructions
• flow_control defines exact analysis steps
• Tool selection for flexibility