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

Remove granular progress tracking across workflow system

Browse Source 
- Remove detailed progress views (Total Tasks: X, Completed: Y %) from all templates
- Simplify TODO_LIST.md structure by removing Progress Overview sections
- Remove stats tracking from session-management-principles.json schema
- Eliminate progress format and calculation logic from context command
- Remove percentage-based progress displays from action-planning-agent
- Simplify vibe command coordination by removing detailed task counts
- Focus on essential JSON state changes rather than UI progress metrics

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-08 15:26:01 +08:00
parent da717546f8
commit 9502741d50
17 changed files with 2064 additions and 3449 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude/agents/action-planning-agent.md
View File

@@ -209,12 +209,6 @@ Your primary responsibilities:
## Dependency Graph
[Visual or text representation of task dependencies]
## Progress Tracking
- **Total Tasks**: [Number]
- **Completed**: [Number] ([Percentage]%)
- **In Progress**: [Number]
- **Blocked**: [Number]
## Resource Requirements
[Tools, libraries, external dependencies needed]
@@ -226,9 +220,6 @@ Your primary responsibilities:
```markdown
# Task Progress List: [Project Name]
## Quick Progress Overview
**Total Items**: [Number] | **Completed**: [Number] ([Percentage]%) | **Remaining**: [Number]
## Main Tasks
### 🎯 [IMPL-001] [Primary Goal]
@@ -278,13 +269,12 @@ Your primary responsibilities:
5. **Integration with Development Workflow**:
- Create TodoWrite entries for each stage and major subtask
- For complex tasks, use enhanced IMPL_PLAN.md structure with hierarchical task breakdown
- Generate TODO_LIST.md for progress tracking and team coordination
- Generate TODO_LIST.md for task coordination
- Link todo checklist items to detailed task descriptions in implementation plan
- Identify which stages require architecture review
- Note where code review checkpoints should occur
- Specify testing requirements for each stage
- Maintain document synchronization across all planning artifacts
- Update progress tracking as tasks complete
- Provide clear navigation between implementation plan, task decomposition, and todo checklist
6. **Complexity Assessment**: Automatically determine planning approach based on task complexity:

533
.claude/commands/context.md
View File

@@ -1,344 +1,259 @@
---
name: context
description: Unified context command - Single source of truth for all workflow and task status information
usage: /context [task-id] [--format=<tree|list|json|progress>] [--health-check] [--detailed] [--export]
argument-hint: [optional task-id] [display format] [analysis options] [export flag]
description: Generate on-demand views from JSON task data
usage: /context [task-id] [--format=<format>] [--validate]
argument-hint: [optional: task-id, format, validation]
examples:
- /context
- /context IMPL-001
- /context --format=tree
- /context --health-check
- /context --detailed --export
- /context --format=progress
- /context impl-1
- /context --format=hierarchy
- /context --validate
---
# Unified Context Command (/context)
# Context Command (/context)
## Overview
Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files.
**Single Source of Truth**: This command replaces `/workflow:context` and `/task:context` with a unified interface that generates all views on-demand from JSON data. Eliminates synchronization complexity by making documents read-only views.
## Core Principles
**Data Source:** @~/.claude/workflows/json-document-coordination-system.md
**Session Management:** @~/.claude/workflows/session-management-principles.md
## Core Architecture
## Key Features
### Single Source of Truth Principle
- **JSON Authority**: All data read from `.task/*.json` and `workflow-session.json` files
- **Generated Views**: All markdown displays generated on-demand (never manually edited)
- **No Synchronization**: Documents are views, not synchronized states
- **Conflict-Free**: Single direction data flow eliminates conflicts
### Pure View Generation
- **No Sync**: Views are generated, not synchronized
- **Always Current**: Reads latest JSON data every time
- **No Persistence**: Views are temporary, not saved
- **Single Source**: All data comes from JSON files only
### Unified Command Interface
- **Global Context**: `/context` shows complete workflow status
- **Task-Specific**: `/context IMPL-001` shows individual task details
- **Health Checking**: `/context --health-check` validates JSON data integrity
- **Multiple Formats**: Tree, list, progress, and JSON output formats
### Multiple View Formats
- **Overview** (default): Current tasks and status
- **Hierarchy**: Task relationships and structure
- **Details**: Specific task information
## Usage Modes
## Usage
### 1. Global Workflow Context (Default)
### Default Overview
```bash
/context
```
**Generated Output** (from JSON data):
```
🔍 Workflow Status Overview
========================
📋 Session Information:
- Session ID: WFS-workflow-optimization
- Current Phase: IMPLEMENT
- Complexity: complex
- Start Time: 2025-09-07 14:30:22Z
- Duration: 4h 15m
📊 Task Progress (from .task/*.json):
✅ Completed: 2/5 (40%)
🔄 In Progress: 1 task
⏳ Pending: 2 tasks
🚫 Blocked: 0 tasks
📁 JSON Data Health:
✅ workflow-session.json - Valid JSON, complete data
✅ .task/ directory - 5 task files, all valid JSON
✅ Task relationships - All dependencies valid
✅ Progress calculations - Mathematically consistent
⏱️ Estimated Completion: 2025-09-07 20:45 (2h 30m remaining)
🎯 Next Actions (generated from JSON state):
1. Complete IMPL-003 (currently in progress)
2. Begin IMPL-004 (dependencies satisfied)
3. Review completed IMPL-001 and IMPL-002
```
### 2. Task-Specific Context
```bash
/context IMPL-001
```
**Generated Output** (from JSON file):
```
📋 Task Context: IMPL-001
━━━━━━━━━━━━━━━━━━━━━━
📄 JSON Source: .task/impl-001.json
Status: completed (from JSON authority)
Created: 2025-09-07T14:45:00Z
Completed: 2025-09-07T16:30:00Z
Duration: 1h 45m
🎯 Task Definition (from JSON):
Title: Implement single source of truth architecture by removing sync commands
Type: architecture
Agent: code-developer
Priority: critical
📋 Context (from JSON):
Requirements:
- Remove workflow:sync and task:sync commands
- Update coordination system documentation
- Establish JSON as single authority source
Scope:
- .claude/commands/workflow/sync.md
- .claude/commands/task/sync.md
- .claude/workflows/json-document-coordination-system.md
🔗 Dependencies (from JSON):
Upstream: None
Downstream: IMPL-002, IMPL-003
Parent: None
✅ Completion Status (from JSON):
Result: success
Files Modified: 3 files moved to deprecated, 1 file updated
Next Task: IMPL-002 ready to begin
```
### 3. Health Check Mode
```bash
/context --health-check
```
**Generated Analysis** (from JSON validation):
```
🏥 System Health Check (JSON Data Analysis)
========================================
✅ JSON File Integrity:
- workflow-session.json: ✅ Valid JSON, complete schema
- .task/impl-001.json: ✅ Valid JSON, all required fields
- .task/impl-002.json: ✅ Valid JSON, all required fields
- .task/impl-003.json: ✅ Valid JSON, all required fields
- .task/impl-004.json: ✅ Valid JSON, all required fields
- .task/impl-005.json: ✅ Valid JSON, all required fields
🔗 Data Consistency Check:
✅ Task IDs: All unique, follow impl-N format
✅ Dependencies: All referenced tasks exist
✅ Status Logic: All transitions valid
✅ Progress Math: Calculations consistent
✅ Timestamps: All valid, chronologically ordered
📊 Data Completeness:
✅ All tasks have required fields
✅ All tasks have context information
✅ All dependencies properly defined
✅ Session state complete
🎯 Overall System Health: 100% (Excellent)
- Zero data conflicts (Single source of truth benefit)
- All JSON files valid and consistent
- No synchronization issues (eliminated by design)
- Ready for continued execution
```
### 4. Tree Format Display
```bash
/context --format=tree
```
**Generated Tree** (from JSON hierarchy):
```
📁 WFS-workflow-optimization (from workflow-session.json)
├── 📋 PLAN [Completed]
│ └── Output: IMPL_PLAN.md, 5 tasks generated
├── 🔨 IMPLEMENT [Active - 40% complete]
│ ├── ✅ IMPL-001: Single source of truth architecture (completed)
│ ├── ✅ IMPL-002: Automated planning-to-execution flow (completed)
│ ├── 🔄 IMPL-003: Unified context commands (in_progress)
│ ├── ⏳ IMPL-004: Dynamic complexity escalation (pending)
│ └── ⏳ IMPL-005: Update session management (pending)
└── 📝 REVIEW [Pending]
└── Awaiting implementation completion
```
### 5. Progress Format
```bash
/context --format=progress
```
**Generated Progress View** (calculated from JSON data):
```
📊 Implementation Progress Report
==============================
🎯 Overall Progress: 40% (2/5 tasks complete)
📈 Progress by Phase:
┌─────────────┬─────────┬──────────┬─────────┐
│ Phase │ Status │ Progress │ Tasks │
├─────────────┼─────────┼──────────┼─────────┤
│ PLAN │ ✅ │ 100% │ N/A │
│ IMPLEMENT │ 🔄 │ 40% │ 2/5 │
│ REVIEW │ ⏳ │ 0% │ 0/0 │
└─────────────┴─────────┴──────────┴─────────┘
📋 Task Progress Details (from JSON files):
✅ IMPL-001: single source of truth [100%] ⏱️ 1h 45m
✅ IMPL-002: automated planning flow [100%] ⏱️ 2h 10m
🔄 IMPL-003: unified context commands [75%] ⏱️ 1h 30m (in progress)
⏳ IMPL-004: dynamic complexity [0%] ⏱️ 2h 00m (estimated)
⏳ IMPL-005: session management updates [0%] ⏱️ 1h 15m (estimated)
⏰ Time Analysis (calculated from JSON):
Time Spent: 5h 25m
Remaining: 2h 45m
Estimated Total: 8h 10m
Completion: 2025-09-07 21:15
```
## File Export Feature
### Export Generated Views
```bash
/context --export
```
**Generated Files** (all from JSON data):
```
.workflow/WFS-workflow-optimization/reports/
├── CONTEXT_REPORT.md # Current context view
├── PROGRESS_REPORT.md # Progress analysis
├── HEALTH_CHECK.md # System health status
└── context-exports/ # Historical exports
├── context-2025-09-07-14-30.md
├── progress-2025-09-07-15-45.md
└── health-2025-09-07-16-15.md
```
**Report Structure** (generated from JSON):
Generates current workflow overview:
```markdown
# Workflow Context Report
*Generated: 2025-09-07 16:15:00 from JSON data sources*
# Workflow Overview
**Session**: WFS-user-auth
**Phase**: IMPLEMENT
**Type**: medium
## Data Sources
- workflow-session.json (last updated: 2025-09-07T15:45:00Z)
- 5 task JSON files in .task/ directory
- All sources validated and consistent
## Active Tasks
- [⚠️] impl-1: Build authentication module (code-developer)
- [⚠️] impl-2: Setup user management (code-developer)
## Session Overview
[Generated from workflow-session.json]
## Completed Tasks
- [✅] impl-0: Project setup
## Task Analysis
[Generated from .task/*.json files]
## Health Assessment
[Validated from JSON data integrity]
---
*This report is a generated view from authoritative JSON data*
*No manual editing required - data updates automatically in JSON files*
## Stats
- **Total**: 8 tasks
- **Completed**: 3
- **Active**: 2
- **Remaining**: 3
```
## Advanced Features
### JSON Output for Scripting
### Specific Task View
```bash
/context --format=json
/context impl-1
```
**Generated JSON** (compiled from all sources):
```json
{
"session": {
"id": "WFS-workflow-optimization",
"status": "active",
"phase": "implement",
"progress": 40,
"data_source": "workflow-session.json"
},
"tasks": [
{
"id": "IMPL-001",
"status": "completed",
"progress": 100,
"data_source": ".task/impl-001.json"
}
],
"health": {
"json_integrity": 100,
"data_consistency": 100,
"completeness": 100
},
"generated_at": "2025-09-07T16:15:00Z",
"data_freshness": "current"
}
Shows detailed task information:
```markdown
# Task: impl-1
**Title**: Build authentication module
**Status**: active
**Agent**: code-developer
**Type**: feature
## Context
- **Requirements**: JWT authentication, OAuth2 support
- **Scope**: src/auth/*, tests/auth/*
- **Acceptance**: Module handles JWT tokens, OAuth2 flow implemented
- **Inherited From**: WFS-user-auth
## Relations
- **Parent**: none
- **Subtasks**: impl-1.1, impl-1.2
- **Dependencies**: impl-0
## Execution
- **Attempts**: 0
- **Last Attempt**: never
## Metadata
- **Created**: 2025-09-05T10:30:00Z
- **Updated**: 2025-09-05T10:35:00Z
```
### Health Check Integration
- **Validation Engine**: Checks all JSON files for schema compliance
- **Consistency Verification**: Validates cross-references between files
- **Data Integrity**: Ensures all dependencies and relationships are valid
- **Performance Monitoring**: Tracks data loading and generation speed
## Benefits of Unified Architecture
### Eliminated Complexity
- **No Sync Commands**: Removed `/workflow:sync` and `/task:sync`
- **No Conflicts**: Single source eliminates data drift
- **No Manual Document Editing**: All documents are generated views
- **Simplified User Experience**: One command for all context needs
### Enhanced Reliability
- **Data Consistency**: JSON authority ensures consistent state
- **Error Reduction**: No synchronization bugs or conflicts
- **Simplified Recovery**: Only JSON files need backup/restore
- **Predictable Behavior**: Views always reflect current JSON state
### Improved Performance
- **On-Demand Generation**: Views created only when requested
- **Efficient Data Access**: Direct JSON file reading
- **No Background Sync**: No overhead from synchronization processes
- **Cached Calculations**: Smart caching for expensive operations
## Technical Implementation
### Data Flow Architecture
```
JSON Files (.task/*.json + workflow-session.json)
↓ (Single Direction - Read Only)
View Generation Engine
↓
Formatted Output (Console/File)
### Hierarchy View
```bash
/context --format=hierarchy
```
### View Generation Process
1. **Load JSON Data**: Read all relevant JSON files
2. **Validate Data**: Check integrity and consistency
3. **Calculate Views**: Generate requested format/content
4. **Format Output**: Apply formatting and display
5. **Export (Optional)**: Save generated views to files
Shows task relationships:
```markdown
# Task Hierarchy
### Error Handling
- **Missing Files**: Clear error messages with recovery suggestions
- **Invalid JSON**: Schema validation with specific error details
- **Broken References**: Dependency validation with repair recommendations
- **Data Inconsistencies**: Automatic detection and resolution suggestions
## Main Tasks
- impl-0: Project setup ✅
- impl-1: Build authentication module ⚠️
- impl-1.1: Design auth schema
- impl-1.2: Implement auth logic
- impl-2: Setup user management ⚠️
## Dependencies
- impl-1 → depends on → impl-0
- impl-2 → depends on → impl-1
```
### Data Management
- All commands now work with JSON as single source of truth
- Document generation happens on-demand
- No synchronization commands needed
- Simplified data model improves reliability
## View Generation Process
### Data Loading
```pseudo
function generate_context_view(task_id, format):
// Load all current data
session = load_workflow_session()
all_tasks = load_all_task_json_files()
// Filter if specific task requested
if task_id:
target_task = find_task(all_tasks, task_id)
return generate_task_detail_view(target_task)
// Generate requested format
switch format:
case 'hierarchy':
return generate_hierarchy_view(all_tasks)
default:
return generate_overview(session, all_tasks)
```
### Real-Time Calculation
- **Task Counts**: Calculated from JSON file status fields
- **Relationships**: Built from JSON relations fields
- **Status**: Read directly from current JSON state
## Validation Mode
### Basic Validation
```bash
/context --validate
```
Performs integrity checks:
```markdown
# Validation Results
## JSON File Validation
✅ All task JSON files are valid
✅ Session file is valid and readable
## Relationship Validation
✅ All parent-child relationships are valid
✅ All dependencies reference existing tasks
✅ No circular dependencies detected
## Hierarchy Validation
✅ Task hierarchy within depth limits (max 3 levels)
✅ All subtask references are bidirectional
## Issues Found
⚠️ impl-3: No subtasks defined (expected for leaf task)
**Status**: All systems operational
```
### Validation Checks
- **JSON Schema**: All files parse correctly
- **References**: All task IDs exist
- **Hierarchy**: Parent-child relationships are valid
- **Dependencies**: No circular dependencies
- **Depth**: Task hierarchy within limits
## Error Handling
### Missing Files
```bash
❌ Session file not found
→ Initialize new workflow session? (y/n)
❌ Task impl-5 not found
→ Available tasks: impl-1, impl-2, impl-3, impl-4
```
### Invalid Data
```bash
❌ Invalid JSON in impl-2.json
→ Cannot generate view for impl-2
→ Repair file manually or recreate task
⚠️ Circular dependency detected: impl-1 → impl-2 → impl-1
→ Task relationships may be incorrect
```
## Performance Benefits
### Fast Generation
- **No File Writes**: Only reads JSON files
- **No Sync Logic**: No complex synchronization
- **Instant Results**: Generate views on demand
- **No Conflicts**: No state consistency issues
### Scalability
- **Large Task Sets**: Handles hundreds of tasks efficiently
- **Complex Hierarchies**: No performance degradation
- **Concurrent Access**: Multiple views can be generated simultaneously
## Integration
### Workflow Integration
- Use after task creation to see current state
- Use for debugging task relationships
### Command Integration
```bash
# Common workflow
/task:create "New feature"
/context # Check current state
/task:breakdown impl-1
/context --format=hierarchy # View new structure
/task:execute impl-1.1
```
## Output Formats
### Supported Formats
- `overview` (default): General workflow status
- `hierarchy`: Task relationships
- `tasks`: Simple task list
- `details`: Comprehensive information
### Custom Filtering
```bash
# Show only active tasks
/context --format=tasks --filter=active
# Show completed tasks only
/context --format=tasks --filter=completed
# Show tasks for specific agent
/context --format=tasks --agent=code-developer
```
## Related Commands
- `/task:create` - Create tasks (generates JSON data)
- `/task:execute` - Execute tasks (updates JSON data)
- `/task:breakdown` - Create subtasks (generates more JSON data)
- `/workflow:vibe` - Coordinate agents (uses context for coordination)
This context system provides instant, accurate views of workflow state without any synchronization complexity or performance overhead.

382
.claude/commands/task/breakdown.md
View File

@@ -33,21 +33,18 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic
- **Context Distribution**: Subtasks inherit parent context
- **Agent Mapping**: Automatic agent assignment per subtask
### Built-in Task Management
### Simplified Task Management
- **JSON Task Hierarchy**: Creates hierarchical JSON subtasks (impl-N.M.P)
- **TODO_LIST.md Integration**: Automatically updates progress display with new subtask structure
- **TODO_LIST.md Maintenance**: Updates task hierarchy display with parent-child relationships
- **Context Distribution**: Subtasks inherit and refine parent context
- **Progress Synchronization**: Updates hierarchical progress calculations in TODO_LIST.md
- **No External Commands**: All task operations are internal to this command
- **Context Distribution**: Subtasks inherit parent context
- **Basic Status Tracking**: Updates task relationships only
- **No Complex Synchronization**: Simple parent-child relationships
### Breakdown Rules
- Only `pending` tasks can be broken down
- Parent becomes container (not directly executable)
- Subtasks use hierarchical format: impl-N.M.P (e.g., IMPL-1.1.2)
- Subtasks use hierarchical format: impl-N.M.P (e.g., impl-1.1.2)
- Maximum depth: 3 levels (impl-N.M.P)
- Parent task progress = average of subtask progress
- Automatically updates TODO_LIST.md with hierarchical structure
- Parent-child relationships tracked in JSON only
## Usage
@@ -56,10 +53,9 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic
/task:breakdown IMPL-1
```
Interactive prompt with automatic task management:
Interactive prompt:
```
Task: Build authentication module
Workflow: 28 total tasks (Complex workflow detected)
Suggested subtasks:
1. Design authentication schema
@@ -67,40 +63,33 @@ Suggested subtasks:
3. Add JWT token handling
4. Write unit tests
Internal task processing:
✅ Level 2 hierarchy will be created (embedded logic)
Reason: >15 total tasks detected
Process: Automatic task hierarchy creation without external command calls
Accept task breakdown? (y/n/edit): y
```
### Auto Strategy with Override Options
### Auto Strategy
```bash
/task:breakdown IMPL-1 --strategy=auto
/task:breakdown IMPL-1 --force-level=2 # Force specific document level
/task:breakdown IMPL-1 --no-split # Disable automatic document splitting
/task:breakdown impl-1 --strategy=auto
```
Automatic generation:
```
✅ Task IMPL-1 broken down:
├── IMPL-1.1: Design authentication schema
├── IMPL-1.2: Implement core auth logic
├── IMPL-1.3: Add security middleware
└── IMPL-1.4: Write comprehensive tests
✅ Task impl-1 broken down:
├── impl-1.1: Design authentication schema
├── impl-1.2: Implement core auth logic
├── impl-1.3: Add security middleware
└── impl-1.4: Write comprehensive tests
Agents assigned:
- IMPL-1.1 → planning-agent
- IMPL-1.2 → code-developer
- IMPL-1.3 → code-developer
- IMPL-1.4 → test-agent
- impl-1.1 → planning-agent
- impl-1.2 → code-developer
- impl-1.3 → code-developer
- impl-1.4 → test-agent
📄 Internal task processing:
- JSON subtasks: IMPL-1.1, IMPL-1.2, IMPL-1.3, IMPL-1.4 created
- Task structure: Level 2 hierarchy established through embedded logic
- Progress tracking: TODO_LIST.md updated with hierarchical progress display
- Cross-references: All task links generated and validated internally
JSON files created:
- .task/impl-1.1.json
- .task/impl-1.2.json
- .task/impl-1.3.json
- .task/impl-1.4.json
```
## Decomposition Patterns
@@ -140,25 +129,30 @@ Parent context is intelligently distributed:
```json
{
"parent": {
"id": "IMPL-1",
"id": "impl-1",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT auth", "2FA support"],
"scope": ["src/auth/*"],
"acceptance": ["Authentication system works"]
"acceptance": ["Authentication system works"],
"inherited_from": "WFS-user-auth"
}
},
"subtasks": [
{
"id": "IMPL-1.1",
"id": "impl-1.1",
"title": "Design authentication schema",
"status": "pending",
"agent": "planning-agent",
"context": {
"inherited_from": "IMPL-1",
"requirements": ["JWT auth schema", "User model design"],
"scope": ["src/auth/models/*"],
"acceptance": ["Schema validates JWT tokens", "User model complete"]
"acceptance": ["Schema validates JWT tokens", "User model complete"],
"inherited_from": "impl-1"
},
"relations": {
"parent": "impl-1",
"subtasks": [],
"dependencies": []
}
}
]
@@ -184,283 +178,71 @@ Based on subtask type:
### Post-breakdown Actions
1. Update parent status to `container`
2. Create subtask JSON files with document references
3. Update IMPL_PLAN.md with enhanced task hierarchy structure
4. Create/update TODO_LIST.md with progress tracking
5. Update workflow session with document references
6. Validate phase alignment with IMPL_PLAN.md (if exists)
7. Generate execution plan with document coordination
2. Create subtask JSON files
3. Update parent task with subtask references
4. Update workflow session stats
## Execution Planning
## Simple File Management
After breakdown, generates execution order:
```
Execution Plan for IMPL-1:
Phase 1 (Parallel):
- IMPL-1.1: Design authentication schema
Phase 2 (Sequential):
- IMPL-1.2: Implement core auth logic
- IMPL-1.3: Add security middleware
Phase 3 (Parallel):
- IMPL-1.4: Write comprehensive tests
Dependencies resolved automatically
```
## Built-in Document Management
### Automatic File Structure Creation (Based on Workflow Scale)
#### Level 0: Unified Documents (<15 tasks)
### File Structure Created
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md (enhanced) # Updated with new task hierarchy
├── TODO_LIST.md # Updated with new progress entries
├── workflow-session.json # Session state
├── IMPL_PLAN.md # Static planning document
└── .task/
├── IMPL-1.json # Parent task (container)
├── IMPL-1.1.json # Subtask 1
└── IMPL-1.2.json # Subtask 2
├── impl-1.json # Parent task (container)
├── impl-1.1.json # Subtask 1
└── impl-1.2.json # Subtask 2
```
#### Level 1: Enhanced Structure (5-15 tasks)
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json
├── IMPL_PLAN.md # Combined planning document
├── TODO_LIST.md # Progress tracking (auto-generated)
├── .summaries/ # Task completion summaries
│ ├── IMPL-*.md # Main task summaries
│ └── IMPL-*.*.md # Subtask summaries
└── .task/
├── IMPL-*.json # Main task definitions
└── IMPL-*.*.json # Subtask definitions (up to 3 levels)
```
#### Level 2: Complete Structure (>15 tasks)
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json
├── IMPL_PLAN.md # Comprehensive planning document
├── TODO_LIST.md # Progress tracking and monitoring
├── .summaries/ # Task completion summaries
│ ├── IMPL-*.md # Main task summaries
│ ├── IMPL-*.*.md # Subtask summaries
│ └── IMPL-*.*.*.md # Detailed subtask summaries
└── .task/
├── IMPL-*.json # Task hierarchy (max 3 levels deep)
├── IMPL-*.*.json # Subtasks
└── IMPL-*.*.*.json # Detailed subtasks
```
### Built-in Document Creation Process
#### Level 0: Unified Document Updates (<15 tasks)
When task count is below threshold, command automatically updates unified documents:
- Updates existing IMPL_PLAN.md with enhanced task hierarchy structure
- Updates existing TODO_LIST.md with progress tracking
- Maintains TODO_LIST.md for progress coordination
#### Level 1: Task-Based Document Generation (15-50 tasks)
When enhanced complexity detected, command automatically:
**Updates IMPL_PLAN.md with task breakdown**:
- Adds hierarchical task structure with subtasks
- Updates requirements and acceptance criteria
- Maintains cross-references to JSON task files
- Preserves overall workflow context
**Creates/Updates TODO_LIST.md**:
- Displays hierarchical task structure with checkboxes
- Shows progress percentages and completion status
- Cross-references task details with JSON files
- Provides at-a-glance workflow progress overview
#### Level 2: Complete Structure Document Updates (>15 tasks)
When complex workflows detected, command automatically:
**Expands IMPL_PLAN.md with comprehensive planning**:
- Detailed task hierarchy with up to 3 levels deep
- Complete requirements analysis and acceptance criteria
- Risk assessment and mitigation strategies
- Cross-references to all JSON task files
**Maintains comprehensive TODO_LIST.md**:
- Full hierarchical display with progress rollups
- Multi-level task completion tracking
- Detailed progress percentages across task hierarchy
- Cross-references to .summaries/ for completed tasks
**Manages .summaries/ directory**:
- Creates task completion documentation structure
- Maintains audit trail of implementation decisions
- Links completed tasks back to workflow session
### JSON Task Management Integration
#### Task JSON Structure
```json
{
"id": "IMPL-1.1",
"title": "Design authentication schema",
"parent_id": "IMPL-1",
"status": "pending",
"type": "design",
"agent": "planning-agent",
"effort": "1h",
"context": {
"inherited_from": "IMPL-1",
"requirements": ["User model schema", "JWT token design"],
"scope": ["src/auth/models/*", "auth-schema.md"],
"acceptance": ["Schema validates JWT tokens", "User model complete"]
},
"hierarchy_context": {
"parent_task": "IMPL-1",
"level": 2,
"siblings": ["IMPL-1.2", "IMPL-1.3", "IMPL-1.4"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-1.2", "IMPL-1.3"]
},
"metadata": {
"created_by": "task:breakdown IMPL-1 --split-docs",
"document_sync": "2025-09-05T10:35:00Z",
"splitting_level": 2
}
}
```
#### TODO_LIST.md Integration
The task breakdown automatically updates TODO_LIST.md with:
- **Hierarchical Task Display**: Shows parent-child relationships using checkbox indentation
- **Progress Tracking**: Calculates completion percentages based on subtask status
- **JSON Cross-References**: Links to .task/ JSON files for detailed task information
- **Status Synchronization**: Keeps TODO_LIST.md checkboxes in sync with JSON task status
### Coordination with IMPL_PLAN.md
If IMPL_PLAN.md exists (complex workflows), task breakdown validates against phase structure:
```markdown
### Phase 1: Foundation
- **Tasks**: IMPL-1 → Now broken down to IMPL-1.1-4
- **Validation**: ✅ All subtasks align with phase objectives
- **Dependencies**: ✅ Phase dependencies preserved
```
## Advanced Options
### Depth Control
```bash
# Single level (default)
/task:breakdown IMPL-1 --depth=1
# Two levels (for complex tasks)
/task:breakdown IMPL-1 --depth=2
```
### Custom Breakdown
```bash
/task:breakdown IMPL-1 --custom
> Enter subtask 1: Custom subtask title
> Assign agent (auto/manual): auto
> Enter subtask 2: ...
```
## Task Validation & Error Handling
### Comprehensive Validation Checks
```bash
/task:breakdown impl-1 --validate
Pre-breakdown validation:
✅ workflow-session.json exists and is writable
✅ .task/ directory accessible
✅ Parent task JSON file valid
✅ Hierarchy depth within limits (max 3 levels)
⚠️ Complexity threshold reached - will generate TODO_LIST.md
Post-breakdown validation:
✅ All subtask JSON files created in .task/
✅ Parent-child relationships established
✅ Cross-references consistent across files
✅ TODO_LIST.md generated/updated (if triggered)
✅ workflow-session.json synchronized
✅ File structure matches complexity level
```
### Error Recovery & File Management
```bash
# JSON file conflicts
⚠️ Parent task JSON structure inconsistent with breakdown
→ Auto-sync parent JSON file? (y/n)
# Missing directory structure
❌ .task/ directory not found
→ Create required directory structure? (y/n)
# Complexity level mismatch
⚠️ Task count suggests Level 1 but structure is Level 0
→ 1. Upgrade structure 2. Keep minimal 3. Manual adjustment
# Hierarchy depth violation
❌ Attempting to create impl-1.2.3.4 (exceeds 3-level limit)
→ 1. Flatten hierarchy 2. Reorganize structure 3. Abort
```
## Integration
### Workflow Updates
- Updates task count in session
- Recalculates progress metrics
- Maintains task hierarchy in both JSON and documents
- Synchronizes document references across all files
### File System Integration
- **Real-time Sync**: JSON task files updated immediately during breakdown
- **Bidirectional Sync**: Maintains consistency between JSON, TODO_LIST.md, and session
- **Conflict Resolution**: JSON files are authoritative for task details and hierarchy
- **Version Control**: All task changes tracked in .task/ directory
- **Backup Recovery**: Can restore task hierarchy from workflow-session.json
- **Structure Validation**: Ensures compliance with progressive structure standards
### Next Actions
After breakdown:
- `/task:execute` - Run subtasks using JSON task context
- `/task:status` - View hierarchy from JSON files and TODO_LIST.md
- `/context` - Analyze task relationships and JSON structure
- `/task:replan` - Adjust breakdown and update task structure
### Output Files
- JSON subtask files in `.task/` directory
- Updated parent task JSON with subtask references
- Updated session stats in `workflow-session.json`
## Examples
### Complex Feature
### Simple Breakdown
```bash
/task:breakdown IMPL-1 --strategy=auto --depth=2
/task:breakdown impl-1
Result:
IMPL-1: E-commerce checkout
├── IMPL-1.1: Payment processing
│ ├── IMPL-1.1.1: Integrate payment gateway
│ ├── IMPL-1.1.2: Handle transactions
│ └── IMPL-1.1.3: Add error handling
├── IMPL-1.2: Order management
│ ├── IMPL-1.2.1: Create order model
│ └── IMPL-1.2.2: Implement order workflow
└── IMPL-1.3: Testing suite
impl-1: Build authentication (container)
├── impl-1.1: Design auth schema
├── impl-1.2: Implement auth logic
├── impl-1.3: Add security middleware
└── impl-1.4: Write tests
```
### Two-Level Breakdown
```bash
/task:breakdown impl-1 --depth=2
Result:
impl-1: E-commerce checkout (container)
├── impl-1.1: Payment processing
│ ├── impl-1.1.1: Integrate gateway
│ └── impl-1.1.2: Handle transactions
├── impl-1.2: Order management
│ └── impl-1.2.1: Create order model
└── impl-1.3: Testing
```
## Error Handling
```bash
# Task not found
❌ Task impl-5 not found
# Already broken down
⚠️ Task impl-1 already has subtasks
# Max depth exceeded
❌ Cannot create impl-1.2.3.4 (max 3 levels)
```
## Related Commands
- `/task:create` - Create new tasks
- `/task:context` - Manage task context
- `/task:execute` - Execute subtasks
- `/task:replan` - Adjust breakdown
- `/task:status` - View task hierarchy
- `/context` - View task hierarchy

289
.claude/commands/task/create.md
View File

@@ -68,234 +68,94 @@ Context inherited from workflow
- `test` - Test implementation
- `docs` - Documentation
### Priority Levels
### Priority Levels (Optional - moved to context)
- `low` - Can be deferred
- `normal` - Standard priority (default)
- `high` - Should be done soon
- `critical` - Must be done immediately
## Task Structure
**Note**: Priority is now stored in `context.priority` if needed, removed from top level for simplification.
## Simplified Task Structure
```json
{
"id": "impl-1",
"parent_id": null,
"title": "Build authentication module",
"type": "feature",
"priority": "normal",
"status": "pending",
"depth": 1,
"type": "feature",
"agent": "code-developer",
"effort": "4h",
"context": {
"inherited_from": "WFS-user-auth-system",
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
},
"dependencies": {
"upstream": [],
"downstream": [],
"parent_dependencies": []
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"relations": {
"parent": null,
"subtasks": [],
"dependencies": []
},
"execution": {
"attempts": 0,
"current_attempt": null,
"history": []
"last_attempt": null
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": null,
"completed_at": null,
"last_updated": "2025-09-05T10:30:00Z",
"version": "1.0"
"meta": {
"created": "2025-09-05T10:30:00Z",
"updated": "2025-09-05T10:30:00Z"
}
}
```
## Document Integration Features
## Simplified File Generation
### JSON Task File Generation
**File Location**: `.workflow/WFS-[topic-slug]/.task/impl-[N].json`
**Hierarchical Naming**: Follows impl-N.M.P format for nested tasks
**Schema Compliance**: All JSON files follow unified task schema from task-management-principles.md
### JSON Task File Only
**File Location**: `.task/impl-[N].json`
**Naming**: Follows impl-N.M.P format for nested tasks
**Content**: Contains all task data (no document coordination needed)
### Import from IMPL_PLAN.md
```bash
/task:create --from-plan
### No Document Synchronization
- Creates JSON task file only
- Updates workflow-session.json stats only
- No automatic TODO_LIST.md generation
- No complex cross-referencing needed
### View Generation On-Demand
- Use `/context` to generate views when needed
- No persistent markdown files created
- All data stored in JSON only
## Simplified Task Management
### Basic Task Statistics
- Task count tracked in workflow-session.json
- No automatic complexity escalation
- Manual workflow type selection during init
### Simple Creation Process
```
- Reads existing IMPL_PLAN.md implementation strategy
- Creates JSON task files based on planned structure
- Maintains hierarchical relationships in JSON format
- Preserves acceptance criteria from plan in task context
### Progressive Document Creation
Based on complexity analysis triggers:
#### Level 0 Structure (<5 tasks)
- Creates individual JSON task files in `.task/`
- No TODO_LIST.md generation (minimal overhead)
- Updates workflow-session.json with task references
#### Level 1 Structure (5-15 tasks)
- Creates hierarchical JSON task files (impl-N.M format)
- **Auto-generates TODO_LIST.md** when complexity threshold reached
- Creates `.summaries/` directory structure
- Enhanced cross-referencing between files
#### Level 2 Structure (>15 tasks)
- Creates complete hierarchical JSON files (impl-N.M.P format)
- Always maintains TODO_LIST.md with progress tracking
- Full `.summaries/` directory with detailed task documentation
- Comprehensive cross-references and validation
### Document Creation Triggers
TODO_LIST.md auto-generation conditions:
- **Task count > 5** OR **modules > 3** OR **estimated effort > 4h** OR **complex dependencies detected**
- **Always** for workflows with >15 tasks (Level 2 structure)
### Cross-Reference Management
- All JSON files contain proper parent_id relationships
- TODO_LIST.md links to individual JSON task files
- workflow-session.json maintains task list with hierarchy depth
- Automatic validation of cross-file references
## Dynamic Complexity Escalation (NEW FEATURE)
### Automatic Workflow Upgrade System
After each task creation, the system automatically evaluates current workflow complexity and upgrades structure when thresholds are exceeded.
### Escalation Process
```
1. Create New Task → Generate JSON file
2. Count All Tasks → Read all .task/*.json files
3. Calculate Metrics → Tasks, modules, dependencies, effort
4. Check Thresholds → Compare against complexity criteria
5. Trigger Upgrade → If threshold exceeded, escalate complexity
6. Generate Documents → Auto-create missing structure documents
7. Update Session → Record complexity change in workflow-session.json
8. Notify User → Inform about automatic upgrade
1. Create New Task → Generate JSON file only
2. Update Session Stats → Increment task count
3. Notify User → Confirm task created
```
### Escalation Triggers
#### Simple → Medium Escalation
**Triggered when ANY condition met:**
- Task count reaches 5 (primary trigger)
- Module count exceeds 3
- Total estimated effort > 4 hours
- Complex dependencies detected
- Cross-component changes required
**Actions taken:**
```bash
✅ Task created: impl-5
⚠️ Complexity threshold reached: 5 tasks (exceeds Simple limit)
🔄 Escalating workflow: Simple → Medium
Auto-generating enhanced structure:
✅ Created TODO_LIST.md with hierarchical task display
✅ Created .summaries/ directory for task completion tracking
✅ Updated workflow-session.json complexity level
✅ Enabled 2-level task hierarchy (impl-N.M)
Workflow now supports:
- Progress tracking via TODO_LIST.md
- Task decomposition up to 2 levels
- Summary generation for completed tasks
```
#### Medium → Complex Escalation
**Triggered when ANY condition met:**
- Task count reaches 15 (primary trigger)
- Module count exceeds 5
- Total estimated effort > 2 days
- Multi-repository impacts detected
- Architecture pattern changes required
**Actions taken:**
```bash
✅ Task created: impl-15
⚠️ Complexity threshold reached: 15 tasks (exceeds Medium limit)
🔄 Escalating workflow: Medium → Complex
Auto-generating comprehensive structure:
✅ Enhanced IMPL_PLAN.md with detailed phases and risk assessment
✅ Expanded TODO_LIST.md with progress monitoring
✅ Created comprehensive .summaries/ structure
✅ Updated workflow-session.json complexity level
✅ Enabled 3-level task hierarchy (impl-N.M.P maximum)
Workflow now supports:
- Comprehensive progress tracking and monitoring
- Full 3-level task decomposition
- Enhanced documentation and audit trails
- Advanced dependency management
```
### Complexity Calculation Algorithm
```javascript
function calculateComplexity(tasks, modules, effort, dependencies) {
// Primary thresholds (hard limits)
if (tasks >= 15 || modules > 5 || effort > 48) return 'complex';
if (tasks >= 5 || modules > 3 || effort > 4) return 'medium';
// Override factors (can force higher complexity)
if (dependencies.includes('multi-repo') ||
dependencies.includes('architecture-change')) return 'complex';
if (dependencies.includes('cross-component') ||
dependencies.includes('complex-integration')) return 'medium';
return 'simple';
}
```
### Session State Updates During Escalation
```json
{
"complexity": "medium",
"escalation_history": [
{
"from": "simple",
"to": "medium",
"triggered_at": "2025-09-07T16:45:00Z",
"trigger_reason": "task_count_threshold",
"task_count_at_escalation": 5,
"auto_generated_documents": ["TODO_LIST.md", ".summaries/"],
"task_hierarchy_enabled": 2
}
],
"task_system": {
"max_depth": 2,
"structure_level": "enhanced",
"documents_generated": ["TODO_LIST.md"],
"auto_escalation_enabled": true
}
}
```
### Benefits of Dynamic Escalation
- **Seamless Growth**: Workflows grow naturally without user intervention
- **No Overhead for Simple Tasks**: Simple workflows remain minimal
- **Automatic Structure**: Enhanced documentation appears when needed
- **Progressive Enhancement**: Users get appropriate tooling for current complexity
- **Transparent Process**: All escalations logged and reversible
### Benefits of Simplification
- **No Overhead**: Just create tasks, no complex logic
- **Predictable**: Same process every time
- **Fast**: Minimal processing needed
- **Clear**: User controls complexity level
## Context Inheritance
Tasks automatically inherit:
1. **Requirements** - From workflow-session.json context and IMPL_PLAN.md
2. **Scope** - File patterns from workflow and IMPL_PLAN.md strategy
3. **Standards** - Quality standards from workflow session
4. **Dependencies** - Related tasks from existing JSON task hierarchy in `.task/`
5. **Parent Context** - When created as subtasks, inherit from parent JSON file
6. **Session Context** - Global workflow context from active session
1. **Requirements** - From workflow-session.json and IMPL_PLAN.md
2. **Scope** - File patterns from workflow context
3. **Parent Context** - When created as subtasks, inherit from parent
4. **Session Context** - Global workflow context from active session
## Smart Suggestions
@@ -358,46 +218,29 @@ Created 3 tasks:
- impl-3: Write authentication tests
```
## File Output Management
## File Output
### JSON Task Files
**Output Location**: `.workflow/WFS-[topic-slug]/.task/impl-[id].json`
**Schema**: Follows unified task JSON schema with hierarchical support
**Contents**: Complete task definition including context, dependencies, and metadata
### JSON Task File
**Location**: `.task/impl-[id].json`
**Schema**: Simplified task JSON schema
**Contents**: Complete task definition with context
### TODO_LIST.md Generation
**Trigger Logic**: Auto-created based on complexity thresholds
**Location**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
**Format**: Hierarchical task display with checkboxes and progress tracking
### Summary Directory Structure
**Location**: `.workflow/WFS-[topic-slug]/.summaries/`
**Purpose**: Ready for task completion summaries
**Structure**: Created when Level 1+ complexity detected
### Workflow Session Updates
**File**: `.workflow/WFS-[topic-slug]/workflow-session.json`
**Updates**: Task list, counters, progress calculations, hierarchy depth
### Session Updates
**File**: `workflow-session.json`
**Updates**: Basic task count and active task list only
## Integration
### Workflow Integration
- Updates workflow-session.json with new task references
- Increments task counter and updates complexity assessment
- Updates IMPLEMENT phase progress and task hierarchy depth
- Maintains bidirectional sync with TodoWrite tool
### File System Coordination
- Validates and creates required directory structure
- Maintains cross-references between all generated files
- Ensures proper naming conventions and hierarchy limits
- Provides rollback capability for failed operations
### Simple Integration
- Updates workflow-session.json stats
- Creates JSON task file
- No complex file coordination needed
### Next Steps
After creation, use:
- `/task:breakdown` - Split into hierarchical subtasks with JSON files
- `/task:execute` - Run the task with summary generation
- `/context` - View task details, status and relationships
- `/task:breakdown` - Split into subtasks
- `/task:execute` - Run the task
- `/context` - View task details and status
## Examples

54
.claude/commands/task/execute.md
View File

@@ -135,39 +135,38 @@ END FUNCTION
- **Conditional Execution (`--if="..."`)**: Proceeds with execution only if a specified condition (e.g., `"tests-pass"`) is met.
- **Rollback (`--rollback`)**: Reverts file modifications and restores the previous task state.
### 📄 **Standard Context Structure (JSON)**
### 📄 **Simplified Context Structure (JSON)**
This is the standard data structure loaded to provide context for task execution.
This is the simplified data structure loaded to provide context for task execution.
```json
{
"task": {
"id": "IMPL-001",
"id": "impl-1",
"title": "Build authentication module",
"type": "feature",
"status": "active",
"agent": "code-developer",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"]
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
}
},
"workflow": {
"session": "WFS-[topic-slug]",
"phase": "IMPLEMENT",
"global_context": ["Security first", "Backward compatible"]
"session": "WFS-user-auth",
"phase": "IMPLEMENT"
},
"execution": {
"agent": "code-developer",
"mode": "auto",
"checkpoints": ["setup", "implement", "test", "validate"],
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"completed_checkpoints": ["setup"]
}
"attempts": 0
}
}
```
@@ -180,37 +179,28 @@ Different agents receive context tailored to their function:
- **`test-agent`**: Test requirements, code to be tested, coverage goals.
- **`review-agent`**: Quality standards, style guides, review criteria.
### 🗃️ **File Output & System Integration**
### 🗃️ **Simplified File Output**
- **Task JSON File (`.task/<task-id>.json`)**: The authoritative source. Updated with status, execution history, and metadata.
- **TODO List (`TODO_LIST.md`)**: The task's checkbox is updated, progress is recalculated, and links to the summary file are added.
- **Session File (`workflow-session.json`)**: Task completion status and overall phase progress are updated.
- **Summary File**: Generated in `.workflow/WFS-[...]/summaries/` upon successful completion.
- **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
- **Session File (`workflow-session.json`)**: Updated task stats (completed count).
- **Summary File**: Generated in `.summaries/` upon completion (optional).
### 📝 **Summary File Template**
### 📝 **Simplified Summary Template**
A summary file is generated at `.workflow/WFS-[topic-slug]/.summaries/IMPL-[task-id]-summary.md`.
Optional summary file generated at `.summaries/impl-[task-id]-summary.md`.
```markdown
# Task Summary: IMPL-001 Build Authentication Module
# Task Summary: impl-1 Build Authentication Module
## What Was Done
- Created src/auth/login.ts with JWT validation
- Modified src/auth/validate.ts for enhanced security
- Added comprehensive tests in tests/auth.test.ts
- Added tests in tests/auth.test.ts
## Execution Results
- **Duration**: 23 minutes
- **Agent**: code-developer
- **Tests Passed**: 12/12 (100%)
- **Coverage**: 87%
- **Status**: completed
## Files Modified
- `src/auth/login.ts` (created)
- `src/auth/validate.ts` (modified)
- `tests/auth.test.ts` (created)
## Links
- [🔙 Back to Task List](../TODO_LIST.md#impl-001)
- [📌 Task Details](../.task/impl-001.json)
```

848
.claude/commands/task/replan.md
View File

@@ -1,466 +1,518 @@
---
name: task-replan
description: Dynamically replan tasks based on changes, blockers, or new requirements
usage: /task:replan [task-id|--all] [--reason=<reason>] [--strategy=<adjust|rebuild>]
argument-hint: [task-id or --all] [optional: reason and strategy]
description: Replan individual tasks with detailed user input and change tracking
usage: /task:replan <task-id> [input-source]
argument-hint: task-id [text|--from-file|--from-issue|--detailed|--interactive]
examples:
- /task:replan IMPL-001 --reason="requirements changed"
- /task:replan --all --reason="new security requirements"
- /task:replan IMPL-003 --strategy=rebuild
- /task:replan impl-1 "Add OAuth2 authentication support"
- /task:replan impl-1 --from-file updated-specs.md
- /task:replan impl-1 --from-issue ISS-001
- /task:replan impl-1 --detailed
- /task:replan impl-1 --interactive
---
# Task Replan Command (/task:replan)
## Overview
Dynamically adjusts task planning based on changes, new requirements, blockers, or execution results.
Replans individual tasks based on detailed user input with comprehensive change tracking, version management, and document synchronization. Focuses exclusively on single-task modifications with rich input options.
## Core Principles
**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
**Task Management:** @~/.claude/workflows/task-management-principles.md
## Single-Task Focus
This command operates on **individual tasks only**. For workflow-wide changes, use `/workflow:action-plan` instead.
## Replan Triggers
⚠️ **CRITICAL**: Before replanning, checks for existing active session to avoid conflicts.
⚠️ **CRITICAL**: Before replanning, MUST check for existing active session to avoid creating duplicate sessions.
## Input Sources for Replanning
### Session Check Process
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
2. **Session Validation**: Use existing active session containing the task to be replanned
3. **Context Integration**: Load existing session state and task hierarchy
### Automatic Detection
System detects replanning needs from file monitoring:
- Requirements changed in workflow-session.json
- Dependencies blocked in JSON task hierarchy
- Task failed execution (logged in JSON execution history)
- New issues discovered and associated with tasks
- Scope modified in task context or IMPL_PLAN.md
- File structure complexity changes requiring reorganization
### Manual Triggers
### Direct Text Input (Default)
```bash
/task:replan IMPL-001 --reason="API spec updated"
/task:replan impl-1 "Add OAuth2 authentication support"
```
**Processing**:
- Parse specific changes and requirements
- Extract new features or modifications needed
- Apply directly to target task structure
### File-based Requirements
```bash
/task:replan impl-1 --from-file updated-specs.md
/task:replan impl-1 --from-file requirements-change.txt
```
**Supported formats**: .md, .txt, .json, .yaml
**Processing**:
- Read detailed requirement changes from file
- Parse structured specifications and updates
- Apply file content to task replanning
### Issue-based Replanning
```bash
/task:replan impl-1 --from-issue ISS-001
/task:replan impl-1 --from-issue "bug-report"
```
**Processing**:
- Load issue description and requirements
- Extract necessary changes for task
- Apply issue resolution to task structure
### Detailed Mode
```bash
/task:replan impl-1 --detailed
```
**Guided Input**:
1. **New Requirements**: What needs to be added/changed?
2. **Scope Changes**: Expand/reduce task scope?
3. **Subtask Modifications**: Add/remove/modify subtasks?
4. **Dependencies**: Update task relationships?
5. **Success Criteria**: Modify completion conditions?
6. **Agent Assignment**: Change assigned agent?
### Interactive Mode
```bash
/task:replan impl-1 --interactive
```
**Step-by-Step Process**:
1. **Current Analysis**: Review existing task structure
2. **Change Identification**: What needs modification?
3. **Impact Assessment**: How changes affect task?
4. **Structure Updates**: Add/modify subtasks
5. **Validation**: Confirm changes before applying
## Replanning Flow with Change Tracking
### 1. Task Loading & Validation
```
Load Task → Read current task JSON file
Validate → Check task exists and can be modified
Session Check → Verify active workflow session
```
## Replan Strategies
### 1. Adjust Strategy (Default)
Minimal changes to existing plan:
```bash
/task:replan IMPL-001 --strategy=adjust
Adjustments for IMPL-001:
- Updated requirements
- Modified subtask IMPL-001.2
- Added validation step
- Kept 80% of original plan
### 2. Input Processing
```
Detect Input Type → Identify source type
Extract Requirements → Parse change requirements
Analyze Impact → Determine modifications needed
```
### 2. Rebuild Strategy
Complete replanning from scratch:
```bash
/task:replan IMPL-001 --strategy=rebuild
Rebuilding IMPL-001:
- Analyzing new requirements
- Generating new breakdown
- Reassigning agents
- New execution plan created
### 3. Version Management
```
Create Version → Backup current task state
Update Version → Increment task version number
Archive → Store previous version in versions/
```
## Usage Scenarios
### Scenario 1: Requirements Change
```bash
/task:replan IMPL-001 --reason="Added OAuth2 requirement"
Analyzing impact...
Current plan:
- IMPL-001.1: Basic login ✅ Complete
- IMPL-001.2: Session management (in progress)
- IMPL-001.3: Tests
Recommended changes:
+ Add IMPL-001.4: OAuth2 integration
~ Modify IMPL-001.2: Include OAuth session
~ Update IMPL-001.3: Add OAuth tests
Apply changes? (y/n): y
✅ Task replanned successfully
### 4. Task Structure Updates
```
Modify Task → Update task JSON structure
Update Subtasks → Add/remove/modify as needed
Update Relations → Fix dependencies and hierarchy
Update Context → Modify requirements and scope
```
### Scenario 2: Blocked Task
```bash
/task:replan IMPL-003 --reason="API not ready"
Task blocked analysis:
- IMPL-003 depends on external API
- API delayed by 2 days
- 3 tasks depend on IMPL-003
Replan options:
1. Defer IMPL-003 and dependents
2. Create mock API for development
3. Reorder to work on independent tasks
Select option: 2
Creating new plan:
+ IMPL-003.0: Create API mock
~ IMPL-003.1: Use mock for development
~ Add note: Replace mock when API ready
### 5. Document Synchronization
```
Update IMPL_PLAN → Regenerate task section
Update TODO_LIST → Sync task hierarchy (if exists)
Update Session → Reflect changes in workflow state
```
### Scenario 3: Failed Execution
```bash
/task:replan IMPL-002 --reason="execution failed"
Failure analysis:
- Failed at: Testing phase
- Reason: Performance issues
- Impact: Blocks 2 downstream tasks
Replan approach:
1. Break down into smaller tasks
2. Add performance optimization task
3. Adjust testing approach
New structure:
IMPL-002 (failed) →
├── IMPL-002.1: Core functionality (smaller scope)
├── IMPL-002.2: Performance optimization
├── IMPL-002.3: Load testing
└── IMPL-002.4: Integration
✅ Replanned with focus on incremental delivery
### 6. Change Documentation
```
Create Change Log → Document all modifications
Generate Summary → Create replan report
Update History → Add to task replan history
```
## Global Replanning
## Version Management (Simplified)
### Replan All Tasks
```bash
/task:replan --all --reason="Architecture change"
Global replan analysis:
- Total tasks: 8
- Completed: 3 (keep as-is)
- In progress: 2 (need adjustment)
- Pending: 3 (full replan)
Changes summary:
- 2 tasks modified
- 1 task removed (no longer needed)
- 2 new tasks added
- Dependencies reordered
Preview changes? (y/n): y
[Detailed change list]
Apply all changes? (y/n): y
✅ All tasks replanned
```
## Impact Analysis
### Before Replanning
```bash
/task:replan IMPL-001 --preview
Impact Preview:
If IMPL-001 is replanned:
- Affected tasks: 4
- Timeline impact: +1 day
- Resource changes: Need planning-agent
- Risk level: Medium
Dependencies affected:
- IMPL-003: Will need adjustment
- IMPL-004: Delay expected
- IMPL-005: No impact
Continue? (y/n):
```
## Replan Operations
### Add Subtasks
```bash
/task:replan IMPL-001 --add-subtask
Current subtasks:
1. IMPL-001.1: Design
2. IMPL-001.2: Implement
Add new subtask:
Title: Add security layer
Position: After IMPL-001.2
Agent: code-developer
✅ Added IMPL-001.3: Add security layer
```
### Remove Subtasks
```bash
/task:replan IMPL-001 --remove-subtask=IMPL-001.3
⚠️ Remove IMPL-001.3?
This will:
- Delete subtask and its context
- Update parent progress
- Adjust dependencies
Confirm? (y/n): y
✅ Subtask removed
```
### Reorder Tasks
```bash
/task:replan --reorder
Current order:
1. IMPL-001: Auth
2. IMPL-002: Database
3. IMPL-003: API
Suggested reorder (based on dependencies):
1. IMPL-002: Database
2. IMPL-001: Auth
3. IMPL-003: API
Apply reorder? (y/n): y
✅ Tasks reordered
```
## Smart Recommendations
### AI-Powered Suggestions
```bash
/task:replan IMPL-001 --suggest
Analysis complete. Suggestions:
1. 🔄 Split IMPL-001.2 (too complex)
2. ⏱️ Reduce scope to meet deadline
3. 🤝 Parallelize IMPL-001.1 and IMPL-001.3
4. 📝 Add documentation task
5. 🧪 Increase test coverage requirement
Apply suggestion: 1
Splitting IMPL-001.2:
→ IMPL-001.2.1: Core implementation
→ IMPL-001.2.2: Error handling
→ IMPL-001.2.3: Optimization
✅ Applied successfully
```
## Version Control & File Management
### JSON Task Version History
**File-Based Versioning**: Each replan creates version history in JSON metadata
```bash
/task:replan impl-001 --history
Plan versions for impl-001 (from JSON file):
v3 (current): 4 subtasks, 2 complete - JSON files: impl-001.1.json to impl-001.4.json
v2: 3 subtasks (archived) - Backup: .task/archive/impl-001-v2-backup.json
v1: 2 subtasks (initial) - Backup: .task/archive/impl-001-v1-backup.json
Version files available:
- Current: .task/impl-001.json
- Backups: .task/archive/impl-001-v[N]-backup.json
- Change log: .summaries/replan-history-impl-001.md
Rollback to version: 2
⚠️ This will:
- Restore JSON files from backup
- Regenerate TODO_LIST.md structure
- Update workflow-session.json
- Archive current version
Continue? (y/n):
```
### Replan Documentation Generation
**Change Tracking Files**: Auto-generated documentation of all changes
```bash
# Generates: .summaries/replan-[task-id]-[timestamp].md
/task:replan impl-001 --reason="API changes" --document
Creating replan documentation...
📝 Replan Report: impl-001
Generated: 2025-09-07 16:00:00
Reason: API changes
Version: v2 → v3
## Changes Made
- Added subtask impl-001.4: Handle new API endpoints
- Modified impl-001.2: Updated authentication flow
- Removed impl-001.3: No longer needed due to API changes
## File Changes
- Created: .task/impl-001.4.json
- Modified: .task/impl-001.2.json
- Archived: .task/impl-001.3.json → .task/archive/
- Updated: TODO_LIST.md hierarchy
- Updated: workflow-session.json task count
## Impact Analysis
- Timeline: +2 days (new subtask)
- Dependencies: impl-002 now depends on impl-001.4
- Resources: Need API specialist for impl-001.4
Report saved: .summaries/replan-impl-001-20250907-160000.md
```
### Enhanced JSON Change Tracking
**Complete Replan History**: All changes documented in JSON files and reports
### Version Tracking
Each replan creates a new version with complete history:
```json
{
"task_id": "impl-001",
"id": "impl-1",
"title": "Build authentication module",
"status": "active",
"version": "1.2",
"replan_history": [
{
"version": "1.2",
"timestamp": "2025-09-07T16:00:00Z",
"reason": "API changes",
"changes_summary": "Added API endpoint handling, removed deprecated auth flow",
"backup_location": ".task/archive/impl-001-v1.1-backup.json",
"documentation": ".summaries/replan-impl-001-20250907-160000.md",
"files_affected": [
{
"action": "created",
"file": ".task/impl-001.4.json",
"description": "New API endpoint handling subtask"
"version": "1.1",
"date": "2025-09-08T10:00:00Z",
"reason": "Original plan",
"input_source": "initial_creation"
},
{
"action": "modified",
"file": ".task/impl-001.2.json",
"description": "Updated authentication flow"
},
{
"action": "archived",
"file": ".task/impl-001.3.json",
"location": ".task/archive/impl-001.3-deprecated.json"
}
],
"todo_list_regenerated": true,
"session_updated": true
}
],
"subtasks": ["impl-001.1", "impl-001.2", "impl-001.4"],
"metadata": {
"version": "1.2",
"last_updated": "2025-09-07T16:00:00Z",
"last_replan": "2025-09-07T16:00:00Z",
"replan_count": 2
"date": "2025-09-08T14:00:00Z",
"reason": "Add OAuth2 authentication support",
"input_source": "direct_text",
"changes": [
"Added subtask impl-1.3: OAuth2 integration",
"Added subtask impl-1.4: Token management",
"Modified scope to include external auth"
],
"backup_location": ".task/versions/impl-1-v1.1.json"
}
],
"context": {
"requirements": ["Basic auth", "Session mgmt", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["All auth methods work"]
}
}
```
## File System Integration
### Comprehensive File Updates
**Multi-File Synchronization**: Ensures consistency across all workflow files
#### JSON Task File Management
- **Version Backups**: Automatic backup before major changes
- **Hierarchical Updates**: Cascading changes through parent-child relationships
- **Archive Management**: Deprecated task files moved to `.task/archive/`
- **Metadata Tracking**: Complete change history in JSON metadata
#### TODO_LIST.md Regeneration
**Smart Regeneration**: Updates based on structural changes
```bash
/task:replan impl-001 --regenerate-todo
Analyzing structural changes from replan...
Current TODO_LIST.md: 8 tasks displayed
New task structure: 9 tasks (1 added, 1 removed, 2 modified)
Regenerating TODO_LIST.md...
✅ Updated task hierarchy display
✅ Recalculated progress percentages
✅ Updated cross-references to JSON files
✅ Added links to new summary files
TODO_LIST.md updated with new structure
### File Structure After Replan
```
.task/
├── impl-1.json # Current version (1.2)
├── impl-1.3.json # New subtask
├── impl-1.4.json # New subtask
├── versions/
│ └── impl-1-v1.1.json # Previous version backup
└── summaries/
└── replan-impl-1-20250908.md # Change log
```
#### Workflow Session Updates
- **Task Count Updates**: Reflect additions/removals in session
- **Progress Recalculation**: Update completion percentages
- **Complexity Assessment**: Re-evaluate structure level if needed
- **Dependency Validation**: Check all task dependencies remain valid
## IMPL_PLAN.md Updates
### Documentation Generation
**Automatic Report Creation**: Every replan generates documentation
### Automatic Plan Regeneration
When task is replanned, the corresponding section in IMPL_PLAN.md is updated:
- **Replan Report**: `.summaries/replan-[task-id]-[timestamp].md`
- **Change Summary**: Detailed before/after comparison
- **Impact Analysis**: Effects on timeline, dependencies, resources
- **File Change Log**: Complete list of affected files
- **Rollback Instructions**: How to revert changes if needed
**Before Replan**:
```markdown
## Task Breakdown
- **IMPL-001**: Build authentication module
- Basic login functionality
- Session management
- Password reset
```
### Issue Integration
**After Replan**:
```markdown
## Task Breakdown
- **IMPL-001**: Build authentication module (v1.2)
- Basic login functionality
- Session management
- OAuth2 integration (added)
- Token management (added)
- Password reset
*Last updated: 2025-09-08 14:00 via task:replan*
```
### Plan Update Process
1. **Locate Task Section**: Find task in IMPL_PLAN.md by ID
2. **Update Description**: Modify task title if changed
3. **Update Subtasks**: Add/remove bullet points for subtasks
4. **Add Version Info**: Include version number and update timestamp
5. **Preserve Context**: Keep surrounding plan structure intact
## TODO_LIST.md Synchronization
### Automatic TODO List Updates
If TODO_LIST.md exists in workflow, synchronize task changes:
**Before Replan**:
```markdown
## Implementation Tasks
- [ ] impl-1: Build authentication module
- [x] impl-1.1: Design schema
- [ ] impl-1.2: Implement logic
```
**After Replan**:
```markdown
## Implementation Tasks
- [ ] impl-1: Build authentication module (updated v1.2)
- [x] impl-1.1: Design schema
- [ ] impl-1.2: Implement logic
- [ ] impl-1.3: OAuth2 integration (new)
- [ ] impl-1.4: Token management (new)
```
### TODO Update Rules
- **Preserve Status**: Keep existing checkbox states [x] or [ ]
- **Add New Items**: New subtasks get [ ] checkbox
- **Mark Changes**: Add (updated), (new), (modified) indicators
- **Remove Items**: Delete subtasks that were removed
- **Update Hierarchy**: Maintain proper indentation structure
## Change Documentation
### Comprehensive Change Log
Every replan generates detailed documentation:
```markdown
# Task Replan Log: impl-1
*Date: 2025-09-08T14:00:00Z*
*Version: 1.1 → 1.2*
*Input: Direct text - "Add OAuth2 authentication support"*
## Changes Applied
### Task Structure Updates
- **Added Subtasks**:
- impl-1.3: OAuth2 provider integration
- impl-1.4: Token management system
- **Modified Subtasks**:
- impl-1.2: Updated to include OAuth flow integration
- **Removed Subtasks**: None
### Context Modifications
- **Requirements**: Added OAuth2 external authentication
- **Scope**: Expanded to include third-party auth integration
- **Acceptance**: Include OAuth2 token validation
- **Dependencies**: No changes
### File System Updates
- **Updated**: .task/impl-1.json (version 1.2)
- **Created**: .task/impl-1.3.json, .task/impl-1.4.json
- **Backed Up**: .task/versions/impl-1-v1.1.json
- **Updated**: IMPL_PLAN.md (task section regenerated)
- **Updated**: TODO_LIST.md (2 new items added)
## Impact Analysis
- **Timeline**: +2 days for OAuth implementation
- **Complexity**: Increased (simple → medium)
- **Agent**: Remains code-developer, may need OAuth expertise
- **Dependencies**: Task impl-2 may need OAuth context
## Related Tasks Affected
- impl-2: May need OAuth integration context
- impl-5: Authentication dependency updated
## Rollback Information
- **Previous Version**: 1.1
- **Backup Location**: .task/versions/impl-1-v1.1.json
- **Rollback Command**: `/task:replan impl-1 --rollback v1.1`
```
## Session State Updates
### Workflow Integration
After task replanning, update session information:
```json
{
"phases": {
"IMPLEMENT": {
"tasks": ["impl-1", "impl-2", "impl-3"],
"completed_tasks": [],
"modified_tasks": {
"impl-1": {
"version": "1.2",
"last_replan": "2025-09-08T14:00:00Z",
"reason": "OAuth2 integration added"
}
},
"task_count": {
"total": 6,
"added_today": 2
}
}
},
"documents": {
"IMPL_PLAN.md": {
"last_updated": "2025-09-08T14:00:00Z",
"updated_sections": ["IMPL-001"]
},
"TODO_LIST.md": {
"last_updated": "2025-09-08T14:00:00Z",
"items_added": 2
}
}
}
```
## Rollback Support (Simple)
### Basic Version Rollback
```bash
/task:replan IMPL-001 --from-issue=ISS-001
/task:replan impl-1 --rollback v1.1
Rollback Analysis:
Current Version: 1.2
Target Version: 1.1
Changes to Revert:
- Remove subtasks: impl-1.3, impl-1.4
- Restore previous context
- Update IMPL_PLAN.md section
- Update TODO_LIST.md structure
Files Affected:
- Restore: .task/impl-1.json from backup
- Remove: .task/impl-1.3.json, .task/impl-1.4.json
- Update: IMPL_PLAN.md, TODO_LIST.md
Confirm rollback? (y/n): y
Rolling back...
✅ Task impl-1 rolled back to version 1.1
✅ Documents updated
✅ Change log created
```
## Practical Examples
### Example 1: Add Feature with Full Tracking
```bash
/task:replan impl-1 "Add two-factor authentication"
Loading task impl-1 (current version: 1.2)...
Processing request: "Add two-factor authentication"
Analyzing required changes...
Proposed Changes:
+ Add impl-1.5: Two-factor setup
+ Add impl-1.6: 2FA validation
~ Modify impl-1.2: Include 2FA in auth flow
Apply changes? (y/n): y
Executing replan...
✓ Version 1.3 created
✓ Added 2 new subtasks
✓ Modified 1 existing subtask
✓ IMPL_PLAN.md updated
✓ TODO_LIST.md synchronized
✓ Change log saved
Result:
- Task version: 1.2 → 1.3
- Subtasks: 4 → 6
- Documents updated: 2
- Backup: .task/versions/impl-1-v1.2.json
```
### Example 2: Issue-based Replanning
```bash
/task:replan impl-2 --from-issue ISS-001
Loading issue ISS-001...
Issue: "Login timeout too short"
Type: Bug
Issue: "Database queries too slow - need caching"
Priority: High
Suggested replan:
+ Add IMPL-001.4: Fix login timeout
~ Adjust IMPL-001.3: Include timeout tests
Applying to task impl-2...
Apply? (y/n): y
Required changes for performance fix:
+ Add impl-2.4: Implement Redis caching
+ Add impl-2.5: Query optimization
~ Modify impl-2.1: Add cache checks
Documents updating:
✓ Task JSON updated (v1.0 → v1.1)
✓ IMPL_PLAN.md section regenerated
✓ TODO_LIST.md: 2 new items added
✓ Issue ISS-001 linked to task
Summary:
Performance improvements added to impl-2
Timeline impact: +1 day for caching setup
```
### Example 3: Interactive Replanning
```bash
/task:replan impl-3 --interactive
Interactive Replan for impl-3: API integration
Current version: 1.0
1. What needs to change? "API spec updated, need webhook support"
2. Add new requirements? "Webhook handling, signature validation"
3. Add subtasks? "y"
- New subtask 1: "Webhook receiver endpoint"
- New subtask 2: "Signature validation"
- Add more? "n"
4. Modify existing subtasks? "n"
5. Update dependencies? "Now depends on impl-1 (auth for webhooks)"
6. Change agent assignment? "n"
Applying interactive changes...
✓ Added 2 subtasks for webhook functionality
✓ Updated dependencies
✓ Context expanded for webhook requirements
✓ Version 1.1 created
✓ All documents synchronized
Interactive replan complete!
```
## Error Handling
### Input Validation Errors
```bash
# Cannot replan completed task
❌ Task IMPL-001 is completed
→ Create new task instead
# Task not found
❌ Task impl-5 not found in current session
→ Check task ID with /context
# No reason provided
⚠️ Please provide reason for replanning
→ Use --reason="explanation"
# No input provided
❌ Please specify changes needed for replanning
→ Use descriptive text or --detailed/--interactive
# Conflicts detected
⚠️ Replan conflicts with IMPL-002
→ Resolve with --force or adjust plan
# Task completed
⚠️ Task impl-1 is completed (cannot replan)
→ Create new task for additional work
# File not found
❌ File updated-specs.md not found
→ Check file path and try again
```
## File Output Summary
### Document Update Issues
```bash
# Missing IMPL_PLAN.md
⚠️ IMPL_PLAN.md not found in workflow
→ Task update proceeding, plan regeneration skipped
### Generated Files
- **Backup Files**: `.task/archive/[task-id]-v[N]-backup.json`
- **Replan Reports**: `.summaries/replan-[task-id]-[timestamp].md`
- **Change Logs**: Embedded in JSON task file metadata
- **Updated TODO_LIST.md**: Reflects new task structure
- **Archive Directory**: `.task/archive/` for deprecated files
# TODO_LIST.md not writable
⚠️ Cannot update TODO_LIST.md (permissions)
→ Task updated, manual TODO sync needed
### File System Maintenance
- **Automatic Cleanup**: Archive old versions after 30 days
- **Integrity Validation**: Ensure all references remain valid after changes
- **Rollback Support**: Complete restoration capability from backups
- **Cross-Reference Updates**: Maintain links between all workflow files
# Session conflict
⚠️ Task impl-1 being modified in another session
→ Complete other operation first
```
## Integration Points
### Command Workflow
```bash
# 1. Replan task with new requirements
/task:replan impl-1 "Add advanced security features"
# 2. View updated task structure
/context impl-1
→ Shows new version with changes
# 3. Check updated planning documents
cat IMPL_PLAN.md
→ Task section shows v1.3 with new features
# 4. Verify TODO list synchronization
cat TODO_LIST.md
→ New subtasks appear with [ ] checkboxes
# 5. Execute replanned task
/task:execute impl-1
→ Works with updated task structure
```
### Session Integration
- **Task Count Updates**: Reflect additions/removals in session stats
- **Document Sync**: Keep IMPL_PLAN.md and TODO_LIST.md current
- **Version Tracking**: Complete audit trail in task JSON
- **Change Traceability**: Link replans to input sources
## Related Commands
- `/task:breakdown` - Initial task breakdown with JSON file creation
- `/context` - Analyze current state from file system
- `/context` - View task structure and version history
- `/task:execute` - Execute replanned tasks with new structure
- `/context` - View updated task structure and relationships
- `/workflow:replan` - Replan entire workflow with session updates
- `/workflow:action-plan` - For workflow-wide replanning
- `/task:create` - Create new tasks for additional work
---
**System ensures**: Focused single-task replanning with comprehensive change tracking, document synchronization, and complete audit trail

804
.claude/commands/workflow/action-plan.md
View File

@@ -1,504 +1,386 @@
---
name: workflow-action-plan
description: Action planning phase that integrates brainstorming insights or user input to create executable implementation plans
usage: /workflow:action-plan [--from-brainstorming] [--skip-brainstorming] [--replan] [--trigger=<reason>]
argument-hint: [optional: from brainstorming, skip brainstorming, replan mode, or replan trigger]
description: Create implementation plans from various input sources
usage: /workflow:action-plan [input-source] [--complexity=<simple|decompose>]
argument-hint: [text|--from-file|--from-issue|--template|--interactive|--from-brainstorming] [optional: complexity]
examples:
- /workflow:action-plan "Build authentication system"
- /workflow:action-plan --from-file requirements.md
- /workflow:action-plan --from-issue ISS-001
- /workflow:action-plan --template web-api
- /workflow:action-plan --interactive
- /workflow:action-plan --from-brainstorming
- /workflow:action-plan --skip-brainstorming "implement OAuth authentication"
- /workflow:action-plan --replan --trigger=requirement-change
- /workflow:action-plan --from-brainstorming --scope=all --strategy=minimal-disruption
---
# Workflow Action Plan Command (/workflow:action-plan)
## Overview
Creates actionable implementation plans based on brainstorming insights or direct user input. Establishes project structure, understands existing workflow context, and generates executable plans with proper task decomposition and resource allocation.
Creates actionable implementation plans from multiple input sources including direct text, files, issues, templates, interactive sessions, and brainstorming outputs. Supports flexible requirement gathering with optional task decomposition.
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
## Input Sources & Planning Approaches
## Input Sources & Processing
### Brainstorming-Based Planning (--from-brainstorming)
**Prerequisites**: Completed brainstorming session with multi-agent analysis
**Input Sources**:
- `.workflow/WFS-[topic-slug]/.brainstorming/[agent]/analysis.md` files
- `.workflow/WFS-[topic-slug]/.brainstorming/synthesis-analysis.md`
- `.workflow/WFS-[topic-slug]/.brainstorming/recommendations.md`
- `workflow-session.json` brainstorming phase results
### Direct User Input Planning (--skip-brainstorming)
**Prerequisites**: User provides task description and requirements
**Input Sources**:
- User task description and requirements
- Existing project structure analysis
- Session context from workflow-session.json (if exists)
### Session Context Detection
⚠️ **CRITICAL**: Before planning, MUST check for existing active session to avoid creating duplicate sessions.
**Session Check Process:**
1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it.
2. **Session Selection**: Use existing active session or create new one only if none exists
3. **Context Integration**: Load existing session state and brainstorming outputs
```json
{
"session_id": "WFS-[topic-slug]",
"type": "simple|medium|complex",
"current_phase": "PLAN",
"session_source": "existing_active|new_creation",
"brainstorming": {
"status": "completed|skipped",
"output_directory": ".workflow/WFS-[topic-slug]/.brainstorming/",
"insights_available": true|false
}
}
```
### Planning Depth & Document Generation
- **Simple**: Skip detailed planning, generate minimal IMPL_PLAN.md or go direct to IMPLEMENT
- **Medium**: Standard planning with IMPL_PLAN.md generation (1-2 agents)
- **Complex**: Full planning with comprehensive IMPL_PLAN.md (enhanced structure)
## Execution Flow
### Phase 1: Context Understanding & Structure Establishment
1. **Session Detection & Selection**:
- **Check Active Sessions**: Query `.workflow/session_status.jsonl` for existing active sessions. If the file doesn't exist, create it.
- **Session Priority**: Use existing active session if available, otherwise create new session
- **Session Analysis**: Read and understand workflow-session.json from selected session
- Detect existing brainstorming outputs
- Identify current phase and progress
- Understand project context and requirements
2. **File Structure Assessment**:
- **If brainstorming exists**: Verify `.workflow/WFS-[topic-slug]/.brainstorming/` structure
- **If no structure exists**: Create complete workflow directory structure
- **Document Discovery**: Identify all existing planning documents
3. **Input Source Determination**:
- **From Brainstorming**: Read all agent analyses and synthesis documents
- **Skip Brainstorming**: Collect user requirements and context directly
- **Hybrid**: Combine existing insights with new user input
### Phase 2: Context Integration & Requirements Analysis
4. **Requirements Synthesis**:
- **From Brainstorming**: Integrate multi-agent perspectives and recommendations
- **From User Input**: Analyze and structure user-provided requirements
- **Gap Analysis**: Identify missing information and clarify with user
5. **Complexity Assessment**: Determine planning depth needed based on:
- Scope of requirements (brainstorming insights or user input)
- Technical complexity indicators
- Resource and timeline constraints
- Risk assessment from available information
### Phase 3: Document Generation & Planning
6. **Create Document Directory**: Setup `.workflow/WFS-[topic-slug]/` structure (if needed)
7. **Execute Planning**:
- **Simple**: Minimal documentation, direct to IMPLEMENT
- **Medium**: Generate IMPL_PLAN.md with task breakdown
- **Complex**: Generate comprehensive IMPL_PLAN.md with staged approach and risk assessment
8. **Auto-Generate Tasks (NEW)**: Parse IMPL_PLAN.md and automatically create corresponding task JSON files
- **Extract Tasks**: Parse task identifiers (IMPL-001, IMPL-002, etc.) from plan
- **Create Task Files**: Generate `.task/impl-*.json` files with plan context
- **Link to Plan**: Include `source_plan_ref` field linking tasks back to plan sections
- **Set Dependencies**: Establish task dependencies based on plan structure
9. **Update Session**: Mark PLAN phase complete with document references and generated task list
10. **Link Documents**: Update JSON state with generated document paths and task file references
## Automated Task Generation (Single Source of Truth Integration)
### Planning-to-Execution Automation
**NEW FEATURE**: Eliminates the gap between planning and execution by automatically creating executable task files from planning documents.
### Task Extraction Process
1. **Parse IMPL_PLAN.md**: Scan for task identifiers in standardized format:
- `IMPL-001`, `IMPL-002`, etc. (main tasks)
- `IMPL-1.1`, `IMPL-1.2`, etc. (subtasks)
- Task titles and descriptions from plan sections
2. **Generate Task JSON Files**: For each identified task, create structured JSON:
```json
{
"id": "IMPL-001",
"title": "Foundation/Infrastructure setup",
"status": "pending",
"type": "infrastructure",
"agent": "code-developer",
"effort": "2h",
"context": {
"inherited_from": "WFS-[topic-slug]",
"source_plan_ref": "IMPL_PLAN.md#phase-1-foundation",
"requirements": ["Extracted from plan description"],
"scope": ["Derived from plan context"],
"acceptance": ["Extracted from success criteria"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-002"],
"phase_group": "Phase 1: Foundation"
},
"metadata": {
"created_at": "2025-09-07T15:00:00Z",
"created_by": "workflow:action-plan",
"auto_generated": true,
"plan_version": "1.0"
}
}
```
3. **Link Bidirectionally**:
- Task files reference plan sections
- Session state includes all generated task IDs
- Ready for immediate execution via `/task:execute`
### Benefits of Automation
- **Zero Manual Task Creation**: Plans immediately become executable
- **Consistency**: All tasks derive from same authoritative plan
- **Traceability**: Clear linkage from requirements through plan to tasks
- **Immediate Execution**: Can run `/task:execute IMPL-001` immediately after planning
## Session State Analysis & Document Understanding
### Workflow Session Discovery
**Command**: `workflow:action-plan` automatically detects and analyzes:
**Session Detection Process**:
1. **Find Active Sessions**: Locate `.workflow/WFS-*/workflow-session.json` files
2. **Session Validation**: Verify session completeness and current phase
3. **Context Extraction**: Read session metadata, progress, and phase outputs
**Session State Analysis**:
```json
{
"session_id": "WFS-user-auth-system",
"current_phase": "PLAN",
"brainstorming": {
"status": "completed",
"agents_completed": ["system-architect", "ui-designer", "security-expert"],
"synthesis_available": true,
"recommendations_count": 12
},
"documents": {
"brainstorming": {
"system-architect/analysis.md": {"status": "available", "insights": ["scalability", "microservices"]},
"synthesis-analysis.md": {"status": "available", "key_themes": ["security-first", "user-experience"]}
}
}
}
```
### Document Intelligence & Content Understanding
**Process**: Action planning reads and interprets existing workflow documents
**Brainstorming Document Analysis**:
- **Agent Analyses**: Extract key insights, recommendations, and constraints from each agent
- **Synthesis Reports**: Understand cross-perspective themes and convergent solutions
- **Recommendation Prioritization**: Identify high-impact, actionable items
- **Context Preservation**: Maintain user requirements and constraints from discussions
**Content Integration Strategy**:
- **Technical Requirements**: From system-architect, data-architect, security-expert analyses
- **User Experience**: From ui-designer, user-researcher perspectives
- **Business Context**: From product-manager, business-analyst insights
- **Implementation Constraints**: From all agent recommendations and user discussions
**Gap Detection**:
- Identify missing technical specifications
- Detect undefined user requirements
- Find unresolved architectural decisions
- Highlight conflicting recommendations requiring resolution
## Output Format
### IMPL_PLAN.md Structure (Enhanced for Action Planning)
```markdown
# Action Implementation Plan
## Context & Requirements
### From Brainstorming Analysis (if --from-brainstorming)
- **Key Insights**: Synthesized from multi-agent perspectives
- **Technical Requirements**: Architecture, security, data considerations
- **User Experience Requirements**: UI/UX design and usability needs
- **Business Requirements**: Product goals, stakeholder priorities, constraints
- **User Discussion Context**: Captured requirements from user interactions
### From User Input (if --skip-brainstorming)
- **User Provided Requirements**: Direct input and specifications
- **Context Analysis**: Interpreted requirements and technical implications
- **Gap Identification**: Areas needing clarification or additional information
## Strategic Approach
- **Implementation Philosophy**: Core principles guiding development
- **Success Metrics**: How progress and completion will be measured
- **Risk Mitigation**: Key risks identified and mitigation strategies
## Task Breakdown
- **IMPL-001**: Foundation/Infrastructure setup
- **IMPL-002**: Core functionality implementation
- **IMPL-003**: Integration and testing
- **IMPL-004**: [Additional tasks based on complexity]
## Dependencies & Sequence
- **Critical Path**: Essential task sequence
- **Parallel Opportunities**: Tasks that can run concurrently
- **External Dependencies**: Third-party integrations or resources needed
## Resource Allocation
- **Technical Resources**: Required skills and expertise
- **Timeline Estimates**: Duration estimates for each phase
- **Quality Gates**: Review and approval checkpoints
## Success Criteria
- **Functional Acceptance**: Core functionality validation
- **Technical Acceptance**: Performance, security, scalability criteria
- **User Acceptance**: Usability and experience validation
```
### Enhanced IMPL_PLAN.md Structure (Complex Workflows)
```markdown
# Implementation Plan - [Project Name]
## Context & Requirements
### From Brainstorming Analysis (if --from-brainstorming)
- **Key Insights**: Synthesized from multi-agent perspectives
- **Technical Requirements**: Architecture, security, data considerations
- **User Experience Requirements**: UI/UX design and usability needs
- **Business Requirements**: Product goals, stakeholder priorities, constraints
- **User Discussion Context**: Captured requirements from user interactions
### From User Input (if --skip-brainstorming)
- **User Provided Requirements**: Direct input and specifications
- **Context Analysis**: Interpreted requirements and technical implications
- **Gap Identification**: Areas needing clarification or additional information
## Strategic Approach
- **Implementation Philosophy**: Core principles guiding development
- **Success Metrics**: How progress and completion will be measured
- **Risk Mitigation**: Key risks identified and mitigation strategies
## Phase Breakdown
### Phase 1: Foundation
- **Objective**: [Core infrastructure/base components]
- **Tasks**: IMPL-001, IMPL-002
- **Duration**: [Estimate]
- **Success Criteria**: [Measurable outcomes]
### Phase 2: Core Implementation
- **Objective**: [Main functionality]
- **Tasks**: IMPL-003, IMPL-004, IMPL-005
- **Duration**: [Estimate]
- **Dependencies**: Phase 1 completion
### Phase 3: Integration & Testing
- **Objective**: [System integration and validation]
- **Tasks**: IMPL-006, IMPL-007
- **Duration**: [Estimate]
## Risk Assessment
- **High Risk**: [Description] - Mitigation: [Strategy]
- **Medium Risk**: [Description] - Mitigation: [Strategy]
## Quality Gates
- Code review requirements
- Testing coverage targets
- Performance benchmarks
- Security validation checks
## Rollback Strategy
- Rollback triggers and procedures
- Data preservation approach
```
## Document Storage
Generated documents are stored in session directory:
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md # Combined planning document (all complexities)
└── workflow-session.json # Updated with document references
```
## Session Updates (Enhanced with Task Generation)
```json
{
"phases": {
"PLAN": {
"status": "completed",
"output": {
"primary": "IMPL_PLAN.md",
"tasks_generated": [".task/impl-001.json", ".task/impl-002.json", ".task/impl-003.json"]
},
"documents_generated": ["IMPL_PLAN.md"],
"tasks_auto_created": 3,
"completed_at": "2025-09-05T11:00:00Z",
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"],
"ready_for_implementation": true
}
},
"documents": {
"planning": {
"IMPL_PLAN.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
"tasks_extracted": 3,
"auto_generation": "completed"
}
}
},
"task_system": {
"enabled": true,
"auto_generated": true,
"directory": ".workflow/WFS-[topic-slug]/.task/",
"task_count": {
"total": 3,
"pending": 3,
"from_planning": 3
}
}
}
```
## Complexity Decision Rules
### Document Generation Matrix
| Complexity | IMPL_PLAN.md | Structure | Agent Requirements |
|------------|--------------|-----------|-------------------|
| **Simple** | Optional/Skip | Minimal | Direct to IMPLEMENT |
| **Medium** | Required | Standard | planning-agent |
| **Complex** | Required | Enhanced with phases + risk assessment | planning-agent + detailed analysis |
### Auto-Detection Triggers
Complex planning triggered when:
- Architecture changes required
- Security implementation needed
- Performance optimization planned
- System integration involved
- Estimated effort > 8 hours
- Risk level assessed as high
### Manual Override
### Direct Text Input (Default)
```bash
# Force complex planning even for medium tasks
/workflow:action-plan --force-complex
# Force simple planning for quick fixes
/workflow:action-plan --force-simple
/workflow:action-plan "Build user authentication system with JWT and OAuth2"
```
**Processing**:
- Parse natural language requirements
- Extract technical components and constraints
- Identify implementation scope and objectives
- Generate structured plan from description
## Skip Option
### File-based Input
```bash
/workflow:action-plan --skip-to-implement
/workflow:action-plan --from-file requirements.md
/workflow:action-plan --from-file PROJECT_SPEC.txt
```
- Generates minimal plan
- Immediately transitions to IMPLEMENT
- Useful for urgent fixes
**Supported formats**: .md, .txt, .json, .yaml
**Processing**:
- Read and parse file contents
- Extract structured requirements and specifications
- Identify task descriptions and dependencies
- Preserve original structure and priorities
## Replanning Mode
### Usage
### Issue-based Input
```bash
# Basic replanning
/workflow:action-plan --replan --trigger=requirement-change
# Strategic replanning with impact analysis
/workflow:action-plan --replan --trigger=new-issue --scope=all --strategy=minimal-disruption --impact-analysis
# Conflict resolution
/workflow:action-plan --replan --trigger=dependency-conflict --auto-resolve
/workflow:action-plan --from-issue ISS-001
/workflow:action-plan --from-issue "feature-request"
```
**Supported sources**: Issue IDs, issue titles, GitHub URLs
**Processing**:
- Load issue description and acceptance criteria
- Parse technical requirements and constraints
- Extract related issues and dependencies
- Include issue context in planning
### Replan Parameters
- `--trigger=<reason>` → Replanning trigger: `new-issue|requirement-change|dependency-conflict|optimization`
- `--scope=<scope>` → Scope: `current-phase|all|documents-only|tasks-only`
- `--strategy=<strategy>` → Strategy: `minimal-disruption|optimal-efficiency|risk-minimization|time-optimization`
- `--impact-analysis` → Detailed impact analysis
- `--auto-resolve` → Auto-resolve conflicts
- `--dry-run` → Simulation mode
### Replanning Strategies
#### Minimal Disruption
- Preserve completed tasks
- Minimize impact on active work
- Insert changes optimally
#### Optimal Efficiency
- Re-optimize task order
- Maximize parallelization
- Optimize critical path
#### Risk Minimization
- Prioritize high-risk tasks
- Add buffer time
- Strengthen dependencies
#### Time Optimization
- Focus on core requirements
- Defer non-critical tasks
- Maximize parallel execution
### Integration with Issues
When issues are created, replanning can be automatically triggered:
### Template-based Input
```bash
# Create issue then replan
/workflow:issue create --type=feature "OAuth2 support"
/workflow:action-plan --replan --trigger=new-issue --issue=ISS-001
/workflow:action-plan --template web-api
/workflow:action-plan --template mobile-app "user management"
```
**Available templates**:
- `web-api`: REST API development template
- `mobile-app`: Mobile application template
- `database-migration`: Database change template
- `security-feature`: Security implementation template
**Processing**:
- Load template structure and best practices
- Prompt for template-specific parameters
- Customize template with user requirements
- Generate plan following template patterns
### Interactive Mode
```bash
/workflow:action-plan --interactive
```
**Guided Process**:
1. **Project Type**: Select development category
2. **Requirements**: Structured requirement gathering
3. **Constraints**: Technical and resource limitations
4. **Success Criteria**: Define completion conditions
5. **Plan Generation**: Create comprehensive plan
### Brainstorming Integration
```bash
/workflow:action-plan --from-brainstorming
```
**Prerequisites**: Completed brainstorming session
**Processing**:
- Read multi-agent brainstorming analyses
- Synthesize recommendations and insights
- Integrate diverse perspectives into unified plan
- Preserve brainstorming context and decisions
### Web-based Input
```bash
/workflow:action-plan --from-url "https://github.com/project/issues/45"
/workflow:action-plan --from-url "https://docs.example.com/spec"
```
**Processing**:
- Fetch content from web URLs
- Parse structured requirements from web pages
- Extract technical specifications
- Handle GitHub issues, documentation sites, specs
## Complexity Levels
### Simple (Default)
```bash
/workflow:action-plan "Build chat system"
```
**Output**: IMPL_PLAN.md document only
**Use case**: Documentation-focused planning, quick overviews
**Content**: Structured plan with task descriptions
### Decompose
```bash
/workflow:action-plan "Build chat system" --complexity=decompose
```
**Output**: IMPL_PLAN.md + task JSON files
**Use case**: Full workflow execution with automated task system
**Content**: Plan document + extracted task files in .task/ directory
## Input Processing Pipeline
### 1. Input Detection
```pseudo
function detect_input_type(args):
if starts_with("--from-file"):
return "file"
elif starts_with("--from-issue"):
return "issue"
elif starts_with("--template"):
return "template"
elif args == "--interactive":
return "interactive"
elif args == "--from-brainstorming":
return "brainstorming"
elif starts_with("--from-url"):
return "url"
else:
return "direct_text"
```
## Integration with Workflow System
### 2. Content Extraction
**Per Input Type**:
- **Direct Text**: Parse natural language requirements
- **File**: Read file contents and structure
- **Issue**: Load issue data and related context
- **Template**: Load template and gather parameters
- **Interactive**: Conduct guided requirement session
- **Brainstorming**: Read brainstorming outputs
- **URL**: Fetch web content and parse
### Action Planning Integration Points
**Prerequisite Commands**:
- `/workflow:session start` → Initialize workflow session
- `/brainstorm` → (Optional) Multi-agent brainstorming phase
### 3. Requirement Analysis
- Structure extracted information
- Identify tasks and dependencies
- Determine technical requirements
- Extract success criteria
- Assess complexity and scope
**Action Planning Execution**:
- `/workflow:action-plan --from-brainstorming` → Plan from completed brainstorming
- `/workflow:action-plan --skip-brainstorming "task description"` → Plan from user input
- `/workflow:action-plan --replan` → Revise existing plans
### 4. Plan Generation
- Create IMPL_PLAN.md with structured content
- Include requirements, tasks, and success criteria
- Maintain traceability to input sources
- Format for readability and execution
**Follow-up Commands**:
- `/workflow:implement` → Execute the action plan
- `/workflow:status` → View current workflow state
- `/task:create` → Create specific implementation tasks
- `/workflow:review` → Validate completed implementation
### 5. Optional Decomposition
**If --complexity=decompose**:
- Parse IMPL_PLAN.md for task identifiers
- Create .task/impl-*.json files
- Establish task relationships
- Update session with task references
## Session Management
### Session Check Process
⚠️ **CRITICAL**: Check for existing active session before planning
1. **Query Session Registry**: Check `.workflow/session_status.jsonl`
2. **Session Selection**: Use existing active session or create new
3. **Context Integration**: Load session state and existing context
### Session State Updates
After action planning completion:
```json
{
"current_phase": "IMPLEMENT",
"current_phase": "PLAN",
"input_source": "direct_text|file|issue|template|interactive|brainstorming|url",
"input_details": {
"type": "detected_input_type",
"source": "input_identifier_or_path",
"processed_at": "2025-09-08T15:00:00Z"
},
"phases": {
"BRAINSTORM": {"status": "completed|skipped"},
"PLAN": {
"status": "completed",
"input_source": "brainstorming|user_input",
"complexity": "simple|decompose",
"documents_generated": ["IMPL_PLAN.md"],
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"],
"complexity_assessed": "simple|medium|complex"
"tasks_created": 0,
"input_processed": true
}
}
}
```
### Quality Assurance
**Action Planning Excellence**:
- **Context Integration** → All brainstorming insights or user requirements incorporated
- **Actionable Output** → Plans translate directly to executable tasks
- **Comprehensive Coverage** → Technical, UX, and business considerations included
- **Clear Sequencing** → Dependencies and critical path clearly defined
- **Measurable Success** → Concrete acceptance criteria established
## IMPL_PLAN.md Template
This action planning command bridges brainstorming insights and implementation execution, ensuring comprehensive planning based on multi-perspective analysis or direct user input.
### Standard Structure
```markdown
# Implementation Plan - [Project Name]
*Generated from: [input_source]*
## Requirements
[Extracted requirements from input source]
## Technical Scope
[Technical components and architecture needs]
## Task Breakdown
- **IMPL-001**: [Task description]
- **IMPL-002**: [Task description]
- **IMPL-003**: [Task description]
## Dependencies & Sequence
[Task execution order and relationships]
## Success Criteria
[Measurable completion conditions]
## Input Source Context
[Traceability information back to original input]
```
## Task Decomposition (Decompose Mode)
### Automatic Task Generation
**Process**:
1. Parse IMPL_PLAN.md for task patterns: `IMPL-\d+`
2. Extract task titles and descriptions
3. Create JSON files in `.task/` directory
4. Establish dependencies from plan structure
### Generated Task JSON Structure
```json
{
"id": "impl-1",
"title": "[Extracted from IMPL_PLAN.md]",
"status": "pending",
"type": "feature",
"agent": "code-developer",
"context": {
"requirements": ["From input source"],
"scope": ["Inferred from task description"],
"acceptance": ["From success criteria"],
"inherited_from": "WFS-[session]",
"input_source": "direct_text|file|issue|template|interactive|brainstorming|url"
},
"relations": {
"parent": null,
"subtasks": [],
"dependencies": []
},
"execution": {
"attempts": 0,
"last_attempt": null
},
"meta": {
"created": "[timestamp]",
"updated": "[timestamp]",
"generated_from": "IMPL_PLAN.md"
}
}
```
## Template System
### Available Templates
#### Web API Template
```markdown
Requirements:
- REST endpoints design
- Database schema
- Authentication/authorization
- API documentation
- Error handling
- Testing strategy
```
#### Mobile App Template
```markdown
Requirements:
- Platform selection (iOS/Android/Cross-platform)
- UI/UX design
- State management
- API integration
- Local storage
- App store deployment
```
#### Security Feature Template
```markdown
Requirements:
- Security requirements analysis
- Threat modeling
- Implementation approach
- Testing and validation
- Compliance considerations
- Documentation updates
```
### Template Customization
Templates prompt for:
- Project-specific requirements
- Technology stack preferences
- Scale and performance needs
- Integration requirements
- Timeline constraints
## Interactive Planning Process
### Step-by-Step Guidance
1. **Project Category**: Web app, mobile app, API, library, etc.
2. **Core Requirements**: Main functionality and features
3. **Technical Stack**: Languages, frameworks, databases
4. **Constraints**: Timeline, resources, performance needs
5. **Dependencies**: External systems, APIs, libraries
6. **Success Criteria**: How to measure completion
7. **Review & Confirmation**: Validate gathered information
## Error Handling
### Input Processing Errors
```bash
# File not found
❌ File requirements.md not found
→ Check file path and try again
# Invalid issue
❌ Issue ISS-001 not found
→ Verify issue ID or create issue first
# Template not available
❌ Template "custom-template" not available
→ Available templates: web-api, mobile-app, database-migration, security-feature
# URL fetch failed
❌ Cannot fetch content from URL
→ Check URL accessibility and format
```
## Integration Points
### Command Flow
```bash
# Planning from various sources
/workflow:action-plan [input-source]
# View generated plan
/context
# Execute tasks (if decomposed)
/task:execute impl-1
# Move to implementation
/workflow:vibe
```
### Session Integration
- Updates workflow-session.json with planning results
- Creates document references for generated files
- Establishes task system if decomposition enabled
- Preserves input source traceability
## Related Commands
- `/context` - View generated plan and task status
- `/task:execute` - Execute decomposed tasks
- `/workflow:vibe` - Coordinate multi-agent execution
- `/workflow:review` - Validate completed implementation
---
**System ensures**: Flexible planning from multiple input sources with optional task decomposition and full workflow integration

