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 workflow plan command and architecture documentation

Browse Source 
- Simplified argument hints and examples in plan.md
- Enhanced input detection logic for files, issues, and text
- Introduced analysis levels for improved context analysis
- Updated core rules for task limits and decomposition strategies
- Improved session management with active session marker system
- Expanded file structure reference and naming conventions
- Clarified task hierarchy and status rules
- Added detailed validation and error handling procedures
- Streamlined document templates for implementation plans and task summaries
This commit is contained in:
catlog22
2025-09-15 22:11:31 +08:00
parent 9371af8d8d
commit 6570af264d
3 changed files with 515 additions and 733 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
.claude/commands/workflow/execute.md
View File

@@ -7,69 +7,46 @@ examples:
- /workflow:execute
---
# Workflow Execute Command (/workflow:execute)
# Workflow Execute Command
## Overview
Coordinates multiple agents for executing existing workflow tasks through automatic discovery and intelligent task orchestration. Analyzes workflow folders, checks task statuses, and coordinates agent execution based on discovered plans.
## Core Principles
Coordinates agents for executing workflow tasks through automatic discovery and orchestration. Discovers plans, checks statuses, and executes ready tasks with complete context.
## Execution Philosophy
- **Discovery-first**: Auto-discover existing plans and tasks
- **Status-aware**: Execute only ready tasks
- **Context-rich**: Use complete task JSON data for agents
- **Progress tracking**: Update status after completion
The intelligent execution approach focuses on:
- **Discovery-first execution** - Automatically discover existing plans and tasks
- **Status-aware coordination** - Execute only tasks that are ready
- **Context-rich agent assignment** - Use complete task JSON data for agent context
- **Dynamic task orchestration** - Coordinate based on discovered task relationships
- **Progress tracking** - Update task status after agent completion
**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
**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)
## Flow Control Execution
**[FLOW_CONTROL]** marker indicates sequential step execution required:
- **Auto-trigger**: When `task.flow_control.pre_analysis` exists
- **Process**: Execute steps sequentially BEFORE implementation
- Load dependency summaries and parent context
- Execute CLI tools, scripts, and commands as specified
- Pass context between steps via `${variable_name}`
- Handle errors per step strategy
## Execution Flow
### 1. Discovery & Analysis Phase
### 1. Discovery Phase
```
Workflow Discovery:
├── Locate workflow folder (provided or current session)
├── Load workflow-session.json for session state
├── Scan .task/ directory for all task JSON files
├── Read IMPL_PLAN.md for workflow context
├── Locate workflow folder (current session)
├── Load workflow-session.json and IMPL_PLAN.md
├── Scan .task/ directory for task JSON files
├── Analyze task statuses and dependencies
└── Determine executable tasks
└── Build execution queue of ready tasks
```
**Discovery Logic:**
- **Folder Detection**: Use provided folder or find current active session
- **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
### 2. TodoWrite Coordination Setup
**Always First**: Create comprehensive TodoWrite based on discovered tasks
### 2. TodoWrite Coordination
Create comprehensive TodoWrite based on discovered tasks:
```markdown
# Workflow Execute Coordination
*Session: WFS-[topic-slug]*
## Execution Plan
- [ ] **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-001**: [Agent: code-developer] [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
@@ -78,84 +55,45 @@ Workflow Discovery:
```
### 3. Agent Context Assignment
For each executable task:
**Task JSON Structure**:
```json
{
"task": {
"id": "IMPL-1.1",
"title": "Design auth schema",
"status": "pending",
"meta": {
"type": "feature",
"agent": "code-developer"
},
"context": {
"requirements": ["JWT authentication", "User model design"],
"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": [
{
"step": "gather_context",
"action": "Load dependency summaries",
"command": "bash(echo 'No dependencies for this initial task')",
"output_to": "dependency_context",
"on_error": "skip_optional"
},
{
"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"
},
{
"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"
]
}
"id": "IMPL-1.1",
"title": "Design auth schema",
"status": "pending",
"meta": { "type": "feature", "agent": "code-developer" },
"context": {
"requirements": ["JWT authentication", "User model design"],
"focus_paths": ["src/auth/models", "tests/auth"],
"acceptance": ["Schema validates JWT tokens"],
"depends_on": [],
"inherited": { "from": "IMPL-1", "context": ["..."] }
},
"workflow": {
"session": "WFS-user-auth",
"phase": "IMPLEMENT",
"plan_context": "Authentication system with OAuth2 support"
"flow_control": {
"pre_analysis": [
{
"step": "analyze_patterns",
"action": "Analyze existing auth patterns",
"command": "~/.claude/scripts/gemini-wrapper -p '@{src/auth/**/*} analyze patterns'",
"output_to": "pattern_analysis",
"on_error": "fail"
}
],
"implementation_approach": "Design flexible user schema",
"target_files": ["src/auth/models/User.ts:UserSchema:10-50"]
}
}
```
**Context Assignment Rules:**
- **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
- **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
**Context Assignment Rules**:
- Use complete task JSON including flow_control
- Load dependency summaries from context.depends_on
- Execute flow_control.pre_analysis steps sequentially
- Direct agents to context.focus_paths
- Auto-add [FLOW_CONTROL] marker when pre_analysis exists
### 4. Agent Execution & Progress Tracking
### 4. Agent Execution Pattern
```bash
Task(subagent_type="code-developer",
@@ -198,182 +136,83 @@ Task(subagent_type="code-developer",
description="Execute task with flow control step processing")
```
**Execution Protocol:**
- **Sequential Execution**: Respect task dependencies and execution order
- **Progress Monitoring**: Track through TodoWrite updates
- **Status Updates**: Update task JSON status after each completion
- **Cross-Agent Handoffs**: Coordinate results between related tasks
**Execution Protocol**:
- Sequential execution respecting dependencies
- Progress tracking through TodoWrite updates
- Status updates after completion
- Cross-agent result coordination
## Discovery & Analysis Process
## File Structure & Analysis
### File Structure Analysis
### Workflow Structure
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Session state and stats
├── IMPL_PLAN.md # Workflow context and requirements
├── workflow-session.json # Session state
├── IMPL_PLAN.md # Requirements
├── .task/ # Task definitions
│ ├── IMPL-1.json # Main tasks
│ ├── IMPL-1.1.json # Subtasks
│ └── IMPL-1.2.json # Detailed tasks
└── .summaries/ # Completed task summaries
│ ├── IMPL-1.json
│ └── IMPL-1.1.json
└── .summaries/ # Completion summaries
```
### Task Status Assessment
```pseudo
function analyze_tasks(task_files):
executable_tasks = []
for task in task_files:
if task.status == "pending" and dependencies_met(task):
if task.subtasks.length == 0: // leaf task
executable_tasks.append(task)
else: // container task - check subtasks
if all_subtasks_ready(task):
executable_tasks.extend(task.subtasks)
return executable_tasks
### Task Status Logic
```
pending + dependencies_met → executable
completed → skip
blocked → skip until dependencies clear
```
### Automatic Agent Assignment
Based on discovered task data:
- **task.agent field**: Use specified agent from task JSON
- **task.type analysis**:
### Agent Assignment
- **task.agent field**: Use specified agent
- **task.type fallback**:
- "feature" → code-developer
- "test" → code-review-test-agent
- "docs" → code-developer
- "test" → code-review-test-agent
- "review" → code-review-agent
- **Gemini context**: Auto-assign based on task.context.scope and requirements
## Agent Task Assignment Patterns
### Discovery-Based Assignment
```bash
# Agent receives complete discovered context with saturation handling
Task(subagent_type="code-developer",
prompt="[FLOW_CONTROL] 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 ~/.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
```bash
# After agent completion, update discovered task status
update_task_status("IMPL-1.2", "completed")
mark_dependent_tasks_ready(task_dependencies)
```
## Coordination Strategies
### Automatic Coordination
- **Task Dependencies**: Execute in dependency order from discovered relationships
- **Agent Handoffs**: Pass results between agents based on task hierarchy
- **Progress Updates**: Update TodoWrite and JSON files after each completion
### Context Distribution
- **Rich Context**: Each agent gets complete task JSON + workflow context
- **Focus Areas**: Direct agents to specific files from task.context.scope
- **Inheritance**: Subtasks inherit parent context automatically
- **Session Integration**: Include workflow-session.json state in agent context
## Status Management
## Status Management & Coordination
### Task Status Updates
```json
// Before execution
{
"id": "IMPL-1.2",
"status": "pending",
"execution": {
"attempts": 0,
"last_attempt": null
}
}
{ "id": "IMPL-1.2", "status": "pending", "execution": { "attempts": 0 } }
// After execution
{
"id": "IMPL-1.2",
"status": "completed",
"execution": {
"attempts": 1,
"last_attempt": "2025-09-08T14:30:00Z"
}
}
// After execution
{ "id": "IMPL-1.2", "status": "completed", "execution": { "attempts": 1, "last_attempt": "2025-09-08T14:30:00Z" } }
```
### Session State Updates
```json
{
"current_phase": "EXECUTE",
"last_execute_run": "2025-09-08T14:30:00Z"
}
```
### Coordination Strategies
- **Dependencies**: Execute in dependency order
- **Agent Handoffs**: Pass results between agents
- **Progress Updates**: Update TodoWrite and JSON files
- **Context Distribution**: Complete task JSON + workflow context
- **Focus Areas**: Direct agents to specific paths from task.context.focus_paths
## Error Handling & Recovery
## Error Handling
### Discovery Issues
```bash
# No active session found
❌ No active workflow session found
→ Use: /workflow:session:start "project name" first
# No executable tasks
⚠️ All tasks completed or blocked
→ Check: /context for task status overview
# Missing task files
❌ Task IMPL-1.2 referenced but JSON file missing
→ Fix: /task/create or repair task references
❌ No active workflow session → Use: /workflow:session:start "project"
⚠️ All tasks completed/blocked → Check: /context for status
❌ Missing task files → Fix: /task/create or repair references
```
### Execution Recovery
- **Failed Agent**: Retry with adjusted context or different agent
- **Failed Agent**: Retry with adjusted context
- **Blocked Dependencies**: Skip and continue with available tasks
- **Context Issues**: Reload from JSON files and session state
## Integration Points
## Integration & Next Steps
### Automatic Behaviors
- **Discovery on start** - Analyze workflow folder structure
- **TodoWrite coordination** - Generate based on discovered tasks
- **Agent context preparation** - Use complete task JSON data
- **Status synchronization** - Update JSON files after completion
- Discovery on start - analyze workflow folder structure
- TodoWrite coordination - generate based on discovered tasks
- Agent context preparation - use complete task JSON data
- Status synchronization - update JSON files after completion
### Next Actions
```bash
# After /workflow:execute completion
```bash
/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
```

