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

533
.claude/commands/context.md
View File

@@ -1,344 +1,259 @@
--- ---
name: context name: context
description: Unified context command - Single source of truth for all workflow and task status information description: Generate on-demand views from JSON task data
usage: /context [task-id] [--format=<tree|list|json|progress>] [--health-check] [--detailed] [--export] usage: /context [task-id] [--format=<format>] [--validate]
argument-hint: [optional task-id] [display format] [analysis options] [export flag] argument-hint: [optional: task-id, format, validation]
examples: examples:
- /context - /context
- /context IMPL-001 - /context impl-1
- /context --format=tree - /context --format=hierarchy
- /context --health-check - /context --validate
- /context --detailed --export
- /context --format=progress
--- ---
# Unified Context Command (/context) # Context Command (/context)
## Overview ## 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 ### Pure View Generation
- **JSON Authority**: All data read from `.task/*.json` and `workflow-session.json` files - **No Sync**: Views are generated, not synchronized
- **Generated Views**: All markdown displays generated on-demand (never manually edited) - **Always Current**: Reads latest JSON data every time
- **No Synchronization**: Documents are views, not synchronized states - **No Persistence**: Views are temporary, not saved
- **Conflict-Free**: Single direction data flow eliminates conflicts - **Single Source**: All data comes from JSON files only
### Unified Command Interface ### Multiple View Formats
- **Global Context**: `/context` shows complete workflow status - **Overview** (default): Current tasks and status
- **Task-Specific**: `/context IMPL-001` shows individual task details - **Hierarchy**: Task relationships and structure
- **Health Checking**: `/context --health-check` validates JSON data integrity - **Details**: Specific task information
- **Multiple Formats**: Tree, list, progress, and JSON output formats
## Usage Modes ## Usage
### 1. Global Workflow Context (Default) ### Default Overview
```bash ```bash
/context /context
``` ```
**Generated Output** (from JSON data): Generates current workflow overview:
```
🔍 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):
```markdown ```markdown
# Workflow Context Report # Workflow Overview
*Generated: 2025-09-07 16:15:00 from JSON data sources* **Session**: WFS-user-auth
**Phase**: IMPLEMENT
**Type**: medium
## Data Sources ## Active Tasks
- workflow-session.json (last updated: 2025-09-07T15:45:00Z) - [⚠️] impl-1: Build authentication module (code-developer)
- 5 task JSON files in .task/ directory - [⚠️] impl-2: Setup user management (code-developer)
- All sources validated and consistent
## Session Overview ## Completed Tasks
[Generated from workflow-session.json] - [✅] impl-0: Project setup
## Task Analysis ## Stats
[Generated from .task/*.json files] - **Total**: 8 tasks
- **Completed**: 3
## Health Assessment - **Active**: 2
[Validated from JSON data integrity] - **Remaining**: 3
---
*This report is a generated view from authoritative JSON data*
*No manual editing required - data updates automatically in JSON files*
``` ```
## Advanced Features ### Specific Task View
### JSON Output for Scripting
```bash ```bash
/context --format=json /context impl-1
``` ```
**Generated JSON** (compiled from all sources): Shows detailed task information:
```json ```markdown
{ # Task: impl-1
"session": {
"id": "WFS-workflow-optimization", **Title**: Build authentication module
"status": "active", **Status**: active
"phase": "implement", **Agent**: code-developer
"progress": 40, **Type**: feature
"data_source": "workflow-session.json"
}, ## Context
"tasks": [ - **Requirements**: JWT authentication, OAuth2 support
{ - **Scope**: src/auth/*, tests/auth/*
"id": "IMPL-001", - **Acceptance**: Module handles JWT tokens, OAuth2 flow implemented
"status": "completed", - **Inherited From**: WFS-user-auth
"progress": 100,
"data_source": ".task/impl-001.json" ## Relations
} - **Parent**: none
], - **Subtasks**: impl-1.1, impl-1.2
"health": { - **Dependencies**: impl-0
"json_integrity": 100,
"data_consistency": 100, ## Execution
"completeness": 100 - **Attempts**: 0
}, - **Last Attempt**: never
"generated_at": "2025-09-07T16:15:00Z",
"data_freshness": "current" ## Metadata
} - **Created**: 2025-09-05T10:30:00Z
- **Updated**: 2025-09-05T10:35:00Z
``` ```
### Health Check Integration ### Hierarchy View
- **Validation Engine**: Checks all JSON files for schema compliance ```bash
- **Consistency Verification**: Validates cross-references between files /context --format=hierarchy
- **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)
``` ```
### View Generation Process Shows task relationships:
1. **Load JSON Data**: Read all relevant JSON files ```markdown
2. **Validate Data**: Check integrity and consistency # Task Hierarchy
3. **Calculate Views**: Generate requested format/content
4. **Format Output**: Apply formatting and display
5. **Export (Optional)**: Save generated views to files
### Error Handling ## Main Tasks
- **Missing Files**: Clear error messages with recovery suggestions - impl-0: Project setup ✅
- **Invalid JSON**: Schema validation with specific error details - impl-1: Build authentication module ⚠️
- **Broken References**: Dependency validation with repair recommendations - impl-1.1: Design auth schema
- **Data Inconsistencies**: Automatic detection and resolution suggestions - 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 ## View Generation Process
- 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
### 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.

384
.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 - **Context Distribution**: Subtasks inherit parent context
- **Agent Mapping**: Automatic agent assignment per subtask - **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) - **JSON Task Hierarchy**: Creates hierarchical JSON subtasks (impl-N.M.P)
- **TODO_LIST.md Integration**: Automatically updates progress display with new subtask structure - **Context Distribution**: Subtasks inherit parent context
- **TODO_LIST.md Maintenance**: Updates task hierarchy display with parent-child relationships - **Basic Status Tracking**: Updates task relationships only
- **Context Distribution**: Subtasks inherit and refine parent context - **No Complex Synchronization**: Simple parent-child relationships
- **Progress Synchronization**: Updates hierarchical progress calculations in TODO_LIST.md
- **No External Commands**: All task operations are internal to this command
### Breakdown Rules ### Breakdown Rules
- Only `pending` tasks can be broken down - Only `pending` tasks can be broken down
- Parent becomes container (not directly executable) - 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) - Maximum depth: 3 levels (impl-N.M.P)
- Parent task progress = average of subtask progress - Parent-child relationships tracked in JSON only
- Automatically updates TODO_LIST.md with hierarchical structure
## Usage ## Usage
@@ -56,10 +53,9 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic
/task:breakdown IMPL-1 /task:breakdown IMPL-1
``` ```
Interactive prompt with automatic task management: Interactive prompt:
``` ```
Task: Build authentication module Task: Build authentication module
Workflow: 28 total tasks (Complex workflow detected)
Suggested subtasks: Suggested subtasks:
1. Design authentication schema 1. Design authentication schema
@@ -67,40 +63,33 @@ Suggested subtasks:
3. Add JWT token handling 3. Add JWT token handling
4. Write unit tests 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 Accept task breakdown? (y/n/edit): y
``` ```
### Auto Strategy with Override Options ### Auto Strategy
```bash ```bash
/task:breakdown IMPL-1 --strategy=auto /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
``` ```
Automatic generation: Automatic generation:
``` ```
✅ Task IMPL-1 broken down: ✅ Task impl-1 broken down:
├── IMPL-1.1: Design authentication schema ├── impl-1.1: Design authentication schema
├── IMPL-1.2: Implement core auth logic ├── impl-1.2: Implement core auth logic
├── IMPL-1.3: Add security middleware ├── impl-1.3: Add security middleware
└── IMPL-1.4: Write comprehensive tests └── impl-1.4: Write comprehensive tests
Agents assigned: Agents assigned:
- IMPL-1.1 → planning-agent - impl-1.1 → planning-agent
- IMPL-1.2 → code-developer - impl-1.2 → code-developer
- IMPL-1.3 → code-developer - impl-1.3 → code-developer
- IMPL-1.4 → test-agent - impl-1.4 → test-agent
📄 Internal task processing: JSON files created:
- JSON subtasks: IMPL-1.1, IMPL-1.2, IMPL-1.3, IMPL-1.4 created - .task/impl-1.1.json
- Task structure: Level 2 hierarchy established through embedded logic - .task/impl-1.2.json
- Progress tracking: TODO_LIST.md updated with hierarchical progress display - .task/impl-1.3.json
- Cross-references: All task links generated and validated internally - .task/impl-1.4.json
``` ```
## Decomposition Patterns ## Decomposition Patterns
@@ -140,25 +129,30 @@ Parent context is intelligently distributed:
```json ```json
{ {
"parent": { "parent": {
"id": "IMPL-1", "id": "impl-1",
"context": { "context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT auth", "2FA support"], "requirements": ["JWT auth", "2FA support"],
"scope": ["src/auth/*"], "scope": ["src/auth/*"],
"acceptance": ["Authentication system works"] "acceptance": ["Authentication system works"],
"inherited_from": "WFS-user-auth"
} }
}, },
"subtasks": [ "subtasks": [
{ {
"id": "IMPL-1.1", "id": "impl-1.1",
"title": "Design authentication schema", "title": "Design authentication schema",
"status": "pending", "status": "pending",
"agent": "planning-agent", "agent": "planning-agent",
"context": { "context": {
"inherited_from": "IMPL-1",
"requirements": ["JWT auth schema", "User model design"], "requirements": ["JWT auth schema", "User model design"],
"scope": ["src/auth/models/*"], "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 ### Post-breakdown Actions
1. Update parent status to `container` 1. Update parent status to `container`
2. Create subtask JSON files with document references 2. Create subtask JSON files
3. Update IMPL_PLAN.md with enhanced task hierarchy structure 3. Update parent task with subtask references
4. Create/update TODO_LIST.md with progress tracking 4. Update workflow session stats
5. Update workflow session with document references
6. Validate phase alignment with IMPL_PLAN.md (if exists)
7. Generate execution plan with document coordination
## Execution Planning ## Simple File Management
After breakdown, generates execution order: ### File Structure Created
```
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)
``` ```
.workflow/WFS-[topic-slug]/ .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 ├── workflow-session.json # Session state
├── IMPL_PLAN.md # Static planning document
└── .task/ └── .task/
├── IMPL-1.json # Parent task (container) ├── impl-1.json # Parent task (container)
├── IMPL-1.1.json # Subtask 1 ├── impl-1.1.json # Subtask 1
└── IMPL-1.2.json # Subtask 2 └── impl-1.2.json # Subtask 2
``` ```
#### Level 1: Enhanced Structure (5-15 tasks) ### Output Files
``` - JSON subtask files in `.task/` directory
.workflow/WFS-[topic-slug]/ - Updated parent task JSON with subtask references
├── workflow-session.json - Updated session stats in `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
## Examples ## Examples
### Complex Feature ### Simple Breakdown
```bash ```bash
/task:breakdown IMPL-1 --strategy=auto --depth=2 /task:breakdown impl-1
Result: Result:
IMPL-1: E-commerce checkout impl-1: Build authentication (container)
├── IMPL-1.1: Payment processing ├── impl-1.1: Design auth schema
│ ├── IMPL-1.1.1: Integrate payment gateway ├── impl-1.2: Implement auth logic
│ ├── IMPL-1.1.2: Handle transactions ├── impl-1.3: Add security middleware
│ └── IMPL-1.1.3: Add error handling └── impl-1.4: Write tests
├── IMPL-1.2: Order management ```
│ ├── IMPL-1.2.1: Create order model
│ └── IMPL-1.2.2: Implement order workflow ### Two-Level Breakdown
└── IMPL-1.3: Testing suite ```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 ## Related Commands
- `/task:create` - Create new tasks - `/task:create` - Create new tasks
- `/task:context` - Manage task context - `/task:execute` - Execute subtasks
- `/task:execute` - Execute subtasks - `/context` - View task hierarchy
- `/task:replan` - Adjust breakdown
- `/task:status` - View task hierarchy

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

