mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
Enhance skill generator documentation and templates
- Updated Phase 1 and Phase 2 documentation to include next phase links and data flow details. - Expanded Phase 5 documentation to include comprehensive validation and README generation steps, along with validation report structure. - Added purpose and usage context sections to various action and script templates (e.g., autonomous-action, llm-action, script-bash). - Improved commands management by simplifying the command scanning logic and enabling/disabling commands through renaming files. - Enhanced dashboard command manager to format group names and display nested groups with appropriate icons and colors. - Updated LiteLLM executor to allow model overrides during execution. - Added action reference guide and template reference sections to the skill-tuning SKILL.md for better navigation and understanding.
This commit is contained in:
catlog22
@@ -1,687 +0,0 @@
|
||||
---
|
||||
name: code-map-memory
|
||||
description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
|
||||
argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Code Flow Mapping Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
|
||||
|
||||
**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
|
||||
|
||||
**Execution Paths**:
|
||||
- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
|
||||
- **Phase 3 Always Executes**: SKILL index is always generated or updated
|
||||
|
||||
**Agent Responsibility** (cli-explore-agent):
|
||||
- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
|
||||
- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
|
||||
- NO file writing - analysis only
|
||||
|
||||
**Orchestrator Responsibility**:
|
||||
- Provides feature keyword and analysis scope to agent
|
||||
- Transforms agent's JSON into Mermaid-enriched markdown documentation
|
||||
- Writes all files (5 docs + metadata.json + SKILL.md)
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
|
||||
3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
|
||||
4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
|
||||
5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
6. **No User Prompts**: Never ask user questions or wait for input between phases
|
||||
7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Parse Feature Keyword & Check Existing
|
||||
|
||||
**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
|
||||
|
||||
**Step 1: Parse Feature Keyword**
|
||||
```bash
|
||||
# Get feature keyword from argument
|
||||
FEATURE_KEYWORD="$1"
|
||||
|
||||
# Normalize: lowercase, spaces to hyphens
|
||||
normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
|
||||
|
||||
# Example: "User Authentication" → "user-authentication"
|
||||
# Example: "支付处理" → "支付处理" (keep non-ASCII)
|
||||
```
|
||||
|
||||
**Step 2: Set Tool Preference**
|
||||
```bash
|
||||
# Default to gemini unless --tool specified
|
||||
TOOL="${tool_flag:-gemini}"
|
||||
```
|
||||
|
||||
**Step 3: Check Existing Codemap**
|
||||
```bash
|
||||
# Define codemap directory
|
||||
CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
|
||||
|
||||
# Check if codemap exists
|
||||
bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
|
||||
|
||||
# Count existing files
|
||||
bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Step 4: Skip Decision**
|
||||
```javascript
|
||||
if (existing_files > 0 && !regenerate_flag) {
|
||||
SKIP_GENERATION = true
|
||||
message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
bash(rm -rf "$CODEMAP_DIR")
|
||||
SKIP_GENERATION = false
|
||||
message = "Regenerating codemap from scratch."
|
||||
} else {
|
||||
SKIP_GENERATION = false
|
||||
message = "No existing codemap found, generating new code flow analysis."
|
||||
}
|
||||
```
|
||||
|
||||
**Output Variables**:
|
||||
- `FEATURE_KEYWORD`: Original feature keyword
|
||||
- `normalized_feature`: Normalized feature name for directory
|
||||
- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
|
||||
- `TOOL`: CLI tool to use (gemini or qwen)
|
||||
- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
|
||||
|
||||
**TodoWrite**:
|
||||
- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
|
||||
- If not skipping: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Code Flow Analysis & Documentation Generation
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
|
||||
|
||||
**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2a: cli-explore-agent Analysis
|
||||
|
||||
**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
|
||||
|
||||
**Agent Task Specification**:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "cli-explore-agent",
|
||||
description: "Analyze code flow: {FEATURE_KEYWORD}",
|
||||
prompt: "
|
||||
Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
|
||||
|
||||
**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
|
||||
|
||||
**Analysis Objectives**:
|
||||
1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
|
||||
2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
|
||||
3. **Data Transformations**: Map data structure changes and transformation stages
|
||||
4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
|
||||
5. **Design Patterns**: Discover architectural patterns and extract design intent
|
||||
|
||||
**Scope**:
|
||||
- Feature: {FEATURE_KEYWORD}
|
||||
- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
|
||||
- File Discovery: MCP Code Index (preferred) + rg fallback
|
||||
- Target: 5-15 most relevant files
|
||||
|
||||
**MANDATORY FIRST STEP**:
|
||||
Read: ~/.claude/workflows/cli-templates/schemas/codemap-json-schema.json
|
||||
|
||||
**Output**: Return JSON following schema exactly. NO FILE WRITING - return JSON analysis only.
|
||||
|
||||
**Critical Requirements**:
|
||||
- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
|
||||
- Focus exclusively on {FEATURE_KEYWORD} feature flow
|
||||
- Include file:line references for ALL findings
|
||||
- Extract design intent from code structure and comments
|
||||
- NO FILE WRITING - return JSON analysis only
|
||||
- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
|
||||
|
||||
---
|
||||
|
||||
#### Phase 2b: Orchestrator Documentation Generation
|
||||
|
||||
**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
|
||||
|
||||
**Input**: Agent's JSON analysis result
|
||||
|
||||
**Process**:
|
||||
|
||||
1. **Parse Agent Analysis**:
|
||||
```javascript
|
||||
const analysis = JSON.parse(agentResult)
|
||||
const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
|
||||
```
|
||||
|
||||
2. **Generate Mermaid Diagrams from Structured Data**:
|
||||
|
||||
**a) architecture-flow.md** (~3K tokens):
|
||||
```javascript
|
||||
// Convert architecture.modules + architecture.interactions → Mermaid graph TD
|
||||
const architectureMermaid = `
|
||||
graph TD
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
${architecture.interactions.map(i => ` ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/architecture-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: architecture
|
||||
detail: high-level module interactions
|
||||
---
|
||||
# Architecture Flow: ${feature}
|
||||
|
||||
## Overview
|
||||
${architecture.overview}
|
||||
|
||||
## Module Architecture
|
||||
${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
|
||||
|
||||
## Flow Diagram
|
||||
\`\`\`mermaid
|
||||
${architectureMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Key Interactions
|
||||
${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
|
||||
|
||||
## Entry Points
|
||||
${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**b) function-calls.md** (~5K tokens):
|
||||
```javascript
|
||||
// Convert function_calls.sequences → Mermaid sequenceDiagram
|
||||
const sequenceMermaid = `
|
||||
sequenceDiagram
|
||||
${function_calls.sequences.map(s => ` ${s.from}->>${s.to}: ${s.method}`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/function-calls.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: function
|
||||
detail: function-level call sequences
|
||||
---
|
||||
# Function Call Chains: ${feature}
|
||||
|
||||
## Call Sequence Diagram
|
||||
\`\`\`mermaid
|
||||
${sequenceMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Detailed Call Chains
|
||||
${function_calls.call_chains.map(chain => `
|
||||
### Chain ${chain.chain_id}: ${chain.description}
|
||||
${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n - Calls: ${fn.calls.join(', ')}`).join('\n')}
|
||||
`).join('\n')}
|
||||
|
||||
## Parameters & Returns
|
||||
${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**c) data-flow.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert data_flow.transformations → Mermaid flowchart LR
|
||||
const dataFlowMermaid = `
|
||||
flowchart LR
|
||||
${data_flow.transformations.map((t, i) => ` Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/data-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: data
|
||||
detail: data structure transformations
|
||||
---
|
||||
# Data Flow: ${feature}
|
||||
|
||||
## Data Transformation Diagram
|
||||
\`\`\`mermaid
|
||||
${dataFlowMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Data Structures
|
||||
${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
|
||||
|
||||
## Transformations
|
||||
${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**d) conditional-paths.md** (~4K tokens):
|
||||
```javascript
|
||||
// Convert conditional_logic.branches → Mermaid flowchart TD
|
||||
const conditionalMermaid = `
|
||||
flowchart TD
|
||||
Start[Entry Point]
|
||||
${conditional_logic.branches.map((b, i) => `
|
||||
Start --> Check${i}{${b.condition}}
|
||||
Check${i} -->|Yes| Path${i}A[${b.true_path}]
|
||||
Check${i} -->|No| Path${i}B[${b.false_path}]
|
||||
`).join('\n')}
|
||||
`
|
||||
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/conditional-paths.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: conditional
|
||||
detail: decision trees and error paths
|
||||
---
|
||||
# Conditional Paths: ${feature}
|
||||
|
||||
## Decision Tree
|
||||
\`\`\`mermaid
|
||||
${conditionalMermaid}
|
||||
\`\`\`
|
||||
|
||||
## Branch Conditions
|
||||
${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n - True: ${b.true_path}\n - False: ${b.false_path}`).join('\n')}
|
||||
|
||||
## Error Handling
|
||||
${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**e) complete-flow.md** (~8K tokens):
|
||||
```javascript
|
||||
// Integrate all Mermaid diagrams
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/complete-flow.md`,
|
||||
content: `---
|
||||
feature: ${feature}
|
||||
level: complete
|
||||
detail: integrated multi-level view
|
||||
---
|
||||
# Complete Flow: ${feature}
|
||||
|
||||
## Integrated Flow Diagram
|
||||
\`\`\`mermaid
|
||||
graph TB
|
||||
subgraph Architecture
|
||||
${architecture.modules.map(m => ` ${m.name}[${m.name}]`).join('\n')}
|
||||
end
|
||||
|
||||
subgraph "Function Calls"
|
||||
${function_calls.call_chains[0]?.sequence.map(fn => ` ${fn.function}`).join('\n') || ''}
|
||||
end
|
||||
|
||||
subgraph "Data Flow"
|
||||
${data_flow.structures.map(s => ` ${s.name}[${s.name}]`).join('\n')}
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
## Complete Trace
|
||||
[Comprehensive end-to-end documentation combining all analysis layers]
|
||||
|
||||
## Design Patterns Identified
|
||||
${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
|
||||
|
||||
## Recommendations
|
||||
${analysis.recommendations.map(r => `- ${r}`).join('\n')}
|
||||
|
||||
## Cross-References
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module structure
|
||||
- [Function Calls](./function-calls.md) - Detailed call chains
|
||||
- [Data Flow](./data-flow.md) - Data transformation stages
|
||||
- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
3. **Write metadata.json**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `${CODEMAP_DIR}/metadata.json`,
|
||||
content: JSON.stringify({
|
||||
feature: feature,
|
||||
normalized_name: normalized_feature,
|
||||
generated_at: new Date().toISOString(),
|
||||
tool_used: analysis.analysis_metadata.tool_used,
|
||||
files_analyzed: files_analyzed.map(f => f.file),
|
||||
analysis_summary: {
|
||||
total_files: files_analyzed.length,
|
||||
modules_traced: architecture.modules.length,
|
||||
functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
|
||||
patterns_discovered: design_patterns.length
|
||||
}
|
||||
}, null, 2)
|
||||
})
|
||||
```
|
||||
|
||||
4. **Report Phase 2 Completion**:
|
||||
```
|
||||
Phase 2 Complete: Code flow analysis and documentation generated
|
||||
|
||||
- Agent Analysis: cli-explore-agent with {TOOL}
|
||||
- Files Analyzed: {count}
|
||||
- Documentation Generated: 5 markdown files + metadata.json
|
||||
- Location: {CODEMAP_DIR}
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- cli-explore-agent task completed successfully with JSON result
|
||||
- 5 documentation files written with valid Mermaid diagrams
|
||||
- metadata.json written with analysis summary
|
||||
- All files properly formatted and cross-referenced
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Generate SKILL.md Index
|
||||
|
||||
**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
|
||||
|
||||
**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Generated Files**:
|
||||
```bash
|
||||
bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
|
||||
```
|
||||
|
||||
2. **Read metadata.json**:
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/metadata.json)
|
||||
// Extract: feature, normalized_name, files_analyzed, analysis_summary
|
||||
```
|
||||
|
||||
3. **Read File Headers** (optional, first 30 lines):
|
||||
```javascript
|
||||
Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
|
||||
Read({CODEMAP_DIR}/function-calls.md, limit: 30)
|
||||
// Extract overview and diagram counts
|
||||
```
|
||||
|
||||
4. **Generate SKILL.md Index**:
|
||||
|
||||
Template structure:
|
||||
```yaml
|
||||
---
|
||||
name: codemap-{normalized_feature}
|
||||
description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
|
||||
version: 1.0.0
|
||||
generated_at: {ISO_TIMESTAMP}
|
||||
---
|
||||
# Code Flow Map: {FEATURE_KEYWORD}
|
||||
|
||||
## Feature: `{FEATURE_KEYWORD}`
|
||||
|
||||
**Analysis Date**: {DATE}
|
||||
**Tool Used**: {TOOL}
|
||||
**Files Analyzed**: {COUNT}
|
||||
|
||||
## Progressive Loading
|
||||
|
||||
### Level 0: Quick Overview (~2K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - High-level module interactions
|
||||
|
||||
### Level 1: Core Flows (~10K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md) - Module architecture
|
||||
- [Function Calls](./function-calls.md) - Function call chains
|
||||
|
||||
### Level 2: Complete Analysis (~20K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md) - Data transformations
|
||||
|
||||
### Level 3: Deep Dive (~30K tokens)
|
||||
- [Architecture Flow](./architecture-flow.md)
|
||||
- [Function Calls](./function-calls.md)
|
||||
- [Data Flow](./data-flow.md)
|
||||
- [Conditional Paths](./conditional-paths.md) - Branches and error handling
|
||||
- [Complete Flow](./complete-flow.md) - Integrated comprehensive view
|
||||
|
||||
## Usage
|
||||
|
||||
Load this SKILL package when:
|
||||
- Analyzing {FEATURE_KEYWORD} implementation
|
||||
- Tracing execution flow for debugging
|
||||
- Understanding code dependencies
|
||||
- Planning refactoring or enhancements
|
||||
|
||||
## Analysis Summary
|
||||
|
||||
- **Modules Traced**: {modules_traced}
|
||||
- **Functions Traced**: {functions_traced}
|
||||
- **Files Analyzed**: {total_files}
|
||||
|
||||
## Mermaid Diagrams Included
|
||||
|
||||
- Architecture flow diagram (graph TD)
|
||||
- Function call sequence diagram (sequenceDiagram)
|
||||
- Data transformation flowchart (flowchart LR)
|
||||
- Conditional decision tree (flowchart TD)
|
||||
- Complete integrated diagram (graph TB)
|
||||
```
|
||||
|
||||
5. **Write SKILL.md**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `{CODEMAP_DIR}/SKILL.md`,
|
||||
content: generatedIndexMarkdown
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md index written
|
||||
- All documentation files verified
|
||||
- Progressive loading levels (0-3) properly structured
|
||||
- Mermaid diagram references included
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
**Final Report**:
|
||||
```
|
||||
Code Flow Mapping Complete
|
||||
|
||||
Feature: {FEATURE_KEYWORD}
|
||||
Location: .claude/skills/codemap-{normalized_feature}/
|
||||
|
||||
Files Generated:
|
||||
- SKILL.md (index)
|
||||
- architecture-flow.md (with Mermaid diagram)
|
||||
- function-calls.md (with Mermaid sequence diagram)
|
||||
- data-flow.md (with Mermaid flowchart)
|
||||
- conditional-paths.md (with Mermaid decision tree)
|
||||
- complete-flow.md (with integrated Mermaid diagram)
|
||||
- metadata.json
|
||||
|
||||
Analysis:
|
||||
- Files analyzed: {count}
|
||||
- Modules traced: {count}
|
||||
- Functions traced: {count}
|
||||
|
||||
Usage: Skill(command: "codemap-{normalized_feature}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
**Initialization** (Before Phase 1):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
|
||||
]})
|
||||
```
|
||||
|
||||
**Full Path** (SKIP_GENERATION = false):
|
||||
```javascript
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", ...}
|
||||
]})
|
||||
|
||||
// After Phase 2
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
|
||||
// After Phase 3
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
**Skip Path** (SKIP_GENERATION = true):
|
||||
```javascript
|
||||
// After Phase 1 (skip Phase 2)
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse feature keyword and check existing", "status": "completed", ...},
|
||||
{"content": "Agent analyzes code flow and generates files", "status": "completed", ...}, // Skipped
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
**Full Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
|
||||
```
|
||||
|
||||
**Skip Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase 1 Errors**:
|
||||
- Empty feature keyword: Report error, ask user to provide feature description
|
||||
- Invalid characters: Normalize and continue
|
||||
|
||||
**Phase 2 Errors (Agent)**:
|
||||
- Agent task fails: Retry once, report if fails again
|
||||
- No files discovered: Warn user, ask for more specific feature keyword
|
||||
- CLI failures: Agent handles internally with retries
|
||||
- Invalid Mermaid syntax: Agent validates before writing
|
||||
|
||||
**Phase 3 Errors**:
|
||||
- Write failures: Report which files failed
|
||||
- Missing files: Note in SKILL.md, suggest regeneration
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **"feature-keyword"**: Feature or flow to analyze (required)
|
||||
- Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
|
||||
- Can be English, Chinese, or mixed
|
||||
- Spaces and underscores normalized to hyphens
|
||||
- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
|
||||
- **--tool**: CLI tool for analysis (default: gemini)
|
||||
- `gemini`: Comprehensive flow analysis with gemini-2.5-pro
|
||||
- `qwen`: Alternative with coder-model
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Generated File Structure** (for all examples):
|
||||
```
|
||||
.claude/skills/codemap-{feature}/
|
||||
├── SKILL.md # Index (Phase 3)
|
||||
├── architecture-flow.md # Agent (Phase 2) - High-level flow
|
||||
├── function-calls.md # Agent (Phase 2) - Function chains
|
||||
├── data-flow.md # Agent (Phase 2) - Data transformations
|
||||
├── conditional-paths.md # Agent (Phase 2) - Branches & errors
|
||||
├── complete-flow.md # Agent (Phase 2) - Integrated view
|
||||
└── metadata.json # Agent (Phase 2)
|
||||
```
|
||||
|
||||
### Example 1: User Authentication Flow
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "user authentication"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Normalizes to "user-authentication", checks existing codemap
|
||||
2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
|
||||
3. Phase 3: Generates SKILL.md index with progressive loading
|
||||
|
||||
**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
|
||||
|
||||
|
||||
### Example 3: Regenerate with Qwen
|
||||
|
||||
```bash
|
||||
/memory:code-map-memory "payment processing" --regenerate --tool qwen
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Deletes existing codemap due to --regenerate
|
||||
2. Phase 2: Agent uses qwen with coder-model for fresh analysis
|
||||
3. Phase 3: Generates updated SKILL.md
|
||||
|
||||
---
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
code-map-memory (orchestrator)
|
||||
├─ Phase 1: Parse & Check (bash commands, skip decision)
|
||||
├─ Phase 2: Code Analysis & Documentation (skippable)
|
||||
│ ├─ Phase 2a: cli-explore-agent Analysis
|
||||
│ │ └─ Deep Scan: Bash structural + Gemini semantic → JSON
|
||||
│ └─ Phase 2b: Orchestrator Documentation
|
||||
│ └─ Transform JSON → 5 Mermaid markdown files + metadata.json
|
||||
└─ Phase 3: Write SKILL.md (index generation, always runs)
|
||||
|
||||
Output: .claude/skills/codemap-{feature}/
|
||||
```
|
||||
@@ -1,615 +0,0 @@
|
||||
---
|
||||
name: docs
|
||||
description: Plan documentation workflow with dynamic grouping (≤10 docs/task), generates IMPL tasks for parallel module trees, README, ARCHITECTURE, and HTTP API docs
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]"
|
||||
---
|
||||
|
||||
# Documentation Workflow (/memory:docs)
|
||||
|
||||
## Overview
|
||||
Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
|
||||
|
||||
**Execution Strategy**:
|
||||
- **Dynamic Task Grouping**: Level 1 tasks grouped by top-level directories with document count limit
|
||||
- **Primary constraint**: Each task generates ≤10 documents (API.md + README.md count)
|
||||
- **Optimization goal**: Prefer grouping 2 top-level directories per task for context sharing
|
||||
- **Conflict resolution**: If 2 dirs exceed 10 docs, reduce to 1 dir/task; if 1 dir exceeds 10 docs, split by subdirectories
|
||||
- **Context benefit**: Same-task directories analyzed together via single Gemini call
|
||||
- **Parallel Execution**: Multiple Level 1 tasks execute concurrently for faster completion
|
||||
- **Pre-computed Analysis**: Phase 2 performs unified analysis once, stored in `.process/` for reuse
|
||||
- **Efficient Data Loading**: All existing docs loaded once in Phase 2, shared across tasks
|
||||
|
||||
**Path Mirroring**: Documentation structure mirrors source code under `.workflow/docs/{project_name}/`
|
||||
- Example: `my_app/src/core/` → `.workflow/docs/my_app/src/core/API.md`
|
||||
|
||||
**Two Execution Modes**:
|
||||
- **Default (Agent Mode)**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs
|
||||
- **--cli-execute (CLI Mode)**: CLI generates docs in `implementation_approach` (MODE=write), agent executes CLI commands
|
||||
|
||||
## Path Mirroring Strategy
|
||||
|
||||
**Principle**: Documentation structure **mirrors** source code structure under project-specific directory.
|
||||
|
||||
| Source Path | Project Name | Documentation Path |
|
||||
|------------|--------------|-------------------|
|
||||
| `my_app/src/core/` | `my_app` | `.workflow/docs/my_app/src/core/API.md` |
|
||||
| `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` |
|
||||
| `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` |
|
||||
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]
|
||||
```
|
||||
|
||||
- **path**: Source directory to analyze (default: current directory)
|
||||
- Specifies the source code directory to be documented
|
||||
- Documentation is generated in a separate `.workflow/docs/{project_name}/` directory at the workspace root, **not** within the source `path` itself
|
||||
- The source path's structure is mirrored within the project-specific documentation folder
|
||||
- Example: analyzing `src/modules` produces documentation at `.workflow/docs/{project_name}/src/modules/`
|
||||
- **--mode**: Documentation generation mode (default: full)
|
||||
- `full`: Complete documentation (modules + README + ARCHITECTURE + EXAMPLES + HTTP API)
|
||||
- `partial`: Module documentation only (API.md + README.md)
|
||||
- **--tool**: CLI tool selection (default: gemini)
|
||||
- `gemini`: Comprehensive documentation, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design focus
|
||||
- `codex`: Implementation validation, code quality
|
||||
- **--cli-execute**: Enable CLI-based documentation generation (optional)
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
```bash
|
||||
# Get target path, project name, and root
|
||||
bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Create docs session (type: docs)
|
||||
SlashCommand(command="/workflow:session:start --type docs --new \"{project_name}-docs-{timestamp}\"")
|
||||
// Parse output to get sessionId
|
||||
```
|
||||
|
||||
```bash
|
||||
# Update workflow-session.json with docs-specific fields
|
||||
bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json)
|
||||
```
|
||||
|
||||
### Phase 2: Analyze Structure
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack.
|
||||
|
||||
**Commands** (collect data with simple bash):
|
||||
|
||||
```bash
|
||||
# 1. Run folder analysis
|
||||
bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}')
|
||||
|
||||
# 2. Get top-level directories (first 2 path levels)
|
||||
bash(ccw tool exec get_modules_by_depth '{}' | ccw tool exec classify_folders '{}' | awk -F'|' '{print $1}' | sed 's|^\./||' | awk -F'/' '{if(NF>=2) print $1"/"$2; else if(NF==1) print $1}' | sort -u)
|
||||
|
||||
# 3. Find existing docs (if directory exists)
|
||||
bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null; fi)
|
||||
|
||||
# 4. Read existing docs content (if files exist)
|
||||
bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi)
|
||||
```
|
||||
|
||||
**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/doc-planning-data.json` with structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"generated_at": "2025-11-03T16:57:30.469669",
|
||||
"project_name": "project_name",
|
||||
"project_root": "/path/to/project"
|
||||
},
|
||||
"folder_analysis": [
|
||||
{"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2}
|
||||
],
|
||||
"top_level_dirs": ["src/modules", "lib/core"],
|
||||
"existing_docs": {
|
||||
"file_list": [".workflow/docs/project/src/core/API.md"],
|
||||
"content": "... existing docs content ..."
|
||||
},
|
||||
"unified_analysis": [],
|
||||
"statistics": {
|
||||
"total": 15,
|
||||
"code": 8,
|
||||
"navigation": 7,
|
||||
"top_level": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Then** use **Edit tool** to update `workflow-session.json` adding analysis field.
|
||||
|
||||
**Output**: Single `doc-planning-data.json` with all analysis data (no temp files or Python scripts).
|
||||
|
||||
**Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories.
|
||||
|
||||
### Phase 3: Detect Update Mode
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# Count existing docs from doc-planning-data.json
|
||||
bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq '.existing_docs.file_list | length')
|
||||
```
|
||||
|
||||
**Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`:
|
||||
- Add `"update_mode": "update"` if count > 0, else `"create"`
|
||||
- Add `"existing_docs": <count>`
|
||||
|
||||
### Phase 4: Decompose Tasks
|
||||
|
||||
**Task Hierarchy** (Dynamic based on document count):
|
||||
|
||||
```
|
||||
Small Projects (total ≤10 docs):
|
||||
Level 1: IMPL-001 (all directories in single task, shared context)
|
||||
Level 2: IMPL-002 (README, full mode only)
|
||||
Level 3: IMPL-003 (ARCHITECTURE+EXAMPLES), IMPL-004 (HTTP API, optional)
|
||||
|
||||
Medium Projects (Example: 7 top-level dirs, 18 total docs):
|
||||
Step 1: Count docs per top-level dir
|
||||
├─ dir1: 3 docs, dir2: 4 docs → Group 1 (7 docs)
|
||||
├─ dir3: 5 docs, dir4: 3 docs → Group 2 (8 docs)
|
||||
├─ dir5: 2 docs → Group 3 (2 docs, can add more)
|
||||
|
||||
Step 2: Create tasks with ≤10 docs constraint
|
||||
Level 1: IMPL-001 to IMPL-003 (parallel groups)
|
||||
├─ IMPL-001: Group 1 (dir1 + dir2, 7 docs, shared context)
|
||||
├─ IMPL-002: Group 2 (dir3 + dir4, 8 docs, shared context)
|
||||
└─ IMPL-003: Group 3 (remaining dirs, ≤10 docs)
|
||||
Level 2: IMPL-004 (README, depends on Level 1, full mode only)
|
||||
Level 3: IMPL-005 (ARCHITECTURE+EXAMPLES), IMPL-006 (HTTP API, optional)
|
||||
|
||||
Large Projects (single dir >10 docs):
|
||||
Step 1: Detect oversized directory
|
||||
└─ src/modules/: 15 subdirs → 30 docs (exceeds limit)
|
||||
|
||||
Step 2: Split by subdirectories
|
||||
Level 1: IMPL-001 to IMPL-003 (split oversized dir)
|
||||
├─ IMPL-001: src/modules/ subdirs 1-5 (10 docs)
|
||||
├─ IMPL-002: src/modules/ subdirs 6-10 (10 docs)
|
||||
└─ IMPL-003: src/modules/ subdirs 11-15 (10 docs)
|
||||
```
|
||||
|
||||
**Grouping Algorithm**:
|
||||
1. Count total docs for each top-level directory
|
||||
2. Try grouping 2 directories (optimization for context sharing)
|
||||
3. If group exceeds 10 docs, split to 1 dir/task
|
||||
4. If single dir exceeds 10 docs, split by subdirectories
|
||||
5. Create parallel Level 1 tasks with ≤10 docs each
|
||||
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Get top-level directories from doc-planning-data.json
|
||||
bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq -r '.top_level_dirs[]')
|
||||
|
||||
# 2. Get mode from workflow-session.json
|
||||
bash(cat .workflow/active/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
|
||||
|
||||
# 3. Check for HTTP API
|
||||
bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo "NO_API")
|
||||
```
|
||||
|
||||
**Data Processing**:
|
||||
1. Count documents for each top-level directory (from folder_analysis):
|
||||
- Code folders: 2 docs each (API.md + README.md)
|
||||
- Navigation folders: 1 doc each (README.md only)
|
||||
2. Apply grouping algorithm with ≤10 docs constraint:
|
||||
- Try grouping 2 directories, calculate total docs
|
||||
- If total ≤10 docs: create group
|
||||
- If total >10 docs: split to 1 dir/group or subdivide
|
||||
- If single dir >10 docs: split by subdirectories
|
||||
3. Use **Edit tool** to update `doc-planning-data.json` adding groups field:
|
||||
```json
|
||||
"groups": {
|
||||
"count": 3,
|
||||
"assignments": [
|
||||
{"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 5},
|
||||
{"group_id": "002", "directories": ["lib/core"], "doc_count": 6},
|
||||
{"group_id": "003", "directories": ["lib/helpers"], "doc_count": 3}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Task ID Calculation**:
|
||||
```bash
|
||||
group_count=$(jq '.groups.count' .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json)
|
||||
readme_id=$((group_count + 1)) # Next ID after groups
|
||||
arch_id=$((group_count + 2))
|
||||
api_id=$((group_count + 3))
|
||||
```
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
**CLI Strategy**:
|
||||
|
||||
| Mode | cli_execute | Placement | CLI MODE | Approval Flag | Agent Role |
|
||||
|------|-------------|-----------|----------|---------------|------------|
|
||||
| **Agent** | false | pre_analysis | analysis | (none) | Generate docs in implementation_approach |
|
||||
| **CLI** | true | implementation_approach | write | --mode write | Execute CLI commands, validate output |
|
||||
|
||||
**Command Patterns**:
|
||||
- Gemini/Qwen: `ccw cli -p "..." --tool gemini --mode analysis --cd dir`
|
||||
- CLI Mode: `ccw cli -p "..." --tool gemini --mode write --cd dir`
|
||||
- Codex: `ccw cli -p "..." --tool codex --mode write --cd dir`
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
|
||||
2. Read group assignments from doc-planning-data.json
|
||||
3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group)
|
||||
4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API)
|
||||
|
||||
## Task Templates
|
||||
|
||||
### Level 1: Module Trees Group Task (Unified)
|
||||
|
||||
**Execution Model**: Each task processes assigned directory group (max 2 directories) using pre-analyzed data from Phase 2.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${group_number}",
|
||||
"title": "Document Module Trees Group ${group_number}",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs-tree-group",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_execute": false,
|
||||
"group_number": "${group_number}",
|
||||
"total_groups": "${total_groups}"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Process directories from group ${group_number} in doc-planning-data.json",
|
||||
"Generate docs to .workflow/docs/${project_name}/ (mirrored structure)",
|
||||
"Code folders: API.md + README.md; Navigation folders: README.md only",
|
||||
"Use pre-analyzed data from Phase 2 (no redundant analysis)"
|
||||
],
|
||||
"focus_paths": ["${group_dirs_from_json}"],
|
||||
"precomputed_data": {
|
||||
"phase2_analysis": "${session_dir}/.process/doc-planning-data.json"
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_precomputed_data",
|
||||
"action": "Load Phase 2 analysis and extract group directories",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/doc-planning-data.json)",
|
||||
"bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/doc-planning-data.json)"
|
||||
],
|
||||
"output_to": "phase2_context",
|
||||
"note": "Single JSON file contains all Phase 2 analysis results"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate documentation for assigned directory group",
|
||||
"description": "Process directories in Group ${group_number} using pre-analyzed data",
|
||||
"modification_points": [
|
||||
"Read group directories from [phase2_context].groups.assignments[${group_number}].directories",
|
||||
"For each directory: parse folder types from folder_analysis, parse structure from unified_analysis",
|
||||
"Map source_path to .workflow/docs/${project_name}/{path}",
|
||||
"Generate API.md for code folders, README.md for all folders",
|
||||
"Preserve user modifications from [phase2_context].existing_docs.content"
|
||||
],
|
||||
"logic_flow": [
|
||||
"phase2 = parse([phase2_context])",
|
||||
"dirs = phase2.groups.assignments[${group_number}].directories",
|
||||
"for dir in dirs:",
|
||||
" folder_info = find(dir, phase2.folder_analysis)",
|
||||
" outline = find(dir, phase2.unified_analysis)",
|
||||
" if folder_info.type == 'code': generate API.md + README.md",
|
||||
" elif folder_info.type == 'navigation': generate README.md only",
|
||||
" write to .workflow/docs/${project_name}/{dir}/"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "group_module_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/*/API.md",
|
||||
".workflow/docs/${project_name}/*/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CLI Execute Mode Note**: When `cli_execute=true`, add Step 2 in `implementation_approach`:
|
||||
```json
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Batch generate documentation via CLI",
|
||||
"command": "ccw cli -p 'PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure' --tool gemini --mode write --cd ${dirs_from_group}",
|
||||
"depends_on": [1],
|
||||
"output": "generated_docs"
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Project README Task
|
||||
|
||||
**Task ID**: `IMPL-${readme_id}` (where `readme_id = group_count + 1`)
|
||||
**Dependencies**: Depends on all Level 1 tasks completing.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${readme_id}",
|
||||
"title": "Generate Project README",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "...", "IMPL-${group_count}"],
|
||||
"meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_existing_readme",
|
||||
"command": "bash(cat .workflow/docs/${project_name}/README.md 2>/dev/null || echo 'No existing README')",
|
||||
"output_to": "existing_readme"
|
||||
},
|
||||
{
|
||||
"step": "load_module_docs",
|
||||
"command": "bash(find .workflow/docs/${project_name} -type f -name '*.md' ! -path '.workflow/docs/${project_name}/README.md' ! -path '.workflow/docs/${project_name}/ARCHITECTURE.md' ! -path '.workflow/docs/${project_name}/EXAMPLES.md' ! -path '.workflow/docs/${project_name}/api/*' | xargs cat)",
|
||||
"output_to": "all_module_docs"
|
||||
},
|
||||
{
|
||||
"step": "analyze_project",
|
||||
"command": "bash(ccw cli -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\" --tool gemini --mode analysis)",
|
||||
"output_to": "project_outline"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate project README",
|
||||
"description": "Generate project README with navigation links while preserving user modifications",
|
||||
"modification_points": [
|
||||
"Parse [project_outline] and [all_module_docs]",
|
||||
"Generate README structure with navigation links",
|
||||
"Preserve [existing_readme] user modifications"
|
||||
],
|
||||
"logic_flow": ["Parse data", "Generate README with navigation", "Preserve modifications"],
|
||||
"depends_on": [],
|
||||
"output": "project_readme"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/${project_name}/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: Architecture & Examples Documentation Task
|
||||
|
||||
**Task ID**: `IMPL-${arch_id}` (where `arch_id = group_count + 2`)
|
||||
**Dependencies**: Depends on Level 2 (Project README).
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${arch_id}",
|
||||
"title": "Generate Architecture & Examples Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-${readme_id}"],
|
||||
"meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{"step": "load_existing_docs", "command": "bash(cat .workflow/docs/${project_name}/{ARCHITECTURE,EXAMPLES}.md 2>/dev/null || echo 'No existing docs')", "output_to": "existing_arch_examples"},
|
||||
{"step": "load_all_docs", "command": "bash(cat .workflow/docs/${project_name}/README.md && find .workflow/docs/${project_name} -type f -name '*.md' ! -path '*/README.md' ! -path '*/ARCHITECTURE.md' ! -path '*/EXAMPLES.md' ! -path '*/api/*' | xargs cat)", "output_to": "all_docs"},
|
||||
{"step": "analyze_architecture", "command": "bash(ccw cli -p \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\" --tool gemini --mode analysis)", "output_to": "arch_examples_outline"}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate architecture and examples documentation",
|
||||
"modification_points": [
|
||||
"Parse [arch_examples_outline] and [all_docs]",
|
||||
"Generate ARCHITECTURE.md (system design, patterns)",
|
||||
"Generate EXAMPLES.md (code snippets, usage)",
|
||||
"Preserve [existing_arch_examples] modifications"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "arch_examples_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/${project_name}/ARCHITECTURE.md", ".workflow/docs/${project_name}/EXAMPLES.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 4: HTTP API Documentation Task (Optional)
|
||||
|
||||
**Task ID**: `IMPL-${api_id}` (where `api_id = group_count + 3`)
|
||||
**Dependencies**: Depends on Level 3.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${api_id}",
|
||||
"title": "Generate HTTP API Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-${arch_id}"],
|
||||
"meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{"step": "discover_api", "command": "bash(rg 'router\\.| @(Get|Post)' -g '*.{ts,js}')", "output_to": "endpoint_discovery"},
|
||||
{"step": "load_existing_api", "command": "bash(cat .workflow/docs/${project_name}/api/README.md 2>/dev/null || echo 'No existing API docs')", "output_to": "existing_api_docs"},
|
||||
{"step": "analyze_api", "command": "bash(ccw cli -p \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\" --tool gemini --mode analysis)", "output_to": "api_outline"}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate HTTP API documentation",
|
||||
"modification_points": [
|
||||
"Parse [api_outline] and [endpoint_discovery]",
|
||||
"Document endpoints, request/response formats",
|
||||
"Preserve [existing_api_docs] modifications"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "api_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/${project_name}/api/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Session Structure
|
||||
|
||||
**Unified Structure** (single JSON replaces multiple text files):
|
||||
|
||||
```
|
||||
.workflow/active/
|
||||
└── WFS-docs-{timestamp}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .process/
|
||||
│ └── doc-planning-data.json # All Phase 2 analysis data (replaces 7+ files)
|
||||
└── .task/
|
||||
├── IMPL-001.json # Small: all modules | Large: group 1
|
||||
├── IMPL-00N.json # (Large only: groups 2-N)
|
||||
├── IMPL-{N+1}.json # README (full mode)
|
||||
├── IMPL-{N+2}.json # ARCHITECTURE+EXAMPLES (full mode)
|
||||
└── IMPL-{N+3}.json # HTTP API (optional)
|
||||
```
|
||||
|
||||
**doc-planning-data.json Structure**:
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"generated_at": "2025-11-03T16:41:06+08:00",
|
||||
"project_name": "Claude_dms3",
|
||||
"project_root": "/d/Claude_dms3"
|
||||
},
|
||||
"folder_analysis": [
|
||||
{"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2},
|
||||
{"path": "./src/utils", "type": "navigation", "code_count": 0, "dirs_count": 4}
|
||||
],
|
||||
"top_level_dirs": ["src/modules", "src/utils", "lib/core"],
|
||||
"existing_docs": {
|
||||
"file_list": [".workflow/docs/project/src/core/API.md"],
|
||||
"content": "... concatenated existing docs ..."
|
||||
},
|
||||
"unified_analysis": [
|
||||
{"module_path": "./src/core", "outline_summary": "Core functionality"}
|
||||
],
|
||||
"groups": {
|
||||
"count": 4,
|
||||
"assignments": [
|
||||
{"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 6},
|
||||
{"group_id": "002", "directories": ["lib/core", "lib/helpers"], "doc_count": 7}
|
||||
]
|
||||
},
|
||||
"statistics": {
|
||||
"total": 15,
|
||||
"code": 8,
|
||||
"navigation": 7,
|
||||
"top_level": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Workflow Session Structure** (workflow-session.json):
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-docs-{timestamp}",
|
||||
"project": "{project_name} documentation",
|
||||
"status": "planning",
|
||||
"timestamp": "2024-01-20T14:30:22+08:00",
|
||||
"path": ".",
|
||||
"target_path": "/path/to/project",
|
||||
"project_root": "/path/to/project",
|
||||
"project_name": "{project_name}",
|
||||
"mode": "full",
|
||||
"tool": "gemini",
|
||||
"cli_execute": false,
|
||||
"update_mode": "update",
|
||||
"existing_docs": 5,
|
||||
"analysis": {
|
||||
"total": "15",
|
||||
"code": "8",
|
||||
"navigation": "7",
|
||||
"top_level": "3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Generated Documentation
|
||||
|
||||
**Structure mirrors project source directories under project-specific folder**:
|
||||
|
||||
```
|
||||
.workflow/docs/
|
||||
└── {project_name}/ # Project-specific root
|
||||
├── src/ # Mirrors src/ directory
|
||||
│ ├── modules/
|
||||
│ │ ├── README.md # Navigation
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── API.md # API signatures
|
||||
│ │ │ ├── README.md # Module docs
|
||||
│ │ │ └── middleware/
|
||||
│ │ │ ├── API.md
|
||||
│ │ │ └── README.md
|
||||
│ │ └── api/
|
||||
│ │ ├── API.md
|
||||
│ │ └── README.md
|
||||
│ └── utils/
|
||||
│ └── README.md
|
||||
├── lib/ # Mirrors lib/ directory
|
||||
│ └── core/
|
||||
│ ├── API.md
|
||||
│ └── README.md
|
||||
├── README.md # Project root
|
||||
├── ARCHITECTURE.md # System design
|
||||
├── EXAMPLES.md # Usage examples
|
||||
└── api/ # Optional
|
||||
└── README.md # HTTP API reference
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
|
||||
```bash
|
||||
# Execute entire workflow (auto-discovers active session)
|
||||
/workflow:execute
|
||||
|
||||
# Or specify session
|
||||
/workflow:execute --resume-session="WFS-docs-yyyymmdd-hhmmss"
|
||||
|
||||
# Individual task execution
|
||||
/task:execute IMPL-001
|
||||
```
|
||||
|
||||
## Template Reference
|
||||
|
||||
**Available Templates** (`~/.claude/workflows/cli-templates/prompts/documentation/`):
|
||||
- `api.txt`: Code API (Part A) + HTTP API (Part B)
|
||||
- `module-readme.txt`: Module purpose, usage, dependencies
|
||||
- `folder-navigation.txt`: Navigation README for folders with subdirectories
|
||||
- `project-readme.txt`: Project overview, getting started, navigation
|
||||
- `project-architecture.txt`: System structure, module map, design patterns
|
||||
- `project-examples.txt`: End-to-end usage examples
|
||||
|
||||
## Execution Mode Summary
|
||||
|
||||
| Mode | CLI Placement | CLI MODE | Approval Flag | Agent Role |
|
||||
|------|---------------|----------|---------------|------------|
|
||||
| **Agent (default)** | pre_analysis | analysis | (none) | Generates documentation content |
|
||||
| **CLI (--cli-execute)** | implementation_approach | write | --mode write | Executes CLI commands, validates output |
|
||||
|
||||
**Execution Flow**:
|
||||
- **Phase 2**: Unified analysis once, results in `.process/`
|
||||
- **Phase 4**: Dynamic grouping (max 2 dirs per group)
|
||||
- **Level 1**: Parallel processing for module tree groups
|
||||
- **Level 2+**: Sequential execution for project-level docs
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:execute` - Execute documentation tasks
|
||||
- `/workflow:status` - View task progress
|
||||
- `/workflow:session:complete` - Mark session complete
|
||||
@@ -1,182 +0,0 @@
|
||||
---
|
||||
name: load-skill-memory
|
||||
description: Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords
|
||||
argument-hint: "[skill_name] \"task intent description\""
|
||||
allowed-tools: Bash(*), Read(*), Skill(*)
|
||||
---
|
||||
|
||||
# Memory Load SKILL Command (/memory:load-skill-memory)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The `memory:load-skill-memory` command **activates SKILL package** (auto-detect from task or manual specification) and intelligently loads documentation based on user's task intent. The system automatically determines which documentation files to read based on the intent description.
|
||||
|
||||
**Core Philosophy**:
|
||||
- **Flexible Activation**: Auto-detect skill from task description/paths, or user explicitly specifies
|
||||
- **Intent-Driven Loading**: System analyzes task intent to determine documentation scope
|
||||
- **Intelligent Selection**: Automatically chooses appropriate documentation level and modules
|
||||
- **Direct Context Loading**: Loads selected documentation into conversation memory
|
||||
|
||||
**When to Use**:
|
||||
- Manually activate a known SKILL package for a specific task
|
||||
- Load SKILL context when system hasn't auto-triggered it
|
||||
- Force reload SKILL documentation with specific intent focus
|
||||
|
||||
**Note**: Normal SKILL activation happens automatically via description triggers or path mentions (system extracts skill name from file paths for intelligent triggering). Use this command only when manual activation is needed.
|
||||
|
||||
## 2. Parameters
|
||||
|
||||
- `[skill_name]` (Optional): Name of SKILL package to activate
|
||||
- If omitted: System auto-detects from task description or file paths
|
||||
- If specified: Direct activation of named SKILL package
|
||||
- Example: `my_project`, `api_service`
|
||||
- Must match directory name under `.claude/skills/`
|
||||
|
||||
- `"task intent description"` (Required): Description of what you want to do
|
||||
- Used for both: auto-detection (if skill_name omitted) and documentation scope selection
|
||||
- **Analysis tasks**: "分析builder pattern实现", "理解参数系统架构"
|
||||
- **Modification tasks**: "修改workflow逻辑", "增强thermal template功能"
|
||||
- **Learning tasks**: "学习接口设计模式", "了解测试框架使用"
|
||||
- **With paths**: "修改D:\projects\my_project\src\auth.py的认证逻辑" (auto-extracts `my_project`)
|
||||
|
||||
## 3. Execution Flow
|
||||
|
||||
### Step 1: Determine SKILL Name (if not provided)
|
||||
|
||||
**Auto-Detection Strategy** (when skill_name parameter is omitted):
|
||||
1. **Path Extraction**: Scan task description for file paths
|
||||
- Extract potential project names from path segments
|
||||
- Example: `"修改D:\projects\my_project\src\auth.py"` → extracts `my_project`
|
||||
2. **Keyword Matching**: Match task keywords against SKILL descriptions
|
||||
- Search for project-specific terms, domain keywords
|
||||
3. **Validation**: Check if extracted name matches `.claude/skills/{skill_name}/`
|
||||
|
||||
**Result**: Either uses provided skill_name or auto-detected name for activation
|
||||
|
||||
### Step 2: Activate SKILL and Analyze Intent
|
||||
|
||||
**Activate SKILL Package**:
|
||||
```javascript
|
||||
Skill(command: "${skill_name}") // Uses provided or auto-detected name
|
||||
```
|
||||
|
||||
**What Happens After Activation**:
|
||||
1. If SKILL exists in memory: System reads `.claude/skills/${skill_name}/SKILL.md`
|
||||
2. If SKILL not found in memory: Error - SKILL package doesn't exist
|
||||
3. SKILL description triggers are loaded into memory
|
||||
4. Progressive loading mechanism becomes available
|
||||
5. Documentation structure is now accessible
|
||||
|
||||
**Intent Analysis**:
|
||||
Based on task intent description, system determines:
|
||||
- **Action type**: analyzing, modifying, learning
|
||||
- **Scope**: specific module, architecture overview, complete system
|
||||
- **Depth**: quick reference, detailed API, full documentation
|
||||
|
||||
### Step 3: Intelligent Documentation Loading
|
||||
|
||||
**Loading Strategy**:
|
||||
|
||||
The system automatically selects documentation based on intent keywords:
|
||||
|
||||
1. **Quick Understanding** ("了解", "快速理解", "什么是"):
|
||||
- Load: Level 0 (README.md only, ~2K tokens)
|
||||
- Use case: Quick overview of capabilities
|
||||
|
||||
2. **Specific Module Analysis** ("分析XXX模块", "理解XXX实现"):
|
||||
- Load: Module-specific README.md + API.md (~5K tokens)
|
||||
- Use case: Deep dive into specific component
|
||||
|
||||
3. **Architecture Review** ("架构", "设计模式", "整体结构"):
|
||||
- Load: README.md + ARCHITECTURE.md (~10K tokens)
|
||||
- Use case: System design understanding
|
||||
|
||||
4. **Implementation/Modification** ("修改", "增强", "实现"):
|
||||
- Load: Relevant module docs + EXAMPLES.md (~15K tokens)
|
||||
- Use case: Code modification with examples
|
||||
|
||||
5. **Comprehensive Learning** ("学习", "完整了解", "深入理解"):
|
||||
- Load: Level 3 (All documentation, ~40K tokens)
|
||||
- Use case: Complete system mastery
|
||||
|
||||
**Documentation Loaded into Memory**:
|
||||
After loading, the selected documentation content is available in conversation memory for subsequent operations.
|
||||
|
||||
## 4. Usage Examples
|
||||
|
||||
### Example 1: Manual Specification
|
||||
|
||||
**User Command**:
|
||||
```bash
|
||||
/memory:load-skill-memory my_project "修改认证模块增加OAuth支持"
|
||||
```
|
||||
|
||||
**Execution**:
|
||||
```javascript
|
||||
// Step 1: Use provided skill_name
|
||||
skill_name = "my_project" // Directly from parameter
|
||||
|
||||
// Step 2: Activate SKILL
|
||||
Skill(command: "my_project")
|
||||
|
||||
// Step 3: Intent Analysis
|
||||
Keywords: ["修改", "认证模块", "增加", "OAuth"]
|
||||
Action: modifying (implementation)
|
||||
Scope: auth module + examples
|
||||
|
||||
// Load documentation based on intent
|
||||
Read(.workflow/docs/my_project/auth/README.md)
|
||||
Read(.workflow/docs/my_project/auth/API.md)
|
||||
Read(.workflow/docs/my_project/EXAMPLES.md)
|
||||
```
|
||||
|
||||
### Example 2: Auto-Detection from Path
|
||||
|
||||
**User Command**:
|
||||
```bash
|
||||
/memory:load-skill-memory "修改D:\projects\my_project\src\services\api.py的接口逻辑"
|
||||
```
|
||||
|
||||
**Execution**:
|
||||
```javascript
|
||||
// Step 1: Auto-detect skill_name from path
|
||||
Path detected: "D:\projects\my_project\src\services\api.py"
|
||||
Extracted: "my_project"
|
||||
Validated: .claude/skills/my_project/ exists ✓
|
||||
skill_name = "my_project"
|
||||
|
||||
// Step 2: Activate SKILL
|
||||
Skill(command: "my_project")
|
||||
|
||||
// Step 3: Intent Analysis
|
||||
Keywords: ["修改", "services", "接口逻辑"]
|
||||
Action: modifying (implementation)
|
||||
Scope: services module + examples
|
||||
|
||||
// Load documentation based on intent
|
||||
Read(.workflow/docs/my_project/services/README.md)
|
||||
Read(.workflow/docs/my_project/services/API.md)
|
||||
Read(.workflow/docs/my_project/EXAMPLES.md)
|
||||
```
|
||||
|
||||
## 5. Intent Keyword Mapping
|
||||
|
||||
**Quick Reference**:
|
||||
- **Triggers**: "了解", "快速", "什么是", "简介"
|
||||
- **Loads**: README.md only (~2K)
|
||||
|
||||
**Module-Specific**:
|
||||
- **Triggers**: "XXX模块", "XXX组件", "分析XXX"
|
||||
- **Loads**: Module README + API (~5K)
|
||||
|
||||
**Architecture**:
|
||||
- **Triggers**: "架构", "设计", "整体结构", "系统设计"
|
||||
- **Loads**: README + ARCHITECTURE (~10K)
|
||||
|
||||
**Implementation**:
|
||||
- **Triggers**: "修改", "增强", "实现", "开发", "集成"
|
||||
- **Loads**: Relevant module + EXAMPLES (~15K)
|
||||
|
||||
**Comprehensive**:
|
||||
- **Triggers**: "完整", "深入", "全面", "学习整个"
|
||||
- **Loads**: All documentation (~40K)
|
||||
@@ -1,525 +0,0 @@
|
||||
---
|
||||
name: skill-memory
|
||||
description: 4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist)
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
# Memory SKILL Package Generator
|
||||
|
||||
## Orchestrator Role
|
||||
|
||||
**Pure Orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files.
|
||||
|
||||
**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction.
|
||||
|
||||
**Execution Paths**:
|
||||
- **Full Path**: All 4 phases (no existing docs OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 4 (existing docs found AND no `--regenerate` flag)
|
||||
- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs
|
||||
3. **Parse Every Output**: Extract required data from each command output (session_id, task_count, file paths)
|
||||
4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool
|
||||
7. **No Manual Steps**: User should never be prompted for decisions between phases
|
||||
|
||||
---
|
||||
|
||||
## 4-Phase Execution
|
||||
|
||||
### Phase 1: Prepare Arguments
|
||||
|
||||
**Goal**: Parse command arguments and check existing documentation
|
||||
|
||||
**Step 1: Get Target Path and Project Name**
|
||||
```bash
|
||||
# Get current directory (or use provided path)
|
||||
bash(pwd)
|
||||
|
||||
# Get project name from directory
|
||||
bash(basename "$(pwd)")
|
||||
|
||||
# Get project root
|
||||
bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- `target_path`: `/d/my_project`
|
||||
- `project_name`: `my_project`
|
||||
- `project_root`: `/d/my_project`
|
||||
|
||||
**Step 2: Set Default Parameters**
|
||||
```bash
|
||||
# Default values (use these unless user specifies otherwise):
|
||||
# - tool: "gemini"
|
||||
# - mode: "full"
|
||||
# - regenerate: false (no --regenerate flag)
|
||||
# - cli_execute: false (no --cli-execute flag)
|
||||
```
|
||||
|
||||
**Step 3: Check Existing Documentation**
|
||||
```bash
|
||||
# Check if docs directory exists
|
||||
bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
|
||||
|
||||
# Count existing documentation files
|
||||
bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- `docs_exists`: `exists` or `not_exists`
|
||||
- `existing_docs`: `5` (or `0` if no docs)
|
||||
|
||||
**Step 4: Determine Execution Path**
|
||||
|
||||
**Decision Logic**:
|
||||
```javascript
|
||||
if (existing_docs > 0 && !regenerate_flag) {
|
||||
// Documentation exists and no regenerate flag
|
||||
SKIP_DOCS_GENERATION = true
|
||||
message = "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
// Force regeneration: delete existing docs
|
||||
bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
|
||||
SKIP_DOCS_GENERATION = false
|
||||
message = "Regenerating documentation from scratch."
|
||||
} else {
|
||||
// No existing docs
|
||||
SKIP_DOCS_GENERATION = false
|
||||
message = "No existing documentation found, generating new documentation."
|
||||
}
|
||||
```
|
||||
|
||||
**Summary Variables**:
|
||||
- `PROJECT_NAME`: `my_project`
|
||||
- `TARGET_PATH`: `/d/my_project`
|
||||
- `DOCS_PATH`: `.workflow/docs/my_project`
|
||||
- `TOOL`: `gemini` (default) or user-specified
|
||||
- `MODE`: `full` (default) or user-specified
|
||||
- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag
|
||||
- `REGENERATE`: `false` (default) or `true` if --regenerate flag
|
||||
- `EXISTING_DOCS`: Count of existing documentation files
|
||||
- `SKIP_DOCS_GENERATION`: `true` if skipping Phase 2/3, `false` otherwise
|
||||
|
||||
**Completion & TodoWrite**:
|
||||
- If `SKIP_DOCS_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress
|
||||
- If `SKIP_DOCS_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress
|
||||
|
||||
**Next Action**:
|
||||
- If skipping: Display skip message → Jump to Phase 4 (SKILL.md generation)
|
||||
- If not skipping: Display preparation results → Continue to Phase 2 (documentation planning)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Call /memory:docs
|
||||
|
||||
**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
|
||||
|
||||
**Goal**: Trigger documentation generation workflow
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]")
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
/memory:docs /d/my_app --tool gemini --mode full
|
||||
/memory:docs /d/my_app --tool gemini --mode full --cli-execute
|
||||
```
|
||||
|
||||
**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection.
|
||||
|
||||
**Parse Output**:
|
||||
- Extract session ID: `WFS-docs-[timestamp]` (store as `docsSessionId`)
|
||||
- Extract task count (store as `taskCount`)
|
||||
|
||||
**Completion Criteria**:
|
||||
- `/memory:docs` command executed successfully
|
||||
- Session ID extracted and stored
|
||||
- Task count retrieved
|
||||
- Task files created in `.workflow/[docsSessionId]/.task/`
|
||||
- workflow-session.json exists
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
|
||||
|
||||
**Next Action**: Display docs planning results (session ID, task count) → Auto-continue to Phase 3
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Execute Documentation Generation
|
||||
|
||||
**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
|
||||
|
||||
**Goal**: Execute documentation generation tasks
|
||||
|
||||
**Command**:
|
||||
```bash
|
||||
SlashCommand(command="/workflow:execute")
|
||||
```
|
||||
|
||||
**Note**: `/workflow:execute` automatically discovers active session from Phase 2
|
||||
|
||||
**Completion Criteria**:
|
||||
- `/workflow:execute` command executed successfully
|
||||
- Documentation files generated in `.workflow/docs/[projectName]/`
|
||||
- All tasks marked as completed in session
|
||||
- At minimum: module documentation files exist (API.md and/or README.md)
|
||||
- For full mode: Project README, ARCHITECTURE, EXAMPLES files generated
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
|
||||
|
||||
**Next Action**: Display execution results (file count, module count) → Auto-continue to Phase 4
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Generate SKILL.md Index
|
||||
|
||||
**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL index.
|
||||
|
||||
**Step 1: Read Key Files** (Use Read tool)
|
||||
- `.workflow/docs/{project_name}/README.md` (required)
|
||||
- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional)
|
||||
|
||||
**Step 2: Discover Structure**
|
||||
```bash
|
||||
bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u)
|
||||
```
|
||||
|
||||
**Step 3: Generate Intelligent Description**
|
||||
|
||||
Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.)
|
||||
|
||||
**Format**: `{Project} {core capabilities} (located at {project_path}). Load this SKILL when analyzing, modifying, or learning about {domain_description} or files under this path, especially when no relevant context exists in memory.`
|
||||
|
||||
**Key Elements**:
|
||||
- **Path Reference**: Use `TARGET_PATH` from Phase 1 for precise location identification
|
||||
- **Domain Description**: Extract human-readable domain/feature area from README (e.g., "workflow management", "thermal modeling")
|
||||
- **Trigger Optimization**: Include project path, emphasize "especially when no relevant context exists in memory"
|
||||
- **Action Coverage**: analyzing (分析), modifying (修改), learning (了解)
|
||||
|
||||
**Example**: "Workflow orchestration system with CLI tools and documentation generation (located at /d/Claude_dms3). Load this SKILL when analyzing, modifying, or learning about workflow management or files under this path, especially when no relevant context exists in memory."
|
||||
|
||||
**Step 4: Write SKILL.md** (Use Write tool)
|
||||
```bash
|
||||
bash(mkdir -p .claude/skills/{project_name})
|
||||
```
|
||||
|
||||
`.claude/skills/{project_name}/SKILL.md`:
|
||||
```yaml
|
||||
---
|
||||
name: {project_name}
|
||||
description: {intelligent description from Step 3}
|
||||
version: 1.0.0
|
||||
---
|
||||
# {Project Name} SKILL Package
|
||||
|
||||
## Documentation: `../../../.workflow/docs/{project_name}/`
|
||||
|
||||
## Progressive Loading
|
||||
### Level 0: Quick Start (~2K)
|
||||
- [README](../../../.workflow/docs/{project_name}/README.md)
|
||||
### Level 1: Core Modules (~8K)
|
||||
{Module READMEs}
|
||||
### Level 2: Complete (~25K)
|
||||
All modules + [Architecture](../../../.workflow/docs/{project_name}/ARCHITECTURE.md)
|
||||
### Level 3: Deep Dive (~40K)
|
||||
Everything + [Examples](../../../.workflow/docs/{project_name}/EXAMPLES.md)
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md file created at `.claude/skills/{project_name}/SKILL.md`
|
||||
- Intelligent description generated from documentation
|
||||
- Progressive loading levels (0-3) properly structured
|
||||
- Module index includes all documented modules
|
||||
- All file references use relative paths
|
||||
|
||||
**TodoWrite**: Mark phase 4 completed
|
||||
|
||||
**Final Action**: Report completion summary to user
|
||||
|
||||
**Return to User**:
|
||||
```
|
||||
SKILL Package Generation Complete
|
||||
|
||||
Project: {project_name}
|
||||
Documentation: .workflow/docs/{project_name}/ ({doc_count} files)
|
||||
SKILL Index: .claude/skills/{project_name}/SKILL.md
|
||||
|
||||
Generated:
|
||||
- {task_count} documentation tasks completed
|
||||
- SKILL.md with progressive loading (4 levels)
|
||||
- Module index with {module_count} modules
|
||||
|
||||
Usage:
|
||||
- Load Level 0: Quick project overview (~2K tokens)
|
||||
- Load Level 1: Core modules (~8K tokens)
|
||||
- Load Level 2: Complete docs (~25K tokens)
|
||||
- Load Level 3: Everything (~40K tokens)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Critical Rules
|
||||
|
||||
1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
|
||||
2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
|
||||
3. **Status-Driven Execution**: Check TodoList status after each phase:
|
||||
- If next task is "pending" → Mark it "in_progress" and execute
|
||||
- If all tasks are "completed" → Report final summary
|
||||
4. **Phase Completion Pattern**:
|
||||
```
|
||||
Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
|
||||
```
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
#### Initialization (Before Phase 1)
|
||||
|
||||
**FIRST ACTION**: Create TodoList with all 4 phases
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
```
|
||||
|
||||
**SECOND ACTION**: Execute Phase 1 immediately
|
||||
|
||||
#### Full Path (SKIP_DOCS_GENERATION = false)
|
||||
|
||||
**After Phase 1**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Auto-continue to Phase 2
|
||||
```
|
||||
|
||||
**After Phase 2**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Auto-continue to Phase 3
|
||||
```
|
||||
|
||||
**After Phase 3**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Auto-continue to Phase 4
|
||||
```
|
||||
|
||||
**After Phase 4**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Report completion summary to user
|
||||
```
|
||||
|
||||
#### Skip Path (SKIP_DOCS_GENERATION = true)
|
||||
|
||||
**After Phase 1** (detects existing docs, skips Phase 2 & 3):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Display skip message: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
|
||||
// Jump directly to Phase 4
|
||||
```
|
||||
|
||||
**After Phase 4**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
|
||||
{"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
|
||||
{"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
|
||||
{"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
|
||||
]})
|
||||
// Report completion summary to user
|
||||
```
|
||||
|
||||
### Execution Flow Diagrams
|
||||
|
||||
#### Full Path Flow
|
||||
```
|
||||
User triggers command
|
||||
↓
|
||||
[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
|
||||
↓
|
||||
[Execute] Phase 1: Parse arguments
|
||||
↓
|
||||
[TodoWrite] Phase 1 = completed, Phase 2 = in_progress
|
||||
↓
|
||||
[Execute] Phase 2: Call /memory:docs
|
||||
↓
|
||||
[TodoWrite] Phase 2 = completed, Phase 3 = in_progress
|
||||
↓
|
||||
[Execute] Phase 3: Call /workflow:execute
|
||||
↓
|
||||
[TodoWrite] Phase 3 = completed, Phase 4 = in_progress
|
||||
↓
|
||||
[Execute] Phase 4: Generate SKILL.md
|
||||
↓
|
||||
[TodoWrite] Phase 4 = completed
|
||||
↓
|
||||
[Report] Display completion summary
|
||||
```
|
||||
|
||||
#### Skip Path Flow
|
||||
```
|
||||
User triggers command
|
||||
↓
|
||||
[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
|
||||
↓
|
||||
[Execute] Phase 1: Parse arguments, detect existing docs
|
||||
↓
|
||||
[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress
|
||||
↓
|
||||
[Display] Skip message: "Documentation already exists, skipping Phase 2 and Phase 3"
|
||||
↓
|
||||
[Execute] Phase 4: Generate SKILL.md (always runs)
|
||||
↓
|
||||
[TodoWrite] Phase 4 = completed
|
||||
↓
|
||||
[Report] Display completion summary
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
- If any phase fails, mark it as "in_progress" (not completed)
|
||||
- Report error details to user
|
||||
- Do NOT auto-continue to next phase on failure
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]
|
||||
```
|
||||
|
||||
- **path**: Target directory (default: current directory)
|
||||
- **--tool**: CLI tool for documentation (default: gemini)
|
||||
- `gemini`: Comprehensive documentation
|
||||
- `qwen`: Architecture analysis
|
||||
- `codex`: Implementation validation
|
||||
- **--regenerate**: Force regenerate all documentation
|
||||
- When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration
|
||||
- Ensures fresh documentation from source code
|
||||
- **--mode**: Documentation mode (default: full)
|
||||
- `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES)
|
||||
- `partial`: Module docs only
|
||||
- **--cli-execute**: Enable CLI-based documentation generation (optional)
|
||||
- When enabled: CLI generates docs directly in implementation_approach
|
||||
- When disabled (default): Agent generates documentation content
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Generate SKILL Package (Default)
|
||||
|
||||
```bash
|
||||
/memory:skill-memory
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects current directory, checks existing docs
|
||||
2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode)
|
||||
3. Phase 3: Executes documentation generation via `/workflow:execute`
|
||||
4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
|
||||
|
||||
### Example 2: Regenerate with Qwen
|
||||
|
||||
```bash
|
||||
/memory:skill-memory /d/my_app --tool qwen --regenerate
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Parses target path, detects regenerate flag, deletes existing docs
|
||||
2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full`
|
||||
3. Phase 3: Executes documentation regeneration
|
||||
4. Phase 4: Generates updated SKILL.md
|
||||
|
||||
### Example 3: Partial Mode (Modules Only)
|
||||
|
||||
```bash
|
||||
/memory:skill-memory --mode partial
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects partial mode
|
||||
2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode)
|
||||
3. Phase 3: Executes module documentation only
|
||||
4. Phase 4: Generates SKILL.md with module-only index
|
||||
|
||||
### Example 4: CLI Execute Mode
|
||||
|
||||
```bash
|
||||
/memory:skill-memory --cli-execute
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects CLI execute mode
|
||||
2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode)
|
||||
3. Phase 3: Executes CLI-based documentation generation
|
||||
4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
|
||||
|
||||
### Example 5: Skip Path (Existing Docs)
|
||||
|
||||
```bash
|
||||
/memory:skill-memory
|
||||
```
|
||||
|
||||
**Scenario**: Documentation already exists in `.workflow/docs/{project_name}/`
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects existing docs (5 files), sets SKIP_DOCS_GENERATION = true
|
||||
2. Display: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
|
||||
3. Phase 4: Generates or updates SKILL.md index only (~5-10x faster)
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
skill-memory (orchestrator)
|
||||
├─ Phase 1: Prepare (bash commands, skip decision)
|
||||
├─ Phase 2: /memory:docs (task planning, skippable)
|
||||
├─ Phase 3: /workflow:execute (task execution, skippable)
|
||||
└─ Phase 4: Write SKILL.md (direct file generation, always runs)
|
||||
|
||||
No task JSON created by this command
|
||||
All documentation tasks managed by /memory:docs
|
||||
Smart skip logic: 5-10x faster when docs exist
|
||||
```
|
||||
@@ -1,773 +0,0 @@
|
||||
---
|
||||
name: swagger-docs
|
||||
description: Generate complete Swagger/OpenAPI documentation following RESTful standards with global security, API details, error codes, and validation tests
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]"
|
||||
---
|
||||
|
||||
# Swagger API Documentation Workflow (/memory:swagger-docs)
|
||||
|
||||
## Overview
|
||||
|
||||
Professional Swagger/OpenAPI documentation generator that strictly follows RESTful API design standards to produce enterprise-grade API documentation.
|
||||
|
||||
**Core Features**:
|
||||
- **RESTful Standards**: Strict adherence to REST architecture and HTTP semantics
|
||||
- **Global Security**: Unified Authorization Token validation mechanism
|
||||
- **Complete API Docs**: Descriptions, methods, URLs, parameters for each endpoint
|
||||
- **Organized Structure**: Clear directory hierarchy by business domain
|
||||
- **Detailed Fields**: Type, required, example, description for each field
|
||||
- **Error Code Standards**: Unified error response format and code definitions
|
||||
- **Validation Tests**: Boundary conditions and exception handling tests
|
||||
|
||||
**Output Structure** (--lang zh):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── 概述/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── 认证说明.md # Authentication guide
|
||||
│ ├── 错误码规范.md # Error code definitions
|
||||
│ └── 版本历史.md # Version history
|
||||
├── 用户模块/ # Grouped by business domain
|
||||
│ ├── 用户认证.md
|
||||
│ ├── 用户管理.md
|
||||
│ └── 权限控制.md
|
||||
├── 业务模块/
|
||||
│ └── ...
|
||||
└── 测试报告/
|
||||
├── 接口测试.md # API test results
|
||||
└── 边界测试.md # Boundary condition tests
|
||||
```
|
||||
|
||||
**Output Structure** (--lang en):
|
||||
```
|
||||
.workflow/docs/{project_name}/api/
|
||||
├── swagger.yaml # Main OpenAPI spec file
|
||||
├── overview/
|
||||
│ ├── README.md # API overview
|
||||
│ ├── authentication.md # Authentication guide
|
||||
│ ├── error-codes.md # Error code definitions
|
||||
│ └── changelog.md # Version history
|
||||
├── users/ # Grouped by business domain
|
||||
│ ├── authentication.md
|
||||
│ ├── management.md
|
||||
│ └── permissions.md
|
||||
├── orders/
|
||||
│ └── ...
|
||||
└── test-reports/
|
||||
├── api-tests.md # API test results
|
||||
└── boundary-tests.md # Boundary condition tests
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:swagger-docs [path] [--tool <gemini|qwen|codex>] [--format <yaml|json>] [--version <v3.0|v3.1>] [--lang <zh|en>]
|
||||
```
|
||||
|
||||
- **path**: API source code directory (default: current directory)
|
||||
- **--tool**: CLI tool selection (default: gemini)
|
||||
- `gemini`: Comprehensive analysis, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design
|
||||
- `codex`: Implementation validation, code quality
|
||||
- **--format**: OpenAPI spec format (default: yaml)
|
||||
- `yaml`: YAML format (recommended, better readability)
|
||||
- `json`: JSON format
|
||||
- **--version**: OpenAPI version (default: v3.0)
|
||||
- `v3.0`: OpenAPI 3.0.x
|
||||
- `v3.1`: OpenAPI 3.1.0 (supports JSON Schema 2020-12)
|
||||
- **--lang**: Documentation language (default: zh)
|
||||
- `zh`: Chinese documentation with Chinese directory names
|
||||
- `en`: English documentation with English directory names
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
```bash
|
||||
# Get project info
|
||||
bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Create swagger-docs session
|
||||
SlashCommand(command="/workflow:session:start --type swagger-docs --new \"{project_name}-swagger-{timestamp}\"")
|
||||
// Parse output to get sessionId
|
||||
```
|
||||
|
||||
```bash
|
||||
# Update workflow-session.json
|
||||
bash(jq '. + {"target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","format":"yaml","openapi_version":"3.0.3","lang":"{lang}","tool":"gemini"}' .workflow/active/{sessionId}/workflow-session.json > tmp.json && mv tmp.json .workflow/active/{sessionId}/workflow-session.json)
|
||||
```
|
||||
|
||||
### Phase 2: Scan API Endpoints
|
||||
|
||||
**Discovery Patterns**: Auto-detect framework signatures and API definition styles.
|
||||
|
||||
**Supported Frameworks**:
|
||||
| Framework | Detection Pattern | Example |
|
||||
|-----------|-------------------|---------|
|
||||
| Express.js | `router.get/post/put/delete` | `router.get('/users/:id')` |
|
||||
| Fastify | `fastify.route`, `@Route` | `fastify.get('/api/users')` |
|
||||
| NestJS | `@Controller`, `@Get/@Post` | `@Get('users/:id')` |
|
||||
| Koa | `router.get`, `ctx.body` | `router.get('/users')` |
|
||||
| Hono | `app.get/post`, `c.json` | `app.get('/users/:id')` |
|
||||
| FastAPI | `@app.get`, `@router.post` | `@app.get("/users/{id}")` |
|
||||
| Flask | `@app.route`, `@bp.route` | `@app.route('/users')` |
|
||||
| Spring | `@GetMapping`, `@PostMapping` | `@GetMapping("/users/{id}")` |
|
||||
| Go Gin | `r.GET`, `r.POST` | `r.GET("/users/:id")` |
|
||||
| Go Chi | `r.Get`, `r.Post` | `r.Get("/users/{id}")` |
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Detect API framework type
|
||||
bash(
|
||||
if rg -q "@Controller|@Get|@Post|@Put|@Delete" --type ts 2>/dev/null; then echo "NESTJS";
|
||||
elif rg -q "router\.(get|post|put|delete|patch)" --type ts --type js 2>/dev/null; then echo "EXPRESS";
|
||||
elif rg -q "fastify\.(get|post|route)" --type ts --type js 2>/dev/null; then echo "FASTIFY";
|
||||
elif rg -q "@app\.(get|post|put|delete)" --type py 2>/dev/null; then echo "FASTAPI";
|
||||
elif rg -q "@GetMapping|@PostMapping|@RequestMapping" --type java 2>/dev/null; then echo "SPRING";
|
||||
elif rg -q 'r\.(GET|POST|PUT|DELETE)' --type go 2>/dev/null; then echo "GO_GIN";
|
||||
else echo "UNKNOWN"; fi
|
||||
)
|
||||
|
||||
# 2. Scan all API endpoint definitions
|
||||
bash(rg -n "(router|app|fastify)\.(get|post|put|delete|patch)|@(Get|Post|Put|Delete|Patch|Controller|RequestMapping)" --type ts --type js --type py --type java --type go -g '!*.test.*' -g '!*.spec.*' -g '!node_modules/**' 2>/dev/null | head -200)
|
||||
|
||||
# 3. Extract route paths
|
||||
bash(rg -o "['\"](/api)?/[a-zA-Z0-9/:_-]+['\"]" --type ts --type js --type py -g '!*.test.*' 2>/dev/null | sort -u | head -100)
|
||||
|
||||
# 4. Detect existing OpenAPI/Swagger files
|
||||
bash(find . -type f \( -name "swagger.yaml" -o -name "swagger.json" -o -name "openapi.yaml" -o -name "openapi.json" \) ! -path "*/node_modules/*" 2>/dev/null)
|
||||
|
||||
# 5. Extract DTO/Schema definitions
|
||||
bash(rg -n "export (interface|type|class).*Dto|@ApiProperty|class.*Schema" --type ts -g '!*.test.*' 2>/dev/null | head -100)
|
||||
```
|
||||
|
||||
**Data Processing**: Parse outputs, use **Write tool** to create `${session_dir}/.process/swagger-planning-data.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"generated_at": "2025-01-01T12:00:00+08:00",
|
||||
"project_name": "project_name",
|
||||
"project_root": "/path/to/project",
|
||||
"openapi_version": "3.0.3",
|
||||
"format": "yaml",
|
||||
"lang": "zh"
|
||||
},
|
||||
"framework": {
|
||||
"type": "NESTJS",
|
||||
"detected_patterns": ["@Controller", "@Get", "@Post"],
|
||||
"base_path": "/api/v1"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"file": "src/modules/users/users.controller.ts",
|
||||
"line": 25,
|
||||
"method": "GET",
|
||||
"path": "/api/v1/users/:id",
|
||||
"handler": "getUser",
|
||||
"controller": "UsersController"
|
||||
}
|
||||
],
|
||||
"existing_specs": {
|
||||
"found": false,
|
||||
"files": []
|
||||
},
|
||||
"dto_schemas": [
|
||||
{
|
||||
"name": "CreateUserDto",
|
||||
"file": "src/modules/users/dto/create-user.dto.ts",
|
||||
"properties": ["email", "password", "name"]
|
||||
}
|
||||
],
|
||||
"statistics": {
|
||||
"total_endpoints": 45,
|
||||
"by_method": {"GET": 20, "POST": 15, "PUT": 5, "DELETE": 5},
|
||||
"by_module": {"users": 12, "auth": 8, "orders": 15, "products": 10}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Analyze API Structure
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Analyze controller/route file structure
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.endpoints[].file' | sort -u | head -20)
|
||||
|
||||
# 2. Extract request/response types
|
||||
bash(for f in $(jq -r '.dto_schemas[].file' ${session_dir}/.process/swagger-planning-data.json | head -20); do echo "=== $f ===" && cat "$f" 2>/dev/null; done)
|
||||
|
||||
# 3. Analyze authentication middleware
|
||||
bash(rg -n "auth|guard|middleware|jwt|bearer|token" -i --type ts --type js -g '!*.test.*' -g '!node_modules/**' 2>/dev/null | head -50)
|
||||
|
||||
# 4. Detect error handling patterns
|
||||
bash(rg -n "HttpException|BadRequest|Unauthorized|Forbidden|NotFound|throw new" --type ts --type js -g '!*.test.*' 2>/dev/null | head -50)
|
||||
```
|
||||
|
||||
**Deep Analysis via Gemini CLI**:
|
||||
|
||||
```bash
|
||||
ccw cli -p "
|
||||
PURPOSE: Analyze API structure and generate OpenAPI specification outline for comprehensive documentation
|
||||
TASK:
|
||||
• Parse all API endpoints and identify business module boundaries
|
||||
• Extract request parameters, request bodies, and response formats
|
||||
• Identify authentication mechanisms and security requirements
|
||||
• Discover error handling patterns and error codes
|
||||
• Map endpoints to logical module groups
|
||||
MODE: analysis
|
||||
CONTEXT: @src/**/*.controller.ts @src/**/*.routes.ts @src/**/*.dto.ts @src/**/middleware/**/*
|
||||
EXPECTED: JSON format API structure analysis report with modules, endpoints, security schemes, and error codes
|
||||
CONSTRAINTS: Strict RESTful standards | Identify all public endpoints | Document output language: {lang}
|
||||
" --tool gemini --mode analysis --rule analysis-code-patterns --cd {project_root}
|
||||
```
|
||||
|
||||
**Update swagger-planning-data.json** with analysis results:
|
||||
|
||||
```json
|
||||
{
|
||||
"api_structure": {
|
||||
"modules": [
|
||||
{
|
||||
"name": "Users",
|
||||
"name_zh": "用户模块",
|
||||
"base_path": "/api/v1/users",
|
||||
"endpoints": [
|
||||
{
|
||||
"path": "/api/v1/users",
|
||||
"method": "GET",
|
||||
"operation_id": "listUsers",
|
||||
"summary": "List all users",
|
||||
"summary_zh": "获取用户列表",
|
||||
"description": "Paginated list of system users with filtering by status and role",
|
||||
"description_zh": "分页获取系统用户列表，支持按状态、角色筛选",
|
||||
"tags": ["User Management"],
|
||||
"tags_zh": ["用户管理"],
|
||||
"security": ["bearerAuth"],
|
||||
"parameters": {
|
||||
"query": ["page", "limit", "status", "role"]
|
||||
},
|
||||
"responses": {
|
||||
"200": "UserListResponse",
|
||||
"401": "UnauthorizedError",
|
||||
"403": "ForbiddenError"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"security_schemes": {
|
||||
"bearerAuth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT",
|
||||
"description": "JWT Token authentication. Add Authorization: Bearer <token> to request header"
|
||||
}
|
||||
},
|
||||
"error_codes": [
|
||||
{"code": "AUTH_001", "status": 401, "message": "Invalid or expired token", "message_zh": "Token 无效或已过期"},
|
||||
{"code": "AUTH_002", "status": 401, "message": "Authentication required", "message_zh": "未提供认证信息"},
|
||||
{"code": "AUTH_003", "status": 403, "message": "Insufficient permissions", "message_zh": "权限不足"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 4: Task Decomposition
|
||||
|
||||
**Task Hierarchy**:
|
||||
|
||||
```
|
||||
Level 1: Infrastructure Tasks (Parallel)
|
||||
├─ IMPL-001: Generate main OpenAPI spec file (swagger.yaml)
|
||||
├─ IMPL-002: Generate global security config and auth documentation
|
||||
└─ IMPL-003: Generate unified error code specification
|
||||
|
||||
Level 2: Module Documentation Tasks (Parallel, by business module)
|
||||
├─ IMPL-004: Users module API documentation
|
||||
├─ IMPL-005: Auth module API documentation
|
||||
├─ IMPL-006: Business module N API documentation
|
||||
└─ ...
|
||||
|
||||
Level 3: Aggregation Tasks (Depends on Level 1-2)
|
||||
├─ IMPL-N+1: Generate API overview and navigation
|
||||
└─ IMPL-N+2: Generate version history and changelog
|
||||
|
||||
Level 4: Validation Tasks (Depends on Level 1-3)
|
||||
├─ IMPL-N+3: API endpoint validation tests
|
||||
└─ IMPL-N+4: Boundary condition tests
|
||||
```
|
||||
|
||||
**Grouping Strategy**:
|
||||
1. Group by business module (users, orders, products, etc.)
|
||||
2. Maximum 10 endpoints per task
|
||||
3. Large modules (>10 endpoints) split by submodules
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Count endpoints by module
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.statistics.by_module')
|
||||
|
||||
# 2. Calculate task groupings
|
||||
bash(cat ${session_dir}/.process/swagger-planning-data.json | jq -r '.api_structure.modules[] | "\(.name):\(.endpoints | length)"')
|
||||
```
|
||||
|
||||
**Data Processing**: Use **Edit tool** to update `swagger-planning-data.json` with task groups:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_groups": {
|
||||
"level1_count": 3,
|
||||
"level2_count": 5,
|
||||
"total_count": 12,
|
||||
"assignments": [
|
||||
{"task_id": "IMPL-001", "level": 1, "type": "openapi-spec", "title": "Generate OpenAPI main spec file"},
|
||||
{"task_id": "IMPL-002", "level": 1, "type": "security", "title": "Generate global security config"},
|
||||
{"task_id": "IMPL-003", "level": 1, "type": "error-codes", "title": "Generate error code specification"},
|
||||
{"task_id": "IMPL-004", "level": 2, "type": "module-doc", "module": "users", "endpoint_count": 12},
|
||||
{"task_id": "IMPL-005", "level": 2, "type": "module-doc", "module": "auth", "endpoint_count": 8}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values from workflow-session.json
|
||||
2. Read task groups from swagger-planning-data.json
|
||||
3. Generate Level 1 tasks (infrastructure)
|
||||
4. Generate Level 2 tasks (by module)
|
||||
5. Generate Level 3-4 tasks (aggregation and validation)
|
||||
|
||||
## Task Templates
|
||||
|
||||
### Level 1-1: OpenAPI Main Spec File
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Generate OpenAPI main specification file",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-openapi-spec",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"priority": "critical"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Generate OpenAPI 3.0.3 compliant swagger.yaml",
|
||||
"Include complete info, servers, tags, paths, components definitions",
|
||||
"Follow RESTful design standards, use {lang} for descriptions"
|
||||
],
|
||||
"precomputed_data": {
|
||||
"planning_data": "${session_dir}/.process/swagger-planning-data.json"
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_analysis_data",
|
||||
"action": "Load API analysis data",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json)"
|
||||
],
|
||||
"output_to": "api_analysis"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate OpenAPI spec file",
|
||||
"description": "Create complete swagger.yaml specification file",
|
||||
"cli_prompt": "PURPOSE: Generate OpenAPI 3.0.3 specification file from analyzed API structure\nTASK:\n• Define openapi version: 3.0.3\n• Define info: title, description, version, contact, license\n• Define servers: development, staging, production environments\n• Define tags: organized by business modules\n• Define paths: all API endpoints with complete specifications\n• Define components: schemas, securitySchemes, parameters, responses\nMODE: write\nCONTEXT: @[api_analysis]\nEXPECTED: Complete swagger.yaml file following OpenAPI 3.0.3 specification\nCONSTRAINTS: Use {lang} for all descriptions | Strict RESTful standards\n--rule documentation-swagger-api",
|
||||
"output": "swagger.yaml"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/swagger.yaml"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-2: Global Security Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-002",
|
||||
"title": "Generate global security configuration and authentication guide",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-security",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Document Authorization header format in detail",
|
||||
"Describe token acquisition, refresh, and expiration mechanisms",
|
||||
"List permission requirements for each endpoint"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "analyze_auth",
|
||||
"command": "bash(rg -n 'auth|guard|jwt|bearer' -i --type ts -g '!*.test.*' 2>/dev/null | head -50)",
|
||||
"output_to": "auth_patterns"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate authentication documentation",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive authentication documentation for API security\nTASK:\n• Document authentication mechanism: JWT Bearer Token\n• Explain header format: Authorization: Bearer <token>\n• Describe token lifecycle: acquisition, refresh, expiration handling\n• Define permission levels: public, user, admin, super_admin\n• Document authentication failure responses: 401/403 error handling\nMODE: write\nCONTEXT: @[auth_patterns] @src/**/auth/**/* @src/**/guard/**/*\nEXPECTED: Complete authentication guide in {lang}\nCONSTRAINTS: Include code examples | Clear step-by-step instructions\n--rule development-feature",
|
||||
"output": "{auth_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{auth_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 1-3: Unified Error Code Specification
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-003",
|
||||
"title": "Generate unified error code specification",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "swagger-error-codes",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Define unified error response format",
|
||||
"Create categorized error code system (auth, business, system)",
|
||||
"Provide detailed description and examples for each error code"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate error code specification document",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive error code specification for consistent API error handling\nTASK:\n• Define error response format: {code, message, details, timestamp}\n• Document authentication errors (AUTH_xxx): 401/403 series\n• Document parameter errors (PARAM_xxx): 400 series\n• Document business errors (BIZ_xxx): business logic errors\n• Document system errors (SYS_xxx): 500 series\n• For each error code: HTTP status, error message, possible causes, resolution suggestions\nMODE: write\nCONTEXT: @src/**/*.exception.ts @src/**/*.filter.ts\nEXPECTED: Complete error code specification in {lang} with tables and examples\nCONSTRAINTS: Include response examples | Clear categorization\n--rule development-feature",
|
||||
"output": "{error_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/{error_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Module API Documentation (Template)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${module_task_id}",
|
||||
"title": "Generate ${module_name} API documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"meta": {
|
||||
"type": "swagger-module-doc",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"module": "${module_name}",
|
||||
"endpoint_count": "${endpoint_count}"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Complete documentation for all endpoints in this module",
|
||||
"Each endpoint: description, method, URL, parameters, responses",
|
||||
"Include success and failure response examples",
|
||||
"Mark API version and last update time"
|
||||
],
|
||||
"focus_paths": ["${module_source_paths}"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_module_endpoints",
|
||||
"action": "Load module endpoint information",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/swagger-planning-data.json | jq '.api_structure.modules[] | select(.name == \"${module_name}\")')"
|
||||
],
|
||||
"output_to": "module_endpoints"
|
||||
},
|
||||
{
|
||||
"step": "read_source_files",
|
||||
"action": "Read module source files",
|
||||
"commands": [
|
||||
"bash(cat ${module_source_files})"
|
||||
],
|
||||
"output_to": "source_code"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate module API documentation",
|
||||
"description": "Generate complete API documentation for ${module_name}",
|
||||
"cli_prompt": "PURPOSE: Generate complete RESTful API documentation for ${module_name} module\nTASK:\n• Create module overview: purpose, use cases, prerequisites\n• Generate endpoint index: grouped by functionality\n• For each endpoint document:\n - Functional description: purpose and business context\n - Request method: GET/POST/PUT/DELETE\n - URL path: complete API path\n - Request headers: Authorization and other required headers\n - Path parameters: {id} and other path variables\n - Query parameters: pagination, filters, etc.\n - Request body: JSON Schema format\n - Response body: success and error responses\n - Field description table: type, required, example, description\n• Add usage examples: cURL, JavaScript, Python\n• Add version info: v1.0.0, last updated date\nMODE: write\nCONTEXT: @[module_endpoints] @[source_code]\nEXPECTED: Complete module API documentation in {lang} with all endpoints fully documented\nCONSTRAINTS: RESTful standards | Include all response codes\n--rule documentation-swagger-api",
|
||||
"output": "${module_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/${module_dir}/${module_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: API Overview and Navigation
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${overview_task_id}",
|
||||
"title": "Generate API overview and navigation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "...", "IMPL-${last_module_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-overview",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_all_docs",
|
||||
"command": "bash(find .workflow/docs/${project_name}/api -type f -name '*.md' ! -path '*/{overview_dir}/*' | xargs cat)",
|
||||
"output_to": "all_module_docs"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate API overview",
|
||||
"cli_prompt": "PURPOSE: Generate API overview document with navigation and quick start guide\nTASK:\n• Create introduction: system features, tech stack, version\n• Write quick start guide: authentication, first request example\n• Build module navigation: categorized links to all modules\n• Document environment configuration: development, staging, production\n• List SDKs and tools: client libraries, Postman collection\nMODE: write\nCONTEXT: @[all_module_docs] @.workflow/docs/${project_name}/api/swagger.yaml\nEXPECTED: Complete API overview in {lang} with navigation links\nCONSTRAINTS: Clear structure | Quick start focus\n--rule development-feature",
|
||||
"output": "README.md"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{overview_dir}/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 4: Validation Tasks
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-${test_task_id}",
|
||||
"title": "API endpoint validation tests",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-${overview_task_id}"],
|
||||
"meta": {
|
||||
"type": "swagger-validation",
|
||||
"agent": "@test-fix-agent",
|
||||
"tool": "codex"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Validate accessibility of all endpoints",
|
||||
"Test various boundary conditions",
|
||||
"Verify exception handling"
|
||||
]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_swagger_spec",
|
||||
"command": "bash(cat .workflow/docs/${project_name}/api/swagger.yaml)",
|
||||
"output_to": "swagger_spec"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate test report",
|
||||
"cli_prompt": "PURPOSE: Generate comprehensive API test validation report\nTASK:\n• Document test environment configuration\n• Calculate endpoint coverage statistics\n• Report test results: pass/fail counts\n• Document boundary tests: parameter limits, null values, special characters\n• Document exception tests: auth failures, permission denied, resource not found\n• List issues found with recommendations\nMODE: write\nCONTEXT: @[swagger_spec]\nEXPECTED: Complete test report in {lang} with detailed results\nCONSTRAINTS: Include test cases | Clear pass/fail status\n--rule development-tests",
|
||||
"output": "{test_doc_name}"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${project_name}/api/{test_dir}/{test_doc_name}"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Language-Specific Directory Mapping
|
||||
|
||||
| Component | --lang zh | --lang en |
|
||||
|-----------|-----------|-----------|
|
||||
| Overview dir | 概述 | overview |
|
||||
| Auth doc | 认证说明.md | authentication.md |
|
||||
| Error doc | 错误码规范.md | error-codes.md |
|
||||
| Changelog | 版本历史.md | changelog.md |
|
||||
| Users module | 用户模块 | users |
|
||||
| Orders module | 订单模块 | orders |
|
||||
| Products module | 商品模块 | products |
|
||||
| Test dir | 测试报告 | test-reports |
|
||||
| API test doc | 接口测试.md | api-tests.md |
|
||||
| Boundary test doc | 边界测试.md | boundary-tests.md |
|
||||
|
||||
## API Documentation Template
|
||||
|
||||
### Single Endpoint Format
|
||||
|
||||
Each endpoint must include:
|
||||
|
||||
```markdown
|
||||
### Get User Details
|
||||
|
||||
**Description**: Retrieve detailed user information by ID, including profile and permissions.
|
||||
|
||||
**Endpoint Info**:
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Method | GET |
|
||||
| URL | `/api/v1/users/{id}` |
|
||||
| Version | v1.0.0 |
|
||||
| Updated | 2025-01-01 |
|
||||
| Auth | Bearer Token |
|
||||
| Permission | user / admin |
|
||||
|
||||
**Request Headers**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| Authorization | string | Yes | `Bearer eyJhbGc...` | JWT Token |
|
||||
| Content-Type | string | No | `application/json` | Request content type |
|
||||
|
||||
**Path Parameters**:
|
||||
|
||||
| Field | Type | Required | Example | Description |
|
||||
|-------|------|----------|---------|-------------|
|
||||
| id | string | Yes | `usr_123456` | Unique user identifier |
|
||||
|
||||
**Query Parameters**:
|
||||
|
||||
| Field | Type | Required | Default | Example | Description |
|
||||
|-------|------|----------|---------|---------|-------------|
|
||||
| include | string | No | - | `roles,permissions` | Related data to include |
|
||||
|
||||
**Success Response** (200 OK):
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "usr_123456",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"status": "active",
|
||||
"roles": ["user"],
|
||||
"created_at": "2025-01-01T00:00:00Z",
|
||||
"updated_at": "2025-01-01T00:00:00Z"
|
||||
},
|
||||
"timestamp": "2025-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Response Fields**:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| code | integer | Business status code, 0 = success |
|
||||
| message | string | Response message |
|
||||
| data.id | string | Unique user identifier |
|
||||
| data.email | string | User email address |
|
||||
| data.name | string | User display name |
|
||||
| data.status | string | User status: active/inactive/suspended |
|
||||
| data.roles | array | User role list |
|
||||
| data.created_at | string | Creation timestamp (ISO 8601) |
|
||||
| data.updated_at | string | Last update timestamp (ISO 8601) |
|
||||
|
||||
**Error Responses**:
|
||||
|
||||
| Status | Code | Message | Possible Cause |
|
||||
|--------|------|---------|----------------|
|
||||
| 401 | AUTH_001 | Invalid or expired token | Token format error or expired |
|
||||
| 403 | AUTH_003 | Insufficient permissions | No access to this user info |
|
||||
| 404 | USER_001 | User not found | User ID doesn't exist or deleted |
|
||||
|
||||
**Examples**:
|
||||
|
||||
```bash
|
||||
# cURL
|
||||
curl -X GET "https://api.example.com/api/v1/users/usr_123456" \
|
||||
-H "Authorization: Bearer eyJhbGc..." \
|
||||
-H "Content-Type: application/json"
|
||||
```
|
||||
|
||||
```javascript
|
||||
// JavaScript (fetch)
|
||||
const response = await fetch('https://api.example.com/api/v1/users/usr_123456', {
|
||||
method: 'GET',
|
||||
headers: {
|
||||
'Authorization': 'Bearer eyJhbGc...',
|
||||
'Content-Type': 'application/json'
|
||||
}
|
||||
});
|
||||
const data = await response.json();
|
||||
```
|
||||
```
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/active/
|
||||
└── WFS-swagger-{timestamp}/
|
||||
├── workflow-session.json
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .process/
|
||||
│ └── swagger-planning-data.json
|
||||
└── .task/
|
||||
├── IMPL-001.json # OpenAPI spec
|
||||
├── IMPL-002.json # Security config
|
||||
├── IMPL-003.json # Error codes
|
||||
├── IMPL-004.json # Module 1 API
|
||||
├── ...
|
||||
├── IMPL-N+1.json # API overview
|
||||
└── IMPL-N+2.json # Validation tests
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
|
||||
```bash
|
||||
# Execute entire workflow
|
||||
/workflow:execute
|
||||
|
||||
# Specify session
|
||||
/workflow:execute --resume-session="WFS-swagger-yyyymmdd-hhmmss"
|
||||
|
||||
# Single task execution
|
||||
/task:execute IMPL-001
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/workflow:execute` - Execute documentation tasks
|
||||
- `/workflow:status` - View task progress
|
||||
- `/workflow:session:complete` - Mark session complete
|
||||
- `/memory:docs` - General documentation workflow
|
||||
@@ -1,310 +0,0 @@
|
||||
---
|
||||
name: tech-research-rules
|
||||
description: "3-phase orchestrator: extract tech stack → Exa research → generate path-conditional rules (auto-loaded by Claude Code)"
|
||||
argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Tech Stack Rules Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Purpose**: Generate multi-layered, path-conditional rules that Claude Code automatically loads based on file context.
|
||||
|
||||
**Output Structure**:
|
||||
```
|
||||
.claude/rules/tech/{tech-stack}/
|
||||
├── core.md # paths: **/*.{ext} - Core principles
|
||||
├── patterns.md # paths: src/**/*.{ext} - Implementation patterns
|
||||
├── testing.md # paths: **/*.{test,spec}.{ext} - Testing rules
|
||||
├── config.md # paths: *.config.* - Configuration rules
|
||||
├── api.md # paths: **/api/**/* - API rules (backend only)
|
||||
├── components.md # paths: **/components/**/* - Component rules (frontend only)
|
||||
└── metadata.json # Generation metadata
|
||||
```
|
||||
|
||||
**Templates Location**: `~/.claude/workflows/cli-templates/prompts/rules/`
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization
|
||||
2. **Path-Conditional Output**: Every rule file includes `paths` frontmatter
|
||||
3. **Template-Driven**: Agent reads templates before generating content
|
||||
4. **Agent Produces Files**: Agent writes all rule files directly
|
||||
5. **No Manual Loading**: Rules auto-activate when Claude works with matching files
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Prepare Context & Detect Tech Stack
|
||||
|
||||
**Goal**: Detect input mode, extract tech stack info, determine file extensions
|
||||
|
||||
**Input Mode Detection**:
|
||||
```bash
|
||||
input="$1"
|
||||
|
||||
if [[ "$input" == WFS-* ]]; then
|
||||
MODE="session"
|
||||
SESSION_ID="$input"
|
||||
# Read workflow-session.json to extract tech stack
|
||||
else
|
||||
MODE="direct"
|
||||
TECH_STACK_NAME="$input"
|
||||
fi
|
||||
```
|
||||
|
||||
**Tech Stack Analysis**:
|
||||
```javascript
|
||||
// Decompose composite tech stacks
|
||||
// "typescript-react-nextjs" → ["typescript", "react", "nextjs"]
|
||||
|
||||
const TECH_EXTENSIONS = {
|
||||
"typescript": "{ts,tsx}",
|
||||
"javascript": "{js,jsx}",
|
||||
"python": "py",
|
||||
"rust": "rs",
|
||||
"go": "go",
|
||||
"java": "java",
|
||||
"csharp": "cs",
|
||||
"ruby": "rb",
|
||||
"php": "php"
|
||||
};
|
||||
|
||||
const FRAMEWORK_TYPE = {
|
||||
"react": "frontend",
|
||||
"vue": "frontend",
|
||||
"angular": "frontend",
|
||||
"nextjs": "fullstack",
|
||||
"nuxt": "fullstack",
|
||||
"fastapi": "backend",
|
||||
"express": "backend",
|
||||
"django": "backend",
|
||||
"rails": "backend"
|
||||
};
|
||||
```
|
||||
|
||||
**Check Existing Rules**:
|
||||
```bash
|
||||
normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
|
||||
rules_dir=".claude/rules/tech/${normalized_name}"
|
||||
existing_count=$(find "${rules_dir}" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Skip Decision**:
|
||||
- If `existing_count > 0` AND no `--regenerate` → `SKIP_GENERATION = true`
|
||||
- If `--regenerate` → Delete existing and regenerate
|
||||
|
||||
**Output Variables**:
|
||||
- `TECH_STACK_NAME`: Normalized name
|
||||
- `PRIMARY_LANG`: Primary language
|
||||
- `FILE_EXT`: File extension pattern
|
||||
- `FRAMEWORK_TYPE`: frontend | backend | fullstack | library
|
||||
- `COMPONENTS`: Array of tech components
|
||||
- `SKIP_GENERATION`: Boolean
|
||||
|
||||
**TodoWrite**: Mark phase 1 completed
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Agent Produces Path-Conditional Rules
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Delegate to agent for Exa research and rule file generation
|
||||
|
||||
**Template Files**:
|
||||
```
|
||||
~/.claude/workflows/cli-templates/prompts/rules/
|
||||
├── tech-rules-agent-prompt.txt # Agent instructions
|
||||
├── rule-core.txt # Core principles template
|
||||
├── rule-patterns.txt # Implementation patterns template
|
||||
├── rule-testing.txt # Testing rules template
|
||||
├── rule-config.txt # Configuration rules template
|
||||
├── rule-api.txt # API rules template (backend)
|
||||
└── rule-components.txt # Component rules template (frontend)
|
||||
```
|
||||
|
||||
**Agent Task**:
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
description: `Generate tech stack rules: ${TECH_STACK_NAME}`,
|
||||
prompt: `
|
||||
You are generating path-conditional rules for Claude Code.
|
||||
|
||||
## Context
|
||||
- Tech Stack: ${TECH_STACK_NAME}
|
||||
- Primary Language: ${PRIMARY_LANG}
|
||||
- File Extensions: ${FILE_EXT}
|
||||
- Framework Type: ${FRAMEWORK_TYPE}
|
||||
- Components: ${JSON.stringify(COMPONENTS)}
|
||||
- Output Directory: .claude/rules/tech/${TECH_STACK_NAME}/
|
||||
|
||||
## Instructions
|
||||
|
||||
Read the agent prompt template for detailed instructions.
|
||||
Use --rule rules-tech-rules-agent-prompt to load the template automatically.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
1. Execute Exa research queries (see agent prompt)
|
||||
2. Read each rule template
|
||||
3. Generate rule files following template structure
|
||||
4. Write files to output directory
|
||||
5. Write metadata.json
|
||||
6. Report completion
|
||||
|
||||
## Variable Substitutions
|
||||
|
||||
Replace in templates:
|
||||
- {TECH_STACK_NAME} → ${TECH_STACK_NAME}
|
||||
- {PRIMARY_LANG} → ${PRIMARY_LANG}
|
||||
- {FILE_EXT} → ${FILE_EXT}
|
||||
- {FRAMEWORK_TYPE} → ${FRAMEWORK_TYPE}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- 4-6 rule files written with proper `paths` frontmatter
|
||||
- metadata.json written
|
||||
- Agent reports files created
|
||||
|
||||
**TodoWrite**: Mark phase 2 completed
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Verify & Report
|
||||
|
||||
**Goal**: Verify generated files and provide usage summary
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Files**:
|
||||
```bash
|
||||
find ".claude/rules/tech/${TECH_STACK_NAME}" -name "*.md" -type f
|
||||
```
|
||||
|
||||
2. **Validate Frontmatter**:
|
||||
```bash
|
||||
head -5 ".claude/rules/tech/${TECH_STACK_NAME}/core.md"
|
||||
```
|
||||
|
||||
3. **Read Metadata**:
|
||||
```javascript
|
||||
Read(`.claude/rules/tech/${TECH_STACK_NAME}/metadata.json`)
|
||||
```
|
||||
|
||||
4. **Generate Summary Report**:
|
||||
```
|
||||
Tech Stack Rules Generated
|
||||
|
||||
Tech Stack: {TECH_STACK_NAME}
|
||||
Location: .claude/rules/tech/{TECH_STACK_NAME}/
|
||||
|
||||
Files Created:
|
||||
├── core.md → paths: **/*.{ext}
|
||||
├── patterns.md → paths: src/**/*.{ext}
|
||||
├── testing.md → paths: **/*.{test,spec}.{ext}
|
||||
├── config.md → paths: *.config.*
|
||||
├── api.md → paths: **/api/**/* (if backend)
|
||||
└── components.md → paths: **/components/**/* (if frontend)
|
||||
|
||||
Auto-Loading:
|
||||
- Rules apply automatically when editing matching files
|
||||
- No manual loading required
|
||||
|
||||
Example Activation:
|
||||
- Edit src/components/Button.tsx → core.md + patterns.md + components.md
|
||||
- Edit tests/api.test.ts → core.md + testing.md
|
||||
- Edit package.json → config.md
|
||||
```
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
---
|
||||
|
||||
## Path Pattern Reference
|
||||
|
||||
| Pattern | Matches |
|
||||
|---------|---------|
|
||||
| `**/*.ts` | All .ts files |
|
||||
| `src/**/*` | All files under src/ |
|
||||
| `*.config.*` | Config files in root |
|
||||
| `**/*.{ts,tsx}` | .ts and .tsx files |
|
||||
|
||||
| Tech Stack | Core Pattern | Test Pattern |
|
||||
|------------|--------------|--------------|
|
||||
| TypeScript | `**/*.{ts,tsx}` | `**/*.{test,spec}.{ts,tsx}` |
|
||||
| Python | `**/*.py` | `**/test_*.py, **/*_test.py` |
|
||||
| Rust | `**/*.rs` | `**/tests/**/*.rs` |
|
||||
| Go | `**/*.go` | `**/*_test.go` |
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:tech-research [session-id | "tech-stack-name"] [--regenerate]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **session-id**: `WFS-*` format - Extract from workflow session
|
||||
- **tech-stack-name**: Direct input - `"typescript"`, `"typescript-react"`
|
||||
- **--regenerate**: Force regenerate existing rules
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Single Language
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/typescript/` with 4 rule files
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript-react"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/typescript-react/` with 5 rule files (includes components.md)
|
||||
|
||||
### Backend Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "python-fastapi"
|
||||
```
|
||||
|
||||
**Output**: `.claude/rules/tech/python-fastapi/` with 5 rule files (includes api.md)
|
||||
|
||||
### From Session
|
||||
|
||||
```bash
|
||||
/memory:tech-research WFS-user-auth-20251104
|
||||
```
|
||||
|
||||
**Workflow**: Extract tech stack from session → Generate rules
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Rules vs SKILL
|
||||
|
||||
| Aspect | SKILL Memory | Rules |
|
||||
|--------|--------------|-------|
|
||||
| Loading | Manual: `Skill("tech")` | Automatic by path |
|
||||
| Scope | All files when loaded | Only matching files |
|
||||
| Granularity | Monolithic packages | Per-file-type |
|
||||
| Context | Full package | Only relevant rules |
|
||||
|
||||
**When to Use**:
|
||||
- **Rules**: Tech stack conventions per file type
|
||||
- **SKILL**: Reference docs, APIs, examples for manual lookup
|
||||
332
.claude/commands/memory/tips.md
Normal file
332
.claude/commands/memory/tips.md
Normal file
@@ -0,0 +1,332 @@
|
||||
---
|
||||
name: tips
|
||||
description: Quick note-taking command to capture ideas, snippets, reminders, and insights for later reference
|
||||
argument-hint: "<note content> [--tag <tag1,tag2>] [--context <context>]"
|
||||
allowed-tools: mcp__ccw-tools__core_memory(*), Read(*)
|
||||
examples:
|
||||
- /memory:tips "Remember to use Redis for rate limiting"
|
||||
- /memory:tips "Auth pattern: JWT with refresh tokens" --tag architecture,auth
|
||||
- /memory:tips "Bug: memory leak in WebSocket handler after 24h" --context websocket-service
|
||||
- /memory:tips "Performance: lazy loading reduced bundle by 40%" --tag performance
|
||||
---
|
||||
|
||||
# Memory Tips Command (/memory:tips)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The `memory:tips` command provides **quick note-taking** for capturing:
|
||||
- Quick ideas and insights
|
||||
- Code snippets and patterns
|
||||
- Reminders and follow-ups
|
||||
- Bug notes and debugging hints
|
||||
- Performance observations
|
||||
- Architecture decisions
|
||||
- Library/tool recommendations
|
||||
|
||||
**Core Philosophy**:
|
||||
- **Speed First**: Minimal friction for capturing thoughts
|
||||
- **Searchable**: Tagged for easy retrieval
|
||||
- **Context-Aware**: Optional context linking
|
||||
- **Lightweight**: No complex session analysis
|
||||
|
||||
## 2. Parameters
|
||||
|
||||
- `<note content>` (Required): The tip/note content to save
|
||||
- `--tag <tags>` (Optional): Comma-separated tags for categorization
|
||||
- `--context <context>` (Optional): Related context (file, module, feature)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
/memory:tips "Use Zod for runtime validation - better DX than class-validator"
|
||||
/memory:tips "Redis connection pool: max 10, min 2" --tag config,redis
|
||||
/memory:tips "Fix needed: race condition in payment processor" --tag bug,payment --context src/payments
|
||||
```
|
||||
|
||||
## 3. Structured Output Format
|
||||
|
||||
```markdown
|
||||
## Tip ID
|
||||
TIP-YYYYMMDD-HHMMSS
|
||||
|
||||
## Timestamp
|
||||
YYYY-MM-DD HH:MM:SS
|
||||
|
||||
## Project Root
|
||||
[Absolute path to project root, e.g., D:\Claude_dms3]
|
||||
|
||||
## Content
|
||||
[The tip/note content exactly as provided]
|
||||
|
||||
## Tags
|
||||
[Comma-separated tags, or (none)]
|
||||
|
||||
## Context
|
||||
[Optional context linking - file, module, or feature reference]
|
||||
|
||||
## Session Link
|
||||
[WFS-ID if workflow session active, otherwise (none)]
|
||||
|
||||
## Auto-Detected Context
|
||||
[Files/topics from current conversation if relevant]
|
||||
```
|
||||
|
||||
## 4. Field Definitions
|
||||
|
||||
| Field | Purpose | Example |
|
||||
|-------|---------|---------|
|
||||
| **Tip ID** | Unique identifier with timestamp | TIP-20260128-143052 |
|
||||
| **Timestamp** | When tip was created | 2026-01-28 14:30:52 |
|
||||
| **Project Root** | Current project path | D:\Claude_dms3 |
|
||||
| **Content** | The actual tip/note | "Use Redis for rate limiting" |
|
||||
| **Tags** | Categorization labels | architecture, auth, performance |
|
||||
| **Context** | Related code/feature | src/auth/**, payment-module |
|
||||
| **Session Link** | Link to workflow session | WFS-auth-20260128 |
|
||||
| **Auto-Detected Context** | Files from conversation | src/api/handler.ts |
|
||||
|
||||
## 5. Execution Flow
|
||||
|
||||
### Step 1: Parse Arguments
|
||||
|
||||
```javascript
|
||||
const parseTipsCommand = (input) => {
|
||||
// Extract note content (everything before flags)
|
||||
const contentMatch = input.match(/^"([^"]+)"|^([^\s-]+)/);
|
||||
const content = contentMatch ? (contentMatch[1] || contentMatch[2]) : '';
|
||||
|
||||
// Extract tags
|
||||
const tagsMatch = input.match(/--tag\s+([^\s-]+)/);
|
||||
const tags = tagsMatch ? tagsMatch[1].split(',').map(t => t.trim()) : [];
|
||||
|
||||
// Extract context
|
||||
const contextMatch = input.match(/--context\s+([^\s-]+)/);
|
||||
const context = contextMatch ? contextMatch[1] : '';
|
||||
|
||||
return { content, tags, context };
|
||||
};
|
||||
```
|
||||
|
||||
### Step 2: Gather Context
|
||||
|
||||
```javascript
|
||||
const gatherTipContext = async () => {
|
||||
// Get project root
|
||||
const projectRoot = process.cwd(); // or detect from environment
|
||||
|
||||
// Get current session if active
|
||||
const manifest = await mcp__ccw-tools__session_manager({
|
||||
operation: "list",
|
||||
location: "active"
|
||||
});
|
||||
const sessionId = manifest.sessions?.[0]?.id || null;
|
||||
|
||||
// Auto-detect files from recent conversation
|
||||
const recentFiles = extractRecentFilesFromConversation(); // Last 5 messages
|
||||
|
||||
return {
|
||||
projectRoot,
|
||||
sessionId,
|
||||
autoDetectedContext: recentFiles
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
### Step 3: Generate Structured Text
|
||||
|
||||
```javascript
|
||||
const generateTipText = (parsed, context) => {
|
||||
const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
|
||||
const tipId = `TIP-${new Date().toISOString().slice(0,10).replace(/-/g, '')}-${new Date().toTimeString().slice(0,8).replace(/:/g, '')}`;
|
||||
|
||||
return `## Tip ID
|
||||
${tipId}
|
||||
|
||||
## Timestamp
|
||||
${timestamp}
|
||||
|
||||
## Project Root
|
||||
${context.projectRoot}
|
||||
|
||||
## Content
|
||||
${parsed.content}
|
||||
|
||||
## Tags
|
||||
${parsed.tags.length > 0 ? parsed.tags.join(', ') : '(none)'}
|
||||
|
||||
## Context
|
||||
${parsed.context || '(none)'}
|
||||
|
||||
## Session Link
|
||||
${context.sessionId || '(none)'}
|
||||
|
||||
## Auto-Detected Context
|
||||
${context.autoDetectedContext.length > 0
|
||||
? context.autoDetectedContext.map(f => `- ${f}`).join('\n')
|
||||
: '(none)'}`;
|
||||
};
|
||||
```
|
||||
|
||||
### Step 4: Save to Core Memory
|
||||
|
||||
```javascript
|
||||
mcp__ccw-tools__core_memory({
|
||||
operation: "import",
|
||||
text: structuredText
|
||||
})
|
||||
```
|
||||
|
||||
**Response Format**:
|
||||
```json
|
||||
{
|
||||
"operation": "import",
|
||||
"id": "CMEM-YYYYMMDD-HHMMSS",
|
||||
"message": "Created memory: CMEM-YYYYMMDD-HHMMSS"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Confirm to User
|
||||
|
||||
```
|
||||
✓ Tip saved successfully
|
||||
|
||||
ID: CMEM-YYYYMMDD-HHMMSS
|
||||
Tags: architecture, auth
|
||||
Context: src/auth/**
|
||||
|
||||
To retrieve: /memory:search "auth patterns"
|
||||
Or via MCP: core_memory(operation="search", query="auth")
|
||||
```
|
||||
|
||||
## 6. Tag Categories (Suggested)
|
||||
|
||||
**Technical**:
|
||||
- `architecture` - Design decisions and patterns
|
||||
- `performance` - Optimization insights
|
||||
- `security` - Security considerations
|
||||
- `bug` - Bug notes and fixes
|
||||
- `config` - Configuration settings
|
||||
- `api` - API design patterns
|
||||
|
||||
**Development**:
|
||||
- `testing` - Test strategies and patterns
|
||||
- `debugging` - Debugging techniques
|
||||
- `refactoring` - Refactoring notes
|
||||
- `documentation` - Doc improvements
|
||||
|
||||
**Domain Specific**:
|
||||
- `auth` - Authentication/authorization
|
||||
- `database` - Database patterns
|
||||
- `frontend` - UI/UX patterns
|
||||
- `backend` - Backend logic
|
||||
- `devops` - Infrastructure and deployment
|
||||
|
||||
**Organizational**:
|
||||
- `reminder` - Follow-up items
|
||||
- `research` - Research findings
|
||||
- `idea` - Feature ideas
|
||||
- `review` - Code review notes
|
||||
|
||||
## 7. Search Integration
|
||||
|
||||
Tips can be retrieved using:
|
||||
|
||||
```bash
|
||||
# Via command (if /memory:search exists)
|
||||
/memory:search "rate limiting"
|
||||
|
||||
# Via MCP tool
|
||||
mcp__ccw-tools__core_memory({
|
||||
operation: "search",
|
||||
query: "rate limiting",
|
||||
source_type: "core_memory",
|
||||
top_k: 10
|
||||
})
|
||||
|
||||
# Via CLI
|
||||
ccw core-memory search --query "rate limiting" --top-k 10
|
||||
```
|
||||
|
||||
## 8. Quality Checklist
|
||||
|
||||
Before saving:
|
||||
- [ ] Content is clear and actionable
|
||||
- [ ] Tags are relevant and consistent
|
||||
- [ ] Context provides enough reference
|
||||
- [ ] Auto-detected context is accurate
|
||||
- [ ] Project root is absolute path
|
||||
- [ ] Timestamp is properly formatted
|
||||
|
||||
## 9. Best Practices
|
||||
|
||||
### Good Tips Examples
|
||||
|
||||
✅ **Specific and Actionable**:
|
||||
```
|
||||
"Use connection pooling for Redis: { max: 10, min: 2, acquireTimeoutMillis: 30000 }"
|
||||
--tag config,redis
|
||||
```
|
||||
|
||||
✅ **With Context**:
|
||||
```
|
||||
"Auth middleware must validate both access and refresh tokens"
|
||||
--tag security,auth --context src/middleware/auth.ts
|
||||
```
|
||||
|
||||
✅ **Problem + Solution**:
|
||||
```
|
||||
"Memory leak fixed by unsubscribing event listeners in componentWillUnmount"
|
||||
--tag bug,react --context src/components/Chat.tsx
|
||||
```
|
||||
|
||||
### Poor Tips Examples
|
||||
|
||||
❌ **Too Vague**:
|
||||
```
|
||||
"Fix the bug" --tag bug
|
||||
```
|
||||
|
||||
❌ **Too Long** (use /memory:compact instead):
|
||||
```
|
||||
"Here's the complete implementation plan for the entire auth system... [3 paragraphs]"
|
||||
```
|
||||
|
||||
❌ **No Context**:
|
||||
```
|
||||
"Remember to update this later"
|
||||
```
|
||||
|
||||
## 10. Use Cases
|
||||
|
||||
### During Development
|
||||
```bash
|
||||
/memory:tips "JWT secret must be 256-bit minimum" --tag security,auth
|
||||
/memory:tips "Use debounce (300ms) for search input" --tag performance,ux
|
||||
```
|
||||
|
||||
### After Bug Fixes
|
||||
```bash
|
||||
/memory:tips "Race condition in payment: lock with Redis SETNX" --tag bug,payment
|
||||
```
|
||||
|
||||
### Code Review Insights
|
||||
```bash
|
||||
/memory:tips "Prefer early returns over nested ifs" --tag style,readability
|
||||
```
|
||||
|
||||
### Architecture Decisions
|
||||
```bash
|
||||
/memory:tips "Chose PostgreSQL over MongoDB for ACID compliance" --tag architecture,database
|
||||
```
|
||||
|
||||
### Library Recommendations
|
||||
```bash
|
||||
/memory:tips "Zod > Yup for TypeScript validation - better type inference" --tag library,typescript
|
||||
```
|
||||
|
||||
## 11. Notes
|
||||
|
||||
- **Frequency**: Use liberally - capture all valuable insights
|
||||
- **Retrieval**: Search by tags, content, or context
|
||||
- **Lifecycle**: Tips persist across sessions
|
||||
- **Organization**: Tags enable filtering and categorization
|
||||
- **Integration**: Can reference tips in later workflows
|
||||
- **Lightweight**: No complex session analysis required
|
||||
@@ -1,517 +0,0 @@
|
||||
---
|
||||
name: workflow-skill-memory
|
||||
description: Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts)
|
||||
argument-hint: "session <session-id> | all"
|
||||
allowed-tools: Task(*), TodoWrite(*), Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
# Workflow SKILL Memory Generator
|
||||
|
||||
## Overview
|
||||
|
||||
Generate SKILL package from archived workflow sessions using agent-driven analysis. Supports single-session incremental updates or parallel processing of all sessions.
|
||||
|
||||
**Scope**: Only processes WFS-* workflow sessions. Other session types (e.g., doc sessions) are automatically ignored.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/memory:workflow-skill-memory session WFS-<session-id> # Process single WFS session
|
||||
/memory:workflow-skill-memory all # Process all WFS sessions in parallel
|
||||
```
|
||||
|
||||
## Execution Modes
|
||||
|
||||
### Mode 1: Single Session (`session <session-id>`)
|
||||
|
||||
**Purpose**: Incremental update - process one archived session and merge into existing SKILL package
|
||||
|
||||
**Workflow**:
|
||||
1. **Validate session**: Check if session exists in `.workflow/.archives/{session-id}/`
|
||||
2. **Invoke agent**: Call `universal-executor` to analyze session and update SKILL documents
|
||||
3. **Agent tasks**:
|
||||
- Read session data from `.workflow/.archives/{session-id}/`
|
||||
- Extract lessons, conflicts, and outcomes
|
||||
- Use Gemini for intelligent aggregation (optional)
|
||||
- Update or create SKILL documents using templates
|
||||
- Regenerate SKILL.md index
|
||||
|
||||
**Command Example**:
|
||||
```bash
|
||||
/memory:workflow-skill-memory session WFS-user-auth
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
Session WFS-user-auth processed
|
||||
Updated:
|
||||
- sessions-timeline.md (1 session added)
|
||||
- lessons-learned.md (3 lessons merged)
|
||||
- conflict-patterns.md (1 conflict added)
|
||||
- SKILL.md (index regenerated)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mode 2: All Sessions (`all`)
|
||||
|
||||
**Purpose**: Full regeneration - process all archived sessions in parallel for complete SKILL package
|
||||
|
||||
**Workflow**:
|
||||
1. **List sessions**: Read manifest.json to get all archived session IDs
|
||||
2. **Parallel invocation**: Launch multiple `universal-executor` agents in parallel (one per session)
|
||||
3. **Agent coordination**:
|
||||
- Each agent processes one session independently
|
||||
- Agents use Gemini for analysis
|
||||
- Agents collect data into JSON (no direct file writes)
|
||||
- Final aggregator agent merges results and generates SKILL documents
|
||||
|
||||
**Command Example**:
|
||||
```bash
|
||||
/memory:workflow-skill-memory all
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
All sessions processed in parallel
|
||||
Sessions: 8 total
|
||||
Updated:
|
||||
- sessions-timeline.md (8 sessions)
|
||||
- lessons-learned.md (24 lessons aggregated)
|
||||
- conflict-patterns.md (12 conflicts documented)
|
||||
- SKILL.md (index regenerated)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Flow
|
||||
|
||||
### Phase 1: Validation and Setup
|
||||
|
||||
**Step 1.1: Parse Command Arguments**
|
||||
|
||||
Extract mode and session ID:
|
||||
```javascript
|
||||
if (args === "all") {
|
||||
mode = "all"
|
||||
} else if (args.startsWith("session ")) {
|
||||
mode = "session"
|
||||
session_id = args.replace("session ", "").trim()
|
||||
} else {
|
||||
ERROR = "Invalid arguments. Usage: session <session-id> | all"
|
||||
EXIT
|
||||
}
|
||||
```
|
||||
|
||||
**Step 1.2: Validate Archive Directory**
|
||||
```bash
|
||||
bash(test -d .workflow/.archives && echo "exists" || echo "missing")
|
||||
```
|
||||
|
||||
If missing, report error and exit.
|
||||
|
||||
**Step 1.3: Mode-Specific Validation**
|
||||
|
||||
**Single Session Mode**:
|
||||
```bash
|
||||
# Validate session ID format (must start with WFS-)
|
||||
if [[ ! "$session_id" =~ ^WFS- ]]; then
|
||||
ERROR = "Invalid session ID format. Only WFS-* sessions are supported"
|
||||
EXIT
|
||||
fi
|
||||
|
||||
# Check if session exists
|
||||
bash(test -d .workflow/.archives/{session_id} && echo "exists" || echo "missing")
|
||||
```
|
||||
|
||||
If missing, report error: "Session {session_id} not found in archives"
|
||||
|
||||
**All Sessions Mode**:
|
||||
```bash
|
||||
# Read manifest and filter only WFS- sessions
|
||||
bash(cat .workflow/.archives/manifest.json | jq -r '.archives[].session_id | select(startswith("WFS-"))')
|
||||
```
|
||||
|
||||
Store filtered session IDs in array. Ignore doc sessions and other non-WFS sessions.
|
||||
|
||||
**Step 1.4: TodoWrite Initialization**
|
||||
|
||||
**Single Session Mode**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Validate session existence", "status": "completed", "activeForm": "Validating session"},
|
||||
{"content": "Invoke agent to process session", "status": "in_progress", "activeForm": "Invoking agent"},
|
||||
{"content": "Verify SKILL package updated", "status": "pending", "activeForm": "Verifying update"}
|
||||
]})
|
||||
```
|
||||
|
||||
**All Sessions Mode**:
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Read manifest and list sessions", "status": "completed", "activeForm": "Reading manifest"},
|
||||
{"content": "Invoke agents in parallel", "status": "in_progress", "activeForm": "Invoking agents"},
|
||||
{"content": "Verify SKILL package regenerated", "status": "pending", "activeForm": "Verifying regeneration"}
|
||||
]})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Agent Invocation
|
||||
|
||||
#### Single Session Mode - Agent Task
|
||||
|
||||
Invoke `universal-executor` with session-specific task:
|
||||
|
||||
**Agent Prompt Structure**:
|
||||
```
|
||||
Task: Process Workflow Session for SKILL Package
|
||||
|
||||
Context:
|
||||
- Session ID: {session_id}
|
||||
- Session Path: .workflow/.archives/{session_id}/
|
||||
- Mode: Incremental update
|
||||
|
||||
Objectives:
|
||||
|
||||
1. Read session data:
|
||||
- workflow-session.json (metadata)
|
||||
- IMPL_PLAN.md (implementation summary)
|
||||
- TODO_LIST.md (if exists)
|
||||
- manifest.json entry for lessons
|
||||
|
||||
2. Extract key information:
|
||||
- Description, tags, metrics
|
||||
- Lessons (successes, challenges, watch_patterns)
|
||||
- Context package path (reference only)
|
||||
- Key outcomes from IMPL_PLAN
|
||||
|
||||
3. Use Gemini for aggregation (optional):
|
||||
Command pattern:
|
||||
ccw cli -p "
|
||||
PURPOSE: Extract lessons and conflicts from workflow session
|
||||
TASK:
|
||||
• Analyze IMPL_PLAN and lessons from manifest
|
||||
• Identify success patterns and challenges
|
||||
• Extract conflict patterns with resolutions
|
||||
• Categorize by functional domain
|
||||
MODE: analysis
|
||||
CONTEXT: @IMPL_PLAN.md @workflow-session.json
|
||||
EXPECTED: Structured lessons and conflicts in JSON format
|
||||
RULES: Template reference from skill-aggregation.txt
|
||||
" --tool gemini --mode analysis --cd .workflow/.archives/{session_id}
|
||||
|
||||
3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading):
|
||||
|
||||
Read skill-index.txt template Section: "Description Field Generation"
|
||||
|
||||
Execute command to get project root:
|
||||
```bash
|
||||
git rev-parse --show-toplevel # Example output: /d/Claude_dms3
|
||||
```
|
||||
|
||||
Apply description format:
|
||||
```
|
||||
Progressive workflow development history (located at {project_root}).
|
||||
Load this SKILL when continuing development, analyzing past implementations,
|
||||
or learning from workflow history, especially when no relevant context exists in memory.
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- [ ] Path uses forward slashes (not backslashes)
|
||||
- [ ] All three use cases present
|
||||
- [ ] Trigger optimization phrase included
|
||||
- [ ] Path is absolute (starts with / or drive letter)
|
||||
|
||||
4. Read templates for formatting guidance:
|
||||
- ~/.claude/workflows/cli-templates/prompts/workflow/skill-sessions-timeline.txt
|
||||
- ~/.claude/workflows/cli-templates/prompts/workflow/skill-lessons-learned.txt
|
||||
- ~/.claude/workflows/cli-templates/prompts/workflow/skill-conflict-patterns.txt
|
||||
- ~/.claude/workflows/cli-templates/prompts/workflow/skill-index.txt
|
||||
|
||||
**CRITICAL**: From skill-index.txt, read these sections:
|
||||
- "Description Field Generation" - Rules for generating description
|
||||
- "Variable Substitution Guide" - All required variables
|
||||
- "Generation Instructions" - Step-by-step generation process
|
||||
- "Validation Checklist" - Final validation steps
|
||||
|
||||
5. Update SKILL documents:
|
||||
- sessions-timeline.md: Append new session, update domain grouping
|
||||
- lessons-learned.md: Merge lessons into categories, update frequencies
|
||||
- conflict-patterns.md: Add conflicts, update recurring pattern frequencies
|
||||
- SKILL.md: Regenerate index with updated counts
|
||||
|
||||
**For SKILL.md generation**:
|
||||
- Follow "Generation Instructions" from skill-index.txt (Steps 1-7)
|
||||
- Use git command for project_root: `git rev-parse --show-toplevel`
|
||||
- Apply "Description Field Generation" rules
|
||||
- Validate using "Validation Checklist"
|
||||
- Increment version (patch level)
|
||||
|
||||
6. Return result JSON:
|
||||
{
|
||||
"status": "success",
|
||||
"session_id": "{session_id}",
|
||||
"updates": {
|
||||
"sessions_added": 1,
|
||||
"lessons_merged": count,
|
||||
"conflicts_added": count
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### All Sessions Mode - Parallel Agent Tasks
|
||||
|
||||
**Step 2.1: Launch parallel session analyzers**
|
||||
|
||||
Invoke multiple agents in parallel (one message with multiple Task calls):
|
||||
|
||||
**Per-Session Agent Prompt**:
|
||||
```
|
||||
Task: Extract Session Data for SKILL Package
|
||||
|
||||
Context:
|
||||
- Session ID: {session_id}
|
||||
- Mode: Parallel analysis (no direct file writes)
|
||||
|
||||
Objectives:
|
||||
|
||||
1. Read session data (same as single mode)
|
||||
|
||||
2. Extract key information (same as single mode)
|
||||
|
||||
3. Use Gemini for analysis (same as single mode)
|
||||
|
||||
4. Return structured data JSON:
|
||||
{
|
||||
"status": "success",
|
||||
"session_id": "{session_id}",
|
||||
"data": {
|
||||
"metadata": {
|
||||
"description": "...",
|
||||
"archived_at": "...",
|
||||
"tags": [...],
|
||||
"metrics": {...}
|
||||
},
|
||||
"lessons": {
|
||||
"successes": [...],
|
||||
"challenges": [...],
|
||||
"watch_patterns": [...]
|
||||
},
|
||||
"conflicts": [
|
||||
{
|
||||
"type": "architecture|dependencies|testing|performance",
|
||||
"pattern": "...",
|
||||
"resolution": "...",
|
||||
"code_impact": [...]
|
||||
}
|
||||
],
|
||||
"impl_summary": "First 200 chars of IMPL_PLAN",
|
||||
"context_package_path": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2.2: Aggregate results**
|
||||
|
||||
After all session agents complete, invoke aggregator agent:
|
||||
|
||||
**Aggregator Agent Prompt**:
|
||||
```
|
||||
Task: Aggregate Session Results and Generate SKILL Package
|
||||
|
||||
Context:
|
||||
- Mode: Full regeneration
|
||||
- Input: JSON results from {session_count} session agents
|
||||
|
||||
Objectives:
|
||||
|
||||
1. Aggregate all session data:
|
||||
- Collect metadata from all sessions
|
||||
- Merge lessons by category
|
||||
- Group conflicts by type
|
||||
- Sort sessions by date
|
||||
|
||||
2. Use Gemini for final aggregation:
|
||||
ccw cli -p "
|
||||
PURPOSE: Aggregate lessons and conflicts from all workflow sessions
|
||||
TASK:
|
||||
• Group successes by functional domain
|
||||
• Categorize challenges by severity (HIGH/MEDIUM/LOW)
|
||||
• Identify recurring conflict patterns
|
||||
• Calculate frequencies and prioritize
|
||||
MODE: analysis
|
||||
CONTEXT: [Provide aggregated JSON data]
|
||||
EXPECTED: Final aggregated structure for SKILL documents
|
||||
RULES: Template reference from skill-aggregation.txt
|
||||
" --tool gemini --mode analysis
|
||||
|
||||
3. Read templates for formatting (same 4 templates as single mode)
|
||||
|
||||
4. Generate all SKILL documents:
|
||||
- sessions-timeline.md (all sessions, sorted by date)
|
||||
- lessons-learned.md (aggregated lessons with frequencies)
|
||||
- conflict-patterns.md (recurring patterns with resolutions)
|
||||
- SKILL.md (index with progressive loading)
|
||||
|
||||
5. Write files to .claude/skills/workflow-progress/
|
||||
|
||||
6. Return result JSON:
|
||||
{
|
||||
"status": "success",
|
||||
"sessions_processed": count,
|
||||
"files_generated": ["SKILL.md", "sessions-timeline.md", ...],
|
||||
"summary": {
|
||||
"total_sessions": count,
|
||||
"functional_domains": [...],
|
||||
"date_range": "...",
|
||||
"lessons_count": count,
|
||||
"conflicts_count": count
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Verification
|
||||
|
||||
**Step 3.1: Check SKILL Package Files**
|
||||
```bash
|
||||
bash(ls -lh .claude/skills/workflow-progress/)
|
||||
```
|
||||
|
||||
Verify all 4 files exist:
|
||||
- SKILL.md
|
||||
- sessions-timeline.md
|
||||
- lessons-learned.md
|
||||
- conflict-patterns.md
|
||||
|
||||
**Step 3.2: TodoWrite Completion**
|
||||
|
||||
Mark all tasks as completed.
|
||||
|
||||
**Step 3.3: Display Summary**
|
||||
|
||||
**Single Session Mode**:
|
||||
```
|
||||
Session {session_id} processed successfully
|
||||
|
||||
Updated:
|
||||
- sessions-timeline.md
|
||||
- lessons-learned.md
|
||||
- conflict-patterns.md
|
||||
- SKILL.md
|
||||
|
||||
SKILL Location: .claude/skills/workflow-progress/SKILL.md
|
||||
```
|
||||
|
||||
**All Sessions Mode**:
|
||||
```
|
||||
All sessions processed in parallel
|
||||
|
||||
Sessions: {count} total
|
||||
Functional Domains: {domain_list}
|
||||
Date Range: {earliest} - {latest}
|
||||
|
||||
Generated:
|
||||
- sessions-timeline.md ({count} sessions)
|
||||
- lessons-learned.md ({lessons_count} lessons)
|
||||
- conflict-patterns.md ({conflicts_count} conflicts)
|
||||
- SKILL.md (4-level progressive loading)
|
||||
|
||||
SKILL Location: .claude/skills/workflow-progress/SKILL.md
|
||||
|
||||
Usage:
|
||||
- Level 0: Quick refresh (~2K tokens)
|
||||
- Level 1: Recent history (~8K tokens)
|
||||
- Level 2: Complete analysis (~25K tokens)
|
||||
- Level 3: Deep dive (~40K tokens)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Guidelines
|
||||
|
||||
### Agent Capabilities
|
||||
|
||||
**universal-executor agents can**:
|
||||
- Read files from `.workflow/.archives/`
|
||||
- Execute bash commands
|
||||
- Call Gemini CLI for intelligent analysis
|
||||
- Read template files for formatting guidance
|
||||
- Write SKILL package files (single mode) or return JSON (parallel mode)
|
||||
- Return structured results
|
||||
|
||||
### Gemini Usage Pattern
|
||||
|
||||
**When to use Gemini**:
|
||||
- Aggregating lessons from multiple sources
|
||||
- Identifying recurring patterns
|
||||
- Classifying conflicts by type and severity
|
||||
- Extracting structured data from IMPL_PLAN
|
||||
|
||||
**Fallback Strategy**: If Gemini fails or times out, use direct file parsing with structured extraction logic.
|
||||
|
||||
---
|
||||
|
||||
## Template System
|
||||
|
||||
### Template Files
|
||||
|
||||
All templates located in: `~/.claude/workflows/cli-templates/prompts/workflow/`
|
||||
|
||||
1. **skill-sessions-timeline.txt**: Format for sessions-timeline.md
|
||||
2. **skill-lessons-learned.txt**: Format for lessons-learned.md
|
||||
3. **skill-conflict-patterns.txt**: Format for conflict-patterns.md
|
||||
4. **skill-index.txt**: Format for SKILL.md index
|
||||
5. **skill-aggregation.txt**: Rules for Gemini aggregation (existing)
|
||||
|
||||
### Template Usage in Agent
|
||||
|
||||
**Agents read templates to understand**:
|
||||
- File structure and markdown format
|
||||
- Data sources (which files to read)
|
||||
- Update strategy (incremental vs full)
|
||||
- Formatting rules and conventions
|
||||
- Aggregation logic (for Gemini)
|
||||
|
||||
**Templates are NOT shown in this command documentation** - agents read them directly as needed.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Validation Errors
|
||||
- **No archives directory**: "Error: No workflow archives found at .workflow/.archives/"
|
||||
- **Invalid session ID format**: "Error: Invalid session ID format. Only WFS-* sessions are supported"
|
||||
- **Session not found**: "Error: Session {session_id} not found in archives"
|
||||
- **No WFS sessions in manifest**: "Error: No WFS-* workflow sessions found in manifest.json"
|
||||
|
||||
### Agent Errors
|
||||
- If agent fails, report error message from agent result
|
||||
- If Gemini times out, agents use fallback direct parsing
|
||||
- If template read fails, agents use inline format
|
||||
|
||||
### Recovery
|
||||
- Single session mode: Can be retried without affecting other sessions
|
||||
- All sessions mode: If one agent fails, others continue; retry failed sessions individually
|
||||
|
||||
|
||||
|
||||
## Integration
|
||||
|
||||
### Called by `/workflow:session:complete`
|
||||
|
||||
Automatically invoked after session archival:
|
||||
```bash
|
||||
SlashCommand(command="/memory:workflow-skill-memory session {session_id}")
|
||||
```
|
||||
|
||||
### Manual Invocation
|
||||
|
||||
Users can manually process sessions:
|
||||
```bash
|
||||
/memory:workflow-skill-memory session WFS-custom-feature # Single session
|
||||
/memory:workflow-skill-memory all # Full regeneration
|
||||
```
|
||||
Reference in New Issue
Block a user