mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
refactor: reorganize memory commands and update brainstorm workflows
Changes: - Move memory commands to .claude/commands/memory/ directory - Relocate update-memory-full.md and update-memory-related.md - Add new docs.md command for documentation workflows - Update brainstorm commands (api-designer, data-architect, system-architect, ui-designer, ux-expert) - Remove deprecated workflow/tools/docs.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
828
.claude/commands/memory/docs.md
Normal file
828
.claude/commands/memory/docs.md
Normal file
@@ -0,0 +1,828 @@
|
||||
---
|
||||
name: docs
|
||||
description: Documentation planning and orchestration - creates structured documentation tasks for execution
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]"
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
**Documentation Output**: All generated documentation is placed in `.workflow/docs/` directory with **mirrored project structure**. For example:
|
||||
- Source: `src/modules/auth/index.ts` → Docs: `.workflow/docs/src/modules/auth/API.md`
|
||||
- Source: `lib/core/utils.js` → Docs: `.workflow/docs/lib/core/README.md`
|
||||
|
||||
**Two Execution Modes**:
|
||||
- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach`
|
||||
- **--cli-generate**: CLI generates docs in `implementation_approach` (MODE=write)
|
||||
|
||||
## Path Mirroring Strategy
|
||||
|
||||
**Principle**: Documentation structure **mirrors** source code structure.
|
||||
|
||||
| Source Path | Documentation Path |
|
||||
|------------|-------------------|
|
||||
| `src/modules/auth/index.ts` | `.workflow/docs/src/modules/auth/API.md` |
|
||||
| `src/modules/auth/middleware/` | `.workflow/docs/src/modules/auth/middleware/README.md` |
|
||||
| `lib/core/utils.js` | `.workflow/docs/lib/core/API.md` |
|
||||
| `lib/core/helpers/` | `.workflow/docs/lib/core/helpers/README.md` |
|
||||
|
||||
**Benefits**:
|
||||
- Easy to locate documentation for any source file
|
||||
- Maintains logical organization
|
||||
- Clear 1:1 mapping between code and docs
|
||||
- Supports any project structure (src/, lib/, packages/, etc.)
|
||||
|
||||
## Parameters
|
||||
|
||||
```bash
|
||||
/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]
|
||||
```
|
||||
|
||||
- **path**: Target directory (default: current directory)
|
||||
- Specifies the directory to generate documentation for
|
||||
|
||||
- **--mode**: Documentation generation mode (default: full)
|
||||
- `full`: Complete documentation (modules + project README + ARCHITECTURE + EXAMPLES)
|
||||
- Level 1: Module tree documentation
|
||||
- Level 2: Project README.md
|
||||
- Level 3: ARCHITECTURE.md + EXAMPLES.md + HTTP API (optional)
|
||||
- `partial`: Module documentation only
|
||||
- Level 1: Module tree documentation (API.md + README.md)
|
||||
- Skips project-level documentation
|
||||
|
||||
- **--tool**: CLI tool selection (default: gemini)
|
||||
- `gemini`: Comprehensive documentation, pattern recognition
|
||||
- `qwen`: Architecture analysis, system design focus
|
||||
- `codex`: Implementation validation, code quality
|
||||
|
||||
- **--cli-generate**: Enable CLI-based documentation generation (optional)
|
||||
- When enabled: CLI generates docs with MODE=write in implementation_approach
|
||||
- When disabled (default): CLI analyzes with MODE=analysis in pre_analysis
|
||||
|
||||
## Planning Workflow
|
||||
|
||||
### Phase 1: Initialize Session
|
||||
|
||||
#### Step 1: Create Session and Generate Config
|
||||
```bash
|
||||
# Create session structure and initialize config in one step
|
||||
bash(
|
||||
# Parse arguments
|
||||
path="${1:-.}"
|
||||
tool="gemini"
|
||||
mode="full"
|
||||
cli_generate=false
|
||||
shift
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--tool) tool="$2"; shift 2 ;;
|
||||
--mode) mode="$2"; shift 2 ;;
|
||||
--cli-generate) cli_generate=true; shift ;;
|
||||
*) shift ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Detect paths
|
||||
project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then
|
||||
target_path="$path"
|
||||
else
|
||||
target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
|
||||
fi
|
||||
|
||||
# Create session
|
||||
timestamp=$(date +%Y%m%d-%H%M%S)
|
||||
session="WFS-docs-${timestamp}"
|
||||
mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
|
||||
touch ".workflow/.active-${session}"
|
||||
|
||||
# Generate single config file with all info
|
||||
cat > ".workflow/${session}/.process/config.json" <<EOF
|
||||
{
|
||||
"session_id": "${session}",
|
||||
"timestamp": "$(date -Iseconds)",
|
||||
"path": "${path}",
|
||||
"target_path": "${target_path}",
|
||||
"project_root": "${project_root}",
|
||||
"mode": "${mode}",
|
||||
"tool": "${tool}",
|
||||
"cli_generate": ${cli_generate}
|
||||
}
|
||||
EOF
|
||||
|
||||
echo "✓ Session initialized: ${session}"
|
||||
echo "✓ Target: ${target_path}"
|
||||
echo "✓ Mode: ${mode}"
|
||||
echo "✓ Tool: ${tool}, CLI generate: ${cli_generate}"
|
||||
)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
✓ Session initialized: WFS-docs-20240120-143022
|
||||
✓ Target: /d/Claude_dms3
|
||||
✓ Mode: full
|
||||
✓ Tool: gemini, CLI generate: false
|
||||
```
|
||||
|
||||
### Phase 2: Analyze Structure
|
||||
|
||||
#### Step 1: Discover and Classify Folders
|
||||
```bash
|
||||
# Run analysis pipeline (module discovery + folder classification)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
|
||||
```
|
||||
|
||||
**Output Sample** (folder-analysis.txt):
|
||||
```
|
||||
./src/modules/auth|code|code:5|dirs:2
|
||||
./src/modules/api|code|code:3|dirs:0
|
||||
./src/utils|navigation|code:0|dirs:4
|
||||
```
|
||||
|
||||
#### Step 2: Extract Top-Level Directories
|
||||
```bash
|
||||
# Group folders by top-level directory
|
||||
bash(awk -F'|' '{
|
||||
path = $1
|
||||
gsub(/^\.\//, "", path)
|
||||
split(path, parts, "/")
|
||||
if (length(parts) >= 2) print parts[1] "/" parts[2]
|
||||
else if (length(parts) == 1 && parts[1] != ".") print parts[1]
|
||||
}' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | sort -u > .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
|
||||
```
|
||||
|
||||
**Output** (top-level-dirs.txt):
|
||||
```
|
||||
src/modules
|
||||
src/utils
|
||||
lib/core
|
||||
```
|
||||
|
||||
#### Step 3: Generate Analysis Summary
|
||||
```bash
|
||||
# Calculate statistics
|
||||
bash(
|
||||
total=$(wc -l < .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
|
||||
code_count=$(grep '|code|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
|
||||
nav_count=$(grep '|navigation|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
|
||||
top_dirs=$(wc -l < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
|
||||
|
||||
echo "📊 Folder Analysis Complete:"
|
||||
echo " - Total folders: $total"
|
||||
echo " - Code folders: $code_count"
|
||||
echo " - Navigation folders: $nav_count"
|
||||
echo " - Top-level dirs: $top_dirs"
|
||||
)
|
||||
|
||||
# Update config with statistics
|
||||
bash(jq '. + {analysis: {total: "15", code: "8", navigation: "7", top_level: "3"}}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json)
|
||||
```
|
||||
|
||||
### Phase 3: Detect Update Mode
|
||||
|
||||
#### Step 1: Count Existing Documentation in .workflow/docs/
|
||||
```bash
|
||||
# Check .workflow/docs/ directory and count existing files
|
||||
bash(if [[ -d ".workflow/docs" ]]; then
|
||||
find .workflow/docs -name "*.md" 2>/dev/null | wc -l
|
||||
else
|
||||
echo "0"
|
||||
fi)
|
||||
```
|
||||
|
||||
**Output**: `5` (existing docs in .workflow/docs/)
|
||||
|
||||
#### Step 2: List Existing Documentation
|
||||
```bash
|
||||
# List existing files in .workflow/docs/ (for task context)
|
||||
bash(if [[ -d ".workflow/docs" ]]; then
|
||||
find .workflow/docs -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt
|
||||
else
|
||||
touch .workflow/WFS-docs-20240120/.process/existing-docs.txt
|
||||
fi)
|
||||
```
|
||||
|
||||
**Output** (existing-docs.txt):
|
||||
```
|
||||
.workflow/docs/src/modules/auth/API.md
|
||||
.workflow/docs/src/modules/auth/README.md
|
||||
.workflow/docs/lib/core/README.md
|
||||
.workflow/docs/README.md
|
||||
```
|
||||
|
||||
#### Step 3: Update Config with Update Status
|
||||
```bash
|
||||
# Determine update status (create or update) and update config
|
||||
bash(
|
||||
existing_count=$(find .workflow/docs -name "*.md" 2>/dev/null | wc -l)
|
||||
if [[ $existing_count -gt 0 ]]; then
|
||||
jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
|
||||
else
|
||||
jq '. + {update_mode: "create", existing_docs: 0}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
|
||||
fi
|
||||
)
|
||||
|
||||
# Display strategy summary
|
||||
bash(
|
||||
mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
update_mode=$(jq -r '.update_mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
existing=$(jq -r '.existing_docs' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
cli_gen=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
echo "📋 Documentation Strategy:"
|
||||
echo " - Path: $(jq -r '.target_path' .workflow/WFS-docs-20240120/.process/config.json)"
|
||||
echo " - Mode: $mode ($([ "$mode" = "full" ] && echo "complete docs" || echo "modules only"))"
|
||||
echo " - Update: $update_mode ($existing existing files)"
|
||||
echo " - Tool: $tool, CLI generate: $cli_gen"
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 4: Decompose Tasks
|
||||
|
||||
#### Task Hierarchy
|
||||
```
|
||||
Level 1: Module Trees (always, parallel execution)
|
||||
├─ IMPL-001: Document 'src/modules/'
|
||||
├─ IMPL-002: Document 'src/utils/'
|
||||
└─ IMPL-003: Document 'lib/'
|
||||
|
||||
Level 2: Project README (mode=full only, depends on Level 1)
|
||||
└─ IMPL-004: Generate Project README
|
||||
|
||||
Level 3: Architecture & Examples (mode=full only, depends on Level 2)
|
||||
├─ IMPL-005: Generate ARCHITECTURE.md + EXAMPLES.md
|
||||
└─ IMPL-006: Generate HTTP API (optional)
|
||||
```
|
||||
|
||||
#### Step 1: Generate Level 1 Tasks (Module Trees)
|
||||
```bash
|
||||
# Read top-level directories and create tasks
|
||||
bash(
|
||||
task_count=0
|
||||
while read -r top_dir; do
|
||||
task_count=$((task_count + 1))
|
||||
task_id=$(printf "IMPL-%03d" $task_count)
|
||||
echo "Creating $task_id for '$top_dir'"
|
||||
# Generate task JSON (see Task Templates section)
|
||||
done < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt
|
||||
)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
Creating IMPL-001 for 'src/modules'
|
||||
Creating IMPL-002 for 'src/utils'
|
||||
Creating IMPL-003 for 'lib'
|
||||
```
|
||||
|
||||
#### Step 2: Generate Level 2-3 Tasks (Full Mode Only)
|
||||
```bash
|
||||
# Check documentation mode
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
# If full mode, create project-level tasks
|
||||
bash(
|
||||
mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
if [[ "$mode" == "full" ]]; then
|
||||
echo "Creating IMPL-004: Project README"
|
||||
echo "Creating IMPL-005: ARCHITECTURE.md + EXAMPLES.md"
|
||||
# Optional: Check for HTTP API endpoints
|
||||
if grep -r "router\.|@Get\|@Post" src/ >/dev/null 2>&1; then
|
||||
echo "Creating IMPL-006: HTTP API docs"
|
||||
fi
|
||||
else
|
||||
echo "Partial mode: Skipping project-level tasks"
|
||||
fi
|
||||
)
|
||||
```
|
||||
|
||||
### Phase 5: Generate Task JSONs
|
||||
|
||||
#### Step 1: Extract Configuration
|
||||
```bash
|
||||
# Read config values from JSON
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
```
|
||||
|
||||
**Output**: `tool=gemini`, `cli_generate=false`
|
||||
|
||||
#### Step 2: Determine CLI Command Strategy
|
||||
```bash
|
||||
# Determine MODE and placement based on cli_generate flag
|
||||
bash(
|
||||
cli_generate=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
if [[ "$cli_generate" == "true" ]]; then
|
||||
echo "mode=write"
|
||||
echo "placement=implementation_approach"
|
||||
echo "approval_flag=--approval-mode yolo"
|
||||
else
|
||||
echo "mode=analysis"
|
||||
echo "placement=pre_analysis"
|
||||
echo "approval_flag="
|
||||
fi
|
||||
)
|
||||
```
|
||||
|
||||
**Output**:
|
||||
```
|
||||
mode=analysis
|
||||
placement=pre_analysis
|
||||
approval_flag=
|
||||
```
|
||||
|
||||
#### Step 3: Build Tool-Specific Commands
|
||||
```bash
|
||||
# Generate command templates based on tool selection
|
||||
bash(
|
||||
tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
if [[ "$tool" == "codex" ]]; then
|
||||
echo "codex -C \${dir} --full-auto exec \"...\" --skip-git-repo-check -s danger-full-access"
|
||||
else
|
||||
echo "bash(cd \${dir} && ~/.claude/scripts/${tool}-wrapper ${approval_flag} -p \"...\")"
|
||||
fi
|
||||
)
|
||||
```
|
||||
|
||||
## Task Templates
|
||||
|
||||
### Level 1: Module Tree Task
|
||||
|
||||
**Path Mapping**: Source `src/modules/` → Output `.workflow/docs/src/modules/`
|
||||
|
||||
**Default Mode (cli_generate=false)**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Document Module Tree: 'src/modules/'",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs-tree",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_generate": false,
|
||||
"source_path": "src/modules",
|
||||
"output_path": ".workflow/docs/src/modules"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Analyze source code in src/modules/",
|
||||
"Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
|
||||
"For code folders: generate API.md + README.md",
|
||||
"For navigation folders: generate README.md only"
|
||||
],
|
||||
"focus_paths": ["src/modules"],
|
||||
"folder_analysis_file": "${session_dir}/.process/folder-analysis.txt"
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_existing_docs",
|
||||
"command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
|
||||
"output_to": "existing_module_docs"
|
||||
},
|
||||
{
|
||||
"step": "load_folder_analysis",
|
||||
"command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
|
||||
"output_to": "target_folders"
|
||||
},
|
||||
{
|
||||
"step": "analyze_module_tree",
|
||||
"command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
|
||||
"output_to": "tree_outline",
|
||||
"note": "CLI for analysis only"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate module tree documentation",
|
||||
"description": "Analyze source folders and generate docs to .workflow/docs/ with mirrored structure",
|
||||
"modification_points": [
|
||||
"Parse folder types from [target_folders]",
|
||||
"Parse structure from [tree_outline]",
|
||||
"For src/modules/auth/ → write to .workflow/docs/src/modules/auth/",
|
||||
"Generate API.md for code folders",
|
||||
"Generate README.md for all folders"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Parse [target_folders] to get folder types",
|
||||
"Parse [tree_outline] for structure",
|
||||
"For each folder in source:",
|
||||
" - Map source_path to .workflow/docs/{source_path}",
|
||||
" - If type == 'code': Generate API.md + README.md",
|
||||
" - Elif type == 'navigation': Generate README.md only"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "module_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${top_dir}/*/API.md",
|
||||
".workflow/docs/${top_dir}/*/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CLI Generate Mode (cli_generate=true)**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Document Module Tree: 'src/modules/'",
|
||||
"status": "pending",
|
||||
"meta": {
|
||||
"type": "docs-tree",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_generate": true,
|
||||
"source_path": "src/modules",
|
||||
"output_path": ".workflow/docs/src/modules"
|
||||
},
|
||||
"context": {
|
||||
"requirements": [
|
||||
"Analyze source code in src/modules/",
|
||||
"Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
|
||||
"CLI generates documentation files directly"
|
||||
],
|
||||
"focus_paths": ["src/modules"]
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_existing_docs",
|
||||
"command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
|
||||
"output_to": "existing_module_docs"
|
||||
},
|
||||
{
|
||||
"step": "load_folder_analysis",
|
||||
"command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
|
||||
"output_to": "target_folders"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Parse folder analysis",
|
||||
"description": "Parse [target_folders] to get folder types and structure",
|
||||
"modification_points": ["Extract folder types", "Identify code vs navigation folders"],
|
||||
"logic_flow": ["Parse [target_folders] to get folder types", "Prepare folder list for CLI generation"],
|
||||
"depends_on": [],
|
||||
"output": "folder_types"
|
||||
},
|
||||
{
|
||||
"step": 2,
|
||||
"title": "Generate documentation via CLI",
|
||||
"description": "Call CLI to generate docs to .workflow/docs/ with mirrored structure using MODE=write",
|
||||
"modification_points": [
|
||||
"Execute CLI generation command",
|
||||
"Generate files to .workflow/docs/src/modules/ (mirrored path)",
|
||||
"Generate API.md and README.md files"
|
||||
],
|
||||
"logic_flow": [
|
||||
"CLI analyzes source code in src/modules/",
|
||||
"CLI writes documentation to .workflow/docs/src/modules/",
|
||||
"Maintains directory structure mirroring"
|
||||
],
|
||||
"command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
|
||||
"depends_on": [1],
|
||||
"output": "generated_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/${top_dir}/*/API.md",
|
||||
".workflow/docs/${top_dir}/*/README.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Project README Task
|
||||
|
||||
**Default Mode**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-004",
|
||||
"title": "Generate Project README",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_generate": false
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_existing_readme",
|
||||
"command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')",
|
||||
"output_to": "existing_readme"
|
||||
},
|
||||
{
|
||||
"step": "load_module_docs",
|
||||
"command": "bash(find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
|
||||
"output_to": "all_module_docs",
|
||||
"note": "Load all module docs from mirrored structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_project",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"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 existing user modifications",
|
||||
"modification_points": ["Parse [project_outline] and [all_module_docs]", "Generate project README structure", "Add navigation links to modules", "Preserve [existing_readme] user modifications"],
|
||||
"logic_flow": ["Parse [project_outline] and [all_module_docs]", "Generate project README with navigation links", "Preserve [existing_readme] user modifications"],
|
||||
"depends_on": [],
|
||||
"output": "project_readme"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: Architecture & Examples Documentation Task
|
||||
|
||||
**Default Mode**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-005",
|
||||
"title": "Generate Architecture & Examples Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-004"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_generate": false
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "load_existing_docs",
|
||||
"command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE'; echo '---SEPARATOR---'; cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
|
||||
"output_to": "existing_arch_examples"
|
||||
},
|
||||
{
|
||||
"step": "load_all_docs",
|
||||
"command": "bash(cat .workflow/docs/README.md && find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
|
||||
"output_to": "all_docs",
|
||||
"note": "Load README + all module docs from mirrored structure"
|
||||
},
|
||||
{
|
||||
"step": "analyze_architecture_and_examples",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
|
||||
"output_to": "arch_examples_outline"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate architecture and examples documentation",
|
||||
"description": "Generate ARCHITECTURE.md and EXAMPLES.md while preserving existing user modifications",
|
||||
"modification_points": [
|
||||
"Parse [arch_examples_outline] and [all_docs]",
|
||||
"Generate ARCHITECTURE.md structure with system design and patterns",
|
||||
"Generate EXAMPLES.md structure with code snippets and usage examples",
|
||||
"Preserve [existing_arch_examples] user modifications"
|
||||
],
|
||||
"logic_flow": [
|
||||
"Parse [arch_examples_outline] and [all_docs]",
|
||||
"Generate ARCHITECTURE.md with system design",
|
||||
"Generate EXAMPLES.md with code snippets",
|
||||
"Preserve [existing_arch_examples] modifications"
|
||||
],
|
||||
"depends_on": [],
|
||||
"output": "arch_examples_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [
|
||||
".workflow/docs/ARCHITECTURE.md",
|
||||
".workflow/docs/EXAMPLES.md"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Level 3: HTTP API Documentation Task (Optional)
|
||||
|
||||
**Default Mode**:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-006",
|
||||
"title": "Generate HTTP API Documentation",
|
||||
"status": "pending",
|
||||
"depends_on": ["IMPL-004"],
|
||||
"meta": {
|
||||
"type": "docs",
|
||||
"agent": "@doc-generator",
|
||||
"tool": "gemini",
|
||||
"cli_generate": false
|
||||
},
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"step": "discover_api_endpoints",
|
||||
"command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')",
|
||||
"output_to": "endpoint_discovery"
|
||||
},
|
||||
{
|
||||
"step": "load_existing_api_docs",
|
||||
"command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')",
|
||||
"output_to": "existing_api_docs"
|
||||
},
|
||||
{
|
||||
"step": "analyze_api",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @{src/api/**/*} [endpoint_discovery]\\nEXPECTED: API outline\")",
|
||||
"output_to": "api_outline"
|
||||
}
|
||||
],
|
||||
"implementation_approach": [
|
||||
{
|
||||
"step": 1,
|
||||
"title": "Generate HTTP API documentation",
|
||||
"description": "Generate HTTP API documentation while preserving existing user modifications",
|
||||
"modification_points": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Document endpoints and request/response formats", "Preserve [existing_api_docs] modifications"],
|
||||
"logic_flow": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Preserve [existing_api_docs] modifications"],
|
||||
"depends_on": [],
|
||||
"output": "api_docs"
|
||||
}
|
||||
],
|
||||
"target_files": [".workflow/docs/api/README.md"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/
|
||||
├── .active-WFS-docs-20240120-143022 # Active session marker
|
||||
└── WFS-docs-20240120-143022/
|
||||
├── IMPL_PLAN.md # Implementation plan
|
||||
├── TODO_LIST.md # Progress tracker
|
||||
├── .process/
|
||||
│ ├── config.json # Single config (all settings + stats)
|
||||
│ ├── folder-analysis.txt # Folder classification results
|
||||
│ ├── top-level-dirs.txt # Top-level directory list
|
||||
│ └── existing-docs.txt # Existing documentation paths
|
||||
└── .task/
|
||||
├── IMPL-001.json # Module tree task
|
||||
├── IMPL-002.json # Module tree task
|
||||
├── IMPL-003.json # Module tree task
|
||||
├── IMPL-004.json # Project README (full mode)
|
||||
├── IMPL-005.json # ARCHITECTURE.md + EXAMPLES.md (full mode)
|
||||
└── IMPL-006.json # HTTP API docs (optional)
|
||||
```
|
||||
|
||||
**Config File Structure** (config.json):
|
||||
```json
|
||||
{
|
||||
"session_id": "WFS-docs-20240120-143022",
|
||||
"timestamp": "2024-01-20T14:30:22+08:00",
|
||||
"path": ".",
|
||||
"target_path": "/d/Claude_dms3",
|
||||
"project_root": "/d/Claude_dms3",
|
||||
"mode": "full",
|
||||
"tool": "gemini",
|
||||
"cli_generate": false,
|
||||
"update_mode": "update",
|
||||
"existing_docs": 5,
|
||||
"analysis": {
|
||||
"total": "15",
|
||||
"code": "8",
|
||||
"navigation": "7",
|
||||
"top_level": "3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Generated Documentation
|
||||
|
||||
**Structure mirrors project source directories**:
|
||||
|
||||
```
|
||||
.workflow/docs/
|
||||
├── src/ # Mirrors src/ directory
|
||||
│ ├── modules/ # Level 1 output
|
||||
│ │ ├── README.md # Navigation for src/modules/
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── API.md # Auth module API signatures
|
||||
│ │ │ ├── README.md # Auth module documentation
|
||||
│ │ │ └── middleware/
|
||||
│ │ │ ├── API.md # Middleware API
|
||||
│ │ │ └── README.md # Middleware docs
|
||||
│ │ └── api/
|
||||
│ │ ├── API.md # API module signatures
|
||||
│ │ └── README.md # API module docs
|
||||
│ └── utils/ # Level 1 output
|
||||
│ └── README.md # Utils navigation
|
||||
├── lib/ # Mirrors lib/ directory
|
||||
│ └── core/
|
||||
│ ├── API.md
|
||||
│ └── README.md
|
||||
├── README.md # Level 2 output (root only)
|
||||
├── ARCHITECTURE.md # Level 3 output (root only)
|
||||
├── EXAMPLES.md # Level 3 output (root only)
|
||||
└── api/ # Level 3 output (optional)
|
||||
└── README.md # HTTP API reference
|
||||
```
|
||||
|
||||
## Execution Commands
|
||||
|
||||
### Full Mode (--mode full)
|
||||
```bash
|
||||
# Level 1 - Module documentation (parallel)
|
||||
/workflow:execute IMPL-001
|
||||
/workflow:execute IMPL-002
|
||||
/workflow:execute IMPL-003
|
||||
|
||||
# Level 2 - Project README (after Level 1)
|
||||
/workflow:execute IMPL-004
|
||||
|
||||
# Level 3 - Architecture & Examples (after Level 2)
|
||||
/workflow:execute IMPL-005 # ARCHITECTURE.md + EXAMPLES.md
|
||||
/workflow:execute IMPL-006 # HTTP API (if present)
|
||||
```
|
||||
|
||||
### Partial Mode (--mode partial)
|
||||
```bash
|
||||
# Only Level 1 tasks generated (module documentation)
|
||||
/workflow:execute IMPL-001
|
||||
/workflow:execute IMPL-002
|
||||
/workflow:execute IMPL-003
|
||||
```
|
||||
|
||||
## Simple Bash Commands
|
||||
|
||||
### Session Management
|
||||
```bash
|
||||
# Create session and initialize config (all in one)
|
||||
bash(
|
||||
session="WFS-docs-$(date +%Y%m%d-%H%M%S)"
|
||||
mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
|
||||
touch ".workflow/.active-${session}"
|
||||
cat > ".workflow/${session}/.process/config.json" <<EOF
|
||||
{"session_id":"${session}","timestamp":"$(date -Iseconds)","path":".","mode":"full","tool":"gemini","cli_generate":false}
|
||||
EOF
|
||||
echo "Session: ${session}"
|
||||
)
|
||||
|
||||
# Read session config
|
||||
bash(cat .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
# Extract config values
|
||||
bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
|
||||
|
||||
# List session tasks
|
||||
bash(ls .workflow/WFS-docs-20240120/.task/*.json)
|
||||
```
|
||||
|
||||
### Analysis Commands
|
||||
```bash
|
||||
# Discover and classify folders (scans project source)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
|
||||
|
||||
# Count existing docs (in .workflow/docs/ directory)
|
||||
bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi)
|
||||
|
||||
# List existing documentation (in .workflow/docs/ directory)
|
||||
bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null; fi)
|
||||
```
|
||||
|
||||
## Template Reference
|
||||
|
||||
**Available Templates**:
|
||||
- `api.txt`: Unified template for Code API (Part A) and 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, module navigation
|
||||
- `project-architecture.txt`: System structure, module map, design patterns
|
||||
- `project-examples.txt`: End-to-end usage examples
|
||||
|
||||
**Template Location**: `~/.claude/workflows/cli-templates/prompts/documentation/`
|
||||
|
||||
## CLI Generate Mode Summary
|
||||
|
||||
| Mode | CLI Placement | CLI MODE | Agent Role |
|
||||
|------|---------------|----------|------------|
|
||||
| **Default** | pre_analysis | analysis | Generates documentation files |
|
||||
| **--cli-generate** | implementation_approach | write | Validates and coordinates CLI output |
|
||||
|
||||
## Related Commands
|
||||
- `/workflow:execute` - Execute documentation tasks
|
||||
- `/workflow:status` - View task progress
|
||||
- `/workflow:session:complete` - Mark session complete
|
||||
330
.claude/commands/memory/update-memory-full.md
Normal file
330
.claude/commands/memory/update-memory-full.md
Normal file
@@ -0,0 +1,330 @@
|
||||
---
|
||||
name: update-full
|
||||
description: Complete project-wide CLAUDE.md documentation update
|
||||
argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
|
||||
---
|
||||
|
||||
# Full Documentation Update (/memory:update-full)
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection.
|
||||
|
||||
**Execution Model**:
|
||||
|
||||
1. **Initial Analysis**: Cache git changes, discover module structure
|
||||
2. **Complexity Detection**: Analyze module count, determine strategy
|
||||
3. **Plan Presentation**: Show user exactly what will be updated
|
||||
4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest)
|
||||
5. **Safety Verification**: Ensure only CLAUDE.md files modified
|
||||
|
||||
**Tool Selection**:
|
||||
- `--tool gemini` (default): Documentation generation, pattern recognition
|
||||
- `--tool qwen`: Architecture analysis, system design docs
|
||||
- `--tool codex`: Implementation validation, code quality analysis
|
||||
|
||||
**Path Parameter**:
|
||||
- `--path <directory>` (optional): Target specific directory for updates
|
||||
- If not specified: Updates entire project from current directory
|
||||
- If specified: Changes to target directory before discovery
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Analyze First**: Run git cache and module discovery before any updates
|
||||
2. **Scope Control**: Use --path to target specific directories, default is entire project
|
||||
3. **Wait for Approval**: Present plan, no execution without user confirmation
|
||||
4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
|
||||
5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
|
||||
6. **Independent Commands**: Each update is a separate bash() call
|
||||
7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Phase 1: Discovery & Analysis
|
||||
|
||||
**Cache git changes:**
|
||||
```bash
|
||||
bash(git add -A 2>/dev/null || true)
|
||||
```
|
||||
|
||||
**Get module structure:**
|
||||
|
||||
*If no --path parameter:*
|
||||
```bash
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
```
|
||||
|
||||
*If --path parameter specified:*
|
||||
```bash
|
||||
bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
```
|
||||
|
||||
**Example with path:**
|
||||
```bash
|
||||
# Update only .claude directory
|
||||
bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
|
||||
# Update specific feature directory
|
||||
bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list)
|
||||
```
|
||||
|
||||
**Parse Output**:
|
||||
- Extract module paths from `depth:N|path:<PATH>|...` format
|
||||
- Count total modules
|
||||
- Identify which modules have/need CLAUDE.md
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no
|
||||
depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no
|
||||
depth:3|path:./.claude/commands/cli|files:6|has_claude:no
|
||||
depth:0|path:.|files:14|has_claude:yes
|
||||
```
|
||||
|
||||
**Validation**:
|
||||
- If --path specified, directory exists and is accessible
|
||||
- Module list contains depth and path information
|
||||
- At least one module exists
|
||||
- All paths are relative to target directory (if --path used)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Plan Presentation
|
||||
|
||||
**Decision Logic**:
|
||||
- **Simple projects (≤20 modules)**: Present plan to user, wait for approval
|
||||
- **Complex projects (>20 modules)**: Delegate to memory-bridge agent
|
||||
|
||||
**Plan format:**
|
||||
```
|
||||
📋 Update Plan:
|
||||
Tool: gemini
|
||||
Total modules: 31
|
||||
|
||||
NEW CLAUDE.md files (30):
|
||||
- ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
|
||||
- ./.claude/commands/cli/mode/CLAUDE.md
|
||||
- ... (28 more)
|
||||
|
||||
UPDATE existing CLAUDE.md files (1):
|
||||
- ./CLAUDE.md
|
||||
|
||||
⚠️ Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**User Confirmation Required**: No execution without explicit approval
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Depth-Parallel Execution
|
||||
|
||||
**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
|
||||
|
||||
**Command structure:**
|
||||
```bash
|
||||
bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
|
||||
```
|
||||
|
||||
**Example - Depth 5 (8 modules):**
|
||||
```bash
|
||||
bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
```bash
|
||||
bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
```bash
|
||||
bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
```bash
|
||||
bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
|
||||
*Wait for depth 5 completion...*
|
||||
|
||||
**Example - Depth 4 (7 modules):**
|
||||
```bash
|
||||
bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
```bash
|
||||
bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
|
||||
*Continue for remaining depths (3 → 2 → 1 → 0)...*
|
||||
|
||||
**Execution Rules**:
|
||||
- Each command is separate bash() call
|
||||
- Up to 4 concurrent jobs per depth
|
||||
- Wait for all jobs in current depth before proceeding
|
||||
- Extract path from `depth:N|path:<PATH>|...` format
|
||||
- All paths relative to target directory (current dir or --path value)
|
||||
|
||||
**Path Context**:
|
||||
- Without --path: Paths relative to current directory
|
||||
- With --path: Paths relative to specified target directory
|
||||
- Module discovery runs in target directory context
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Safety Verification
|
||||
|
||||
**Check modified files:**
|
||||
```bash
|
||||
bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
✅ Only CLAUDE.md files modified
|
||||
```
|
||||
|
||||
**If non-CLAUDE.md files detected:**
|
||||
```
|
||||
⚠️ Warning: Non-CLAUDE.md files were modified
|
||||
Modified files: src/index.ts, package.json
|
||||
→ Run: git restore --staged .
|
||||
```
|
||||
|
||||
**Display final status:**
|
||||
```bash
|
||||
bash(git status --short)
|
||||
```
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
A .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
|
||||
A .claude/commands/cli/mode/CLAUDE.md
|
||||
M CLAUDE.md
|
||||
... (30 more files)
|
||||
```
|
||||
|
||||
## Command Pattern Reference
|
||||
|
||||
**Single module update:**
|
||||
```bash
|
||||
bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
|
||||
```
|
||||
|
||||
**Components**:
|
||||
- `cd <module-path>` - Navigate to module (from `path:` field)
|
||||
- `&&` - Ensure cd succeeds
|
||||
- `update_module_claude.sh` - Update script
|
||||
- `"."` - Current directory
|
||||
- `"full"` - Full update mode
|
||||
- `"<tool>"` - gemini/qwen/codex
|
||||
- `&` - Background execution
|
||||
|
||||
**Path extraction:**
|
||||
```bash
|
||||
# From: depth:5|path:./src/auth|files:10|has_claude:no
|
||||
# Extract: ./src/auth
|
||||
# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
|
||||
```
|
||||
|
||||
## Complex Projects Strategy
|
||||
|
||||
For projects >20 modules, delegate to memory-bridge agent:
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="memory-bridge",
|
||||
description="Complex project full update",
|
||||
prompt=`
|
||||
CONTEXT:
|
||||
- Total modules: ${module_count}
|
||||
- Tool: ${tool}
|
||||
- Mode: full
|
||||
|
||||
MODULE LIST:
|
||||
${modules_output}
|
||||
|
||||
REQUIREMENTS:
|
||||
1. Use TodoWrite to track each depth level
|
||||
2. Process depths N→0 sequentially, max 4 parallel per depth
|
||||
3. Command: cd "<path>" && update_module_claude.sh "." "full" "${tool}" &
|
||||
4. Extract path from "depth:N|path:<PATH>|..." format
|
||||
5. Verify all modules processed
|
||||
6. Run safety check
|
||||
7. Display git status
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution
|
||||
- **Module discovery failure**: Report error, abort execution
|
||||
- **User declines approval**: Abort execution, no changes made
|
||||
- **Safety check failure**: Automatic staging revert, report modified files
|
||||
- **Update script failure**: Report failed modules, continue with remaining
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
✅ Parse `--tool` parameter (default: gemini)
|
||||
✅ Parse `--path` parameter (optional, default: current directory)
|
||||
✅ Execute git cache in current directory
|
||||
✅ Execute module discovery (with cd if --path specified)
|
||||
✅ Parse module list, count total modules
|
||||
✅ Determine strategy based on module count (≤20 vs >20)
|
||||
✅ Present plan with exact file paths
|
||||
✅ **Wait for user confirmation** (simple projects only)
|
||||
✅ Organize modules by depth
|
||||
✅ For each depth (highest to lowest):
|
||||
- Launch up to 5 parallel updates
|
||||
- Wait for depth completion
|
||||
- Proceed to next depth
|
||||
✅ Run safety check after all updates
|
||||
✅ Display git status
|
||||
✅ Report completion summary
|
||||
|
||||
|
||||
|
||||
## Tool Parameter Reference
|
||||
|
||||
**Gemini** (default):
|
||||
- Best for: Documentation generation, pattern recognition, architecture review
|
||||
- Context window: Large, handles complex codebases
|
||||
- Output style: Comprehensive, detailed explanations
|
||||
|
||||
**Qwen**:
|
||||
- Best for: Architecture analysis, system design documentation
|
||||
- Context window: Large, similar to Gemini
|
||||
- Output style: Structured, systematic analysis
|
||||
|
||||
**Codex**:
|
||||
- Best for: Implementation validation, code quality analysis
|
||||
- Capabilities: Mathematical reasoning, autonomous development
|
||||
- Output style: Technical, implementation-focused
|
||||
|
||||
## Path Parameter Reference
|
||||
|
||||
**Use Cases**:
|
||||
|
||||
**Update configuration directory only:**
|
||||
```bash
|
||||
/memory:update-full --path .claude
|
||||
```
|
||||
- Updates only .claude directory and subdirectories
|
||||
- Useful after workflow or command modifications
|
||||
- Faster than full project update
|
||||
|
||||
**Update specific feature module:**
|
||||
```bash
|
||||
/memory:update-full --path src/features/auth
|
||||
```
|
||||
- Updates authentication feature and sub-modules
|
||||
- Ideal for feature-specific documentation
|
||||
- Isolates scope for targeted updates
|
||||
|
||||
**Update nested structure:**
|
||||
```bash
|
||||
/memory:update-full --path .claude/workflows/cli-templates
|
||||
```
|
||||
- Updates deeply nested directory tree
|
||||
- Maintains relative path structure in output
|
||||
- All module paths relative to specified directory
|
||||
|
||||
**Best Practices**:
|
||||
- Use `--path` when working on specific features/modules
|
||||
- Omit `--path` for project-wide architectural changes
|
||||
- Combine with `--tool` for specialized documentation needs
|
||||
- Verify directory exists before execution (automatic validation)
|
||||
306
.claude/commands/memory/update-memory-related.md
Normal file
306
.claude/commands/memory/update-memory-related.md
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
name: update-related
|
||||
description: Context-aware CLAUDE.md documentation updates based on recent changes
|
||||
argument-hint: "[--tool gemini|qwen|codex]"
|
||||
---
|
||||
|
||||
# Related Documentation Update (/memory:update-related)
|
||||
|
||||
## Coordinator Role
|
||||
|
||||
**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection.
|
||||
|
||||
**Execution Model**:
|
||||
|
||||
1. **Change Detection**: Analyze git changes to identify affected modules
|
||||
2. **Complexity Analysis**: Evaluate change count and determine strategy
|
||||
3. **Plan Presentation**: Show user which modules need updates
|
||||
4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest)
|
||||
5. **Safety Verification**: Ensure only CLAUDE.md files modified
|
||||
|
||||
**Tool Selection**:
|
||||
- `--tool gemini` (default): Documentation generation, pattern recognition
|
||||
- `--tool qwen`: Architecture analysis, system design docs
|
||||
- `--tool codex`: Implementation validation, code quality analysis
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Detect Changes First**: Use git diff to identify affected modules before updates
|
||||
2. **Wait for Approval**: Present plan, no execution without user confirmation
|
||||
3. **Related Mode**: Update only changed modules and their parent contexts
|
||||
4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
|
||||
5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
|
||||
6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Phase 1: Change Detection & Analysis
|
||||
|
||||
**Refresh code index:**
|
||||
```bash
|
||||
bash(mcp__code-index__refresh_index)
|
||||
```
|
||||
|
||||
**Detect changed modules:**
|
||||
```bash
|
||||
bash(~/.claude/scripts/detect_changed_modules.sh list)
|
||||
```
|
||||
|
||||
**Cache git changes:**
|
||||
```bash
|
||||
bash(git add -A 2>/dev/null || true)
|
||||
```
|
||||
|
||||
**Parse Output**:
|
||||
- Extract changed module paths from `depth:N|path:<PATH>|...` format
|
||||
- Count affected modules
|
||||
- Identify which modules have/need CLAUDE.md updates
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new
|
||||
depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified
|
||||
depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent
|
||||
depth:0|path:.|files:14|has_claude:yes|change:parent
|
||||
```
|
||||
|
||||
**Fallback behavior**:
|
||||
- If no git changes detected, use recent modules (first 10 by depth)
|
||||
|
||||
**Validation**:
|
||||
- Changed module list contains valid paths
|
||||
- At least one affected module exists
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Plan Presentation
|
||||
|
||||
**Decision Logic**:
|
||||
- **Simple changes (≤15 modules)**: Present plan to user, wait for approval
|
||||
- **Complex changes (>15 modules)**: Delegate to memory-bridge agent
|
||||
|
||||
**Plan format:**
|
||||
```
|
||||
📋 Related Update Plan:
|
||||
Tool: gemini
|
||||
Changed modules: 4
|
||||
|
||||
NEW CLAUDE.md files (1):
|
||||
- ./src/api/auth/CLAUDE.md [new module]
|
||||
|
||||
UPDATE existing CLAUDE.md files (3):
|
||||
- ./src/api/CLAUDE.md [parent of changed auth/]
|
||||
- ./src/CLAUDE.md [parent context]
|
||||
- ./CLAUDE.md [root level]
|
||||
|
||||
⚠️ Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**User Confirmation Required**: No execution without explicit approval
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Depth-Parallel Execution
|
||||
|
||||
**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
|
||||
|
||||
**Command structure:**
|
||||
```bash
|
||||
bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
|
||||
```
|
||||
|
||||
**Example - Depth 3 (new module):**
|
||||
```bash
|
||||
bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
|
||||
```
|
||||
|
||||
*Wait for depth 3 completion...*
|
||||
|
||||
**Example - Depth 2 (modified parent):**
|
||||
```bash
|
||||
bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
|
||||
```
|
||||
|
||||
*Wait for depth 2 completion...*
|
||||
|
||||
**Example - Depth 1 & 0 (parent contexts):**
|
||||
```bash
|
||||
bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
|
||||
```
|
||||
```bash
|
||||
bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
|
||||
```
|
||||
|
||||
*Wait for all depths completion...*
|
||||
|
||||
**Execution Rules**:
|
||||
- Each command is separate bash() call
|
||||
- Up to 4 concurrent jobs per depth
|
||||
- Wait for all jobs in current depth before proceeding
|
||||
- Use "related" mode (not "full") for context-aware updates
|
||||
- Extract path from `depth:N|path:<PATH>|...` format
|
||||
|
||||
**Related Mode Behavior**:
|
||||
- Updates module based on recent git changes
|
||||
- Includes parent context for better documentation coherence
|
||||
- More efficient than full updates for iterative development
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Safety Verification
|
||||
|
||||
**Check modified files:**
|
||||
```bash
|
||||
bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
✅ Only CLAUDE.md files modified
|
||||
```
|
||||
|
||||
**If non-CLAUDE.md files detected:**
|
||||
```
|
||||
⚠️ Warning: Non-CLAUDE.md files were modified
|
||||
Modified files: src/api/auth/index.ts, package.json
|
||||
→ Run: git restore --staged .
|
||||
```
|
||||
|
||||
**Display final statistics:**
|
||||
```bash
|
||||
bash(git diff --stat)
|
||||
```
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++
|
||||
src/api/CLAUDE.md | 23 +++++++++--
|
||||
src/CLAUDE.md | 12 ++++--
|
||||
CLAUDE.md | 8 ++--
|
||||
4 files changed, 82 insertions(+), 6 deletions(-)
|
||||
```
|
||||
|
||||
## Command Pattern Reference
|
||||
|
||||
**Single module update:**
|
||||
```bash
|
||||
bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
|
||||
```
|
||||
|
||||
**Components**:
|
||||
- `cd <module-path>` - Navigate to module (from `path:` field)
|
||||
- `&&` - Ensure cd succeeds
|
||||
- `update_module_claude.sh` - Update script
|
||||
- `"."` - Current directory
|
||||
- `"related"` - Related mode (context-aware, change-based)
|
||||
- `"<tool>"` - gemini/qwen/codex
|
||||
- `&` - Background execution
|
||||
|
||||
**Path extraction:**
|
||||
```bash
|
||||
# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no
|
||||
# Extract: ./src/api/auth
|
||||
# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
|
||||
```
|
||||
|
||||
**Mode comparison:**
|
||||
- `"full"` - Complete module documentation regeneration
|
||||
- `"related"` - Context-aware update based on recent changes (faster)
|
||||
|
||||
## Complex Changes Strategy
|
||||
|
||||
For changes affecting >15 modules, delegate to memory-bridge agent:
|
||||
|
||||
```javascript
|
||||
Task(
|
||||
subagent_type="memory-bridge",
|
||||
description="Complex project related update",
|
||||
prompt=`
|
||||
CONTEXT:
|
||||
- Total modules: ${change_count}
|
||||
- Tool: ${tool}
|
||||
- Mode: related
|
||||
|
||||
MODULE LIST:
|
||||
${changed_modules_output}
|
||||
|
||||
REQUIREMENTS:
|
||||
1. Use TodoWrite to track each depth level
|
||||
2. Process depths N→0 sequentially, max 4 parallel per depth
|
||||
3. Command: cd "<path>" && update_module_claude.sh "." "related" "${tool}" &
|
||||
4. Extract path from "depth:N|path:<PATH>|..." format
|
||||
5. Verify all ${change_count} modules processed
|
||||
6. Run safety check
|
||||
7. Display git diff --stat
|
||||
`
|
||||
)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **No changes detected**: Use fallback mode (recent 10 modules)
|
||||
- **Change detection failure**: Report error, abort execution
|
||||
- **User declines approval**: Abort execution, no changes made
|
||||
- **Safety check failure**: Automatic staging revert, report modified files
|
||||
- **Update script failure**: Report failed modules, continue with remaining
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
✅ Parse `--tool` parameter (default: gemini)
|
||||
✅ Refresh code index for accurate change detection
|
||||
✅ Detect changed modules via detect_changed_modules.sh
|
||||
✅ Cache git changes to protect current state
|
||||
✅ Parse changed module list, count affected modules
|
||||
✅ Apply fallback if no changes detected (recent 10 modules)
|
||||
✅ Determine strategy based on change count (≤15 vs >15)
|
||||
✅ Present plan with exact file paths and change types
|
||||
✅ **Wait for user confirmation** (simple changes only)
|
||||
✅ Organize modules by depth
|
||||
✅ For each depth (highest to lowest):
|
||||
- Launch up to 4 parallel updates with "related" mode
|
||||
- Wait for depth completion
|
||||
- Proceed to next depth
|
||||
✅ Run safety check after all updates
|
||||
✅ Display git diff statistics
|
||||
✅ Report completion summary
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Daily development update (default: gemini)
|
||||
/memory:update-related
|
||||
|
||||
# After feature work with specific tool
|
||||
/memory:update-related --tool qwen
|
||||
|
||||
# Code quality review after implementation
|
||||
/memory:update-related --tool codex
|
||||
```
|
||||
|
||||
## Tool Parameter Reference
|
||||
|
||||
**Gemini** (default):
|
||||
- Best for: Documentation generation, pattern recognition
|
||||
- Use case: Daily development updates, feature documentation
|
||||
- Output style: Comprehensive, contextual explanations
|
||||
|
||||
**Qwen**:
|
||||
- Best for: Architecture analysis, system design
|
||||
- Use case: Structural changes, API design updates
|
||||
- Output style: Structured, systematic documentation
|
||||
|
||||
**Codex**:
|
||||
- Best for: Implementation validation, code quality
|
||||
- Use case: After implementation, refactoring work
|
||||
- Output style: Technical, implementation-focused
|
||||
|
||||
## 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 |
|
||||
| **Complexity threshold** | ≤15 modules | ≤20 modules |
|
||||
Reference in New Issue
Block a user