345
.claude/commands/workflow/implement.md
View File

@@ -1,345 +0,0 @@
---
name: workflow-implement
description: Implementation phase with simple, medium, and complex execution modes
usage: /workflow:implement [--type=<simple|medium|complex>] [--auto-create-tasks]
argument-hint: [optional: complexity type and auto-create]
examples:
- /workflow:implement
- /workflow:implement --type=simple
- /workflow:implement --type=complex --auto-create-tasks
---
# Workflow Implement Command (/workflow:implement)
## Overview
Executes implementation phase with three complexity modes (simple/medium/complex), replacing separate complexity commands.
## Core Principles
**Session Management:** @~/.claude/workflows/session-management-principles.md
## Complexity Modes
### Simple Mode (Single file, bug fixes)
```bash
/workflow:implement --type=simple
```
**Agent Flow:** code-developer → code-review-agent
**TodoWrite:** 3-4 items
**Documents:** TODO_LIST.md + IMPLEMENTATION_LOG.md (auto-generated)
- Streamlined planning, direct implementation
- Quick review cycle
- < 2 hours effort
### Medium Mode (Multi-file features)
```bash
/workflow:implement --type=medium
```
**Agent Flow:** planning-agent → code-developer → code-review-agent
**TodoWrite:** 5-7 items
**Documents:** IMPL_PLAN.md + TODO_LIST.md (auto-triggered)
- Structured planning with hierarchical JSON task decomposition
- Test-driven development
- Comprehensive review
- 2-8 hours effort
### Complex Mode (System-level changes)
```bash
/workflow:implement --type=complex
```
**Agent Flow:** planning-agent → code-developer → code-review-agent → iterate
**TodoWrite:** 7-10 items
**Documents:** IMPL_PLAN.md + TODO_LIST.md (mandatory)
- Detailed planning with mandatory 3-level JSON task hierarchy
- Risk assessment and quality gates
- Multi-faceted review with multiple iterations
- > 8 hours effort
## Execution Flow
1. **Detect Complexity** (if not specified)
- Read from workflow-session.json
- Auto-detect from task description
- Default to medium if unclear
2. **Initialize Based on Complexity**
**Simple:**
- Use existing IMPL_PLAN.md (minimal updates)
- Direct JSON task creation (impl-*.json)
- Minimal state tracking
**Medium:**
- Update IMPL_PLAN.md with implementation strategy
- Auto-trigger TODO_LIST.md creation
- Create hierarchical JSON tasks (impl-*.*.json up to 2 levels)
- Standard agent flow
**Complex:**
- Comprehensive IMPL_PLAN.md with risk assessment
- Mandatory TODO_LIST.md with progress tracking
- Full 3-level JSON task hierarchy (impl-*.*.*.json)
- Full iteration support with cross-document synchronization
3. **Update Session**
```json
{
"current_phase": "IMPLEMENT",
"type": "simple|medium|complex",
"phases": {
"IMPLEMENT": {
"status": "active",
"complexity": "simple|medium|complex",
"agent_flow": [...],
"todos": [...],
"tasks": ["impl-1", "impl-2", "impl-3"],
"progress": 0,
"documents_generated": ["TODO_LIST.md", "IMPLEMENTATION_LOG.md"],
"documents_updated": ["IMPL_PLAN.md"]
}
},
"documents": {
"IMPL_PLAN.md": {
"status": "updated",
"path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
"last_updated": "2025-09-05T10:30:00Z"
},
"TODO_LIST.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/TODO_LIST.md",
"last_updated": "2025-09-05T11:20:00Z",
"type": "task_tracking"
},
"IMPLEMENTATION_LOG.md": {
"status": "generated",
"path": ".workflow/WFS-[topic-slug]/IMPLEMENTATION_LOG.md",
"last_updated": "2025-09-05T11:20:00Z",
"type": "execution_log",
"auto_update": true
}
},
"task_system": {
"max_depth": 3,
"task_count": {
"main_tasks": 3,
"total_tasks": 8
}
}
}
```
4. **Execute Agent Flow**
- Create TodoWrite entries
- Execute agents based on complexity
- Track checkpoints
- Support pause/resume
## Document Generation Rules
### Decomposition Triggers (Medium Workflows)
Task decomposition documents generated when ANY condition met:
- Task involves >3 modules/components
- >5 distinct subtasks identified
- Complex interdependencies detected
- Estimated effort >4 hours
- Cross-team coordination required
### Mandatory Generation (Complex Workflows)
Always generates complete document suite:
- **Enhanced IMPL_PLAN.md structure** - Hierarchical task breakdown integrated into main plan
- **TODO_LIST.md** - Progress tracking with cross-links
- Links to existing IMPL_PLAN.md from planning phase
### Document-JSON Synchronization
- **Document Creation** → Update workflow session with document references
- **Task Status Changes** → Update TODO_LIST.md progress
- **Task Completion** → Mark items complete in checklist
- **New Tasks Added** → Add to both JSON and enhanced implementation plan
### Document Storage Structure
```
.workflow/WFS-[topic-slug]/
├── IMPL_PLAN.md # From planning phase (all complexities)
├── (enhanced IMPL_PLAN.md) # Enhanced structure in implement phase (medium+/complex)
├── TODO_LIST.md # Generated in implement phase (ALL complexities)
├── IMPLEMENTATION_LOG.md # Execution progress log (ALL complexities)
├── workflow-session.json # Updated with document references
└── artifacts/
├── logs/
├── backups/ # Task state backups
└── implementation/ # Implementation artifacts
```
## File Generation Details
### TODO_LIST.md Generation (All Complexities)
**Always Generated**: Now created for Simple, Medium, and Complex workflows
**Simple Workflow Structure:**
```markdown
# Implementation Task List
*Session: WFS-[topic-slug]*
## Quick Implementation Tasks
- [ ] **IMPL-001**: Core implementation
- [ ] **IMPL-002**: Basic testing
- [ ] **IMPL-003**: Review and cleanup
## Progress Tracking
- **Total Tasks**: 3
- **Completed**: 0/3 (0%)
- **Estimated Time**: < 2 hours
---
*Generated by /workflow:implement --type=simple*
```
**Medium/Complex Workflow Structure:**
```markdown
# Implementation Task List
*Session: WFS-[topic-slug]*
## Main Implementation Tasks
### Phase 1: Foundation
- [ ] **IMPL-001**: Set up base infrastructure
- Dependencies: None
- Effort: 2h
- Agent: code-developer
### Phase 2: Core Features
- [ ] **IMPL-002**: Implement main functionality
- Dependencies: IMPL-001
- Effort: 4h
- Agent: code-developer
### Phase 3: Testing & Review
- [ ] **IMPL-003**: Comprehensive testing
- Dependencies: IMPL-002
- Effort: 2h
- Agent: code-review-agent
## Progress Summary
- **Total Tasks**: 8
- **Completed**: 0/8 (0%)
- **Current Phase**: Foundation
- **Estimated Completion**: 2025-09-07 18:00
---
*Generated by /workflow:implement --type=medium*
```
### IMPLEMENTATION_LOG.md Generation (All Complexities)
**Always Generated**: Real-time execution progress tracking
```markdown
# Implementation Execution Log
*Session: WFS-[topic-slug] | Started: 2025-09-07 14:00:00*
## Execution Summary
- **Workflow Type**: Medium
- **Total Tasks**: 8
- **Current Status**: In Progress
- **Progress**: 3/8 (37.5%)
## Execution Timeline
### 2025-09-07 14:00:00 - Implementation Started
- **Phase**: IMPLEMENT
- **Agent**: code-developer
- **Status**: Task execution initialized
### 2025-09-07 14:15:00 - IMPL-001 Started
- **Task**: Set up base infrastructure
- **Agent**: code-developer
- **Approach**: Standard project structure setup
### 2025-09-07 14:45:00 - IMPL-001 Completed
- **Duration**: 30 minutes
- **Status**: ✅ Successful
- **Output**: Base project structure created
- **Next**: IMPL-002
### 2025-09-07 15:00:00 - IMPL-002 Started
- **Task**: Implement main functionality
- **Agent**: code-developer
- **Dependencies**: IMPL-001 ✅
## Current Task Progress
- **Active Task**: IMPL-002
- **Progress**: 60%
- **Estimated Completion**: 15:30
- **Agent**: code-developer
## Issues & Resolutions
- No issues reported
## Next Actions
1. Complete IMPL-002 implementation
2. Begin IMPL-003 testing phase
3. Schedule review checkpoint
---
*Log updated: 2025-09-07 15:15:00*
```
## Individual Task Files Structure
```json
{
"id": "IMPL-001",
"title": "Build authentication module",
"status": "pending",
"type": "feature",
"agent": "code-developer",
"effort": "4h",
"context": {
"inherited_from": "WFS-2025-001",
"requirements": ["JWT authentication"],
"scope": ["src/auth/*"],
"acceptance": ["Module handles JWT tokens"]
},
"dependencies": {
"upstream": [],
"downstream": ["IMPL-002"]
},
"subtasks": [],
"execution": {
"attempts": 0,
"current_attempt": null,
"history": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"version": "1.0"
}
}
```
## Integration Points
### Automatic Behaviors
- Creates individual task JSON files (.task/tasks/IMPL-XXX.json) as needed
- Generates decomposition documents based on complexity triggers
- Links documents to workflow-session.json with paths and status
- Enables task commands (/task:*) with document integration
- Initializes tasks in 'pending' state within their JSON files
- Synchronizes task creation between documents and JSON states
### Next Actions
```bash
# After /workflow:implement
/task:create "First task" # Create tasks
/task:status # View task list
/task:execute IMPL-001 # Execute tasks
```
## Sync Mechanism
- Every task operation updates workflow-session.json
- Progress calculated from task completion
- Issues automatically linked
## Related Commands
- `/workflow:plan` - Should complete first
- `/task:create` - Create implementation tasks
- `/task:status` - Monitor progress
- `/workflow:review` - Next phase after implementation

