mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
refactor: Enforce 10-task limit and file cohesion across workflow system
- Update workflow-architecture.md: Streamline structure, enforce 10-task hard limit - Update workflow plan.md: Add file cohesion rules, similar functionality warnings - Update task breakdown.md: Manual breakdown controls, conflict detection - Update task-core.md: Sync JSON schema with workflow-architecture.md - Establish consistent 10-task maximum across all workflow commands - Add file cohesion enforcement to prevent splitting related files - Replace "Complex" classification with "Over-scope" requiring re-planning 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -23,20 +23,22 @@ The intelligent execution approach focuses on:
|
||||
- **Dynamic task orchestration** - Coordinate based on discovered task relationships
|
||||
- **Progress tracking** - Update task status after agent completion
|
||||
|
||||
**Analysis Marker**:
|
||||
- **[MULTI_STEP_ANALYSIS]**: Indicates sequential pre-execution analysis required
|
||||
- **Auto-trigger**: When task.pre_analysis is an array (default format)
|
||||
- **Agent Action**: Execute comprehensive pre-analysis BEFORE implementation begins
|
||||
- Process each step sequentially with specified templates and methods
|
||||
- Expand brief actions into full analysis tasks
|
||||
- Gather context, understand patterns, identify requirements
|
||||
- Use method specified in each step (gemini/codex/manual/auto-detected)
|
||||
**Flow Control Execution**:
|
||||
- **[FLOW_CONTROL]**: Indicates sequential flow control execution required
|
||||
- **Auto-trigger**: When task.flow_control.pre_analysis is an array (default format)
|
||||
- **Agent Action**: Execute flow control steps sequentially BEFORE implementation begins
|
||||
- Process each step with command execution and context accumulation
|
||||
- Load dependency summaries and parent task context
|
||||
- Execute CLI tools, scripts, and agent commands as specified
|
||||
- Pass context between steps via named variables
|
||||
- Handle errors according to per-step error strategies
|
||||
|
||||
**pre_analysis to Marker Mapping**:
|
||||
- **Array format (multi-step pre-analysis)**:
|
||||
- Add [MULTI_STEP_ANALYSIS] - triggers comprehensive pre-execution analysis
|
||||
- Agent processes each step with specified method (gemini/codex/manual/auto-detected)
|
||||
- Agent expands each action into comprehensive analysis based on template
|
||||
**Flow Control Step Processing**:
|
||||
- **Sequential Execution**: Steps processed in order with context flow
|
||||
- Each step can use outputs from previous steps via ${variable_name}
|
||||
- Dependency summaries loaded automatically from .summaries/
|
||||
- Context accumulates through the execution chain
|
||||
- Error handling per step (skip_optional, fail, retry_once, manual_intervention)
|
||||
|
||||
## Execution Flow
|
||||
|
||||
@@ -53,7 +55,7 @@ Workflow Discovery:
|
||||
|
||||
**Discovery Logic:**
|
||||
- **Folder Detection**: Use provided folder or find current active session
|
||||
- **Task Inventory**: Load all impl-*.json files from .task/ directory
|
||||
- **Task Inventory**: Load all IMPL-*.json files from .task/ directory
|
||||
- **Status Analysis**: Check pending/active/completed/blocked states
|
||||
- **Dependency Check**: Verify all task dependencies are met
|
||||
- **Execution Queue**: Build list of ready-to-execute tasks
|
||||
@@ -66,14 +68,13 @@ Workflow Discovery:
|
||||
*Session: WFS-[topic-slug]*
|
||||
|
||||
## Execution Plan
|
||||
- [ ] **TASK-001**: [Agent: planning-agent] [MULTI_STEP_ANALYSIS] Design auth schema (impl-1.1)
|
||||
- [ ] **TASK-002**: [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement auth logic (impl-1.2)
|
||||
- [ ] **TASK-001**: [Agent: planning-agent] [FLOW_CONTROL] Design auth schema (IMPL-1.1)
|
||||
- [ ] **TASK-002**: [Agent: code-developer] [FLOW_CONTROL] Implement auth logic (IMPL-1.2)
|
||||
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
|
||||
- [ ] **TASK-004**: Update task statuses and session state
|
||||
|
||||
**Marker Legend**:
|
||||
- [MULTI_STEP_ANALYSIS] = Agent must execute multi-step pre-execution analysis
|
||||
- [PREPARATION_INCLUDED] = Task includes preparation phase (analyze then implement)
|
||||
- [FLOW_CONTROL] = Agent must execute flow control steps with context accumulation
|
||||
```
|
||||
|
||||
### 3. Agent Context Assignment
|
||||
@@ -82,126 +83,119 @@ For each executable task:
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": "impl-1.1",
|
||||
"id": "IMPL-1.1",
|
||||
"title": "Design auth schema",
|
||||
"status": "pending",
|
||||
|
||||
"meta": {
|
||||
"type": "feature",
|
||||
"agent": "code-developer"
|
||||
},
|
||||
|
||||
"context": {
|
||||
"requirements": ["JWT authentication", "User model design"],
|
||||
"scope": ["src/auth/models/*"],
|
||||
"acceptance": ["Schema validates JWT tokens"]
|
||||
},
|
||||
"implementation": {
|
||||
"files": [
|
||||
{
|
||||
"path": "src/auth/models/User.ts",
|
||||
"location": {
|
||||
"function": "UserSchema",
|
||||
"lines": "10-50",
|
||||
"description": "User model definition"
|
||||
},
|
||||
"original_code": "// Requires gemini analysis for current schema",
|
||||
"modifications": {
|
||||
"current_state": "Basic user model without auth fields",
|
||||
"proposed_changes": [
|
||||
"Add JWT token fields to schema",
|
||||
"Include OAuth provider fields"
|
||||
],
|
||||
"logic_flow": [
|
||||
"createUser() ───► validateSchema() ───► generateJWT()",
|
||||
"◊─── if OAuth ───► linkProvider() ───► storeTokens()"
|
||||
],
|
||||
"reason": "Support modern authentication patterns",
|
||||
"expected_outcome": "Flexible user schema supporting multiple auth methods"
|
||||
}
|
||||
}
|
||||
],
|
||||
"context_notes": {
|
||||
"dependencies": ["mongoose", "jsonwebtoken"],
|
||||
"affected_modules": ["auth-middleware", "user-service"],
|
||||
"risks": [
|
||||
"Schema changes require database migration",
|
||||
"Existing user data compatibility"
|
||||
],
|
||||
"performance_considerations": "Index JWT fields for faster lookups",
|
||||
"error_handling": "Graceful schema validation errors"
|
||||
"focus_paths": ["src/auth/models", "tests/auth"],
|
||||
"acceptance": ["Schema validates JWT tokens"],
|
||||
"parent": "IMPL-1",
|
||||
"depends_on": [],
|
||||
"inherited": {
|
||||
"from": "IMPL-1",
|
||||
"context": ["Authentication system architecture completed"]
|
||||
},
|
||||
"shared_context": {
|
||||
"auth_strategy": "JWT with refresh tokens"
|
||||
}
|
||||
},
|
||||
|
||||
"flow_control": {
|
||||
"pre_analysis": [
|
||||
{
|
||||
"action": "analyze auth",
|
||||
"template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
|
||||
"method": "gemini"
|
||||
"step": "gather_context",
|
||||
"action": "Load dependency summaries",
|
||||
"command": "bash(echo 'No dependencies for this initial task')",
|
||||
"output_to": "dependency_context",
|
||||
"on_error": "skip_optional"
|
||||
},
|
||||
{
|
||||
"action": "security review",
|
||||
"template": "~/.claude/workflows/cli-templates/prompts/analysis/security.txt",
|
||||
"method": "gemini"
|
||||
"step": "analyze_patterns",
|
||||
"action": "Analyze existing auth patterns",
|
||||
"command": "bash(~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]')",
|
||||
"output_to": "pattern_analysis",
|
||||
"on_error": "fail"
|
||||
},
|
||||
{
|
||||
"action": "implement feature",
|
||||
"template": "~/.claude/workflows/cli-templates/prompts/development/feature.txt",
|
||||
"method": "codex"
|
||||
"step": "implement",
|
||||
"action": "Design JWT schema based on analysis",
|
||||
"command": "bash(codex --full-auto exec 'Design JWT schema using analysis: [pattern_analysis] and context: [dependency_context]')",
|
||||
"on_error": "manual_intervention"
|
||||
}
|
||||
],
|
||||
"implementation_approach": "Design flexible user schema supporting JWT and OAuth authentication",
|
||||
"target_files": [
|
||||
"src/auth/models/User.ts:UserSchema:10-50"
|
||||
]
|
||||
}
|
||||
},
|
||||
"workflow": {
|
||||
"session": "WFS-user-auth",
|
||||
"session": "WFS-user-auth",
|
||||
"phase": "IMPLEMENT",
|
||||
"plan_context": "Authentication system with OAuth2 support"
|
||||
},
|
||||
"focus_modules": ["src/auth/", "tests/auth/"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Context Assignment Rules:**
|
||||
- **Complete Context**: Use full task JSON context including implementation field for agent execution
|
||||
- **Implementation Details**: Pass complete implementation.files array to agents for precise execution
|
||||
- **Code Context**: Include original_code snippets and logic_flow diagrams in agent prompts
|
||||
- **Risk Awareness**: Alert agents to implementation.context_notes.risks before execution
|
||||
- **Complete Context**: Use full task JSON context including flow_control field for agent execution
|
||||
- **Flow Control Processing**: Execute flow_control.pre_analysis steps sequentially with context accumulation
|
||||
- **Dependency Integration**: Load summaries from context.depends_on automatically
|
||||
- **Mandatory Dependency Reading**: For tasks with dependencies, MUST read previous task summary documents
|
||||
- **Context Inheritance**: Use dependency summaries to maintain consistency and include context.inherited data from parent tasks
|
||||
- **Workflow Integration**: Include session state and IMPL_PLAN.md context
|
||||
- **Scope Focus**: Direct agents to specific files from implementation.files[].path
|
||||
- **Analysis Marker**: Auto-add [MULTI_STEP_ANALYSIS] when pre_analysis is array format
|
||||
- **Merged Task Handling**: Add [PREPARATION_INCLUDED] marker when preparation_complexity exists
|
||||
- **Focus Scope**: Direct agents to specific paths from context.focus_paths array
|
||||
- **Flow Control Marker**: Auto-add [FLOW_CONTROL] when flow_control.pre_analysis exists
|
||||
- **Target File Guidance**: Use flow_control.target_files for precise file targeting
|
||||
|
||||
### 4. Agent Execution & Progress Tracking
|
||||
|
||||
```bash
|
||||
Task(subagent_type="code-developer",
|
||||
prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Analyze auth patterns and implement JWT authentication system
|
||||
prompt="[FLOW_CONTROL] Execute IMPL-1.2: Implement JWT authentication system with flow control
|
||||
|
||||
Task Context: impl-1.2 - Saturated task with merged preparation and execution
|
||||
Task Context: IMPL-1.2 - Flow control managed 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
|
||||
FLOW CONTROL EXECUTION:
|
||||
Execute the following steps sequentially with context accumulation:
|
||||
|
||||
EXECUTION PHASE:
|
||||
Based on preparation findings, implement JWT authentication system
|
||||
Step 1 (gather_context): Load dependency summaries
|
||||
Command: for dep in ${depends_on}; do cat .summaries/$dep-summary.md 2>/dev/null || echo "No summary for $dep"; done
|
||||
Output: dependency_context
|
||||
|
||||
Step 2 (analyze_patterns): Analyze existing auth patterns
|
||||
Command: ~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze authentication patterns with context: [dependency_context]'
|
||||
Output: pattern_analysis
|
||||
|
||||
Step 3 (implement): Implement JWT based on analysis
|
||||
Command: codex --full-auto exec 'Implement JWT using analysis: [pattern_analysis] and context: [dependency_context]'
|
||||
|
||||
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
|
||||
- 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)
|
||||
- Current State: Basic user model without auth fields
|
||||
- Required Changes: Add JWT token fields, Include OAuth provider fields
|
||||
- Logic Flow: createUser() ───► validateSchema() ───► generateJWT()
|
||||
- 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: ~/.claude/scripts/gemini-wrapper -p "$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
|
||||
Implementation Guidance:
|
||||
- Approach: Design flexible user schema supporting JWT and OAuth authentication
|
||||
- Target Files: src/auth/models/User.ts:UserSchema:10-50
|
||||
- Focus Paths: src/auth/models, tests/auth
|
||||
- Dependencies: From context.depends_on
|
||||
- Inherited Context: [context.inherited]
|
||||
|
||||
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")
|
||||
1. Execute flow control steps in sequence with error handling
|
||||
2. Accumulate context through step chain
|
||||
3. Create comprehensive summary with 'Outputs for Dependent Tasks' section
|
||||
4. Update TODO_LIST.md upon completion",
|
||||
description="Execute task with flow control step processing")
|
||||
```
|
||||
|
||||
**Execution Protocol:**
|
||||
@@ -218,9 +212,9 @@ Task(subagent_type="code-developer",
|
||||
├── workflow-session.json # Session state and stats
|
||||
├── IMPL_PLAN.md # Workflow context and requirements
|
||||
├── .task/ # Task definitions
|
||||
│ ├── impl-1.json # Main tasks
|
||||
│ ├── impl-1.1.json # Subtasks
|
||||
│ └── impl-1.2.json # Detailed tasks
|
||||
│ ├── IMPL-1.json # Main tasks
|
||||
│ ├── IMPL-1.1.json # Subtasks
|
||||
│ └── IMPL-1.2.json # Detailed tasks
|
||||
└── .summaries/ # Completed task summaries
|
||||
```
|
||||
|
||||
@@ -256,7 +250,7 @@ Based on discovered task data:
|
||||
```bash
|
||||
# Agent receives complete discovered context with saturation handling
|
||||
Task(subagent_type="code-developer",
|
||||
prompt="[PREPARATION_INCLUDED] [MULTI_STEP_ANALYSIS] Execute impl-1.2: Analyze and implement auth logic
|
||||
prompt="[FLOW_CONTROL] Execute IMPL-1.2: Analyze and implement auth logic
|
||||
|
||||
TASK TYPE: Saturated task (preparation_complexity: simple)
|
||||
|
||||
@@ -271,17 +265,17 @@ Task(subagent_type="code-developer",
|
||||
Context from discovery:
|
||||
- Requirements: JWT authentication, OAuth2 support
|
||||
- Scope: src/auth/*, tests/auth/*
|
||||
- Dependencies: impl-1.1 (completed)
|
||||
- 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
|
||||
- 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 ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
|
||||
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
|
||||
@@ -295,7 +289,7 @@ Task(subagent_type="code-developer",
|
||||
### Status Tracking Integration
|
||||
```bash
|
||||
# After agent completion, update discovered task status
|
||||
update_task_status("impl-1.2", "completed")
|
||||
update_task_status("IMPL-1.2", "completed")
|
||||
mark_dependent_tasks_ready(task_dependencies)
|
||||
```
|
||||
|
||||
@@ -318,7 +312,7 @@ mark_dependent_tasks_ready(task_dependencies)
|
||||
```json
|
||||
// Before execution
|
||||
{
|
||||
"id": "impl-1.2",
|
||||
"id": "IMPL-1.2",
|
||||
"status": "pending",
|
||||
"execution": {
|
||||
"attempts": 0,
|
||||
@@ -328,7 +322,7 @@ mark_dependent_tasks_ready(task_dependencies)
|
||||
|
||||
// After execution
|
||||
{
|
||||
"id": "impl-1.2",
|
||||
"id": "IMPL-1.2",
|
||||
"status": "completed",
|
||||
"execution": {
|
||||
"attempts": 1,
|
||||
@@ -358,7 +352,7 @@ mark_dependent_tasks_ready(task_dependencies)
|
||||
→ Check: /context for task status overview
|
||||
|
||||
# Missing task files
|
||||
❌ Task impl-1.2 referenced but JSON file missing
|
||||
❌ Task IMPL-1.2 referenced but JSON file missing
|
||||
→ Fix: /task/create or repair task references
|
||||
```
|
||||
|
||||
@@ -379,7 +373,7 @@ mark_dependent_tasks_ready(task_dependencies)
|
||||
```bash
|
||||
# After /workflow:execute completion
|
||||
/context # View updated task status
|
||||
/task:execute impl-X # Execute specific remaining tasks
|
||||
/task:execute IMPL-X # Execute specific remaining tasks
|
||||
/workflow:review # Move to review phase when complete
|
||||
```
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ Simple keyword-based filtering:
|
||||
🔗 ISS-004: Implement rate limiting
|
||||
Type: Feature | Priority: Medium
|
||||
Status: Integrated → IMPL-003
|
||||
Integrated: 2025-09-06 | Task: impl-3.json
|
||||
Integrated: 2025-09-06 | Task: IMPL-3.json
|
||||
```
|
||||
|
||||
## Summary Stats
|
||||
|
||||
@@ -90,9 +90,9 @@ Task(action-planning-agent):
|
||||
- Execute comprehensive Gemini CLI analysis (4 dimensions)
|
||||
- Skip PRD processing (no PRD provided)
|
||||
- Skip session inheritance (standalone planning)
|
||||
- Force MULTI_STEP_ANALYSIS flag = true
|
||||
- Force FLOW_CONTROL flag = true
|
||||
- Set pre_analysis = multi-step array format with comprehensive analysis steps
|
||||
- Generate hierarchical task decomposition (max 2 levels: impl-N.M)
|
||||
- Generate hierarchical task decomposition (max 2 levels: IMPL-N.M)
|
||||
- Create detailed IMPL_PLAN.md with subtasks
|
||||
- Generate TODO_LIST.md for tracking
|
||||
|
||||
@@ -126,7 +126,7 @@ def process_plan_deep_command(input):
|
||||
TASK: {task_description}
|
||||
|
||||
MANDATORY FLAGS:
|
||||
- MULTI_STEP_ANALYSIS = true
|
||||
- FLOW_CONTROL = true
|
||||
- pre_analysis = multi-step array format for comprehensive pre-analysis
|
||||
- FORCE_PARALLEL_ANALYSIS = true
|
||||
- SKIP_PRD = true
|
||||
|
||||
@@ -17,6 +17,10 @@ Creates actionable implementation plans with intelligent input source detection.
|
||||
## Core Principles
|
||||
**File Structure:** @~/.claude/workflows/workflow-architecture.md
|
||||
|
||||
**Dependency Context Rules:**
|
||||
- **For tasks with dependencies**: MUST read previous task summary documents before planning
|
||||
- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:plan [--AM gemini|codex] <input>
|
||||
@@ -74,36 +78,42 @@ The command automatically detects input type:
|
||||
1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
|
||||
2. **Decomposition Strategy**: Based on complexity, decide:
|
||||
- Task structure (flat vs hierarchical)
|
||||
- Subtask necessity (>15 tasks triggers decomposition)
|
||||
- Re-scoping necessity (>10 tasks triggers re-scoping)
|
||||
- Task saturation level (merged vs separated)
|
||||
- File grouping strategy (cohesive files together)
|
||||
3. **Quantity Prediction**: Calculate expected:
|
||||
- Total main tasks (IMPL-XXX)
|
||||
- Subtasks per main task (impl-N.M)
|
||||
- Subtasks per main task (IMPL-N.M)
|
||||
- Container vs leaf task ratio
|
||||
|
||||
**Pre-Planning Outputs**:
|
||||
- Complexity level: Simple (≤8) | Medium (9-15) | Complex (>15)
|
||||
- Decomposition approach: Flat | Two-level hierarchy
|
||||
- Estimated task count: [number] main tasks, [number] total leaf tasks
|
||||
- Complexity level: Simple (≤5) | Medium (6-10) | Over-scoped (>10, requires re-scoping)
|
||||
- Decomposition approach: Flat | Two-level hierarchy | Re-scope required
|
||||
- Estimated task count: [number] main tasks, [number] total leaf tasks (max 10)
|
||||
- Document set: Which documents will be generated (IMPL_PLAN.md, TODO_LIST.md, .task/*.json)
|
||||
- **Re-scoping recommendation**: If >10 tasks, provide guidance for breaking into iterations
|
||||
|
||||
**Only after completing pre-planning analysis**: Proceed to generate actual plan documents
|
||||
|
||||
### Complexity Detection with Saturation
|
||||
*Based on Pre-Planning Analysis results:*
|
||||
- **Simple**: ≤8 saturated tasks → Direct IMPL_PLAN.md
|
||||
- **Medium**: 9-15 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
|
||||
- **Complex**: >15 saturated tasks → Full decomposition
|
||||
- **Simple**: ≤5 saturated tasks → Direct IMPL_PLAN.md
|
||||
- **Medium**: 6-10 saturated tasks → IMPL_PLAN.md + TODO_LIST.md
|
||||
- **Complex**: Exceeding 10 tasks requires re-scoping (maximum enforced)
|
||||
|
||||
**10-Task Hard Limit**: Projects exceeding 10 tasks must be re-scoped into smaller iterations
|
||||
**Note**: 1 complex preparation task = 0.5 saturated task for counting
|
||||
|
||||
### Task Granularity Principles
|
||||
- **Decompose by function, not by file**: Each task should complete a whole functional unit
|
||||
- **Maintain functional integrity**: Each task produces independently runnable or testable functionality
|
||||
- **Implement related components together**: UI, logic, tests and other related parts in the same task
|
||||
- **Group related files together**: Keep related files (UI, logic, tests, config) in same task
|
||||
- **File cohesion rule**: Files that work together should be modified in the same task
|
||||
- **Avoid technical step decomposition**: Don't make "create file" or "add function" as separate tasks
|
||||
- **Maximum 10 tasks**: Hard limit enforced; re-scope if exceeded
|
||||
|
||||
### Task Decomposition Anti-patterns
|
||||
|
||||
❌ **Wrong Example - File/Step-based Decomposition**:
|
||||
- IMPL-001: Create database model
|
||||
- IMPL-002: Create API endpoint
|
||||
@@ -111,9 +121,18 @@ The command automatically detects input type:
|
||||
- IMPL-004: Add routing configuration
|
||||
- IMPL-005: Write unit tests
|
||||
|
||||
✅ **Correct Example - Function-based Decomposition**:
|
||||
- IMPL-001: Implement user authentication feature (includes model, API, UI, tests)
|
||||
- IMPL-002: Implement data export functionality (includes processing logic, UI, file generation)
|
||||
❌ **Wrong Example - Same File Split Across Tasks**:
|
||||
- IMPL-001: Add authentication routes to routes/auth.js
|
||||
- IMPL-002: Add user validation to routes/auth.js
|
||||
- IMPL-003: Add session handling to routes/auth.js
|
||||
|
||||
✅ **Correct Example - Function-based with File Cohesion**:
|
||||
- IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, middleware/auth.js, tests/auth.test.js)
|
||||
- IMPL-002: Implement data export functionality (includes services/export.js, routes/export.js, components/ExportButton.jsx, utils/fileGenerator.js, tests/export.test.js)
|
||||
|
||||
✅ **Correct Example - Related Files Grouped**:
|
||||
- IMPL-001: User management system (includes User model, UserController, UserService, user routes, user tests)
|
||||
- IMPL-002: Product catalog system (includes Product model, ProductController, catalog components, product tests)
|
||||
|
||||
### Task Generation with Saturation Control
|
||||
*Using decomposition strategy determined in Pre-Planning Analysis:*
|
||||
@@ -152,45 +171,53 @@ Three analysis levels available:
|
||||
3. Populates task paths automatically
|
||||
|
||||
### Task Saturation Assessment
|
||||
Evaluates whether to merge preparation and execution:
|
||||
Evaluates whether to merge preparation and execution within 10-task limit:
|
||||
|
||||
**Default Merge Principles** (Saturated Tasks):
|
||||
- All components of the same functional module
|
||||
- Frontend and backend paired implementation
|
||||
- Features with their corresponding tests
|
||||
- Related files that work together (UI, logic, tests, config)
|
||||
- Features with their corresponding tests and documentation
|
||||
- Configuration with its usage code
|
||||
- Multiple small interdependent functions
|
||||
- Files that share common interfaces or data structures
|
||||
|
||||
**Only Separate Tasks When**:
|
||||
- Completely independent functional modules (no shared code)
|
||||
- Independent services with different tech stacks (e.g., separate frontend/backend deployment)
|
||||
- Completely independent functional modules (no shared code or interfaces)
|
||||
- Independent services with different tech stacks (e.g., separate deployment units)
|
||||
- Modules requiring different expertise (e.g., ML model training vs Web development)
|
||||
- Large features with clear sequential dependencies
|
||||
- **Critical**: Would exceed 10-task limit otherwise
|
||||
|
||||
**Task Examples**:
|
||||
- **Merged Example**: "IMPL-001: Implement user authentication system (includes JWT management, API endpoints, UI components, and tests)"
|
||||
- **Separated Example**: "IMPL-001: Design cross-service authentication architecture" + "IMPL-002: Implement frontend authentication module" + "IMPL-003: Implement backend authentication service"
|
||||
**File Cohesion Examples**:
|
||||
- **Merged**: "IMPL-001: Implement user authentication (includes models/User.js, routes/auth.js, components/LoginForm.jsx, tests/auth.test.js)"
|
||||
- **Separated**: "IMPL-001: User service authentication" + "IMPL-002: Admin dashboard authentication" (different user contexts)
|
||||
|
||||
**10-Task Compliance**: Always prioritize related file grouping to stay within limit
|
||||
|
||||
### Task Breakdown Process
|
||||
- **Automatic decomposition**: Only when task count >15 are tasks broken into subtasks (impl-N.M format)
|
||||
- **Automatic decomposition**: Only when task count >10 triggers re-scoping (not decomposition)
|
||||
- **Function-based decomposition**: Split by independent functional boundaries, not by technical layers
|
||||
- **Container tasks**: Parent tasks with subtasks become containers (marked with ▸ in TODO_LIST)
|
||||
- **Smart decomposition**: AI analyzes task title to suggest logical functional subtask structure
|
||||
- **Complete unit principle**: Each subtask must still represent a complete functional unit
|
||||
- **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
|
||||
- **Maximum depth**: 2 levels (IMPL-N.M) to maintain manageable hierarchy
|
||||
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
|
||||
|
||||
### Implementation Field Requirements
|
||||
- **pre_analysis**: Multi-step analysis configuration array containing:
|
||||
- `action`: Brief 2-3 word description (e.g., "analyze patterns", "review security") - agent expands based on context
|
||||
- `template`: Full template path (e.g., "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt")
|
||||
- `method`: Analysis method ("manual"|"auto-detected"|"gemini"|"codex")
|
||||
- **Agent Behavior**: Agents interpret brief actions and expand them into comprehensive analysis tasks
|
||||
- **Execution**: Steps processed sequentially, results accumulated for comprehensive context
|
||||
- **Auto-assignment**: Defaults to appropriate multi-step configuration based on complexity
|
||||
- **Required fields**: files (with path/location/modifications), context_notes, pre_analysis
|
||||
- **Paths format**: Semicolon-separated list (e.g., "src/auth;tests/auth;config/auth.json")
|
||||
### Flow Control Field Requirements
|
||||
- **flow_control**: Universal process manager containing:
|
||||
- `pre_analysis`: Array of sequential process steps with:
|
||||
- `step`: Unique identifier for the step
|
||||
- `action`: Human-readable description
|
||||
- `command`: Executable command with embedded context variables (e.g., `${variable_name}`)
|
||||
- `output_to`: Variable name to store step results (optional for final steps)
|
||||
- `on_error`: Error handling strategy
|
||||
- `implementation_approach`: Brief one-line strategy description
|
||||
- `target_files`: Array of "file:function:lines" format strings
|
||||
- **Auto-generation**: Creates flow based on task type and complexity
|
||||
- **Required fields**: meta (type, agent), context (requirements, focus_paths, acceptance, depends_on), flow_control
|
||||
- **Focus paths format**: Array of strings (e.g., ["src/auth", "tests/auth", "config/auth.json"])
|
||||
|
||||
## Session Check Process
|
||||
⚠️ **CRITICAL**: Check for existing active session before planning
|
||||
@@ -208,9 +235,9 @@ Evaluates whether to merge preparation and execution:
|
||||
- Used by: `/workflow:execute` for context loading
|
||||
- Contains: Requirements, task overview, success criteria
|
||||
|
||||
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/impl-*.json`
|
||||
- **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
|
||||
- Contains: Complete task details with 7-field structure including flow_control process manager
|
||||
|
||||
- **Progress Tracking**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
|
||||
- Used by: `/workflow:execute` for status tracking
|
||||
@@ -233,7 +260,7 @@ Evaluates whether to merge preparation and execution:
|
||||
```
|
||||
|
||||
### Optional TODO_LIST.md (Auto-triggered)
|
||||
Created when complexity > simple or task count > 5
|
||||
Created when complexity > simple or task count > 3
|
||||
|
||||
**TODO_LIST Structure**: Uses unified hierarchical list format
|
||||
- Container tasks (with subtasks) marked with `▸` symbol
|
||||
@@ -258,18 +285,20 @@ Generated in .task/ directory when decomposition enabled
|
||||
### Recommended Task Patterns
|
||||
|
||||
#### Complete Feature Implementation
|
||||
"Implement user management system" - includes CRUD operations, permissions, UI components, API endpoints, and tests
|
||||
"Implement user management system" - includes all related files: models/User.js, controllers/UserController.js, routes/users.js, components/UserList.jsx, services/UserService.js, tests/user.test.js
|
||||
|
||||
#### End-to-End Features
|
||||
"Add Excel export functionality" - includes data processing, file generation, download API, UI buttons, and error handling
|
||||
"Add Excel export functionality" - includes cohesive file set: services/ExportService.js, utils/excelGenerator.js, routes/export.js, components/ExportButton.jsx, middleware/downloadHandler.js, tests/export.test.js
|
||||
|
||||
#### System Integration
|
||||
"Integrate payment gateway" - includes API integration, order processing, payment flows, webhook handling, and testing
|
||||
"Integrate payment gateway" - includes integration files: services/PaymentService.js, controllers/PaymentController.js, models/Payment.js, components/PaymentForm.jsx, webhooks/paymentWebhook.js, tests/payment.test.js
|
||||
|
||||
#### Problem Resolution
|
||||
"Fix and optimize search functionality" - includes bug fixes, performance optimization, UI improvements, and related tests
|
||||
"Fix and optimize search functionality" - includes related files: services/SearchService.js, utils/searchOptimizer.js, components/SearchBar.jsx, controllers/SearchController.js, tests/search.test.js
|
||||
|
||||
#### Module Development
|
||||
"Create notification system" - includes email/SMS sending, template management, subscription handling, and admin interface
|
||||
"Create notification system" - includes module files: services/NotificationService.js, models/Notification.js, templates/emailTemplates.js, components/NotificationCenter.jsx, workers/notificationQueue.js, tests/notification.test.js
|
||||
|
||||
**System ensures**: Unified planning interface with intelligent input detection and function-based task granularity
|
||||
**File Cohesion Principle**: Each task includes ALL files that work together to deliver the complete functionality
|
||||
|
||||
**System ensures**: Unified planning interface with intelligent input detection, function-based task granularity, file cohesion enforcement, and 10-task maximum limit
|
||||
@@ -18,6 +18,10 @@ Intelligently resumes interrupted workflows with automatic detection of interrup
|
||||
## Core Principles
|
||||
**File Structure:** @~/.claude/workflows/workflow-architecture.md
|
||||
|
||||
**Dependency Context Rules:**
|
||||
- **For tasks with dependencies**: MUST read previous task summary documents before resuming
|
||||
- **Context inheritance**: Use dependency summaries to maintain consistency and avoid duplicate work
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
/workflow:resume [--from TASK-ID] [--retry] [--skip TASK-ID] [--force]
|
||||
@@ -152,7 +156,7 @@ function detect_interruption():
|
||||
```bash
|
||||
# Reconstruct complete agent context from interruption point
|
||||
Task(subagent_type="code-developer",
|
||||
prompt="[RESUME_CONTEXT] [MULTI_STEP_ANALYSIS] Resume impl-1.2: Implement JWT authentication
|
||||
prompt="[RESUME_CONTEXT] [FLOW_CONTROL] Resume impl-1.2: Implement JWT authentication
|
||||
|
||||
RESUMPTION CONTEXT:
|
||||
- Interruption Type: agent_timeout
|
||||
@@ -160,6 +164,7 @@ Task(subagent_type="code-developer",
|
||||
- Completed Tasks: impl-1.1 (auth schema design)
|
||||
- Current Task State: in_progress
|
||||
- Recovery Strategy: retry_with_enhanced_context
|
||||
- Interrupted at Flow Step: analyze_patterns
|
||||
|
||||
AVAILABLE CONTEXT:
|
||||
- Completed Task Summaries: .workflow/WFS-user-auth/.summaries/impl-1.1-summary.md
|
||||
@@ -167,20 +172,28 @@ Task(subagent_type="code-developer",
|
||||
- Task Definition: .workflow/WFS-user-auth/.task/impl-1.2.json
|
||||
- Session State: .workflow/WFS-user-auth/workflow-session.json
|
||||
|
||||
PRE-ANALYSIS REQUIREMENTS:
|
||||
$(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.implementation.pre_analysis[] | "- " + .action + " (" + .method + "): " + .template')
|
||||
FLOW CONTROL RECOVERY:
|
||||
Resume from step: analyze_patterns
|
||||
$(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.pre_analysis[] | "- Step: " + .step + " | Action: " + .action + " | Command: " + .command')
|
||||
|
||||
CONTINUATION INSTRUCTIONS:
|
||||
1. Review previous completion summaries for context
|
||||
2. Check current codebase state against expected progress
|
||||
3. Identify any changes since last execution
|
||||
4. Resume from detected interruption point
|
||||
5. Complete remaining task objectives
|
||||
CONTEXT RECOVERY STEPS:
|
||||
1. MANDATORY: Read previous task summary documents for all dependencies
|
||||
2. Load dependency summaries from context.depends_on
|
||||
3. Restore previous step outputs if available
|
||||
4. Resume from interrupted flow control step
|
||||
5. Execute remaining steps with accumulated context
|
||||
6. Generate comprehensive summary with dependency outputs
|
||||
|
||||
Focus Paths: $(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
|
||||
Analysis Command: ~/.claude/scripts/gemini-wrapper -p \"$(~/.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"",
|
||||
Focus Paths: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.context.focus_paths[]')
|
||||
Target Files: $(cat .workflow/WFS-user-auth/.task/impl-1.2.json | jq -r '.flow_control.target_files[]')
|
||||
|
||||
description="Resume interrupted task with complete context reconstruction")
|
||||
IMPORTANT:
|
||||
1. Resume flow control from interrupted step with error recovery
|
||||
2. Ensure context continuity through step chain
|
||||
3. Create enhanced summary for dependent tasks
|
||||
4. Update progress tracking upon successful completion",
|
||||
|
||||
description="Resume interrupted task with flow control step recovery")
|
||||
```
|
||||
|
||||
### 4. Resume Coordination with TodoWrite
|
||||
@@ -197,7 +210,7 @@ Task(subagent_type="code-developer",
|
||||
|
||||
## Resume Execution Plan
|
||||
- [x] **TASK-001**: [Completed] Design auth schema (impl-1.1)
|
||||
- [ ] **TASK-002**: [RESUME] [Agent: code-developer] [MULTI_STEP_ANALYSIS] Implement JWT authentication (impl-1.2)
|
||||
- [ ] **TASK-002**: [RESUME] [Agent: code-developer] [FLOW_CONTROL] Implement JWT authentication (impl-1.2)
|
||||
- [ ] **TASK-003**: [Pending] [Agent: code-review-agent] Review implementations (impl-1.3)
|
||||
- [ ] **TASK-004**: Update session state and mark workflow complete
|
||||
|
||||
@@ -326,10 +339,34 @@ Task(subagent_type="code-developer",
|
||||
|
||||
## Advanced Resume Features
|
||||
|
||||
### Step-Level Recovery
|
||||
- **Flow Control Interruption Detection**: Identify which flow control step was interrupted
|
||||
- **Step Context Restoration**: Restore accumulated context up to interruption point
|
||||
- **Partial Step Recovery**: Resume from specific flow control step
|
||||
- **Context Chain Validation**: Verify context continuity through step sequence
|
||||
|
||||
#### Step-Level Resume Options
|
||||
```bash
|
||||
# Resume from specific flow control step
|
||||
/workflow:resume --from-step analyze_patterns impl-1.2
|
||||
|
||||
# Retry specific step with enhanced context
|
||||
/workflow:resume --retry-step gather_context impl-1.2
|
||||
|
||||
# Skip failing step and continue with next
|
||||
/workflow:resume --skip-step analyze_patterns impl-1.2
|
||||
```
|
||||
|
||||
### Enhanced Context Recovery
|
||||
- **Dependency Summary Integration**: Automatic loading of prerequisite task summaries
|
||||
- **Variable State Restoration**: Restore step output variables from previous execution
|
||||
- **Command State Recovery**: Detect partial command execution and resume appropriately
|
||||
- **Error Context Preservation**: Maintain error information for improved retry strategies
|
||||
|
||||
### Checkpoint System
|
||||
- **Automatic Checkpoints**: Created after each successful task completion
|
||||
- **Checkpoint Validation**: Verify codebase state matches expected progress
|
||||
- **Rollback Capability**: Option to resume from previous valid checkpoint
|
||||
- **Step-Level Checkpoints**: Created after each successful flow control step
|
||||
- **Context State Snapshots**: Save variable states at each checkpoint
|
||||
- **Rollback Capability**: Option to resume from previous valid step checkpoint
|
||||
|
||||
### Parallel Task Recovery
|
||||
```bash
|
||||
|
||||
@@ -53,7 +53,7 @@ Display comprehensive status information for the currently active workflow sessi
|
||||
📄 Generated Documents:
|
||||
✅ IMPL_PLAN.md (Complete)
|
||||
✅ TODO_LIST.md (Auto-updated)
|
||||
📝 .task/impl-*.json (5 tasks)
|
||||
📝 .task/IMPL-*.json (5 tasks)
|
||||
📊 reports/ (Ready for generation)
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user