mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Refactor documentation workflow and templates
- Updated `/workflow:docs` command to enhance documentation planning and orchestration. - Introduced new parameters for tool selection and scope filtering. - Separated documentation planning from content generation, clarifying roles of docs.md and doc-generator.md. - Added detailed planning process phases, including session initialization, project structure analysis, and task decomposition. - Created new templates for API, module, and project-level documentation, ensuring comprehensive coverage and consistency. - Enhanced output structure for better organization of generated documentation. - Implemented error handling and completion checklist for improved user experience.
This commit is contained in:
catlog22
@@ -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:
|
||||
<example>
|
||||
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."
|
||||
<commentary>
|
||||
Complex system documentation requires flow_control for structured analysis
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
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"
|
||||
<commentary>
|
||||
Simple module documentation can be handled directly without flow_control
|
||||
The agent is a pure executor, following instructions from the task JSON.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
@@ -1,256 +1,564 @@
|
||||
---
|
||||
name: docs
|
||||
description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
|
||||
usage: /workflow:docs <type> [scope]
|
||||
argument-hint: "architecture"|"api"|"all"
|
||||
description: Documentation planning and orchestration - creates structured documentation tasks for execution
|
||||
usage: /workflow:docs <type> [options]
|
||||
argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||
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 <type> [scope]
|
||||
/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||
```
|
||||
|
||||
## 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:<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.
|
||||
### Full Context for Execution
|
||||
- Each task JSON contains complete instructions
|
||||
- flow_control defines exact analysis steps
|
||||
- Conditional tool selection for flexibility
|
||||
|
||||
@@ -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 <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 <token>
|
||||
```
|
||||
|
||||
**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 <token>
|
||||
```
|
||||
|
||||
**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
|
||||
@@ -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]
|
||||
@@ -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]
|
||||
Reference in New Issue
Block a user