catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-10 02:24:35 +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

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

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

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

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

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
This document defines the **Single Source of Truth** architecture where JSON files are the authoritative state source and all markdown documents are read-only, generated views. This eliminates bidirectional synchronization complexity and data conflicts.
This document defines a **pure JSON data model** where JSON files are the only data source and all markdown documents are generated on-demand views. This eliminates all synchronization complexity and ensures data consistency.
**Key Principle**: `.task/*.json` files are the **only** authoritative source of task state. All markdown documents (`TODO_LIST.md`, progress displays, etc.) are generated on-demand from JSON data.
**Key Principle**: `.task/*.json` files are the **only** authoritative source of task state. All markdown documents are **read-only generated views** that never persist state.
## File Structure
### JSON File Hierarchy
```
.workflow/WFS-[topic-slug]/
├── workflow-session.json # Master session state
├── IMPL_PLAN.md # Combined planning document
├── TODO_LIST.md # Progress tracking document
├── workflow-session.json # Session state (simplified)
├── IMPL_PLAN.md # Static planning document
└── .task/
├── impl-1.json # Main task
├── impl-1.1.json # Level 2 subtask
├── impl-1.1.1.json # Level 3 detailed subtask
├── impl-1.2.json # Another level 2 subtask
└── impl-2.json # Another main task
├── impl-1.json # Task data (only data source)
├── impl-1.1.json # Subtask data
└── impl-2.json # Another task
```
## JSON File Structures
## JSON Data Structures
### 1. Simplified workflow-session.json
### 1. workflow-session.json (Master State)
```json
{
"session_id": "WFS-user-auth-system",
"session_id": "WFS-user-auth",
"project": "OAuth2 authentication system",
"type": "complex",
"status": "active",
"current_phase": "IMPLEMENT",
"directory": ".workflow/WFS-user-auth-system",
"phase": "IMPLEMENT",
"documents": {
"IMPL_PLAN.md": {
"status": "generated",
"path": ".workflow/WFS-user-auth-system/IMPL_PLAN.md",
"last_updated": "2025-09-05T10:30:00Z",
"sync_status": "synced"
},
"TODO_LIST.md": {
"status": "generated",
"path": ".workflow/WFS-user-auth-system/TODO_LIST.md",
"last_updated": "2025-09-05T11:20:00Z",
"sync_status": "synced"
}
"progress": {
"completed_phases": ["PLAN"],
"current_tasks": ["impl-1", "impl-2"],
"last_checkpoint": "2025-09-07T10:00:00Z"
},
"task_system": {
"enabled": true,
"directory": ".workflow/WFS-user-auth-system/.task",
"next_main_task_id": 3,
"max_depth": 3,
"task_count": {
"total": 8,
"main_tasks": 2,
"subtasks": 6,
"pending": 3,
"active": 2,
"completed": 2,
"blocked": 1
}
"stats": {
"total_tasks": 8,
"completed": 3,
"active": 2
},
"coordination": {
"last_sync": "2025-09-05T11:20:00Z",
"sync_conflicts": 0,
"auto_sync_enabled": true,
"manual_sync_required": false
},
"metadata": {
"created_at": "2025-09-05T10:00:00Z",
"last_updated": "2025-09-05T11:20:00Z",
"version": "2.1"
"meta": {
"created": "2025-09-05T10:00:00Z",
"updated": "2025-09-07T10:00:00Z"
}
}
```
### 2. TODO_LIST.md (Task Registry & Display)
TODO_LIST.md serves as both the task registry and progress display:
### 2. Simplified Task JSON (impl-*.json)
```markdown
# Implementation Progress
## Task Status Summary
- **Total Tasks**: 5
- **Completed**: 2 (40%)
- **Active**: 2
- **Pending**: 1
## Task Hierarchy
### ☐ impl-1: Build authentication module (75% complete)
- ☑ impl-1.1: Design authentication schema (100%)
- ☑ impl-1.1.1: Create user model
- ☑ impl-1.1.2: Design JWT structure
- ☐ impl-1.2: Implement OAuth2 flow (50%)
### ☐ impl-2: Setup user management (0%)
```
**Task Registry Data Extracted from TODO_LIST.md:**
"last_updated": "2025-09-05T11:20:00Z"
}
```
### 3. Individual Task JSON (impl-*.json)
```json
{
"id": "impl-1.1",
"title": "Design authentication schema",
"parent_id": "impl-1",
"depth": 2,
"status": "completed",
"type": "design",
"priority": "normal",
"agent": "planning-agent",
"effort": "1h",
"subtasks": ["impl-1.1.1", "impl-1.1.2"],
"id": "impl-1",
"title": "Build authentication module",
"status": "active",
"type": "feature",
"agent": "code-developer",
"context": {
"inherited_from": "impl-1",
"requirements": ["User model schema", "JWT token design", "OAuth2 integration points"],
"scope": ["src/auth/models/*", "docs/auth-schema.md"],
"acceptance": ["Schema validates JWT tokens", "User model complete", "OAuth2 flow documented"]
"requirements": ["JWT authentication", "OAuth2 support"],
"scope": ["src/auth/*", "tests/auth/*"],
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"],
"inherited_from": "WFS-user-auth"
},
"document_refs": {
"todo_section": "TODO_LIST.md#impl-1.1",
"todo_items": [
"TODO_LIST.md#impl-1.1",
"TODO_LIST.md#impl-1.1.1",
"TODO_LIST.md#impl-1.1.2"
],
"impl_plan_ref": "IMPL_PLAN.md#authentication-schema-design"
},
"dependencies": {
"upstream": [],
"downstream": ["impl-1.2"],
"blocking": [],
"blocked_by": [],
"parent_dependencies": ["impl-1"]
"relations": {
"parent": null,
"subtasks": ["impl-1.1", "impl-1.2"],
"dependencies": ["impl-0"]
},
"execution": {
"attempts": 1,
"current_attempt": {
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"duration": "45m",
"checkpoints": ["setup", "design", "validate", "document"],
"completed_checkpoints": ["setup", "design", "validate", "document"]
},
"history": [
{
"attempt": 1,
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"result": "success",
"outputs": ["src/auth/models/User.ts", "docs/auth-schema.md"]
}
]
"attempts": 0,
"last_attempt": "2025-09-05T10:35:00Z"
},
"sync_metadata": {
"last_document_sync": "2025-09-05T11:20:00Z",
"document_version": "1.2",
"sync_conflicts": [],
"pending_document_updates": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": "2025-09-05T10:35:00Z",
"completed_at": "2025-09-05T11:20:00Z",
"last_updated": "2025-09-05T11:20:00Z",
"created_by": "task:breakdown IMPL-001",
"version": "1.0"
"meta": {
"created": "2025-09-05T10:30:00Z",
"updated": "2025-09-05T10:35:00Z"
}
}
```
## Single Source of Truth Architecture
## Pure Generation Architecture
### 1. Data Authority (Simplified)
### JSON as Single Source of Truth
#### JSON Files Own (ONLY Authoritative Source)
- **ALL Task State**: Complete task definitions, status, progress, metadata
- **Hierarchical Relationships**: Parent-child links, depth management
- **Execution State**: pending/active/completed/blocked/failed
- **Progress Data**: Percentages, timing, checkpoints
- **Agent Assignment**: Current agent, execution history
- **Dependencies**: Task relationships across all hierarchy levels
- **Session Metadata**: Timestamps, versions, attempt counts
- **Runtime State**: Current attempt, active processes
**JSON Files Own Everything:**
- All task state and metadata
- All relationships and dependencies
- All execution history
- All progress information
#### Documents Are Read-Only Views (Generated Only)
- **IMPL_PLAN.md**: Static planning document (manually created, rarely changes)
- **TODO_LIST.md**: **Generated view** from JSON files (never manually edited)
- **Progress Reports**: **Generated views** from JSON data
- **Status Displays**: **Generated views** from JSON state
**Documents Are Temporary Views:**
- Generated only when requested
- Never stored permanently
- Never parsed back to JSON
- No state persistence in markdown
#### No Shared Responsibility (Eliminates Conflicts)
- **Single Direction Flow**: JSON → Markdown (never Markdown → JSON)
- **No Synchronization**: Documents are generated, not synchronized
- **No Conflicts**: Only one source of truth eliminates data conflicts
### No Synchronization Needed
### 2. View Generation (Replaces Synchronization)
**Eliminated Concepts:**
- Bidirectional sync
- Document parsing
- Conflict resolution
- Sync state tracking
- Update coordination
#### No Document → JSON Flow (Eliminated)
**Documents are read-only**: No parsing, no status updates from documents
**No bidirectional sync**: Documents cannot modify JSON state
**No conflict resolution needed**: Single direction eliminates conflicts
**Single Flow Only:**
```
JSON Files → On-Demand Generation → Temporary Views → Display
```
#### JSON → View Generation (On Demand)
**Trigger Events**:
- User requests context view (`/context`)
- Task status changed in JSON files
- View generation requested by commands
**Actions**:
### Generation Process
```pseudo
function generate_view(format, filters):
// Load all JSON data
tasks = load_all_task_json_files()
session = load_workflow_session()
// Generate requested view
switch format:
case 'tasks':
return generate_task_list_view(tasks)
case 'progress':
return generate_progress_view(tasks, session)
case 'hierarchy':
return generate_hierarchy_view(tasks)
default:
return generate_overview(tasks, session)
```
### View Examples
#### Task List View (Generated)
```markdown
# Current Tasks
## Active Tasks
- [⚠️] impl-1: Build authentication module (code-developer)
- [⚠️] impl-2: Setup user management (code-developer)
## Completed Tasks
- [✅] impl-0: Project setup
## Task Dependencies
- impl-2 → depends on → impl-1
```
## Data Operations
### Task Updates (JSON Only)
```javascript
// Pseudo-code for view generation process
on_view_request(view_type, options) {
const task_data = load_all_task_json_files();
const session_data = load_workflow_session();
if (view_type === 'todo_list') {
const todo_view = generate_todo_list_view(task_data);
return render_markdown_view(todo_view);
}
if (view_type === 'progress') {
const progress = calculate_progress_from_json(task_data);
return render_progress_view(progress, session_data);
}
if (view_type === 'status') {
const status = compile_status_from_json(task_data, session_data);
return render_status_view(status);
}
// Update task status
function update_task_status(task_id, new_status) {
const task_file = `.task/${task_id}.json`
const task = load_json(task_file)
task.status = new_status
task.meta.updated = current_timestamp()
save_json(task_file, task)
// No document updates needed - views generated on demand
}
```
### 3. View Generation Process (Replaces Real-Time Sync)
### Session Updates (Minimal)
#### On-Demand View Process
```
1. Command Request → User requests view (`/context`)
2. JSON Loader → Reads all task JSON files
3. Data Processor → Calculates progress, status, hierarchy
4. View Generator → Creates markdown representation
5. Display → Returns formatted view to user
```
#### Context Command (Replaces Sync Commands)
```bash
# Generate todo list view
/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"
```javascript
// Update session stats
function update_session_stats() {
const session = load_workflow_session()
const tasks = load_all_tasks()
session.stats.completed = count_completed_tasks(tasks)
session.stats.active = count_active_tasks(tasks)
session.meta.updated = current_timestamp()
save_json('workflow-session.json', session)
// No document coordination needed
}
```
### Performance Metrics
- Sync frequency and duration
- Conflict rate and resolution time
- File size growth over time
- Error rate and recovery success
## Benefits of Pure Generation
This JSON-document coordination system ensures reliable, consistent, and performant integration between state management and planning documentation while maintaining clear data ownership and providing robust error handling.
### Performance Benefits
- **No Sync Overhead**: Zero synchronization operations
- **Faster Updates**: Direct JSON updates only
- **Reduced I/O**: No document file writes
- **Instant Views**: Generate views only when needed
### Reliability Benefits
- **No Data Conflicts**: Single source of truth
- **No Sync Failures**: No synchronization to fail
- **Consistent State**: JSON always authoritative
- **Simple Recovery**: Restore from JSON only
### Maintenance Benefits
- **Simpler Code**: No sync logic needed
- **Easier Debugging**: Check JSON files only
- **Clear Data Flow**: Always JSON → View
- **No Edge Cases**: No sync conflict scenarios
## Validation (Simplified)
### JSON Schema Validation
```bash
/context --validate
Validation Results:
✅ All task JSON files valid
✅ Task relationships consistent
✅ No circular dependencies
⚠️ impl-3 has no subtasks (expected for leaf task)
Status: All systems operational
```
### Basic Integrity Checks
- Task IDs are unique
- Parent-child relationships valid
- Dependencies exist
- Required fields present
## Error Handling
### Simple Error Scenarios
```bash
# Missing task file
❌ Task impl-5 not found
→ Check .task/impl-5.json exists
# Invalid JSON
❌ Parse error in impl-2.json
→ Restore from backup or recreate task
# Circular dependency
❌ Circular dependency: impl-1 → impl-2 → impl-1
→ Fix dependency chain manually
```
### Recovery Strategy
- **JSON First**: Always repair JSON files
- **Regenerate Views**: Views are disposable, regenerate as needed
- **Simple Rollback**: Use git to restore JSON files
- **Manual Repair**: Direct JSON editing for complex issues
## Migration from Complex System
### Removed Features
- All document parsing
- Bidirectional synchronization
- Conflict resolution
- Real-time document updates
- Sync state tracking
- Document metadata
- Cross-file reference validation
- Automated document repairs
### Simplified Workflows
1. **Task Creation**: Create JSON file only
2. **Status Updates**: Update JSON file only
3. **View Request**: Generate from JSON on demand
4. **Progress Check**: Calculate from JSON data
5. **Completion**: Mark JSON as completed
This pure generation system provides all the functionality of the previous complex system while eliminating synchronization overhead, conflicts, and maintenance complexity.

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

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

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

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

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

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

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

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