mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
feat: 增强 command-guide skill 支持深度命令分析和 CLI 辅助查询
新增 Mode 6: 深度命令分析 - 创建 reference 备份目录（80个文档：11 agents + 69 commands） - 支持简单查询（直接文件查找）和复杂查询（CLI 辅助分析） - 集成 gemini/qwen 进行跨命令对比、最佳实践、工作流分析 - 添加查询复杂度自动分类和降级策略 更新文档 - SKILL.md: 添加 Mode 6 说明和 Reference Documentation 章节 - implementation-details.md: 添加完整的 Mode 6 实现逻辑 - 版本更新至 v1.3.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
609
.claude/skills/command-guide/reference/commands/memory/docs.md
Normal file
609
.claude/skills/command-guide/reference/commands/memory/docs.md
Normal file
@@ -0,0 +1,609 @@
|
||||
---
|
||||
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` |
|
||||
|
||||
**Benefits**: Easy to locate documentation, maintains logical organization, clear 1:1 mapping, supports any project structure.
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]
|
||||
```
|
||||
|
||||
- **path**: Target directory (default: current directory)
|
||||
- **--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)
|
||||
|
||||
# Create session directories (replace timestamp)
|
||||
bash(mkdir -p .workflow/WFS-docs-{timestamp}/.{task,process,summaries} && touch .workflow/.active-WFS-docs-{timestamp})
|
||||
|
||||
# Create workflow-session.json (replace values)
|
||||
bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-{timestamp}/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(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
|
||||
|
||||
# 2. Get top-level directories (first 2 path levels)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh | 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/phase2-analysis.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 `phase2-analysis.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 phase2-analysis.json
|
||||
bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.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
|
||||
|
||||
**Benefits**: Parallel execution, failure isolation, progress visibility, context sharing, document count control.
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
# 1. Get top-level directories from phase2-analysis.json
|
||||
bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq -r '.top_level_dirs[]')
|
||||
|
||||
# 2. Get mode from workflow-session.json
|
||||
bash(cat .workflow/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 `phase2-analysis.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/WFS-docs-{timestamp}/.process/phase2-analysis.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 | --approval-mode yolo | Execute CLI commands, validate output |
|
||||
|
||||
**Command Patterns**:
|
||||
- Gemini/Qwen: `cd dir && gemini -p "..."`
|
||||
- CLI Mode: `cd dir && gemini --approval-mode yolo -p "..."`
|
||||
- Codex: `codex -C dir --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
|
||||
|
||||
**Generation Process**:
|
||||
1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
|
||||
2. Read group assignments from phase2-analysis.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 phase2-analysis.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/phase2-analysis.json"
|
||||
}
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_precomputed_data",
|
||||
"action": "Load Phase 2 analysis and extract group directories",
|
||||
"commands": [
|
||||
"bash(cat ${session_dir}/.process/phase2-analysis.json)",
|
||||
"bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/phase2-analysis.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": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/phase2-analysis.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
|
||||
"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(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
|
||||
"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(gemini \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\")", "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(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")", "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}
|
||||
└── WFS-docs-{timestamp}/
|
||||
├── workflow-session.json # Session metadata
|
||||
├── IMPL_PLAN.md
|
||||
├── TODO_LIST.md
|
||||
├── .process/
|
||||
│ └── phase2-analysis.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)
|
||||
```
|
||||
|
||||
**phase2-analysis.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 | --approval-mode yolo | 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
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
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)
|
||||
240
.claude/skills/command-guide/reference/commands/memory/load.md
Normal file
240
.claude/skills/command-guide/reference/commands/memory/load.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: load
|
||||
description: Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context
|
||||
argument-hint: "[--tool gemini|qwen] \"task context description\""
|
||||
allowed-tools: Task(*), Bash(*)
|
||||
examples:
|
||||
- /memory:load "在当前前端基础上开发用户认证功能"
|
||||
- /memory:load --tool qwen -p "重构支付模块API"
|
||||
---
|
||||
|
||||
# Memory Load Command (/memory:load)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The `memory:load` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
|
||||
|
||||
**Core Philosophy**:
|
||||
- **Agent-Driven**: Fully delegates execution to universal-executor agent
|
||||
- **Read-Only Analysis**: Does not modify code, only extracts context
|
||||
- **Structured Output**: Returns standardized JSON content package
|
||||
- **Memory Optimization**: Package loaded directly into main thread memory
|
||||
- **Token Efficiency**: CLI analysis executed within agent to save tokens
|
||||
|
||||
## 2. Parameters
|
||||
|
||||
- `"task context description"` (Required): Task description to guide context extraction
|
||||
- Example: "在当前前端基础上开发用户认证功能"
|
||||
- Example: "重构支付模块API"
|
||||
- Example: "修复数据库查询性能问题"
|
||||
|
||||
- `--tool <gemini|qwen>` (Optional): Specify CLI tool for agent to use (default: gemini)
|
||||
- gemini: Large context window, suitable for complex project analysis
|
||||
- qwen: Alternative to Gemini with similar capabilities
|
||||
|
||||
## 3. Agent-Driven Execution Flow
|
||||
|
||||
The command fully delegates to **universal-executor agent**, which autonomously:
|
||||
|
||||
1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture
|
||||
2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs
|
||||
3. **Extracts Keywords**: Derives core keywords from task description
|
||||
4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files
|
||||
5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis
|
||||
6. **Generates Content Package**: Returns structured JSON core content package
|
||||
|
||||
## 4. Core Content Package Structure
|
||||
|
||||
**Output Format** - Loaded into main thread memory for subsequent use:
|
||||
|
||||
```json
|
||||
{
|
||||
"task_context": "在当前前端基础上开发用户认证功能",
|
||||
"keywords": ["前端", "用户", "认证", "auth", "login"],
|
||||
"project_summary": {
|
||||
"architecture": "TypeScript + React frontend with Vite build system",
|
||||
"tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"],
|
||||
"key_patterns": [
|
||||
"State management via Context API",
|
||||
"Functional components with Hooks pattern",
|
||||
"API calls encapsulated in custom hooks"
|
||||
]
|
||||
},
|
||||
"relevant_files": [
|
||||
{
|
||||
"path": "src/components/Auth/LoginForm.tsx",
|
||||
"relevance": "Existing login form component",
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"path": "src/contexts/AuthContext.tsx",
|
||||
"relevance": "Authentication state management context",
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"path": "CLAUDE.md",
|
||||
"relevance": "Project development standards",
|
||||
"priority": "high"
|
||||
}
|
||||
],
|
||||
"integration_points": [
|
||||
"Must integrate with existing AuthContext",
|
||||
"Follow component organization pattern: src/components/[Feature]/",
|
||||
"API calls should use src/hooks/useApi.ts wrapper"
|
||||
],
|
||||
"constraints": [
|
||||
"Maintain backward compatibility",
|
||||
"Follow TypeScript strict mode",
|
||||
"Use existing UI component library"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Agent Invocation
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="universal-executor",
|
||||
description="Load project memory: ${task_description}",
|
||||
prompt=`
|
||||
## Mission: Load Project Memory Context
|
||||
|
||||
**Task**: Load project memory context for: "${task_description}"
|
||||
**Mode**: analysis
|
||||
**Tool Preference**: ${tool || 'gemini'}
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Foundation Analysis
|
||||
|
||||
1. **Project Structure**
|
||||
\`\`\`bash
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh)
|
||||
\`\`\`
|
||||
|
||||
2. **Core Documentation**
|
||||
\`\`\`javascript
|
||||
Read(CLAUDE.md)
|
||||
Read(README.md)
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Keyword Extraction & File Discovery
|
||||
|
||||
1. Extract core keywords from task description
|
||||
2. Discover relevant files using ripgrep and find:
|
||||
\`\`\`bash
|
||||
# Find files by name
|
||||
find . -name "*{keyword}*" -type f
|
||||
|
||||
# Search content with ripgrep
|
||||
rg "{keyword}" --type ts --type md -C 2
|
||||
rg -l "{keyword}" --type ts --type md # List files only
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Deep Analysis via CLI
|
||||
|
||||
Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
|
||||
|
||||
\`\`\`bash
|
||||
cd . && ${tool} -p "
|
||||
PURPOSE: Extract project core context for task: ${task_description}
|
||||
TASK: Analyze project architecture, tech stack, key patterns, relevant files
|
||||
MODE: analysis
|
||||
CONTEXT: @CLAUDE.md,README.md @${discovered_files}
|
||||
EXPECTED: Structured project summary and integration point analysis
|
||||
RULES:
|
||||
- Focus on task-relevant core information
|
||||
- Identify key architecture patterns and technical constraints
|
||||
- Extract integration points and development standards
|
||||
- Output concise, structured format
|
||||
"
|
||||
\`\`\`
|
||||
|
||||
### Step 4: Generate Core Content Package
|
||||
|
||||
Generate structured JSON content package (format shown above)
|
||||
|
||||
**Required Fields**:
|
||||
- task_context: Original task description
|
||||
- keywords: Extracted keyword array
|
||||
- project_summary: Architecture, tech stack, key patterns
|
||||
- relevant_files: File list with path, relevance, priority
|
||||
- integration_points: Integration guidance
|
||||
- constraints: Development constraints
|
||||
|
||||
### Step 5: Return Content Package
|
||||
|
||||
Return JSON content package as final output for main thread to load into memory.
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before returning:
|
||||
- [ ] Valid JSON format
|
||||
- [ ] All required fields complete
|
||||
- [ ] relevant_files contains 3-10 files minimum
|
||||
- [ ] project_summary accurately reflects architecture
|
||||
- [ ] integration_points clearly specify integration paths
|
||||
- [ ] keywords accurately extracted (3-8 keywords)
|
||||
- [ ] Content concise, avoiding redundancy (< 5KB total)
|
||||
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
## 6. Usage Examples
|
||||
|
||||
### Example 1: Load Context for New Feature
|
||||
|
||||
```bash
|
||||
/memory:load "在当前前端基础上开发用户认证功能"
|
||||
```
|
||||
|
||||
**Agent Execution**:
|
||||
1. Analyzes project structure (`get_modules_by_depth.sh`)
|
||||
2. Reads CLAUDE.md, README.md
|
||||
3. Extracts keywords: ["前端", "用户", "认证", "auth"]
|
||||
4. Uses MCP to search relevant files
|
||||
5. Executes Gemini CLI for deep analysis
|
||||
6. Returns core content package
|
||||
|
||||
**Returned Package** (loaded into memory):
|
||||
```json
|
||||
{
|
||||
"task_context": "在当前前端基础上开发用户认证功能",
|
||||
"keywords": ["前端", "认证", "auth", "login"],
|
||||
"project_summary": { ... },
|
||||
"relevant_files": [ ... ],
|
||||
"integration_points": [ ... ],
|
||||
"constraints": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: Using Qwen Tool
|
||||
|
||||
```bash
|
||||
/memory:load --tool qwen -p "重构支付模块API"
|
||||
```
|
||||
|
||||
Agent uses Qwen CLI for analysis, returns same structured package.
|
||||
|
||||
### Example 3: Bug Fix Context
|
||||
|
||||
```bash
|
||||
/memory:load "修复登录验证错误"
|
||||
```
|
||||
|
||||
Returns core context related to login validation, including test files and validation logic.
|
||||
|
||||
### Memory Persistence
|
||||
|
||||
- **Session-Scoped**: Content package valid for current session
|
||||
- **Subsequent Reference**: All subsequent agents/commands can access
|
||||
- **Reload Required**: New sessions need to re-execute /memory:load
|
||||
|
||||
## 8. Notes
|
||||
|
||||
- **Read-Only**: Does not modify any code, pure analysis
|
||||
- **Token Optimization**: CLI analysis executed within agent, saves main thread tokens
|
||||
- **Memory Loading**: Returned JSON loaded directly into main thread memory
|
||||
- **Subsequent Use**: Other commands/agents can reference this package for development
|
||||
- **Session-Level**: Content package valid for current session
|
||||
@@ -0,0 +1,534 @@
|
||||
---
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
- **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
|
||||
- **Auto-Continue**: Autonomous 4-phase execution without user interaction
|
||||
- **Intelligent Skip**: Detects existing docs and skips regeneration for fast SKILL updates
|
||||
- **Always Fresh Index**: Phase 4 always executes to ensure SKILL.md stays synchronized
|
||||
- **Simplified**: ~70% less code than previous version
|
||||
- **Maintainable**: Changes to /memory:docs automatically apply
|
||||
- **Direct Generation**: Phase 4 directly writes SKILL.md
|
||||
- **Flexible**: Supports all /memory:docs options (tool, mode, cli-execute)
|
||||
|
||||
## 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
|
||||
```
|
||||
@@ -0,0 +1,477 @@
|
||||
---
|
||||
name: tech-research
|
||||
description: 3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)
|
||||
argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
|
||||
allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
|
||||
---
|
||||
|
||||
# Tech Stack Research SKILL Generator
|
||||
|
||||
## Overview
|
||||
|
||||
**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates ALL work to agent. Agent produces files directly.
|
||||
|
||||
**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 SKILL OR `--regenerate` specified)
|
||||
- **Skip Path**: Phase 1 → Phase 3 (existing SKILL found AND no `--regenerate` flag)
|
||||
- **Phase 3 Always Executes**: SKILL index is always generated or updated
|
||||
|
||||
**Agent Responsibility**:
|
||||
- Agent does ALL the work: context reading, Exa research, content synthesis, file writing
|
||||
- Orchestrator only provides context paths and waits for completion
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
|
||||
2. **Context Path Delegation**: Pass session directory or tech stack name to agent, let agent do discovery
|
||||
3. **Agent Produces Files**: Agent directly writes all module files, orchestrator does NOT parse agent output
|
||||
4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
|
||||
5. **No User Prompts**: Never ask user questions or wait for input between phases
|
||||
6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
|
||||
7. **Lightweight Index**: Phase 3 only generates SKILL.md index by reading existing files
|
||||
|
||||
---
|
||||
|
||||
## 3-Phase Execution
|
||||
|
||||
### Phase 1: Prepare Context Paths
|
||||
|
||||
**Goal**: Detect input mode, prepare context paths for agent, check existing SKILL
|
||||
|
||||
**Input Mode Detection**:
|
||||
```bash
|
||||
# Get input parameter
|
||||
input="$1"
|
||||
|
||||
# Detect mode
|
||||
if [[ "$input" == WFS-* ]]; then
|
||||
MODE="session"
|
||||
SESSION_ID="$input"
|
||||
CONTEXT_PATH=".workflow/${SESSION_ID}"
|
||||
else
|
||||
MODE="direct"
|
||||
TECH_STACK_NAME="$input"
|
||||
CONTEXT_PATH="$input" # Pass tech stack name as context
|
||||
fi
|
||||
```
|
||||
|
||||
**Check Existing SKILL**:
|
||||
```bash
|
||||
# For session mode, peek at session to get tech stack name
|
||||
if [[ "$MODE" == "session" ]]; then
|
||||
bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
|
||||
Read(.workflow/${SESSION_ID}/workflow-session.json)
|
||||
# Extract tech_stack_name (minimal extraction)
|
||||
fi
|
||||
|
||||
# Normalize and check
|
||||
normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
|
||||
bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
|
||||
bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)
|
||||
```
|
||||
|
||||
**Skip Decision**:
|
||||
```javascript
|
||||
if (existing_files > 0 && !regenerate_flag) {
|
||||
SKIP_GENERATION = true
|
||||
message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
|
||||
} else if (regenerate_flag) {
|
||||
bash(rm -rf ".claude/skills/${normalized_name}")
|
||||
SKIP_GENERATION = false
|
||||
message = "Regenerating tech stack SKILL from scratch."
|
||||
} else {
|
||||
SKIP_GENERATION = false
|
||||
message = "No existing SKILL found, generating new tech stack documentation."
|
||||
}
|
||||
```
|
||||
|
||||
**Output Variables**:
|
||||
- `MODE`: `session` or `direct`
|
||||
- `SESSION_ID`: Session ID (if session mode)
|
||||
- `CONTEXT_PATH`: Path to session directory OR tech stack name
|
||||
- `TECH_STACK_NAME`: Extracted or provided tech stack name
|
||||
- `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: Agent Produces All Files
|
||||
|
||||
**Skip Condition**: Skipped if `SKIP_GENERATION = true`
|
||||
|
||||
**Goal**: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing
|
||||
|
||||
**Agent Task Specification**:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type: "general-purpose",
|
||||
description: "Generate tech stack SKILL: {CONTEXT_PATH}",
|
||||
prompt: "
|
||||
Generate a complete tech stack SKILL package with Exa research.
|
||||
|
||||
**Context Provided**:
|
||||
- Mode: {MODE}
|
||||
- Context Path: {CONTEXT_PATH}
|
||||
|
||||
**Templates Available**:
|
||||
- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
|
||||
- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt
|
||||
|
||||
**Your Responsibilities**:
|
||||
|
||||
1. **Extract Tech Stack Information**:
|
||||
|
||||
IF MODE == 'session':
|
||||
- Read `.workflow/{SESSION_ID}/workflow-session.json`
|
||||
- Read `.workflow/{SESSION_ID}/.process/context-package.json`
|
||||
- Extract tech_stack: {language, frameworks, libraries}
|
||||
- Build tech stack name: \"{language}-{framework1}-{framework2}\"
|
||||
- Example: \"typescript-react-nextjs\"
|
||||
|
||||
IF MODE == 'direct':
|
||||
- Tech stack name = CONTEXT_PATH
|
||||
- Parse composite: split by '-' delimiter
|
||||
- Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]
|
||||
|
||||
2. **Execute Exa Research** (4-6 parallel queries):
|
||||
|
||||
Base Queries (always execute):
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
|
||||
- mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
|
||||
- mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)
|
||||
|
||||
Component Queries (if composite):
|
||||
- For each additional component:
|
||||
mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)
|
||||
|
||||
3. **Read Module Format Template**:
|
||||
|
||||
Read template for structure guidance:
|
||||
```bash
|
||||
Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)
|
||||
```
|
||||
|
||||
4. **Synthesize Content into 6 Modules**:
|
||||
|
||||
Follow template structure from tech-module-format.txt:
|
||||
- **principles.md** - Core concepts, philosophies (~3K tokens)
|
||||
- **patterns.md** - Implementation patterns with code examples (~5K tokens)
|
||||
- **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
|
||||
- **testing.md** - Testing strategies, frameworks (~3K tokens)
|
||||
- **config.md** - Setup, configuration, tooling (~3K tokens)
|
||||
- **frameworks.md** - Framework integration (only if composite, ~4K tokens)
|
||||
|
||||
Each module follows template format:
|
||||
- Frontmatter (YAML)
|
||||
- Main sections with clear headings
|
||||
- Code examples from Exa research
|
||||
- Best practices sections
|
||||
- References to Exa sources
|
||||
|
||||
5. **Write Files Directly**:
|
||||
|
||||
```javascript
|
||||
// Create directory
|
||||
bash(mkdir -p \".claude/skills/{tech_stack_name}\")
|
||||
|
||||
// Write each module file using Write tool
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
|
||||
Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
|
||||
// Write frameworks.md only if composite
|
||||
|
||||
// Write metadata.json
|
||||
Write({
|
||||
file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
|
||||
content: JSON.stringify({
|
||||
tech_stack_name,
|
||||
components,
|
||||
is_composite,
|
||||
generated_at: timestamp,
|
||||
source: \"exa-research\",
|
||||
research_summary: { total_queries, total_sources }
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
6. **Report Completion**:
|
||||
|
||||
Provide summary:
|
||||
- Tech stack name
|
||||
- Files created (count)
|
||||
- Exa queries executed
|
||||
- Sources consulted
|
||||
|
||||
**CRITICAL**:
|
||||
- MUST read external template files before generating content (step 3 for modules, step 4 for index)
|
||||
- You have FULL autonomy - read files, execute Exa, synthesize content, write files
|
||||
- Do NOT return JSON or structured data - produce actual .md files
|
||||
- Handle errors gracefully (Exa failures, missing files, template read failures)
|
||||
- If tech stack cannot be determined, ask orchestrator to clarify
|
||||
"
|
||||
)
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- Agent task executed successfully
|
||||
- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
|
||||
- metadata.json written
|
||||
- Agent reports completion
|
||||
|
||||
**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 module files and create SKILL.md index with loading recommendations
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Verify Generated Files**:
|
||||
```bash
|
||||
bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)
|
||||
```
|
||||
|
||||
2. **Read metadata.json**:
|
||||
```javascript
|
||||
Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
|
||||
// Extract: tech_stack_name, components, is_composite, research_summary
|
||||
```
|
||||
|
||||
3. **Read Module Headers** (optional, first 20 lines):
|
||||
```javascript
|
||||
Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
|
||||
// Repeat for other modules
|
||||
```
|
||||
|
||||
4. **Read SKILL Index Template**:
|
||||
|
||||
```javascript
|
||||
Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
|
||||
```
|
||||
|
||||
5. **Generate SKILL.md Index**:
|
||||
|
||||
Follow template from tech-skill-index.txt with variable substitutions:
|
||||
- `{TECH_STACK_NAME}`: From metadata.json
|
||||
- `{MAIN_TECH}`: Primary technology
|
||||
- `{ISO_TIMESTAMP}`: Current timestamp
|
||||
- `{QUERY_COUNT}`: From research_summary
|
||||
- `{SOURCE_COUNT}`: From research_summary
|
||||
- Conditional sections for composite tech stacks
|
||||
|
||||
Template provides structure for:
|
||||
- Frontmatter with metadata
|
||||
- Overview and tech stack description
|
||||
- Module organization (Core/Practical/Config sections)
|
||||
- Loading recommendations (Quick/Implementation/Complete)
|
||||
- Usage guidelines and auto-trigger keywords
|
||||
- Research metadata and version history
|
||||
|
||||
6. **Write SKILL.md**:
|
||||
```javascript
|
||||
Write({
|
||||
file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
|
||||
content: generatedIndexMarkdown
|
||||
})
|
||||
```
|
||||
|
||||
**Completion Criteria**:
|
||||
- SKILL.md index written
|
||||
- All module files verified
|
||||
- Loading recommendations included
|
||||
|
||||
**TodoWrite**: Mark phase 3 completed
|
||||
|
||||
**Final Report**:
|
||||
```
|
||||
Tech Stack SKILL Package Complete
|
||||
|
||||
Tech Stack: {TECH_STACK_NAME}
|
||||
Location: .claude/skills/{TECH_STACK_NAME}/
|
||||
|
||||
Files: SKILL.md + 5-6 modules + metadata.json
|
||||
Exa Research: {queries} queries, {sources} sources
|
||||
|
||||
Usage: Skill(command: "{TECH_STACK_NAME}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### TodoWrite Patterns
|
||||
|
||||
**Initialization** (Before Phase 1):
|
||||
```javascript
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
|
||||
{"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
|
||||
]})
|
||||
```
|
||||
|
||||
**Full Path** (SKIP_GENERATION = false):
|
||||
```javascript
|
||||
// After Phase 1
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "in_progress", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "pending", ...}
|
||||
]})
|
||||
|
||||
// After Phase 2
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "completed", ...},
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
|
||||
// After Phase 3
|
||||
TodoWrite({todos: [
|
||||
{"content": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module 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": "Prepare context paths", "status": "completed", ...},
|
||||
{"content": "Agent produces all module files", "status": "completed", ...}, // Skipped
|
||||
{"content": "Generate SKILL.md index", "status": "in_progress", ...}
|
||||
]})
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
**Full Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report
|
||||
```
|
||||
|
||||
**Skip Path**:
|
||||
```
|
||||
User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Phase 1 Errors**:
|
||||
- Invalid session ID: Report error, verify session exists
|
||||
- Missing context-package: Warn, fall back to direct mode
|
||||
- No tech stack detected: Ask user to specify tech stack name
|
||||
|
||||
**Phase 2 Errors (Agent)**:
|
||||
- Agent task fails: Retry once, report if fails again
|
||||
- Exa API failures: Agent handles internally with retries
|
||||
- Incomplete results: Warn user, proceed with partial data if minimum sections available
|
||||
|
||||
**Phase 3 Errors**:
|
||||
- Write failures: Report which files failed
|
||||
- Missing files: Note in SKILL.md, suggest regeneration
|
||||
|
||||
---
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]
|
||||
```
|
||||
|
||||
**Arguments**:
|
||||
- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix)
|
||||
- Session mode: `WFS-user-auth-v2` - Extract tech stack from workflow
|
||||
- Direct mode: `"typescript"`, `"typescript-react-nextjs"` - User specifies
|
||||
- **--regenerate**: Force regenerate existing SKILL (deletes and recreates)
|
||||
- **--tool**: Reserved for future CLI integration (default: gemini)
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Generated File Structure** (for all examples):
|
||||
```
|
||||
.claude/skills/{tech-stack}/
|
||||
├── SKILL.md # Index (Phase 3)
|
||||
├── principles.md # Agent (Phase 2)
|
||||
├── patterns.md # Agent
|
||||
├── practices.md # Agent
|
||||
├── testing.md # Agent
|
||||
├── config.md # Agent
|
||||
├── frameworks.md # Agent (if composite)
|
||||
└── metadata.json # Agent
|
||||
```
|
||||
|
||||
### Direct Mode - Single Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects direct mode, checks existing SKILL
|
||||
2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
|
||||
3. Phase 3: Generates SKILL.md index
|
||||
|
||||
### Direct Mode - Composite Stack
|
||||
|
||||
```bash
|
||||
/memory:tech-research "typescript-react-nextjs"
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
|
||||
2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
|
||||
3. Phase 3: Generates SKILL.md index with framework integration
|
||||
|
||||
### Session Mode - Extract from Workflow
|
||||
|
||||
```bash
|
||||
/memory:tech-research WFS-user-auth-20251104
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Reads session, extracts tech stack: `python-fastapi-sqlalchemy`
|
||||
2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
|
||||
3. Phase 3: Generates SKILL.md index
|
||||
|
||||
### Regenerate Existing
|
||||
|
||||
```bash
|
||||
/memory:tech-research "react" --regenerate
|
||||
```
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Deletes existing SKILL due to --regenerate
|
||||
2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
|
||||
3. Phase 3: Generates updated SKILL.md
|
||||
|
||||
### Skip Path - Fast Update
|
||||
|
||||
```bash
|
||||
/memory:tech-research "python"
|
||||
```
|
||||
|
||||
**Scenario**: SKILL already exists with 7 files
|
||||
|
||||
**Workflow**:
|
||||
1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
|
||||
2. Phase 2: **SKIPPED**
|
||||
3. Phase 3: Updates SKILL.md index only (5-10x faster)
|
||||
|
||||
|
||||
@@ -0,0 +1,333 @@
|
||||
---
|
||||
name: update-full
|
||||
description: Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
|
||||
argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
|
||||
---
|
||||
|
||||
# Full Documentation Update (/memory:update-full)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
|
||||
|
||||
**Parameters**:
|
||||
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
|
||||
- `--path <directory>`: Target specific directory (default: entire project)
|
||||
|
||||
**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
|
||||
|
||||
## 3-Layer Architecture & Auto-Strategy Selection
|
||||
|
||||
### Layer Definition & Strategy Assignment
|
||||
|
||||
| Layer | Depth | Strategy | Purpose | Context Pattern |
|
||||
|-------|-------|----------|---------|----------------|
|
||||
| **Layer 3** (Deepest) | ≥3 | `multi-layer` | Handle unstructured files, generate docs for all subdirectories | `@**/*` (all files) |
|
||||
| **Layer 2** (Middle) | 1-2 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
|
||||
| **Layer 1** (Top) | 0 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
|
||||
|
||||
**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
|
||||
|
||||
**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
|
||||
|
||||
### Strategy Details
|
||||
|
||||
#### Multi-Layer Strategy (Layer 3 Only)
|
||||
- **Use Case**: Deepest directories with unstructured file layouts
|
||||
- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
|
||||
- **Context**: All files in current directory tree (`@**/*`)
|
||||
- **Benefits**: Creates foundation documentation for upper layers to reference
|
||||
|
||||
#### Single-Layer Strategy (Layers 1-2)
|
||||
- **Use Case**: Upper layers that aggregate from existing documentation
|
||||
- **Behavior**: Generates CLAUDE.md only for current directory
|
||||
- **Context**: Direct children CLAUDE.md files + current directory code files
|
||||
- **Benefits**: Minimal context consumption, clear layer separation
|
||||
|
||||
### Example Flow
|
||||
```
|
||||
src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
|
||||
CONTEXT: @**/* (all files in handlers/ and subdirs)
|
||||
GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
|
||||
↓
|
||||
src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
|
||||
CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
|
||||
GENERATES: ./CLAUDE.md only
|
||||
↓
|
||||
src/ (depth 1) → SINGLE-LAYER STRATEGY
|
||||
CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
|
||||
GENERATES: ./CLAUDE.md only
|
||||
↓
|
||||
./ (depth 0) → SINGLE-LAYER STRATEGY
|
||||
CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
|
||||
GENERATES: ./CLAUDE.md only
|
||||
```
|
||||
|
||||
## Core Execution Rules
|
||||
|
||||
1. **Analyze First**: Git cache + module discovery before updates
|
||||
2. **Wait for Approval**: Present plan, no execution without user confirmation
|
||||
3. **Execution Strategy**:
|
||||
- **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
|
||||
- **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
|
||||
4. **Tool Fallback**: Auto-retry with fallback tools on failure
|
||||
5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
|
||||
6. **Safety Check**: Verify only CLAUDE.md files modified
|
||||
7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
|
||||
|
||||
## Tool Fallback Hierarchy
|
||||
|
||||
```javascript
|
||||
--tool gemini → [gemini, qwen, codex] // default
|
||||
--tool qwen → [qwen, gemini, codex]
|
||||
--tool codex → [codex, gemini, qwen]
|
||||
```
|
||||
|
||||
**Trigger**: Non-zero exit code from update script
|
||||
|
||||
| Tool | Best For | Fallback To |
|
||||
|--------|--------------------------------|----------------|
|
||||
| gemini | Documentation, patterns | qwen → codex |
|
||||
| qwen | Architecture, system design | gemini → codex |
|
||||
| codex | Implementation, code quality | gemini → qwen |
|
||||
|
||||
## Execution Phases
|
||||
|
||||
### Phase 1: Discovery & Analysis
|
||||
|
||||
```bash
|
||||
# Cache git changes
|
||||
bash(git add -A 2>/dev/null || true)
|
||||
|
||||
# Get module structure
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
# OR with --path
|
||||
bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
|
||||
|
||||
### Phase 2: Plan Presentation
|
||||
|
||||
**For <20 modules**:
|
||||
```
|
||||
Update Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Total: 7 modules
|
||||
Execution: Direct parallel (< 20 modules threshold)
|
||||
|
||||
Will update:
|
||||
- ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
|
||||
- ./core (22 files) - depth 1 [Layer 2] - single-layer strategy
|
||||
- ./models (9 files) - depth 1 [Layer 2] - single-layer strategy
|
||||
- ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
|
||||
- . (5 files) - depth 0 [Layer 1] - single-layer strategy
|
||||
|
||||
Context Strategy (Auto-Selected):
|
||||
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
|
||||
- Layer 1 (depth 0): @*/CLAUDE.md + current code files
|
||||
|
||||
Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
|
||||
Execution order: Layer 2 → Layer 1
|
||||
Estimated time: ~5-10 minutes
|
||||
|
||||
Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**For ≥20 modules**:
|
||||
```
|
||||
Update Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Total: 31 modules
|
||||
Execution: Agent batch processing (4 modules/agent)
|
||||
|
||||
Will update:
|
||||
- ./src/features/auth (12 files) - depth 3 [Layer 3] - multi-layer strategy
|
||||
- ./.claude/commands/cli (6 files) - depth 3 [Layer 3] - multi-layer strategy
|
||||
- ./src/utils (8 files) - depth 2 [Layer 2] - single-layer strategy
|
||||
...
|
||||
|
||||
Context Strategy (Auto-Selected):
|
||||
- Layer 3 (depth ≥3): @**/* (all files)
|
||||
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
|
||||
- Layer 1 (depth 0): @*/CLAUDE.md + current code files
|
||||
|
||||
Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
|
||||
Execution order: Layer 2 → Layer 1
|
||||
Estimated time: ~5-10 minutes
|
||||
|
||||
Agent allocation (by LAYER):
|
||||
- Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
|
||||
- Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
|
||||
- Layer 1 (2 modules, depth 0): 1 agent [2]
|
||||
|
||||
Estimated time: ~15-25 minutes
|
||||
|
||||
Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
### Phase 3A: Direct Execution (<20 modules)
|
||||
|
||||
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
|
||||
|
||||
```javascript
|
||||
// Group modules by LAYER (not depth)
|
||||
let modules_by_layer = group_by_layer(module_list);
|
||||
let tool_order = construct_tool_order(primary_tool);
|
||||
|
||||
// Process by LAYER (3 → 2 → 1), not by depth
|
||||
for (let layer of [3, 2, 1]) {
|
||||
if (modules_by_layer[layer].length === 0) continue;
|
||||
|
||||
let batches = batch_modules(modules_by_layer[layer], 4);
|
||||
|
||||
for (let batch of batches) {
|
||||
let parallel_tasks = batch.map(module => {
|
||||
return async () => {
|
||||
// Auto-determine strategy based on depth
|
||||
let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
|
||||
|
||||
for (let tool of tool_order) {
|
||||
let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
|
||||
if (exit_code === 0) {
|
||||
report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
|
||||
return false;
|
||||
};
|
||||
});
|
||||
|
||||
await Promise.all(parallel_tasks.map(task => task()));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3B: Agent Batch Execution (≥20 modules)
|
||||
|
||||
**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
|
||||
|
||||
```javascript
|
||||
// Group modules by LAYER and batch within each layer
|
||||
let modules_by_layer = group_by_layer(module_list);
|
||||
let tool_order = construct_tool_order(primary_tool);
|
||||
|
||||
for (let layer of [3, 2, 1]) {
|
||||
if (modules_by_layer[layer].length === 0) continue;
|
||||
|
||||
let batches = batch_modules(modules_by_layer[layer], 4);
|
||||
let worker_tasks = [];
|
||||
|
||||
for (let batch of batches) {
|
||||
worker_tasks.push(
|
||||
Task(
|
||||
subagent_type="memory-bridge",
|
||||
description=`Update ${batch.length} modules in Layer ${layer}`,
|
||||
prompt=generate_batch_worker_prompt(batch, tool_order, layer)
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
await parallel_execute(worker_tasks);
|
||||
}
|
||||
```
|
||||
|
||||
**Batch Worker Prompt Template**:
|
||||
```
|
||||
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
|
||||
|
||||
TASK: Update documentation for assigned modules using specified strategies.
|
||||
|
||||
MODULES:
|
||||
{{module_path_1}} (strategy: {{strategy_1}})
|
||||
{{module_path_2}} (strategy: {{strategy_2}})
|
||||
...
|
||||
|
||||
TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
|
||||
|
||||
EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
|
||||
- Accepts strategy parameter: multi-layer | single-layer
|
||||
- Tool execution via direct CLI commands (gemini/qwen/codex)
|
||||
|
||||
EXECUTION FLOW (for each module):
|
||||
1. Tool fallback loop (exit on first success):
|
||||
for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
|
||||
exit_code=$?
|
||||
|
||||
if [ $exit_code -eq 0 ]; then
|
||||
report "✅ {{module_path}} updated with $tool"
|
||||
break
|
||||
else
|
||||
report "⚠️ {{module_path}} failed with $tool, trying next..."
|
||||
continue
|
||||
fi
|
||||
done
|
||||
|
||||
2. Handle complete failure (all tools failed):
|
||||
if [ $exit_code -ne 0 ]; then
|
||||
report "❌ FAILED: {{module_path}} - all tools exhausted"
|
||||
# Continue to next module (do not abort batch)
|
||||
fi
|
||||
|
||||
FAILURE HANDLING:
|
||||
- Module-level isolation: One module's failure does not affect others
|
||||
- Exit code detection: Non-zero exit code triggers next tool
|
||||
- Exhaustion reporting: Log modules where all tools failed
|
||||
- Batch continuation: Always process remaining modules
|
||||
|
||||
REPORTING FORMAT:
|
||||
Per-module status:
|
||||
✅ path/to/module updated with {tool}
|
||||
⚠️ path/to/module failed with {tool}, trying next...
|
||||
❌ FAILED: path/to/module - all tools exhausted
|
||||
```
|
||||
### Phase 4: Safety Verification
|
||||
|
||||
```bash
|
||||
# Check only CLAUDE.md modified
|
||||
bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
|
||||
|
||||
# Display status
|
||||
bash(git status --short)
|
||||
```
|
||||
|
||||
**Result Summary**:
|
||||
```
|
||||
Update Summary:
|
||||
Total: 31 | Success: 29 | Failed: 2
|
||||
Tool usage: gemini: 25, qwen: 4, codex: 0
|
||||
Failed: path1, path2
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
|
||||
**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
|
||||
**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full project update (auto-strategy selection)
|
||||
/memory:update-full
|
||||
|
||||
# Target specific directory
|
||||
/memory:update-full --path .claude
|
||||
/memory:update-full --path src/features/auth
|
||||
|
||||
# Use specific tool
|
||||
/memory:update-full --tool qwen
|
||||
/memory:update-full --path .claude --tool qwen
|
||||
```
|
||||
|
||||
## Key Advantages
|
||||
|
||||
- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
|
||||
- **Resilience**: 3-tier tool fallback per module
|
||||
- **Performance**: Parallel batches, no concurrency limits
|
||||
- **Observability**: Per-module tool usage, batch-level metrics
|
||||
- **Automation**: Zero configuration - strategy auto-selected by directory depth
|
||||
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: update-related
|
||||
description: Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution
|
||||
argument-hint: "[--tool gemini|qwen|codex]"
|
||||
---
|
||||
|
||||
# Related Documentation Update (/memory:update-related)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
|
||||
|
||||
**Parameters**:
|
||||
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
|
||||
|
||||
**Execution Flow**:
|
||||
1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Detect Changes First**: Use git diff to identify affected modules
|
||||
2. **Wait for Approval**: Present plan, no execution without user confirmation
|
||||
3. **Execution Strategy**:
|
||||
- <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
|
||||
- ≥15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
|
||||
4. **Tool Fallback**: Auto-retry with fallback tools on failure
|
||||
5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
|
||||
6. **Related Mode**: Update only changed modules and their parent contexts
|
||||
|
||||
## Tool Fallback Hierarchy
|
||||
|
||||
```javascript
|
||||
--tool gemini → [gemini, qwen, codex] // default
|
||||
--tool qwen → [qwen, gemini, codex]
|
||||
--tool codex → [codex, gemini, qwen]
|
||||
```
|
||||
|
||||
**Trigger**: Non-zero exit code from update script
|
||||
|
||||
## Phase 1: Change Detection & Analysis
|
||||
|
||||
```bash
|
||||
# Detect changed modules (no index refresh needed)
|
||||
bash(~/.claude/scripts/detect_changed_modules.sh list)
|
||||
|
||||
# Cache git changes
|
||||
bash(git add -A 2>/dev/null || true)
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc).
|
||||
|
||||
**Fallback**: If no changes detected, use recent modules (first 10 by depth).
|
||||
|
||||
## Phase 2: Plan Presentation
|
||||
|
||||
**Present filtered plan**:
|
||||
```
|
||||
Related Update Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Changed: 4 modules | Batching: 4 modules/agent
|
||||
|
||||
Will update:
|
||||
- ./src/api/auth (5 files) [new module]
|
||||
- ./src/api (12 files) [parent of changed auth/]
|
||||
- ./src (8 files) [parent context]
|
||||
- . (14 files) [root level]
|
||||
|
||||
Auto-skipped (12 paths):
|
||||
- Tests: ./src/api/auth.test.ts (8 paths)
|
||||
- Config: tsconfig.json (3 paths)
|
||||
- Other: node_modules (1 path)
|
||||
|
||||
Agent allocation:
|
||||
- Depth 3 (1 module): 1 agent [1]
|
||||
- Depth 2 (1 module): 1 agent [1]
|
||||
- Depth 1 (1 module): 1 agent [1]
|
||||
- Depth 0 (1 module): 1 agent [1]
|
||||
|
||||
Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**Decision logic**:
|
||||
- User confirms "y": Proceed with execution
|
||||
- User declines "n": Abort, no changes
|
||||
- <15 modules: Direct execution
|
||||
- ≥15 modules: Agent batch execution
|
||||
|
||||
## Phase 3A: Direct Execution (<15 modules)
|
||||
|
||||
**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
|
||||
|
||||
```javascript
|
||||
let modules_by_depth = group_by_depth(changed_modules);
|
||||
let tool_order = construct_tool_order(primary_tool);
|
||||
|
||||
for (let depth of sorted_depths.reverse()) { // N → 0
|
||||
let modules = modules_by_depth[depth];
|
||||
let batches = batch_modules(modules, 4); // Split into groups of 4
|
||||
|
||||
for (let batch of batches) {
|
||||
// Execute batch in parallel (max 4 concurrent)
|
||||
let parallel_tasks = batch.map(module => {
|
||||
return async () => {
|
||||
let success = false;
|
||||
for (let tool of tool_order) {
|
||||
let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
|
||||
if (exit_code === 0) {
|
||||
report("${module.path} updated with ${tool}");
|
||||
success = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!success) {
|
||||
report("FAILED: ${module.path} failed all tools");
|
||||
}
|
||||
};
|
||||
});
|
||||
|
||||
await Promise.all(parallel_tasks.map(task => task())); // Run batch in parallel
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- No agent startup overhead
|
||||
- Parallel execution within depth (max 4 concurrent)
|
||||
- Tool fallback still applies per module
|
||||
- Faster for small changesets (<15 modules)
|
||||
- Same batching strategy as Phase 3B but without agent layer
|
||||
|
||||
---
|
||||
|
||||
## Phase 3B: Agent Batch Execution (≥15 modules)
|
||||
|
||||
### Batching Strategy
|
||||
|
||||
```javascript
|
||||
// Batch modules into groups of 4
|
||||
function batch_modules(modules, batch_size = 4) {
|
||||
let batches = [];
|
||||
for (let i = 0; i < modules.length; i += batch_size) {
|
||||
batches.push(modules.slice(i, i + batch_size));
|
||||
}
|
||||
return batches;
|
||||
}
|
||||
// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
|
||||
```
|
||||
|
||||
### Coordinator Orchestration
|
||||
|
||||
```javascript
|
||||
let modules_by_depth = group_by_depth(changed_modules);
|
||||
let tool_order = construct_tool_order(primary_tool);
|
||||
|
||||
for (let depth of sorted_depths.reverse()) { // N → 0
|
||||
let batches = batch_modules(modules_by_depth[depth], 4);
|
||||
let worker_tasks = [];
|
||||
|
||||
for (let batch of batches) {
|
||||
worker_tasks.push(
|
||||
Task(
|
||||
subagent_type="memory-bridge",
|
||||
description=`Update ${batch.length} modules at depth ${depth}`,
|
||||
prompt=generate_batch_worker_prompt(batch, tool_order, "related")
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
await parallel_execute(worker_tasks); // Batches run in parallel
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Worker Prompt Template
|
||||
|
||||
```
|
||||
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
|
||||
|
||||
TASK:
|
||||
Update documentation for the following modules based on recent changes. For each module, try tools in order until success.
|
||||
|
||||
MODULES:
|
||||
{{module_path_1}}
|
||||
{{module_path_2}}
|
||||
{{module_path_3}}
|
||||
{{module_path_4}}
|
||||
|
||||
TOOLS (try in order):
|
||||
1. {{tool_1}}
|
||||
2. {{tool_2}}
|
||||
3. {{tool_3}}
|
||||
|
||||
EXECUTION:
|
||||
For each module above:
|
||||
1. cd "{{module_path}}"
|
||||
2. Try tool 1:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
|
||||
→ Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
|
||||
→ Failure: Try tool 2
|
||||
3. Try tool 2:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
|
||||
→ Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
|
||||
→ Failure: Try tool 3
|
||||
4. Try tool 3:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
|
||||
→ Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
|
||||
→ Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
|
||||
|
||||
REPORTING:
|
||||
Report final summary with:
|
||||
- Total processed: X modules
|
||||
- Successful: Y modules
|
||||
- Failed: Z modules
|
||||
- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
|
||||
- Detailed results for each module
|
||||
```
|
||||
|
||||
### Example Execution
|
||||
|
||||
**Depth 3 (new module)**:
|
||||
```javascript
|
||||
Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- 4 modules → 1 agent (75% reduction)
|
||||
- Parallel batches, sequential within batch
|
||||
- Each module gets full fallback chain
|
||||
- Context-aware updates based on git changes
|
||||
|
||||
## Phase 4: Safety Verification
|
||||
|
||||
```bash
|
||||
# Check only CLAUDE.md modified
|
||||
bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
|
||||
|
||||
# Display statistics
|
||||
bash(git diff --stat)
|
||||
```
|
||||
|
||||
**Aggregate results**:
|
||||
```
|
||||
Update Summary:
|
||||
Total: 4 | Success: 4 | Failed: 0
|
||||
|
||||
Tool usage:
|
||||
- gemini: 4 modules
|
||||
- qwen: 0 modules (fallback)
|
||||
- codex: 0 modules
|
||||
|
||||
Changes:
|
||||
src/api/auth/CLAUDE.md | 45 +++++++++++++++++++++
|
||||
src/api/CLAUDE.md | 23 +++++++++--
|
||||
src/CLAUDE.md | 12 ++++--
|
||||
CLAUDE.md | 8 ++--
|
||||
4 files changed, 82 insertions(+), 6 deletions(-)
|
||||
```
|
||||
|
||||
## Execution Summary
|
||||
|
||||
**Module Count Threshold**:
|
||||
- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
|
||||
- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
|
||||
|
||||
**Agent Hierarchy** (for ≥15 modules):
|
||||
- **Coordinator**: Handles batch division, spawns worker agents per depth
|
||||
- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Batch Worker**:
|
||||
- Tool fallback per module (auto-retry)
|
||||
- Batch isolation (failures don't propagate)
|
||||
- Clear per-module status reporting
|
||||
|
||||
**Coordinator**:
|
||||
- No changes: Use fallback (recent 10 modules)
|
||||
- User decline: No execution
|
||||
- Safety check fail: Auto-revert staging
|
||||
- Partial failures: Continue execution, report failed modules
|
||||
|
||||
**Fallback Triggers**:
|
||||
- Non-zero exit code
|
||||
- Script timeout
|
||||
- Unexpected output
|
||||
|
||||
## Tool Reference
|
||||
|
||||
| Tool | Best For | Fallback To |
|
||||
|--------|--------------------------------|----------------|
|
||||
| gemini | Documentation, patterns | qwen → codex |
|
||||
| qwen | Architecture, system design | gemini → codex |
|
||||
| codex | Implementation, code quality | gemini → qwen |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Daily development update
|
||||
/memory:update-related
|
||||
|
||||
# After feature work with specific tool
|
||||
/memory:update-related --tool qwen
|
||||
|
||||
# Code quality review after implementation
|
||||
/memory:update-related --tool codex
|
||||
```
|
||||
|
||||
## Key Advantages
|
||||
|
||||
**Efficiency**: 30 modules → 8 agents (73% reduction)
|
||||
**Resilience**: 3-tier fallback per module
|
||||
**Performance**: Parallel batches, no concurrency limits
|
||||
**Context-aware**: Updates based on actual git changes
|
||||
**Fast**: Only affected modules, not entire project
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
- Parse `--tool` (default: gemini)
|
||||
- Refresh code index for accurate change detection
|
||||
- Detect changed modules via detect_changed_modules.sh
|
||||
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
|
||||
- Cache git changes
|
||||
- Apply fallback if no changes (recent 10 modules)
|
||||
- Construct tool fallback order
|
||||
- **Present filtered plan** with skip reasons and change types
|
||||
- **Wait for y/n confirmation**
|
||||
- Determine execution mode:
|
||||
- **<15 modules**: Direct execution (Phase 3A)
|
||||
- For each depth (N→0): Sequential module updates with tool fallback
|
||||
- **≥15 modules**: Agent batch execution (Phase 3B)
|
||||
- For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
|
||||
- Wait for depth/batch completion
|
||||
- Aggregate results
|
||||
- Safety check (only CLAUDE.md modified)
|
||||
- Display git diff statistics + summary
|
||||
|
||||
## Comparison with Full Update
|
||||
|
||||
| Aspect | Related Update | Full Update |
|
||||
|--------|----------------|-------------|
|
||||
| **Scope** | Changed modules only | All project modules |
|
||||
| **Speed** | Fast (minutes) | Slower (10-30 min) |
|
||||
| **Use case** | Daily development | Major refactoring |
|
||||
| **Mode** | `"related"` | `"full"` |
|
||||
| **Trigger** | After commits | After major changes |
|
||||
| **Batching** | 4 modules/agent | 4 modules/agent |
|
||||
| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
|
||||
| **Complexity threshold** | ≤15 modules | ≤20 modules |
|
||||
@@ -0,0 +1,517 @@
|
||||
---
|
||||
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:
|
||||
cd .workflow/.archives/{session_id} && gemini -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
|
||||
"
|
||||
|
||||
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:
|
||||
gemini -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
|
||||
"
|
||||
|
||||
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