mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
docs: 更新文档，明确任务结构和操作模式的约束条件
This commit is contained in:
catlog22
@@ -8,111 +8,72 @@ argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
|
||||
|
||||
## Overview
|
||||
|
||||
Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback (gemini→qwen→codex) and 3-layer architecture support.
|
||||
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**:
|
||||
1. Discovery & Analysis → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
|
||||
**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
|
||||
|
||||
## 3-Layer Architecture
|
||||
## 3-Layer Architecture & Auto-Strategy Selection
|
||||
|
||||
**Layer Definition**:
|
||||
- **Layer 3 (Bottom/Deepest)**: depth ≥ 3 - Use multi-layer strategy (generate CLAUDE.md for all subdirectories)
|
||||
- **Layer 2 (Middle)**: depth 1-2 - Use single-layer strategy (aggregate from children)
|
||||
- **Layer 1 (Top)**: depth 0 - Use single-layer strategy (aggregate from children)
|
||||
### Layer Definition & Strategy Assignment
|
||||
|
||||
**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up)
|
||||
| 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,...}` |
|
||||
|
||||
**Strategy Auto-Selection**: Strategies are automatically determined by directory depth:
|
||||
- **Layer 3 (depth ≥3)**: Uses `multi-layer` strategy (handles unstructured files)
|
||||
- **Layer 2 (depth 1-2)**: Uses `single-layer` strategy (aggregates from children)
|
||||
- **Layer 1 (depth 0)**: Uses `single-layer` strategy (aggregates from children)
|
||||
**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
|
||||
|
||||
## Update Strategies
|
||||
**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
|
||||
|
||||
### Strategy 1: single-layer (For Layers 1-2)
|
||||
### Strategy Details
|
||||
|
||||
**Use Case**: Upper layers that aggregate from existing child CLAUDE.md files
|
||||
#### 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
|
||||
|
||||
**Context Configuration**:
|
||||
- **Layer 2** (depth 1-2): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
|
||||
- **Layer 1** (depth 0): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
|
||||
#### 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
|
||||
|
||||
**Benefits**:
|
||||
- Minimal context consumption
|
||||
- Clear layer separation
|
||||
- Each layer reads only immediate children summaries
|
||||
- Ideal for structured projects with defined hierarchy
|
||||
|
||||
**Example Execution Flow**:
|
||||
### Example Flow
|
||||
```
|
||||
src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
|
||||
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, middleware/CLAUDE.md, index.ts)
|
||||
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
|
||||
src/ (depth 1) → SINGLE-LAYER STRATEGY
|
||||
CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
|
||||
GENERATES: ./CLAUDE.md only
|
||||
↓
|
||||
./ (depth 0) - SINGLE-LAYER STRATEGY
|
||||
./ (depth 0) → SINGLE-LAYER STRATEGY
|
||||
CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
|
||||
GENERATES: ./CLAUDE.md only
|
||||
```
|
||||
|
||||
### Strategy 2: multi-layer (For Layer 3 only)
|
||||
|
||||
**Use Case**: Deepest layer with unstructured files, initial documentation generation
|
||||
|
||||
**Context Configuration**:
|
||||
- **Layer 3** (depth ≥3): `@**/*` - All files in current directory and generate CLAUDE.md for each subdirectory
|
||||
|
||||
**Benefits**:
|
||||
- Handles unstructured file layouts
|
||||
- Generates documentation for all directories with files
|
||||
- Creates the foundation layer for upper layers to reference
|
||||
- Ideal for leaf directories that haven't been documented yet
|
||||
|
||||
**Example Execution Flow**:
|
||||
```
|
||||
src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
|
||||
CONTEXT: @**/* (all files: login.ts, logout.ts, validation/)
|
||||
GENERATES: ./CLAUDE.md + validation/CLAUDE.md (if validation/ has files)
|
||||
```
|
||||
|
||||
### Strategy Selection Guidelines
|
||||
|
||||
**Strategy Assignment by Layer**:
|
||||
|
||||
| Layer | Depth | Strategy | Purpose |
|
||||
|-------|-------|----------|---------|
|
||||
| Layer 3 (Deepest) | ≥3 | multi-layer | Generate docs for unstructured directories |
|
||||
| Layer 2 (Middle) | 1-2 | single-layer | Aggregate from children + current code |
|
||||
| Layer 1 (Top) | 0 | single-layer | Aggregate from children + current code |
|
||||
|
||||
**Layer 3 Processing**:
|
||||
- Use multi-layer strategy to handle unstructured file layouts
|
||||
- Generate CLAUDE.md for each directory containing files
|
||||
- Create foundation for upper layers to reference
|
||||
|
||||
## Core Rules
|
||||
## 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, no agent overhead)
|
||||
- ≥20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
|
||||
- **<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. **Strategy Auto-Selection**: Strategies determined by directory depth (multi-layer for depth ≥3, single-layer for depth 0-2)
|
||||
8. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
|
||||
7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
|
||||
|
||||
## Tool Fallback Hierarchy
|
||||
|
||||
@@ -124,7 +85,15 @@ src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
|
||||
|
||||
**Trigger**: Non-zero exit code from update script
|
||||
|
||||
## Phase 1: Discovery & Analysis
|
||||
| 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
|
||||
@@ -138,23 +107,21 @@ 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 (Node.js/Python/Go/Rust/etc).
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
|
||||
|
||||
## Phase 2: Plan Presentation
|
||||
### Phase 2: Plan Presentation
|
||||
|
||||
**Present filtered plan**:
|
||||
**For <20 modules**:
|
||||
```
|
||||
Update Plan:
|
||||
Tool: gemini (fallback: qwen → codex)
|
||||
Total: 7 modules
|
||||
Execution: Direct sequential (< 20 modules threshold)
|
||||
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
|
||||
- ./parametric (6 files) - depth 1 [Layer 2] - single-layer strategy
|
||||
- ./results (7 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
|
||||
|
||||
@@ -162,16 +129,8 @@ Update Plan:
|
||||
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
|
||||
- Layer 1 (depth 0): @*/CLAUDE.md + current code files
|
||||
|
||||
Auto-skipped (15 paths):
|
||||
- Tests: ./tests, **/*_test.py (8 paths)
|
||||
- Build: __pycache__, dist, *.egg-info (5 paths)
|
||||
- Config: setup.py, requirements.txt (2 paths)
|
||||
|
||||
Execution order (by depth):
|
||||
1. Depth 2: ./core/interfaces
|
||||
2. Depth 1: ./core, ./models, ./parametric, ./results, ./utils
|
||||
3. Depth 0: .
|
||||
|
||||
Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
|
||||
Execution order: Layer 2 → Layer 1
|
||||
Estimated time: ~5-10 minutes
|
||||
|
||||
Confirm execution? (y/n)
|
||||
@@ -195,13 +154,6 @@ Update Plan:
|
||||
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
|
||||
- Layer 1 (depth 0): @*/CLAUDE.md + current code files
|
||||
|
||||
Auto-skipped (45 paths):
|
||||
- Tests: ./tests, ./src/**/*.test.ts (18 paths)
|
||||
- Config: package.json, tsconfig.json, vite.config.ts (12 paths)
|
||||
- Build: ./dist, ./node_modules, ./.next (8 paths)
|
||||
- Docs: ./README.md, ./docs (5 paths)
|
||||
- Other: .git, .vscode, coverage (2 paths)
|
||||
|
||||
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]
|
||||
@@ -212,38 +164,12 @@ Update Plan:
|
||||
Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
**Decision logic**:
|
||||
- User confirms "y": Proceed with execution
|
||||
- User declines "n": Abort, no changes
|
||||
- <20 modules: Direct execution (Phase 3A)
|
||||
- ≥20 modules: Agent batch execution (Phase 3B)
|
||||
### Phase 3A: Direct Execution (<20 modules)
|
||||
|
||||
## Phase 3A: Direct Execution (<20 modules)
|
||||
|
||||
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead, tool fallback per module.
|
||||
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
|
||||
|
||||
```javascript
|
||||
// Group modules by LAYER (not depth)
|
||||
function group_by_layer(modules) {
|
||||
let layers = {
|
||||
3: [], // Layer 3: depth ≥3
|
||||
2: [], // Layer 2: depth 1-2
|
||||
1: [] // Layer 1: depth 0
|
||||
};
|
||||
|
||||
modules.forEach(module => {
|
||||
if (module.depth >= 3) {
|
||||
layers[3].push(module);
|
||||
} else if (module.depth >= 1) {
|
||||
layers[2].push(module);
|
||||
} else {
|
||||
layers[1].push(module);
|
||||
}
|
||||
});
|
||||
|
||||
return layers;
|
||||
}
|
||||
|
||||
let modules_by_layer = group_by_layer(module_list);
|
||||
let tool_order = construct_tool_order(primary_tool);
|
||||
|
||||
@@ -251,112 +177,40 @@ 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); // Split into groups of 4
|
||||
let batches = batch_modules(modules_by_layer[layer], 4);
|
||||
|
||||
for (let batch of batches) {
|
||||
// Execute batch in parallel (max 4 concurrent)
|
||||
let parallel_tasks = batch.map(module => {
|
||||
return async () => {
|
||||
let success = false;
|
||||
// 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}");
|
||||
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}");
|
||||
success = true;
|
||||
break;
|
||||
report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
|
||||
return true;
|
||||
}
|
||||
}
|
||||
if (!success) {
|
||||
report("❌ FAILED: ${module.path} (Layer ${layer}) failed all tools");
|
||||
}
|
||||
report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
|
||||
return false;
|
||||
};
|
||||
});
|
||||
|
||||
await Promise.all(parallel_tasks.map(task => task())); // Run batch in parallel
|
||||
await Promise.all(parallel_tasks.map(task => task()));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example execution (7 modules with auto-strategy)**:
|
||||
```bash
|
||||
# Layer 2 (1 module: depth 2) - auto-selects single-layer strategy
|
||||
bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
|
||||
# → CONTEXT: @*/CLAUDE.md @*.ts @*.tsx... (direct children + current code)
|
||||
# → Success with gemini
|
||||
### Phase 3B: Agent Batch Execution (≥20 modules)
|
||||
|
||||
# Layer 2 (5 modules: depth 1 → 2 batches: [4, 1]) - auto-selects single-layer strategy
|
||||
# Batch 1 (4 modules in parallel):
|
||||
bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
|
||||
bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
|
||||
bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
|
||||
bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
|
||||
wait # Wait for batch 1 to complete
|
||||
|
||||
# Batch 2 (1 module):
|
||||
bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
|
||||
# → Success with gemini
|
||||
|
||||
# Layer 1 (1 module: depth 0) - auto-selects single-layer strategy
|
||||
bash(cd . && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
|
||||
# → CONTEXT: @*/CLAUDE.md @*.ts... (direct children + current code)
|
||||
# → Success with gemini
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- No agent startup overhead
|
||||
- Parallel execution within depth (max 4 concurrent)
|
||||
- Tool fallback still applies per module
|
||||
- Faster for small projects (<20 modules)
|
||||
- Same batching strategy as Phase 3B but without agent layer
|
||||
|
||||
---
|
||||
|
||||
## Phase 3B: Agent Batch Execution (≥20 modules)
|
||||
|
||||
### Batching Strategy
|
||||
**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
|
||||
|
||||
```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
|
||||
// Group modules by LAYER (not depth)
|
||||
function group_by_layer(modules) {
|
||||
let layers = {
|
||||
3: [], // Layer 3: depth ≥3
|
||||
2: [], // Layer 2: depth 1-2
|
||||
1: [] // Layer 1: depth 0
|
||||
};
|
||||
|
||||
modules.forEach(module => {
|
||||
if (module.depth >= 3) {
|
||||
layers[3].push(module);
|
||||
} else if (module.depth >= 1) {
|
||||
layers[2].push(module);
|
||||
} else {
|
||||
layers[1].push(module);
|
||||
}
|
||||
});
|
||||
|
||||
return layers;
|
||||
}
|
||||
|
||||
// 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);
|
||||
|
||||
// Process by LAYER (3 → 2 → 1), not by depth
|
||||
for (let layer of [3, 2, 1]) {
|
||||
if (modules_by_layer[layer].length === 0) continue;
|
||||
|
||||
@@ -373,89 +227,35 @@ for (let layer of [3, 2, 1]) {
|
||||
);
|
||||
}
|
||||
|
||||
await parallel_execute(worker_tasks); // Batches run in parallel within layer
|
||||
await parallel_execute(worker_tasks);
|
||||
}
|
||||
```
|
||||
|
||||
### Batch Worker Prompt Template
|
||||
|
||||
**Batch Worker Prompt Template**:
|
||||
```
|
||||
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback and auto-strategy selection
|
||||
|
||||
TASK:
|
||||
Update documentation for the following modules. For each module, try tools in order until success.
|
||||
Strategy is automatically determined by directory depth.
|
||||
TASK: Update documentation for modules with auto-determined strategy based on directory depth.
|
||||
|
||||
MODULES:
|
||||
{{module_path_1}} (depth: {{depth_1}}, layer: {{layer_1}})
|
||||
{{module_path_2}} (depth: {{depth_2}}, layer: {{layer_2}})
|
||||
{{module_path_3}} (depth: {{depth_3}}, layer: {{layer_3}})
|
||||
{{module_path_4}} (depth: {{depth_4}}, layer: {{layer_4}})
|
||||
...
|
||||
|
||||
TOOLS (try in order):
|
||||
1. {{tool_1}}
|
||||
2. {{tool_2}}
|
||||
3. {{tool_3}}
|
||||
TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
|
||||
|
||||
EXECUTION:
|
||||
For each module above:
|
||||
1. cd "{{module_path}}"
|
||||
2. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer"
|
||||
3. Try tool 1:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{tool_1}}")
|
||||
→ Success: Report "✅ {{module_path}} updated with {{tool_1}}", proceed to next module
|
||||
→ Failure: Try tool 2
|
||||
4. Try tool 2:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{tool_2}}")
|
||||
→ Success: Report "✅ {{module_path}} updated with {{tool_2}}", proceed to next module
|
||||
→ Failure: Try tool 3
|
||||
5. Try tool 3:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{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
|
||||
For each module:
|
||||
1. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer"
|
||||
2. Try tools in order until success:
|
||||
bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}")
|
||||
|
||||
CONTEXT SELECTION (automatically handled by script based on strategy):
|
||||
CONTEXT SELECTION (automatically handled by script):
|
||||
- multi-layer strategy (depth ≥3): @**/* (all files)
|
||||
- single-layer strategy (depth 0-2): @*/CLAUDE.md + current code files
|
||||
|
||||
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 with layer information
|
||||
```
|
||||
|
||||
### Example Execution
|
||||
|
||||
**Layer-based allocation (31 modules total)**:
|
||||
```javascript
|
||||
// Layer 3: 14 modules (depth ≥3) → 4 agents
|
||||
Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4]) // Agent 1
|
||||
Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8]) // Agent 2
|
||||
Task(subagent_type="memory-bridge", batch=[mod9, mod10, mod11, mod12]) // Agent 3
|
||||
Task(subagent_type="memory-bridge", batch=[mod13, mod14]) // Agent 4
|
||||
// All 4 agents run in parallel
|
||||
|
||||
// Layer 2: 15 modules (depth 1-2) → 4 agents
|
||||
Task(subagent_type="memory-bridge", batch=[mod15, mod16, mod17, mod18]) // Agent 5
|
||||
Task(subagent_type="memory-bridge", batch=[mod19, mod20, mod21, mod22]) // Agent 6
|
||||
Task(subagent_type="memory-bridge", batch=[mod23, mod24, mod25, mod26]) // Agent 7
|
||||
Task(subagent_type="memory-bridge", batch=[mod27, mod28, mod29]) // Agent 8
|
||||
// All 4 agents run in parallel
|
||||
|
||||
// Layer 1: 2 modules (depth 0) → 1 agent
|
||||
Task(subagent_type="memory-bridge", batch=[mod30, mod31]) // Agent 9
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- 31 modules → 9 agents (71% reduction from sequential)
|
||||
- Parallel execution within each layer
|
||||
- Each module gets full fallback chain
|
||||
- Layer isolation ensures proper dependency order
|
||||
|
||||
## Phase 4: Safety Verification
|
||||
### Phase 4: Safety Verification
|
||||
|
||||
```bash
|
||||
# Check only CLAUDE.md modified
|
||||
@@ -465,56 +265,21 @@ bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md
|
||||
bash(git status --short)
|
||||
```
|
||||
|
||||
**Aggregate results**:
|
||||
**Result Summary**:
|
||||
```
|
||||
Update Summary:
|
||||
Total: 31 | Success: 29 | Failed: 2
|
||||
|
||||
Tool usage:
|
||||
- gemini: 25 modules
|
||||
- qwen: 4 modules (fallback)
|
||||
- codex: 0 modules
|
||||
|
||||
Failed: FAILED: path1, path2
|
||||
Tool usage: gemini: 25, qwen: 4, codex: 0
|
||||
Failed: path1, path2
|
||||
```
|
||||
|
||||
## Execution Summary
|
||||
|
||||
**Module Count Threshold**:
|
||||
- **<20 modules**: Coordinator executes Phase 3A (Direct Execution)
|
||||
- **≥20 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
|
||||
|
||||
**Agent Hierarchy** (for ≥20 modules):
|
||||
- **Coordinator**: Handles batch division, spawns worker agents per depth
|
||||
- **Worker Agents**: Each processes 4 modules with tool fallback
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Batch Worker**:
|
||||
- Tool fallback per module (auto-retry)
|
||||
- Batch isolation (failures don't propagate)
|
||||
- Clear per-module status reporting
|
||||
**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
|
||||
|
||||
**Coordinator**:
|
||||
- Invalid path: Abort with error
|
||||
- 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 |
|
||||
|
||||
## Path Parameter Examples
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full project update (auto-strategy selection)
|
||||
@@ -531,33 +296,8 @@ Update Summary:
|
||||
|
||||
## Key Advantages
|
||||
|
||||
**Efficiency**: 30 modules → 8 agents (73% reduction)
|
||||
**Resilience**: 3-tier fallback per module
|
||||
**Performance**: Parallel batches, no concurrency limits
|
||||
**Observability**: Per-module tool usage, batch-level metrics
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
- Parse `--tool` (default: gemini) and `--path` (default: current dir)
|
||||
- Git cache + module discovery
|
||||
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
|
||||
- **Group modules by LAYER** (not depth):
|
||||
- Layer 3: depth ≥3 (auto-select multi-layer strategy)
|
||||
- Layer 2: depth 1-2 (auto-select single-layer strategy)
|
||||
- Layer 1: depth 0 (auto-select single-layer strategy)
|
||||
- Construct tool fallback order
|
||||
- **Present filtered plan** with:
|
||||
- Execution strategy (<20: direct, ≥20: agent batch)
|
||||
- Layer groupings with auto-selected strategies
|
||||
- Context strategy per layer
|
||||
- Agent allocation by LAYER
|
||||
- **Wait for y/n confirmation**
|
||||
- Determine execution mode:
|
||||
- **<20 modules**: Direct execution (Phase 3A)
|
||||
- For each layer (3→2→1): Parallel module updates within layer (max 4 concurrent) with tool fallback and auto-strategy selection
|
||||
- **≥20 modules**: Agent batch execution (Phase 3B)
|
||||
- For each layer (3→2→1): Batch modules (4 per batch), spawn batch workers in parallel with auto-strategy selection
|
||||
- Wait for layer completion before moving to next layer
|
||||
- Aggregate results
|
||||
- Safety check (only CLAUDE.md modified)
|
||||
- Display git status + summary with layer statistics
|
||||
- **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
|
||||
@@ -155,11 +155,11 @@ codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s
|
||||
|
||||
Every command MUST follow this structure:
|
||||
- [ ] **PURPOSE** - Clear goal and intent
|
||||
- [ ] **TASK** - Specific execution task
|
||||
- [ ] **TASK** - Specific execution task (use list format: • Task item 1 • Task item 2 • Task item 3)
|
||||
- [ ] **MODE** - Execution mode and permission level
|
||||
- [ ] **CONTEXT** - File references and memory context from previous sessions
|
||||
- [ ] **EXPECTED** - Clear expected results
|
||||
- [ ] **RULES** - Template reference and constraints
|
||||
- [ ] **RULES** - Template reference and constraints (include mode constraints: analysis=READ-ONLY | write=CREATE/MODIFY/DELETE | auto=FULL operations)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user