mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
Add comprehensive documentation templates for API, folder navigation, module README, project architecture, examples, and project-level README
- Introduced a unified API documentation template covering both Code API and HTTP API sections. - Created a folder navigation documentation template for directories containing subdirectories. - Developed a module README documentation template focusing on module purpose, usage, and dependencies. - Added a project architecture documentation template synthesizing module information and system design. - Implemented a project examples documentation template showcasing practical usage scenarios. - Established a project-level documentation template outlining project overview, architecture, and navigation.
This commit is contained in:
catlog22
@@ -79,18 +79,54 @@ mkdir -p "${session_dir}"/{.task,.process,.summaries}
|
||||
touch ".workflow/.active-WFS-docs-${timestamp}"
|
||||
```
|
||||
|
||||
#### Phase 2: Lightweight Metadata Collection (MANDATORY)
|
||||
#### Phase 2: Lightweight Metadata Collection with Folder Type Analysis (MANDATORY)
|
||||
```bash
|
||||
# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only)
|
||||
module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
# Format: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no
|
||||
|
||||
# Step 2: Use Code Index MCP for file discovery (optional, for better precision)
|
||||
# Example: mcp__code-index__find_files(pattern="src/**/")
|
||||
# This finds directories without loading content
|
||||
# Step 2: Analyze each folder to determine its type
|
||||
# Create folder analysis file
|
||||
mkdir -p "${session_dir}/.process"
|
||||
> "${session_dir}/.process/folder-analysis.txt"
|
||||
|
||||
# For each folder discovered by get_modules_by_depth.sh:
|
||||
while IFS='|' read -r depth_info path_info files_info size_info claude_info; do
|
||||
folder_path=$(echo "$path_info" | cut -d':' -f2-)
|
||||
depth=$(echo "$depth_info" | cut -d':' -f2)
|
||||
|
||||
# Count code files in this folder (not recursive, maxdepth 1)
|
||||
code_files=$(find "$folder_path" -maxdepth 1 -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) 2>/dev/null | wc -l)
|
||||
|
||||
# Count immediate subfolders
|
||||
subfolders=$(find "$folder_path" -maxdepth 1 -type d -not -path "$folder_path" 2>/dev/null | wc -l)
|
||||
|
||||
# Determine folder type
|
||||
if [[ $code_files -gt 0 ]]; then
|
||||
folder_type="code" # Has code files → needs API.md + README.md
|
||||
elif [[ $subfolders -gt 0 ]]; then
|
||||
folder_type="navigation" # Only subfolders → needs README.md (navigation)
|
||||
else
|
||||
folder_type="skip" # Empty folder → skip
|
||||
fi
|
||||
|
||||
# Record the analysis
|
||||
echo "${folder_path}|${folder_type}|depth:${depth}|code_files:${code_files}|subfolders:${subfolders}" >> "${session_dir}/.process/folder-analysis.txt"
|
||||
done <<< "$module_data"
|
||||
|
||||
# Step 3: Group folders by top-level directories for task assignment
|
||||
# Example: src/modules/auth, src/modules/api → group under "src/modules"
|
||||
# This reduces task count while maintaining logical organization
|
||||
awk -F'|' '{
|
||||
split($1, parts, "/");
|
||||
if (length(parts) >= 2) {
|
||||
top_dir = parts[1] "/" parts[2];
|
||||
print top_dir;
|
||||
}
|
||||
}' "${session_dir}/.process/folder-analysis.txt" | sort -u > "${session_dir}/.process/top-level-dirs.txt"
|
||||
|
||||
# IMPORTANT: Do NOT read file contents in planning phase
|
||||
# Only collect: paths, file counts, module structure
|
||||
# Only collect: paths, file counts, module structure, folder types
|
||||
```
|
||||
|
||||
#### Phase 3: Quick Documentation Assessment
|
||||
@@ -110,27 +146,52 @@ cat > "${session_dir}/.process/strategy.md" <<EOF
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Phase 4: Task Decomposition & TodoWrite Setup
|
||||
#### Phase 4: Task Decomposition & TodoWrite Setup (Revised Dependency Order)
|
||||
|
||||
**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)
|
||||
**New Decomposition Strategy (Bottom-Up)**:
|
||||
|
||||
**Grouping Rules**:
|
||||
- Max 3 modules per task
|
||||
- Max 30 files per task
|
||||
- Group by dependency depth and functional similarity
|
||||
**Level 1: Module Tree Tasks** (Execute in parallel)
|
||||
- For each top-level directory in `top-level-dirs.txt`, create one "tree" task
|
||||
- Each tree task recursively handles all subfolders within that directory
|
||||
- Task generates both API.md and README.md based on folder type analysis
|
||||
|
||||
**TodoWrite Setup**:
|
||||
**Level 2: Project README Task** (Depends on all Level 1 tasks)
|
||||
- MUST wait for all module trees to complete
|
||||
- Aggregates information from all module documents
|
||||
- Creates navigation structure
|
||||
|
||||
**Level 3: Architecture & Examples** (Depends on Level 2)
|
||||
- Architecture document synthesizes from all module docs + project README
|
||||
- Examples document uses project README as foundation
|
||||
|
||||
**Task ID Assignment**:
|
||||
```
|
||||
IMPL-001 to IMPL-00N: Module tree tasks (Level 1)
|
||||
IMPL-[N+1]: Project README.md (Level 2, depends_on: IMPL-001 to IMPL-00N)
|
||||
IMPL-[N+2]: ARCHITECTURE.md (Level 3, depends_on: IMPL-[N+1])
|
||||
IMPL-[N+3]: EXAMPLES.md (Level 3, depends_on: IMPL-[N+1])
|
||||
IMPL-[N+4]: API docs (Optional, Level 3, depends_on: IMPL-[N+1])
|
||||
```
|
||||
|
||||
**Example with 3 top-level dirs**:
|
||||
```
|
||||
IMPL-001: Document tree 'src/modules/' (Level 1)
|
||||
IMPL-002: Document tree 'src/utils/' (Level 1)
|
||||
IMPL-003: Document tree 'lib/' (Level 1)
|
||||
IMPL-004: Project README.md (Level 2, depends_on: [001,002,003])
|
||||
IMPL-005: ARCHITECTURE.md (Level 3, depends_on: [004])
|
||||
IMPL-006: EXAMPLES.md (Level 3, depends_on: [004])
|
||||
```
|
||||
|
||||
**TodoWrite Setup (Correct Dependency Order)**:
|
||||
```
|
||||
✅ Session initialization (completed)
|
||||
⏳ IMPL-001: Project Overview (pending)
|
||||
⏳ IMPL-002: Module 'auth' (pending)
|
||||
⏳ IMPL-003: Module 'api' (pending)
|
||||
⏳ IMPL-004: Architecture Documentation (pending)
|
||||
⏳ IMPL-005: API Documentation (pending)
|
||||
⏳ IMPL-001: Document tree 'src/modules/' (pending)
|
||||
⏳ IMPL-002: Document tree 'src/utils/' (pending)
|
||||
⏳ IMPL-003: Document tree 'lib/' (pending)
|
||||
⏳ IMPL-004: Project README (pending, depends on IMPL-001~003)
|
||||
⏳ IMPL-005: Architecture Documentation (pending, depends on IMPL-004)
|
||||
⏳ IMPL-006: Examples Documentation (pending, depends on IMPL-004)
|
||||
```
|
||||
|
||||
#### Phase 5: Task JSON Generation
|
||||
@@ -149,61 +210,148 @@ fi
|
||||
|
||||
## Task Templates
|
||||
|
||||
### 1. System Overview (IMPL-001)
|
||||
**Purpose**: Project-level documentation
|
||||
**Output**: `.workflow/docs/README.md`
|
||||
### Task Execution Order
|
||||
|
||||
**Level 1** (Parallel): Module tree tasks (IMPL-001 to IMPL-00N)
|
||||
**Level 2** (Sequential): Project README (IMPL-[N+1], depends on Level 1)
|
||||
**Level 3** (Parallel): Architecture, Examples, API docs (depends on Level 2)
|
||||
|
||||
### 1. Module Tree Task (IMPL-001 to IMPL-00N) - Level 1
|
||||
**Purpose**: Recursively document entire directory tree
|
||||
**Output**: Multiple files: `modules/*/API.md`, `modules/*/README.md`
|
||||
**Dependencies**: None (can run in parallel with other tree tasks)
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate Project Overview Documentation",
|
||||
"title": "Document Module Tree: 'src/modules/'",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"type": "docs-tree",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "project-overview"
|
||||
"template": "api + module-readme + folder-navigation"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document project purpose, architecture, and getting started guide",
|
||||
"Create navigation structure for all documentation",
|
||||
"Use Project-Level Documentation Template"
|
||||
"Recursively process all folders in src/modules/",
|
||||
"For folders with code files: generate API.md + README.md",
|
||||
"For folders with only subfolders: generate README.md (navigation)",
|
||||
"Use folder-analysis.txt to determine folder types"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"focus_paths": ["src/modules"],
|
||||
"folder_analysis_file": "${session_dir}/.process/folder-analysis.txt",
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/README.md following template",
|
||||
"All template sections populated with accurate information",
|
||||
"Navigation links to module and API documentation"
|
||||
"All code-containing folders have both API.md and README.md",
|
||||
"All navigation folders have README.md",
|
||||
"Documents follow their respective templates",
|
||||
"File hierarchy matches source structure"
|
||||
],
|
||||
"scope": "Project root and overall structure"
|
||||
"scope": "src/modules/ tree only"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "discover_project_structure",
|
||||
"action": "Get project module hierarchy metadata",
|
||||
"command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
|
||||
"output_to": "system_structure",
|
||||
"step": "load_folder_analysis",
|
||||
"action": "Load folder type analysis for this tree",
|
||||
"command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
|
||||
"output_to": "target_folders",
|
||||
"on_error": "fail",
|
||||
"note": "Lightweight metadata only - no file content"
|
||||
"note": "Filter analysis to only this tree's folders"
|
||||
},
|
||||
{
|
||||
"step": "analyze_tech_stack",
|
||||
"action": "Analyze technology stack from key config files",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack from key config files\\nMODE: analysis\\nCONTEXT: @{package.json,pom.xml,build.gradle,requirements.txt,go.mod,Cargo.toml,CLAUDE.md}\\nEXPECTED: Technology list and architecture style\\nRULES: Be concise, focus on stack only\")",
|
||||
"output_to": "tech_stack_analysis",
|
||||
"on_error": "skip_optional",
|
||||
"note": "Only analyze config files - small, controlled context"
|
||||
"step": "analyze_module_tree_content",
|
||||
"action": "Deep analysis of module tree content",
|
||||
"command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module tree comprehensively\\nTASK: For each folder, generate appropriate documentation (API.md for code folders, README.md for all)\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structured documentation content for entire tree\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) for API docs, $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-readme.txt) for module README, $(cat ~/.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt) for navigation README\")",
|
||||
"output_to": "tree_documentation",
|
||||
"on_error": "fail",
|
||||
"note": "Analysis scoped to focus_paths only - controlled context"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use system_structure and tech_stack_analysis to populate Project Overview Template",
|
||||
"task_description": "Generate all documentation files for the module tree based on folder types",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt",
|
||||
"Fill sections using [system_structure] and [tech_stack_analysis]",
|
||||
"Generate navigation links based on module paths",
|
||||
"Parse [target_folders] to get list of folders and their types",
|
||||
"For each folder in tree:",
|
||||
" if type == 'code':",
|
||||
" - Generate API.md using api.txt template (Part A: Code API)",
|
||||
" - Generate README.md using module-readme.txt template",
|
||||
" elif type == 'navigation':",
|
||||
" - Generate README.md using folder-navigation.txt template",
|
||||
"Maintain directory structure in output"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
".workflow/docs/modules/README.md",
|
||||
".workflow/docs/modules/*/API.md",
|
||||
".workflow/docs/modules/*/README.md",
|
||||
".workflow/docs/modules/*/*/API.md",
|
||||
".workflow/docs/modules/*/*/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Project README Task (IMPL-[N+1]) - Level 2
|
||||
**Purpose**: Project-level overview and navigation
|
||||
**Output**: `.workflow/docs/README.md`
|
||||
**Dependencies**: All Level 1 module tree tasks (MUST complete first)
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-004",
|
||||
"title": "Generate Project README",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "project-readme"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Aggregate information from all module documentation",
|
||||
"Generate navigation links to all modules",
|
||||
"Provide project overview and getting started guide",
|
||||
"Use Project README Template"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/README.md following template",
|
||||
"All modules linked in navigation",
|
||||
"Project structure clearly explained"
|
||||
],
|
||||
"scope": "Project root - aggregates all module info"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_module_docs",
|
||||
"action": "Load all module documentation for aggregation",
|
||||
"command": "bash(find .workflow/docs/modules -name 'README.md' -o -name 'API.md' | xargs cat)",
|
||||
"output_to": "all_module_docs",
|
||||
"on_error": "fail",
|
||||
"note": "This step requires all module tree tasks to be completed"
|
||||
},
|
||||
{
|
||||
"step": "analyze_project_structure",
|
||||
"action": "Synthesize project overview from module docs",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate project overview\\nTASK: Extract project structure, navigation, and summary from all module docs\\nMODE: analysis\\nCONTEXT: [all_module_docs] @{package.json,CLAUDE.md}\\nEXPECTED: Project README content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt) | Focus on navigation and aggregation\")",
|
||||
"output_to": "project_overview",
|
||||
"on_error": "fail",
|
||||
"note": "Synthesizes information from completed module docs"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Generate project README aggregating all module information",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt",
|
||||
"Extract module list and purposes from [all_module_docs]",
|
||||
"Generate navigation structure with links to all modules",
|
||||
"Fill template sections with [project_overview]",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
@@ -212,142 +360,166 @@ fi
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Module Documentation (IMPL-002+)
|
||||
**Purpose**: Module-level documentation
|
||||
**Output**: `.workflow/docs/modules/[name]/README.md`
|
||||
### 3. Architecture Documentation Task (IMPL-[N+2]) - Level 3
|
||||
**Purpose**: System design and patterns aggregation
|
||||
**Output**: `.workflow/docs/ARCHITECTURE.md`
|
||||
**Dependencies**: Project README (IMPL-[N+1]) - MUST complete first
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Document Module: 'auth'",
|
||||
"id": "IMPL-005",
|
||||
"title": "Generate Architecture Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-004"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "module-documentation"
|
||||
"template": "project-architecture"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document module purpose, internal architecture, public API",
|
||||
"Include dependencies and usage examples",
|
||||
"Use Module-Level Documentation Template"
|
||||
],
|
||||
"focus_paths": ["src/auth"],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/modules/auth/README.md",
|
||||
"All exported functions/classes documented",
|
||||
"Working code examples included"
|
||||
],
|
||||
"scope": "auth module only"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "analyze_module_content",
|
||||
"action": "Perform deep analysis of the specific module's content",
|
||||
"command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document 'auth' module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: Structured analysis of module content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
|
||||
"output_to": "module_analysis",
|
||||
"on_error": "fail",
|
||||
"note": "Analysis strictly limited to focus_paths ('src/auth') - controlled context"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use the detailed [module_analysis] to populate the Module-Level Documentation Template",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt",
|
||||
"Fill sections using [module_analysis]",
|
||||
"Generate code examples from actual usage",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [".workflow/docs/modules/auth/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Architecture Documentation (if requested)
|
||||
**Purpose**: System design and patterns
|
||||
**Output**: `.workflow/docs/architecture/`
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```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"
|
||||
"Synthesize system architecture from all module docs",
|
||||
"Aggregate API overview from all module API.md files",
|
||||
"Document module interactions and design patterns",
|
||||
"Use Project Architecture Template"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"acceptance": [
|
||||
"Complete architecture documentation in .workflow/docs/architecture/",
|
||||
"Diagrams explaining system design",
|
||||
"Clear explanation of architectural patterns"
|
||||
]
|
||||
"Complete .workflow/docs/ARCHITECTURE.md following template",
|
||||
"All modules included in architecture overview",
|
||||
"Aggregated API section with links to detailed docs"
|
||||
],
|
||||
"scope": "System-level architecture synthesis"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_module_docs",
|
||||
"action": "Aggregate all module documentation",
|
||||
"command": "bash(find .workflow/docs/modules -name 'README.md' -exec cat {} \\;)",
|
||||
"output_to": "module_docs",
|
||||
"on_error": "fail"
|
||||
"step": "load_all_docs",
|
||||
"action": "Load project README and all module documentation",
|
||||
"command": "bash(cat .workflow/docs/README.md && find .workflow/docs/modules -name 'README.md' -o -name 'API.md' | xargs cat)",
|
||||
"output_to": "all_docs",
|
||||
"on_error": "fail",
|
||||
"note": "Requires both project README and all module docs to be complete"
|
||||
},
|
||||
{
|
||||
"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",
|
||||
"step": "synthesize_architecture",
|
||||
"action": "Create system architecture synthesis",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create comprehensive architecture doc from all module information\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture documentation with patterns, module map, aggregated APIs\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt) | Focus on system-level view, aggregate APIs, show relationships\")",
|
||||
"output_to": "architecture_content",
|
||||
"on_error": "fail",
|
||||
"note": "Command varies: gemini-wrapper (default) | qwen-wrapper | codex exec"
|
||||
"note": "Synthesizes from completed documentation"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Create architecture documentation from synthesis",
|
||||
"task_description": "Generate architecture documentation synthesizing all module information",
|
||||
"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"
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt",
|
||||
"Extract module purposes and responsibilities from [all_docs]",
|
||||
"Build module map showing relationships",
|
||||
"Aggregate public APIs from all API.md files",
|
||||
"Generate architecture diagrams (text-based)",
|
||||
"Fill template sections with [architecture_content]",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [
|
||||
".workflow/docs/architecture/system-design.md",
|
||||
".workflow/docs/architecture/module-map.md",
|
||||
".workflow/docs/architecture/data-flow.md"
|
||||
]
|
||||
"target_files": [".workflow/docs/ARCHITECTURE.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. API Documentation (if requested)
|
||||
**Purpose**: API reference and specifications
|
||||
**Output**: `.workflow/docs/api/README.md`
|
||||
### 4. Examples Documentation Task (IMPL-[N+3]) - Level 3
|
||||
**Purpose**: Practical usage examples and best practices
|
||||
**Output**: `.workflow/docs/EXAMPLES.md`
|
||||
**Dependencies**: Project README (IMPL-[N+1]) - MUST complete first
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-N",
|
||||
"title": "Generate Unified API Documentation",
|
||||
"id": "IMPL-006",
|
||||
"title": "Generate Examples Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-004"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "api-reference"
|
||||
"template": "project-examples"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Create end-to-end usage examples spanning multiple modules",
|
||||
"Demonstrate common scenarios with complete, runnable code",
|
||||
"Show best practices and integration patterns",
|
||||
"Use Project Examples Template"
|
||||
],
|
||||
"focus_paths": ["."],
|
||||
"acceptance": [
|
||||
"Complete .workflow/docs/EXAMPLES.md following template",
|
||||
"All code examples are complete and runnable",
|
||||
"Core use cases covered with explanations"
|
||||
],
|
||||
"scope": "Project-level examples"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_project_readme",
|
||||
"action": "Load project README for context",
|
||||
"command": "bash(cat .workflow/docs/README.md)",
|
||||
"output_to": "project_readme",
|
||||
"on_error": "fail",
|
||||
"note": "Requires project README to be complete"
|
||||
},
|
||||
{
|
||||
"step": "identify_example_scenarios",
|
||||
"action": "Identify key usage scenarios from module docs",
|
||||
"command": "bash(find .workflow/docs/modules -name 'README.md' | xargs grep -A 5 'Usage Scenarios\\|Common Use Cases' | head -100)",
|
||||
"output_to": "module_usage_patterns",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"step": "generate_examples_content",
|
||||
"action": "Create comprehensive examples based on project structure",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate practical usage examples\\nTASK: Create end-to-end examples showing how modules work together\\nMODE: analysis\\nCONTEXT: [project_readme] [module_usage_patterns] @{src/**/*.ts}\\nEXPECTED: Complete, runnable code examples\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt) | Focus on real-world scenarios\")",
|
||||
"output_to": "examples_content",
|
||||
"on_error": "fail"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Generate comprehensive examples documentation",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt",
|
||||
"Identify 3-5 core usage scenarios from [module_usage_patterns]",
|
||||
"Generate complete, runnable code for each scenario",
|
||||
"Add explanations and best practices",
|
||||
"Fill template sections with [examples_content]",
|
||||
"Format output as Markdown"
|
||||
]
|
||||
},
|
||||
"target_files": [".workflow/docs/EXAMPLES.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. HTTP API Documentation (IMPL-[N+4]) - Level 3 (Optional)
|
||||
**Purpose**: REST/GraphQL API reference
|
||||
**Output**: `.workflow/docs/api/README.md`
|
||||
**Dependencies**: Project README (IMPL-[N+1])
|
||||
|
||||
**Complete JSON Structure**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-007",
|
||||
"title": "Generate HTTP API Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-004"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"template": "api"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
@@ -376,16 +548,17 @@ fi
|
||||
{
|
||||
"step": "analyze_api_structure",
|
||||
"action": "Analyze API structure and patterns",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete HTTP API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api.txt) | Use Part B: HTTP API only\")",
|
||||
"output_to": "api_analysis",
|
||||
"on_error": "fail",
|
||||
"note": "Analysis limited to API-related paths - controlled context"
|
||||
}
|
||||
],
|
||||
"implementation_approach": {
|
||||
"task_description": "Use api_analysis to populate API-Level Documentation Template",
|
||||
"task_description": "Use api_analysis to populate HTTP API Documentation Template",
|
||||
"logic_flow": [
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt",
|
||||
"Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api.txt",
|
||||
"Use Part B: HTTP API section only",
|
||||
"Parse api_analysis for: endpoints, auth, request/response",
|
||||
"Fill template sections with extracted information",
|
||||
"Generate OpenAPI spec if REST API detected",
|
||||
@@ -427,54 +600,114 @@ fi
|
||||
**Session**: WFS-docs-[timestamp]
|
||||
**Type**: [architecture|api|all]
|
||||
**Tool**: [gemini|qwen|codex]
|
||||
**Strategy**: Bottom-up, layered approach
|
||||
|
||||
## Task Breakdown
|
||||
## Task Breakdown by Level
|
||||
|
||||
### IMPL-001: System Overview
|
||||
- **Output**: .workflow/docs/README.md
|
||||
- **Template**: project-overview.txt
|
||||
### Level 1: Module Tree Tasks (Parallel Execution)
|
||||
- **IMPL-001**: Document tree 'src/modules/'
|
||||
- Output: modules/*/API.md, modules/*/README.md
|
||||
- Templates: api.txt (Part A), module-readme.txt, folder-navigation.txt
|
||||
- **IMPL-002**: Document tree 'src/utils/'
|
||||
- **IMPL-003**: Document tree 'lib/'
|
||||
|
||||
### IMPL-002+: Module Documentation
|
||||
- **Modules**: [list]
|
||||
- **Template**: module-documentation.txt
|
||||
### Level 2: Project README (Sequential - Depends on Level 1)
|
||||
- **IMPL-004**: Generate Project README
|
||||
- Output: .workflow/docs/README.md
|
||||
- Template: project-readme.txt
|
||||
- Dependencies: IMPL-001, IMPL-002, IMPL-003
|
||||
|
||||
### IMPL-N: Architecture/API (if requested)
|
||||
- **Template**: architecture.txt / api-reference.txt
|
||||
### Level 3: Architecture & Examples (Parallel - Depends on Level 2)
|
||||
- **IMPL-005**: Generate Architecture Documentation
|
||||
- Output: .workflow/docs/ARCHITECTURE.md
|
||||
- Template: project-architecture.txt
|
||||
- Dependencies: IMPL-004
|
||||
- **IMPL-006**: Generate Examples Documentation
|
||||
- Output: .workflow/docs/EXAMPLES.md
|
||||
- Template: project-examples.txt
|
||||
- Dependencies: IMPL-004
|
||||
- **IMPL-007**: Generate HTTP API Documentation (Optional)
|
||||
- Output: .workflow/docs/api/README.md
|
||||
- Template: api.txt (Part B)
|
||||
- Dependencies: IMPL-004
|
||||
|
||||
## Execution Order
|
||||
1. IMPL-001 (Foundation)
|
||||
2. IMPL-002 to IMPL-[M] (Modules - can parallelize)
|
||||
3. IMPL-[M+1] (Architecture - needs modules)
|
||||
4. IMPL-[N] (API - can run after IMPL-001)
|
||||
## Execution Order (Respects Dependencies)
|
||||
1. **Level 1** (Parallel): IMPL-001, IMPL-002, IMPL-003
|
||||
2. **Level 2** (After Level 1): IMPL-004
|
||||
3. **Level 3** (After Level 2, can parallelize within level): IMPL-005, IMPL-006, IMPL-007
|
||||
```
|
||||
|
||||
### TODO_LIST.md
|
||||
```markdown
|
||||
# Documentation Progress Tracker
|
||||
|
||||
- [ ] **IMPL-001**: Generate Project Overview
|
||||
- [ ] **IMPL-002**: Document Module: 'auth'
|
||||
- [ ] **IMPL-003**: Document Module: 'api'
|
||||
- [ ] **IMPL-004**: Generate Architecture Documentation
|
||||
- [ ] **IMPL-005**: Generate Unified API Documentation
|
||||
## Level 1: Module Tree Tasks (Can execute in parallel)
|
||||
- [ ] **IMPL-001**: Document tree 'src/modules/'
|
||||
- [ ] **IMPL-002**: Document tree 'src/utils/'
|
||||
- [ ] **IMPL-003**: Document tree 'lib/'
|
||||
|
||||
## Level 2: Project README (Execute after Level 1)
|
||||
- [ ] **IMPL-004**: Generate Project README (depends on IMPL-001~003)
|
||||
|
||||
## Level 3: Architecture & Examples (Execute after Level 2, can parallelize)
|
||||
- [ ] **IMPL-005**: Generate Architecture Documentation (depends on IMPL-004)
|
||||
- [ ] **IMPL-006**: Generate Examples Documentation (depends on IMPL-004)
|
||||
- [ ] **IMPL-007**: Generate HTTP API Documentation (Optional, depends on IMPL-004)
|
||||
|
||||
## Execution
|
||||
|
||||
### Sequential (Respects Dependencies)
|
||||
```bash
|
||||
# Level 1 - Execute in parallel or sequence
|
||||
/workflow:execute IMPL-001
|
||||
/workflow:execute IMPL-002
|
||||
# ...
|
||||
/workflow:execute IMPL-003
|
||||
|
||||
# Wait for Level 1 to complete, then Level 2
|
||||
/workflow:execute IMPL-004
|
||||
|
||||
# Wait for Level 2 to complete, then Level 3 (can parallelize)
|
||||
/workflow:execute IMPL-005
|
||||
/workflow:execute IMPL-006
|
||||
/workflow:execute IMPL-007 # if applicable
|
||||
```
|
||||
|
||||
### With Dependency Awareness (Future Enhancement)
|
||||
```bash
|
||||
# /workflow:execute will automatically handle dependencies
|
||||
/workflow:execute --auto-deps IMPL-007
|
||||
# This would automatically execute IMPL-001~003 → IMPL-004 → IMPL-007
|
||||
```
|
||||
```
|
||||
|
||||
## Execution Phase
|
||||
|
||||
### Via /workflow:execute
|
||||
### Layered Execution Flow
|
||||
|
||||
```
|
||||
For Each Task (IMPL-001, IMPL-002, ...):
|
||||
Phase 1: Module Tree Generation (Level 1 - Parallel)
|
||||
├─ /workflow:execute IMPL-001 (src/modules/) ──┐
|
||||
├─ /workflow:execute IMPL-002 (src/utils/) ──┼─> All complete
|
||||
└─ /workflow:execute IMPL-003 (lib/) ──┘
|
||||
│
|
||||
Phase 2: Project README (Level 2 - Sequential) │
|
||||
└─ /workflow:execute IMPL-004 <────────────────┘ (Waits for Level 1)
|
||||
│
|
||||
Phase 3: Architecture & Examples (Level 3) │
|
||||
├─ /workflow:execute IMPL-005 (Architecture) <─┤
|
||||
├─ /workflow:execute IMPL-006 (Examples) <──┤ (Waits for Level 2)
|
||||
└─ /workflow:execute IMPL-007 (HTTP API) <──┘
|
||||
```
|
||||
|
||||
### Per-Task Execution Flow
|
||||
|
||||
```
|
||||
For Each Task (IMPL-001 to IMPL-007):
|
||||
|
||||
/workflow:execute IMPL-NNN
|
||||
↓
|
||||
Check dependencies (if specified in depends_on)
|
||||
↓
|
||||
TodoWrite: pending → in_progress
|
||||
↓
|
||||
Execute flow_control (pre_analysis steps)
|
||||
@@ -510,20 +743,25 @@ After IMPL-001:
|
||||
|
||||
## Documentation Output
|
||||
|
||||
### Final Structure
|
||||
### Final Structure (Revised)
|
||||
```
|
||||
.workflow/docs/
|
||||
├── README.md # IMPL-001: Project overview
|
||||
├── modules/
|
||||
│ ├── auth/README.md # IMPL-002: Auth module
|
||||
│ └── api/README.md # IMPL-003: API module
|
||||
├── architecture/ # IMPL-004: Architecture
|
||||
│ ├── system-design.md
|
||||
│ ├── module-map.md
|
||||
│ └── data-flow.md
|
||||
└── api/ # IMPL-005: API docs
|
||||
├── README.md
|
||||
└── openapi.yaml
|
||||
├── modules/ # IMPL-001,002,003 (Level 1)
|
||||
│ ├── README.md # Navigation for modules/
|
||||
│ ├── auth/
|
||||
│ │ ├── API.md # Auth module API signatures
|
||||
│ │ ├── README.md # Auth module documentation
|
||||
│ │ └── middleware/
|
||||
│ │ ├── API.md # Middleware API
|
||||
│ │ └── README.md # Middleware docs
|
||||
│ └── api/
|
||||
│ ├── API.md # API module signatures
|
||||
│ └── README.md # API module docs
|
||||
├── README.md # IMPL-004 (Level 2) - Project overview
|
||||
├── ARCHITECTURE.md # IMPL-005 (Level 3) - System architecture
|
||||
├── EXAMPLES.md # IMPL-006 (Level 3) - Usage examples
|
||||
└── api/ # IMPL-007 (Level 3, Optional)
|
||||
└── README.md # HTTP API reference
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
@@ -569,21 +807,35 @@ cat .workflow/docs/README.md
|
||||
|
||||
## Key Benefits
|
||||
|
||||
### Bottom-Up Documentation Strategy
|
||||
- **Self-contained modules first**: Each module gets complete documentation (API.md + README.md)
|
||||
- **Project-level aggregation**: README, Architecture, Examples synthesize from completed modules
|
||||
- **No premature aggregation**: Project docs wait for all module docs to complete
|
||||
|
||||
### Dynamic Folder Structure Recognition
|
||||
- **No hardcoded paths**: Automatically discovers all project directories
|
||||
- **Intelligent type detection**: Code folders get API.md + README.md, navigation folders get README.md only
|
||||
- **Respects project structure**: Works with any directory layout (not just "modules/")
|
||||
|
||||
### Clear Separation of Concerns
|
||||
- **Planning**: Session creation, task decomposition (this command)
|
||||
- **Execution**: Content generation, quality assurance (doc-generator agent)
|
||||
- **API.md**: Pure interface signatures (what can be called)
|
||||
- **README.md**: Purpose, usage, concepts (how and why to use it)
|
||||
- **Architecture.md**: System design and module relationships
|
||||
- **Examples.md**: End-to-end usage scenarios
|
||||
|
||||
### Correct Dependency Management
|
||||
- **Level 1** (Module trees): Can execute in parallel
|
||||
- **Level 2** (Project README): Must wait for all module docs
|
||||
- **Level 3** (Architecture/Examples): Must wait for project README
|
||||
- **Prevents incomplete aggregation**: Ensures all source data exists before synthesis
|
||||
|
||||
### Scalable Task Management
|
||||
- Independent, self-contained tasks
|
||||
- Parallelizable module documentation
|
||||
- Clear dependencies (architecture needs modules)
|
||||
- **Coarse-grained tasks**: One task per top-level directory tree (not per module)
|
||||
- **Recursive processing**: Each task handles all subfolders within its tree
|
||||
- **Reduced task count**: 3 tree tasks instead of 10+ module tasks
|
||||
|
||||
### Template-Driven Consistency
|
||||
- All documentation follows standard templates
|
||||
- Reusable and maintainable
|
||||
- Easy to update standards
|
||||
|
||||
### Full Context for Execution
|
||||
- Each task JSON contains complete instructions
|
||||
- flow_control defines exact analysis steps
|
||||
- Tool selection for flexibility
|
||||
- **5 specialized templates**: api (unified), module-readme, folder-navigation, project-architecture, project-examples
|
||||
- **Clear template purpose**: Each template focuses on a single documentation aspect
|
||||
- **Unified API template**: Single api.txt handles both Code API (Part A) and HTTP API (Part B)
|
||||
- **No content duplication**: API signatures stay in API.md, usage stays in README.md
|
||||
|
||||
@@ -1,240 +0,0 @@
|
||||
# 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
|
||||
337
.claude/workflows/cli-templates/prompts/documentation/api.txt
Normal file
337
.claude/workflows/cli-templates/prompts/documentation/api.txt
Normal file
@@ -0,0 +1,337 @@
|
||||
# Unified API Documentation Template
|
||||
|
||||
Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
|
||||
|
||||
---
|
||||
|
||||
## Part A: Code API (For Libraries, Modules, SDKs)
|
||||
|
||||
**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.
|
||||
|
||||
**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.
|
||||
|
||||
### 1. Exported Functions
|
||||
|
||||
For each exported function, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of what the function does
|
||||
* @param paramName - Parameter type and description
|
||||
* @returns Return type and description
|
||||
* @throws ErrorType - When this error occurs
|
||||
*/
|
||||
export function functionName(paramName: ParamType): ReturnType;
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Authenticates a user with email and password
|
||||
* @param credentials - User email and password
|
||||
* @returns Authentication token and user info
|
||||
* @throws AuthenticationError - When credentials are invalid
|
||||
*/
|
||||
export function authenticate(credentials: Credentials): Promise<AuthResult>;
|
||||
```
|
||||
|
||||
### 2. Exported Classes
|
||||
|
||||
For each exported class, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief one-line description of the class purpose
|
||||
*/
|
||||
export class ClassName {
|
||||
constructor(param: Type);
|
||||
|
||||
// Public properties
|
||||
propertyName: Type;
|
||||
|
||||
// Public methods
|
||||
methodName(param: Type): ReturnType;
|
||||
}
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```typescript
|
||||
/**
|
||||
* Manages user session lifecycle and token refresh
|
||||
*/
|
||||
export class SessionManager {
|
||||
constructor(config: SessionConfig);
|
||||
|
||||
// Current session state
|
||||
isActive: boolean;
|
||||
|
||||
// Refresh the session token
|
||||
refresh(): Promise<void>;
|
||||
|
||||
// Terminate the session
|
||||
destroy(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Exported Interfaces
|
||||
|
||||
For each exported interface, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this interface represents
|
||||
*/
|
||||
export interface InterfaceName {
|
||||
field1: Type; // Field description
|
||||
field2: Type; // Field description
|
||||
method?: (param: Type) => ReturnType; // Optional method
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Type Definitions
|
||||
|
||||
For each exported type, provide:
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what this type represents
|
||||
*/
|
||||
export type TypeName = string | number | CustomType;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part B: HTTP API (For Web Services, REST APIs, GraphQL)
|
||||
|
||||
**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.
|
||||
|
||||
**Omit this section if**: This is a library/SDK with no HTTP interface.
|
||||
|
||||
### 1. Overview
|
||||
|
||||
[Brief description of the API's purpose and capabilities]
|
||||
|
||||
**Base URL**:
|
||||
```
|
||||
Production: https://api.example.com/v1
|
||||
Staging: https://staging.api.example.com/v1
|
||||
Development: http://localhost:3000/api/v1
|
||||
```
|
||||
|
||||
### 2. Authentication
|
||||
|
||||
#### Authentication Method
|
||||
[e.g., JWT Bearer Token, OAuth2, API Keys]
|
||||
|
||||
#### Obtaining Credentials
|
||||
```bash
|
||||
# Example: Login to get token
|
||||
curl -X POST https://api.example.com/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email": "user@example.com", "password": "password"}'
|
||||
```
|
||||
|
||||
#### Using Credentials
|
||||
```http
|
||||
GET /api/resource HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 3. Common Response Codes
|
||||
|
||||
| Code | Description | Common Causes |
|
||||
|------|-------------|---------------|
|
||||
| 200 | Success | Request completed successfully |
|
||||
| 201 | Created | Resource created successfully |
|
||||
| 400 | Bad Request | Invalid request body or parameters |
|
||||
| 401 | Unauthorized | Missing or invalid authentication |
|
||||
| 403 | Forbidden | Authenticated but not authorized |
|
||||
| 404 | Not Found | Resource does not exist |
|
||||
| 429 | Too Many Requests | Rate limit exceeded |
|
||||
| 500 | Internal Server Error | Server-side error |
|
||||
|
||||
### 4. Endpoints
|
||||
|
||||
#### Resource: [Resource Name, e.g., Users]
|
||||
|
||||
##### GET /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Query Parameters**:
|
||||
| Parameter | Type | Required | Description | Default |
|
||||
|-----------|------|----------|-------------|---------|
|
||||
| `limit` | number | No | Number of results | 20 |
|
||||
| `offset` | number | No | Pagination offset | 0 |
|
||||
|
||||
**Example Request**:
|
||||
```http
|
||||
GET /users?limit=10&offset=0 HTTP/1.1
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"total": 100,
|
||||
"limit": 10,
|
||||
"offset": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Response (401 Unauthorized)**:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "UNAUTHORIZED",
|
||||
"message": "Invalid or expired token"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### POST /resource
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"field1": "value",
|
||||
"field2": 123
|
||||
}
|
||||
```
|
||||
|
||||
**Validation Rules**:
|
||||
- `field1`: Required, 2-100 characters
|
||||
- `field2`: Required, positive integer
|
||||
|
||||
**Response (201 Created)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "value",
|
||||
"field2": 123,
|
||||
"created_at": "2024-01-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### PUT /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Request Body** (all fields optional):
|
||||
```json
|
||||
{
|
||||
"field1": "new value"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK)**:
|
||||
```json
|
||||
{
|
||||
"id": 124,
|
||||
"field1": "new value",
|
||||
"updated_at": "2024-01-21T09:15:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
##### DELETE /resource/:id
|
||||
**Description**: [What this endpoint does]
|
||||
|
||||
**Path Parameters**:
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `id` | number | Resource ID |
|
||||
|
||||
**Response (204 No Content)**:
|
||||
[Empty response body]
|
||||
|
||||
---
|
||||
|
||||
### 5. 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
|
||||
|
||||
**Example Response Headers**:
|
||||
```http
|
||||
X-RateLimit-Limit: 1000
|
||||
X-RateLimit-Remaining: 847
|
||||
X-RateLimit-Reset: 1640000000
|
||||
```
|
||||
|
||||
### 6. Webhooks (Optional)
|
||||
|
||||
[Description of webhook system if applicable]
|
||||
|
||||
**Webhook Events**:
|
||||
- `resource.created` - Triggered when a new resource is created
|
||||
- `resource.updated` - Triggered when a resource is updated
|
||||
- `resource.deleted` - Triggered when a resource is deleted
|
||||
|
||||
**Webhook Payload Example**:
|
||||
```json
|
||||
{
|
||||
"event": "resource.created",
|
||||
"timestamp": "2024-01-20T12:00:00Z",
|
||||
"data": {
|
||||
"id": 124,
|
||||
"field1": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
|
||||
2. **Signatures only in Part A** - No implementation code in Code API section
|
||||
3. **Complete examples in Part B** - All HTTP examples should be runnable
|
||||
4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
|
||||
5. **Brief descriptions** - One line per item is sufficient for Code API
|
||||
6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
|
||||
7. **Alphabetical order** - Sort items within each section for easy lookup
|
||||
8. **Public API only** - Do not document internal/private exports or endpoints
|
||||
|
||||
---
|
||||
|
||||
## Template Usage Guidelines
|
||||
|
||||
### For Module-Level API.md (Code API)
|
||||
**Use**: Part A only
|
||||
**Location**: `modules/[module-name]/API.md`
|
||||
**Focus**: Exported functions, classes, interfaces
|
||||
|
||||
### For Project-Level HTTP API Documentation
|
||||
**Use**: Part B only
|
||||
**Location**: `.workflow/docs/api/README.md`
|
||||
**Focus**: REST/GraphQL endpoints, authentication
|
||||
|
||||
### For Full-Stack Projects (Both Code and HTTP APIs)
|
||||
**Use**: Both Part A and Part B
|
||||
**Organization**:
|
||||
- Part A for SDK/client library APIs
|
||||
- Part B for HTTP endpoints
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**API Version**: [Version number]
|
||||
**Module/Service Path**: [Auto-fill with actual path]
|
||||
@@ -0,0 +1,68 @@
|
||||
# Folder Navigation Documentation Template
|
||||
|
||||
Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Overview
|
||||
|
||||
Brief description of what this directory/category contains:
|
||||
|
||||
> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
|
||||
|
||||
### 2. Directory Structure
|
||||
|
||||
Provide a tree view of the subdirectories with brief descriptions:
|
||||
|
||||
```
|
||||
modules/
|
||||
├── auth/ - User authentication and authorization
|
||||
├── api/ - API route handlers and middleware
|
||||
├── database/ - Database connections and ORM models
|
||||
└── utils/ - Shared utility functions
|
||||
```
|
||||
|
||||
### 3. Module Quick Reference
|
||||
|
||||
Table format for quick scanning:
|
||||
|
||||
| Module | Purpose | Key Features |
|
||||
|--------|---------|--------------|
|
||||
| [auth](./auth/) | Authentication | JWT tokens, session management |
|
||||
| [api](./api/) | API routing | REST endpoints, validation |
|
||||
| [database](./database/) | Data layer | PostgreSQL, migrations |
|
||||
| [utils](./utils/) | Utilities | Logging, helpers |
|
||||
|
||||
### 4. How to Navigate
|
||||
|
||||
Guidance on which module to explore based on needs:
|
||||
|
||||
- **For authentication logic** → [auth module](./auth/)
|
||||
- **For API endpoints** → [api module](./api/)
|
||||
- **For database queries** → [database module](./database/)
|
||||
- **For helper functions** → [utils module](./utils/)
|
||||
|
||||
### 5. Module Relationships (Optional)
|
||||
|
||||
If modules have significant dependencies, show them:
|
||||
|
||||
```
|
||||
api → auth (uses for authentication)
|
||||
api → database (uses for data access)
|
||||
auth → database (uses for user storage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Keep it brief** - This is an index, not detailed documentation
|
||||
2. **One-line descriptions** - Each module gets a concise purpose statement
|
||||
3. **Scannable format** - Use tables and lists for quick navigation
|
||||
4. **Link to submodules** - Every module mentioned should link to its README
|
||||
5. **No code examples** - This is navigation only
|
||||
|
||||
---
|
||||
|
||||
**Directory Path**: [Auto-fill with actual directory path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
@@ -1,91 +0,0 @@
|
||||
# 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,98 @@
|
||||
# Module README Documentation Template
|
||||
|
||||
Generate comprehensive module documentation focused on understanding and usage. Explain WHAT the module does, WHY it exists, and HOW to use it. Do NOT duplicate API signatures (those belong in API.md).
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Purpose
|
||||
|
||||
**What**: Clearly state what this module is responsible for
|
||||
**Why**: Explain why this module exists and what problems it solves
|
||||
**Boundaries**: Define what is IN scope and OUT of scope
|
||||
|
||||
Example:
|
||||
> The `auth` module handles user authentication and authorization. It exists to centralize security logic and provide a consistent authentication interface across the application. It does NOT handle user profile management or session storage.
|
||||
|
||||
### 2. Core Concepts
|
||||
|
||||
List and explain key concepts, patterns, or abstractions used by this module:
|
||||
|
||||
- **Concept 1**: [Brief explanation of important concept]
|
||||
- **Concept 2**: [Another key concept users should understand]
|
||||
- **Pattern**: [Architectural pattern used, e.g., "Uses middleware pattern for request processing"]
|
||||
|
||||
### 3. Usage Scenarios
|
||||
|
||||
Provide 2-4 common use cases with code examples:
|
||||
|
||||
#### Scenario 1: [Common use case title]
|
||||
```typescript
|
||||
// Brief example showing how to use the module for this scenario
|
||||
import { functionName } from './module';
|
||||
|
||||
const result = functionName(input);
|
||||
```
|
||||
|
||||
#### Scenario 2: [Another common use case]
|
||||
```typescript
|
||||
// Another practical example
|
||||
```
|
||||
|
||||
### 4. Dependencies
|
||||
|
||||
#### Internal Dependencies
|
||||
List other project modules this module depends on and explain why:
|
||||
- **[Module Name]** - [Why this dependency exists and what it provides]
|
||||
|
||||
#### External Dependencies
|
||||
List third-party libraries and their purpose:
|
||||
- **[Library Name]** (`version`) - [What functionality it provides to this module]
|
||||
|
||||
### 5. Configuration
|
||||
|
||||
#### Environment Variables
|
||||
List any environment variables the module uses:
|
||||
- `ENV_VAR_NAME` - [Description, type, default value]
|
||||
|
||||
#### Configuration Options
|
||||
If the module accepts configuration objects:
|
||||
```typescript
|
||||
// Example configuration
|
||||
const config = {
|
||||
option1: value, // Description of option1
|
||||
option2: value, // Description of option2
|
||||
};
|
||||
```
|
||||
|
||||
### 6. Testing
|
||||
|
||||
Explain how to test code that uses this module:
|
||||
```bash
|
||||
# Command to run tests for this module
|
||||
npm test -- path/to/module
|
||||
```
|
||||
|
||||
**Test Coverage**: [Brief note on what's tested]
|
||||
|
||||
### 7. Common Issues
|
||||
|
||||
List 2-3 common problems and their solutions:
|
||||
|
||||
#### Issue: [Common problem description]
|
||||
**Solution**: [How to resolve it]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **No API duplication** - Refer to API.md for signatures
|
||||
2. **Focus on understanding** - Explain concepts, not just code
|
||||
3. **Practical examples** - Show real usage, not trivial cases
|
||||
4. **Clear dependencies** - Help readers understand module relationships
|
||||
5. **Concise** - Each section should be scannable and to-the-point
|
||||
|
||||
---
|
||||
|
||||
**Module Path**: [Auto-fill with actual module path]
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**: [Link to API.md for interface details]
|
||||
@@ -0,0 +1,167 @@
|
||||
# Project Architecture Documentation Template
|
||||
|
||||
Generate comprehensive architecture documentation that synthesizes information from all module documents. Focus on system-level design, module relationships, and aggregated API overview. This document should be created AFTER all module documentation is complete.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. System Overview
|
||||
|
||||
High-level description of the system architecture:
|
||||
|
||||
**Architectural Style**: [e.g., Layered, Microservices, Event-Driven, Hexagonal]
|
||||
|
||||
**Core Principles**:
|
||||
- [Principle 1, e.g., "Separation of concerns"]
|
||||
- [Principle 2, e.g., "Dependency inversion"]
|
||||
- [Principle 3, e.g., "Single responsibility"]
|
||||
|
||||
**Technology Stack**:
|
||||
- **Languages**: [Primary programming languages]
|
||||
- **Frameworks**: [Key frameworks]
|
||||
- **Databases**: [Data storage solutions]
|
||||
- **Infrastructure**: [Deployment, hosting, CI/CD]
|
||||
|
||||
### 2. System Structure
|
||||
|
||||
Visual representation of the system structure using text diagrams:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (API Routes, Controllers) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Business Logic Layer │
|
||||
│ (Modules: auth, orders, payments) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ Data Access Layer │
|
||||
│ (Database, ORM, Repositories) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. Module Map
|
||||
|
||||
Comprehensive list of all modules with their responsibilities:
|
||||
|
||||
| Module | Layer | Responsibility | Dependencies |
|
||||
|--------|-------|----------------|--------------|
|
||||
| `auth` | Business | Authentication & authorization | database, utils |
|
||||
| `api` | Application | HTTP routing & validation | auth, orders |
|
||||
| `database` | Data | Data persistence | - |
|
||||
| `utils` | Infrastructure | Shared utilities | - |
|
||||
|
||||
### 4. Module Interactions
|
||||
|
||||
Describe key interaction patterns between modules:
|
||||
|
||||
#### Data Flow Example: User Authentication
|
||||
```
|
||||
1. Client → api/login endpoint
|
||||
2. api → auth.authenticateUser()
|
||||
3. auth → database.findUser()
|
||||
4. database → PostgreSQL
|
||||
5. auth → JWT token generation
|
||||
6. api → Response with token
|
||||
```
|
||||
|
||||
#### Dependency Graph
|
||||
```
|
||||
api ──────┐
|
||||
├──→ auth ───→ database
|
||||
orders ───┤ ↑
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### 5. Design Patterns
|
||||
|
||||
Document key architectural patterns used:
|
||||
|
||||
#### Pattern 1: [Pattern Name, e.g., "Repository Pattern"]
|
||||
- **Where**: [Which modules use this pattern]
|
||||
- **Why**: [Reason for using this pattern]
|
||||
- **How**: [Brief explanation of implementation]
|
||||
|
||||
#### Pattern 2: [Another pattern]
|
||||
[Similar structure]
|
||||
|
||||
### 6. Aggregated API Overview
|
||||
|
||||
High-level summary of all public APIs across modules. Group by category:
|
||||
|
||||
#### Authentication APIs
|
||||
- `auth.authenticate(credentials)` - Validate user credentials
|
||||
- `auth.authorize(user, permission)` - Check user permissions
|
||||
- `auth.generateToken(userId)` - Create JWT token
|
||||
|
||||
#### Data APIs
|
||||
- `database.findOne(query)` - Find single record
|
||||
- `database.findMany(query)` - Find multiple records
|
||||
- `database.insert(data)` - Insert new record
|
||||
|
||||
#### Utility APIs
|
||||
- `utils.logger.log(message)` - Application logging
|
||||
- `utils.validator.validate(data, schema)` - Data validation
|
||||
|
||||
*Note: For detailed API signatures, refer to individual module API.md files*
|
||||
|
||||
### 7. Data Flow
|
||||
|
||||
Describe how data moves through the system:
|
||||
|
||||
**Request Lifecycle**:
|
||||
1. HTTP request enters through API layer
|
||||
2. Request validation and authentication (auth module)
|
||||
3. Business logic processing (domain modules)
|
||||
4. Data persistence (database module)
|
||||
5. Response formatting and return
|
||||
|
||||
**Event Flow** (if applicable):
|
||||
- [Describe event-driven flows if present]
|
||||
|
||||
### 8. Security Architecture
|
||||
|
||||
Overview of security measures:
|
||||
|
||||
- **Authentication**: [JWT, OAuth2, etc.]
|
||||
- **Authorization**: [RBAC, ACL, etc.]
|
||||
- **Data Protection**: [Encryption, hashing]
|
||||
- **API Security**: [Rate limiting, CORS, etc.]
|
||||
|
||||
### 9. Scalability Considerations
|
||||
|
||||
Architectural decisions that support scalability:
|
||||
|
||||
- [Horizontal scaling approach]
|
||||
- [Caching strategy]
|
||||
- [Database optimization]
|
||||
- [Load balancing]
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Synthesize, don't duplicate** - Reference module docs, don't copy them
|
||||
2. **System-level perspective** - Focus on how modules work together
|
||||
3. **Visual aids** - Use diagrams for clarity (ASCII art is fine)
|
||||
4. **Aggregated APIs** - One-line summaries only, link to detailed docs
|
||||
5. **Design rationale** - Explain WHY decisions were made
|
||||
6. **Maintain consistency** - Ensure all module docs are considered
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
This document requires the following to be available:
|
||||
- All module README.md files (for understanding module purposes)
|
||||
- All module API.md files (for aggregating API overview)
|
||||
- Project README.md (for context and navigation)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for project overview
|
||||
- [Module Documentation](./modules/) for detailed module docs
|
||||
@@ -0,0 +1,205 @@
|
||||
# Project Examples Documentation Template
|
||||
|
||||
Generate practical, end-to-end examples demonstrating core usage patterns of the project. Focus on realistic scenarios that span multiple modules. These examples should help users understand how to accomplish common tasks.
|
||||
|
||||
## Structure
|
||||
|
||||
### 1. Introduction
|
||||
|
||||
Brief overview of what these examples cover:
|
||||
|
||||
> This document provides complete, working examples for common use cases. Each example demonstrates how multiple modules work together to accomplish a specific task.
|
||||
|
||||
**Prerequisites**:
|
||||
- [List required setup, e.g., "Project installed and configured"]
|
||||
- [Environment requirements, e.g., "PostgreSQL running on localhost"]
|
||||
|
||||
### 2. Quick Start Example
|
||||
|
||||
The simplest possible working example to get started:
|
||||
|
||||
```typescript
|
||||
// The minimal example to verify setup
|
||||
import { App } from './src';
|
||||
|
||||
const app = new App();
|
||||
await app.start();
|
||||
console.log('Application running!');
|
||||
```
|
||||
|
||||
**What this does**: [Brief explanation]
|
||||
|
||||
### 3. Core Use Cases
|
||||
|
||||
Provide 3-5 complete examples for common scenarios:
|
||||
|
||||
#### Example 1: [Scenario Name, e.g., "User Registration and Login"]
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
|
||||
**Modules involved**: `auth`, `database`, `api`
|
||||
|
||||
**Complete code**:
|
||||
```typescript
|
||||
import { createUser, authenticateUser } from './modules/auth';
|
||||
import { startServer } from './modules/api';
|
||||
|
||||
// Step 1: Initialize the application
|
||||
const app = await startServer({ port: 3000 });
|
||||
|
||||
// Step 2: Register a new user
|
||||
const user = await createUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123',
|
||||
name: 'John Doe'
|
||||
});
|
||||
|
||||
// Step 3: Authenticate the user
|
||||
const session = await authenticateUser({
|
||||
email: 'user@example.com',
|
||||
password: 'securePassword123'
|
||||
});
|
||||
|
||||
// Step 4: Use the authentication token
|
||||
console.log('Login successful, token:', session.token);
|
||||
```
|
||||
|
||||
**Expected output**:
|
||||
```
|
||||
Server started on port 3000
|
||||
User created: { id: 1, email: 'user@example.com', name: 'John Doe' }
|
||||
Login successful, token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**Explanation**:
|
||||
1. [Step-by-step breakdown of what each part does]
|
||||
2. [How modules interact]
|
||||
3. [Common variations or customizations]
|
||||
|
||||
---
|
||||
|
||||
#### Example 2: [Another Common Scenario]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
---
|
||||
|
||||
#### Example 3: [Another Use Case]
|
||||
|
||||
[Similar structure with complete code]
|
||||
|
||||
### 4. Advanced Examples
|
||||
|
||||
More complex scenarios for power users:
|
||||
|
||||
#### Advanced Example 1: [Complex Scenario]
|
||||
|
||||
**Objective**: [What this example accomplishes]
|
||||
|
||||
**Modules involved**: [List]
|
||||
|
||||
```typescript
|
||||
// Complete working code with detailed comments
|
||||
```
|
||||
|
||||
**Key points**:
|
||||
- [Important concept or gotcha]
|
||||
- [Performance consideration]
|
||||
- [Security note]
|
||||
|
||||
### 5. Integration Examples
|
||||
|
||||
Examples showing how to integrate with external systems:
|
||||
|
||||
#### Integration with [External System]
|
||||
|
||||
```typescript
|
||||
// Example of integrating with a third-party service
|
||||
```
|
||||
|
||||
### 6. Testing Examples
|
||||
|
||||
Show how to test code that uses this project:
|
||||
|
||||
```typescript
|
||||
// Example test case using the project
|
||||
import { describe, it, expect } from 'your-test-framework';
|
||||
|
||||
describe('User authentication', () => {
|
||||
it('should authenticate valid credentials', async () => {
|
||||
const result = await authenticateUser({
|
||||
email: 'test@example.com',
|
||||
password: 'password123'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.token).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 7. Best Practices
|
||||
|
||||
Demonstrate recommended patterns:
|
||||
|
||||
#### Pattern 1: [Best Practice Title]
|
||||
```typescript
|
||||
// Good: Recommended approach
|
||||
const result = await handleWithErrorRecovery(operation);
|
||||
|
||||
// Bad: Anti-pattern to avoid
|
||||
const result = operation(); // No error handling
|
||||
```
|
||||
|
||||
**Why**: [Explanation of why this is the best approach]
|
||||
|
||||
#### Pattern 2: [Another Best Practice]
|
||||
[Similar structure]
|
||||
|
||||
### 8. Troubleshooting Common Issues
|
||||
|
||||
Example-based solutions to common problems:
|
||||
|
||||
#### Issue: [Common Problem]
|
||||
|
||||
**Symptom**: [What the user experiences]
|
||||
|
||||
**Solution**:
|
||||
```typescript
|
||||
// Before: Code that causes the issue
|
||||
const broken = doSomethingWrong();
|
||||
|
||||
// After: Corrected code
|
||||
const fixed = doSomethingRight();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Complete, runnable code** - Every example should be copy-paste ready
|
||||
2. **Real-world scenarios** - Avoid trivial or contrived examples
|
||||
3. **Explain the flow** - Show how modules work together
|
||||
4. **Include output** - Show what users should expect to see
|
||||
5. **Error handling** - Demonstrate proper error handling patterns
|
||||
6. **Comment complex parts** - Help readers understand non-obvious code
|
||||
7. **Version compatibility** - Note if examples are version-specific
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Standards
|
||||
|
||||
All example code should:
|
||||
- Follow project coding standards
|
||||
- Include proper error handling
|
||||
- Use async/await correctly
|
||||
- Show TypeScript types where applicable
|
||||
- Be tested and verified to work
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: [Auto-generated timestamp]
|
||||
**See also**:
|
||||
- [Project README](./README.md) for getting started
|
||||
- [Architecture](./ARCHITECTURE.md) for understanding system design
|
||||
- [Module Documentation](./modules/) for API details
|
||||
33
README.md
33
README.md
@@ -274,6 +274,21 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
|
||||
/workflow:brainstorm:synthesis # Generate consolidated specification
|
||||
```
|
||||
|
||||
**Phase 1.5: Concept Verification** *(Optional Quality Gate)*
|
||||
```bash
|
||||
# Identify and resolve ambiguities in brainstorming artifacts
|
||||
/workflow:concept-clarify
|
||||
|
||||
# OR specify session explicitly
|
||||
/workflow:concept-clarify --session WFS-auth
|
||||
```
|
||||
- Runs after `/workflow:brainstorm:synthesis` and before `/workflow:plan`
|
||||
- Interactive Q&A to clarify underspecified requirements, architecture decisions, or risks
|
||||
- Maximum 5 questions per session with multiple-choice or short-answer format
|
||||
- Updates `synthesis-specification.md` with clarifications incrementally
|
||||
- Ensures conceptual foundation is clear before detailed planning
|
||||
- Generates coverage summary with recommendations to proceed or address outstanding items
|
||||
|
||||
**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
|
||||
|
||||
**🎯 Choose Your Workflow:**
|
||||
@@ -330,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
/workflow:tdd-plan "Implement authentication with test-first development"
|
||||
```
|
||||
|
||||
**Phase 3.5: Action Plan Verification** *(Optional Pre-Execution Check)*
|
||||
```bash
|
||||
# Validate plan consistency and completeness
|
||||
/workflow:action-plan-verify
|
||||
|
||||
# OR specify session explicitly
|
||||
/workflow:action-plan-verify --session WFS-auth
|
||||
```
|
||||
- Runs after `/workflow:plan` or `/workflow:tdd-plan` and before `/workflow:execute`
|
||||
- Read-only analysis of `IMPL_PLAN.md` and task JSON files against `synthesis-specification.md`
|
||||
- Validates requirements coverage, dependency integrity, and synthesis alignment
|
||||
- Identifies inconsistencies, duplications, ambiguities, and underspecified items
|
||||
- Generates detailed verification report with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW)
|
||||
- Recommends whether to PROCEED, PROCEED_WITH_FIXES, or BLOCK_EXECUTION
|
||||
- Provides actionable remediation suggestions for detected issues
|
||||
|
||||
**Phase 4: Execution**
|
||||
```bash
|
||||
# Execute tasks with AI agents
|
||||
@@ -412,6 +443,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
|---|---|
|
||||
| `/workflow:session:*` | Manage development sessions (`start`, `resume`, `list`, `complete`). |
|
||||
| `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
|
||||
| `/workflow:concept-clarify` | **Optional** Quality gate - Identify and resolve ambiguities in brainstorming artifacts before planning (runs after synthesis, before plan). |
|
||||
| `/workflow:ui-design:explore-auto` | **v4.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. |
|
||||
| `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. |
|
||||
| `/workflow:ui-design:style-extract` | **v4.4.0** Extract visual style (colors, typography, spacing) from images/text using Claude-native analysis. |
|
||||
@@ -421,6 +453,7 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
| `/workflow:ui-design:update` | **v4.4.0** Integrate finalized design system into brainstorming artifacts. |
|
||||
| `/workflow:plan` | Create a detailed, executable plan from a description. |
|
||||
| `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
|
||||
| `/workflow:action-plan-verify` | **Optional** Pre-execution check - Validate IMPL_PLAN.md and task.json consistency and completeness (runs after plan, before execute). |
|
||||
| `/workflow:execute` | Execute the current workflow plan autonomously. |
|
||||
| `/workflow:status` | Display the current status of the workflow. |
|
||||
| `/workflow:test-gen [--use-codex] <session>` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. |
|
||||
|
||||
301
README_CN.md
301
README_CN.md
@@ -2,7 +2,7 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](https://github.com/catlog22/Claude-Code-Workflow/releases)
|
||||
[](LICENSE)
|
||||
[]()
|
||||
[](https://github.com/modelcontextprotocol)
|
||||
@@ -15,13 +15,13 @@
|
||||
|
||||
**Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
|
||||
|
||||
> **🎉 最新版本: v4.3.0** - UI 设计工作流 V2 自包含 CSS 架构。详见 [CHANGELOG.md](CHANGELOG.md)。
|
||||
> **🎉 最新版本: v4.4.0** - UI 设计工作流 V3 布局/样式分离架构。详见 [CHANGELOG.md](CHANGELOG.md)。
|
||||
>
|
||||
> **v4.3.0 版本新特性**:
|
||||
> - 🎨 **自包含 CSS**: Agent 从 design-tokens.json 直接生成独立 CSS
|
||||
> - ⚡ **简化工作流**: 移除占位符机制和令牌转换步骤
|
||||
> - 💪 **更强风格差异**: CSS 使用直接令牌值，实现更强视觉区分
|
||||
> - 📉 **代码减少 31%**: 移除 346 行代码，职责更清晰
|
||||
> **v4.4.0 版本新特性**:
|
||||
> - 🏗️ **布局/样式分离**: 新的 `layout-extract` 命令将结构与视觉令牌分离
|
||||
> - 📦 **纯汇编器**: `generate` 命令现在纯粹组合预提取的布局 + 样式
|
||||
> - 🎯 **更好的多样性**: 布局探索生成结构上不同的设计
|
||||
> - ✅ **单一职责**: 每个阶段（样式、布局、汇编）都有明确的目的
|
||||
|
||||
---
|
||||
|
||||
@@ -274,28 +274,65 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
|
||||
/workflow:brainstorm:synthesis # 生成综合规范
|
||||
```
|
||||
|
||||
**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
|
||||
**阶段 1.5：概念验证** *(可选质量关卡)*
|
||||
```bash
|
||||
# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
|
||||
# 识别并解决头脑风暴产物中的歧义
|
||||
/workflow:concept-clarify
|
||||
|
||||
# 或显式指定会话
|
||||
/workflow:concept-clarify --session WFS-auth
|
||||
```
|
||||
- 在 `/workflow:brainstorm:synthesis` 之后、`/workflow:plan` 之前运行
|
||||
- 通过交互式问答澄清未明确的需求、架构决策或风险
|
||||
- 每次会话最多 5 个问题，支持多选或简答格式
|
||||
- 增量更新 `synthesis-specification.md` 以记录澄清内容
|
||||
- 确保概念基础明确后再进行详细规划
|
||||
- 生成覆盖度摘要，建议继续或解决未决项
|
||||
|
||||
**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
|
||||
|
||||
**🎯 选择您的工作流：**
|
||||
|
||||
**场景 1：从想法或概念开始** → 使用 `explore-auto`
|
||||
```bash
|
||||
# 生成多个风格和布局选项来探索不同方向
|
||||
/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
|
||||
# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择
|
||||
```
|
||||
|
||||
# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
|
||||
**场景 2：复制现有设计** → 使用 `imitate-auto`
|
||||
```bash
|
||||
# 快速、高保真复制参考设计
|
||||
/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
|
||||
# 或从 URL 自动截图（需要 Playwright/Chrome DevTools MCP）
|
||||
/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
|
||||
```
|
||||
|
||||
# 与会话集成
|
||||
/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
|
||||
**场景 3：从现有设计系统批量创建** → 使用 `batch-generate`
|
||||
```bash
|
||||
# 已有设计系统？快速生成多个页面
|
||||
/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2
|
||||
```
|
||||
|
||||
# 或者运行单独的设计阶段
|
||||
/workflow:ui-design:extract --images "refs/*.png" --variants 3
|
||||
**高级：手动分步控制** (v4.4.0+)
|
||||
```bash
|
||||
# 1. 提取视觉样式（颜色、排版、间距）
|
||||
/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
|
||||
|
||||
# 2. 整合为可用于生产的设计令牌
|
||||
/workflow:ui-design:consolidate --variants "variant-1,variant-3"
|
||||
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
|
||||
|
||||
# 预览生成的原型
|
||||
# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/compare.html
|
||||
# 选项2：启动本地服务器
|
||||
# 3. 提取布局结构（DOM、CSS 布局规则）
|
||||
/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
|
||||
|
||||
# 4. 组合样式 + 布局 → HTML/CSS 原型
|
||||
/workflow:ui-design:generate --style-variants 1 --layout-variants 2
|
||||
|
||||
# 5. 预览并选择
|
||||
cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
# 访问 http://localhost:8080 获取交互式预览和对比工具
|
||||
# 访问 http://localhost:8080/compare.html 进行并排比较
|
||||
|
||||
# 6. 将选定的设计集成到项目中
|
||||
/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
|
||||
```
|
||||
|
||||
@@ -308,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
/workflow:tdd-plan "使用测试优先开发实现认证"
|
||||
```
|
||||
|
||||
**阶段 3.5：行动计划验证** *(可选执行前检查)*
|
||||
```bash
|
||||
# 验证计划一致性和完整性
|
||||
/workflow:action-plan-verify
|
||||
|
||||
# 或显式指定会话
|
||||
/workflow:action-plan-verify --session WFS-auth
|
||||
```
|
||||
- 在 `/workflow:plan` 或 `/workflow:tdd-plan` 之后、`/workflow:execute` 之前运行
|
||||
- 对 `IMPL_PLAN.md` 和任务 JSON 文件进行只读分析，并与 `synthesis-specification.md` 对照
|
||||
- 验证需求覆盖率、依赖完整性和综合对齐性
|
||||
- 识别不一致、重复、歧义和未充分说明的项目
|
||||
- 生成详细验证报告，包含严重性评级的发现（CRITICAL/HIGH/MEDIUM/LOW）
|
||||
- 建议是否 PROCEED、PROCEED_WITH_FIXES 或 BLOCK_EXECUTION
|
||||
- 提供针对检测到的问题的可操作修复建议
|
||||
|
||||
**阶段 4：执行**
|
||||
```bash
|
||||
# 使用 AI 智能体执行任务
|
||||
@@ -390,14 +443,17 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
|---|---|
|
||||
| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `complete`）。 |
|
||||
| `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
|
||||
| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
|
||||
| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
|
||||
| `/workflow:ui-design:extract` | **v4.2.1** 使用 Claude 原生分析从图像/文本提取设计。单次生成变体。 |
|
||||
| `/workflow:ui-design:consolidate` | **v4.2.1** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
|
||||
| `/workflow:ui-design:generate` | **v4.2.1** 生成矩阵模式（风格×布局组合）的令牌驱动 HTML/CSS 原型。 |
|
||||
| `/workflow:ui-design:update` | **v4.2.1** 将最终确定的设计系统集成到头脑风暴产物中。 |
|
||||
| `/workflow:concept-clarify` | **可选** 质量关卡 - 在规划之前识别并解决头脑风暴产物中的歧义（在综合后、规划前运行）。 |
|
||||
| `/workflow:ui-design:explore-auto` | **v4.4.0** 矩阵探索模式 - 通过布局/样式分离生成多个风格×布局变体。 |
|
||||
| `/workflow:ui-design:imitate-auto` | **v4.4.0** 快速模仿模式 - 通过自动截图、布局提取和汇编实现快速 UI 复制。 |
|
||||
| `/workflow:ui-design:style-extract` | **v4.4.0** 使用 Claude 原生分析从图像/文本提取视觉样式（颜色、排版、间距）。 |
|
||||
| `/workflow:ui-design:layout-extract` | **v4.4.0** 通过设备感知模板提取结构布局（DOM、CSS 布局规则）。 |
|
||||
| `/workflow:ui-design:consolidate` | **v4.4.0** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
|
||||
| `/workflow:ui-design:generate` | **v4.4.0** 纯汇编器 - 组合布局模板 + 设计令牌 → HTML/CSS 原型。 |
|
||||
| `/workflow:ui-design:update` | **v4.4.0** 将最终确定的设计系统集成到头脑风暴产物中。 |
|
||||
| `/workflow:plan` | 从描述创建详细、可执行的计划。 |
|
||||
| `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
|
||||
| `/workflow:action-plan-verify` | **可选** 执行前检查 - 验证 IMPL_PLAN.md 和任务 JSON 的一致性和完整性（在规划后、执行前运行）。 |
|
||||
| `/workflow:execute` | 自主执行当前的工作流计划。 |
|
||||
| `/workflow:status` | 显示工作流的当前状态。 |
|
||||
| `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 |
|
||||
@@ -407,9 +463,80 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
| `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
|
||||
| `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
|
||||
|
||||
### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
|
||||
### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)*
|
||||
|
||||
设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
|
||||
设计工作流系统提供完整的 UI 设计精炼，具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
|
||||
|
||||
#### 📐 架构概述
|
||||
|
||||
UI 工作流遵循**关注点分离**哲学：
|
||||
- **样式（视觉令牌）**：颜色、排版、间距、边框 → `design-tokens.json`
|
||||
- **布局（结构）**：DOM 层次结构、CSS 布局规则 → `layout-templates.json`
|
||||
- **汇编**：纯粹组合样式 + 布局 → HTML/CSS 原型
|
||||
|
||||
**命令分类：**
|
||||
|
||||
| 类别 | 命令 | 目的 |
|
||||
|----------|----------|---------|
|
||||
| **高级编排器** | `explore-auto`, `imitate-auto`, `batch-generate` | 完整工作流（推荐） |
|
||||
| **输入/捕获** | `capture`, `explore-layers` | 截图获取 |
|
||||
| **分析/提取** | `style-extract`, `layout-extract` | 视觉样式和结构布局提取 |
|
||||
| **处理/生成** | `consolidate`, `generate` | 令牌验证和原型汇编 |
|
||||
| **集成** | `update` | 设计系统集成到项目 |
|
||||
|
||||
#### 🧭 决策树：应该使用哪个命令？
|
||||
|
||||
```
|
||||
┌─ 有想法或文本描述？
|
||||
│ └─→ /workflow:ui-design:explore-auto
|
||||
│ （探索多个风格 × 布局选项）
|
||||
│
|
||||
┌─ 想复制现有设计？
|
||||
│ └─→ /workflow:ui-design:imitate-auto
|
||||
│ （高保真单一设计复制）
|
||||
│
|
||||
┌─ 已有设计系统？
|
||||
│ └─→ /workflow:ui-design:batch-generate
|
||||
│ （批量创建多个页面/组件）
|
||||
│
|
||||
└─ 需要细粒度控制？
|
||||
└─→ 按顺序使用单独命令：
|
||||
1. style-extract → 提取颜色、字体、间距
|
||||
2. consolidate → 验证并合并令牌
|
||||
3. layout-extract → 提取 DOM 结构
|
||||
4. generate → 组合为原型
|
||||
5. update → 集成到项目
|
||||
```
|
||||
|
||||
#### 🔄 工作流程图
|
||||
|
||||
**探索工作流**（想法 → 多个设计）：
|
||||
```
|
||||
提示词/图像 → style-extract（探索模式）
|
||||
↓
|
||||
consolidate（N 个变体）
|
||||
↓
|
||||
layout-extract（探索模式）
|
||||
↓
|
||||
generate（N 个样式 × M 个布局）
|
||||
↓
|
||||
update（选定的设计）
|
||||
```
|
||||
|
||||
**模仿工作流**（参考 → 单一设计）：
|
||||
```
|
||||
URL/图像 → capture/explore-layers
|
||||
↓
|
||||
style-extract（模仿模式）
|
||||
↓
|
||||
layout-extract（模仿模式）
|
||||
↓
|
||||
consolidate（单一变体）
|
||||
↓
|
||||
generate（1 个样式 × 1 个布局）
|
||||
↓
|
||||
update（最终设计）
|
||||
```
|
||||
|
||||
#### 核心命令
|
||||
|
||||
@@ -446,27 +573,64 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
|
||||
- **🎯 直接提取**: 跳过变体选择，直接进入实现
|
||||
- **🔧 单一设计聚焦**: 最适合快速复制现有设计
|
||||
|
||||
**`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
|
||||
**`/workflow:ui-design:style-extract`** - 视觉样式提取（v4.4.0）
|
||||
```bash
|
||||
# 纯文本提示
|
||||
/workflow:ui-design:style-extract --prompt "现代极简，深色主题" --mode explore --variants 3
|
||||
|
||||
# 纯图像
|
||||
/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
|
||||
|
||||
# 混合（文本指导图像分析）
|
||||
/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app 风格" --mode imitate
|
||||
|
||||
# 高保真单一风格
|
||||
/workflow:ui-design:style-extract --images "design.png" --mode imitate
|
||||
```
|
||||
- **🎨 仅视觉令牌**：颜色、排版、间距（无布局结构）
|
||||
- **🔄 双模式**：模仿（单一变体）/ 探索（多个变体）
|
||||
- **Claude 原生**：单次分析，无外部工具
|
||||
- **输出**：包含嵌入式 `proposed_tokens` 的 `style-cards.json`
|
||||
|
||||
**`/workflow:ui-design:layout-extract`** - 结构布局提取（v4.4.0）
|
||||
```bash
|
||||
# 探索模式 - 多个布局变体
|
||||
/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
|
||||
|
||||
# 模仿模式 - 单一布局复制
|
||||
/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
|
||||
|
||||
# 使用 MCP 研究（探索模式）
|
||||
/workflow:ui-design:layout-extract --prompt "电商结账" --targets "cart,checkout" --mode explore --variants 2
|
||||
```
|
||||
- **🏗️ 仅结构**：DOM 层次结构、CSS 布局规则（无视觉样式）
|
||||
- **📱 设备感知**：桌面、移动、平板、响应式优化
|
||||
- **🧠 智能体驱动**：使用 ui-design-agent 进行结构分析
|
||||
- **🔍 MCP 研究**：布局模式灵感（探索模式）
|
||||
- **输出**：包含基于令牌的 CSS 的 `layout-templates.json`
|
||||
|
||||
**`/workflow:ui-design:consolidate`** - 验证和合并令牌
|
||||
```bash
|
||||
# 整合选定的风格变体
|
||||
/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
|
||||
/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3"
|
||||
```
|
||||
- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
|
||||
- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
|
||||
- **Claude 合成**：单次生成所有设计系统文件
|
||||
- **功能**：WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
|
||||
- **输出**：`design-tokens.json`、`style-guide.md`、`tailwind.config.js`、`validation-report.json`
|
||||
|
||||
**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
|
||||
**`/workflow:ui-design:generate`** - 纯汇编器（v4.4.0）
|
||||
```bash
|
||||
# 矩阵模式 - 风格×布局组合
|
||||
/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
|
||||
# 组合布局模板 + 设计令牌
|
||||
/workflow:ui-design:generate --style-variants 1 --layout-variants 2
|
||||
|
||||
# 单页面多变体
|
||||
/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
|
||||
# 多个样式与多个布局
|
||||
/workflow:ui-design:generate --style-variants 2 --layout-variants 3
|
||||
```
|
||||
- **🎯 矩阵生成**: 创建所有风格×布局组合
|
||||
- **📊 多页面支持**: 跨页面一致的设计系统
|
||||
- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
|
||||
- **🔍 交互式预览**: `compare.html` 并排比较
|
||||
- **📋 批量选择**: 按风格或布局过滤器快速选择
|
||||
- **📦 纯汇编**：组合预提取的 layout-templates.json + design-tokens.json
|
||||
- **❌ 无设计逻辑**：所有布局/样式决策在之前阶段完成
|
||||
- **✅ 令牌解析**：用实际令牌值替换 var() 占位符
|
||||
- **🎯 矩阵输出**：生成样式 × 布局 × 目标原型
|
||||
- **🔍 交互式预览**：`compare.html` 并排比较
|
||||
|
||||
**`/workflow:ui-design:update`** - 集成设计系统
|
||||
```bash
|
||||
@@ -507,6 +671,61 @@ php -S localhost:8080 # PHP
|
||||
- 动态页面切换
|
||||
- 实时响应式测试
|
||||
|
||||
#### 📦 输出结构
|
||||
|
||||
所有 UI 工作流输出都组织在会话内的 `.design` 目录中：
|
||||
|
||||
```
|
||||
.workflow/WFS-<session-id>/.design/
|
||||
├── design-run-YYYYMMDD-HHMMSS/ # 带时间戳的设计运行
|
||||
│ ├── screenshots/ # 📸 捕获的截图
|
||||
│ │ ├── home.png
|
||||
│ │ └── dashboard.png
|
||||
│ │
|
||||
│ ├── style-extraction/ # 🎨 样式分析阶段
|
||||
│ │ ├── style-cards.json # AI 提议的风格变体
|
||||
│ │ └── design-space-analysis.json # （探索模式）多样性分析
|
||||
│ │
|
||||
│ ├── layout-extraction/ # 🏗️ 布局分析阶段
|
||||
│ │ └── layout-templates.json # 包含基于令牌的 CSS 的结构模板
|
||||
│ │
|
||||
│ ├── style-consolidation/ # ✅ 生产设计系统
|
||||
│ │ ├── style-1/
|
||||
│ │ │ ├── design-tokens.json # W3C 设计令牌
|
||||
│ │ │ ├── style-guide.md # 视觉设计文档
|
||||
│ │ │ ├── tailwind.config.js # Tailwind 配置
|
||||
│ │ │ └── validation-report.json # WCAG AA 验证结果
|
||||
│ │ └── style-2/
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ └── prototypes/ # 🎯 最终 HTML/CSS 原型
|
||||
│ ├── home-style-1-layout-1.html # 矩阵生成的原型
|
||||
│ ├── home-style-1-layout-1.css
|
||||
│ ├── home-style-1-layout-2.html
|
||||
│ ├── dashboard-style-2-layout-1.html
|
||||
│ ├── index.html # 主导航页面
|
||||
│ └── compare.html # 并排比较工具
|
||||
│
|
||||
└── latest -> design-run-YYYYMMDD-HHMMSS # 指向最新运行的符号链接
|
||||
```
|
||||
|
||||
**关键文件：**
|
||||
|
||||
| 文件 | 目的 | 生成命令 |
|
||||
|------|---------|--------------|
|
||||
| `style-cards.json` | AI 提议的视觉样式及嵌入的令牌 | `style-extract` |
|
||||
| `layout-templates.json` | 包含基于令牌的 CSS 的结构模板 | `layout-extract` |
|
||||
| `design-tokens.json` | 可用于生产的 W3C 设计令牌 | `consolidate` |
|
||||
| `style-guide.md` | 视觉设计系统文档 | `consolidate` |
|
||||
| `compare.html` | 交互式原型比较矩阵 | `generate` |
|
||||
|
||||
**最佳实践：**
|
||||
|
||||
1. **会话管理**：会话内的所有运行累积在 `.design/design-run-*/`
|
||||
2. **版本控制**：每次运行都有时间戳，便于回滚
|
||||
3. **集成**：使用 `update` 命令将最终令牌链接到项目产物
|
||||
4. **清理**：旧运行可以安全删除；`latest` 符号链接始终指向最新的
|
||||
|
||||
---
|
||||
|
||||
### **任务与内存命令**
|
||||
|
||||
Reference in New Issue
Block a user