mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
feat: Add v1.1 update-memory system with dual-mode operations and enhanced documentation
## New Features - **Dual-mode update-memory commands**: /update-memory-full and /update-memory-related - **Git-aware change detection**: Intelligent context-aware documentation updates - **Complexity-adaptive execution**: Auto-delegation to memory-gemini-bridge for complex projects - **Depth-parallel processing**: Bottom-up execution ensuring proper context propagation - **Enhanced issue tracking integration**: Complete /workflow:issue:* command set documentation ## New Scripts & Infrastructure - detect_changed_modules.sh: Git-based change detection with fallback strategies - get_modules_by_depth.sh: Hierarchical module discovery and organization - update_module_claude.sh: Core CLAUDE.md update execution engine ## Documentation Updates - **README.md**: Added comprehensive update-memory system documentation with usage examples - **README_CN.md**: Complete Chinese localization of new features and technical details - **Command reference tables**: Updated with new /update-memory-* commands and /workflow:issue:* set - **Technical highlights**: Enhanced with dual-mode operations and complexity thresholds - **Usage workflows**: Added detailed examples for different development scenarios ## Technical Improvements - Streamlined memory-gemini-bridge.md (reduced by 200+ lines) - Simplified gemini-unified.md workflow documentation - Added comprehensive CLAUDE.md files for new modules - Enhanced DMS (Distributed Memory System) with 4-layer hierarchy templates ## Architecture Enhancements - **Complexity thresholds**: related mode (>15 modules), full mode (>20 modules) - **Git integration**: Smart change detection with comprehensive status reporting - **User confirmation workflows**: Clear execution plans with mandatory approval steps - **Fallback strategies**: Graceful handling of non-git environments 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
57
.claude/commands/gemini/mode/CLAUDE.md
Normal file
57
.claude/commands/gemini/mode/CLAUDE.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Module: Gemini Mode (`/gemini:mode:*`)
|
||||
|
||||
## Overview
|
||||
|
||||
The `mode` module provides specialized commands for executing the Gemini CLI with different analysis strategies. Each mode is tailored for a specific task, such as bug analysis, project planning, or automatic template selection based on user intent.
|
||||
|
||||
These commands act as wrappers around the core `gemini` CLI, pre-configuring it with specific prompt templates and context settings.
|
||||
|
||||
## Module-Specific Implementation Patterns
|
||||
|
||||
### Command Definition Files
|
||||
|
||||
Each command within the `mode` module is defined by a Markdown file (e.g., `auto.md`, `bug-index.md`). These files contain YAML frontmatter that specifies:
|
||||
- `name`: The command name.
|
||||
- `description`: A brief explanation of the command's purpose.
|
||||
- `usage`: How to invoke the command.
|
||||
- `argument-hint`: A hint for the user about the expected argument.
|
||||
- `examples`: Sample usages.
|
||||
- `allowed-tools`: Tools the command is permitted to use.
|
||||
- `model`: The underlying model to be used.
|
||||
|
||||
The body of the Markdown file provides detailed documentation for the command.
|
||||
|
||||
### Template-Driven Execution
|
||||
|
||||
The core pattern for this module is the use of pre-defined prompt templates stored in `~/.claude/prompt-templates/`. The commands construct a `gemini` CLI call, injecting the content of a specific template into the prompt.
|
||||
|
||||
## Commands and Interfaces
|
||||
|
||||
### `/gemini:mode:auto`
|
||||
- **Purpose**: Automatically selects the most appropriate Gemini template by analyzing the user's input against keywords, names, and descriptions defined in the templates' YAML frontmatter.
|
||||
- **Interface**: `/gemini:mode:auto "description of task"`
|
||||
- **Dependencies**: Relies on the dynamic discovery of templates in `~/.claude/prompt-templates/`.
|
||||
|
||||
### `/gemini:mode:bug-index`
|
||||
- **Purpose**: Executes a systematic bug analysis using a dedicated diagnostic template.
|
||||
- **Interface**: `/gemini:mode:bug-index "bug description"`
|
||||
- **Dependencies**: Uses the `~/.claude/prompt-templates/bug-fix.md` template.
|
||||
|
||||
### `/gemini:mode:plan`
|
||||
- **Purpose**: Performs comprehensive project planning and architecture analysis using a specialized planning template.
|
||||
- **Interface**: `/gemini:mode:plan "planning topic"`
|
||||
- **Dependencies**: Uses the `~/.claude/prompt-templates/plan.md` template.
|
||||
|
||||
## Dependencies and Relationships
|
||||
|
||||
- **External Dependency**: The `mode` module is highly dependent on the prompt templates located in the `~/.claude/prompt-templates/` directory. The structure and metadata (YAML frontmatter) of these templates are critical for the `auto` mode's functionality.
|
||||
- **Internal Relationship**: The commands within this module are independent of each other but share a common purpose of simplifying access to the `gemini` CLI for specific use cases. They do not call each other.
|
||||
- **Core CLI**: All commands are wrappers that ultimately construct and execute a `gemini` shell command.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit Testing**: Not directly applicable as these are command definition files.
|
||||
- **Integration Testing**: Testing should focus on verifying that each command correctly constructs and executes the intended `gemini` CLI command.
|
||||
- For `/gemini:mode:auto`, tests should cover the selection logic with various inputs to ensure the correct template is chosen.
|
||||
- For `/gemini:mode:bug-index` and `/gemini:mode:plan`, tests should confirm that the correct, hardcoded template is used.
|
||||
- **Manual Verification**: Manually running each command with its example arguments is the primary way to ensure they are functioning as documented.
|
||||
117
.claude/commands/update-memory-full.md
Normal file
117
.claude/commands/update-memory-full.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
name: update-memory-full
|
||||
description: Complete project-wide CLAUDE.md documentation update
|
||||
usage: /update-memory-full
|
||||
examples:
|
||||
- /update-memory-full # Full project documentation update
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/update-memory-full`
|
||||
|
||||
Complete project-wide documentation update using depth-parallel execution.
|
||||
|
||||
### 📝 Execution Template
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete project-wide CLAUDE.md documentation update
|
||||
|
||||
# Step 1: Cache git changes
|
||||
Bash(git add -A 2>/dev/null || true)
|
||||
|
||||
# Step 2: Get and display project structure
|
||||
modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
|
||||
count=$(echo "$modules" | wc -l)
|
||||
|
||||
# Step 3: Analysis handover → Model takes control
|
||||
# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
|
||||
|
||||
# Pseudocode flow:
|
||||
# IF (module_count > 20 OR complex_project_detected):
|
||||
# → Task "Complex project full update" subagent_type: "memory-gemini-bridge"
|
||||
# ELSE:
|
||||
# → Present plan and WAIT FOR USER APPROVAL before execution
|
||||
```
|
||||
|
||||
### 🧠 Model Analysis Phase
|
||||
|
||||
After the bash script completes the initial analysis, the model takes control to:
|
||||
|
||||
1. **Analyze Complexity**: Review module count and project context
|
||||
2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
|
||||
3. **Choose Strategy**:
|
||||
- Simple projects: Present execution plan with CLAUDE.md paths to user
|
||||
- Complex projects: Delegate to memory-gemini-bridge agent
|
||||
4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
|
||||
5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
|
||||
|
||||
### 📋 Execution Strategies
|
||||
|
||||
**For Simple Projects (≤20 modules):**
|
||||
|
||||
Model will present detailed plan:
|
||||
```
|
||||
📋 Update Plan:
|
||||
NEW CLAUDE.md files (X):
|
||||
- ./src/components/CLAUDE.md
|
||||
- ./src/services/CLAUDE.md
|
||||
|
||||
UPDATE existing CLAUDE.md files (Y):
|
||||
- ./CLAUDE.md
|
||||
- ./src/CLAUDE.md
|
||||
- ./tests/CLAUDE.md
|
||||
|
||||
Total: N CLAUDE.md files will be processed
|
||||
|
||||
⚠️ Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
```pseudo
|
||||
# ⚠️ MANDATORY: User confirmation → MUST await explicit approval
|
||||
IF user_explicitly_confirms():
|
||||
continue_execution()
|
||||
ELSE:
|
||||
abort_execution()
|
||||
|
||||
# Step 4: Organize modules by depth → Prepare execution
|
||||
depth_modules = organize_by_depth(modules)
|
||||
|
||||
# Step 5: Execute depth-parallel updates → Process by depth
|
||||
FOR depth FROM max_depth DOWN TO 0:
|
||||
FOR each module IN depth_modules[depth]:
|
||||
WHILE active_jobs >= 4: wait(0.1)
|
||||
Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" &)
|
||||
wait_all_jobs()
|
||||
|
||||
# Step 6: Display changes → Final status
|
||||
Bash(git status --short)
|
||||
```
|
||||
|
||||
**For Complex Projects (>20 modules):**
|
||||
The model will delegate to the memory-gemini-bridge agent using the Task tool:
|
||||
```
|
||||
Task "Complex project full update"
|
||||
prompt: "Execute full documentation update for [count] modules using depth-parallel execution"
|
||||
subagent_type: "memory-gemini-bridge"
|
||||
```
|
||||
|
||||
|
||||
### 📚 Usage Examples
|
||||
|
||||
```bash
|
||||
# Complete project documentation refresh
|
||||
/update-memory-full
|
||||
|
||||
# After major architectural changes
|
||||
/update-memory-full
|
||||
```
|
||||
|
||||
### ✨ Features
|
||||
|
||||
- **Separated Commands**: Each bash operation is a discrete, trackable step
|
||||
- **Intelligent Complexity Detection**: Model analyzes project context for optimal strategy
|
||||
- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially
|
||||
- **Git Integration**: Auto-cache changes before, show status after
|
||||
- **Module Detection**: Uses get_modules_by_depth.sh for structure discovery
|
||||
- **User Confirmation**: Clear plan presentation with approval step
|
||||
- **CLAUDE.md Only**: Only updates documentation, never source code
|
||||
123
.claude/commands/update-memory-related.md
Normal file
123
.claude/commands/update-memory-related.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
name: update-memory-related
|
||||
description: Context-aware CLAUDE.md documentation updates based on recent changes
|
||||
usage: /update-memory-related
|
||||
examples:
|
||||
- /update-memory-related # Update documentation based on recent changes
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/update-memory-related`
|
||||
|
||||
Context-aware documentation update for modules affected by recent changes.
|
||||
|
||||
|
||||
### 📝 Execution Template
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Context-aware CLAUDE.md documentation update
|
||||
|
||||
# Step 1: Cache git changes
|
||||
Bash(git add -A 2>/dev/null || true)
|
||||
|
||||
# Step 2: Detect changed modules
|
||||
changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list))
|
||||
if [ -z "$changed" ]; then
|
||||
changed=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list | head -10))
|
||||
fi
|
||||
count=$(echo "$changed" | wc -l)
|
||||
|
||||
# Step 3: Analysis handover → Model takes control
|
||||
# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
|
||||
|
||||
# Pseudocode flow:
|
||||
# IF (change_count > 15 OR complex_changes_detected):
|
||||
# → Task "Complex project related update" subagent_type: "memory-gemini-bridge"
|
||||
# ELSE:
|
||||
# → Present plan and WAIT FOR USER APPROVAL before execution
|
||||
```
|
||||
|
||||
### 🧠 Model Analysis Phase
|
||||
|
||||
After the bash script completes change detection, the model takes control to:
|
||||
|
||||
1. **Analyze Changes**: Review change count and complexity
|
||||
2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
|
||||
3. **Choose Strategy**:
|
||||
- Simple changes: Present execution plan with CLAUDE.md paths to user
|
||||
- Complex changes: Delegate to memory-gemini-bridge agent
|
||||
4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
|
||||
5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
|
||||
|
||||
### 📋 Execution Strategies
|
||||
|
||||
**For Simple Changes (≤15 modules):**
|
||||
|
||||
Model will present detailed plan for affected modules:
|
||||
```
|
||||
📋 Related Update Plan:
|
||||
CHANGED modules affecting CLAUDE.md:
|
||||
|
||||
NEW CLAUDE.md files (X):
|
||||
- ./src/api/auth/CLAUDE.md [new module]
|
||||
- ./src/utils/helpers/CLAUDE.md [new module]
|
||||
|
||||
UPDATE existing CLAUDE.md files (Y):
|
||||
- ./src/api/CLAUDE.md [parent of changed auth/]
|
||||
- ./src/CLAUDE.md [root level]
|
||||
|
||||
Total: N CLAUDE.md files will be processed for recent changes
|
||||
|
||||
⚠️ Confirm execution? (y/n)
|
||||
```
|
||||
|
||||
```pseudo
|
||||
# ⚠️ MANDATORY: User confirmation → MUST await explicit approval
|
||||
IF user_explicitly_confirms():
|
||||
continue_execution()
|
||||
ELSE:
|
||||
abort_execution()
|
||||
|
||||
# Step 4: Organize modules by depth → Prepare execution
|
||||
depth_modules = organize_by_depth(changed_modules)
|
||||
|
||||
# Step 5: Execute depth-parallel updates → Process by depth
|
||||
FOR depth FROM max_depth DOWN TO 0:
|
||||
FOR each module IN depth_modules[depth]:
|
||||
WHILE active_jobs >= 4: wait(0.1)
|
||||
Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" &)
|
||||
wait_all_jobs()
|
||||
|
||||
# Step 6: Display changes → Final status
|
||||
Bash(git diff --stat)
|
||||
```
|
||||
|
||||
**For Complex Changes (>15 modules):**
|
||||
The model will delegate to the memory-gemini-bridge agent using the Task tool:
|
||||
```
|
||||
Task "Complex project related update"
|
||||
prompt: "Execute context-aware update for [count] changed modules using depth-parallel execution"
|
||||
subagent_type: "memory-gemini-bridge"
|
||||
```
|
||||
|
||||
|
||||
### 📚 Usage Examples
|
||||
|
||||
```bash
|
||||
# Daily development update
|
||||
/update-memory-related
|
||||
|
||||
# After feature work
|
||||
/update-memory-related
|
||||
```
|
||||
|
||||
### ✨ Features
|
||||
|
||||
- **Separated Commands**: Each bash operation is a discrete, trackable step
|
||||
- **Intelligent Change Analysis**: Model analyzes change complexity for optimal strategy
|
||||
- **Change Detection**: Automatically finds affected modules using git diff
|
||||
- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially
|
||||
- **Git Integration**: Auto-cache changes, show diff statistics after
|
||||
- **Fallback Mode**: Updates recent files when no git changes found
|
||||
- **User Confirmation**: Clear plan presentation with approval step
|
||||
- **CLAUDE.md Only**: Only updates documentation, never source code
|
||||
@@ -1,354 +0,0 @@
|
||||
---
|
||||
name: update-memory
|
||||
description: Intelligent CLAUDE.md documentation system with context-aware updates
|
||||
usage: /update-memory [mode]
|
||||
argument-hint: [related|full]
|
||||
examples:
|
||||
- /update-memory # Default: related mode (context-based)
|
||||
- /update-memory related # Update only context-related modules
|
||||
- /update-memory full # Full project documentation update
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: `/update-memory`
|
||||
|
||||
- **Type**: Hierarchical Documentation Management System
|
||||
- **Purpose**: To maintain `CLAUDE.md` documentation using intelligent context detection and automatic task partitioning.
|
||||
- **Key Features**: Context-aware updates, strict hierarchy preservation, automatic scaling of execution strategy, and direct file modification via `Gemini --yolo`.
|
||||
|
||||
### ⚙️ Processing Modes
|
||||
|
||||
- **related (Default)**
|
||||
- **Scope**: Updates only context-related modules based on recent changes (git diff, recent edits).
|
||||
- **Action**: Updates affected module `CLAUDE.md` files, their parent hierarchy, and the root `CLAUDE.md`.
|
||||
- **Use Case**: Ideal for daily development, feature updates, and bug fixes.
|
||||
- **full**
|
||||
- **Scope**: Executes a complete, project-wide documentation update.
|
||||
- **Action**: Analyzes the entire project and updates all `CLAUDE.md` files at every hierarchy level.
|
||||
- **Use Case**: Best for major refactoring, project initialization, or periodic maintenance.
|
||||
|
||||
### 🧠 Core Execution Logic: Automatic Strategy Selection
|
||||
|
||||
The command automatically selects an execution strategy based on project complexity. This logic applies to both `related` and `full` modes.
|
||||
|
||||
```pseudo
|
||||
FUNCTION select_execution_strategy(mode):
|
||||
// Step 1: Analyze project scale
|
||||
file_count = count_source_code_files()
|
||||
|
||||
// Step 2: Determine execution strategy based on file count
|
||||
IF file_count < 50:
|
||||
// This action corresponds to the "Small Project" templates.
|
||||
EXECUTE_STRATEGY("Single Gemini Execution")
|
||||
ELSE IF file_count < 200:
|
||||
// This action corresponds to the "Medium Project" templates.
|
||||
EXECUTE_STRATEGY("Parallel Shell Execution")
|
||||
ELSE:
|
||||
// This action corresponds to the "Large Project" template.
|
||||
EXECUTE_STRATEGY("Multi-Agent Coordination")
|
||||
END FUNCTION
|
||||
```
|
||||
|
||||
### 🔍 Context Detection Logic (`related` Mode)
|
||||
|
||||
This describes how the command identifies which files need updating in `related` mode.
|
||||
|
||||
```pseudo
|
||||
FUNCTION detect_affected_modules():
|
||||
// Priority 1: Check for staged or recent git changes.
|
||||
changed_files = get_git_diff_or_status()
|
||||
|
||||
// Priority 2: If no git changes, find recently edited files as a fallback.
|
||||
IF changed_files is empty:
|
||||
changed_files = find_recently_modified_source_files(limit=10)
|
||||
|
||||
// Convert file paths into a unique list of parent directories.
|
||||
affected_modules = extract_unique_directories_from(changed_files)
|
||||
|
||||
RETURN affected_modules
|
||||
END FUNCTION
|
||||
```
|
||||
|
||||
### 📝 Template: Small Project (`related` Mode Update)
|
||||
|
||||
This template is executed when the project is small and the mode is `related`.
|
||||
|
||||
```bash
|
||||
# Single comprehensive analysis
|
||||
gemini --all-files --yolo -p "@{changed_files} @{affected_module/CLAUDE.md} @{CLAUDE.md}
|
||||
Analyze recent changes and update only affected CLAUDE.md files:
|
||||
|
||||
1. Module-level update:
|
||||
- Focus on changed patterns and implementations
|
||||
- Follow Layer 3/4 hierarchy rules
|
||||
- Avoid duplicating parent content
|
||||
|
||||
2. Root-level update:
|
||||
- Reflect only significant architectural changes
|
||||
- Maintain high-level project perspective
|
||||
- Reference but don't duplicate module details
|
||||
|
||||
Only update files that are actually affected by the changes."
|
||||
```
|
||||
|
||||
### 📝 Template: Medium/Large Project (`related` Mode Update)
|
||||
|
||||
This template is executed for medium or large projects in `related` mode.
|
||||
|
||||
```bash
|
||||
# Step-by-step layered update
|
||||
|
||||
# Update affected modules first
|
||||
for module in $affected_modules; do
|
||||
echo "Updating module: $module"
|
||||
gemini --all-files --yolo -p "@{$module/**/*} @{$module/CLAUDE.md}
|
||||
Update $module/CLAUDE.md based on recent changes:
|
||||
- Analyze what specifically changed in this module
|
||||
- Update implementation patterns that were modified
|
||||
- Follow Layer 3 hierarchy rules (module-specific focus)
|
||||
- Do not include project overview or domain-wide patterns
|
||||
- Only document what changed or was impacted"
|
||||
done
|
||||
|
||||
# Update parent domain if structure changed
|
||||
parent_domains=$(echo "$affected_modules" | xargs dirname | sort -u)
|
||||
for domain in $parent_domains; do
|
||||
if [ -f "$domain/CLAUDE.md" ]; then
|
||||
echo "Checking domain impact: $domain"
|
||||
gemini --all-files --yolo -p "@{$domain/*/CLAUDE.md} @{$domain/CLAUDE.md}
|
||||
Review if domain-level documentation needs updates:
|
||||
- Check if module organization changed
|
||||
- Update integration patterns if affected
|
||||
- Follow Layer 2 hierarchy rules (domain focus)
|
||||
- Only update if there are actual structural changes
|
||||
- Do not duplicate module details"
|
||||
fi
|
||||
done
|
||||
|
||||
# Finally, update root if significant changes
|
||||
echo "Updating root documentation"
|
||||
gemini --all-files --yolo -p "@{changed_files} @{*/CLAUDE.md} @{CLAUDE.md}
|
||||
Review and update root CLAUDE.md only if changes affect:
|
||||
- Project architecture or technology stack
|
||||
- Major feature additions
|
||||
- Development workflow changes
|
||||
|
||||
Follow Layer 1 hierarchy rules:
|
||||
- Maintain high-level project perspective
|
||||
- Only reference architectural impacts
|
||||
- Do not duplicate domain or module content"
|
||||
```
|
||||
|
||||
### 📝 Template: Small Project (`full` Mode Update)
|
||||
|
||||
This template is executed when the project is small and the mode is `full`.
|
||||
|
||||
```bash
|
||||
# Single comprehensive analysis with hierarchy awareness
|
||||
gemini --all-files --yolo -p "@{**/*} @{**/*CLAUDE.md}
|
||||
Perform complete project analysis and update all CLAUDE.md files with strict hierarchy:
|
||||
|
||||
1. Root CLAUDE.md (Layer 1):
|
||||
- Project overview, architecture, technology stack
|
||||
- Development guidelines and workflow
|
||||
- Do NOT include implementation details
|
||||
|
||||
2. Domain CLAUDE.md (Layer 2):
|
||||
- Domain architecture and module organization
|
||||
- Inter-module communication patterns
|
||||
- Do NOT duplicate project overview or module internals
|
||||
|
||||
3. Module CLAUDE.md (Layer 3):
|
||||
- Module-specific patterns and internal architecture
|
||||
- API contracts and dependencies
|
||||
- Do NOT duplicate domain patterns or project overview
|
||||
|
||||
4. Sub-module CLAUDE.md (Layer 4):
|
||||
- Implementation specifics and configuration
|
||||
- Usage examples and performance notes
|
||||
- Do NOT duplicate higher-level architecture
|
||||
|
||||
Ensure each layer maintains its proper abstraction level without content duplication."
|
||||
```
|
||||
|
||||
### 📝 Template: Medium Project (`full` Mode Update)
|
||||
|
||||
This template is executed when the project is medium-sized and the mode is `full`.
|
||||
|
||||
```bash
|
||||
# Dependency-aware parallel execution
|
||||
|
||||
echo "🏗️ Layer 1: Foundation modules (parallel)"
|
||||
(
|
||||
gemini --all-files --yolo -p "@{src/utils/**/*} @{src/utils/CLAUDE.md}
|
||||
Update utilities documentation (Layer 3 focus):
|
||||
- Utility patterns and helper functions
|
||||
- Module internal organization
|
||||
- Avoid project/domain overview" &
|
||||
|
||||
gemini --all-files --yolo -p "@{src/types/**/*} @{src/types/CLAUDE.md}
|
||||
Update types documentation (Layer 3 focus):
|
||||
- Type definitions and interface patterns
|
||||
- Type architecture within module
|
||||
- Avoid project/domain overview" &
|
||||
|
||||
gemini --all-files --yolo -p "@{src/core/**/*} @{src/core/CLAUDE.md}
|
||||
Update core documentation (Layer 3 focus):
|
||||
- Core module patterns and initialization
|
||||
- Internal system architecture
|
||||
- Avoid project/domain overview" &
|
||||
wait
|
||||
)
|
||||
|
||||
echo "🏭 Layer 2: Business modules (parallel, with foundation context)"
|
||||
(
|
||||
gemini --all-files --yolo -p "@{src/api/**/*} @{src/core/CLAUDE.md,src/types/CLAUDE.md} @{src/api/CLAUDE.md}
|
||||
Update API documentation with foundation context (Layer 3 focus):
|
||||
- API architecture and endpoint patterns
|
||||
- Integration with core and types modules
|
||||
- Module-specific implementation details
|
||||
- Avoid duplicating foundation or project content" &
|
||||
|
||||
gemini --all-files --yolo -p "@{src/services/**/*} @{src/utils/CLAUDE.md} @{src/services/CLAUDE.md}
|
||||
Update services documentation with utils context (Layer 3 focus):
|
||||
- Service layer patterns and business logic
|
||||
- Integration with utility modules
|
||||
- Module internal architecture
|
||||
- Avoid duplicating utils or project content" &
|
||||
wait
|
||||
)
|
||||
|
||||
echo "🎨 Layer 3: Application modules (parallel, with business context)"
|
||||
(
|
||||
gemini --all-files --yolo -p "@{src/components/**/*} @{src/api/CLAUDE.md} @{src/components/CLAUDE.md}
|
||||
Update components documentation with API context (Layer 3 focus):
|
||||
- Component architecture and patterns
|
||||
- API integration approaches
|
||||
- Module-specific UI patterns
|
||||
- Avoid duplicating API or project content" &
|
||||
|
||||
gemini --all-files --yolo -p "@{src/pages/**/*} @{src/services/CLAUDE.md} @{src/pages/CLAUDE.md}
|
||||
Update pages documentation with services context (Layer 3 focus):
|
||||
- Page structure and routing patterns
|
||||
- Service utilization approaches
|
||||
- Module-specific page architecture
|
||||
- Avoid duplicating services or project content" &
|
||||
wait
|
||||
)
|
||||
|
||||
echo "📋 Layer 4: Domain integration"
|
||||
gemini --all-files --yolo -p "@{src/*/CLAUDE.md} @{src/CLAUDE.md}
|
||||
Update src domain documentation (Layer 2 focus):
|
||||
- Synthesize module organization and relationships
|
||||
- Domain-wide architecture patterns
|
||||
- Inter-module communication strategies
|
||||
- Do NOT duplicate module implementation details
|
||||
- Do NOT duplicate project overview content"
|
||||
|
||||
echo "🎯 Layer 5: Root integration"
|
||||
gemini --all-files --yolo -p "@{*/CLAUDE.md} @{CLAUDE.md}
|
||||
Update root documentation (Layer 1 focus):
|
||||
- High-level project architecture and overview
|
||||
- Technology stack summary and decisions
|
||||
- Development workflow and guidelines
|
||||
- Do NOT duplicate domain-specific content
|
||||
- Do NOT include implementation details"
|
||||
```
|
||||
|
||||
### 📝 Template: Large Project (`full` Mode Update)
|
||||
|
||||
This YAML-based plan is used for large projects in `full` mode, coordinating multiple agents.
|
||||
|
||||
```yaml
|
||||
# Multi-agent coordination for complex projects
|
||||
Main Coordinator Agent:
|
||||
description: "Coordinate full documentation update"
|
||||
subagent_type: "memory-gemini-bridge"
|
||||
prompt: |
|
||||
Execute large project full documentation update:
|
||||
|
||||
1. Analyze project structure:
|
||||
gemini --all-files -p "@{**/*} Identify major domains, complexity, and module relationships"
|
||||
|
||||
2. Launch parallel domain agents:
|
||||
- Each agent handles one domain (frontend, backend, infrastructure)
|
||||
- Each agent follows hierarchy rules strictly
|
||||
- Each agent avoids content duplication
|
||||
|
||||
3. Final integration:
|
||||
gemini --all-files --yolo -p "@{*/CLAUDE.md} @{CLAUDE.md}
|
||||
Update root with Layer 1 focus only:
|
||||
- Project overview and architecture
|
||||
- Technology stack decisions
|
||||
- Development workflow
|
||||
- Do NOT duplicate domain details"
|
||||
|
||||
Frontend Domain Agent:
|
||||
prompt: |
|
||||
Update frontend domain with hierarchy awareness:
|
||||
|
||||
1. Module updates (Layer 3):
|
||||
gemini --all-files --yolo -p "@{src/components/**/*} @{src/components/CLAUDE.md}
|
||||
Component-specific patterns and architecture"
|
||||
|
||||
gemini --all-files --yolo -p "@{src/pages/**/*} @{src/pages/CLAUDE.md}
|
||||
Page-specific patterns and routing"
|
||||
|
||||
2. Domain integration (Layer 2):
|
||||
gemini --all-files --yolo -p "@{src/frontend/*/CLAUDE.md} @{src/frontend/CLAUDE.md}
|
||||
Frontend domain architecture, module relationships
|
||||
Do NOT duplicate component details or project overview"
|
||||
|
||||
Backend Domain Agent:
|
||||
prompt: |
|
||||
Update backend domain with hierarchy awareness:
|
||||
|
||||
1. Module updates (Layer 3):
|
||||
gemini --all-files --yolo -p "@{src/api/**/*} @{src/api/CLAUDE.md}
|
||||
API-specific patterns and endpoints"
|
||||
|
||||
gemini --all-files --yolo -p "@{src/services/**/*} @{src/services/CLAUDE.md}
|
||||
Service-specific business logic and patterns"
|
||||
|
||||
2. Domain integration (Layer 2):
|
||||
gemini --all-files --yolo -p "@{src/backend/*/CLAUDE.md} @{src/backend/CLAUDE.md}
|
||||
Backend domain architecture, service relationships
|
||||
Do NOT duplicate service details or project overview"
|
||||
```
|
||||
|
||||
### 📈 Performance Characteristics
|
||||
|
||||
| Mode | Small Project (<50 files) | Medium Project (50-200 files) | Large Project (>200 files) |
|
||||
| :-------- | :------------------------ | :---------------------------- | :------------------------- |
|
||||
| **related** | <1 minute | 1-3 minutes | 3-5 minutes |
|
||||
| **full** | 1-2 minutes | 3-5 minutes | 10-15 minutes |
|
||||
|
||||
### 📚 Usage Examples
|
||||
|
||||
```bash
|
||||
# Daily development (automatically detects what you've been working on)
|
||||
/update-memory
|
||||
|
||||
# After working in a specific module, explicitly run related mode
|
||||
cd src/api && /update-memory related
|
||||
|
||||
# Weekly full refresh for project-wide consistency
|
||||
/update-memory full
|
||||
|
||||
# Intelligently update based on a large refactoring commit
|
||||
git add -A && git commit -m "Major refactoring"
|
||||
/update-memory related
|
||||
```
|
||||
|
||||
### ✨ Key Features
|
||||
|
||||
- **Context Intelligence**: Automatically detects which modules need updating based on recent changes.
|
||||
- **Hierarchy Preservation**: Enforces strict content boundaries between documentation layers to prevent duplication.
|
||||
- **Smart Partitioning**: Dynamically scales its execution strategy (single, parallel, multi-agent) based on project size.
|
||||
- **Zero Configuration**: Works out-of-the-box with intelligent defaults for context detection and execution.
|
||||
|
||||
### 📝 Best Practices
|
||||
|
||||
- Use `related` mode for daily development; it's fast and focused.
|
||||
- Run `full` mode weekly or after major architectural changes to ensure consistency.
|
||||
- Trust the hierarchy; let each `CLAUDE.md` file serve its specific layer of abstraction.
|
||||
- Allow the automatic context detection to guide updates rather than manually specifying files.
|
||||
75
.claude/commands/workflow/brainstorm/CLAUDE.md
Normal file
75
.claude/commands/workflow/brainstorm/CLAUDE.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# Module Analysis: `workflow:brainstorm`
|
||||
|
||||
## 1. Module-specific Implementation Patterns
|
||||
|
||||
### Role-Based Command Structure
|
||||
The `brainstorm` workflow is composed of multiple, distinct "role" commands. Each role is defined in its own Markdown file (e.g., `product-manager.md`, `system-architect.md`). This modular design allows for easy extension by adding new role files.
|
||||
|
||||
- **Command Naming Convention**: Each role is invoked via a consistent command structure: `/workflow:brainstorm:<role-name> <topic>`.
|
||||
- **File Naming Convention**: The command's `<role-name>` corresponds directly to the filename (e.g., `product-manager.md` implements `/workflow:brainstorm:product-manager`).
|
||||
|
||||
### Standardized Role Definition Structure
|
||||
Each role's `.md` file follows a strict, standardized structure:
|
||||
1. **Frontmatter**: Defines the command `name`, `description`, `usage`, `argument-hint`, `examples`, and `allowed-tools`. All roles consistently use `Task(conceptual-planning-agent)` and `TodoWrite(*)`.
|
||||
2. **Role Overview**: Defines the role's purpose, responsibilities, and success metrics.
|
||||
3. **Analysis Framework**: References shared principles (`brainstorming-principles.md`, `brainstorming-framework.md`) and lists key questions specific to the role's perspective.
|
||||
4. **Execution Protocol**: A multi-phase process detailing session detection, directory creation, task initialization (`TodoWrite`), and delegation to the `conceptual-planning-agent`.
|
||||
5. **Output Specification**: Defines the directory structure and file templates for the analysis artifacts generated by the role.
|
||||
6. **Session Integration**: Specifies how the role's output integrates with the parent session state (`workflow-session.json`).
|
||||
7. **Quality Assurance**: Provides checklists and standards for validating the quality of the role's output.
|
||||
|
||||
## 2. Internal Architecture and Design Decisions
|
||||
|
||||
### Session-Based Workflow
|
||||
The entire workflow is stateful and session-based, managed within the `.workflow/` directory.
|
||||
- **State Management**: An active session is marked by a `.workflow/.active-*` file.
|
||||
- **Output Scaffolding**: Each role command creates a dedicated output directory: `.workflow/WFS-{topic-slug}/.brainstorming/<role-name>/`. This isolates each perspective's artifacts.
|
||||
|
||||
### "Map-Reduce" Architectural Pattern
|
||||
The workflow follows a pattern analogous to Map-Reduce:
|
||||
- **Map Phase**: Each individual role command (`product-manager`, `ui-designer`, etc.) acts as a "mapper". It takes the input `{topic}` and produces a detailed analysis from its unique perspective.
|
||||
- **Reduce Phase**: The `synthesis` command acts as the "reducer". It collects the outputs from all completed roles, integrates them, identifies consensus and conflicts, and produces a single, comprehensive strategic report.
|
||||
|
||||
### Delegation to `conceptual-planning-agent`
|
||||
The core analytical work is not performed by the commands themselves. Instead, they act as templating engines that construct a detailed prompt for the `conceptual-planning-agent`. This design decision centralizes the complex reasoning and generation logic into a single, powerful tool, while the Markdown files serve as declarative "configurations" for that tool.
|
||||
|
||||
## 3. API Contracts and Interfaces
|
||||
|
||||
### Command-Line Interface (CLI)
|
||||
The primary user-facing interface is the set of CLI commands:
|
||||
- **Role Commands**: `/workflow:brainstorm:<role-name> <topic>`
|
||||
- **Synthesis Command**: `/workflow:brainstorm:synthesis` (no arguments)
|
||||
|
||||
### `conceptual-planning-agent` Contract
|
||||
The interface with the planning agent is a structured prompt passed to the `Task()` tool. This prompt consistently contains:
|
||||
- `ASSIGNED_ROLE` / `ROLE CONTEXT`: Defines the persona for the agent.
|
||||
- `USER_CONTEXT`: Injects user requirements from the session.
|
||||
- `ANALYSIS_REQUIREMENTS`: A detailed, numbered list of tasks for the agent to perform.
|
||||
- `OUTPUT REQUIREMENTS`: Specifies the exact file paths and high-level content structure for the generated artifacts.
|
||||
|
||||
### Filesystem Contract
|
||||
The workflow relies on a strict filesystem structure for state and outputs:
|
||||
- **Session State**: `.workflow/WFS-{topic-slug}/workflow-session.json` is updated by each role to track progress.
|
||||
- **Role Outputs**: Each role must produce a set of `.md` files in its designated directory (e.g., `analysis.md`, `roadmap.md`).
|
||||
- **Synthesis Input**: The `synthesis` command expects to find these specific output files to perform its function.
|
||||
|
||||
## 4. Module Dependencies and Relationships
|
||||
|
||||
- **Internal Dependencies**:
|
||||
- The `synthesis` command is dependent on the outputs of all other role commands. It cannot function until one or more roles have completed their analysis.
|
||||
- Individual role commands are largely independent of one another.
|
||||
|
||||
- **External Dependencies**:
|
||||
- **`conceptual-planning-agent`**: All roles have a critical dependency on this tool for their core logic.
|
||||
- **Shared Frameworks**: All roles include and depend on `@~/.claude/workflows/brainstorming-principles.md` and `@~/.claude/workflows/brainstorming-framework.md`, ensuring a consistent analytical foundation.
|
||||
|
||||
## 5. Testing Strategies
|
||||
|
||||
This module does not contain automated tests. Validation relies on a set of quality assurance standards defined within each role's Markdown file.
|
||||
|
||||
- **Checklist-Based Validation**: Each file contains a "Quality Assurance" or "Quality Standards" section with checklists for:
|
||||
- **Required Analysis Elements**: Ensures all necessary components are present in the output.
|
||||
- **Core Principles**: Validates that the analysis adheres to the role's guiding principles (e.g., "User-Centric", "Data-Driven").
|
||||
- **Quality Metrics**: Provides criteria for assessing the quality of the output (e.g., "Requirements completeness", "Feasibility of implementation plan").
|
||||
|
||||
This approach serves as a form of manual, requirement-based testing for the output generated by the `conceptual-planning-agent`.
|
||||
@@ -2,7 +2,6 @@
|
||||
name: list
|
||||
description: List all workflow sessions with status
|
||||
usage: /workflow:session:list
|
||||
|
||||
---
|
||||
|
||||
# List Workflow Sessions (/workflow/session/list)
|
||||
|
||||
Reference in New Issue
Block a user