@@ -68,234 +68,94 @@ Context inherited from workflow
- `test` - Test implementation - `test` - Test implementation
- `docs` - Documentation - `docs` - Documentation
### Priority Levels ### Priority Levels (Optional - moved to context)
- `low` - Can be deferred - `low` - Can be deferred
- `normal` - Standard priority (default) - `normal` - Standard priority (default)
- `high` - Should be done soon - `high` - Should be done soon
- `critical` - Must be done immediately - `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 ```json
{ {
"id": "impl-1", "id": "impl-1",
"parent_id": null,
"title": "Build authentication module", "title": "Build authentication module",
"type": "feature",
"priority": "normal",
"status": "pending", "status": "pending",
"depth": 1, "type": "feature",
"agent": "code-developer", "agent": "code-developer",
"effort": "4h",
"context": { "context": {
"inherited_from": "WFS-user-auth-system",
"requirements": ["JWT authentication", "OAuth2 support"], "requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"], "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"
}, },
"dependencies": { "relations": {
"upstream": [], "parent": null,
"downstream": [], "subtasks": [],
"parent_dependencies": [] "dependencies": []
}, },
"subtasks": [],
"execution": { "execution": {
"attempts": 0, "attempts": 0,
"current_attempt": null, "last_attempt": null
"history": []
}, },
"metadata": { "meta": {
"created_at": "2025-09-05T10:30:00Z", "created": "2025-09-05T10:30:00Z",
"started_at": null, "updated": "2025-09-05T10:30:00Z"
"completed_at": null,
"last_updated": "2025-09-05T10:30:00Z",
"version": "1.0"
} }
} }
``` ```
## Document Integration Features ## Simplified File Generation
### JSON Task File Generation ### JSON Task File Only
**File Location**: `.workflow/WFS-[topic-slug]/.task/impl-[N].json` **File Location**: `.task/impl-[N].json`
**Hierarchical Naming**: Follows impl-N.M.P format for nested tasks **Naming**: Follows impl-N.M.P format for nested tasks
**Schema Compliance**: All JSON files follow unified task schema from task-management-principles.md **Content**: Contains all task data (no document coordination needed)
### Import from IMPL_PLAN.md ### No Document Synchronization
```bash - Creates JSON task file only
/task:create --from-plan - 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 1. Create New Task → Generate JSON file only
- Creates JSON task files based on planned structure 2. Update Session Stats → Increment task count
- Maintains hierarchical relationships in JSON format 3. Notify User → Confirm task created
- 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
``` ```
### Escalation Triggers ### Benefits of Simplification
- **No Overhead**: Just create tasks, no complex logic
#### Simple → Medium Escalation - **Predictable**: Same process every time
**Triggered when ANY condition met:** - **Fast**: Minimal processing needed
- Task count reaches 5 (primary trigger) - **Clear**: User controls complexity level
- 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
## Context Inheritance ## Context Inheritance
Tasks automatically inherit: Tasks automatically inherit:
1. **Requirements** - From workflow-session.json context and IMPL_PLAN.md 1. **Requirements** - From workflow-session.json and IMPL_PLAN.md
2. **Scope** - File patterns from workflow and IMPL_PLAN.md strategy 2. **Scope** - File patterns from workflow context
3. **Standards** - Quality standards from workflow session 3. **Parent Context** - When created as subtasks, inherit from parent
4. **Dependencies** - Related tasks from existing JSON task hierarchy in `.task/` 4. **Session Context** - Global workflow context from active session
5. **Parent Context** - When created as subtasks, inherit from parent JSON file
6. **Session Context** - Global workflow context from active session
## Smart Suggestions ## Smart Suggestions
@@ -358,46 +218,29 @@ Created 3 tasks:
- impl-3: Write authentication tests - impl-3: Write authentication tests
``` ```
## File Output Management ## File Output
### JSON Task Files ### JSON Task File
**Output Location**: `.workflow/WFS-[topic-slug]/.task/impl-[id].json` **Location**: `.task/impl-[id].json`
**Schema**: Follows unified task JSON schema with hierarchical support **Schema**: Simplified task JSON schema
**Contents**: Complete task definition including context, dependencies, and metadata **Contents**: Complete task definition with context
### TODO_LIST.md Generation ### Session Updates
**Trigger Logic**: Auto-created based on complexity thresholds **File**: `workflow-session.json`
**Location**: `.workflow/WFS-[topic-slug]/TODO_LIST.md` **Updates**: Basic task count and active task list only
**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
## Integration ## Integration
### Workflow Integration ### Simple Integration
- Updates workflow-session.json with new task references - Updates workflow-session.json stats
- Increments task counter and updates complexity assessment - Creates JSON task file
- Updates IMPLEMENT phase progress and task hierarchy depth - No complex file coordination needed
- 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
### Next Steps ### Next Steps
After creation, use: After creation, use:
- `/task:breakdown` - Split into hierarchical subtasks with JSON files - `/task:breakdown` - Split into subtasks
- `/task:execute` - Run the task with summary generation - `/task:execute` - Run the task
- `/context` - View task details, status and relationships - `/context` - View task details and status
## Examples ## 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. - **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. - **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 ```json
{ {
"task": { "task": {
"id": "IMPL-001", "id": "impl-1",
"title": "Build authentication module", "title": "Build authentication module",
"type": "feature", "type": "feature",
"status": "active", "status": "active",
"agent": "code-developer", "agent": "code-developer",
"context": { "context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT authentication", "OAuth2 support"], "requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"], "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": { "workflow": {
"session": "WFS-[topic-slug]", "session": "WFS-user-auth",
"phase": "IMPLEMENT", "phase": "IMPLEMENT"
"global_context": ["Security first", "Backward compatible"]
}, },
"execution": { "execution": {
"agent": "code-developer", "agent": "code-developer",
"mode": "auto", "mode": "auto",
"checkpoints": ["setup", "implement", "test", "validate"], "attempts": 0
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"completed_checkpoints": ["setup"]
}
} }
} }
``` ```
@@ -180,37 +179,28 @@ Different agents receive context tailored to their function:
- **`test-agent`**: Test requirements, code to be tested, coverage goals. - **`test-agent`**: Test requirements, code to be tested, coverage goals.
- **`review-agent`**: Quality standards, style guides, review criteria. - **`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. - **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
- **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`)**: Updated task stats (completed count).
- **Session File (`workflow-session.json`)**: Task completion status and overall phase progress are updated. - **Summary File**: Generated in `.summaries/` upon completion (optional).
- **Summary File**: Generated in `.workflow/WFS-[...]/summaries/` upon successful completion.
### 📝 **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 ```markdown
# Task Summary: IMPL-001 Build Authentication Module # Task Summary: impl-1 Build Authentication Module
## What Was Done ## What Was Done
- Created src/auth/login.ts with JWT validation - Created src/auth/login.ts with JWT validation
- Modified src/auth/validate.ts for enhanced security - Added tests in tests/auth.test.ts
- Added comprehensive tests in tests/auth.test.ts
## Execution Results ## Execution Results
- **Duration**: 23 minutes
- **Agent**: code-developer - **Agent**: code-developer
- **Tests Passed**: 12/12 (100%) - **Status**: completed
- **Coverage**: 87%
## Files Modified ## Files Modified
- `src/auth/login.ts` (created) - `src/auth/login.ts` (created)
- `src/auth/validate.ts` (modified)
- `tests/auth.test.ts` (created) - `tests/auth.test.ts` (created)
## Links
- [🔙 Back to Task List](../TODO_LIST.md#impl-001)
- [📌 Task Details](../.task/impl-001.json)
``` ```

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

@@ -1,466 +1,518 @@
--- ---
name: task-replan name: task-replan
description: Dynamically replan tasks based on changes, blockers, or new requirements description: Replan individual tasks with detailed user input and change tracking
usage: /task:replan [task-id|--all] [--reason=<reason>] [--strategy=<adjust|rebuild>] usage: /task:replan <task-id> [input-source]
argument-hint: [task-id or --all] [optional: reason and strategy] argument-hint: task-id [text|--from-file|--from-issue|--detailed|--interactive]
examples: examples:
- /task:replan IMPL-001 --reason="requirements changed" - /task:replan impl-1 "Add OAuth2 authentication support"
- /task:replan --all --reason="new security requirements" - /task:replan impl-1 --from-file updated-specs.md
- /task:replan IMPL-003 --strategy=rebuild - /task:replan impl-1 --from-issue ISS-001
- /task:replan impl-1 --detailed
- /task:replan impl-1 --interactive
--- ---
# Task Replan Command (/task:replan) # Task Replan Command (/task:replan)
## Overview ## 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 ## 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 ### Direct Text Input (Default)
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
```bash ```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 ### 2. Input Processing
```
### 1. Adjust Strategy (Default) Detect Input Type → Identify source type
Minimal changes to existing plan: Extract Requirements → Parse change requirements
```bash Analyze Impact → Determine modifications needed
/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. Rebuild Strategy ### 3. Version Management
Complete replanning from scratch: ```
```bash Create Version → Backup current task state
/task:replan IMPL-001 --strategy=rebuild Update Version → Increment task version number
Archive → Store previous version in versions/
Rebuilding IMPL-001:
- Analyzing new requirements
- Generating new breakdown
- Reassigning agents
- New execution plan created
``` ```
## Usage Scenarios ### 4. Task Structure Updates
```
### Scenario 1: Requirements Change Modify Task → Update task JSON structure
```bash Update Subtasks → Add/remove/modify as needed
/task:replan IMPL-001 --reason="Added OAuth2 requirement" Update Relations → Fix dependencies and hierarchy
Update Context → Modify requirements and scope
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
``` ```
### Scenario 2: Blocked Task ### 5. Document Synchronization
```bash ```
/task:replan IMPL-003 --reason="API not ready" Update IMPL_PLAN → Regenerate task section
Update TODO_LIST → Sync task hierarchy (if exists)
Task blocked analysis: Update Session → Reflect changes in workflow state
- 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
``` ```
### Scenario 3: Failed Execution ### 6. Change Documentation
```bash ```
/task:replan IMPL-002 --reason="execution failed" Create Change Log → Document all modifications
Generate Summary → Create replan report
Failure analysis: Update History → Add to task replan history
- 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
``` ```
## Global Replanning ## Version Management (Simplified)
### Replan All Tasks ### Version Tracking
```bash Each replan creates a new version with complete history:
/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
```json ```json
{ {
"task_id": "impl-001", "id": "impl-1",
"title": "Build authentication module", "title": "Build authentication module",
"status": "active",
"version": "1.2", "version": "1.2",
"replan_history": [ "replan_history": [
{ {
"version": "1.2", "version": "1.1",
"timestamp": "2025-09-07T16:00:00Z", "date": "2025-09-08T10:00:00Z",
"reason": "API changes", "reason": "Original plan",
"changes_summary": "Added API endpoint handling, removed deprecated auth flow", "input_source": "initial_creation"
"backup_location": ".task/archive/impl-001-v1.1-backup.json", },
"documentation": ".summaries/replan-impl-001-20250907-160000.md", {
"files_affected": [ "version": "1.2",
{ "date": "2025-09-08T14:00:00Z",
"action": "created", "reason": "Add OAuth2 authentication support",
"file": ".task/impl-001.4.json", "input_source": "direct_text",
"description": "New API endpoint handling subtask" "changes": [
}, "Added subtask impl-1.3: OAuth2 integration",
{ "Added subtask impl-1.4: Token management",
"action": "modified", "Modified scope to include external auth"
"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, "backup_location": ".task/versions/impl-1-v1.1.json"
"session_updated": true
} }
], ],
"context": {
"subtasks": ["impl-001.1", "impl-001.2", "impl-001.4"], "requirements": ["Basic auth", "Session mgmt", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"metadata": { "acceptance": ["All auth methods work"]
"version": "1.2",
"last_updated": "2025-09-07T16:00:00Z",
"last_replan": "2025-09-07T16:00:00Z",
"replan_count": 2
} }
} }
``` ```
## File System Integration ### File Structure After Replan
```
### Comprehensive File Updates .task/
**Multi-File Synchronization**: Ensures consistency across all workflow files ├── impl-1.json # Current version (1.2)
├── impl-1.3.json # New subtask
#### JSON Task File Management ├── impl-1.4.json # New subtask
- **Version Backups**: Automatic backup before major changes ├── versions/
- **Hierarchical Updates**: Cascading changes through parent-child relationships │ └── impl-1-v1.1.json # Previous version backup
- **Archive Management**: Deprecated task files moved to `.task/archive/` └── summaries/
- **Metadata Tracking**: Complete change history in JSON metadata └── replan-impl-1-20250908.md # Change log
#### 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
``` ```
#### Workflow Session Updates ## IMPL_PLAN.md 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
### Documentation Generation ### Automatic Plan Regeneration
**Automatic Report Creation**: Every replan generates documentation When task is replanned, the corresponding section in IMPL_PLAN.md is updated:
- **Replan Report**: `.summaries/replan-[task-id]-[timestamp].md` **Before Replan**:
- **Change Summary**: Detailed before/after comparison ```markdown
- **Impact Analysis**: Effects on timeline, dependencies, resources ## Task Breakdown
- **File Change Log**: Complete list of affected files - **IMPL-001**: Build authentication module
- **Rollback Instructions**: How to revert changes if needed - 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 ```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... Loading issue ISS-001...
Issue: "Login timeout too short" Issue: "Database queries too slow - need caching"
Type: Bug
Priority: High Priority: High
Suggested replan: Applying to task impl-2...
+ Add IMPL-001.4: Fix login timeout
~ Adjust IMPL-001.3: Include timeout tests
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 ## Error Handling
### Input Validation Errors
```bash ```bash
# Cannot replan completed task # Task not found
❌ Task IMPL-001 is completed ❌ Task impl-5 not found in current session
→ Create new task instead → Check task ID with /context
# No reason provided # No input provided
⚠️ Please provide reason for replanning ❌ Please specify changes needed for replanning
→ Use --reason="explanation" → Use descriptive text or --detailed/--interactive
# Conflicts detected # Task completed
⚠️ Replan conflicts with IMPL-002 ⚠️ Task impl-1 is completed (cannot replan)
→ Resolve with --force or adjust plan → 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 # TODO_LIST.md not writable
- **Backup Files**: `.task/archive/[task-id]-v[N]-backup.json` ⚠️ Cannot update TODO_LIST.md (permissions)
- **Replan Reports**: `.summaries/replan-[task-id]-[timestamp].md` → Task updated, manual TODO sync needed
- **Change Logs**: Embedded in JSON task file metadata
- **Updated TODO_LIST.md**: Reflects new task structure
- **Archive Directory**: `.task/archive/` for deprecated files
### File System Maintenance # Session conflict
- **Automatic Cleanup**: Archive old versions after 30 days ⚠️ Task impl-1 being modified in another session
- **Integrity Validation**: Ensure all references remain valid after changes → Complete other operation first
- **Rollback Support**: Complete restoration capability from backups ```
- **Cross-Reference Updates**: Maintain links between all workflow files
## 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 ## Related Commands
- `/task:breakdown` - Initial task breakdown with JSON file creation - `/context` - View task structure and version history
- `/context` - Analyze current state from file system - `/task:execute` - Execute replanned tasks with new structure
- `/task:execute` - Execute replanned tasks with new structure - `/workflow:action-plan` - For workflow-wide replanning
- `/context` - View updated task structure and relationships - `/task:create` - Create new tasks for additional work
- `/workflow:replan` - Replan entire workflow with session updates
---
**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 name: workflow-action-plan
description: Action planning phase that integrates brainstorming insights or user input to create executable implementation plans description: Create implementation plans from various input sources
usage: /workflow:action-plan [--from-brainstorming] [--skip-brainstorming] [--replan] [--trigger=<reason>] usage: /workflow:action-plan [input-source] [--complexity=<simple|decompose>]
argument-hint: [optional: from brainstorming, skip brainstorming, replan mode, or replan trigger] argument-hint: [text|--from-file|--from-issue|--template|--interactive|--from-brainstorming] [optional: complexity]
examples: 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 --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) # Workflow Action Plan Command (/workflow:action-plan)
## Overview ## 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 ## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md **System:** @~/.claude/workflows/unified-workflow-system-principles.md
## Input Sources & Planning Approaches ## Input Sources & Processing
### Brainstorming-Based Planning (--from-brainstorming) ### Direct Text Input (Default)
**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
```bash ```bash
# Force complex planning even for medium tasks /workflow:action-plan "Build user authentication system with JWT and OAuth2"
/workflow:action-plan --force-complex
# Force simple planning for quick fixes
/workflow:action-plan --force-simple
``` ```
**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 ```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 **Supported formats**: .md, .txt, .json, .yaml
- Immediately transitions to IMPLEMENT **Processing**:
- Useful for urgent fixes - Read and parse file contents
- Extract structured requirements and specifications
- Identify task descriptions and dependencies
- Preserve original structure and priorities
## Replanning Mode ### Issue-based Input
### Usage
```bash ```bash
# Basic replanning /workflow:action-plan --from-issue ISS-001
/workflow:action-plan --replan --trigger=requirement-change /workflow:action-plan --from-issue "feature-request"
# 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
``` ```
**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 ### Template-based Input
- `--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:
```bash ```bash
# Create issue then replan /workflow:action-plan --template web-api
/workflow:issue create --type=feature "OAuth2 support" /workflow:action-plan --template mobile-app "user management"
/workflow:action-plan --replan --trigger=new-issue --issue=ISS-001 ```
**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 ### 3. Requirement Analysis
**Prerequisite Commands**: - Structure extracted information
- `/workflow:session start` → Initialize workflow session - Identify tasks and dependencies
- `/brainstorm` → (Optional) Multi-agent brainstorming phase - Determine technical requirements
- Extract success criteria
- Assess complexity and scope
**Action Planning Execution**: ### 4. Plan Generation
- `/workflow:action-plan --from-brainstorming` → Plan from completed brainstorming - Create IMPL_PLAN.md with structured content
- `/workflow:action-plan --skip-brainstorming "task description"` → Plan from user input - Include requirements, tasks, and success criteria
- `/workflow:action-plan --replan` → Revise existing plans - Maintain traceability to input sources
- Format for readability and execution
**Follow-up Commands**: ### 5. Optional Decomposition
- `/workflow:implement` → Execute the action plan **If --complexity=decompose**:
- `/workflow:status` → View current workflow state - Parse IMPL_PLAN.md for task identifiers
- `/task:create` → Create specific implementation tasks - Create .task/impl-*.json files
- `/workflow:review` → Validate completed implementation - 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 ### Session State Updates
After action planning completion:
```json ```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": { "phases": {
"BRAINSTORM": {"status": "completed|skipped"},
"PLAN": { "PLAN": {
"status": "completed", "status": "completed",
"input_source": "brainstorming|user_input", "complexity": "simple|decompose",
"documents_generated": ["IMPL_PLAN.md"], "documents_generated": ["IMPL_PLAN.md"],
"tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"], "tasks_created": 0,
"complexity_assessed": "simple|medium|complex" "input_processed": true
} }
} }
} }
``` ```
### Quality Assurance ## IMPL_PLAN.md Template
**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
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

