mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +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
|
name: doc-generator
|
||||||
description: |
|
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:
|
Examples:
|
||||||
<example>
|
<example>
|
||||||
Context: User needs comprehensive system documentation with flow control
|
Context: A task JSON with flow_control is provided to document a module.
|
||||||
user: "Generate complete system documentation with architecture and API docs"
|
user: "Execute documentation task DOC-001"
|
||||||
assistant: "I'll use the doc-generator agent with flow_control to systematically analyze and document the system"
|
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>
|
<commentary>
|
||||||
Complex system documentation requires flow_control for structured analysis
|
The agent is a pure executor, following instructions from the task JSON.
|
||||||
</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
|
|
||||||
</commentary>
|
</commentary>
|
||||||
</example>
|
</example>
|
||||||
|
|
||||||
color: green
|
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
|
## Core Philosophy
|
||||||
|
|
||||||
- **Context-driven Documentation** - Use provided context and flow_control structures for systematic analysis
|
- **Execution, Not Planning**: You are a pure executor. All instructions come from the task JSON.
|
||||||
- **Hierarchical Generation** - Build documentation from module-level to system-level understanding
|
- **Context-Driven**: All necessary context is gathered via the `pre_analysis` steps in the `flow_control` block.
|
||||||
- **Tool Integration** - Leverage CLI tools (gemini-wrapper, codex, bash) within agent execution
|
- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
|
||||||
- **Progress Tracking** - Use TodoWrite throughout documentation generation process
|
- **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
|
||||||
|
|
||||||
## Execution Process
|
## 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**:
|
### 2. Pre-Analysis Execution (Context Gathering)
|
||||||
```
|
- **Action**: Execute the `pre_analysis` array from the `flow_control` block sequentially.
|
||||||
IF task contains [FLOW_CONTROL] marker:
|
- **Context Accumulation**: Store the output of each step in a variable specified by `output_to`.
|
||||||
→ Execute flow_control.pre_analysis steps sequentially for context gathering
|
- **Variable Substitution**: Use `[variable_name]` syntax to inject outputs from previous steps into subsequent commands.
|
||||||
→ 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. 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
|
```json
|
||||||
{
|
{
|
||||||
"flow_control": {
|
"step": "analyze_module_structure",
|
||||||
"pre_analysis": [
|
"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)\")",
|
||||||
"step": "discover_structure",
|
"output_to": "module_analysis"
|
||||||
"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/"]
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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
|
// After completing a step
|
||||||
|
TodoWrite({
|
||||||
**Code Documentation**: Function/method descriptions with parameters/returns, class/module overviews, algorithm explanations, usage examples, edge cases, performance characteristics
|
todos: [
|
||||||
|
{ "content": "Load and validate task JSON", "status": "completed" },
|
||||||
## Workflow Execution
|
{ "content": "Execute pre-analysis step: discover_structure", "status": "in_progress" },
|
||||||
|
// ... rest of the tasks
|
||||||
### 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"
|
|
||||||
}
|
|
||||||
])
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Phase 2: Flow Control Execution
|
### 5. Quality Assurance
|
||||||
1. **Parse Flow Control**: Extract pre_analysis steps from task context
|
Before completing the task, you must verify the following:
|
||||||
2. **Sequential Execution**: Execute each step and capture outputs
|
- [ ] **Content Accuracy**: Technical information is verified against the analysis context.
|
||||||
3. **Context Accumulation**: Build understanding through variable passing
|
- [ ] **Completeness**: All sections of the specified template are populated.
|
||||||
4. **Progress Updates**: Mark completed steps in TodoWrite
|
- [ ] **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
|
### 6. Task Completion
|
||||||
1. **Module-Level**: Individual component analysis, API docs per module, usage examples
|
1. **Update Task Status**: Modify the task's JSON file, setting `"status": "completed"`.
|
||||||
2. **System-Level**: Architecture overview synthesis, cross-module integration, complete API specs
|
2. **Generate Summary**: Create a summary document in the `.summaries/` directory (e.g., `DOC-001-summary.md`).
|
||||||
3. **Progress Updates**: Update TodoWrite for each completed section
|
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**:
|
## Documentation Generated
|
||||||
- [ ] **Content Accuracy**: Technical information verified against actual code
|
- **[Document Name]** (`[file-path]`): [Brief description of the document's purpose and content].
|
||||||
- [ ] **Completeness**: All required sections included
|
- **[Section Name]** (`[file:section]`): [Details about a specific section generated].
|
||||||
- [ ] **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
|
|
||||||
|
|
||||||
**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):
|
## Status: ✅ Complete
|
||||||
- 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)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Gemini-Wrapper
|
## Key Reminders
|
||||||
```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
|
|
||||||
"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Codex Integration
|
**ALWAYS**:
|
||||||
```bash
|
- **Follow `flow_control`**: Execute the steps exactly as defined in the task JSON.
|
||||||
codex --full-auto exec "
|
- **Execute Commands Directly**: All commands are tool-specific and ready to run.
|
||||||
PURPOSE: Generate comprehensive module documentation
|
- **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution.
|
||||||
TASK: Create detailed documentation based on analysis
|
- **Verify Output**: Ensure all `target_files` are created and meet quality standards.
|
||||||
CONTEXT: Analysis results from previous steps
|
- **Update Progress**: Use `TodoWrite` to track each step of the execution.
|
||||||
EXPECTED: Complete documentation in .workflow/docs/
|
- **Generate a Summary**: Create a detailed summary upon task completion.
|
||||||
" -s danger-full-access
|
|
||||||
```
|
|
||||||
|
|
||||||
## Best Practices & Guidelines
|
**NEVER**:
|
||||||
|
- **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
|
||||||
**Content Excellence**:
|
- **Assume Context**: Do not guess information; gather it through the `pre_analysis` steps.
|
||||||
- Write for your audience (developers, users, stakeholders)
|
- **Generate Code**: Your role is to document, not to implement.
|
||||||
- Use examples liberally (code, curl commands, configurations)
|
- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
|
||||||
- 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.
|
|
||||||
|
|||||||
@@ -1,256 +1,564 @@
|
|||||||
---
|
---
|
||||||
name: docs
|
name: docs
|
||||||
description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
|
description: Documentation planning and orchestration - creates structured documentation tasks for execution
|
||||||
usage: /workflow:docs <type> [scope]
|
usage: /workflow:docs <type> [options]
|
||||||
argument-hint: "architecture"|"api"|"all"
|
argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||||
examples:
|
examples:
|
||||||
- /workflow:docs all
|
- /workflow:docs all # Complete documentation (gemini default)
|
||||||
- /workflow:docs architecture src/modules
|
- /workflow:docs all --tool qwen # Use Qwen for architecture focus
|
||||||
- /workflow:docs api --scope api/
|
- /workflow:docs architecture --scope src/modules
|
||||||
|
- /workflow:docs api --tool gemini --scope api/
|
||||||
---
|
---
|
||||||
|
|
||||||
# Workflow Documentation Command
|
# 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
|
## Usage
|
||||||
```bash
|
```bash
|
||||||
/workflow:docs <type> [scope]
|
/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]
|
||||||
```
|
```
|
||||||
|
|
||||||
## Input Detection
|
### Parameters
|
||||||
- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
|
- **type**: `architecture` | `api` | `all` (required)
|
||||||
- **Scope**: Optional module/directory filtering → Focuses documentation generation
|
- `architecture`: System design, module interactions, patterns
|
||||||
- **Default**: `all` → Complete documentation suite
|
- `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
|
### Phase 1: Session Initialization
|
||||||
The command performs structured planning and task creation:
|
```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
|
# Extract from command arguments
|
||||||
- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
|
[[ "$*" == *"architecture"* ]] && doc_type="architecture"
|
||||||
- **Module Boundary Identification**: Understand module organization and dependencies
|
[[ "$*" == *"api"* ]] && doc_type="api"
|
||||||
- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
|
[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
|
||||||
- **Foundation for documentation**: Use structure analysis to guide task decomposition
|
[[ "$*" == *"--tool codex"* ]] && tool="codex"
|
||||||
|
[[ "$*" =~ --scope[[:space:]]+([^[:space:]]+) ]] && scope="${BASH_REMATCH[1]}"
|
||||||
|
|
||||||
**1. Documentation Planning**
|
# 2. Create session structure
|
||||||
- **Type Analysis**: Determine documentation scope (architecture/api/all)
|
timestamp=$(date +%Y%m%d-%H%M%S)
|
||||||
- **Module Discovery**: Use architecture analysis results to identify components
|
session_dir=".workflow/WFS-docs-${timestamp}"
|
||||||
- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
|
mkdir -p "${session_dir}"/{.task,.process,.summaries}
|
||||||
- **Session Management**: Create or use existing documentation session
|
|
||||||
|
|
||||||
**2. Task Generation**
|
# 3. Create active marker
|
||||||
- **Create session**: `.workflow/WFS-docs-[timestamp]/`
|
touch ".workflow/.active-WFS-docs-${timestamp}"
|
||||||
- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
|
```
|
||||||
- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
|
|
||||||
- **Create task.json files**: Individual documentation tasks with flow_control
|
|
||||||
- **Setup TODO_LIST.md**: Progress tracking for documentation generation
|
|
||||||
|
|
||||||
### Session Management ⚠️ CRITICAL
|
### Phase 2: Project Structure Analysis (MANDATORY)
|
||||||
- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
|
```bash
|
||||||
- **Marker naming**: Active marker must exactly match session folder name
|
# Run get_modules_by_depth.sh for module hierarchy
|
||||||
- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
|
module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
|
||||||
- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
|
|
||||||
- **Session isolation**: Each documentation session maintains independent context and state
|
# 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
|
## 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/
|
.workflow/docs/
|
||||||
├── README.md # System navigation
|
├── README.md # From IMPL-001
|
||||||
├── modules/ # Level 1: Module documentation
|
├── modules/
|
||||||
│ ├── [module-1]/
|
│ ├── auth/
|
||||||
│ │ ├── overview.md
|
│ │ └── README.md # From IMPL-002
|
||||||
│ │ ├── api.md
|
│ └── api/
|
||||||
│ │ ├── dependencies.md
|
│ └── README.md # From IMPL-003
|
||||||
│ │ └── examples.md
|
├── architecture/
|
||||||
│ └── [module-n]/...
|
│ ├── system-design.md # From IMPL-004
|
||||||
├── architecture/ # Level 2: System architecture
|
|
||||||
│ ├── system-design.md
|
|
||||||
│ ├── module-map.md
|
│ ├── module-map.md
|
||||||
│ ├── data-flow.md
|
│ └── data-flow.md
|
||||||
│ └── tech-stack.md
|
└── api/
|
||||||
└── api/ # Level 2: Unified API docs
|
├── README.md # From IMPL-005
|
||||||
├── unified-api.md
|
|
||||||
└── openapi.yaml
|
└── 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
|
## Error Handling
|
||||||
- **Invalid document type**: Clear error message with valid options
|
|
||||||
- **Module not found**: Skip missing modules with warning
|
- **No modules found**: Create only IMPL-001 (system overview)
|
||||||
- **Analysis failures**: Fall back to file-based analysis
|
- **Scope path invalid**: Show error and exit
|
||||||
- **Permission issues**: Clear guidance on directory access
|
- **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
|
## Key Benefits
|
||||||
|
|
||||||
### Structured Documentation Process
|
### Clear Separation of Concerns
|
||||||
- **Task-based approach**: Documentation broken into manageable, trackable tasks
|
- **Planning** (docs.md): Session creation, task decomposition, no content generation
|
||||||
- **Flow control integration**: Systematic analysis ensures completeness
|
- **Execution** (doc-generator.md): Content generation, template application, quality assurance
|
||||||
- **Progress visibility**: TODO_LIST.md provides clear completion status
|
|
||||||
- **Quality assurance**: Each task has defined acceptance criteria
|
|
||||||
|
|
||||||
### Workflow Integration
|
### Scalable Task Management
|
||||||
- **Planning foundation**: Documentation provides context for implementation planning
|
- Each documentation task is independent and self-contained
|
||||||
- **Execution consistency**: Same task execution model as implementation
|
- Tasks can be parallelized for faster completion
|
||||||
- **Context accumulation**: Documentation builds comprehensive project understanding
|
- 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
|
### Full Context for Execution
|
||||||
```bash
|
- Each task JSON contains complete instructions
|
||||||
# Step 1: Create documentation plan and tasks
|
- flow_control defines exact analysis steps
|
||||||
/workflow:docs all
|
- Conditional tool selection for flexibility
|
||||||
|
|
||||||
# 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.
|
|
||||||
|
|||||||
@@ -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