catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 更新文档，明确任务结构和操作模式的约束条件

Browse Source
This commit is contained in:
catlog22
2025-10-22 11:16:34 +08:00
parent 804617d8cd
commit eb9b10c96b
4 changed files with 139 additions and 369 deletions
Download Patch File Download Diff File Expand all files Collapse all files

426
.claude/commands/memory/update-full.md
View File

@@ -8,111 +8,72 @@ argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
## Overview ## 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**: **Parameters**:
- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini) - `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
- `--path <directory>`: Target specific directory (default: entire project) - `--path <directory>`: Target specific directory (default: entire project)
**Execution Flow**: **Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
1. Discovery & Analysis → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
## 3-Layer Architecture ## 3-Layer Architecture & Auto-Strategy Selection
**Layer Definition**: ### Layer Definition & Strategy Assignment
- **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)
**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: **Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
- **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 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**: #### Single-Layer Strategy (Layers 1-2)
- **Layer 2** (depth 1-2): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code - **Use Case**: Upper layers that aggregate from existing documentation
- **Layer 1** (depth 0): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code - **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**: ### Example Flow
- Minimal context consumption
- Clear layer separation
- Each layer reads only immediate children summaries
- Ideal for structured projects with defined hierarchy
**Example Execution Flow**:
``` ```
src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
CONTEXT: @**/* (all files in handlers/ and subdirs) CONTEXT: @**/* (all files in handlers/ and subdirs)
GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
↓ ↓
src/auth/ (depth 2) - SINGLE-LAYER STRATEGY src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md, middleware/CLAUDE.md, index.ts) CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
GENERATES: ./CLAUDE.md only 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) CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
GENERATES: ./CLAUDE.md only GENERATES: ./CLAUDE.md only
↓ ↓
./ (depth 0) - SINGLE-LAYER STRATEGY ./ (depth 0) → SINGLE-LAYER STRATEGY
CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md) CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
GENERATES: ./CLAUDE.md only GENERATES: ./CLAUDE.md only
``` ```
### Strategy 2: multi-layer (For Layer 3 only) ## Core Execution Rules
**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
1. **Analyze First**: Git cache + module discovery before updates 1. **Analyze First**: Git cache + module discovery before updates
2. **Wait for Approval**: Present plan, no execution without user confirmation 2. **Wait for Approval**: Present plan, no execution without user confirmation
3. **Execution Strategy**: 3. **Execution Strategy**:
- <20 modules: Direct parallel execution (max 4 concurrent per layer, no agent overhead) - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
- ≥20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction) - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
4. **Tool Fallback**: Auto-retry with fallback tools on failure 4. **Tool Fallback**: Auto-retry with fallback tools on failure
5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer 5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
6. **Safety Check**: Verify only CLAUDE.md files modified 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) 7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
8. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
## Tool Fallback Hierarchy ## Tool Fallback Hierarchy
@@ -124,7 +85,15 @@ src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
**Trigger**: Non-zero exit code from update script **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 ```bash
# Cache git changes # 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. **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: Update Plan:
Tool: gemini (fallback: qwen → codex) Tool: gemini (fallback: qwen → codex)
Total: 7 modules Total: 7 modules
Execution: Direct sequential (< 20 modules threshold) Execution: Direct parallel (< 20 modules threshold)
Will update: Will update:
- ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy - ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
- ./core (22 files) - depth 1 [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 - ./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 - ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
- . (5 files) - depth 0 [Layer 1] - 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 2 (depth 1-2): @*/CLAUDE.md + current code files
- Layer 1 (depth 0): @*/CLAUDE.md + current code files - Layer 1 (depth 0): @*/CLAUDE.md + current code files
Auto-skipped (15 paths): Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
- Tests: ./tests, **/*_test.py (8 paths) Execution order: Layer 2 → Layer 1
- 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: .
Estimated time: ~5-10 minutes Estimated time: ~5-10 minutes
Confirm execution? (y/n) Confirm execution? (y/n)
@@ -195,13 +154,6 @@ Update Plan:
- Layer 2 (depth 1-2): @*/CLAUDE.md + current code files - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
- Layer 1 (depth 0): @*/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): Agent allocation (by LAYER):
- Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2] - 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 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
@@ -212,38 +164,12 @@ Update Plan:
Confirm execution? (y/n) Confirm execution? (y/n)
``` ```
**Decision logic**: ### Phase 3A: Direct Execution (<20 modules)
- 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) **Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead, tool fallback per module.
```javascript ```javascript
// Group modules by LAYER (not depth) // 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 modules_by_layer = group_by_layer(module_list);
let tool_order = construct_tool_order(primary_tool); 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]) { for (let layer of [3, 2, 1]) {
if (modules_by_layer[layer].length === 0) continue; 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) { for (let batch of batches) {
// Execute batch in parallel (max 4 concurrent)
let parallel_tasks = batch.map(module => { let parallel_tasks = batch.map(module => {
return async () => { return async () => {
let success = false;
// Auto-determine strategy based on depth // Auto-determine strategy based on depth
let strategy = module.depth >= 3 ? "multi-layer" : "single-layer"; let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
for (let tool of tool_order) { 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) { if (exit_code === 0) {
report("✅ ${module.path} (Layer ${layer}) updated with ${tool}"); report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
success = true; return true;
break;
} }
} }
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)**: ### Phase 3B: Agent Batch Execution (≥20 modules)
```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
# Layer 2 (5 modules: depth 1 → 2 batches: [4, 1]) - auto-selects single-layer strategy **Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
# 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
```javascript ```javascript
// Batch modules into groups of 4 // Group modules by LAYER and batch within each layer
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;
}
let modules_by_layer = group_by_layer(module_list); let modules_by_layer = group_by_layer(module_list);
let tool_order = construct_tool_order(primary_tool); let tool_order = construct_tool_order(primary_tool);
// Process by LAYER (3 → 2 → 1), not by depth
for (let layer of [3, 2, 1]) { for (let layer of [3, 2, 1]) {
if (modules_by_layer[layer].length === 0) continue; 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 PURPOSE: Update CLAUDE.md for assigned modules with tool fallback and auto-strategy selection
TASK: TASK: Update documentation for modules with auto-determined strategy based on directory depth.
Update documentation for the following modules. For each module, try tools in order until success.
Strategy is automatically determined by directory depth.
MODULES: MODULES:
{{module_path_1}} (depth: {{depth_1}}, layer: {{layer_1}}) {{module_path_1}} (depth: {{depth_1}}, layer: {{layer_1}})
{{module_path_2}} (depth: {{depth_2}}, layer: {{layer_2}}) {{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): TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
1. {{tool_1}}
2. {{tool_2}}
3. {{tool_3}}
EXECUTION: EXECUTION:
For each module above: For each module:
1. cd "{{module_path}}" 1. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer"
2. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer" 2. Try tools in order until success:
3. Try tool 1: bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}")
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
CONTEXT SELECTION (automatically handled by script based on strategy): CONTEXT SELECTION (automatically handled by script):
- multi-layer strategy (depth ≥3): @**/* (all files) - multi-layer strategy (depth ≥3): @**/* (all files)
- single-layer strategy (depth 0-2): @*/CLAUDE.md + current code 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 ### Phase 4: Safety Verification
**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
```bash ```bash
# Check only CLAUDE.md modified # 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) bash(git status --short)
``` ```
**Aggregate results**: **Result Summary**:
``` ```
Update Summary: Update Summary:
Total: 31 | Success: 29 | Failed: 2 Total: 31 | Success: 29 | Failed: 2
Tool usage: gemini: 25, qwen: 4, codex: 0
Tool usage: Failed: path1, path2
- gemini: 25 modules
- qwen: 4 modules (fallback)
- codex: 0 modules
Failed: 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 ## Error Handling
**Batch Worker**: **Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
- Tool fallback per module (auto-retry) **Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
- Batch isolation (failures don't propagate) **Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
- Clear per-module status reporting
**Coordinator**: ## Usage Examples
- 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
```bash ```bash
# Full project update (auto-strategy selection) # Full project update (auto-strategy selection)
@@ -531,33 +296,8 @@ Update Summary:
## Key Advantages ## Key Advantages
**Efficiency**: 30 modules → 8 agents (73% reduction) - **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
**Resilience**: 3-tier fallback per module - **Resilience**: 3-tier tool fallback per module
**Performance**: Parallel batches, no concurrency limits - **Performance**: Parallel batches, no concurrency limits
**Observability**: Per-module tool usage, batch-level metrics - **Observability**: Per-module tool usage, batch-level metrics
- **Automation**: Zero configuration - strategy auto-selected by directory depth
## 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

4
.claude/workflows/intelligent-tools-strategy.md
View File

@@ -155,11 +155,11 @@ codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s
Every command MUST follow this structure: Every command MUST follow this structure:
- [ ] **PURPOSE** - Clear goal and intent - [ ] **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 - [ ] **MODE** - Execution mode and permission level
- [ ] **CONTEXT** - File references and memory context from previous sessions - [ ] **CONTEXT** - File references and memory context from previous sessions
- [ ] **EXPECTED** - Clear expected results - [ ] **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)
--- ---

39
.gemini/GEMINI.md
View File

@@ -17,28 +17,43 @@ EXPECTED: [deliverables]
RULES: [templates | additional constraints] RULES: [templates | additional constraints]
``` ```
## MODE Definitions ## MODE Definitions - STRICT OPERATION BOUNDARIES
### MODE: analysis (default) ### MODE: analysis (default) - READ-ONLY OPERATIONS
**Permissions**: **ALLOWED OPERATIONS**:
- Read all CONTEXT files - **READ**: All CONTEXT files and analyze content
- Create/modify documentation files - **ANALYZE**: Code patterns, architecture, dependencies
- **GENERATE**: Text output, insights, recommendations
- **DOCUMENT**: Analysis results in output response only
**FORBIDDEN OPERATIONS**:
- **NO FILE CREATION**: Cannot create any files on disk
- **NO FILE MODIFICATION**: Cannot modify existing files
- **NO FILE DELETION**: Cannot delete any files
- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
**Execute**: **Execute**:
1. Read and analyze CONTEXT files 1. Read and analyze CONTEXT files
2. Identify patterns and issues 2. Identify patterns and issues
3. Generate insights and recommendations 3. Generate insights and recommendations
4. Create documentation if needed 4. Output structured analysis (text response only)
5. Output structured analysis
**Constraint**: Do NOT modify source code files **CRITICAL CONSTRAINT**: Absolutely NO file system operations - ANALYSIS OUTPUT ONLY
### MODE: write ### MODE: write - FILE CREATION/MODIFICATION OPERATIONS
**Permissions**: **ALLOWED OPERATIONS**:
- Full file operations - **READ**: All CONTEXT files and analyze content
- Create/modify any files - **CREATE**: New files (documentation, code, configuration)
- **MODIFY**: Existing files (update content, refactor code)
- **DELETE**: Files when explicitly required
- **ORGANIZE**: Directory structure operations
**STILL RESTRICTED**:
- Must follow project conventions and patterns
- Cannot break existing functionality
- Must validate changes before completion
**Execute**: **Execute**:
1. Read CONTEXT files 1. Read CONTEXT files

39
.qwen/QWEN.md
View File

@@ -17,28 +17,43 @@ EXPECTED: [deliverables]
RULES: [templates | additional constraints] RULES: [templates | additional constraints]
``` ```
## MODE Definitions ## MODE Definitions - STRICT OPERATION BOUNDARIES
### MODE: analysis (default) ### MODE: analysis (default) - READ-ONLY OPERATIONS
**Permissions**: **ALLOWED OPERATIONS**:
- Read all CONTEXT files - **READ**: All CONTEXT files and analyze content
- Create/modify documentation files - **ANALYZE**: Code patterns, architecture, dependencies
- **GENERATE**: Text output, insights, recommendations
- **DOCUMENT**: Analysis results in output response only
**FORBIDDEN OPERATIONS**:
- **NO FILE CREATION**: Cannot create any files on disk
- **NO FILE MODIFICATION**: Cannot modify existing files
- **NO FILE DELETION**: Cannot delete any files
- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories
**Execute**: **Execute**:
1. Read and analyze CONTEXT files 1. Read and analyze CONTEXT files
2. Identify patterns and issues 2. Identify patterns and issues
3. Generate insights and recommendations 3. Generate insights and recommendations
4. Create documentation if needed 4. Output structured analysis (text response only)
5. Output structured analysis
**Constraint**: Do NOT modify source code files **CRITICAL CONSTRAINT**: Absolutely NO file system operations - ANALYSIS OUTPUT ONLY
### MODE: write ### MODE: write - FILE CREATION/MODIFICATION OPERATIONS
**Permissions**: **ALLOWED OPERATIONS**:
- Full file operations - **READ**: All CONTEXT files and analyze content
- Create/modify any files - **CREATE**: New files (documentation, code, configuration)
- **MODIFY**: Existing files (update content, refactor code)
- **DELETE**: Files when explicitly required
- **ORGANIZE**: Directory structure operations
**STILL RESTRICTED**:
- Must follow project conventions and patterns
- Cannot break existing functionality
- Must validate changes before completion
**Execute**: **Execute**:
1. Read CONTEXT files 1. Read CONTEXT files