267
.claude/commands/workflow/vibe.md Normal file
View File

@@ -0,0 +1,267 @@
---
name: workflow-vibe
description: Coordinate agents for existing workflow tasks with automatic discovery
usage: /workflow:vibe [workflow-folder]
argument-hint: [optional: workflow folder path]
examples:
- /workflow:vibe
- /workflow:vibe .workflow/WFS-user-auth
---
# Workflow Vibe Command (/workflow:vibe)
## 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
**Session Management:** @~/.claude/workflows/session-management-principles.md
**Agent Orchestration:** @~/.claude/workflows/agent-orchestration-patterns.md
## Vibe Philosophy
The "vibe" 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
**IMPORTANT**: Gemini context analysis is automatically applied based on discovered task scope and requirements.
## Execution Flow
### 1. Discovery & Analysis 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
├── Analyze task statuses and dependencies
└── Determine executable 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
```markdown
# Workflow Vibe Coordination
*Session: WFS-[topic-slug]*
## Execution Plan
- [ ] **TASK-001**: [Agent: planning-agent] [GEMINI_CLI_REQUIRED] Design auth schema (impl-1.1)
- [ ] **TASK-002**: [Agent: code-developer] [GEMINI_CLI_REQUIRED] Implement auth logic (impl-1.2)
- [ ] **TASK-003**: [Agent: code-review-agent] Review implementations
- [ ] **TASK-004**: Update task statuses and session state
```
### 3. Agent Context Assignment
For each executable task:
```json
{
"task": {
"id": "impl-1.1",
"title": "Design auth schema",
"context": {
"requirements": ["JWT authentication", "User model design"],
"scope": ["src/auth/models/*"],
"acceptance": ["Schema validates JWT tokens"]
}
},
"workflow": {
"session": "WFS-user-auth",
"phase": "IMPLEMENT",
"plan_context": "Authentication system with OAuth2 support"
},
"focus_modules": ["src/auth/", "tests/auth/"],
"gemini_required": true
}
```
**Context Assignment Rules:**
- **Complete Context**: Use full task JSON context for agent execution
- **Workflow Integration**: Include session state and IMPL_PLAN.md context
- **Scope Focus**: Direct agents to specific files from task.context.scope
- **Gemini Flags**: Automatically add [GEMINI_CLI_REQUIRED] for multi-file tasks
### 4. Agent Execution & Progress Tracking
```bash
Task(subagent_type="code-developer",
prompt="[GEMINI_CLI_REQUIRED] Implement authentication logic based on schema",
description="Execute impl-1.2 with full workflow context and status tracking")
```
**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
## Discovery & Analysis Process
### File Structure Analysis
```
.workflow/WFS-[topic-slug]/
├── 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
└── .summaries/ # Completed task 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
```
### Automatic Agent Assignment
Based on discovered task data:
- **task.agent field**: Use specified agent from task JSON
- **task.type analysis**:
- "feature" → code-developer
- "test" → test-agent
- "docs" → docs-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
Task(subagent_type="code-developer",
prompt="[GEMINI_CLI_REQUIRED] Execute impl-1.2: Implement auth logic
Context from discovery:
- Requirements: JWT authentication, OAuth2 support
- Scope: src/auth/*, tests/auth/*
- Dependencies: impl-1.1 (completed)
- Workflow: WFS-user-auth authentication system",
description="Agent executes with full discovered context")
```
### 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
### Task Status Updates
```json
// Before execution
{
"id": "impl-1.2",
"status": "pending",
"execution": {
"attempts": 0,
"last_attempt": null
}
}
// After execution
{
"id": "impl-1.2",
"status": "completed",
"execution": {
"attempts": 1,
"last_attempt": "2025-09-08T14:30:00Z"
}
}
```
### Session State Updates
```json
{
"current_phase": "VIBE",
"last_vibe_execution": "2025-09-08T14:30:00Z"
}
```
## Error Handling & Recovery
### Discovery Issues
```bash
# No workflow found
❌ No workflow folder found
→ Use: /workflow init "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: Recreate task or repair references
```
### Execution Recovery
- **Failed Agent**: Retry with adjusted context or different agent
- **Blocked Dependencies**: Skip and continue with available tasks
- **Context Issues**: Reload from JSON files and session state
## Integration Points
### 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
### Next Actions
```bash
# After /workflow:vibe execution
/context # View updated task status
/task:execute impl-X # Execute specific remaining tasks
/workflow:review # Move to review phase when complete
```
## Related Commands
- `/context` - View discovered tasks and current status
- `/task:execute` - Execute individual tasks (user-controlled)
- `/task:status` - Check task 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

118
.claude/output-styles/agent-workflow-coordination.md
View File

@@ -1,13 +1,7 @@
---
name: Agent Workflow Coordination
name: Workflow Coordination
description: Core coordination principles for multi-agent development workflows
---
## System Reference
**Complete Architecture**: @~/.claude/workflows/core-principles.md
This document defines essential coordination principles between agents. For complete system architecture, file structures, commands, and implementation details, refer to the unified workflow system principles.
## Core Agent Coordination Principles
### Planning First Principle
@@ -36,101 +30,27 @@ This document defines essential coordination principles between agents. For comp
6. **Checkpoint Safety**: State is saved automatically after each agent completes its work.
7. **Interrupt/Resume**: The system must support full state preservation and restoration.
### Implementation Prerequisites Principle
## Context Management
**Deliverable Validation**: Code modification agents can only execute when proper planning deliverables exist.
### Gemini Context Protocol
**Context Integration**: Agents use Gemini CLI for context gathering when needed, with memory-gemini-bridge agent handling complex analysis.
**Required Artifacts Before Implementation** (at least one must exist):
- `IMPL_PLAN.md`: Must contain detailed implementation strategy
- `.chat/` sessions: Context analysis supporting planning decisions
- Task definitions: JSON task files with clear acceptance criteria
- Complexity assessment: Validated task complexity and scope
**CLI Guidelines Reference**: Follow @~/.cluade/workflows/gemini-cli-guidelines.md for consistency and `memory-gemini-bridge` agent for comprehensive analysis.
**Validation Protocol**:
```pseudo
FUNCTION validate_implementation_prerequisites():
artifacts_found = 0
### 🎯 Gemini CLI Requirements by Task Complexity
IF exists("IMPL_PLAN.md") AND valid_content("IMPL_PLAN.md"):
artifacts_found += 1
#### 🚀 Simple Tasks (CLI Optional)
**Task Examples**: Single file modifications, documentation updates, text changes, simple bug fixes
**CLI Decision**: Optional - only when unfamiliar patterns encountered
**Context Scope**: Basic guidelines and patterns
IF exists(".chat/") AND NOT empty_directory(".chat/"):
artifacts_found += 1
IF validate_task_definitions():
artifacts_found += 1
IF has_complexity_assessment():
artifacts_found += 1
IF artifacts_found == 0:
BLOCK_IMPLEMENTATION("No planning artifacts found - at least one required")
IF artifacts_found < 2:
WARN_IMPLEMENTATION("Limited planning context - recommend additional artifacts")
RETURN READY_FOR_IMPLEMENTATION
END FUNCTION
```
### Core Workflow Process
`TodoWrite Creation` **->** `Context Collection` **->** `Implementation` **->** `Quality Assurance` **->** `State Update`
### Interrupt & Resume Protocol
**Checkpoint Strategy Flow:**
`Agent Completes` **->** `Save State (Todo + Context)` **->** `Check for Interrupt Signal` **->** `Continue or Stop`
**State Components for Resume**:
- TodoWrite current state
- Agent output chain
- Accumulated context
- Planning documents
- `.chat/` analysis history
### Agent Selection Logic
```pseudo
FUNCTION select_agent_for_task(task_complexity):
CASE task_complexity:
WHEN 'Research/Analysis':
RETURN "General-Purpose" // For research, file analysis
WHEN 'Simple Implementation':
RETURN "Code Developer" // For implementation, TDD, algorithms
WHEN 'Complex Features (3+ components)':
RETURN ["Action Planning", "Code Developer", "Code Review"] // Multi-stage agent chain
WHEN 'Full Lifecycle':
RETURN "Boomerang" // For full workflow orchestration
WHEN 'Post-Implementation':
RETURN "Code Review" // For quality validation, security, compliance
END FUNCTION
```
### Agent Output Standards
**Action Planning Agent**:
```
PLAN_SUMMARY: [One-line summary]
STEPS: [Numbered deliverables]
SUCCESS_CRITERIA: [Measurable standards]
TODOWRITE_ENTRIES: [TodoWrite items created for each stage/subtask]
```
**Code Developer Agent**:
```
PREREQUISITE_VALIDATION: [IMPL_PLAN.md and .chat/ sessions verified]
IMPLEMENTATION_SUMMARY: [What was built]
FILES_MODIFIED: [File list with changes]
CONTEXT_REFERENCES: [Links to supporting .chat/ analysis]
TODOWRITE_UPDATES: [Progress status updates made during implementation]
READY_FOR_REVIEW: [YES/NO with reason]
```
**Code Review Agent**:
```
REVIEW_STATUS: [PASS/ISSUES_FOUND/CRITICAL_ISSUES]
QUALITY_SCORE: [1-10]
TODOWRITE_COMPLETION: [Tasks marked as completed after validation]
RECOMMENDATION: [APPROVE/FIX_REQUIRED/REVISION_NEEDED]
#### 🎯 Medium Tasks (CLI Recommended)
**Task Examples**: Multi-file features, component modifications, API endpoint additions
**CLI Decision**: Recommended for consistency and quality
**Context Scope**: Guidelines + architecture + feature patterns
**Standard Context Collection**:
```bash
gemini --all-files -p "@{**/*CLAUDE.md} Guidelines for: [task]"
gemini --all-files -p "@[modules] Architecture for: [task]"
gemini --all-files -p "@[files] Patterns for: [task]"
```

175
.claude/workflows/agent-orchestration-patterns.md
View File

@@ -2,112 +2,159 @@
## Core Agent Coordination Features
- **Context Preservation**: Maintain original task context throughout Agent chain
- **Gemini Context Analysis**: MANDATORY context gathering before any agent execution
- **Context-Driven Coordination**: Agents work with comprehensive codebase understanding
- **Dynamic Agent Selection**: Choose agents based on discovered context and patterns
- **Continuous Context Updates**: Refine understanding throughout agent execution
- **Cross-Agent Context Sharing**: Maintain shared context state across all agents
- **Pattern-Aware Execution**: Leverage discovered patterns for optimal implementation
- **Quality Gates**: Each Agent validates input and ensures output standards
- **Adaptive Complexity**: Workflow depth matches task complexity requirements
- **Iterative Improvement**: Complex workflows include multiple review-fix cycles
- **Structured Output**: Standardized Agent output formats ensure reliable coordination
- **Error Recovery**: Graceful handling of Agent coordination failures
## Workflow Implementation Patterns
### Simple Workflow Pattern
```pseudocode
Flow: TodoWrite Creation → Context → Implementation → Review
Flow: Gemini Context Analysis → TodoWrite Creation → Context-Aware Implementation → Review
1. MANDATORY TodoWrite Creation:
- "Gather context for implementation"
- "Implement solution"
- "Review and validate code"
- "Complete task"
1. MANDATORY Gemini Context Analysis:
- Analyze target files and immediate dependencies
- Discover existing patterns and conventions
- Identify utilities and libraries to use
- Generate context package for agents
2. Implementation Checkpoint:
Task(code-developer): Direct implementation
2. TodoWrite Creation (Context-informed):
- "Execute Gemini context analysis"
- "Implement solution following discovered patterns"
- "Review against codebase standards"
- "Complete task with context validation"
3. Context-Aware Implementation:
Task(code-developer): Implementation with Gemini context package
Input: CONTEXT_PACKAGE, PATTERNS_DISCOVERED, CONVENTIONS_IDENTIFIED
Output: SUMMARY, FILES_MODIFIED, TESTS, VERIFICATION
3. Review Checkpoint:
Task(code-review-agent): Quick quality review
4. Context-Aware Review:
Task(code-review-agent): Review with codebase standards context
Input: CONTEXT_PACKAGE, IMPLEMENTATION_RESULTS
Output: STATUS, SCORE, ISSUES, RECOMMENDATIONS
Resume Support: Load todos + context from checkpoint
Resume Support: Load todos + full context state from checkpoint
```
### Medium Workflow Pattern
```pseudocode
Flow: TodoWrite → Planning → Implementation → Review
Flow: Comprehensive Gemini Analysis → TodoWrite → Multi-Context Implementation → Review
1. MANDATORY TodoWrite Creation (5-7 todos):
- "Create implementation plan"
- "Gather context", "Implement with tests"
- "Validate", "Review", "Complete"
1. MANDATORY Comprehensive Gemini Context Analysis:
- Analyze feature area and related components
- Discover cross-file patterns and architectural decisions
- Identify integration points and dependencies
- Generate comprehensive context packages for multiple agents
2. Planning Checkpoint:
Task(planning-agent): Create plan
Trigger decomposition if >3 modules or >5 subtasks
Output: PLAN_SUMMARY, STEPS, SUCCESS_CRITERIA
2. TodoWrite Creation (Context-driven, 5-7 todos):
- "Execute comprehensive Gemini context analysis"
- "Coordinate multi-agent implementation with shared context"
- "Implement following discovered architectural patterns"
- "Validate against existing system patterns", "Review", "Complete"
3. Implementation Checkpoint:
Task(code-developer): Follow plan
Update TODO_CHECKLIST.md if decomposition exists
3. Multi-Context Implementation:
Task(code-developer): Implementation with comprehensive context
Input: CONTEXT_PACKAGES, ARCHITECTURAL_PATTERNS, INTEGRATION_POINTS
Update context as new patterns discovered
4. Review Checkpoint:
Task(code-review-agent): Comprehensive review
Verify against plan and decomposition
4. Context-Aware Review:
Task(code-review-agent): Comprehensive review with system context
Input: FULL_CONTEXT_STATE, IMPLEMENTATION_RESULTS, PATTERN_COMPLIANCE
Verify against discovered architectural patterns
Resume Support: Full state restoration at each checkpoint
Resume Support: Full context state + pattern discovery restoration
```
### Complex Workflow Pattern
```pseudocode
Flow: TodoWrite → Planning → Implementation → Review → Iterate (max 2)
Flow: Deep Gemini Analysis → TodoWrite → Orchestrated Multi-Agent → Review → Iterate (max 2)
1. MANDATORY TodoWrite Creation (7-10 todos):
- "Create detailed plan", "Generate decomposition docs"
- "Gather context", "Implement with testing"
- "Validate criteria", "Review", "Iterate", "Complete"
1. MANDATORY Deep Gemini Context Analysis:
- System-wide architectural understanding
- Deep pattern analysis across entire codebase
- Integration complexity assessment
- Multi-agent coordination requirements discovery
- Risk pattern identification
2. Planning Checkpoint:
Task(planning-agent): MANDATORY task decomposition
Generate: IMPL_PLAN.md (enhanced structure), TODO_LIST.md
Include risk assessment and quality gates
2. TodoWrite Creation (Context-orchestrated, 7-10 todos):
- "Execute deep system-wide Gemini analysis"
- "Orchestrate multi-agent coordination with shared context"
- "Implement with continuous context refinement"
- "Validate against system architectural patterns", "Review", "Iterate", "Complete"
3. Implementation Checkpoint:
Task(code-developer): Follow hierarchical breakdown
Update TODO_CHECKLIST.md for each subtask completion
3. Orchestrated Multi-Agent Implementation:
Multiple specialized agents with shared deep context
Input: SYSTEM_CONTEXT, ARCHITECTURAL_PATTERNS, RISK_ASSESSMENT
Continuous Gemini context updates throughout execution
Cross-agent context synchronization
4. Review & Iteration Loop (max 2 iterations):
Task(code-review-agent): Production-ready review
If CRITICAL_ISSUES found: Task(code-developer) fixes issues
4. Deep Context Review & Iteration Loop (max 2 iterations):
Task(code-review-agent): Production-ready review with full system context
If CRITICAL_ISSUES found: Re-analyze context and coordinate fixes
Continue until no critical issues or max iterations reached
Document Validation: Verify decomposition docs generated
Resume Support: Full state + iteration tracking
Context Validation: Verify deep context analysis maintained throughout
Resume Support: Full context state + iteration tracking + cross-agent coordination
```
## Workflow Characteristics by Pattern
| Pattern | Agent Chain | Quality Focus | Iteration Strategy |
|---------|-------------|---------------|--------------------|
| **Complex** | Full 3-stage + iterations | Production-ready quality | Multiple rounds until perfect |
| **Medium** | Full 3-stage single-pass | Comprehensive quality | Single thorough review |
| **Simple** | 2-stage direct | Basic quality | Quick validation |
| Pattern | Context Analysis | Agent Coordination | Iteration Strategy |
|---------|------------------|--------------------|--------------------|
| **Complex** | Deep system-wide Gemini analysis | Multi-agent orchestration with shared context | Multiple rounds with context refinement |
| **Medium** | Comprehensive multi-file analysis | Context-driven coordination | Single thorough pass with pattern validation |
| **Simple** | Focused file-level analysis | Direct context-aware execution | Quick context validation |
## Task Invocation Examples
## Context-Driven Task Invocation Examples
```bash
# Research Task
# Gemini Context Analysis (Always First)
gemini "Analyze authentication patterns in codebase - identify existing implementations,
conventions, utilities, and integration patterns"
# Context-Aware Research Task
Task(subagent_type="general-purpose",
prompt="Research authentication patterns in codebase")
prompt="Research authentication patterns in codebase",
context="[GEMINI_CONTEXT_PACKAGE]")
# Planning Task
Task(subagent_type="planning-agent",
prompt="Plan OAuth2 implementation across API, middleware, and UI")
# Implementation Task
# Context-Informed Implementation Task
Task(subagent_type="code-developer",
prompt="Implement email validation function with tests")
prompt="Implement email validation function following discovered patterns",
context="PATTERNS: [pattern_list], UTILITIES: [util_list], CONVENTIONS: [conv_list]")
# Review Task
# Context-Driven Review Task
Task(subagent_type="code-review-agent",
prompt="Review recently implemented authentication service")
prompt="Review authentication service against codebase standards and patterns",
context="STANDARDS: [discovered_standards], PATTERNS: [existing_patterns]")
# Cross-Agent Context Sharing
Task(subagent_type="code-developer",
prompt="Coordinate with previous agent results using shared context",
context="PREVIOUS_CONTEXT: [agent_context], SHARED_STATE: [context_state]")
```
## Gemini Context Integration Points
### Pre-Agent Context Gathering
```bash
# Always execute before agent coordination
gemini "Comprehensive analysis for [task] - discover patterns, conventions, and optimal approach"
```
### During-Agent Context Updates
```bash
# Continuous context refinement
gemini "Update context understanding based on agent discoveries in [area]"
```
### Cross-Agent Context Synchronization
```bash
# Ensure context consistency across agents
gemini "Synchronize context between [agent1] and [agent2] work on [feature]"
```

6
.claude/workflows/file-structure-standards.md
View File

@@ -151,12 +151,6 @@ impl-2 # Another main task
```markdown
# Task Progress List: [Session Topic]
## Progress Overview
- **Total Tasks**: X
- **Completed**: Y (Z%)
- **In Progress**: N
- **Pending**: M
## Implementation Tasks
### Main Tasks