120
.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 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 ## Core Agent Coordination Principles
### Planning First Principle ### 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. 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. 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): **CLI Guidelines Reference**: Follow @~/.cluade/workflows/gemini-cli-guidelines.md for consistency and `memory-gemini-bridge` agent for comprehensive analysis.
- `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
**Validation Protocol**: ### 🎯 Gemini CLI Requirements by Task Complexity
```pseudo
FUNCTION validate_implementation_prerequisites():
artifacts_found = 0
IF exists("IMPL_PLAN.md") AND valid_content("IMPL_PLAN.md"):
artifacts_found += 1
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 #### 🚀 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
`TodoWrite Creation` **->** `Context Collection` **->** `Implementation` **->** `Quality Assurance` **->** `State Update` #### 🎯 Medium Tasks (CLI Recommended)
**Task Examples**: Multi-file features, component modifications, API endpoint additions
### Interrupt & Resume Protocol **CLI Decision**: Recommended for consistency and quality
**Context Scope**: Guidelines + architecture + feature patterns
**Checkpoint Strategy Flow:** **Standard Context Collection**:
`Agent Completes` **->** `Save State (Todo + Context)` **->** `Check for Interrupt Signal` **->** `Continue or Stop` ```bash
gemini --all-files -p "@{**/*CLAUDE.md} Guidelines for: [task]"
**State Components for Resume**: gemini --all-files -p "@[modules] Architecture for: [task]"
- TodoWrite current state gemini --all-files -p "@[files] Patterns for: [task]"
- 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]
```

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

