mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
Add CLI commands for full and related documentation generation
- Implemented `/memory:docs-full-cli` for comprehensive project documentation generation using CLI execution with batched agents and tool fallback. - Introduced `/memory:docs-related-cli` to generate/update documentation for git-changed modules, optimizing for efficiency with direct parallel execution for fewer modules and agent batch processing for larger sets. - Defined execution flows, strategies, and error handling for both commands, ensuring robust documentation processes.
This commit is contained in:
catlog22
472
.claude/commands/memory/docs-full-cli.md
Normal file
472
.claude/commands/memory/docs-full-cli.md
Normal file
@@ -0,0 +1,472 @@
|
||||
---
|
||||
name: docs-full-cli
|
||||
description: Generate full project documentation using CLI execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
|
||||
argument-hint: "[path] [--tool <gemini|qwen|codex>]"
|
||||
---
|
||||
|
||||
# Full Documentation Generation - CLI Mode (/memory:docs-full-cli)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrates project-wide documentation generation using CLI-based execution with batched agents and automatic tool fallback.
|
||||
|
||||
**Parameters**:
|
||||
- `path`: Target directory (default: current directory)
|
||||
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
|
||||
|
||||
**Execution Flow**: Discovery → Plan Presentation → Execution → Verification
|
||||
|
||||
## 3-Layer Architecture & Auto-Strategy Selection
|
||||
|
||||
### Layer Definition & Strategy Assignment
|
||||
|
||||
| Layer | Depth | Strategy | Purpose | Context Pattern |
|
||||
|-------|-------|----------|---------|----------------|
|
||||
| **Layer 3** (Deepest) | ≥3 | `full` | Generate docs for all subdirectories with code | `@**/*` (all files) |
|
||||
| **Layer 2** (Middle) | 1-2 | `single` | Current dir + child docs | `@*/API.md @*/README.md @*.{ts,tsx,js,...}` |
|
||||
| **Layer 1** (Top) | 0 | `single` | Current dir + child docs | `@*/API.md @*/README.md @*.{ts,tsx,js,...}` |
|
||||
|
||||
**Generation 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
|
||||
|
||||
#### Full Strategy (Layer 3 Only)
|
||||
- **Use Case**: Deepest directories with comprehensive file coverage
|
||||
- **Behavior**: Generates API.md + README.md for current directory AND subdirectories containing code
|
||||
- **Context**: All files in current directory tree (`@**/*`)
|
||||
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
|
||||
- **Benefits**: Creates foundation documentation for upper layers to reference
|
||||
|
||||
#### Single Strategy (Layers 1-2)
|
||||
- **Use Case**: Upper layers that aggregate from existing documentation
|
||||
- **Behavior**: Generates API.md + README.md only in current directory
|
||||
- **Context**: Direct children docs + current directory code files
|
||||
- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
|
||||
- **Benefits**: Minimal context consumption, clear layer separation
|
||||
|
||||
### Example Flow
|
||||
```
|
||||
src/auth/handlers/ (depth 3) → FULL STRATEGY
|
||||
CONTEXT: @**/* (all files in handlers/ and subdirs)
|
||||
GENERATES: .workflow/docs/project/src/auth/handlers/{API.md,README.md} + subdirs
|
||||
↓
|
||||
src/auth/ (depth 2) → SINGLE STRATEGY
|
||||
CONTEXT: @*/API.md @*/README.md @*.ts (handlers docs + current code)
|
||||
GENERATES: .workflow/docs/project/src/auth/{API.md,README.md} only
|
||||
↓
|
||||
src/ (depth 1) → SINGLE STRATEGY
|
||||
CONTEXT: @*/API.md @*/README.md (auth docs, utils docs)
|
||||
GENERATES: .workflow/docs/project/src/{API.md,README.md} only
|
||||
↓
|
||||
./ (depth 0) → SINGLE STRATEGY
|
||||
CONTEXT: @*/API.md @*/README.md (src docs, tests docs)
|
||||
GENERATES: .workflow/docs/project/{API.md,README.md} only
|
||||
```
|
||||
|
||||
## Core Execution Rules
|
||||
|
||||
1. **Analyze First**: Module discovery + folder classification before generation
|
||||
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 docs files modified in .workflow/docs/
|
||||
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 generation 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
|
||||
|
||||
```javascript
|
||||
// Get project metadata
|
||||
Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
|
||||
|
||||
// Get module structure with classification
|
||||
Bash({command: "~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
|
||||
|
||||
// OR with path parameter
|
||||
Bash({command: "cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|type:<code|navigation>|...` to extract module paths, types, and count.
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack.
|
||||
|
||||
### Phase 2: Plan Presentation
|
||||
|
||||
**For <20 modules**:
|
||||
```
|
||||
Documentation Generation Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Total: 7 modules
|
||||
Execution: Direct parallel (< 20 modules threshold)
|
||||
Project: myproject
|
||||
Output: .workflow/docs/myproject/
|
||||
|
||||
Will generate docs for:
|
||||
- ./core/interfaces (12 files, type: code) - depth 2 [Layer 2] - single strategy
|
||||
- ./core (22 files, type: code) - depth 1 [Layer 2] - single strategy
|
||||
- ./models (9 files, type: code) - depth 1 [Layer 2] - single strategy
|
||||
- ./utils (12 files, type: navigation) - depth 1 [Layer 2] - single strategy
|
||||
- . (5 files, type: code) - depth 0 [Layer 1] - single strategy
|
||||
|
||||
Documentation Strategy (Auto-Selected):
|
||||
- Layer 2 (depth 1-2): API.md + README.md (current dir only, reference child docs)
|
||||
- Layer 1 (depth 0): API.md + README.md (current dir only, reference child docs)
|
||||
|
||||
Output Structure:
|
||||
- Code folders: API.md + README.md
|
||||
- Navigation folders: README.md only
|
||||
|
||||
Auto-skipped: ./tests, __pycache__, node_modules (15 paths)
|
||||
Execution order: Layer 2 → Layer 1
|
||||
Estimated time: ~5-10 minutes
|
||||
|
||||
Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**For ≥20 modules**:
|
||||
```
|
||||
Documentation Generation Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Total: 31 modules
|
||||
Execution: Agent batch processing (4 modules/agent)
|
||||
Project: myproject
|
||||
Output: .workflow/docs/myproject/
|
||||
|
||||
Will generate docs for:
|
||||
- ./src/features/auth (12 files, type: code) - depth 3 [Layer 3] - full strategy
|
||||
- ./.claude/commands/cli (6 files, type: code) - depth 3 [Layer 3] - full strategy
|
||||
- ./src/utils (8 files, type: code) - depth 2 [Layer 2] - single strategy
|
||||
...
|
||||
|
||||
Documentation Strategy (Auto-Selected):
|
||||
- Layer 3 (depth ≥3): API.md + README.md (all subdirs with code)
|
||||
- Layer 2 (depth 1-2): API.md + README.md (current dir only)
|
||||
- Layer 1 (depth 0): API.md + README.md (current dir only)
|
||||
|
||||
Output Structure:
|
||||
- Code folders: API.md + README.md
|
||||
- Navigation folders: README.md only
|
||||
|
||||
Auto-skipped: ./tests, __pycache__, node_modules (15 paths)
|
||||
Execution order: Layer 3 → Layer 2 → Layer 1
|
||||
|
||||
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.
|
||||
|
||||
**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
|
||||
|
||||
```javascript
|
||||
let project_name = detect_project_name();
|
||||
|
||||
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 () => {
|
||||
let strategy = module.depth >= 3 ? "full" : "single";
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "${strategy}" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
report(`✅ ${module.path} (Layer ${layer}) docs generated 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);
|
||||
let project_name = detect_project_name();
|
||||
|
||||
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=`Generate docs for ${batch.length} modules in Layer ${layer}`,
|
||||
prompt=generate_batch_worker_prompt(batch, tool_order, layer, project_name)
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
await parallel_execute(worker_tasks);
|
||||
}
|
||||
```
|
||||
|
||||
**Batch Worker Prompt Template**:
|
||||
```
|
||||
PURPOSE: Generate documentation for assigned modules with tool fallback
|
||||
|
||||
TASK: Generate API.md + README.md for assigned modules using specified strategies.
|
||||
|
||||
PROJECT: {{project_name}}
|
||||
OUTPUT: .workflow/docs/{{project_name}}/
|
||||
|
||||
MODULES:
|
||||
{{module_path_1}} (strategy: {{strategy_1}}, type: {{folder_type_1}})
|
||||
{{module_path_2}} (strategy: {{strategy_2}}, type: {{folder_type_2}})
|
||||
...
|
||||
|
||||
TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
|
||||
|
||||
EXECUTION SCRIPT: ~/.claude/scripts/generate_module_docs.sh
|
||||
- Accepts strategy parameter: full | single
|
||||
- Accepts folder type detection: code | navigation
|
||||
- Tool execution via direct CLI commands (gemini/qwen/codex)
|
||||
- Output path: .workflow/docs/{{project_name}}/{module_path}/
|
||||
|
||||
EXECUTION FLOW (for each module):
|
||||
1. Tool fallback loop (exit on first success):
|
||||
for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "{{strategy}}" "." "{{project_name}}" "${tool}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
exit_code=$?
|
||||
|
||||
if [ $exit_code -eq 0 ]; then
|
||||
report "✅ {{module_path}} docs generated 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
|
||||
|
||||
FOLDER TYPE HANDLING:
|
||||
- code: Generate API.md + README.md
|
||||
- navigation: Generate README.md only
|
||||
|
||||
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 docs generated with {tool}
|
||||
⚠️ path/to/module failed with {tool}, trying next...
|
||||
❌ FAILED: path/to/module - all tools exhausted
|
||||
```
|
||||
|
||||
### Phase 4: Project-Level Documentation
|
||||
|
||||
**After all module documentation is generated, create project-level documentation files.**
|
||||
|
||||
```javascript
|
||||
let project_name = detect_project_name();
|
||||
let project_root = get_project_root();
|
||||
|
||||
// Step 1: Generate Project README
|
||||
report("Generating project README.md...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-readme" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
report(`✅ Project README generated with ${tool}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Step 2: Generate Architecture & Examples
|
||||
report("Generating ARCHITECTURE.md and EXAMPLES.md...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-architecture" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
report(`✅ Architecture docs generated with ${tool}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// Step 3: Generate HTTP API documentation (if API routes detected)
|
||||
Bash({command: 'rg "router\\.|@Get|@Post" -g "*.{ts,js,py}" 2>/dev/null && echo "API_FOUND" || echo "NO_API"', run_in_background: false});
|
||||
if (bash_result.stdout.includes("API_FOUND")) {
|
||||
report("Generating HTTP API documentation...");
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "http-api" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
report(`✅ HTTP API docs generated with ${tool}`);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
Project-Level Documentation:
|
||||
✅ README.md (project root overview)
|
||||
✅ ARCHITECTURE.md (system design)
|
||||
✅ EXAMPLES.md (usage examples)
|
||||
✅ api/README.md (HTTP API reference) [optional]
|
||||
```
|
||||
|
||||
### Phase 5: Verification
|
||||
|
||||
```javascript
|
||||
// Check documentation files created
|
||||
Bash({command: 'find .workflow/docs -type f -name "*.md" 2>/dev/null | wc -l', run_in_background: false});
|
||||
|
||||
// Display structure
|
||||
Bash({command: 'tree -L 3 .workflow/docs/', run_in_background: false});
|
||||
```
|
||||
|
||||
**Result Summary**:
|
||||
```
|
||||
Documentation Generation Summary:
|
||||
Total: 31 | Success: 29 | Failed: 2
|
||||
Tool usage: gemini: 25, qwen: 4, codex: 0
|
||||
Failed: path1, path2
|
||||
|
||||
Generated documentation:
|
||||
.workflow/docs/myproject/
|
||||
├── src/
|
||||
│ ├── auth/
|
||||
│ │ ├── API.md
|
||||
│ │ └── README.md
|
||||
│ └── utils/
|
||||
│ └── README.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
|
||||
**Coordinator**: Invalid path abort, user decline handling, verification with cleanup
|
||||
**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
.workflow/docs/{project_name}/
|
||||
├── src/ # Mirrors source structure
|
||||
│ ├── 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/
|
||||
│ └── core/
|
||||
│ ├── API.md
|
||||
│ └── README.md
|
||||
├── README.md # ✨ Project root overview (auto-generated)
|
||||
├── ARCHITECTURE.md # ✨ System design (auto-generated)
|
||||
├── EXAMPLES.md # ✨ Usage examples (auto-generated)
|
||||
└── api/ # ✨ Optional (auto-generated if HTTP API detected)
|
||||
└── README.md # HTTP API reference
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full project documentation generation
|
||||
/memory:docs-full-cli
|
||||
|
||||
# Target specific directory
|
||||
/memory:docs-full-cli src/features/auth
|
||||
/memory:docs-full-cli .claude
|
||||
|
||||
# Use specific tool
|
||||
/memory:docs-full-cli --tool qwen
|
||||
/memory:docs-full-cli src --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
|
||||
- **Path Mirroring**: Clear 1:1 mapping between source and documentation structure
|
||||
|
||||
## Template Reference
|
||||
|
||||
Templates used from `~/.claude/workflows/cli-templates/prompts/documentation/`:
|
||||
- `api.txt`: Code API documentation (Part A: Code API, Part B: HTTP API)
|
||||
- `module-readme.txt`: Module purpose, usage, dependencies
|
||||
- `folder-navigation.txt`: Navigation README for folders with subdirectories
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/memory:docs` - Agent-based documentation planning workflow
|
||||
- `/memory:docs-related-cli` - Update docs for changed modules only
|
||||
- `/workflow:execute` - Execute documentation tasks (when using agent mode)
|
||||
386
.claude/commands/memory/docs-related-cli.md
Normal file
386
.claude/commands/memory/docs-related-cli.md
Normal file
@@ -0,0 +1,386 @@
|
||||
---
|
||||
name: docs-related-cli
|
||||
description: Generate/update documentation for git-changed modules using CLI execution with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <15 modules uses direct parallel
|
||||
argument-hint: "[--tool <gemini|qwen|codex>]"
|
||||
---
|
||||
|
||||
# Related Documentation Generation - CLI Mode (/memory:docs-related-cli)
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrates context-aware documentation generation/update for changed modules using CLI-based execution with batched agents and 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 Execution → 4. 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**: Generate/update only changed modules and their parent contexts
|
||||
7. **Single Strategy**: Always use `single` strategy (incremental update)
|
||||
|
||||
## 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 generation script
|
||||
|
||||
| Tool | Best For | Fallback To |
|
||||
|--------|--------------------------------|----------------|
|
||||
| gemini | Documentation, patterns | qwen → codex |
|
||||
| qwen | Architecture, system design | gemini → codex |
|
||||
| codex | Implementation, code quality | gemini → qwen |
|
||||
|
||||
## Phase 1: Change Detection & Analysis
|
||||
|
||||
```javascript
|
||||
// Get project metadata
|
||||
Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
|
||||
|
||||
// Detect changed modules
|
||||
Bash({command: "~/.claude/scripts/detect_changed_modules.sh list", run_in_background: false});
|
||||
|
||||
// Cache git changes
|
||||
Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
|
||||
```
|
||||
|
||||
**Parse output** `depth:N|path:<PATH>|change:<TYPE>|type:<code|navigation>` to extract affected modules.
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/vendor 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 Documentation Generation Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Changed: 4 modules | Batching: 4 modules/agent
|
||||
Project: myproject
|
||||
Output: .workflow/docs/myproject/
|
||||
|
||||
Will generate/update docs for:
|
||||
- ./src/api/auth (5 files, type: code) [new module]
|
||||
- ./src/api (12 files, type: code) [parent of changed auth/]
|
||||
- ./src (8 files, type: code) [parent context]
|
||||
- . (14 files, type: code) [root level]
|
||||
|
||||
Documentation Strategy:
|
||||
- Strategy: single (all modules - incremental update)
|
||||
- Output: API.md + README.md (code folders), README.md only (navigation folders)
|
||||
- Context: Current dir code + child docs
|
||||
|
||||
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]
|
||||
|
||||
Estimated time: ~5-10 minutes
|
||||
|
||||
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.
|
||||
|
||||
**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
|
||||
|
||||
```javascript
|
||||
let project_name = detect_project_name();
|
||||
|
||||
for (let depth of sorted_depths.reverse()) { // N → 0
|
||||
let batches = batch_modules(modules_by_depth[depth], 4);
|
||||
|
||||
for (let batch of batches) {
|
||||
let parallel_tasks = batch.map(module => {
|
||||
return async () => {
|
||||
for (let tool of tool_order) {
|
||||
Bash({
|
||||
command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "single" "." "${project_name}" "${tool}"`,
|
||||
run_in_background: false
|
||||
});
|
||||
if (bash_result.exit_code === 0) {
|
||||
report(`✅ ${module.path} docs generated with ${tool}`);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
report(`❌ FAILED: ${module.path} failed all tools`);
|
||||
return false;
|
||||
};
|
||||
});
|
||||
await Promise.all(parallel_tasks.map(task => task()));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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);
|
||||
let project_name = detect_project_name();
|
||||
|
||||
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=`Generate docs for ${batch.length} modules at depth ${depth}`,
|
||||
prompt=generate_batch_worker_prompt(batch, tool_order, depth, project_name, "related")
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
await parallel_execute(worker_tasks); // Batches run in parallel
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Worker Prompt Template
|
||||
|
||||
```
|
||||
PURPOSE: Generate/update documentation for assigned modules with tool fallback (related mode)
|
||||
|
||||
TASK:
|
||||
Generate documentation for the following modules based on recent changes. For each module, try tools in order until success.
|
||||
|
||||
PROJECT: {{project_name}}
|
||||
OUTPUT: .workflow/docs/{{project_name}}/
|
||||
|
||||
MODULES:
|
||||
{{module_path_1}} (type: {{folder_type_1}})
|
||||
{{module_path_2}} (type: {{folder_type_2}})
|
||||
{{module_path_3}} (type: {{folder_type_3}})
|
||||
{{module_path_4}} (type: {{folder_type_4}})
|
||||
|
||||
TOOLS (try in order):
|
||||
1. {{tool_1}}
|
||||
2. {{tool_2}}
|
||||
3. {{tool_3}}
|
||||
|
||||
EXECUTION:
|
||||
For each module above:
|
||||
1. Try tool 1:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_1}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_1}}", proceed to next module
|
||||
→ Failure: Try tool 2
|
||||
2. Try tool 2:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_2}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_2}}", proceed to next module
|
||||
→ Failure: Try tool 3
|
||||
3. Try tool 3:
|
||||
Bash({
|
||||
command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_3}}"`,
|
||||
run_in_background: false
|
||||
})
|
||||
→ Success: Report "✅ {{module_path}} docs generated with {{tool_3}}", proceed to next module
|
||||
→ Failure: Report "❌ FAILED: {{module_path}} failed all tools", proceed to next module
|
||||
|
||||
FOLDER TYPE HANDLING:
|
||||
- code: Generate API.md + README.md
|
||||
- navigation: Generate README.md only
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Phase 4: Verification
|
||||
|
||||
```javascript
|
||||
// Check documentation files created/updated
|
||||
Bash({command: 'find .workflow/docs -type f -name "*.md" 2>/dev/null | wc -l', run_in_background: false});
|
||||
|
||||
// Display recent changes
|
||||
Bash({command: 'find .workflow/docs -type f -name "*.md" -mmin -60 2>/dev/null', run_in_background: false});
|
||||
```
|
||||
|
||||
**Aggregate results**:
|
||||
```
|
||||
Documentation Generation Summary:
|
||||
Total: 4 | Success: 4 | Failed: 0
|
||||
|
||||
Tool usage:
|
||||
- gemini: 4 modules
|
||||
- qwen: 0 modules (fallback)
|
||||
- codex: 0 modules
|
||||
|
||||
Changes:
|
||||
.workflow/docs/myproject/src/api/auth/API.md (new)
|
||||
.workflow/docs/myproject/src/api/auth/README.md (new)
|
||||
.workflow/docs/myproject/src/api/API.md (updated)
|
||||
.workflow/docs/myproject/src/api/README.md (updated)
|
||||
.workflow/docs/myproject/src/API.md (updated)
|
||||
.workflow/docs/myproject/src/README.md (updated)
|
||||
.workflow/docs/myproject/API.md (updated)
|
||||
.workflow/docs/myproject/README.md (updated)
|
||||
```
|
||||
|
||||
## 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
|
||||
- Verification fail: Report incomplete modules
|
||||
- Partial failures: Continue execution, report failed modules
|
||||
|
||||
**Fallback Triggers**:
|
||||
- Non-zero exit code
|
||||
- Script timeout
|
||||
- Unexpected output
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
.workflow/docs/{project_name}/
|
||||
├── src/ # Mirrors source structure
|
||||
│ ├── modules/
|
||||
│ │ ├── README.md
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── API.md # Updated based on code changes
|
||||
│ │ │ └── README.md # Updated based on code changes
|
||||
│ │ └── api/
|
||||
│ │ ├── API.md
|
||||
│ │ └── README.md
|
||||
│ └── utils/
|
||||
│ └── README.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Daily development documentation update
|
||||
/memory:docs-related-cli
|
||||
|
||||
# After feature work with specific tool
|
||||
/memory:docs-related-cli --tool qwen
|
||||
|
||||
# Code quality documentation review after implementation
|
||||
/memory:docs-related-cli --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
|
||||
**Incremental**: Single strategy for focused updates
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
- Parse `--tool` (default: gemini)
|
||||
- Get project metadata (name, root)
|
||||
- Detect changed modules via detect_changed_modules.sh
|
||||
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/vendor)
|
||||
- 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
|
||||
- Verification check (documentation files created/updated)
|
||||
- Display summary + recent changes
|
||||
|
||||
## Comparison with Full Documentation Generation
|
||||
|
||||
| Aspect | Related Generation | Full Generation |
|
||||
|--------|-------------------|-----------------|
|
||||
| **Scope** | Changed modules only | All project modules |
|
||||
| **Speed** | Fast (minutes) | Slower (10-30 min) |
|
||||
| **Use case** | Daily development | Initial setup, major refactoring |
|
||||
| **Strategy** | `single` (all) | `full` (L3) + `single` (L1-2) |
|
||||
| **Trigger** | After commits | After setup or major changes |
|
||||
| **Batching** | 4 modules/agent | 4 modules/agent |
|
||||
| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
|
||||
| **Complexity threshold** | ≤15 modules | ≤20 modules |
|
||||
|
||||
## Template Reference
|
||||
|
||||
Templates used from `~/.claude/workflows/cli-templates/prompts/documentation/`:
|
||||
- `api.txt`: Code API documentation
|
||||
- `module-readme.txt`: Module purpose, usage, dependencies
|
||||
- `folder-navigation.txt`: Navigation README for folders
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/memory:docs-full-cli` - Full project documentation generation
|
||||
- `/memory:docs` - Agent-based documentation planning workflow
|
||||
- `/memory:update-related` - Update CLAUDE.md for changed modules
|
||||
Reference in New Issue
Block a user