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

refactor: Enhance workflow system with comprehensive improvements

Browse Source 
Agent enhancements:
- Add free exploration phase for supplementary context gathering
- Update project structure documentation with detailed hierarchy
- Improve summary template with standardized naming convention
- Add comprehensive search strategies with bash command examples

Architecture improvements:
- Add extensive combined search strategy examples (rg, grep, find, awk, sed)
- Enhance flow control with pattern discovery commands
- Update path reference format for session-specific commands
- Improve session naming rules with WFS prefix explanation
- Reorganize document structure for better readability

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-15 23:31:51 +08:00
parent 2879c3c00d
commit ab32650cf8
3 changed files with 198 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
.claude/agents/code-developer.md
View File

@@ -65,6 +65,7 @@ ELIF context insufficient OR task has flow control marker:
- **Dependency Loading**: Read summaries from context.depends_on automatically - **Dependency Loading**: Read summaries from context.depends_on automatically
- **Context Accumulation**: Pass step outputs to subsequent steps via [variable_name] - **Context Accumulation**: Pass step outputs to subsequent steps via [variable_name]
- **Error Handling**: Apply on_error strategies per step (skip_optional, fail, retry_once, manual_intervention) - **Error Handling**: Apply on_error strategies per step (skip_optional, fail, retry_once, manual_intervention)
- **Free Exploration Phase**: After completing pre_analysis steps, can enter additional exploration using bash commands (grep, find, rg, awk, sed) or CLI tools to gather supplementary context if needed
- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md - **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md and @~/.claude/workflows/tools-implementation-guide.md
@@ -120,9 +121,15 @@ ELIF context insufficient OR task has flow control marker:
**Project Structure Understanding**: **Project Structure Understanding**:
``` ```
.workflow/WFS-[session-id]/ # (Path provided in session context) .workflow/WFS-[session-id]/ # (Path provided in session context)
├── TODO_LIST.md # Progress tracking document ├── workflow-session.json # Session metadata and state (REQUIRED)
├── .task/IMPL-*.json # Task definitions (source of truth) ├── IMPL_PLAN.md # Planning document (REQUIRED)
└── .summaries/IMPL-*.md # Task completion summaries ├── TODO_LIST.md # Progress tracking document (REQUIRED)
├── .task/ # Task definitions (REQUIRED)
│ ├── IMPL-*.json # Main task definitions
│ └── IMPL-*.*.json # Subtask definitions (created dynamically)
└── .summaries/ # Task completion summaries (created when tasks complete)
├── IMPL-*-summary.md # Main task summaries
└── IMPL-*.*-summary.md # Subtask summaries
``` ```
**Example TODO_LIST.md Update**: **Example TODO_LIST.md Update**:
@@ -144,11 +151,11 @@ ELIF context insufficient OR task has flow control marker:
``` ```
3. **Generate Summary** (using session context paths): 3. **Generate Summary** (using session context paths):
- **MANDATORY**: Create summary in provided Summaries Directory - **MANDATORY**: Create summary in provided summaries directory
- Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`) - Use exact paths from session context (e.g., `.workflow/WFS-[session-id]/.summaries/`)
- Link summary in TODO_LIST.md using relative path - Link summary in TODO_LIST.md using relative path
**Enhanced Summary Template**: **Enhanced Summary Template** (using naming convention `IMPL-[task-id]-summary.md`):
```markdown ```markdown
# Task: [Task-ID] [Name] # Task: [Task-ID] [Name]
@@ -188,6 +195,11 @@ ELIF context insufficient OR task has flow control marker:
## Status: ✅ Complete ## Status: ✅ Complete
``` ```
**Summary Naming Convention** (per workflow-architecture.md):
- **Main tasks**: `IMPL-[task-id]-summary.md` (e.g., `IMPL-001-summary.md`)
- **Subtasks**: `IMPL-[task-id].[subtask-id]-summary.md` (e.g., `IMPL-001.1-summary.md`)
- **Location**: Always in `.summaries/` directory within session workflow folder
**Auto-Check Workflow Context**: **Auto-Check Workflow Context**:
- Verify session context paths are provided in agent prompt - Verify session context paths are provided in agent prompt

1
.claude/agents/code-review-test-agent.md
View File

@@ -58,6 +58,7 @@ When task assignment includes flow control marker:
- **Context variable handling**: Process [variable_name] references in commands - **Context variable handling**: Process [variable_name] references in commands
- **Sequential execution**: Execute each step in order, accumulating context through variables - **Sequential execution**: Execute each step in order, accumulating context through variables
- **Error handling**: Apply per-step error strategies - **Error handling**: Apply per-step error strategies
- **Free Exploration Phase**: After completing pre_analysis steps, can enter additional exploration using bash commands (grep, find, rg, awk, sed) or CLI tools to gather supplementary context for more thorough review
**Context Gathering Decision Logic**: **Context Gathering Decision Logic**:
``` ```

246
.claude/workflows/workflow-architecture.md
View File

@@ -4,8 +4,6 @@
This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition. This document defines the complete workflow system architecture using a **JSON-only data model**, **marker-based session management**, and **unified file structure** with dynamic task decomposition.
## Core Architecture Principles
### Key Design Decisions ### Key Design Decisions
- **JSON files are the single source of truth** - All markdown documents are read-only generated views - **JSON files are the single source of truth** - All markdown documents are read-only generated views
- **Marker files for session tracking** - Ultra-simple active session management - **Marker files for session tracking** - Ultra-simple active session management
@@ -76,6 +74,22 @@ Each session directory contains `workflow-session.json`:
- **No Synchronization**: Eliminates bidirectional sync complexity - **No Synchronization**: Eliminates bidirectional sync complexity
- **Performance**: Direct JSON access without parsing overhead - **Performance**: Direct JSON access without parsing overhead
### Hierarchical Task System
**Maximum Depth**: 2 levels (IMPL-N.M format)
```
IMPL-1 # Main task
IMPL-1.1 # Subtask of IMPL-1 (dynamically created)
IMPL-1.2 # Another subtask of IMPL-1
IMPL-2 # Another main task
IMPL-2.1 # Subtask of IMPL-2 (dynamically created)
```
**Task Status Rules**:
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
- **Leaf tasks**: Only these can be executed directly
- **Status inheritance**: Parent status derived from subtask completion
### Task JSON Schema ### Task JSON Schema
All task files use this simplified 5-field schema: All task files use this simplified 5-field schema:
@@ -110,7 +124,7 @@ All task files use this simplified 5-field schema:
{ {
"step": "gather_context", "step": "gather_context",
"action": "Read dependency summaries", "action": "Read dependency summaries",
"command": "bash(cat .workflow/*/summaries/IMPL-1.1-summary.md)", "command": "bash(cat .workflow/WFS-[session-id]/.summaries/IMPL-1.1-summary.md)",
"output_to": "auth_design_context", "output_to": "auth_design_context",
"on_error": "skip_optional" "on_error": "skip_optional"
}, },
@@ -202,11 +216,106 @@ Each step contains:
- **Task Properties**: Use `[depends_on]`, `[focus_paths]` to reference task JSON properties - **Task Properties**: Use `[depends_on]`, `[focus_paths]` to reference task JSON properties
- **Bash Compatibility**: Avoids conflicts with bash `${}` variable expansion - **Bash Compatibility**: Avoids conflicts with bash `${}` variable expansion
#### Path Reference Format
- **Session-Specific**: Use `.workflow/WFS-[session-id]/` for commands within active session context
- **Cross-Session**: Use `.workflow/*/` only when accessing multiple sessions (rare cases)
- **Relative Paths**: Use `.summaries/` when executing from within session directory
#### Command Types Supported #### Command Types Supported
- **CLI Analysis**: `bash(~/.claude/scripts/gemini-wrapper -p 'prompt')` - **CLI Analysis**: `bash(~/.claude/scripts/gemini-wrapper -p 'prompt')`
- **Agent Execution**: `bash(codex --full-auto exec 'task description')` - **Agent Execution**: `bash(codex --full-auto exec 'task description')`
- **Shell Commands**: `bash(cat)`, `bash(grep)`, `bash(find)`, `bash(custom scripts)` - **Shell Commands**: `bash(cat)`, `bash(grep)`, `bash(find)`, `bash(rg)`, `bash(awk)`, `bash(sed)`, `bash(custom scripts)`
- **Search Pipelines**: `bash(find + grep combinations)`, `bash(rg + jq processing)`, `bash(pattern discovery chains)`
- **Context Processing**: `bash(file reading)`, `bash(dependency loading)`, `bash(context merging)` - **Context Processing**: `bash(file reading)`, `bash(dependency loading)`, `bash(context merging)`
- **Combined Analysis**: `bash(multi-tool command pipelines for comprehensive analysis)`
#### Combined Search Strategies
The pre_analysis system supports flexible command combinations beyond just codex and gemini CLI tools. You can chain together grep, ripgrep (rg), find, awk, sed, and other bash commands for powerful analysis pipelines.
**Pattern Discovery Commands**:
```json
// Search for authentication patterns with context
{
"step": "find_auth_patterns",
"action": "Discover authentication patterns across codebase",
"command": "bash(rg -A 3 -B 3 'authenticate|login|jwt|auth' --type ts --type js | head -50)",
"output_to": "auth_patterns",
"on_error": "skip_optional"
}
// Find related test files
{
"step": "discover_test_files",
"action": "Locate test files related to authentication",
"command": "bash(find . -type f \\( -name '*test*' -o -name '*spec*' \\) | xargs rg -l 'auth|login' 2>/dev/null | head -10)",
"output_to": "test_files",
"on_error": "skip_optional"
}
// Extract interface definitions
{
"step": "extract_interfaces",
"action": "Extract TypeScript interface definitions",
"command": "bash(rg '^\\s*interface\\s+\\w+' --type ts -A 5 [focus_paths] | awk '/^[[:space:]]*interface/{p=1} p&&/^[[:space:]]*}/{p=0;print;print\"\"}')",
"output_to": "interfaces",
"on_error": "skip_optional"
}
```
**File Discovery Commands**:
```json
// Find configuration files
{
"step": "find_config_files",
"action": "Locate configuration files related to auth",
"command": "bash(find [focus_paths] -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.env*' \\) | xargs rg -l 'auth|jwt|token' 2>/dev/null)",
"output_to": "config_files",
"on_error": "skip_optional"
}
// Discover API endpoints
{
"step": "find_api_endpoints",
"action": "Find API route definitions",
"command": "bash(rg -n 'app\\.(get|post|put|delete|patch).*auth|router\\.(get|post|put|delete|patch).*auth' --type js --type ts [focus_paths])",
"output_to": "api_routes",
"on_error": "skip_optional"
}
```
**Advanced Analysis Commands**:
```json
// Analyze import dependencies
{
"step": "analyze_imports",
"action": "Map import dependencies for auth modules",
"command": "bash(rg '^import.*from.*auth' --type ts --type js [focus_paths] | awk -F'from' '{print $2}' | sort | uniq -c | sort -nr)",
"output_to": "import_analysis",
"on_error": "skip_optional"
}
// Count function definitions
{
"step": "count_functions",
"action": "Count and categorize function definitions",
"command": "bash(rg '^\\s*(function|const\\s+\\w+\\s*=|export\\s+(function|const))' --type ts --type js [focus_paths] | wc -l)",
"output_to": "function_count",
"on_error": "skip_optional"
}
```
**Context Merging Commands**:
```json
// Combine multiple analysis results
{
"step": "merge_analysis",
"action": "Combine pattern and structure analysis",
"command": "bash(echo 'Auth Patterns:'; echo '[auth_patterns]'; echo; echo 'Test Files:'; echo '[test_files]'; echo; echo 'Config Files:'; echo '[config_files]')",
"output_to": "combined_context",
"on_error": "skip_optional"
}
```
#### Error Handling Strategies #### Error Handling Strategies
- **skip_optional**: Continue execution, step result is empty - **skip_optional**: Continue execution, step result is empty
@@ -221,21 +330,35 @@ Each step contains:
{ {
"step": "gather_dependencies", "step": "gather_dependencies",
"action": "Load context from completed dependencies", "action": "Load context from completed dependencies",
"command": "bash(for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo \"No summary for $dep\"; done)", "command": "bash(for dep in ${depends_on}; do cat .workflow/WFS-[session-id]/.summaries/${dep}-summary.md 2>/dev/null || echo \"No summary for $dep\"; done)",
"output_to": "dependency_context", "output_to": "dependency_context",
"on_error": "skip_optional" "on_error": "skip_optional"
}, },
{
"step": "discover_patterns",
"action": "Find existing patterns using combined search",
"command": "bash(rg -A 2 -B 2 'class.*Auth|interface.*Auth|type.*Auth' --type ts [focus_paths] | head -30)",
"output_to": "auth_patterns",
"on_error": "skip_optional"
},
{
"step": "find_related_files",
"action": "Discover related implementation files",
"command": "bash(find [focus_paths] -type f -name '*.ts' -o -name '*.js' | xargs rg -l 'auth|login|jwt' 2>/dev/null | head -15)",
"output_to": "related_files",
"on_error": "skip_optional"
},
{ {
"step": "analyze_codebase", "step": "analyze_codebase",
"action": "Understand current implementation", "action": "Understand current implementation with Gemini",
"command": "bash(gemini -p '@{[focus_paths]} analyze current patterns using context: [dependency_context]')", "command": "bash(~/.claude/scripts/gemini-wrapper -p 'Analyze patterns: [auth_patterns] in files: [related_files] using context: [dependency_context]')",
"output_to": "codebase_analysis", "output_to": "codebase_analysis",
"on_error": "fail" "on_error": "fail"
}, },
{ {
"step": "implement", "step": "implement",
"action": "Execute implementation based on analysis", "action": "Execute implementation based on comprehensive analysis",
"command": "bash(codex --full-auto exec 'Implement based on: [codebase_analysis] with dependency context: [dependency_context]')", "command": "bash(codex --full-auto exec 'Implement based on: [codebase_analysis] with discovered patterns: [auth_patterns] and dependency context: [dependency_context]')",
"on_error": "manual_intervention" "on_error": "manual_intervention"
} }
], ],
@@ -262,22 +385,6 @@ Each step contains:
- **Command Flexibility**: Supports any executable command or agent - **Command Flexibility**: Supports any executable command or agent
- **Dependency Integration**: Automatic loading of prerequisite task results - **Dependency Integration**: Automatic loading of prerequisite task results
### Hierarchical Task System
**Maximum Depth**: 2 levels (IMPL-N.M format)
```
IMPL-1 # Main task
IMPL-1.1 # Subtask of IMPL-1 (dynamically created)
IMPL-1.2 # Another subtask of IMPL-1
IMPL-2 # Another main task
IMPL-2.1 # Subtask of IMPL-2 (dynamically created)
```
**Task Status Rules**:
- **Container tasks**: Parent tasks with subtasks (cannot be directly executed)
- **Leaf tasks**: Only these can be executed directly
- **Status inheritance**: Parent status derived from subtask completion
## File Structure ## File Structure
### Unified File Structure ### Unified File Structure
@@ -313,8 +420,16 @@ All workflows use the same file structure definition regardless of complexity. *
#### Session Identifiers #### Session Identifiers
**Format**: `WFS-[topic-slug]` **Format**: `WFS-[topic-slug]`
**WFS Prefix Meaning**:
- `WFS` = **W**ork**F**low **S**ession
- Identifies directories as workflow session containers
- Distinguishes workflow sessions from other project directories
**Naming Rules**:
- Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`) - Convert topic to lowercase with hyphens (e.g., "User Auth System" → `WFS-user-auth-system`)
- Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`) - Add `-NNN` suffix only if conflicts exist (e.g., `WFS-payment-integration-002`)
- Maximum length: 50 characters including WFS- prefix
#### Document Naming #### Document Naming
- `workflow-session.json` - Session state (required) - `workflow-session.json` - Session state (required)
@@ -323,56 +438,22 @@ All workflows use the same file structure definition regardless of complexity. *
- Chat sessions: `chat-analysis-*.md` - Chat sessions: `chat-analysis-*.md`
- Task summaries: `IMPL-[task-id]-summary.md` - Task summaries: `IMPL-[task-id]-summary.md`
## Complexity Classification
### Task Complexity Rules ### Document Templates
**Complexity is determined by task count and decomposition needs:**
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior | #### IMPL_PLAN.md Template
|------------|------------|----------------|----------------------|
| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
### Simple Workflows
**Characteristics**: Direct implementation tasks with clear, limited scope
- **Examples**: Bug fixes, small feature additions, configuration changes
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
- **Agent Coordination**: Direct execution without complex orchestration
### Medium Workflows
**Characteristics**: Feature implementation requiring moderate task breakdown
- **Examples**: New features, API endpoints with integration, database schema changes
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
- **Agent Coordination**: Context coordination between related tasks
### Complex Workflows
**Characteristics**: System-wide changes requiring detailed decomposition
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
### Automatic Assessment & Upgrades
- **During Creation**: System evaluates requirements and assigns complexity
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
- **Override Allowed**: Users can specify higher complexity manually
## Document Templates
### IMPL_PLAN.md
Generated based on task complexity and requirements. Contains overview, requirements, and task structure. Generated based on task complexity and requirements. Contains overview, requirements, and task structure.
## Notes for Future Tasks **Notes for Future Tasks**: [Any important considerations, limitations, or follow-up items]
[Any important considerations, limitations, or follow-up items]
#### Summary Document Purpose **Summary Document Purpose**:
- **Context Inheritance**: Provides structured context for dependent tasks - **Context Inheritance**: Provides structured context for dependent tasks
- **Integration Guidance**: Offers clear integration points and usage instructions - **Integration Guidance**: Offers clear integration points and usage instructions
- **Quality Assurance**: Documents testing and validation performed - **Quality Assurance**: Documents testing and validation performed
- **Decision History**: Preserves rationale for implementation choices - **Decision History**: Preserves rationale for implementation choices
- **Dependency Chain**: Enables automatic context accumulation through task dependencies - **Dependency Chain**: Enables automatic context accumulation through task dependencies
### TODO_LIST.md Template #### TODO_LIST.md Template
```markdown ```markdown
# Tasks: [Session Topic] # Tasks: [Session Topic]
@@ -402,7 +483,7 @@ Generated based on task complexity and requirements. Contains overview, requirem
### Agent Assignment ### Agent Assignment
Based on task type and title keywords: Based on task type and title keywords:
- **Planning tasks** → planning-agent - **Planning tasks** → planning-agent
- **Implementation** → code-developer - **Implementation** → code-developer
- **Testing** → code-review-test-agent - **Testing** → code-review-test-agent
- **Review** → review-agent - **Review** → review-agent
@@ -418,7 +499,6 @@ Agents receive complete task JSON plus workflow context:
} }
``` ```
## Data Operations ## Data Operations
### Session Initialization ### Session Initialization
@@ -454,6 +534,40 @@ jq '.status = "active"' .task/IMPL-1.json > temp && mv temp .task/IMPL-1.json
generate_todo_list_from_json .task/ generate_todo_list_from_json .task/
``` ```
## Complexity Classification
### Task Complexity Rules
**Complexity is determined by task count and decomposition needs:**
| Complexity | Task Count | Hierarchy Depth | Decomposition Behavior |
|------------|------------|----------------|----------------------|
| **Simple** | <5 tasks | 1 level (IMPL-N) | Direct execution, minimal decomposition |
| **Medium** | 5-15 tasks | 2 levels (IMPL-N.M) | Moderate decomposition, context coordination |
| **Complex** | >15 tasks | 2 levels (IMPL-N.M) | Frequent decomposition, multi-agent orchestration |
### Simple Workflows
**Characteristics**: Direct implementation tasks with clear, limited scope
- **Examples**: Bug fixes, small feature additions, configuration changes
- **Task Decomposition**: Usually single-level tasks, minimal breakdown needed
- **Agent Coordination**: Direct execution without complex orchestration
### Medium Workflows
**Characteristics**: Feature implementation requiring moderate task breakdown
- **Examples**: New features, API endpoints with integration, database schema changes
- **Task Decomposition**: Two-level hierarchy when decomposition is needed
- **Agent Coordination**: Context coordination between related tasks
### Complex Workflows
**Characteristics**: System-wide changes requiring detailed decomposition
- **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
- **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
- **Agent Coordination**: Multi-agent orchestration with deep context analysis
### Automatic Assessment & Upgrades
- **During Creation**: System evaluates requirements and assigns complexity
- **During Execution**: Can upgrade (Simple→Medium→Complex) but never downgrade
- **Override Allowed**: Users can specify higher complexity manually
## Validation and Error Handling ## Validation and Error Handling
### Task Integrity Rules ### Task Integrity Rules