@@ -2,112 +2,159 @@
## Core Agent Coordination Features ## 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 - **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 - **Error Recovery**: Graceful handling of Agent coordination failures
## Workflow Implementation Patterns ## Workflow Implementation Patterns
### Simple Workflow Pattern ### Simple Workflow Pattern
```pseudocode ```pseudocode
Flow: TodoWrite Creation → Context → Implementation → Review Flow: Gemini Context Analysis → TodoWrite Creation → Context-Aware Implementation → Review
1. MANDATORY TodoWrite Creation: 1. MANDATORY Gemini Context Analysis:
- "Gather context for implementation" - Analyze target files and immediate dependencies
- "Implement solution" - Discover existing patterns and conventions
- "Review and validate code" - Identify utilities and libraries to use
- "Complete task" - Generate context package for agents
2. Implementation Checkpoint: 2. TodoWrite Creation (Context-informed):
Task(code-developer): Direct implementation - "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 Output: SUMMARY, FILES_MODIFIED, TESTS, VERIFICATION
3. Review Checkpoint: 4. Context-Aware Review:
Task(code-review-agent): Quick quality review Task(code-review-agent): Review with codebase standards context
Input: CONTEXT_PACKAGE, IMPLEMENTATION_RESULTS
Output: STATUS, SCORE, ISSUES, RECOMMENDATIONS Output: STATUS, SCORE, ISSUES, RECOMMENDATIONS
Resume Support: Load todos + context from checkpoint Resume Support: Load todos + full context state from checkpoint
``` ```
### Medium Workflow Pattern ### Medium Workflow Pattern
```pseudocode ```pseudocode
Flow: TodoWrite → Planning → Implementation → Review Flow: Comprehensive Gemini Analysis → TodoWrite → Multi-Context Implementation → Review
1. MANDATORY TodoWrite Creation (5-7 todos): 1. MANDATORY Comprehensive Gemini Context Analysis:
- "Create implementation plan" - Analyze feature area and related components
- "Gather context", "Implement with tests" - Discover cross-file patterns and architectural decisions
- "Validate", "Review", "Complete" - Identify integration points and dependencies
- Generate comprehensive context packages for multiple agents
2. Planning Checkpoint: 2. TodoWrite Creation (Context-driven, 5-7 todos):
Task(planning-agent): Create plan - "Execute comprehensive Gemini context analysis"
Trigger decomposition if >3 modules or >5 subtasks - "Coordinate multi-agent implementation with shared context"
Output: PLAN_SUMMARY, STEPS, SUCCESS_CRITERIA - "Implement following discovered architectural patterns"
- "Validate against existing system patterns", "Review", "Complete"
3. Multi-Context Implementation:
Task(code-developer): Implementation with comprehensive context
Input: CONTEXT_PACKAGES, ARCHITECTURAL_PATTERNS, INTEGRATION_POINTS
Update context as new patterns discovered
3. Implementation Checkpoint: 4. Context-Aware Review:
Task(code-developer): Follow plan Task(code-review-agent): Comprehensive review with system context
Update TODO_CHECKLIST.md if decomposition exists Input: FULL_CONTEXT_STATE, IMPLEMENTATION_RESULTS, PATTERN_COMPLIANCE
Verify against discovered architectural patterns
4. Review Checkpoint:
Task(code-review-agent): Comprehensive review
Verify against plan and decomposition
Resume Support: Full state restoration at each checkpoint Resume Support: Full context state + pattern discovery restoration
``` ```
### Complex Workflow Pattern ### Complex Workflow Pattern
```pseudocode ```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): 1. MANDATORY Deep Gemini Context Analysis:
- "Create detailed plan", "Generate decomposition docs" - System-wide architectural understanding
- "Gather context", "Implement with testing" - Deep pattern analysis across entire codebase
- "Validate criteria", "Review", "Iterate", "Complete" - Integration complexity assessment
- Multi-agent coordination requirements discovery
- Risk pattern identification
2. Planning Checkpoint: 2. TodoWrite Creation (Context-orchestrated, 7-10 todos):
Task(planning-agent): MANDATORY task decomposition - "Execute deep system-wide Gemini analysis"
Generate: IMPL_PLAN.md (enhanced structure), TODO_LIST.md - "Orchestrate multi-agent coordination with shared context"
Include risk assessment and quality gates - "Implement with continuous context refinement"
- "Validate against system architectural patterns", "Review", "Iterate", "Complete"
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
3. Implementation Checkpoint: 4. Deep Context Review & Iteration Loop (max 2 iterations):
Task(code-developer): Follow hierarchical breakdown Task(code-review-agent): Production-ready review with full system context
Update TODO_CHECKLIST.md for each subtask completion If CRITICAL_ISSUES found: Re-analyze context and coordinate fixes
4. Review & Iteration Loop (max 2 iterations):
Task(code-review-agent): Production-ready review
If CRITICAL_ISSUES found: Task(code-developer) fixes issues
Continue until no critical issues or max iterations reached Continue until no critical issues or max iterations reached
Document Validation: Verify decomposition docs generated Context Validation: Verify deep context analysis maintained throughout
Resume Support: Full state + iteration tracking Resume Support: Full context state + iteration tracking + cross-agent coordination
``` ```
## Workflow Characteristics by Pattern ## Workflow Characteristics by Pattern
| Pattern | Agent Chain | Quality Focus | Iteration Strategy | | Pattern | Context Analysis | Agent Coordination | Iteration Strategy |
|---------|-------------|---------------|--------------------| |---------|------------------|--------------------|--------------------|
| **Complex** | Full 3-stage + iterations | Production-ready quality | Multiple rounds until perfect | | **Complex** | Deep system-wide Gemini analysis | Multi-agent orchestration with shared context | Multiple rounds with context refinement |
| **Medium** | Full 3-stage single-pass | Comprehensive quality | Single thorough review | | **Medium** | Comprehensive multi-file analysis | Context-driven coordination | Single thorough pass with pattern validation |
| **Simple** | 2-stage direct | Basic quality | Quick validation | | **Simple** | Focused file-level analysis | Direct context-aware execution | Quick context validation |
## Task Invocation Examples ## Context-Driven Task Invocation Examples
```bash ```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", Task(subagent_type="general-purpose",
prompt="Research authentication patterns in codebase") prompt="Research authentication patterns in codebase",
context="[GEMINI_CONTEXT_PACKAGE]")
# Planning Task # Context-Informed Implementation Task
Task(subagent_type="planning-agent",
prompt="Plan OAuth2 implementation across API, middleware, and UI")
# Implementation Task
Task(subagent_type="code-developer", 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", 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 ```markdown
# Task Progress List: [Session Topic] # Task Progress List: [Session Topic]
## Progress Overview
- **Total Tasks**: X
- **Completed**: Y (Z%)
- **In Progress**: N
- **Pending**: M
## Implementation Tasks ## Implementation Tasks
### Main Tasks ### Main Tasks

567
.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 ## 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/WFS-[topic-slug]/
├── workflow-session.json # Master session state ├── workflow-session.json # Session state (simplified)
├── IMPL_PLAN.md # Combined planning document ├── IMPL_PLAN.md # Static planning document
├── TODO_LIST.md # Progress tracking document
└── .task/ └── .task/
├── impl-1.json # Main task ├── impl-1.json # Task data (only data source)
├── impl-1.1.json # Level 2 subtask ├── impl-1.1.json # Subtask data
├── impl-1.1.1.json # Level 3 detailed subtask └── impl-2.json # Another task
├── impl-1.2.json # Another level 2 subtask
└── impl-2.json # Another main task
``` ```
## JSON File Structures ## JSON Data Structures
### 1. Simplified workflow-session.json
### 1. workflow-session.json (Master State)
```json ```json
{ {
"session_id": "WFS-user-auth-system", "session_id": "WFS-user-auth",
"project": "OAuth2 authentication system", "project": "OAuth2 authentication system",
"type": "complex",
"status": "active", "status": "active",
"current_phase": "IMPLEMENT", "phase": "IMPLEMENT",
"directory": ".workflow/WFS-user-auth-system",
"documents": { "progress": {
"IMPL_PLAN.md": { "completed_phases": ["PLAN"],
"status": "generated", "current_tasks": ["impl-1", "impl-2"],
"path": ".workflow/WFS-user-auth-system/IMPL_PLAN.md", "last_checkpoint": "2025-09-07T10:00:00Z"
"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"
}
}, },
"task_system": { "stats": {
"enabled": true, "total_tasks": 8,
"directory": ".workflow/WFS-user-auth-system/.task", "completed": 3,
"next_main_task_id": 3, "active": 2
"max_depth": 3,
"task_count": {
"total": 8,
"main_tasks": 2,
"subtasks": 6,
"pending": 3,
"active": 2,
"completed": 2,
"blocked": 1
}
}, },
"coordination": { "meta": {
"last_sync": "2025-09-05T11:20:00Z", "created": "2025-09-05T10:00:00Z",
"sync_conflicts": 0, "updated": "2025-09-07T10:00:00Z"
"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"
} }
} }
``` ```
### 2. TODO_LIST.md (Task Registry & Display) ### 2. Simplified Task JSON (impl-*.json)
TODO_LIST.md serves as both the task registry and progress display:
```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 ```json
{ {
"id": "impl-1.1", "id": "impl-1",
"title": "Design authentication schema", "title": "Build authentication module",
"parent_id": "impl-1", "status": "active",
"depth": 2, "type": "feature",
"status": "completed", "agent": "code-developer",
"type": "design",
"priority": "normal",
"agent": "planning-agent",
"effort": "1h",
"subtasks": ["impl-1.1.1", "impl-1.1.2"],
"context": { "context": {
"inherited_from": "impl-1", "requirements": ["JWT authentication", "OAuth2 support"],
"requirements": ["User model schema", "JWT token design", "OAuth2 integration points"], "scope": ["src/auth/*", "tests/auth/*"],
"scope": ["src/auth/models/*", "docs/auth-schema.md"], "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"acceptance": ["Schema validates JWT tokens", "User model complete", "OAuth2 flow documented"] "inherited_from": "WFS-user-auth"
}, },
"document_refs": { "relations": {
"todo_section": "TODO_LIST.md#impl-1.1", "parent": null,
"todo_items": [ "subtasks": ["impl-1.1", "impl-1.2"],
"TODO_LIST.md#impl-1.1", "dependencies": ["impl-0"]
"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"]
}, },
"execution": { "execution": {
"attempts": 1, "attempts": 0,
"current_attempt": { "last_attempt": "2025-09-05T10:35:00Z"
"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"]
}
]
}, },
"sync_metadata": { "meta": {
"last_document_sync": "2025-09-05T11:20:00Z", "created": "2025-09-05T10:30:00Z",
"document_version": "1.2", "updated": "2025-09-05T10:35:00Z"
"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"
} }
} }
``` ```
## Single Source of Truth Architecture ## Pure Generation Architecture
### 1. Data Authority (Simplified) ### JSON as Single Source of Truth
#### JSON Files Own (ONLY Authoritative Source) **JSON Files Own Everything:**
- **ALL Task State**: Complete task definitions, status, progress, metadata - All task state and metadata
- **Hierarchical Relationships**: Parent-child links, depth management - All relationships and dependencies
- **Execution State**: pending/active/completed/blocked/failed - All execution history
- **Progress Data**: Percentages, timing, checkpoints - All progress information
- **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
#### Documents Are Read-Only Views (Generated Only) **Documents Are Temporary Views:**
- **IMPL_PLAN.md**: Static planning document (manually created, rarely changes) - Generated only when requested
- **TODO_LIST.md**: **Generated view** from JSON files (never manually edited) - Never stored permanently
- **Progress Reports**: **Generated views** from JSON data - Never parsed back to JSON
- **Status Displays**: **Generated views** from JSON state - No state persistence in markdown
#### No Shared Responsibility (Eliminates Conflicts) ### No Synchronization Needed
- **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
### 2. View Generation (Replaces Synchronization) **Eliminated Concepts:**
- Bidirectional sync
- Document parsing
- Conflict resolution
- Sync state tracking
- Update coordination
#### No Document → JSON Flow (Eliminated) **Single Flow Only:**
**Documents are read-only**: No parsing, no status updates from documents ```
**No bidirectional sync**: Documents cannot modify JSON state JSON Files → On-Demand Generation → Temporary Views → Display
**No conflict resolution needed**: Single direction eliminates conflicts ```
#### 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 ```javascript
// Pseudo-code for view generation process // Update task status
on_view_request(view_type, options) { function update_task_status(task_id, new_status) {
const task_data = load_all_task_json_files(); const task_file = `.task/${task_id}.json`
const session_data = load_workflow_session(); const task = load_json(task_file)
task.status = new_status
if (view_type === 'todo_list') { task.meta.updated = current_timestamp()
const todo_view = generate_todo_list_view(task_data); save_json(task_file, task)
return render_markdown_view(todo_view); // No document updates needed - views generated on demand
}
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);
}
} }
``` ```
### 3. View Generation Process (Replaces Real-Time Sync) ### Session Updates (Minimal)
#### On-Demand View Process ```javascript
``` // Update session stats
1. Command Request → User requests view (`/context`) function update_session_stats() {
2. JSON Loader → Reads all task JSON files const session = load_workflow_session()
3. Data Processor → Calculates progress, status, hierarchy const tasks = load_all_tasks()
4. View Generator → Creates markdown representation
5. Display → Returns formatted view to user session.stats.completed = count_completed_tasks(tasks)
``` session.stats.active = count_active_tasks(tasks)
session.meta.updated = current_timestamp()
#### Context Command (Replaces Sync Commands)
```bash save_json('workflow-session.json', session)
# Generate todo list view // No document coordination needed
/context
# 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"
} }
``` ```
### Performance Metrics ## Benefits of Pure Generation
- Sync frequency and duration
- Conflict rate and resolution time
- File size growth over time
- Error rate and recovery success
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.

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

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

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

@@ -2,133 +2,103 @@
## Overview ## 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) ### Medium Workflows
**Criteria**: Tasks < 5 AND modules ≤ 3 AND effort ≤ 4h **Criteria**: Feature implementation requiring task breakdown
**Structure**: Minimal structure with basic task tracking **Structure**: Two-level hierarchy (impl-N.M format)
**Documents**: IMPL_PLAN.md only, no TODO_LIST.md **Task Files**: Parent and child JSON files
**Task Files**: impl-*.json (single level) **Max Depth**: 2 levels
### Medium Workflows (5-15 tasks) ### Complex Workflows
**Criteria**: Tasks 5-15 OR modules > 3 OR effort > 4h OR complex dependencies **Criteria**: System-wide changes requiring detailed decomposition
**Structure**: Enhanced structure with progress tracking **Structure**: Three-level hierarchy (impl-N.M.P format)
**Documents**: IMPL_PLAN.md + TODO_LIST.md (auto-triggered) **Task Files**: Multi-level JSON hierarchy
**Task Files**: impl-*.*.json (up to 2 levels) **Max Depth**: 3 levels (maximum allowed)
### Complex Workflows (>15 tasks) ## Task Hierarchy Rules
**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)
## 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 ### Parent-Child Relationships
``` ```json
START: Analyze Workflow Requirements // Parent task
↓ {
Count Tasks → Is Task Count < 5? "id": "impl-1",
↓ YES ↓ NO "title": "Build authentication module",
Count Modules Count Modules → > 5? "status": "pending",
↓ ↓ YES "relations": {
≤ 3 Modules? COMPLEX "parent": null,
↓ YES ↓ NO "subtasks": ["impl-1.1", "impl-1.2"],
Estimate Effort Estimate Effort → > 2 days? "dependencies": []
↓ ↓ YES }
≤ 4 hours? COMPLEX }
↓ YES ↓ NO
SIMPLE Check Dependencies → Multi-repo? // Child task
↓ YES ↓ NO {
COMPLEX MEDIUM "id": "impl-1.1",
"title": "Design auth schema",
"status": "pending",
"relations": {
"parent": "impl-1",
"subtasks": [],
"dependencies": []
}
}
``` ```
### Decision Matrix ## Decomposition Triggers
| **Factor** | **Simple** | **Medium** | **Complex** | ### Automatic Decomposition When:
|------------|------------|------------|-------------| - Task title indicates multiple distinct activities
| Task Count | < 5 | 5-15 | > 15 | - Implementation scope spans multiple modules
| Module Count | ≤ 3 | 4-5 | > 5 | - Clear sub-components can be identified
| Effort Estimate | ≤ 4h | 4h-2d | > 2d | - Task complexity exceeds single-agent execution
| Dependencies | Simple | Complex | Multi-repo |
| Repository Scope | Single | Single | Multiple |
### Threshold Priority ### Skip Decomposition For:
1. **Task Count**: Primary factor (most reliable predictor) - Single file modifications
2. **Module Count**: Secondary factor (scope indicator) - Simple bug fixes
3. **Effort Estimate**: Tertiary factor (complexity indicator) - Clear, atomic tasks
4. **Dependencies**: Override factor (can force higher complexity) - Documentation updates
## Automatic Document Generation Rules ## Task Status 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
### 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 ## Validation Rules
### Complexity Classification Validation ### Hierarchy Validation
1. **Threshold Verification**: Ensure task count, module count, and effort estimates align 1. **Depth Limit**: Maximum 3 levels (impl-N.M.P)
2. **Override Checks**: Verify dependency complexity doesn't require higher classification 2. **ID Format**: Must follow hierarchical naming
3. **Consistency Validation**: Confirm file structure matches complexity level 3. **Parent References**: All parent IDs must exist
4. **Progress Calculation**: Validate progress tracking matches hierarchy depth 4. **Circular Dependencies**: Not allowed in hierarchy
### Quality Assurance ### Task Integrity
- Decomposition depth must not exceed 3 levels (impl-N.M.P maximum) - All referenced tasks must exist as JSON files
- Task hierarchy must be consistent across JSON files and TODO_LIST.md - Parent-child relationships must be bidirectional
- Complexity classification must align with document generation rules - Container tasks cannot have "completed" status until all children complete
- Auto-trigger conditions must be properly evaluated and documented - 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

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

@@ -2,396 +2,152 @@
## Overview ## 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. ## Simplified Task JSON Schema
## Unified Task JSON Schema
### Core Task Structure ### 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 ```json
{ {
"id": "impl-1", "id": "impl-1",
"parent_id": null, "title": "Build authentication module",
"title": "Task title describing the work", "status": "pending",
"type": "feature|bugfix|refactor|test|docs", "type": "feature",
"status": "pending|active|completed|blocked|failed", "agent": "code-developer",
"priority": "low|normal|high|critical",
"agent": "code-developer|planning-agent|test-agent|review-agent",
"effort": "1h|2h|4h|1d|2d",
"context": { "context": {
"inherited_from": "WFS-user-auth-system", "requirements": ["JWT authentication", "OAuth2 support"],
"requirements": ["Specific requirement 1", "Specific requirement 2"], "scope": ["src/auth/*", "tests/auth/*"],
"scope": ["src/module/*", "tests/module/*"], "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"acceptance": ["Success criteria 1", "Success criteria 2"] "inherited_from": "WFS-user-auth"
}, },
"dependencies": { "relations": {
"upstream": ["impl-0"], "parent": null,
"downstream": ["impl-2", "impl-3"] "subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
}, },
"subtasks": ["impl-1.1", "impl-1.2", "impl-1.3"],
"execution": { "execution": {
"attempts": 1, "attempts": 0,
"current_attempt": { "last_attempt": null
"started_at": "2025-09-05T10:35:00Z",
"checkpoints": ["setup", "implement", "test", "validate"],
"completed_checkpoints": ["setup", "implement"]
},
"history": []
}, },
"metadata": { "meta": {
"created_at": "2025-09-05T10:30:00Z", "created": "2025-09-05T10:30:00Z",
"started_at": "2025-09-05T10:35:00Z", "updated": "2025-09-05T10:30:00Z"
"completed_at": "2025-09-05T13:15:00Z",
"last_updated": "2025-09-05T13:15:00Z",
"version": "1.0"
} }
} }
``` ```
### Status Enumeration ### Status Values
Standard status values across all systems:
- **pending**: Task created but not started - **pending**: Task created but not started
- **active**: Task currently being worked on - **active**: Task currently being worked on
- **completed**: Task successfully finished - **completed**: Task successfully finished
- **blocked**: Task cannot proceed due to dependencies - **blocked**: Task cannot proceed due to dependencies
- **failed**: Task attempted but failed execution - **container**: Parent task with subtasks (not directly executable)
### Type Classification ### Task Types
Standard task types:
- **feature**: New functionality implementation - **feature**: New functionality implementation
- **bugfix**: Fixing existing issues - **bugfix**: Fixing existing issues
- **refactor**: Code improvement without functionality change - **refactor**: Code improvement without functionality change
- **test**: Test implementation or testing tasks - **test**: Test implementation or testing tasks
- **docs**: Documentation creation or updates - **docs**: Documentation creation or updates
### Priority Levels ## Context Management
Standard priority values:
- **low**: Can be deferred
- **normal**: Standard priority (default)
- **high**: Should be completed soon
- **critical**: Must be completed immediately
## TodoWrite Integration System ### Context Structure
Context provides complete information for agent execution:
### TodoWrite Tool vs TODO_LIST.md File - **requirements**: Specific functional requirements
**Clear Distinction**: TodoWrite is Claude's internal task tracking tool, TODO_LIST.md is the persistent workflow file - **scope**: File patterns and modules affected
- **acceptance**: Success criteria and completion definition
- **inherited_from**: Source workflow or parent task
**TodoWrite Tool**: ### Context Inheritance
- Claude's internal task management interface - **Workflow → Task**: Global requirements and constraints
- Real-time progress tracking during execution - **Parent → Subtask**: Refined scope and specific requirements
- Temporary state for active workflow sessions - **Context Preservation**: All fields maintained for agent execution
- Used by agents and commands for immediate task coordination
**TODO_LIST.md File**: ## Task Relationships
- 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
### Synchronization Protocol ### Hierarchical Structure
- **Parent-Child**: Uses `relations.parent` and `relations.subtasks`
**TodoWrite → TODO_LIST.md**: - **Dependencies**: Uses `relations.dependencies` for task ordering
- TodoWrite task completion triggers TODO_LIST.md checkbox updates - **Maximum Depth**: 3 levels (impl-N.M.P format)
- 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
### ID Format Standards ### ID Format Standards
``` ```
impl-1 # Main task impl-1 # Main task
impl-1.1 # Subtask of impl-1 impl-1.1 # Subtask of impl-1
impl-1.1.1 # Detailed subtask of impl-1.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 Integration
### Agent Assignment Logic ### Agent Assignment
Based on task type and complexity: Based on task type and title keywords:
- **Planning tasks** → planning-agent - **Planning tasks** → planning-agent
- **Implementation** → code-developer - **Implementation** → code-developer
- **Testing** → test-agent - **Testing** → test-agent
- **Documentation** → docs-agent - **Documentation** → docs-agent
- **Review** → review-agent - **Review** → review-agent
### Execution Context Preparation ### Execution Context
Agents receive complete task JSON plus workflow context:
```json ```json
{ {
"execution_context": { "task": { /* complete task JSON */ },
"task": { "workflow": {
"id": "IMPL-001", "session": "WFS-user-auth",
"requirements": ["from task context"], "phase": "IMPLEMENT"
"scope": ["from task context"]
},
"workflow": {
"session": "WFS-2025-001",
"phase": "IMPLEMENT",
"global_context": ["from workflow"]
},
"agent": {
"type": "code-developer",
"capabilities": ["coding", "testing"],
"context_optimizations": ["code_patterns"]
}
} }
} }
``` ```
## 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 ## Error Handling
### Common Error Scenarios ### Common Scenarios
1. **JSON Task File Missing**: Recreate from TODO_LIST.md or parent task data 1. **Missing JSON File**: Indicates broken reference - must repair
2. **Status Mismatch**: JSON files are authoritative, update TODO_LIST.md 2. **Invalid Status**: Update to valid status value
3. **Hierarchy Broken**: Reconstruct parent-child relationships from IDs 3. **Broken Hierarchy**: Reconstruct parent-child relationships
4. **Invalid Dependencies**: Validate across all hierarchy levels 4. **Orphaned Task**: Reassign to proper parent or workflow
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
### Recovery Strategies ### Recovery Strategy
- **Automatic Recovery**: For common, well-defined conflicts - **JSON Authoritative**: Task JSON files are source of truth
- **Validation Warnings**: For non-critical inconsistencies - **Validation Warnings**: For non-critical inconsistencies
- **Manual Intervention**: For complex or ambiguous conflicts - **Manual Resolution**: For complex relationship conflicts
- **Graceful Degradation**: Continue with best available data
### 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 **System ensures**: Consistent task management using simplified JSON-only data model with complete context preservation for agent execution
### 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

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 4. **Single Active Rule** - Only one todo in_progress at any time
5. **Completion Gates** - Mark completed only when truly finished 5. **Completion Gates** - Mark completed only when truly finished
6. **Persistence Sync** - TodoWrite changes trigger workflow file updates 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