mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
feat: Implement intelligent task saturation control for workflow planning
- Add task saturation assessment to merge preparation with execution when appropriate - Optimize complexity thresholds: <3/<8 saturated tasks instead of <5/<15 - Enhance JSON schema with preparation_complexity, preparation_tasks, estimated_prep_time - Update execute.md to handle merged tasks with PREPARATION_INCLUDED marker - Add document reference paths for execution phase - Reduce task fragmentation while preserving complex preparation when needed 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -70,9 +70,10 @@ Workflow Discovery:
|
||||
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
|
||||
- [ ] **TASK-004**: Update task statuses and session state
|
||||
|
||||
**Marker Legend**:
|
||||
**Marker Legend**:
|
||||
- [GEMINI_CLI_REQUIRED] = Agent must use Gemini CLI for pattern analysis
|
||||
- [CODEX_CLI_REQUIRED] = Agent must use Codex CLI for autonomous analysis
|
||||
- [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement)
|
||||
```
|
||||
|
||||
### 3. Agent Context Assignment
|
||||
@@ -144,20 +145,30 @@ For each executable task:
|
||||
- **Workflow Integration**: Include session state and IMPL_PLAN.md context
|
||||
- **Scope Focus**: Direct agents to specific files from implementation.files[].path
|
||||
- **Gemini Marker**: Auto-add [GEMINI_CLI_REQUIRED] when analysis_source = "gemini"
|
||||
- **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists
|
||||
|
||||
### 4. Agent Execution & Progress Tracking
|
||||
|
||||
```bash
|
||||
Task(subagent_type="code-developer",
|
||||
prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema
|
||||
|
||||
Task Context: impl-1.2 - Implement auth logic
|
||||
prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Analyze auth patterns and implement JWT authentication system
|
||||
|
||||
Task Context: impl-1.2 - Saturated task with merged preparation and execution
|
||||
|
||||
PREPARATION PHASE (preparation_complexity: simple, estimated_prep_time: 20min):
|
||||
1. Review existing auth patterns in the codebase
|
||||
2. Check JWT library compatibility with current stack
|
||||
3. Analyze current session management approach
|
||||
|
||||
EXECUTION PHASE:
|
||||
Based on preparation findings, implement JWT authentication system
|
||||
|
||||
Session Context:
|
||||
- Workflow Directory: .workflow/WFS-user-auth/
|
||||
- TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
|
||||
- Summaries Directory: .workflow/WFS-user-auth/.summaries/
|
||||
- Task JSON Location: .workflow/WFS-user-auth/.task/impl-1.2.json
|
||||
|
||||
|
||||
Implementation Details:
|
||||
- Target File: src/auth/models/User.ts
|
||||
- Function: UserSchema (lines 10-50)
|
||||
@@ -167,13 +178,15 @@ Task(subagent_type="code-developer",
|
||||
- Dependencies: mongoose, jsonwebtoken
|
||||
- Risks: Schema changes require database migration, Existing user data compatibility
|
||||
- Performance: Index JWT fields for faster lookups
|
||||
|
||||
Focus Paths (from task JSON): $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
|
||||
Gemini Command: gemini -p "$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
|
||||
|
||||
IMPORTANT: Update TODO_LIST.md and create summary in provided directories upon completion.
|
||||
Use implementation details above for precise, targeted development.",
|
||||
description="Execute impl-1.2 with full workflow context and implementation details")
|
||||
|
||||
Focus Paths (from task JSON): $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
|
||||
Gemini Command: ~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
|
||||
|
||||
IMPORTANT:
|
||||
1. Document both preparation analysis results and implementation in summary
|
||||
2. Update TODO_LIST.md and create summary in provided directories upon completion
|
||||
3. Use preparation findings to inform implementation decisions",
|
||||
description="Execute saturated task with preparation and implementation phases")
|
||||
```
|
||||
|
||||
**Execution Protocol:**
|
||||
@@ -226,28 +239,42 @@ Based on discovered task data:
|
||||
|
||||
### Discovery-Based Assignment
|
||||
```bash
|
||||
# Agent receives complete discovered context
|
||||
# Agent receives complete discovered context with saturation handling
|
||||
Task(subagent_type="code-developer",
|
||||
prompt="[GEMINI_CLI_REQUIRED] Execute impl-1.2: Implement auth logic
|
||||
|
||||
prompt="[PREPARATION_INCLUDED] [GEMINI_CLI_REQUIRED] Execute impl-1.2: Analyze and implement auth logic
|
||||
|
||||
TASK TYPE: Saturated task (preparation_complexity: simple)
|
||||
|
||||
PREPARATION PHASE:
|
||||
- Review existing auth patterns and conventions
|
||||
- Check JWT library compatibility
|
||||
- Analyze current session management
|
||||
|
||||
EXECUTION PHASE:
|
||||
Implement JWT authentication based on preparation findings
|
||||
|
||||
Context from discovery:
|
||||
- Requirements: JWT authentication, OAuth2 support
|
||||
- Scope: src/auth/*, tests/auth/*
|
||||
- Dependencies: impl-1.1 (completed)
|
||||
- Workflow: WFS-user-auth authentication system
|
||||
|
||||
|
||||
Session Context:
|
||||
- Workflow Directory: .workflow/WFS-user-auth/
|
||||
- TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
|
||||
- Summaries Directory: .workflow/WFS-user-auth/.summaries/
|
||||
- Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json
|
||||
|
||||
Focus Paths: $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
|
||||
Analysis Command: Use gemini -p \"$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
|
||||
|
||||
CRITICAL: Use task-specific paths for focused analysis. Update TODO_LIST.md and create completion summary using provided paths.",
|
||||
|
||||
description="Agent executes with task-specific paths and full discovered context")
|
||||
|
||||
Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
|
||||
Analysis Command: Use ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
|
||||
|
||||
CRITICAL:
|
||||
1. Execute preparation phase first, then use findings for implementation
|
||||
2. Use task-specific paths for focused analysis
|
||||
3. Document both phases in completion summary
|
||||
4. Update TODO_LIST.md and create completion summary using provided paths.",
|
||||
|
||||
description="Agent executes saturated task with preparation and implementation phases")
|
||||
```
|
||||
|
||||
### Status Tracking Integration
|
||||
@@ -341,13 +368,3 @@ mark_dependent_tasks_ready(task_dependencies)
|
||||
/workflow:review # Move to review phase when complete
|
||||
```
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/context` - View discovered tasks and current status
|
||||
- `/task:execute` - Execute individual tasks (user-controlled)
|
||||
- `/workflow:session:status` - Check session progress and dependencies
|
||||
- `/workflow:review` - Move to review phase after completion
|
||||
|
||||
---
|
||||
|
||||
**System ensures**: Intelligent task discovery with context-rich agent coordination and automatic progress tracking
|
||||
@@ -7,7 +7,6 @@ examples:
|
||||
- /workflow:plan "Build authentication system"
|
||||
- /workflow:plan requirements.md
|
||||
- /workflow:plan ISS-001
|
||||
- /workflow:plan web-api
|
||||
---
|
||||
|
||||
# Workflow Plan Command (/workflow:plan)
|
||||
@@ -32,7 +31,6 @@ Optional flag to specify which CLI tool to use for context analysis:
|
||||
```bash
|
||||
/workflow:plan --AM codex "Build authentication system"
|
||||
/workflow:plan --AM gemini requirements.md
|
||||
/workflow:plan ISS-001 # Uses default (gemini)
|
||||
```
|
||||
|
||||
## Input Detection Logic
|
||||
@@ -41,9 +39,7 @@ The command automatically detects input type:
|
||||
### File Input (Auto-detected)
|
||||
```bash
|
||||
/workflow:plan requirements.md
|
||||
/workflow:plan PROJECT_SPEC.txt
|
||||
/workflow:plan config.json
|
||||
/workflow:plan spec.yaml
|
||||
```
|
||||
**Triggers**: Extensions: .md, .txt, .json, .yaml, .yml
|
||||
**Processing**: Reads file contents and extracts requirements
|
||||
@@ -52,25 +48,14 @@ The command automatically detects input type:
|
||||
```bash
|
||||
/workflow:plan ISS-001
|
||||
/workflow:plan ISSUE-123
|
||||
/workflow:plan feature-request-45
|
||||
```
|
||||
**Triggers**: Patterns: ISS-*, ISSUE-*, *-request-*
|
||||
**Processing**: Loads issue data and acceptance criteria
|
||||
|
||||
### Template Input (Auto-detected)
|
||||
```bash
|
||||
/workflow:plan web-api
|
||||
/workflow:plan mobile-app
|
||||
/workflow:plan database-migration
|
||||
/workflow:plan security-feature
|
||||
```
|
||||
**Triggers**: Known template names
|
||||
**Processing**: Loads template and prompts for customization
|
||||
|
||||
### Text Input (Default)
|
||||
```bash
|
||||
/workflow:plan "Build user authentication with JWT and OAuth2"
|
||||
/workflow:plan "Fix performance issues in dashboard"
|
||||
```
|
||||
**Triggers**: Everything else
|
||||
**Processing**: Parse natural language requirements
|
||||
@@ -82,87 +67,55 @@ The command automatically detects input type:
|
||||
- Uses active session if available
|
||||
- Generates session ID: WFS-[topic-slug]
|
||||
|
||||
### Complexity Detection
|
||||
- **Simple**: <5 tasks → Direct IMPL_PLAN.md
|
||||
- **Medium**: 5-15 tasks → IMPL_PLAN.md + TODO_LIST.md
|
||||
- **Complex**: >15 tasks → Full decomposition
|
||||
### Complexity Detection with Saturation
|
||||
- **Simple**: <3 saturated tasks → Direct IMPL_PLAN.md
|
||||
- **Medium**: 3-8 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
|
||||
- **Complex**: >8 saturated tasks → Full decomposition
|
||||
|
||||
### Task Generation
|
||||
**Note**: 1 complex preparation task = 0.5 saturated task for counting
|
||||
|
||||
### Task Generation with Saturation Control
|
||||
- **Task Saturation Assessment**: Evaluates whether to merge preparation and execution
|
||||
- **Default merge mode**: "Analyze and implement X" instead of "Analyze X" + "Implement X"
|
||||
- **Smart splitting**: Only separate when preparation complexity > threshold
|
||||
- Automatically creates .task/ files when complexity warrants
|
||||
- Generates hierarchical task structure (max 3 levels)
|
||||
- Generates hierarchical task structure (max 2 levels)
|
||||
- Main tasks with subtasks become container tasks (not directly executable)
|
||||
- Updates session state with task references
|
||||
- Runs project structure analysis to populate paths field
|
||||
|
||||
### Implementation Field Requirements
|
||||
⚠️ **CRITICAL**: All generated tasks must include detailed implementation guidance
|
||||
### Task Saturation Assessment
|
||||
Evaluates whether to merge preparation and execution:
|
||||
|
||||
**analysis_source Assignment Rules**:
|
||||
- **"manual"**: User provides complete implementation details (including specific files and code snippets)
|
||||
- **"gemini"**: Insufficient information, requires Gemini analysis (missing file paths or code context)
|
||||
- **"codex"**: Insufficient information, requires Codex autonomous development analysis (complex refactoring or intelligent file discovery)
|
||||
- **"auto-detected"**: System automatically infers implementation details (based on pattern recognition)
|
||||
**Merge Conditions** (Saturated Tasks):
|
||||
- Preparation work < 30min estimated
|
||||
- Analysis scope ≤ 3 files
|
||||
- No complex dependencies
|
||||
- Single module operation
|
||||
|
||||
**Decision Flow**:
|
||||
1. **IF** user provides file paths + code snippets → "manual"
|
||||
2. **ELIF** system can infer implementation location → "auto-detected"
|
||||
3. **ELIF** --AM codex specified → "codex" (requires autonomous development analysis)
|
||||
4. **ELSE** → "gemini" (requires deep analysis, default method)
|
||||
**Separate Preparation Conditions**:
|
||||
- Cross-module architecture analysis (>5 modules)
|
||||
- Deep performance analysis or security audit required
|
||||
- Database migration design needed
|
||||
- Third-party API integration research
|
||||
|
||||
**Auto-fill Strategy**:
|
||||
1. **Sufficient Information**: Auto-fill implementation field based on user input and project context
|
||||
2. **Insufficient Information**: Mark analysis_source appropriately and prompt:
|
||||
|
||||
**For Gemini Analysis (default)**:
|
||||
```
|
||||
⚠️ Implementation details incomplete, recommend using gemini analysis:
|
||||
gemini --all-files -p "@{relevant-file-patterns} @{CLAUDE.md}
|
||||
Analyze task: [task description]
|
||||
Extract: 1) File locations and code snippets 2) Modification logic and data flow 3) Risks and dependencies"
|
||||
```
|
||||
|
||||
**For Codex Analysis (when --AM codex specified)**:
|
||||
```
|
||||
⚠️ Implementation details incomplete, recommend using codex analysis:
|
||||
codex --full-auto exec "Analyze and implement: [task description]
|
||||
Context: Autonomous analysis and implementation guidance needed
|
||||
Extract: 1) Intelligent file discovery 2) Implementation strategy 3) Autonomous development approach"
|
||||
```
|
||||
**Task Examples**:
|
||||
- **Saturated**: "IMPL-001: Analyze auth patterns and implement JWT token management"
|
||||
- **Split needed**: "IMPL-001: Design cross-service auth architecture" + "IMPL-002: Implement auth service"
|
||||
|
||||
**Required Implementation Sub-fields**:
|
||||
- **files**: Must contain at least 1 file with detailed info (path, location, original_code, modifications)
|
||||
- **context_notes**: Dependencies, risks, performance considerations
|
||||
- **analysis_source**: manual|gemini|codex|auto-detected
|
||||
### Task Breakdown Process
|
||||
- **Automatic decomposition**: Tasks with complexity >5 are broken into subtasks (impl-N.M format)
|
||||
- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
|
||||
- **Smart decomposition**: AI analyzes task title to suggest logical subtask structure
|
||||
- **Context inheritance**: Subtasks inherit parent's requirements and scope, refined for specific needs
|
||||
- **Agent assignment**: Automatic agent mapping based on subtask type (planning/code/test/review)
|
||||
- **Maximum depth**: 2 levels (impl-N.M) to maintain manageable hierarchy
|
||||
|
||||
**Paths Field Population Process**:
|
||||
1. **Project Structure Analysis**: Run `get_modules_by_depth.sh` to discover project structure
|
||||
2. **Relevance Filtering**: Match discovered modules to task requirements
|
||||
3. **Path Selection**: Choose concrete directories/files (avoid wildcards)
|
||||
4. **Format**: Semicolon-separated list (e.g., `"src/auth;tests/auth;config/auth.json"`)
|
||||
|
||||
**Path Selection Strategy**:
|
||||
```pseudo
|
||||
# Step 1: Analyze project structure
|
||||
modules = Bash(.claude/scripts/get_modules_by_depth.sh list)
|
||||
|
||||
# Step 2: Extract relevant modules based on task scope
|
||||
relevant_paths = []
|
||||
for module in modules:
|
||||
if matches_task_scope(module.path, task_requirements):
|
||||
relevant_paths.append(module.path)
|
||||
|
||||
# Step 3: Add specific files mentioned in requirements
|
||||
specific_files = extract_file_mentions(task_requirements)
|
||||
relevant_paths.extend(specific_files)
|
||||
|
||||
# Step 4: Format as semicolon-separated string
|
||||
task.paths = join(relevant_paths, ";")
|
||||
```
|
||||
|
||||
**Quality Standards**:
|
||||
- logic_flow must use specified symbols (───►, ◊───, ◄───)
|
||||
- Each file must have specific location (function name or line range)
|
||||
- risks array cannot be empty, must contain at least 1 risk assessment
|
||||
### Implementation Field Requirements
|
||||
- **analysis_source**: Determines context gathering method (manual|auto-detected|gemini|codex)
|
||||
- **Auto-assignment**: manual (user provides details) → auto-detected (system infers) → gemini/codex (needs analysis)
|
||||
- **Required fields**: files (with path/location/modifications), context_notes, analysis_source
|
||||
- **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")
|
||||
|
||||
## Session Check Process
|
||||
⚠️ **CRITICAL**: Check for existing active session before planning
|
||||
@@ -173,6 +126,21 @@ task.paths = join(relevant_paths, ";")
|
||||
|
||||
## Output Documents
|
||||
|
||||
### Document References for Execution
|
||||
|
||||
#### Primary References
|
||||
- **Planning Document**: `.workflow/WFS-[topic-slug]/IMPL_PLAN.md`
|
||||
- Used by: `/workflow:execute` for context loading
|
||||
- Contains: Requirements, task overview, success criteria
|
||||
|
||||
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/impl-*.json`
|
||||
- Used by: Agents for implementation context
|
||||
- Contains: Complete task details with implementation field including preparation_complexity
|
||||
|
||||
- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
|
||||
- Used by: `/workflow:execute` for status tracking
|
||||
- Updated by: Agents after task completion
|
||||
|
||||
### IMPL_PLAN.md (Always Created)
|
||||
```markdown
|
||||
# Implementation Plan - [Project Name]
|
||||
@@ -182,7 +150,7 @@ task.paths = join(relevant_paths, ";")
|
||||
[Extracted requirements from input source]
|
||||
|
||||
## Task Breakdown
|
||||
- **IMPL-001**: [Task description]
|
||||
- **IMPL-001**: [Saturated task description with merged preparation and execution]
|
||||
- **IMPL-002**: [Task description]
|
||||
|
||||
## Success Criteria
|
||||
@@ -208,22 +176,8 @@ Generated in .task/ directory when decomposition enabled
|
||||
- **Invalid issue**: Verify issue ID exists
|
||||
- **Unknown template**: List available templates
|
||||
- **Empty input**: Prompt for valid input
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Related Commands
|
||||
- `/workflow:session:start` - Create new session first
|
||||
- `/context` - View generated plan
|
||||
- `/task/execute` - Execute decomposed tasks
|
||||
- `/workflow:execute` - Run implementation phase
|
||||
|
||||
### Template System
|
||||
Available templates:
|
||||
- `web-api`: REST API development
|
||||
- `mobile-app`: Mobile application
|
||||
- `database-migration`: Database changes
|
||||
- `security-feature`: Security implementation
|
||||
|
||||
---
|
||||
- **Vague text input**: Auto-reject without guidance
|
||||
- Rejected examples: "do something", "fix it", "make it better", "add feature"
|
||||
- Response: Direct rejection message, no further assistance
|
||||
|
||||
**System ensures**: Unified planning interface with intelligent input detection and automatic complexity handling
|
||||
@@ -107,6 +107,13 @@ All task files use this 10-field schema:
|
||||
},
|
||||
|
||||
"implementation": {
|
||||
"preparation_complexity": "simple|moderate|complex",
|
||||
"preparation_tasks": [
|
||||
"Review existing auth patterns",
|
||||
"Check JWT library compatibility",
|
||||
"Analyze current session management"
|
||||
],
|
||||
"estimated_prep_time": "20min",
|
||||
"files": [
|
||||
{
|
||||
"path": "src/auth/login.ts",
|
||||
@@ -120,7 +127,7 @@ All task files use this 10-field schema:
|
||||
"current_state": "Currently using simple password validation",
|
||||
"proposed_changes": [
|
||||
"Add JWT token generation logic",
|
||||
"Integrate OAuth2 authentication flow",
|
||||
"Integrate OAuth2 authentication flow",
|
||||
"Enhance error handling mechanisms"
|
||||
],
|
||||
"logic_flow": [
|
||||
@@ -193,6 +200,20 @@ The **implementation** field provides detailed code implementation guidance with
|
||||
- **reason**: Modification rationale and objectives
|
||||
- **expected_outcome**: Expected results
|
||||
|
||||
#### preparation_complexity - Task Saturation Assessment
|
||||
- **simple**: Preparation work < 30min, ≤ 3 files, single module → Merge with execution
|
||||
- **moderate**: Cross-module analysis needed, 30min-2h prep → Consider separation
|
||||
- **complex**: Architecture design, >2h prep, >5 modules → Separate preparation task
|
||||
|
||||
#### preparation_tasks - Preparation Work List
|
||||
- Array of specific preparation activities to be performed
|
||||
- Used to estimate complexity and decide merge/split strategy
|
||||
- Examples: ["Review patterns", "Check dependencies", "Analyze performance"]
|
||||
|
||||
#### estimated_prep_time - Time Estimation
|
||||
- String format time estimate (e.g., "20min", "2h", "half-day")
|
||||
- Helps determine if preparation should be merged with execution
|
||||
|
||||
#### context_notes - Implementation Context Information
|
||||
- **dependencies**: Required dependency packages or modules
|
||||
- **affected_modules**: Other modules that will be affected
|
||||
|
||||
Reference in New Issue
Block a user