563
.claude/workflows/json-document-coordination-system.md
View File

@@ -1,410 +1,271 @@
# JSON-Document Coordination System (Single Source of Truth)
# JSON-Only Data System (Single Source of Truth)
## Overview
This document defines the **Single Source of Truth** architecture where JSON files are the authoritative state source and all markdown documents are read-only, generated views. This eliminates bidirectional synchronization complexity and data conflicts.
This document defines a **pure JSON data model** where JSON files are the only data source and all markdown documents are generated on-demand views. This eliminates all synchronization complexity and ensures data consistency.
**Key Principle**: `.task/*.json` files are the **only** authoritative source of task state. All markdown documents (`TODO_LIST.md`, progress displays, etc.) are generated on-demand from JSON data.
**Key Principle**: `.task/*.json` files are the **only** authoritative source of task state. All markdown documents are **read-only generated views** that never persist state.
## File Structure
### JSON File Hierarchy
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Master session state
├── IMPL_PLAN.md # Combined planning document
├── TODO_LIST.md # Progress tracking document
├── workflow-session.json # Session state (simplified)
├── IMPL_PLAN.md # Static planning document
└── .task/
├── impl-1.json # Main task
├── impl-1.1.json # Level 2 subtask
├── impl-1.1.1.json # Level 3 detailed subtask
├── impl-1.2.json # Another level 2 subtask
└── impl-2.json # Another main task
├── impl-1.json # Task data (only data source)
├── impl-1.1.json # Subtask data
└── impl-2.json # Another task
```
## JSON File Structures
## JSON Data Structures
### 1. Simplified workflow-session.json
### 1. workflow-session.json (Master State)
```json
{
"session_id": "WFS-user-auth-system",
"session_id": "WFS-user-auth",
"project": "OAuth2 authentication system",
"type": "complex",
"status": "active",
"current_phase": "IMPLEMENT",
"directory": ".workflow/WFS-user-auth-system",
"phase": "IMPLEMENT",
"documents": {
"IMPL_PLAN.md": {
"status": "generated",
"path": ".workflow/WFS-user-auth-system/IMPL_PLAN.md",
"last_updated": "2025-09-05T10:30:00Z",
"sync_status": "synced"
},
"TODO_LIST.md": {
"status": "generated",
"path": ".workflow/WFS-user-auth-system/TODO_LIST.md",
"last_updated": "2025-09-05T11:20:00Z",
"sync_status": "synced"
}
"progress": {
"completed_phases": ["PLAN"],
"current_tasks": ["impl-1", "impl-2"],
"last_checkpoint": "2025-09-07T10:00:00Z"
},
"task_system": {
"enabled": true,
"directory": ".workflow/WFS-user-auth-system/.task",
"next_main_task_id": 3,
"max_depth": 3,
"task_count": {
"total": 8,
"main_tasks": 2,
"subtasks": 6,
"pending": 3,
"active": 2,
"completed": 2,
"blocked": 1
}
"stats": {
"total_tasks": 8,
"completed": 3,
"active": 2
},
"coordination": {
"last_sync": "2025-09-05T11:20:00Z",
"sync_conflicts": 0,
"auto_sync_enabled": true,
"manual_sync_required": false
},
"metadata": {
"created_at": "2025-09-05T10:00:00Z",
"last_updated": "2025-09-05T11:20:00Z",
"version": "2.1"
"meta": {
"created": "2025-09-05T10:00:00Z",
"updated": "2025-09-07T10:00:00Z"
}
}
```
### 2. TODO_LIST.md (Task Registry & Display)
TODO_LIST.md serves as both the task registry and progress display:
### 2. Simplified Task JSON (impl-*.json)
```markdown
# Implementation Progress
## Task Status Summary
- **Total Tasks**: 5
- **Completed**: 2 (40%)
- **Active**: 2
- **Pending**: 1
## Task Hierarchy
### ☐ impl-1: Build authentication module (75% complete)
- ☑ impl-1.1: Design authentication schema (100%)
- ☑ impl-1.1.1: Create user model
- ☑ impl-1.1.2: Design JWT structure
- ☐ impl-1.2: Implement OAuth2 flow (50%)
### ☐ impl-2: Setup user management (0%)
```
**Task Registry Data Extracted from TODO_LIST.md:**
"last_updated": "2025-09-05T11:20:00Z"
}
```
### 3. Individual Task JSON (impl-*.json)
```json
{
"id": "impl-1.1",
"title": "Design authentication schema",
"parent_id": "impl-1",
"depth": 2,
"status": "completed",
"type": "design",
"priority": "normal",
"agent": "planning-agent",
"effort": "1h",
"subtasks": ["impl-1.1.1", "impl-1.1.2"],
"id": "impl-1",
"title": "Build authentication module",
"status": "active",
"type": "feature",
"agent": "code-developer",
"context": {
"inherited_from": "impl-1",
"requirements": ["User model schema", "JWT token design", "OAuth2 integration points"],
"scope": ["src/auth/models/*", "docs/auth-schema.md"],
"acceptance": ["Schema validates JWT tokens", "User model complete", "OAuth2 flow documented"]
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"document_refs": {
"todo_section": "TODO_LIST.md#impl-1.1",
"todo_items": [
"TODO_LIST.md#impl-1.1",
"TODO_LIST.md#impl-1.1.1",
"TODO_LIST.md#impl-1.1.2"
],
"impl_plan_ref": "IMPL_PLAN.md#authentication-schema-design"
},
"dependencies": {
"upstream": [],
"downstream": ["impl-1.2"],
"blocking": [],
"blocked_by": [],
"parent_dependencies": ["impl-1"]
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
},
"execution": {
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"duration": "45m",
"checkpoints": ["setup", "design", "validate", "document"],
"completed_checkpoints": ["setup", "design", "validate", "document"]
},
"history": [
{
"attempt": 1,
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"result": "success",
"outputs": ["src/auth/models/User.ts", "docs/auth-schema.md"]
}
]
"attempts": 0,
"last_attempt": "2025-09-05T10:35:00Z"
},
"sync_metadata": {
"last_document_sync": "2025-09-05T11:20:00Z",
"document_version": "1.2",
"sync_conflicts": [],
"pending_document_updates": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"last_updated": "2025-09-05T11:20:00Z",
"created_by": "task:breakdown IMPL-001",
"version": "1.0"
"meta": {
"created": "2025-09-05T10:30:00Z",
"updated": "2025-09-05T10:35:00Z"
}
}
```
## Single Source of Truth Architecture
## Pure Generation Architecture
### 1. Data Authority (Simplified)
### JSON as Single Source of Truth
#### JSON Files Own (ONLY Authoritative Source)
- **ALL Task State**: Complete task definitions, status, progress, metadata
- **Hierarchical Relationships**: Parent-child links, depth management
- **Execution State**: pending/active/completed/blocked/failed
- **Progress Data**: Percentages, timing, checkpoints
- **Agent Assignment**: Current agent, execution history
- **Dependencies**: Task relationships across all hierarchy levels
- **Session Metadata**: Timestamps, versions, attempt counts
- **Runtime State**: Current attempt, active processes
**JSON Files Own Everything:**
- All task state and metadata
- All relationships and dependencies
- All execution history
- All progress information
#### Documents Are Read-Only Views (Generated Only)
- **IMPL_PLAN.md**: Static planning document (manually created, rarely changes)
- **TODO_LIST.md**: **Generated view** from JSON files (never manually edited)
- **Progress Reports**: **Generated views** from JSON data
- **Status Displays**: **Generated views** from JSON state
**Documents Are Temporary Views:**
- Generated only when requested
- Never stored permanently
- Never parsed back to JSON
- No state persistence in markdown
#### No Shared Responsibility (Eliminates Conflicts)
- **Single Direction Flow**: JSON → Markdown (never Markdown → JSON)
- **No Synchronization**: Documents are generated, not synchronized
- **No Conflicts**: Only one source of truth eliminates data conflicts
### No Synchronization Needed
### 2. View Generation (Replaces Synchronization)
**Eliminated Concepts:**
- Bidirectional sync
- Document parsing
- Conflict resolution
- Sync state tracking
- Update coordination
#### No Document → JSON Flow (Eliminated)
**Documents are read-only**: No parsing, no status updates from documents
**No bidirectional sync**: Documents cannot modify JSON state
**No conflict resolution needed**: Single direction eliminates conflicts
**Single Flow Only:**
```
JSON Files → On-Demand Generation → Temporary Views → Display
```
#### JSON → View Generation (On Demand)
**Trigger Events**:
- User requests context view (`/context`)
- Task status changed in JSON files
- View generation requested by commands
**Actions**:
### Generation Process
```pseudo
function generate_view(format, filters):
// Load all JSON data
tasks = load_all_task_json_files()
session = load_workflow_session()
// Generate requested view
switch format:
case 'tasks':
return generate_task_list_view(tasks)
case 'progress':
return generate_progress_view(tasks, session)
case 'hierarchy':
return generate_hierarchy_view(tasks)
default:
return generate_overview(tasks, session)
```
### View Examples
#### Task List View (Generated)
```markdown
# Current Tasks
## Active Tasks
- [⚠️] impl-1: Build authentication module (code-developer)
- [⚠️] impl-2: Setup user management (code-developer)
## Completed Tasks
- [✅] impl-0: Project setup
## Task Dependencies
- impl-2 → depends on → impl-1
```
## Data Operations
### Task Updates (JSON Only)
```javascript
// Pseudo-code for view generation process
on_view_request(view_type, options) {
const task_data = load_all_task_json_files();
const session_data = load_workflow_session();
if (view_type === 'todo_list') {
const todo_view = generate_todo_list_view(task_data);
return render_markdown_view(todo_view);
}
if (view_type === 'progress') {
const progress = calculate_progress_from_json(task_data);
return render_progress_view(progress, session_data);
}
if (view_type === 'status') {
const status = compile_status_from_json(task_data, session_data);
return render_status_view(status);
}
// Update task status
function update_task_status(task_id, new_status) {
const task_file = `.task/${task_id}.json`
const task = load_json(task_file)
task.status = new_status
task.meta.updated = current_timestamp()
save_json(task_file, task)
// No document updates needed - views generated on demand
}
```
### 3. View Generation Process (Replaces Real-Time Sync)
### Session Updates (Minimal)
#### On-Demand View Process
```
1. Command Request → User requests view (`/context`)
2. JSON Loader → Reads all task JSON files
3. Data Processor → Calculates progress, status, hierarchy
4. View Generator → Creates markdown representation
5. Display → Returns formatted view to user
```
```javascript
// Update session stats
function update_session_stats() {
const session = load_workflow_session()
const tasks = load_all_tasks()
#### Context Command (Replaces Sync Commands)
```bash
# Generate todo list view
/context
session.stats.completed = count_completed_tasks(tasks)
session.stats.active = count_active_tasks(tasks)
session.meta.updated = current_timestamp()
# Generate task-specific view
/context IMPL-001
# Generate progress view
/context --format=progress
# Generate status view with health check
/context --health-check
```
## No Conflict Resolution Needed (Architecture Benefit)
### Eliminated Conflict Types
#### Conflicts That No Longer Exist
- **Timestamp Conflicts**: No bidirectional updates means no timestamp conflicts
- **Data Authority Conflicts**: Only JSON has authority, documents are read-only
- **Hierarchy Conflicts**: JSON defines structure, documents display it (no conflicts)
- **Sync State Conflicts**: No synchronization means no sync state issues
### Simplified Data Model Benefits
- **Zero Conflicts**: Single source of truth eliminates all data conflicts
- **No Resolution Logic**: No complex conflict detection or resolution needed
- **Reduced Complexity**: Eliminates entire conflict resolution subsystem
- **Improved Reliability**: Cannot have data drift or inconsistency issues
## Validation and Integrity
### Consistency Checks
```bash
/task:validate --consistency
Running consistency checks:
✅ Task IDs consistent across JSON files and TODO_LIST.md
✅ Hierarchical relationships valid (parent-child links)
✅ Task depth within limits (max 3 levels)
✅ Progress calculations accurate across hierarchy
⚠️ impl-2.1 missing from TODO_LIST.md display
❌ impl-1.1 status mismatch (JSON: completed, TODO: pending)
❌ Orphaned task: impl-3.2.1 has non-existent parent
Issues found: 3
Auto-fix available: 2
Manual review required: 1
```
### Cross-Reference Validation
- Task IDs exist in all referenced documents
- Document sections referenced in JSON exist
- Progress percentages mathematically consistent
- Dependency relationships bidirectional
### Data Integrity Checks
- JSON schema validation
- Document structure validation
- Cross-file referential integrity
- Timeline consistency validation
## Performance and Scalability
### Optimization Strategies
- **Incremental Sync**: Only sync changed sections
- **Batch Updates**: Group related changes
- **Async Processing**: Non-blocking synchronization
- **Caching**: Cache parsed document structures
### Scalability Considerations
- **File Size Limits**: Split large task sets across multiple files
- **Memory Usage**: Stream processing for large document parsing
- **I/O Optimization**: Minimize file reads/writes through batching
## Error Handling and Recovery
### Common Error Scenarios
```bash
# Document parsing error
❌ Failed to parse TODO_LIST.md
→ Syntax error in checkbox format at line 23
→ Restore from JSON task data? (y/n)
# JSON corruption
❌ Invalid JSON in impl-1.2.json
→ Reconstruct from parent task and TODO_LIST.md? (y/n)
# Hierarchy errors
❌ Circular parent-child relationship detected: impl-1.1 → impl-1.1.1 → impl-1.1
→ Break circular dependency? (y/n)
# Missing files
❌ TODO_LIST.md not found
→ Regenerate from JSON task hierarchy? (y/n)
# Depth violations
⚠️ Task impl-1.2.3.1 exceeds maximum depth (3 levels)
→ Flatten hierarchy or promote task? (flatten/promote)
```
### Recovery Mechanisms
- **Automatic Backup**: Git-based document versioning
- **Rollback Options**: Restore from previous sync point
- **Reconstruction**: Rebuild JSON from documents or vice versa
- **Partial Recovery**: Fix individual files without full reset
## Monitoring and Auditing
### Sync Event Logging
```json
{
"timestamp": "2025-09-05T11:20:00Z",
"event_type": "json_to_todo_list_sync",
"source": "impl-1.1.json",
"target": ["TODO_LIST.md"],
"changes": [
{
"type": "hierarchical_status_update",
"task_id": "impl-1.1",
"old_value": "active",
"new_value": "completed",
"propagation": {
"parent_progress": {
"task_id": "impl-1",
"old_progress": 45,
"new_progress": 67
}
}
}
],
"hierarchy_effects": [
"impl-1 progress recalculated",
"impl-1.2 unblocked due to impl-1.1 completion"
],
"conflicts": 0,
"duration_ms": 89,
"status": "success"
save_json('workflow-session.json', session)
// No document coordination needed
}
```
### Performance Metrics
- Sync frequency and duration
- Conflict rate and resolution time
- File size growth over time
- Error rate and recovery success
## Benefits of Pure Generation
This JSON-document coordination system ensures reliable, consistent, and performant integration between state management and planning documentation while maintaining clear data ownership and providing robust error handling.
### Performance Benefits
- **No Sync Overhead**: Zero synchronization operations
- **Faster Updates**: Direct JSON updates only
- **Reduced I/O**: No document file writes
- **Instant Views**: Generate views only when needed
### Reliability Benefits
- **No Data Conflicts**: Single source of truth
- **No Sync Failures**: No synchronization to fail
- **Consistent State**: JSON always authoritative
- **Simple Recovery**: Restore from JSON only
### Maintenance Benefits
- **Simpler Code**: No sync logic needed
- **Easier Debugging**: Check JSON files only
- **Clear Data Flow**: Always JSON → View
- **No Edge Cases**: No sync conflict scenarios
## Validation (Simplified)
### JSON Schema Validation
```bash
/context --validate
Validation Results:
✅ All task JSON files valid
✅ Task relationships consistent
✅ No circular dependencies
⚠️ impl-3 has no subtasks (expected for leaf task)
Status: All systems operational
```
### Basic Integrity Checks
- Task IDs are unique
- Parent-child relationships valid
- Dependencies exist
- Required fields present
## Error Handling
### Simple Error Scenarios
```bash
# Missing task file
❌ Task impl-5 not found
→ Check .task/impl-5.json exists
# Invalid JSON
❌ Parse error in impl-2.json
→ Restore from backup or recreate task
# Circular dependency
❌ Circular dependency: impl-1 → impl-2 → impl-1
→ Fix dependency chain manually
```
### Recovery Strategy
- **JSON First**: Always repair JSON files
- **Regenerate Views**: Views are disposable, regenerate as needed
- **Simple Rollback**: Use git to restore JSON files
- **Manual Repair**: Direct JSON editing for complex issues
## Migration from Complex System
### Removed Features
- All document parsing
- Bidirectional synchronization
- Conflict resolution
- Real-time document updates
- Sync state tracking
- Document metadata
- Cross-file reference validation
- Automated document repairs
### Simplified Workflows
1. **Task Creation**: Create JSON file only
2. **Status Updates**: Update JSON file only
3. **View Request**: Generate from JSON on demand
4. **Progress Check**: Calculate from JSON data
5. **Completion**: Mark JSON as completed
This pure generation system provides all the functionality of the previous complex system while eliminating synchronization overhead, conflicts, and maintenance complexity.

259
.claude/workflows/session-management-principles.md
View File

@@ -2,8 +2,7 @@
## Overview
This document provides complete technical implementation details for session state management, multi-session registry, command pre-execution protocol, and recovery mechanisms.
This document provides simplified session state management with minimal overhead, phase-level tracking, and streamlined coordination.
## Multi-Session Architecture
@@ -57,237 +56,133 @@ All workflow state for each session managed through `workflow-session.json` with
```json
{
"session_id": "WFS-[topic-slug]",
"session_version": "2.0",
"project": "feature description",
"type": "simple|medium|complex",
"current_phase": "PLAN|IMPLEMENT|REVIEW",
"status": "active|paused|completed",
"created_at": "timestamp",
"updated_at": "timestamp",
"checkpoints": {
"plan": {
"status": "completed|in_progress|pending",
"documents": ["IMPL_PLAN.md", "TASK_BREAKDOWN.md"],
"timestamp": "timestamp"
},
"implement": {
"status": "completed|in_progress|pending",
"agents_completed": ["code-developer"],
"current_agent": "code-review-agent",
"todos": {
"total": 12,
"completed": 8,
"in_progress": 1
},
"timestamp": "timestamp"
},
"review": {
"status": "completed|in_progress|pending",
"quality_checks": {
"code_quality": "passed",
"test_coverage": "pending"
}
}
"progress": {
"completed_phases": ["PLAN"],
"current_tasks": ["impl-1", "impl-2"],
"last_checkpoint": "2025-09-07T10:00:00Z"
},
"context_chain": [],
"state_transitions": []
"meta": {
"created": "2025-09-05T10:00:00Z",
"updated": "2025-09-07T10:00:00Z"
}
}
```
## Phase-Aware Session Management
## Simplified Phase Management
### Conceptual/Planning Phase
- Tracks planning document generation
- Monitors task decomposition progress
- Preserves planning context and decisions
- Safe interruption at document boundaries
### Phase-Level Tracking Only
- **Planning Phase**: Track completion status only
- **Implementation Phase**: Track active tasks, not detailed progress
- **Review Phase**: Track completion status only
### Implementation Phase
- Integrates with existing TodoWrite system
- Tracks agent progression and outputs
- Maintains file modification history
- Supports multi-agent coordination
### Minimal Checkpoint Strategy
- **Phase Transitions**: Save state when moving between phases
- **User Request**: Manual checkpoint on explicit user action
- **Session End**: Final state save before closing
### Review Phase
- Tracks validation and quality gates
- Preserves review comments and decisions
- Maintains compliance check status
## Automatic Checkpoints
### Checkpoint Triggers
- **Planning Phase**:
- After planning document completion
- After task breakdown generation
- On user interrupt request
- **Implementation Phase**:
- After agent completion
- At TodoWrite milestones
- After significant file changes
- On phase transitions
- **Review Phase**:
- After quality check completion
- On validation milestones
- At review agent boundaries
### Checkpoint Strategy
### Checkpoint Data (Minimal)
```json
{
"save_triggers": ["agent_complete", "todo_milestone", "user_interrupt"],
"save_data": ["agent_outputs", "file_changes", "todo_state"],
"resume_logic": "skip_completed_continue_sequence"
"save_triggers": ["phase_complete", "user_request", "session_end"],
"save_data": ["phase_status", "active_tasks", "session_meta"],
"resume_logic": "resume_from_last_phase_checkpoint"
}
```
## Cross-Phase Context Preservation
## Simplified Context Preservation
### Context Chain Maintenance
- All phase outputs preserved in session
- Context automatically transferred between phases
- Planning documents bridge PLAN → IMPLEMENT phases
- Implementation artifacts bridge IMPLEMENT → REVIEW
- Full audit trail maintained for decisions
### Essential Context Only
- Planning documents available to implementation phase
- Implementation results available to review phase
- Minimal handoff data between phases
### State Transitions
### Simple State Transitions
```json
{
"from": "PLAN",
"to": "IMPLEMENT",
"timestamp": "timestamp",
"trigger": "planning completion",
"handoff_data": {
"plan_path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
"tasks": ["task1", "task2"],
"complexity": "medium"
"phase_completed": "PLAN",
"next_phase": "IMPLEMENT",
"completed_at": "2025-09-07T10:00:00Z",
"artifacts": {
"plan_document": "IMPL_PLAN.md"
}
}
```
## Recovery Mechanisms
## Simplified Recovery
### Automatic Recovery Logic
### Basic Recovery Logic
```python
def resume_workflow():
session = load_session()
if session.current_phase == "PLAN":
resume_planning(session.checkpoints.plan)
check_plan_document_exists()
elif session.current_phase == "IMPLEMENT":
resume_implementation(session.checkpoints.implement)
load_active_tasks()
elif session.current_phase == "REVIEW":
resume_review(session.checkpoints.review)
check_implementation_complete()
```
### State Validation
- Verify required artifacts exist for resumption
- Check file system consistency with session state
- Validate TodoWrite synchronization
- Ensure agent context completeness
- Confirm phase prerequisites met
### Minimal State Validation
- Check current phase is valid
- Verify session directory exists
- Confirm basic file structure
### Recovery Strategies
- **Complete Recovery**: Full state restoration when possible
- **Partial Recovery**: Resume with warning when some data missing
- **Graceful Degradation**: Restart phase with maximum retained context
- **Manual Intervention**: Request user guidance for complex conflicts
### Simple Recovery Strategy
- **Phase Restart**: If unclear state, restart current phase
- **User Confirmation**: Ask user to confirm resume point
- **Minimal Recovery**: Restore basic session info only
## Agent Integration Protocol
## Simplified Agent Integration
### Required Agent Capabilities
All agents must support:
- Checkpoint save/load functionality
- State validation for resumption
- Context preservation across interrupts
- Progress reporting to session manager
### Minimal Agent Requirements
- Report task completion status
- Update task JSON files
- No complex checkpoint management needed
### Phase-Specific Integration
- **Planning Agents**: Auto-save planning outputs
- **Implementation Agents**: Track code changes and test results
- **Review Agents**: Preserve validation outcomes
### Phase Integration
- **Planning Agents**: Create planning documents
- **Implementation Agents**: Update task status to completed
- **Review Agents**: Mark review as complete
## Error Handling
### Common Scenarios
1. **Session File Corruption**:
- Automatic backup before each save
- Rollback to last known good state
- Recovery from planning documents
1. **Session File Missing**: Create new session file with defaults
2. **Invalid Phase State**: Reset to last known valid phase
3. **Multi-Session Conflicts**: Auto-resolve by latest timestamp
2. **Version Incompatibility**:
- Automatic migration for minor versions
- Manual intervention for major changes
- Backward compatibility for essential fields
## Session Lifecycle
3. **Missing Dependencies**:
- Graceful handling of missing files
- Regeneration of recoverable artifacts
- Clear error messages for resolution
### Simple Lifecycle
1. **Create**: Generate session ID and directory
2. **Activate**: Set as current active session
3. **Execute**: Track phase completion only
4. **Complete**: Mark as finished
4. **Multi-Session Conflicts**:
- Registry integrity validation
- Active session collision detection
- Automatic session status correction
## Session Lifecycle Management
### Complete Session Lifecycle
**1. Registration Phase**
- Add session to global registry (`.workflow/session_status.jsonl`)
- Generate unique session ID in WFS-[topic-slug] format
- Create session directory structure
**2. Activation Phase**
- Set session as active (deactivates any other active session)
- Initialize session state file (`workflow-session.json`)
- Create base directory structure based on complexity level
**3. Execution Phase**
- Track progress through workflow phases (PLAN → IMPLEMENT → REVIEW)
- Maintain checkpoints at natural boundaries
- Update session state with phase transitions and progress
**4. State Management Phase**
- **Active**: Session is currently being worked on
- **Paused**: Session temporarily suspended, can be resumed
- **Completed**: Session finished successfully
**5. Session Operations**
- **Switching**: Change active session (preserves state of previous)
- **Resumption**: Intelligent recovery from saved state and checkpoints
- **Interruption**: Graceful pause with complete state preservation
### Session State Transitions
### State Transitions
```
INACTIVE → ACTIVE → PAUSED → ACTIVE → COMPLETED
↑ ↓ ↓ ↑ ↓
CREATE PAUSE SWITCH RESUME ARCHIVE
INACTIVE → ACTIVE → COMPLETED
↑ ↓ ↓
CREATE WORK FINISH
```
## Implementation Guidelines
### Session Management Operations
### Testing Requirements
- Single-phase interruption/resumption
- Multi-phase workflow continuity
- Context preservation validation
- Error recovery scenarios
- Multi-session registry operations
- Session switching without data loss
- Active session inheritance in commands
- Registry integrity validation
- Version migration testing
### Key Principles
- **Minimal State**: Only track essential information
- **Phase-Level Updates**: Avoid frequent micro-updates
- **Simple Recovery**: Basic session restoration only
- **User Control**: Manual checkpoint requests
### Success Metrics
- Zero data loss on resume or session switch
- Context continuity maintained across sessions
- No duplicate work performed
- Full workflow completion capability
- Seamless multi-session management
- Registry integrity maintained
- Commands automatically inherit active session context
- Minimal performance overhead
- Fast session resume (< 1 second)
- Minimal file I/O operations
- Clear session state understanding
- No complex synchronization needed

188
.claude/workflows/task-decomposition-integration.md
View File

@@ -2,133 +2,103 @@
## Overview
This document defines simplified complexity classification and task hierarchy rules for the JSON-only workflow system.
This document defines authoritative complexity thresholds, decomposition triggers, and decision trees for workflow complexity classification.
## Simplified Complexity Classification
## Standardized Complexity Thresholds
### Simple Workflows
**Criteria**: Direct implementation tasks with clear scope
**Structure**: Single-level tasks (impl-N format)
**Task Files**: impl-*.json only
**Max Depth**: 1 level
### Simple Workflows (<5 tasks)
**Criteria**: Tasks < 5 AND modules ≤ 3 AND effort ≤ 4h
**Structure**: Minimal structure with basic task tracking
**Documents**: IMPL_PLAN.md only, no TODO_LIST.md
**Task Files**: impl-*.json (single level)
### Medium Workflows
**Criteria**: Feature implementation requiring task breakdown
**Structure**: Two-level hierarchy (impl-N.M format)
**Task Files**: Parent and child JSON files
**Max Depth**: 2 levels
### Medium Workflows (5-15 tasks)
**Criteria**: Tasks 5-15 OR modules > 3 OR effort > 4h OR complex dependencies
**Structure**: Enhanced structure with progress tracking
**Documents**: IMPL_PLAN.md + TODO_LIST.md (auto-triggered)
**Task Files**: impl-*.*.json (up to 2 levels)
### Complex Workflows
**Criteria**: System-wide changes requiring detailed decomposition
**Structure**: Three-level hierarchy (impl-N.M.P format)
**Task Files**: Multi-level JSON hierarchy
**Max Depth**: 3 levels (maximum allowed)
### Complex Workflows (>15 tasks)
**Criteria**: Tasks > 15 OR modules > 5 OR effort > 2 days OR multi-repository
**Structure**: Complete structure with comprehensive documentation
**Documents**: IMPL_PLAN.md + TODO_LIST.md + expanded documentation
**Task Files**: impl-*.*.*.json (up to 3 levels maximum)
## Task Hierarchy Rules
## Complexity Decision Tree
### Hierarchical ID Format
- **Level 1**: impl-N (main tasks)
- **Level 2**: impl-N.M (subtasks)
- **Level 3**: impl-N.M.P (detailed subtasks)
- **Maximum**: 3 levels deep
### Classification Algorithm
```
START: Analyze Workflow Requirements
↓
Count Tasks → Is Task Count < 5?
↓ YES ↓ NO
Count Modules Count Modules → > 5?
↓ ↓ YES
≤ 3 Modules? COMPLEX
↓ YES ↓ NO
Estimate Effort Estimate Effort → > 2 days?
↓ ↓ YES
≤ 4 hours? COMPLEX
↓ YES ↓ NO
SIMPLE Check Dependencies → Multi-repo?
↓ YES ↓ NO
COMPLEX MEDIUM
### Parent-Child Relationships
```json
// Parent task
{
"id": "impl-1",
"title": "Build authentication module",
"status": "pending",
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": []
}
}
// Child task
{
"id": "impl-1.1",
"title": "Design auth schema",
"status": "pending",
"relations": {
"parent": "impl-1",
"subtasks": [],
"dependencies": []
}
}
```
### Decision Matrix
## Decomposition Triggers
| **Factor** | **Simple** | **Medium** | **Complex** |
|------------|------------|------------|-------------|
| Task Count | < 5 | 5-15 | > 15 |
| Module Count | ≤ 3 | 4-5 | > 5 |
| Effort Estimate | ≤ 4h | 4h-2d | > 2d |
| Dependencies | Simple | Complex | Multi-repo |
| Repository Scope | Single | Single | Multiple |
### Automatic Decomposition When:
- Task title indicates multiple distinct activities
- Implementation scope spans multiple modules
- Clear sub-components can be identified
- Task complexity exceeds single-agent execution
### Threshold Priority
1. **Task Count**: Primary factor (most reliable predictor)
2. **Module Count**: Secondary factor (scope indicator)
3. **Effort Estimate**: Tertiary factor (complexity indicator)
4. **Dependencies**: Override factor (can force higher complexity)
### Skip Decomposition For:
- Single file modifications
- Simple bug fixes
- Clear, atomic tasks
- Documentation updates
## Automatic Document Generation Rules
### Generation Matrix
| **Complexity** | **IMPL_PLAN.md** | **TODO_LIST.md** | **Task Hierarchy** | **Structure** |
|----------------|------------------|------------------|-------------------|---------------|
| Simple | Always | No | 1 level | Minimal |
| Medium | Always | Auto-trigger | 2 levels | Enhanced |
| Complex | Always | Always | 3 levels | Complete |
### Auto-trigger Conditions
**TODO_LIST.md Generation** (Medium workflows):
- Tasks ≥ 5 OR modules > 3 OR effort > 4h OR dependencies complex
**Enhanced Structure** (Medium workflows):
- Progress tracking with hierarchical task breakdown
- Cross-references between planning and implementation
- Summary generation for major tasks
**Complete Structure** (Complex workflows):
- Comprehensive documentation suite
- Multi-level task decomposition
- Full progress monitoring and audit trail
## Task System Integration
### Hierarchical Task Schema
**Maximum Depth**: 3 levels (impl-N.M.P)
**Task File Structure**: Complexity determines maximum hierarchy depth
### Progress Calculation Rules
**Simple**: Linear progress through main tasks
**Medium**: Weighted progress with subtask consideration
**Complex**: Hierarchical progress with multi-level rollup
## Implementation Integration Rules
### Decomposition Triggers
**Automatic Decomposition Required When**:
- Task count exceeds complexity threshold (5+ for medium, 15+ for complex)
- Cross-module changes affect >3 modules
- Architecture pattern changes required
- Multi-repository impacts detected
- Complex interdependencies identified
### Direct Execution Conditions
**Skip Decomposition For**:
- Single module updates with clear boundaries
- Simple documentation changes
- Isolated bug fixes affecting <3 files
- Clear, well-defined maintenance tasks
## Task Status Rules
### Container Task Rules
- Parent tasks become "container" status when broken down
- Cannot be directly executed (must execute subtasks)
- Status derived from subtask completion
### Leaf Task Rules
- Only leaf tasks can be executed directly
- Status reflects actual execution state
- Progress tracked at leaf level only
## Validation Rules
### Complexity Classification Validation
1. **Threshold Verification**: Ensure task count, module count, and effort estimates align
2. **Override Checks**: Verify dependency complexity doesn't require higher classification
3. **Consistency Validation**: Confirm file structure matches complexity level
4. **Progress Calculation**: Validate progress tracking matches hierarchy depth
### Hierarchy Validation
1. **Depth Limit**: Maximum 3 levels (impl-N.M.P)
2. **ID Format**: Must follow hierarchical naming
3. **Parent References**: All parent IDs must exist
4. **Circular Dependencies**: Not allowed in hierarchy
### Quality Assurance
- Decomposition depth must not exceed 3 levels (impl-N.M.P maximum)
- Task hierarchy must be consistent across JSON files and TODO_LIST.md
- Complexity classification must align with document generation rules
- Auto-trigger conditions must be properly evaluated and documented
### Task Integrity
- All referenced tasks must exist as JSON files
- Parent-child relationships must be bidirectional
- Container tasks cannot have "completed" status until all children complete
- Leaf tasks must have valid execution status
---
**System ensures**: Consistent complexity classification with appropriate decomposition and structure scaling
**System ensures**: Consistent hierarchical decomposition within depth limits using JSON-only data model

412
.claude/workflows/task-management-principles.md
View File

@@ -2,396 +2,152 @@
## Overview
This document defines the simplified task system using JSON-only data storage with minimal structure and essential fields only.
This document provides complete technical implementation for the task system, including JSON schema, coordination rules, TodoWrite integration, and validation mechanisms.
## Unified Task JSON Schema
## Simplified Task JSON Schema
### Core Task Structure
All task files must conform to this schema with support for recursive decomposition:
All task files use this simplified 8-field schema:
```json
{
"id": "impl-1",
"parent_id": null,
"title": "Task title describing the work",
"type": "feature|bugfix|refactor|test|docs",
"status": "pending|active|completed|blocked|failed",
"priority": "low|normal|high|critical",
"agent": "code-developer|planning-agent|test-agent|review-agent",
"effort": "1h|2h|4h|1d|2d",
"title": "Build authentication module",
"status": "pending",
"type": "feature",
"agent": "code-developer",
"context": {
"inherited_from": "WFS-user-auth-system",
"requirements": ["Specific requirement 1", "Specific requirement 2"],
"scope": ["src/module/*", "tests/module/*"],
"acceptance": ["Success criteria 1", "Success criteria 2"]
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"dependencies": {
"upstream": ["impl-0"],
"downstream": ["impl-2", "impl-3"]
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
},
"subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"],
"execution": {
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"checkpoints": ["setup", "implement", "test", "validate"],
"completed_checkpoints": ["setup", "implement"]
},
"history": []
"attempts": 0,
"last_attempt": null
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T13:15:00Z",
"last_updated": "2025-09-05T13:15:00Z",
"version": "1.0"
"meta": {
"created": "2025-09-05T10:30:00Z",
"updated": "2025-09-05T10:30:00Z"
}
}
```
### Status Enumeration
Standard status values across all systems:
### Status Values
- **pending**: Task created but not started
- **active**: Task currently being worked on
- **completed**: Task successfully finished
- **blocked**: Task cannot proceed due to dependencies
- **failed**: Task attempted but failed execution
- **container**: Parent task with subtasks (not directly executable)
### Type Classification
Standard task types:
### Task Types
- **feature**: New functionality implementation
- **bugfix**: Fixing existing issues
- **refactor**: Code improvement without functionality change
- **test**: Test implementation or testing tasks
- **docs**: Documentation creation or updates
### Priority Levels
Standard priority values:
- **low**: Can be deferred
- **normal**: Standard priority (default)
- **high**: Should be completed soon
- **critical**: Must be completed immediately
## Context Management
## TodoWrite Integration System
### Context Structure
Context provides complete information for agent execution:
### TodoWrite Tool vs TODO_LIST.md File
**Clear Distinction**: TodoWrite is Claude's internal task tracking tool, TODO_LIST.md is the persistent workflow file
- **requirements**: Specific functional requirements
- **scope**: File patterns and modules affected
- **acceptance**: Success criteria and completion definition
- **inherited_from**: Source workflow or parent task
**TodoWrite Tool**:
- Claude's internal task management interface
- Real-time progress tracking during execution
- Temporary state for active workflow sessions
- Used by agents and commands for immediate task coordination
### Context Inheritance
- **Workflow → Task**: Global requirements and constraints
- **Parent → Subtask**: Refined scope and specific requirements
- **Context Preservation**: All fields maintained for agent execution
**TODO_LIST.md File**:
- Persistent task list stored in workflow session directory
- Cross-referenced with JSON task files
- Maintains task hierarchy and progress visualization
- Provides audit trail and resumable task state
## Task Relationships
### Synchronization Protocol
**TodoWrite → TODO_LIST.md**:
- TodoWrite task completion triggers TODO_LIST.md checkbox updates
- TodoWrite progress reflected in TODO_LIST.md progress calculations
- TodoWrite task status changes sync to JSON task files
**TODO_LIST.md → JSON Task Files**:
- Checkbox changes in TODO_LIST.md update JSON task status
- Manual task modifications propagate to JSON files
- Progress calculations derived from JSON task completion
**JSON Task Files → TodoWrite**:
- Task creation in JSON automatically creates TodoWrite entries when session is active
- JSON status changes reflect in TodoWrite display
- Agent task assignments sync to TodoWrite coordination
### Integration Rules
1. **Session Active**: TodoWrite automatically syncs with TODO_LIST.md
2. **Session Paused**: TodoWrite state preserved in TODO_LIST.md
3. **Session Resumed**: TodoWrite reconstructed from TODO_LIST.md and JSON files
4. **Cross-Session**: TODO_LIST.md provides continuity, TodoWrite provides active session interface
## Workflow Integration Schema
### Workflow Task Summary
Workflow session contains minimal task references with hierarchical support:
```json
{
"phases": {
"IMPLEMENT": {
"tasks": ["impl-1", "impl-2", "impl-3"],
"completed_tasks": ["impl-1"],
"blocked_tasks": [],
"progress": 33,
"task_depth": 2,
"last_sync": "2025-09-05T13:15:00Z"
}
}
}
```
### Task Reference Format
Tasks referenced by hierarchical ID, full details in JSON files:
```json
{
"task_summary": {
"id": "impl-1",
"parent_id": null,
"title": "Task title",
"status": "completed",
"type": "feature",
"depth": 1,
"progress": 100
}
}
// Subtask example
{
"task_summary": {
"id": "impl-1.2.1",
"parent_id": "impl-1.2",
"title": "Detailed subtask",
"status": "active",
"type": "implementation",
"depth": 3,
"progress": 45
}
}
```
## Data Ownership Rules
### JSON Task Files Own
- Complete task details and context (all levels)
- Execution history and checkpoints
- Parent-child relationships (via parent_id)
- Requirements and acceptance criteria
- Agent assignment and progress tracking
- Hierarchical decomposition state
### Workflow Session Owns
- Top-level task ID lists per phase
- Overall progress calculations
- Phase transition triggers
- Global context inheritance rules
- Task depth management (max 3 levels)
- Sync timestamps and validation
### Shared Responsibility
- Task status (JSON authoritative, TODO_LIST.md displays)
- Progress calculations (derived from JSON, shown in TODO_LIST.md)
- Hierarchical relationships (JSON defines, TODO_LIST.md visualizes)
- Dependency validation (cross-file consistency)
## Synchronization Principles
### Automatic Sync Triggers
- **Task Creation**: Add to workflow task list and TODO_LIST.md
- **Status Change**: Update TODO_LIST.md checkboxes and progress
- **Task Completion**: Update TODO_LIST.md and recalculate hierarchy progress
- **Task Decomposition**: Create child JSON files, update TODO_LIST.md structure
- **Context Update**: Propagate to child tasks in hierarchy
- **Dependency Change**: Validate across all hierarchy levels
### Sync Direction Rules
1. **JSON Task → TODO_LIST.md**: Status updates, progress changes, completion
2. **JSON Task → Workflow**: Task creation, hierarchy changes, phase completion
3. **IMPL_PLAN.md → JSON Task**: Context updates, requirement changes
4. **TODO_LIST.md → JSON Task**: Manual status changes via checkboxes
5. **Bidirectional**: Dependencies, timestamps, hierarchy validation
### Conflict Resolution
Priority order for conflicts:
1. **Most Recent**: Latest timestamp wins
2. **Task Authority**: Task files authoritative for task details
3. **Workflow Authority**: Workflow authoritative for phase management
4. **Manual Resolution**: User confirmation for complex conflicts
### Data Integrity Checks
- **ID Consistency**: All task IDs exist across JSON files and TODO_LIST.md
- **Hierarchy Validation**: Parent-child relationships are bidirectional and valid
- **Depth Limits**: No task exceeds 3 levels deep (impl-N.M.P max)
- **Status Validation**: Status values match enumeration across all files
- **Dependency Validation**: All dependencies exist and respect hierarchy
- **Progress Accuracy**: Calculated progress matches hierarchical task completion
- **Timestamp Ordering**: Created ≤ Started ≤ Completed across hierarchy
## Hierarchical Task Decomposition
### Decomposition Rules
**Maximum Depth**: 3 levels (impl-N.M.P)
- **Level 1** (impl-N): Main implementation tasks
- **Level 2** (impl-N.M): Subtasks with specific focus areas
- **Level 3** (impl-N.M.P): Detailed implementation steps
### Hierarchical Structure
- **Parent-Child**: Uses `relations.parent` and `relations.subtasks`
- **Dependencies**: Uses `relations.dependencies` for task ordering
- **Maximum Depth**: 3 levels (impl-N.M.P format)
### ID Format Standards
```
impl-1 # Main task
impl-1.1 # Subtask of impl-1
impl-1.1.1 # Detailed subtask of impl-1.1
impl-1.2 # Another subtask of impl-1
impl-2 # Another main task
```
### Parent-Child Relationships
```json
// Parent task (impl-1.json)
{
"id": "impl-1",
"parent_id": null,
"subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"]
}
// Child task (impl-1.1.json)
{
"id": "impl-1.1",
"parent_id": "impl-1",
"subtasks": ["impl-1.1.1", "impl-1.1.2"]
}
// Grandchild task (impl-1.1.1.json)
{
"id": "impl-1.1.1",
"parent_id": "impl-1.1",
"subtasks": [] // Leaf node - no further decomposition
}
```
### Progress Calculation
- **Leaf tasks**: Progress based on execution checkpoints
- **Container tasks**: Progress = average of all subtask progress
- **Workflow progress**: Weighted average of all top-level tasks
### Status Propagation Rules
- **Child → Parent**: Parent cannot be "completed" until all children complete
- **Parent → Child**: Parent "blocked" status may propagate to children
- **Sibling Independence**: Subtasks at same level operate independently
## Context Management
### Context Inheritance Chain
```
Workflow Context
↓ (inherits requirements, constraints)
Task Context
↓ (distributes scope, specific requirements)
Subtask Context
```
### Context Distribution Rules
- **Requirements**: Flow from workflow to tasks
- **Scope**: Refined at each level (workflow → task → subtask)
- **Constraints**: Apply globally from workflow
- **Acceptance Criteria**: Specific to each task level
### Dynamic Context Updates
- Changes in workflow context propagate to tasks
- Task-specific context remains isolated
- Subtask context inherits from parent task
- Context versioning tracks changes
## Agent Integration
### Agent Assignment Logic
Based on task type and complexity:
### Agent Assignment
Based on task type and title keywords:
- **Planning tasks** → planning-agent
- **Implementation** → code-developer
- **Testing** → test-agent
- **Documentation** → docs-agent
- **Review** → review-agent
### Execution Context Preparation
### Execution Context
Agents receive complete task JSON plus workflow context:
```json
{
"execution_context": {
"task": {
"id": "IMPL-001",
"requirements": ["from task context"],
"scope": ["from task context"]
},
"task": { /* complete task JSON */ },
"workflow": {
"session": "WFS-2025-001",
"phase": "IMPLEMENT",
"global_context": ["from workflow"]
},
"agent": {
"type": "code-developer",
"capabilities": ["coding", "testing"],
"context_optimizations": ["code_patterns"]
}
"session": "WFS-user-auth",
"phase": "IMPLEMENT"
}
}
```
## File Organization
### JSON Task Files
**Location**: `.task/impl-[id].json`
**Naming**: Follows hierarchical ID format
**Content**: Complete task definition
### Single Source of Truth
- JSON files contain all task data
- No document synchronization needed
- Views generated on-demand from JSON only
## Validation Rules
### Task Integrity
1. **ID Uniqueness**: All task IDs must be unique
2. **Hierarchical Format**: Must follow impl-N[.M[.P]] pattern
3. **Parent References**: All parent IDs must exist as JSON files
4. **Depth Limits**: Maximum 3 levels deep
5. **Status Consistency**: Status values from defined enumeration
6. **Required Fields**: All 8 core fields must be present
### Relationship Validation
- Parent-child relationships must be bidirectional
- Dependencies must reference existing tasks
- Container tasks cannot be completed until all subtasks complete
- No circular dependencies allowed
## Error Handling
### Common Error Scenarios
1. **JSON Task File Missing**: Recreate from TODO_LIST.md or parent task data
2. **Status Mismatch**: JSON files are authoritative, update TODO_LIST.md
3. **Hierarchy Broken**: Reconstruct parent-child relationships from IDs
4. **Invalid Dependencies**: Validate across all hierarchy levels
5. **Schema Version Mismatch**: Migrate to current hierarchical schema
6. **Orphaned Tasks**: Clean up or reassign to proper parent/workflow
7. **Depth Violation**: Flatten excessive hierarchy to 3 levels max
### Common Scenarios
1. **Missing JSON File**: Indicates broken reference - must repair
2. **Invalid Status**: Update to valid status value
3. **Broken Hierarchy**: Reconstruct parent-child relationships
4. **Orphaned Task**: Reassign to proper parent or workflow
### Recovery Strategies
- **Automatic Recovery**: For common, well-defined conflicts
### Recovery Strategy
- **JSON Authoritative**: Task JSON files are source of truth
- **Validation Warnings**: For non-critical inconsistencies
- **Manual Intervention**: For complex or ambiguous conflicts
- **Graceful Degradation**: Continue with best available data
- **Manual Resolution**: For complex relationship conflicts
### Validation Rules
- All task IDs must be unique and follow impl-N[.M[.P]] format
- Hierarchical IDs must have valid parent relationships
- Maximum depth of 3 levels (impl-N.M.P)
- Status values must be from defined enumeration
- Dependencies must reference existing tasks at appropriate levels
- Parent tasks cannot be completed until all subtasks complete
- Timestamps must be chronologically ordered
- Required fields cannot be null or empty
---
## Implementation Guidelines
### File Organization
```
.task/
├── impl-1.json # Main task
├── impl-1.1.json # Level 2 subtask
├── impl-1.1.1.json # Level 3 detailed subtask
├── impl-1.2.json # Level 2 subtask
└── impl-2.json # Another main task
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Master session
├── IMPL_PLAN.md # Planning document
└── TODO_LIST.md # Progress tracking and task registry
```
### Performance Considerations
- **Lazy Loading**: Load task details only when needed
- **Batch Operations**: Group sync operations for efficiency
- **Incremental Updates**: Only sync changed data
- **Cache Management**: Cache frequently accessed task data
### Testing Requirements
- Schema validation for all task operations
- Sync consistency across workflow/task boundaries
- Error recovery scenario testing
- Performance testing with multiple tasks
- Concurrent access handling
### Success Metrics
- Zero data loss during sync operations
- Consistent task status across systems
- Fast task operations (< 100ms for single task)
- Reliable error recovery
- Complete audit trail of changes
**System ensures**: Consistent task management using simplified JSON-only data model with complete context preservation for agent execution

204
.claude/workflows/todowrite-coordination-rules.md
View File

@@ -28,207 +28,3 @@ This document defines the complete coordination system between Claude's TodoWrit
4. **Single Active Rule** - Only one todo in_progress at any time
5. **Completion Gates** - Mark completed only when truly finished
6. **Persistence Sync** - TodoWrite changes trigger workflow file updates
### Integration Architecture
```
TodoWrite Tool (Claude Internal)
↕ Real-time sync
TODO_LIST.md (Workflow Persistence)
↕ Bidirectional updates
JSON Task Files (Detailed State)
↕ Status propagation
Workflow Session (Master State)
```
## Mandatory TodoWrite Creation
### Pre-execution Requirements
Every workflow execution MUST create TodoWrite entries before agent coordination begins.
**Workflow Initialization**:
1. Analyze workflow complexity
2. Create appropriate TodoWrite pattern based on complexity
3. Initialize TODO_LIST.md file if complexity warrants it
4. Begin agent coordination with TodoWrite context
### Agent Handoff Protocol
**Agent → TodoWrite**:
- Agents receive TodoWrite context on initialization
- Agents update todo status in real-time during execution
- Agents mark completion only when truly finished
- Agents create new todos when discovering additional work
## TodoWrite Patterns by Complexity
### Simple Workflows (3-4 todos)
**Pattern**: Linear execution with minimal tracking
```
1. [pending] Context gathering
2. [pending] Solution implementation
3. [pending] Code review and validation
4. [pending] Task completion
```
**Coordination**: Direct TodoWrite → JSON files (no TODO_LIST.md)
### Medium Workflows (5-7 todos)
**Pattern**: Structured execution with progress tracking
```
1. [pending] Implementation planning
2. [pending] Context gathering
3. [pending] Implementation with testing
4. [pending] Functionality validation
5. [pending] Code quality review
6. [pending] Task completion
```
**Coordination**: TodoWrite ↔ TODO_LIST.md ↔ JSON files
### Complex Workflows (7-10 todos)
**Pattern**: Comprehensive execution with full documentation
```
1. [pending] Detailed planning
2. [pending] Documentation generation
3. [pending] Context and dependency gathering
4. [pending] Comprehensive implementation
5. [pending] Acceptance criteria validation
6. [pending] Thorough review process
7. [pending] Feedback iteration
8. [pending] Task completion
```
**Coordination**: Full three-way sync with audit trails
## Synchronization Protocols
### TodoWrite → TODO_LIST.md Sync
**Trigger Events**:
- Todo status change (pending → active → completed)
- Todo creation during workflow execution
- Todo blocking/unblocking status changes
- Progress milestone achievement
**Sync Actions**:
- Update TODO_LIST.md checkbox states
- Recalculate progress percentages
- Update task status summaries
- Propagate completion timestamps
### TODO_LIST.md → TodoWrite Sync
**Trigger Events**:
- Manual checkbox modification in TODO_LIST.md
- External task status updates
- Workflow resumption from paused state
- Cross-session task inheritance
**Sync Actions**:
- Reconstruct TodoWrite state from TODO_LIST.md
- Initialize appropriate todo patterns
- Restore progress tracking context
- Re-establish agent coordination context
### Bidirectional JSON Integration
**TodoWrite → JSON**:
- Task completion triggers JSON status updates
- Progress checkpoints sync to JSON execution state
- Agent assignments propagate to JSON context
**JSON → TodoWrite**:
- JSON task creation generates TodoWrite entries
- JSON status changes reflect in TodoWrite display
- JSON dependency updates trigger TodoWrite coordination
## State Management Rules
### Session Lifecycle Integration
**Active Session**:
- TodoWrite automatically syncs with workflow session
- Real-time updates propagate to persistent files
- Progress tracking maintains workflow continuity
**Session Pause**:
- TodoWrite state preserved in TODO_LIST.md
- JSON files maintain detailed task context
- Workflow session tracks overall progress
**Session Resume**:
- TodoWrite reconstructed from TODO_LIST.md + JSON files
- Previous progress state fully restored
- Agent context re-established from preserved state
**Session Switch**:
- Current TodoWrite state saved to workflow files
- New session TodoWrite initialized from target session files
- Seamless context switching without data loss
### Progress Calculation Rules
**Simple Workflows**: Progress = completed todos / total todos
**Medium Workflows**: Progress = weighted completion across todo + subtask hierarchy
**Complex Workflows**: Progress = multi-level rollup with checkpoint weighting
### Blocking and Dependency Management
**Todo Blocking**:
- Blocked todos tracked with resolution requirements
- Upstream dependencies prevent todo activation
- Dependency resolution automatically unblocks downstream todos
**Cross-Todo Dependencies**:
- TodoWrite enforces dependency order
- JSON files maintain dependency graph
- TODO_LIST.md visualizes dependency relationships
## Error Handling and Recovery
### TodoWrite State Corruption
**Recovery Strategy**:
1. Attempt to reconstruct from TODO_LIST.md
2. Fallback to JSON file task status
3. Last resort: regenerate from workflow session state
4. Manual intervention if all sources inconsistent
### Sync Conflict Resolution
**Priority Order**:
1. **TodoWrite** (most recent user interaction)
2. **JSON Files** (authoritative task state)
3. **TODO_LIST.md** (persistence layer)
4. **Manual Resolution** (complex conflicts)
### Validation Rules
- Todo IDs must map to valid JSON task IDs
- Todo status must be consistent across all coordination layers
- Progress calculations must align with actual task completion
- Single active todo rule must be enforced at all times
## Integration with Specialized Systems
### Task Management Integration
**Hierarchical Support**: TodoWrite flattens task hierarchy for execution view
**Status Synchronization**: Bidirectional sync with JSON task status
### Session Management Integration
**Multi-Session Support**: TodoWrite aware of active session context
**Context Switching**: Seamless integration with session switching
### Complexity Classification Integration
**Pattern Selection**: TodoWrite patterns match complexity classification
**Auto-scaling**: TodoWrite patterns adapt to workflow complexity changes
## Quality Assurance
### Mandatory Validation Checks
- TodoWrite entries exist before agent coordination
- Single active todo rule maintained throughout execution
- Progress tracking accuracy across all coordination layers
- Completion gates properly validated before marking tasks complete
- Sync consistency across TodoWrite, TODO_LIST.md, and JSON files
### Performance Requirements
- TodoWrite updates must be real-time (< 100ms response)
- Sync operations must complete within 500ms
- Progress calculation must be immediate
- Context switching must preserve full state
---
**System ensures**: Seamless coordination between TodoWrite tool interface and persistent workflow state with real-time progress tracking and reliable state management