347
.claude/commands/workflow/plan.md
View File

@@ -2,303 +2,116 @@
name: plan
description: Create implementation plans with intelligent input detection
usage: /workflow:plan <input>
argument-hint: "text description"|file.md|ISS-001|template-name
argument-hint: "text description"|file.md|ISS-001
examples:
- /workflow:plan "Build authentication system"
- /workflow:plan requirements.md
- /workflow:plan ISS-001
---
# Workflow Plan Command (/workflow:plan)
## Overview
Creates actionable implementation plans with intelligent input source detection. Supports text, files, issues, and templates through automatic recognition.
## 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
# Workflow Plan Command
## Usage
```bash
/workflow:plan [--AM gemini|codex] <input>
/workflow:plan [--AM gemini|codex] [--analyze|--deep] <input>
```
### Analysis Method Flag (--AM)
Optional flag to specify which CLI tool to use for context analysis:
- **gemini** (default): Uses Gemini CLI for pattern-based analysis, architectural understanding, and broader context acquisition
- **codex**: Uses Codex CLI for autonomous development context gathering with intelligent file discovery
## Input Detection
- **Files**: `.md/.txt/.json/.yaml/.yml` → Reads content and extracts requirements
- **Issues**: `ISS-*`, `ISSUE-*`, `*-request-*` → Loads issue data and acceptance criteria
- **Text**: Everything else → Parses natural language requirements
**Examples**:
```bash
/workflow:plan --AM codex "Build authentication system"
/workflow:plan --AM gemini requirements.md
```
## Analysis Levels
- **Quick** (default): Structure only (5s)
- **--analyze**: Structure + context analysis (30s)
- **--deep**: Structure + comprehensive parallel analysis (1-2m)
## Input Detection Logic
The command automatically detects input type:
## Core Rules
### File Input (Auto-detected)
```bash
/workflow:plan requirements.md
/workflow:plan config.json
```
**Triggers**: Extensions: .md, .txt, .json, .yaml, .yml
**Processing**: Reads file contents and extracts requirements
### File Structure Reference
**Architecture**: @~/.claude/workflows/workflow-architecture.md
### Issue Input (Auto-detected)
```bash
/workflow:plan ISS-001
/workflow:plan ISSUE-123
```
**Triggers**: Patterns: ISS-*, ISSUE-*, *-request-*
**Processing**: Loads issue data and acceptance criteria
### Task Limits & Decomposition
- **Maximum 10 tasks**: Hard enforced limit - projects exceeding must be re-scoped
- **Function-based decomposition**: By complete functional units, not files/steps
- **File cohesion**: Group related files (UI + logic + tests + config) in same task
- **Task saturation**: Merge "analyze + implement" by default (0.5 count for complex prep tasks)
### Text Input (Default)
```bash
/workflow:plan "Build user authentication with JWT and OAuth2"
```
**Triggers**: Everything else
**Processing**: Parse natural language requirements
## Automatic Behaviors
### Pre-Planning Analysis (CRITICAL)
⚠️ **Must complete BEFORE generating any plan documents**
1. **Complexity assessment**: Count total saturated tasks
2. **Decomposition strategy**: Flat (≤5) | Hierarchical (6-10) | Re-scope (>10)
3. **File grouping**: Identify cohesive file sets
4. **Quantity prediction**: Estimate main tasks, subtasks, container vs leaf ratio
### Session Management
- Creates new session if none exists
- Uses active session if available
- Generates session ID: WFS-[topic-slug]
- **Active session check**: Check for `.workflow/.active-*` marker first
- Auto-creates new session: `WFS-[topic-slug]`
- Uses existing active session if available
- **Dependency context**: MUST read previous task summary documents before planning
### Pre-Planning Analysis
⚠️ **CRITICAL**: Determine decomposition strategy BEFORE generating any plan documents
## Task Patterns
**Required Pre-Analysis Steps**:
1. **Complexity Assessment**: Analyze requirements to determine total saturated task count
2. **Decomposition Strategy**: Based on complexity, decide:
- Task structure (flat vs hierarchical)
- 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)
- Container vs leaf task ratio
### ✅ Correct (Function-based)
- `IMPL-001: User authentication system` (models + routes + components + middleware + tests)
- `IMPL-002: Data export functionality` (service + routes + UI + utils + tests)
**Pre-Planning Outputs**:
- 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**: ≤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
- **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
- IMPL-003: Create frontend component
- IMPL-004: Add routing configuration
- IMPL-005: Write unit tests
❌ **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:*
- **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 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
### Project Analysis Options
Three analysis levels available:
```bash
# Quick - Structure only (5 seconds)
/workflow:plan "requirements"
# Standard - Structure + Gemini analysis (30 seconds)
/workflow:plan --analyze "requirements"
# Deep - Structure + Parallel comprehensive analysis (1-2 minutes)
/workflow:plan --deep "requirements"
```
**Analysis Selection**:
- Default: Auto-selects based on project complexity
- Manual: Use flags to override automatic selection
- Strategy: See @~/.claude/workflows/intelligent-tools-strategy.md for tool selection principles
**Execution**:
1. Always runs `get_modules_by_depth.sh` for structure
2. Applies selected analysis level
3. Populates task paths automatically
### Task Saturation Assessment
Evaluates whether to merge preparation and execution within 10-task limit:
**Default Merge Principles** (Saturated Tasks):
- All components of the same functional module
- 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 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
**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 >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
- **10-task enforcement**: Exceeding 10 tasks requires project re-scoping
### 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
1. **Check Active Session**: Check for `.workflow/.active-*` marker file
2. **Session Selection**: Use existing active session or create new
3. **Context Integration**: Load session state and existing context
### ❌ Wrong (File/step-based)
- `IMPL-001: Create database model`
- `IMPL-002: Create API endpoint`
- `IMPL-003: Create frontend component`
## Output Documents
### Document References for Execution
### Always Created
- **IMPL_PLAN.md**: Requirements, task breakdown, success criteria
- **Session state**: Task references and paths
#### Primary References
- **Planning Document**: `.workflow/WFS-[topic-slug]/IMPL_PLAN.md`
- Used by: `/workflow:execute` for context loading
- Contains: Requirements, task overview, success criteria
### Auto-Created (complexity > simple)
- **TODO_LIST.md**: Hierarchical progress tracking
- **.task/*.json**: Individual task definitions with flow_control
- **Task Definitions**: `.workflow/WFS-[topic-slug]/.task/IMPL-*.json`
- Used by: Agents for implementation context
- 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
- Updated by: Agents after task completion
### IMPL_PLAN.md (Always Created)
```markdown
# Implementation Plan - [Project Name]
*Generated from: [input_source]*
## Requirements
[Extracted requirements from input source]
## Task Breakdown
- **IMPL-001**: [Saturated task description with merged preparation and execution]
- **IMPL-002**: [Task description]
## Success Criteria
[Measurable completion conditions]
### Document Structure
```
.workflow/WFS-[topic]/
├── IMPL_PLAN.md # Main planning document
├── TODO_LIST.md # Progress tracking (if complex)
└── .task/
├── IMPL-001.json # Task definitions
└── IMPL-002.json
```
### Optional TODO_LIST.md (Auto-triggered)
Created when complexity > simple or task count > 3
## Task Saturation Assessment
**Default Merge** (cohesive files together):
- Functional modules with UI + logic + tests + config
- Features with their tests and documentation
- Files sharing common interfaces/data structures
**TODO_LIST Structure**: Uses unified hierarchical list format
- Container tasks (with subtasks) marked with `▸` symbol
- Leaf tasks use standard `- [ ]` / `- [x]` checkboxes
- Indentation shows hierarchy (2 spaces per level)
- Container tasks represent logical grouping, not executable items
**Only Separate When**:
- Completely independent functional modules
- Different tech stacks or deployment units
- Would exceed 10-task limit otherwise
### Task JSON Files (Auto-created)
Generated in .task/ directory when decomposition enabled
## Flow Control Schema
Each task.json includes required fields:
- **meta**: type, agent assignment
- **context**: requirements, focus_paths, acceptance, depends_on
- **flow_control**:
- `pre_analysis`: Steps with commands and context variables (${var})
- `implementation_approach`: One-line strategy
- `target_files`: "file:function:lines" format
## Execution Integration
Documents created for `/workflow:execute`:
- **IMPL_PLAN.md**: Context loading and requirements
- **.task/*.json**: Agent implementation context
- **TODO_LIST.md**: Status tracking (container tasks with ▸, leaf tasks with checkboxes)
## Error Handling
- **Vague input**: Auto-reject ("fix it", "make better", etc.)
- **File not found**: Clear suggestions
- **>10 tasks**: Force re-scoping into iterations
### Input Processing Errors
- **File not found**: Clear error message with suggestions
- **Invalid issue**: Verify issue ID exists
- **Unknown template**: List available templates
- **Empty input**: Prompt for valid input
- **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
### Recommended Task Patterns
#### Complete Feature Implementation
"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 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 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 related files: services/SearchService.js, utils/searchOptimizer.js, components/SearchBar.jsx, controllers/SearchController.js, tests/search.test.js
#### Module Development
"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
**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
## Analysis Method (--AM)
- **gemini** (default): Pattern analysis, architectural understanding
- **codex**: Autonomous development, intelligent file discovery