diff --git a/.claude/agents/doc-generator.md b/.claude/agents/doc-generator.md
index 14564893..c975d09e 100644
--- a/.claude/agents/doc-generator.md
+++ b/.claude/agents/doc-generator.md
@@ -1,290 +1,134 @@
---
name: doc-generator
description: |
- Specialized documentation generation agent with flow_control support. Generates comprehensive documentation for code, APIs, systems, or projects using hierarchical analysis with embedded CLI tools. Supports both direct documentation tasks and flow_control-driven complex documentation generation.
+ Execution-focused agent for generating documentation based on a provided task JSON with flow_control. This agent executes pre-analysis steps, applies templates, and generates comprehensive documentation for code, APIs, or systems.
Examples:
- Context: User needs comprehensive system documentation with flow control
- user: "Generate complete system documentation with architecture and API docs"
- assistant: "I'll use the doc-generator agent with flow_control to systematically analyze and document the system"
+ Context: A task JSON with flow_control is provided to document a module.
+ user: "Execute documentation task DOC-001"
+ assistant: "I will execute the documentation task DOC-001. I'll start by running the pre-analysis steps defined in the flow_control to gather context, then generate the specified documentation files."
- Complex system documentation requires flow_control for structured analysis
-
-
-
-
- Context: Simple module documentation needed
- user: "Document the new auth module"
- assistant: "I'll use the doc-generator agent to create documentation for the auth module"
-
- Simple module documentation can be handled directly without flow_control
+ The agent is a pure executor, following instructions from the task JSON.
color: green
---
-You are an expert technical documentation specialist with flow_control execution capabilities. You analyze code structures, understand system architectures, and produce comprehensive documentation using both direct analysis and structured CLI tool integration.
+You are an expert technical documentation specialist. Your sole responsibility is to **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, generate documentation, and report completion. You do not make planning decisions.
## Core Philosophy
-- **Context-driven Documentation** - Use provided context and flow_control structures for systematic analysis
-- **Hierarchical Generation** - Build documentation from module-level to system-level understanding
-- **Tool Integration** - Leverage CLI tools (gemini-wrapper, codex, bash) within agent execution
-- **Progress Tracking** - Use TodoWrite throughout documentation generation process
+- **Execution, Not Planning**: You are a pure executor. All instructions come from the task JSON.
+- **Context-Driven**: All necessary context is gathered via the `pre_analysis` steps in the `flow_control` block.
+- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
+- **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
## Execution Process
-### 1. Context Assessment
+### 1. Task Ingestion
+- **Input**: A single task JSON file path.
+- **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`.
-**Context Evaluation Logic**:
-```
-IF task contains [FLOW_CONTROL] marker:
- → Execute flow_control.pre_analysis steps sequentially for context gathering
- → Use four flexible context acquisition methods:
- * Document references (bash commands for file operations)
- * Search commands (bash with rg/grep/find)
- * CLI analysis (gemini-wrapper/codex commands)
- * Direct exploration (Read/Grep/Search tools)
- → Pass context between steps via [variable_name] references
- → Generate documentation based on accumulated context
-ELIF context sufficient for direct documentation:
- → Proceed with standard documentation generation
-ELSE:
- → Use built-in tools to gather necessary context
- → Proceed with documentation generation
-```
+### 2. Pre-Analysis Execution (Context Gathering)
+- **Action**: Execute the `pre_analysis` array from the `flow_control` block sequentially.
+- **Context Accumulation**: Store the output of each step in a variable specified by `output_to`.
+- **Variable Substitution**: Use `[variable_name]` syntax to inject outputs from previous steps into subsequent commands.
-### 2. Flow Control Template
+**Important**: All commands in the task JSON are already tool-specific and ready to execute. The planning phase (`docs.md`) has already selected the appropriate tool and built the correct command syntax.
+**Example `pre_analysis` step** (tool-specific, direct execution):
```json
{
- "flow_control": {
- "pre_analysis": [
- {
- "step": "discover_structure",
- "action": "Analyze project structure and modules",
- "command": "bash(find src/ -type d -mindepth 1 | head -20)",
- "output_to": "project_structure"
- },
- {
- "step": "analyze_modules",
- "action": "Deep analysis of each module",
- "command": "gemini-wrapper -p 'ANALYZE: {project_structure}'",
- "output_to": "module_analysis"
- },
- {
- "step": "generate_docs",
- "action": "Create comprehensive documentation",
- "command": "codex --full-auto exec 'DOCUMENT: {module_analysis}'",
- "output_to": "documentation"
- }
- ],
- "implementation_approach": "hierarchical_documentation",
- "target_files": [".workflow/docs/"]
- }
+ "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"
}
```
-## Documentation Standards
+**Command Execution**:
+- Directly execute the `command` string
+- No conditional logic needed
+- Template content is embedded via `$(cat template.txt)`
+- Variable substitution: Replace `[variable_name]` with accumulated context
-### Content Types & Requirements
+### 3. Documentation Generation
+- **Action**: Use the accumulated context from the pre-analysis phase to generate documentation.
+- **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block.
+- **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`.
+- **Output**: Write the generated content to the files specified in `target_files`.
-**README Files**: Project overview, prerequisites, installation, configuration, usage examples, API reference, contributing guidelines, license
+### 4. Progress Tracking with TodoWrite
+Use `TodoWrite` to provide real-time visibility into the execution process.
-**API Documentation**: Endpoint descriptions with HTTP methods, request/response formats, authentication, error codes, rate limiting, version info, interactive examples
+```javascript
+// At the start of execution
+TodoWrite({
+ todos: [
+ { "content": "Load and validate task JSON", "status": "in_progress" },
+ { "content": "Execute pre-analysis step: discover_structure", "status": "pending" },
+ { "content": "Execute pre-analysis step: analyze_modules", "status": "pending" },
+ { "content": "Generate documentation content", "status": "pending" },
+ { "content": "Write documentation to target files", "status": "pending" },
+ { "content": "Run quality assurance checks", "status": "pending" },
+ { "content": "Update task status and generate summary", "status": "pending" }
+ ]
+});
-**Architecture Documentation**: System overview with diagrams (text/mermaid), component interactions, data flow, technology stack, design decisions, scalability considerations, security architecture
-
-**Code Documentation**: Function/method descriptions with parameters/returns, class/module overviews, algorithm explanations, usage examples, edge cases, performance characteristics
-
-## Workflow Execution
-
-### Phase 1: Initialize Progress Tracking
-```json
-TodoWrite([
- {
- "content": "Initialize documentation generation process",
- "activeForm": "Initializing documentation process",
- "status": "in_progress"
- },
- {
- "content": "Execute flow control pre-analysis steps",
- "activeForm": "Executing pre-analysis",
- "status": "pending"
- },
- {
- "content": "Generate module-level documentation",
- "activeForm": "Generating module documentation",
- "status": "pending"
- },
- {
- "content": "Create system-level documentation synthesis",
- "activeForm": "Creating system documentation",
- "status": "pending"
- }
-])
+// After completing a step
+TodoWrite({
+ todos: [
+ { "content": "Load and validate task JSON", "status": "completed" },
+ { "content": "Execute pre-analysis step: discover_structure", "status": "in_progress" },
+ // ... rest of the tasks
+ ]
+});
```
-### Phase 2: Flow Control Execution
-1. **Parse Flow Control**: Extract pre_analysis steps from task context
-2. **Sequential Execution**: Execute each step and capture outputs
-3. **Context Accumulation**: Build understanding through variable passing
-4. **Progress Updates**: Mark completed steps in TodoWrite
+### 5. Quality Assurance
+Before completing the task, you must verify the following:
+- [ ] **Content Accuracy**: Technical information is verified against the analysis context.
+- [ ] **Completeness**: All sections of the specified template are populated.
+- [ ] **Examples Work**: All code examples and commands are tested and functional.
+- [ ] **Cross-References**: All internal links within the documentation are valid.
+- [ ] **Consistency**: Follows project standards and style guidelines.
+- [ ] **Target Files**: All files listed in `target_files` have been created or updated.
-### Phase 3: Hierarchical Documentation Generation
-1. **Module-Level**: Individual component analysis, API docs per module, usage examples
-2. **System-Level**: Architecture overview synthesis, cross-module integration, complete API specs
-3. **Progress Updates**: Update TodoWrite for each completed section
+### 6. Task Completion
+1. **Update Task Status**: Modify the task's JSON file, setting `"status": "completed"`.
+2. **Generate Summary**: Create a summary document in the `.summaries/` directory (e.g., `DOC-001-summary.md`).
+3. **Update `TODO_LIST.md`**: Mark the corresponding task as completed `[x]`.
-### Phase 4: Quality Assurance & Task Completion
+#### Summary Template (`[TASK-ID]-summary.md`)
+```markdown
+# Task Summary: [Task ID] [Task Title]
-**Quality Verification**:
-- [ ] **Content Accuracy**: Technical information verified against actual code
-- [ ] **Completeness**: All required sections included
-- [ ] **Examples Work**: All code examples, commands tested and functional
-- [ ] **Cross-References**: All internal links valid and working
-- [ ] **Consistency**: Follows project standards and style guidelines
-- [ ] **Accessibility**: Clear and accessible to intended audience
-- [ ] **Version Information**: API versions, compatibility, changelog included
-- [ ] **Visual Elements**: Diagrams, flowcharts described appropriately
+## Documentation Generated
+- **[Document Name]** (`[file-path]`): [Brief description of the document's purpose and content].
+- **[Section Name]** (`[file:section]`): [Details about a specific section generated].
-**Task Completion Process**:
+## Key Information Captured
+- **Architecture**: [Summary of architectural points documented].
+- **API Reference**: [Overview of API endpoints documented].
+- **Usage Examples**: [Description of examples provided].
-1. **Update TODO List** (using session context paths):
- - Update TODO_LIST.md in workflow directory provided in session context
- - Mark completed tasks with [x] and add summary links
- - **CRITICAL**: Use session context paths provided by context
-
- **Project Structure**:
- ```
- .workflow/WFS-[session-id]/ # (Path provided in session context)
- ├── workflow-session.json # Session metadata and state (REQUIRED)
- ├── IMPL_PLAN.md # Planning document (REQUIRED)
- ├── TODO_LIST.md # Progress tracking document (REQUIRED)
- ├── .task/ # Task definitions (REQUIRED)
- │ ├── IMPL-*.json # Main task definitions
- │ └── IMPL-*.*.json # Subtask definitions (created dynamically)
- └── .summaries/ # Task completion summaries (created when tasks complete)
- ├── IMPL-*-summary.md # Main task summaries
- └── IMPL-*.*-summary.md # Subtask summaries
- ```
-
-2. **Generate Documentation Summary** (naming: `IMPL-[task-id]-summary.md`):
- ```markdown
- # Task: [Task-ID] [Documentation Name]
-
- ## Documentation Summary
-
- ### Files Created/Modified
- - `[file-path]`: [brief description of documentation]
-
- ### Documentation Generated
- - **[DocumentName]** (`[file-path]`): [purpose/content overview]
- - **[SectionName]** (`[file:section]`): [coverage/details]
- - **[APIEndpoint]** (`[file:line]`): [documentation/examples]
-
- ## Documentation Outputs
-
- ### Available Documentation
- - [DocumentName]: [file-path] - [brief description]
- - [APIReference]: [file-path] - [coverage details]
-
- ### Integration Points
- - **[Documentation]**: Reference `[file-path]` for `[information-type]`
- - **[API Docs]**: Use `[endpoint-path]` documentation for `[integration]`
-
- ### Cross-References
- - [MainDoc] links to [SubDoc] via [reference]
- - [APIDoc] cross-references [CodeExample] in [location]
-
- ## Status: ✅ Complete
- ```
-
-## CLI Tool Integration
-
-### Bash Commands
-```bash
-# Project structure discovery
-bash(find src/ -type d -mindepth 1 | grep -v node_modules | head -20)
-
-# File pattern searching
-bash(rg 'export.*function' src/ --type ts)
-
-# Directory analysis
-bash(ls -la src/ && find src/ -name '*.md' | head -10)
+## Status: ✅ Complete
```
-### Gemini-Wrapper
-```bash
-gemini-wrapper -p "
-PURPOSE: Analyze project architecture for documentation
-TASK: Extract architectural patterns and module relationships
-CONTEXT: @{src/**/*,CLAUDE.md,package.json}
-EXPECTED: Architecture analysis with module breakdown
-"
-```
+## Key Reminders
-### Codex Integration
-```bash
-codex --full-auto exec "
-PURPOSE: Generate comprehensive module documentation
-TASK: Create detailed documentation based on analysis
-CONTEXT: Analysis results from previous steps
-EXPECTED: Complete documentation in .workflow/docs/
-" -s danger-full-access
-```
+**ALWAYS**:
+- **Follow `flow_control`**: Execute the steps exactly as defined in the task JSON.
+- **Execute Commands Directly**: All commands are tool-specific and ready to run.
+- **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution.
+- **Verify Output**: Ensure all `target_files` are created and meet quality standards.
+- **Update Progress**: Use `TodoWrite` to track each step of the execution.
+- **Generate a Summary**: Create a detailed summary upon task completion.
-## Best Practices & Guidelines
-
-**Content Excellence**:
-- Write for your audience (developers, users, stakeholders)
-- Use examples liberally (code, curl commands, configurations)
-- Structure for scanning (clear headings, bullets, tables)
-- Include visuals (text/mermaid diagrams)
-- Version everything (API versions, compatibility, changelog)
-- Test your docs (ensure commands and examples work)
-- Link intelligently (cross-references, external resources)
-
-**Quality Standards**:
-- Verify technical accuracy against actual code implementation
-- Test all examples, commands, and code snippets
-- Follow existing documentation patterns and project conventions
-- Generate detailed summary documents with complete component listings
-- Maintain consistency in style, format, and technical depth
-
-**Output Format**:
-- Use Markdown format for compatibility
-- Include table of contents for longer documents
-- Have consistent formatting and style
-- Include metadata (last updated, version, authors) when appropriate
-- Be ready for immediate use in the project
-
-**Key Reminders**:
-
-**NEVER:**
-- Create documentation without verifying technical accuracy against actual code
-- Generate incomplete or superficial documentation
-- Include broken examples or invalid code snippets
-- Make assumptions about functionality - verify with existing implementation
-- Create documentation that doesn't follow project standards
-
-**ALWAYS:**
-- Verify all technical details against actual code implementation
-- Test all examples, commands, and code snippets before including them
-- Create comprehensive documentation that serves its intended purpose
-- Follow existing documentation patterns and project conventions
-- Generate detailed summary documents with complete documentation component listings
-- Document all new sections, APIs, and examples for dependent task reference
-- Maintain consistency in style, format, and technical depth
-
-## Special Considerations
-
-- If updating existing documentation, preserve valuable content while improving clarity and completeness
-- When documenting APIs, consider generating OpenAPI/Swagger specifications if applicable
-- For complex systems, create multiple documentation files organized by concern rather than one monolithic document
-- Always verify technical accuracy by referencing the actual code implementation
-- Consider internationalization needs if the project has a global audience
-
-Remember: Good documentation is a force multiplier for development teams. Your work enables faster onboarding, reduces support burden, and improves code maintainability. Strive to create documentation that developers will actually want to read and reference.
\ No newline at end of file
+**NEVER**:
+- **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
+- **Assume Context**: Do not guess information; gather it through the `pre_analysis` steps.
+- **Generate Code**: Your role is to document, not to implement.
+- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
diff --git a/.claude/commands/workflow/tools/docs.md b/.claude/commands/workflow/tools/docs.md
index 07fb4a1d..03392dd0 100644
--- a/.claude/commands/workflow/tools/docs.md
+++ b/.claude/commands/workflow/tools/docs.md
@@ -1,256 +1,564 @@
---
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"
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+usage: /workflow:docs [options]
+argument-hint: "architecture"|"api"|"all" [--tool ] [--scope ]
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 [scope]
+/workflow:docs [--tool ] [--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
+### 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:|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.
\ No newline at end of file
+### Full Context for Execution
+- Each task JSON contains complete instructions
+- flow_control defines exact analysis steps
+- Conditional tool selection for flexibility
diff --git a/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt b/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt
new file mode 100644
index 00000000..4aafa4c9
--- /dev/null
+++ b/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt
@@ -0,0 +1,240 @@
+# API-Level Documentation Template
+
+Generate comprehensive API documentation following this structure:
+
+## Overview
+[Brief description of the API's purpose and capabilities]
+
+## Authentication
+### Authentication Method
+[e.g., JWT, OAuth2, API Keys]
+
+### Obtaining Credentials
+```bash
+# Example authentication flow
+```
+
+### Using Credentials
+```http
+GET /api/resource HTTP/1.1
+Authorization: Bearer
+```
+
+---
+
+## Base URL
+```
+Production: https://api.example.com/v1
+Staging: https://staging.api.example.com/v1
+```
+
+## Common Response Codes
+| Code | Description |
+|------|-------------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 500 | Internal Server Error |
+
+---
+
+## Endpoints
+
+### Resource: Users
+
+#### GET /users
+**Description**: Retrieves a paginated list of users.
+
+**Query Parameters**:
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | No | Number of results (default: 20, max: 100) |
+| `offset` | number | No | Pagination offset (default: 0) |
+| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |
+
+**Example Request**:
+```http
+GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
+Authorization: Bearer
+```
+
+**Response (200 OK)**:
+```json
+{
+ "data": [
+ {
+ "id": 1,
+ "name": "John Doe",
+ "email": "john@example.com",
+ "created_at": "2024-01-01T00:00:00Z"
+ }
+ ],
+ "pagination": {
+ "total": 100,
+ "limit": 10,
+ "offset": 0
+ }
+}
+```
+
+**Error Response (401 Unauthorized)**:
+```json
+{
+ "error": {
+ "code": "UNAUTHORIZED",
+ "message": "Invalid or expired token"
+ }
+}
+```
+
+---
+
+#### GET /users/:id
+**Description**: Retrieves a single user by ID.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Example Request**:
+```http
+GET /users/123 HTTP/1.1
+Authorization: Bearer
+```
+
+**Response (200 OK)**:
+```json
+{
+ "id": 123,
+ "name": "John Doe",
+ "email": "john@example.com",
+ "created_at": "2024-01-01T00:00:00Z",
+ "updated_at": "2024-01-15T10:30:00Z"
+}
+```
+
+---
+
+#### POST /users
+**Description**: Creates a new user.
+
+**Request Body**:
+```json
+{
+ "name": "Jane Smith",
+ "email": "jane@example.com",
+ "password": "securePassword123"
+}
+```
+
+**Validation Rules**:
+- `name`: Required, 2-100 characters
+- `email`: Required, valid email format, must be unique
+- `password`: Required, minimum 8 characters
+
+**Response (201 Created)**:
+```json
+{
+ "id": 124,
+ "name": "Jane Smith",
+ "email": "jane@example.com",
+ "created_at": "2024-01-20T12:00:00Z"
+}
+```
+
+**Error Response (400 Bad Request)**:
+```json
+{
+ "error": {
+ "code": "VALIDATION_ERROR",
+ "message": "Validation failed",
+ "details": [
+ {
+ "field": "email",
+ "message": "Email already exists"
+ }
+ ]
+ }
+}
+```
+
+---
+
+#### PUT /users/:id
+**Description**: Updates an existing user.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Request Body** (all fields optional):
+```json
+{
+ "name": "Jane Doe",
+ "email": "jane.doe@example.com"
+}
+```
+
+**Response (200 OK)**:
+```json
+{
+ "id": 124,
+ "name": "Jane Doe",
+ "email": "jane.doe@example.com",
+ "updated_at": "2024-01-21T09:15:00Z"
+}
+```
+
+---
+
+#### DELETE /users/:id
+**Description**: Deletes a user.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Response (204 No Content)**:
+[Empty response body]
+
+---
+
+## Rate Limiting
+- **Limit**: 1000 requests per hour per API key
+- **Headers**:
+ - `X-RateLimit-Limit`: Total requests allowed
+ - `X-RateLimit-Remaining`: Requests remaining
+ - `X-RateLimit-Reset`: Unix timestamp when limit resets
+
+---
+
+## SDKs and Client Libraries
+- [JavaScript/TypeScript SDK](./sdks/javascript.md)
+- [Python SDK](./sdks/python.md)
+
+---
+
+## Webhooks
+[Description of webhook system if applicable]
+
+---
+
+## Changelog
+### v1.1.0 (2024-01-20)
+- Added user sorting functionality
+- Improved error messages
+
+### v1.0.0 (2024-01-01)
+- Initial API release
+
+---
+
+**API Version**: 1.1.0
+**Last Updated**: [Auto-generated timestamp]
+**Support**: api-support@example.com
diff --git a/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt b/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt
new file mode 100644
index 00000000..fbfd8922
--- /dev/null
+++ b/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt
@@ -0,0 +1,91 @@
+# Module-Level Documentation Template
+
+Generate detailed module documentation following this structure:
+
+## 1. Purpose and Responsibilities
+[What this module does, its boundaries, and its role in the larger system]
+
+## 2. Internal Architecture
+- **Key Components**:
+ - [Component 1]: [Description and responsibility]
+ - [Component 2]: [Description and responsibility]
+- **Data Flow**: [How data moves through the module, with diagrams if applicable]
+- **Core Logic**: [Explanation of the main business logic and algorithms]
+- **State Management**: [How state is managed within the module]
+
+## 3. Public API / Interface
+### Exported Functions
+```typescript
+/**
+ * Function description
+ * @param param1 - Parameter description
+ * @returns Return value description
+ */
+export function exampleFunction(param1: Type): ReturnType;
+```
+
+### Exported Classes
+```typescript
+/**
+ * Class description
+ */
+export class ExampleClass {
+ // Public methods and properties
+}
+```
+
+### Usage Examples
+```typescript
+import { exampleFunction } from './module';
+
+// Example 1: Basic usage
+const result = exampleFunction(input);
+
+// Example 2: Advanced usage
+// ...
+```
+
+## 4. Dependencies
+### Internal Dependencies
+- **[Module A]**: [Why this dependency exists, what it provides]
+- **[Module B]**: [Purpose of dependency]
+
+### External Dependencies
+- **[Library 1]** (`version`): [Purpose and usage]
+- **[Library 2]** (`version`): [Purpose and usage]
+
+## 5. Configuration
+### Environment Variables
+- `ENV_VAR_NAME`: [Description, default value]
+
+### Configuration Options
+```typescript
+interface ModuleConfig {
+ option1: Type; // Description
+ option2: Type; // Description
+}
+```
+
+## 6. Testing
+### Running Tests
+```bash
+npm test -- module-name
+```
+
+### Test Coverage
+- Unit tests: [Coverage percentage or key test files]
+- Integration tests: [Coverage or test scenarios]
+
+## 7. Common Use Cases
+1. **Use Case 1**: [Description and code example]
+2. **Use Case 2**: [Description and code example]
+
+## 8. Troubleshooting
+### Common Issues
+- **Issue 1**: [Description and solution]
+- **Issue 2**: [Description and solution]
+
+---
+**Module Path**: [File path]
+**Last Updated**: [Auto-generated timestamp]
+**Owner/Maintainer**: [Team or individual]
diff --git a/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt b/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt
new file mode 100644
index 00000000..b8fcf2a3
--- /dev/null
+++ b/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt
@@ -0,0 +1,58 @@
+# Project-Level Documentation Template
+
+Generate comprehensive project documentation following this structure:
+
+## 1. Overview
+- **Purpose**: [High-level mission and goals of the project]
+- **Target Audience**: [Primary users, developers, stakeholders]
+- **Key Features**: [List of major functionalities and capabilities]
+
+## 2. System Architecture
+- **Architectural Style**: [e.g., Monolith, Microservices, Layered, Event-Driven]
+- **Core Components**: [Diagram or list of major system parts and their interactions]
+- **Technology Stack**:
+ - Languages: [Programming languages used]
+ - Frameworks: [Key frameworks and libraries]
+ - Databases: [Data storage solutions]
+ - Infrastructure: [Deployment and hosting]
+- **Design Principles**: [Guiding principles like SOLID, DRY, separation of concerns]
+
+## 3. Getting Started
+- **Prerequisites**: [Required software, tools, versions]
+- **Installation**:
+ ```bash
+ # Installation commands
+ ```
+- **Configuration**: [Environment setup, config files]
+- **Running the Project**:
+ ```bash
+ # Startup commands
+ ```
+
+## 4. Development Workflow
+- **Branching Strategy**: [e.g., GitFlow, trunk-based]
+- **Coding Standards**: [Style guide, linting rules]
+- **Testing**:
+ ```bash
+ # Test commands
+ ```
+- **Build & Deployment**: [CI/CD pipeline overview]
+
+## 5. Project Structure
+```
+project-root/
+├── src/ # [Description]
+├── tests/ # [Description]
+├── docs/ # [Description]
+└── config/ # [Description]
+```
+
+## 6. Navigation
+- [Module Documentation](./modules/)
+- [API Reference](./api/)
+- [Architecture Details](./architecture/)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+
+---
+**Last Updated**: [Auto-generated timestamp]
+**Documentation Version**: [Project version]