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

/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 Process

Phase 1: Session Initialization

# 1. Parse user input
doc_type="all"  # architecture|api|all
tool="gemini"   # gemini|qwen|codex (default: gemini)
scope=""        # optional path filter

# 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]}"

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

# 3. Create active marker
touch ".workflow/.active-WFS-docs-${timestamp}"

Phase 2: Project Structure Analysis (MANDATORY)

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

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:

# 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

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

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

{
  "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"
    ]
  }
}

API Documentation Task (if requested)

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

# 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

# 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 # 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 └── api/ ├── README.md # From IMPL-005 └── openapi.yaml

## Error Handling

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

### Clear Separation of Concerns
- **Planning** (docs.md): Session creation, task decomposition, no content generation
- **Execution** (doc-generator.md): Content generation, template application, quality assurance

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

### Template-Driven Consistency
- All documentation follows standard templates
- Templates are reusable and maintainable
- Easy to update documentation standards

### Full Context for Execution
- Each task JSON contains complete instructions
- flow_control defines exact analysis steps
- Conditional tool selection for flexibility