diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index e02cf897..0d17031c 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -209,12 +209,6 @@ Your primary responsibilities: ## Dependency Graph [Visual or text representation of task dependencies] - ## Progress Tracking - - **Total Tasks**: [Number] - - **Completed**: [Number] ([Percentage]%) - - **In Progress**: [Number] - - **Blocked**: [Number] - ## Resource Requirements [Tools, libraries, external dependencies needed] @@ -226,9 +220,6 @@ Your primary responsibilities: ```markdown # Task Progress List: [Project Name] - ## Quick Progress Overview - **Total Items**: [Number] | **Completed**: [Number] ([Percentage]%) | **Remaining**: [Number] - ## Main Tasks ### ๐ŸŽฏ [IMPL-001] [Primary Goal] @@ -278,13 +269,12 @@ Your primary responsibilities: 5. **Integration with Development Workflow**: - Create TodoWrite entries for each stage and major subtask - For complex tasks, use enhanced IMPL_PLAN.md structure with hierarchical task breakdown - - Generate TODO_LIST.md for progress tracking and team coordination + - Generate TODO_LIST.md for task coordination - Link todo checklist items to detailed task descriptions in implementation plan - Identify which stages require architecture review - Note where code review checkpoints should occur - Specify testing requirements for each stage - Maintain document synchronization across all planning artifacts - - Update progress tracking as tasks complete - Provide clear navigation between implementation plan, task decomposition, and todo checklist 6. **Complexity Assessment**: Automatically determine planning approach based on task complexity: diff --git a/.claude/commands/context.md b/.claude/commands/context.md index e0438c39..b97ba8f8 100644 --- a/.claude/commands/context.md +++ b/.claude/commands/context.md @@ -1,344 +1,259 @@ --- name: context -description: Unified context command - Single source of truth for all workflow and task status information -usage: /context [task-id] [--format=] [--health-check] [--detailed] [--export] -argument-hint: [optional task-id] [display format] [analysis options] [export flag] +description: Generate on-demand views from JSON task data +usage: /context [task-id] [--format=] [--validate] +argument-hint: [optional: task-id, format, validation] examples: - /context - - /context IMPL-001 - - /context --format=tree - - /context --health-check - - /context --detailed --export - - /context --format=progress + - /context impl-1 + - /context --format=hierarchy + - /context --validate --- -# Unified Context Command (/context) +# Context Command (/context) ## Overview +Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files. -**Single Source of Truth**: This command replaces `/workflow:context` and `/task:context` with a unified interface that generates all views on-demand from JSON data. Eliminates synchronization complexity by making documents read-only views. +## Core Principles +**Data Source:** @~/.claude/workflows/json-document-coordination-system.md +**Session Management:** @~/.claude/workflows/session-management-principles.md -## Core Architecture +## Key Features -### Single Source of Truth Principle -- **JSON Authority**: All data read from `.task/*.json` and `workflow-session.json` files -- **Generated Views**: All markdown displays generated on-demand (never manually edited) -- **No Synchronization**: Documents are views, not synchronized states -- **Conflict-Free**: Single direction data flow eliminates conflicts +### Pure View Generation +- **No Sync**: Views are generated, not synchronized +- **Always Current**: Reads latest JSON data every time +- **No Persistence**: Views are temporary, not saved +- **Single Source**: All data comes from JSON files only -### Unified Command Interface -- **Global Context**: `/context` shows complete workflow status -- **Task-Specific**: `/context IMPL-001` shows individual task details -- **Health Checking**: `/context --health-check` validates JSON data integrity -- **Multiple Formats**: Tree, list, progress, and JSON output formats +### Multiple View Formats +- **Overview** (default): Current tasks and status +- **Hierarchy**: Task relationships and structure +- **Details**: Specific task information -## Usage Modes +## Usage -### 1. Global Workflow Context (Default) +### Default Overview ```bash /context ``` -**Generated Output** (from JSON data): -``` -๐Ÿ” Workflow Status Overview -======================== - -๐Ÿ“‹ Session Information: - - Session ID: WFS-workflow-optimization - - Current Phase: IMPLEMENT - - Complexity: complex - - Start Time: 2025-09-07 14:30:22Z - - Duration: 4h 15m - -๐Ÿ“Š Task Progress (from .task/*.json): - โœ… Completed: 2/5 (40%) - ๐Ÿ”„ In Progress: 1 task - โณ Pending: 2 tasks - ๐Ÿšซ Blocked: 0 tasks - -๐Ÿ“ JSON Data Health: - โœ… workflow-session.json - Valid JSON, complete data - โœ… .task/ directory - 5 task files, all valid JSON - โœ… Task relationships - All dependencies valid - โœ… Progress calculations - Mathematically consistent - -โฑ๏ธ Estimated Completion: 2025-09-07 20:45 (2h 30m remaining) - -๐ŸŽฏ Next Actions (generated from JSON state): - 1. Complete IMPL-003 (currently in progress) - 2. Begin IMPL-004 (dependencies satisfied) - 3. Review completed IMPL-001 and IMPL-002 -``` - -### 2. Task-Specific Context -```bash -/context IMPL-001 -``` - -**Generated Output** (from JSON file): -``` -๐Ÿ“‹ Task Context: IMPL-001 -โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” - -๐Ÿ“„ JSON Source: .task/impl-001.json -Status: completed (from JSON authority) -Created: 2025-09-07T14:45:00Z -Completed: 2025-09-07T16:30:00Z -Duration: 1h 45m - -๐ŸŽฏ Task Definition (from JSON): -Title: Implement single source of truth architecture by removing sync commands -Type: architecture -Agent: code-developer -Priority: critical - -๐Ÿ“‹ Context (from JSON): -Requirements: - - Remove workflow:sync and task:sync commands - - Update coordination system documentation - - Establish JSON as single authority source -Scope: - - .claude/commands/workflow/sync.md - - .claude/commands/task/sync.md - - .claude/workflows/json-document-coordination-system.md - -๐Ÿ”— Dependencies (from JSON): -Upstream: None -Downstream: IMPL-002, IMPL-003 -Parent: None - -โœ… Completion Status (from JSON): -Result: success -Files Modified: 3 files moved to deprecated, 1 file updated -Next Task: IMPL-002 ready to begin -``` - -### 3. Health Check Mode -```bash -/context --health-check -``` - -**Generated Analysis** (from JSON validation): -``` -๐Ÿฅ System Health Check (JSON Data Analysis) -======================================== - -โœ… JSON File Integrity: - - workflow-session.json: โœ… Valid JSON, complete schema - - .task/impl-001.json: โœ… Valid JSON, all required fields - - .task/impl-002.json: โœ… Valid JSON, all required fields - - .task/impl-003.json: โœ… Valid JSON, all required fields - - .task/impl-004.json: โœ… Valid JSON, all required fields - - .task/impl-005.json: โœ… Valid JSON, all required fields - -๐Ÿ”— Data Consistency Check: - โœ… Task IDs: All unique, follow impl-N format - โœ… Dependencies: All referenced tasks exist - โœ… Status Logic: All transitions valid - โœ… Progress Math: Calculations consistent - โœ… Timestamps: All valid, chronologically ordered - -๐Ÿ“Š Data Completeness: - โœ… All tasks have required fields - โœ… All tasks have context information - โœ… All dependencies properly defined - โœ… Session state complete - -๐ŸŽฏ Overall System Health: 100% (Excellent) - - Zero data conflicts (Single source of truth benefit) - - All JSON files valid and consistent - - No synchronization issues (eliminated by design) - - Ready for continued execution -``` - -### 4. Tree Format Display -```bash -/context --format=tree -``` - -**Generated Tree** (from JSON hierarchy): -``` -๐Ÿ“ WFS-workflow-optimization (from workflow-session.json) -โ”œโ”€โ”€ ๐Ÿ“‹ PLAN [Completed] -โ”‚ โ””โ”€โ”€ Output: IMPL_PLAN.md, 5 tasks generated -โ”œโ”€โ”€ ๐Ÿ”จ IMPLEMENT [Active - 40% complete] -โ”‚ โ”œโ”€โ”€ โœ… IMPL-001: Single source of truth architecture (completed) -โ”‚ โ”œโ”€โ”€ โœ… IMPL-002: Automated planning-to-execution flow (completed) -โ”‚ โ”œโ”€โ”€ ๐Ÿ”„ IMPL-003: Unified context commands (in_progress) -โ”‚ โ”œโ”€โ”€ โณ IMPL-004: Dynamic complexity escalation (pending) -โ”‚ โ””โ”€โ”€ โณ IMPL-005: Update session management (pending) -โ””โ”€โ”€ ๐Ÿ“ REVIEW [Pending] - โ””โ”€โ”€ Awaiting implementation completion -``` - -### 5. Progress Format -```bash -/context --format=progress -``` - -**Generated Progress View** (calculated from JSON data): -``` -๐Ÿ“Š Implementation Progress Report -============================== - -๐ŸŽฏ Overall Progress: 40% (2/5 tasks complete) - -๐Ÿ“ˆ Progress by Phase: -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ Phase โ”‚ Status โ”‚ Progress โ”‚ Tasks โ”‚ -โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค -โ”‚ PLAN โ”‚ โœ… โ”‚ 100% โ”‚ N/A โ”‚ -โ”‚ IMPLEMENT โ”‚ ๐Ÿ”„ โ”‚ 40% โ”‚ 2/5 โ”‚ -โ”‚ REVIEW โ”‚ โณ โ”‚ 0% โ”‚ 0/0 โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ - -๐Ÿ“‹ Task Progress Details (from JSON files): -โœ… IMPL-001: single source of truth [100%] โฑ๏ธ 1h 45m -โœ… IMPL-002: automated planning flow [100%] โฑ๏ธ 2h 10m -๐Ÿ”„ IMPL-003: unified context commands [75%] โฑ๏ธ 1h 30m (in progress) -โณ IMPL-004: dynamic complexity [0%] โฑ๏ธ 2h 00m (estimated) -โณ IMPL-005: session management updates [0%] โฑ๏ธ 1h 15m (estimated) - -โฐ Time Analysis (calculated from JSON): - Time Spent: 5h 25m - Remaining: 2h 45m - Estimated Total: 8h 10m - Completion: 2025-09-07 21:15 -``` - -## File Export Feature - -### Export Generated Views -```bash -/context --export -``` - -**Generated Files** (all from JSON data): -``` -.workflow/WFS-workflow-optimization/reports/ -โ”œโ”€โ”€ CONTEXT_REPORT.md # Current context view -โ”œโ”€โ”€ PROGRESS_REPORT.md # Progress analysis -โ”œโ”€โ”€ HEALTH_CHECK.md # System health status -โ””โ”€โ”€ context-exports/ # Historical exports - โ”œโ”€โ”€ context-2025-09-07-14-30.md - โ”œโ”€โ”€ progress-2025-09-07-15-45.md - โ””โ”€โ”€ health-2025-09-07-16-15.md -``` - -**Report Structure** (generated from JSON): +Generates current workflow overview: ```markdown -# Workflow Context Report -*Generated: 2025-09-07 16:15:00 from JSON data sources* +# Workflow Overview +**Session**: WFS-user-auth +**Phase**: IMPLEMENT +**Type**: medium -## Data Sources -- workflow-session.json (last updated: 2025-09-07T15:45:00Z) -- 5 task JSON files in .task/ directory -- All sources validated and consistent +## Active Tasks +- [โš ๏ธ] impl-1: Build authentication module (code-developer) +- [โš ๏ธ] impl-2: Setup user management (code-developer) -## Session Overview -[Generated from workflow-session.json] +## Completed Tasks +- [โœ…] impl-0: Project setup -## Task Analysis -[Generated from .task/*.json files] - -## Health Assessment -[Validated from JSON data integrity] - ---- -*This report is a generated view from authoritative JSON data* -*No manual editing required - data updates automatically in JSON files* +## Stats +- **Total**: 8 tasks +- **Completed**: 3 +- **Active**: 2 +- **Remaining**: 3 ``` -## Advanced Features - -### JSON Output for Scripting +### Specific Task View ```bash -/context --format=json +/context impl-1 ``` -**Generated JSON** (compiled from all sources): -```json -{ - "session": { - "id": "WFS-workflow-optimization", - "status": "active", - "phase": "implement", - "progress": 40, - "data_source": "workflow-session.json" - }, - "tasks": [ - { - "id": "IMPL-001", - "status": "completed", - "progress": 100, - "data_source": ".task/impl-001.json" - } - ], - "health": { - "json_integrity": 100, - "data_consistency": 100, - "completeness": 100 - }, - "generated_at": "2025-09-07T16:15:00Z", - "data_freshness": "current" -} +Shows detailed task information: +```markdown +# Task: impl-1 + +**Title**: Build authentication module +**Status**: active +**Agent**: code-developer +**Type**: feature + +## Context +- **Requirements**: JWT authentication, OAuth2 support +- **Scope**: src/auth/*, tests/auth/* +- **Acceptance**: Module handles JWT tokens, OAuth2 flow implemented +- **Inherited From**: WFS-user-auth + +## Relations +- **Parent**: none +- **Subtasks**: impl-1.1, impl-1.2 +- **Dependencies**: impl-0 + +## Execution +- **Attempts**: 0 +- **Last Attempt**: never + +## Metadata +- **Created**: 2025-09-05T10:30:00Z +- **Updated**: 2025-09-05T10:35:00Z ``` -### Health Check Integration -- **Validation Engine**: Checks all JSON files for schema compliance -- **Consistency Verification**: Validates cross-references between files -- **Data Integrity**: Ensures all dependencies and relationships are valid -- **Performance Monitoring**: Tracks data loading and generation speed - -## Benefits of Unified Architecture - -### Eliminated Complexity -- **No Sync Commands**: Removed `/workflow:sync` and `/task:sync` -- **No Conflicts**: Single source eliminates data drift -- **No Manual Document Editing**: All documents are generated views -- **Simplified User Experience**: One command for all context needs - -### Enhanced Reliability -- **Data Consistency**: JSON authority ensures consistent state -- **Error Reduction**: No synchronization bugs or conflicts -- **Simplified Recovery**: Only JSON files need backup/restore -- **Predictable Behavior**: Views always reflect current JSON state - -### Improved Performance -- **On-Demand Generation**: Views created only when requested -- **Efficient Data Access**: Direct JSON file reading -- **No Background Sync**: No overhead from synchronization processes -- **Cached Calculations**: Smart caching for expensive operations - -## Technical Implementation - -### Data Flow Architecture -``` -JSON Files (.task/*.json + workflow-session.json) - โ†“ (Single Direction - Read Only) -View Generation Engine - โ†“ -Formatted Output (Console/File) +### Hierarchy View +```bash +/context --format=hierarchy ``` -### View Generation Process -1. **Load JSON Data**: Read all relevant JSON files -2. **Validate Data**: Check integrity and consistency -3. **Calculate Views**: Generate requested format/content -4. **Format Output**: Apply formatting and display -5. **Export (Optional)**: Save generated views to files +Shows task relationships: +```markdown +# Task Hierarchy -### Error Handling -- **Missing Files**: Clear error messages with recovery suggestions -- **Invalid JSON**: Schema validation with specific error details -- **Broken References**: Dependency validation with repair recommendations -- **Data Inconsistencies**: Automatic detection and resolution suggestions +## Main Tasks +- impl-0: Project setup โœ… +- impl-1: Build authentication module โš ๏ธ + - impl-1.1: Design auth schema + - impl-1.2: Implement auth logic +- impl-2: Setup user management โš ๏ธ +## Dependencies +- impl-1 โ†’ depends on โ†’ impl-0 +- impl-2 โ†’ depends on โ†’ impl-1 +``` -### Data Management -- All commands now work with JSON as single source of truth -- Document generation happens on-demand -- No synchronization commands needed -- Simplified data model improves reliability +## View Generation Process +### Data Loading +```pseudo +function generate_context_view(task_id, format): + // Load all current data + session = load_workflow_session() + all_tasks = load_all_task_json_files() + + // Filter if specific task requested + if task_id: + target_task = find_task(all_tasks, task_id) + return generate_task_detail_view(target_task) + + // Generate requested format + switch format: + case 'hierarchy': + return generate_hierarchy_view(all_tasks) + default: + return generate_overview(session, all_tasks) +``` + +### Real-Time Calculation +- **Task Counts**: Calculated from JSON file status fields +- **Relationships**: Built from JSON relations fields +- **Status**: Read directly from current JSON state + +## Validation Mode + +### Basic Validation +```bash +/context --validate +``` + +Performs integrity checks: +```markdown +# Validation Results + +## JSON File Validation +โœ… All task JSON files are valid +โœ… Session file is valid and readable + +## Relationship Validation +โœ… All parent-child relationships are valid +โœ… All dependencies reference existing tasks +โœ… No circular dependencies detected + +## Hierarchy Validation +โœ… Task hierarchy within depth limits (max 3 levels) +โœ… All subtask references are bidirectional + +## Issues Found +โš ๏ธ impl-3: No subtasks defined (expected for leaf task) + +**Status**: All systems operational +``` + +### Validation Checks +- **JSON Schema**: All files parse correctly +- **References**: All task IDs exist +- **Hierarchy**: Parent-child relationships are valid +- **Dependencies**: No circular dependencies +- **Depth**: Task hierarchy within limits + +## Error Handling + +### Missing Files +```bash +โŒ Session file not found +โ†’ Initialize new workflow session? (y/n) + +โŒ Task impl-5 not found +โ†’ Available tasks: impl-1, impl-2, impl-3, impl-4 +``` + +### Invalid Data +```bash +โŒ Invalid JSON in impl-2.json +โ†’ Cannot generate view for impl-2 +โ†’ Repair file manually or recreate task + +โš ๏ธ Circular dependency detected: impl-1 โ†’ impl-2 โ†’ impl-1 +โ†’ Task relationships may be incorrect +``` + +## Performance Benefits + +### Fast Generation +- **No File Writes**: Only reads JSON files +- **No Sync Logic**: No complex synchronization +- **Instant Results**: Generate views on demand +- **No Conflicts**: No state consistency issues + +### Scalability +- **Large Task Sets**: Handles hundreds of tasks efficiently +- **Complex Hierarchies**: No performance degradation +- **Concurrent Access**: Multiple views can be generated simultaneously + +## Integration + +### Workflow Integration +- Use after task creation to see current state +- Use for debugging task relationships + +### Command Integration +```bash +# Common workflow +/task:create "New feature" +/context # Check current state +/task:breakdown impl-1 +/context --format=hierarchy # View new structure +/task:execute impl-1.1 +``` + +## Output Formats + +### Supported Formats +- `overview` (default): General workflow status +- `hierarchy`: Task relationships +- `tasks`: Simple task list +- `details`: Comprehensive information + +### Custom Filtering +```bash +# Show only active tasks +/context --format=tasks --filter=active + +# Show completed tasks only +/context --format=tasks --filter=completed + +# Show tasks for specific agent +/context --format=tasks --agent=code-developer +``` + +## Related Commands + +- `/task:create` - Create tasks (generates JSON data) +- `/task:execute` - Execute tasks (updates JSON data) +- `/task:breakdown` - Create subtasks (generates more JSON data) +- `/workflow:vibe` - Coordinate agents (uses context for coordination) + +This context system provides instant, accurate views of workflow state without any synchronization complexity or performance overhead. \ No newline at end of file diff --git a/.claude/commands/task/breakdown.md b/.claude/commands/task/breakdown.md index 889fe441..77d9580a 100644 --- a/.claude/commands/task/breakdown.md +++ b/.claude/commands/task/breakdown.md @@ -33,21 +33,18 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic - **Context Distribution**: Subtasks inherit parent context - **Agent Mapping**: Automatic agent assignment per subtask -### Built-in Task Management +### Simplified Task Management - **JSON Task Hierarchy**: Creates hierarchical JSON subtasks (impl-N.M.P) -- **TODO_LIST.md Integration**: Automatically updates progress display with new subtask structure -- **TODO_LIST.md Maintenance**: Updates task hierarchy display with parent-child relationships -- **Context Distribution**: Subtasks inherit and refine parent context -- **Progress Synchronization**: Updates hierarchical progress calculations in TODO_LIST.md -- **No External Commands**: All task operations are internal to this command +- **Context Distribution**: Subtasks inherit parent context +- **Basic Status Tracking**: Updates task relationships only +- **No Complex Synchronization**: Simple parent-child relationships ### Breakdown Rules - Only `pending` tasks can be broken down - Parent becomes container (not directly executable) -- Subtasks use hierarchical format: impl-N.M.P (e.g., IMPL-1.1.2) +- Subtasks use hierarchical format: impl-N.M.P (e.g., impl-1.1.2) - Maximum depth: 3 levels (impl-N.M.P) -- Parent task progress = average of subtask progress -- Automatically updates TODO_LIST.md with hierarchical structure +- Parent-child relationships tracked in JSON only ## Usage @@ -56,10 +53,9 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic /task:breakdown IMPL-1 ``` -Interactive prompt with automatic task management: +Interactive prompt: ``` Task: Build authentication module -Workflow: 28 total tasks (Complex workflow detected) Suggested subtasks: 1. Design authentication schema @@ -67,40 +63,33 @@ Suggested subtasks: 3. Add JWT token handling 4. Write unit tests -Internal task processing: -โœ… Level 2 hierarchy will be created (embedded logic) - Reason: >15 total tasks detected - Process: Automatic task hierarchy creation without external command calls - Accept task breakdown? (y/n/edit): y ``` -### Auto Strategy with Override Options +### Auto Strategy ```bash -/task:breakdown IMPL-1 --strategy=auto -/task:breakdown IMPL-1 --force-level=2 # Force specific document level -/task:breakdown IMPL-1 --no-split # Disable automatic document splitting +/task:breakdown impl-1 --strategy=auto ``` Automatic generation: ``` -โœ… Task IMPL-1 broken down: -โ”œโ”€โ”€ IMPL-1.1: Design authentication schema -โ”œโ”€โ”€ IMPL-1.2: Implement core auth logic -โ”œโ”€โ”€ IMPL-1.3: Add security middleware -โ””โ”€โ”€ IMPL-1.4: Write comprehensive tests +โœ… Task impl-1 broken down: +โ”œโ”€โ”€ impl-1.1: Design authentication schema +โ”œโ”€โ”€ impl-1.2: Implement core auth logic +โ”œโ”€โ”€ impl-1.3: Add security middleware +โ””โ”€โ”€ impl-1.4: Write comprehensive tests Agents assigned: -- IMPL-1.1 โ†’ planning-agent -- IMPL-1.2 โ†’ code-developer -- IMPL-1.3 โ†’ code-developer -- IMPL-1.4 โ†’ test-agent +- impl-1.1 โ†’ planning-agent +- impl-1.2 โ†’ code-developer +- impl-1.3 โ†’ code-developer +- impl-1.4 โ†’ test-agent -๐Ÿ“„ Internal task processing: -- JSON subtasks: IMPL-1.1, IMPL-1.2, IMPL-1.3, IMPL-1.4 created -- Task structure: Level 2 hierarchy established through embedded logic -- Progress tracking: TODO_LIST.md updated with hierarchical progress display -- Cross-references: All task links generated and validated internally +JSON files created: +- .task/impl-1.1.json +- .task/impl-1.2.json +- .task/impl-1.3.json +- .task/impl-1.4.json ``` ## Decomposition Patterns @@ -140,25 +129,30 @@ Parent context is intelligently distributed: ```json { "parent": { - "id": "IMPL-1", + "id": "impl-1", "context": { - "inherited_from": "WFS-[topic-slug]", "requirements": ["JWT auth", "2FA support"], "scope": ["src/auth/*"], - "acceptance": ["Authentication system works"] + "acceptance": ["Authentication system works"], + "inherited_from": "WFS-user-auth" } }, "subtasks": [ { - "id": "IMPL-1.1", + "id": "impl-1.1", "title": "Design authentication schema", "status": "pending", "agent": "planning-agent", "context": { - "inherited_from": "IMPL-1", "requirements": ["JWT auth schema", "User model design"], "scope": ["src/auth/models/*"], - "acceptance": ["Schema validates JWT tokens", "User model complete"] + "acceptance": ["Schema validates JWT tokens", "User model complete"], + "inherited_from": "impl-1" + }, + "relations": { + "parent": "impl-1", + "subtasks": [], + "dependencies": [] } } ] @@ -184,283 +178,71 @@ Based on subtask type: ### Post-breakdown Actions 1. Update parent status to `container` -2. Create subtask JSON files with document references -3. Update IMPL_PLAN.md with enhanced task hierarchy structure -4. Create/update TODO_LIST.md with progress tracking -5. Update workflow session with document references -6. Validate phase alignment with IMPL_PLAN.md (if exists) -7. Generate execution plan with document coordination +2. Create subtask JSON files +3. Update parent task with subtask references +4. Update workflow session stats -## Execution Planning +## Simple File Management -After breakdown, generates execution order: -``` -Execution Plan for IMPL-1: -Phase 1 (Parallel): - - IMPL-1.1: Design authentication schema - -Phase 2 (Sequential): - - IMPL-1.2: Implement core auth logic - - IMPL-1.3: Add security middleware - -Phase 3 (Parallel): - - IMPL-1.4: Write comprehensive tests - -Dependencies resolved automatically -``` - -## Built-in Document Management - -### Automatic File Structure Creation (Based on Workflow Scale) - -#### Level 0: Unified Documents (<15 tasks) +### File Structure Created ``` .workflow/WFS-[topic-slug]/ -โ”œโ”€โ”€ IMPL_PLAN.md (enhanced) # Updated with new task hierarchy -โ”œโ”€โ”€ TODO_LIST.md # Updated with new progress entries โ”œโ”€โ”€ workflow-session.json # Session state +โ”œโ”€โ”€ IMPL_PLAN.md # Static planning document โ””โ”€โ”€ .task/ - โ”œโ”€โ”€ IMPL-1.json # Parent task (container) - โ”œโ”€โ”€ IMPL-1.1.json # Subtask 1 - โ””โ”€โ”€ IMPL-1.2.json # Subtask 2 + โ”œโ”€โ”€ impl-1.json # Parent task (container) + โ”œโ”€โ”€ impl-1.1.json # Subtask 1 + โ””โ”€โ”€ impl-1.2.json # Subtask 2 ``` -#### Level 1: Enhanced Structure (5-15 tasks) -``` -.workflow/WFS-[topic-slug]/ -โ”œโ”€โ”€ workflow-session.json -โ”œโ”€โ”€ IMPL_PLAN.md # Combined planning document -โ”œโ”€โ”€ TODO_LIST.md # Progress tracking (auto-generated) -โ”œโ”€โ”€ .summaries/ # Task completion summaries -โ”‚ โ”œโ”€โ”€ IMPL-*.md # Main task summaries -โ”‚ โ””โ”€โ”€ IMPL-*.*.md # Subtask summaries -โ””โ”€โ”€ .task/ - โ”œโ”€โ”€ IMPL-*.json # Main task definitions - โ””โ”€โ”€ IMPL-*.*.json # Subtask definitions (up to 3 levels) -``` - -#### Level 2: Complete Structure (>15 tasks) -``` -.workflow/WFS-[topic-slug]/ -โ”œโ”€โ”€ workflow-session.json -โ”œโ”€โ”€ IMPL_PLAN.md # Comprehensive planning document -โ”œโ”€โ”€ TODO_LIST.md # Progress tracking and monitoring -โ”œโ”€โ”€ .summaries/ # Task completion summaries -โ”‚ โ”œโ”€โ”€ IMPL-*.md # Main task summaries -โ”‚ โ”œโ”€โ”€ IMPL-*.*.md # Subtask summaries -โ”‚ โ””โ”€โ”€ IMPL-*.*.*.md # Detailed subtask summaries -โ””โ”€โ”€ .task/ - โ”œโ”€โ”€ IMPL-*.json # Task hierarchy (max 3 levels deep) - โ”œโ”€โ”€ IMPL-*.*.json # Subtasks - โ””โ”€โ”€ IMPL-*.*.*.json # Detailed subtasks -``` - -### Built-in Document Creation Process - -#### Level 0: Unified Document Updates (<15 tasks) -When task count is below threshold, command automatically updates unified documents: -- Updates existing IMPL_PLAN.md with enhanced task hierarchy structure -- Updates existing TODO_LIST.md with progress tracking -- Maintains TODO_LIST.md for progress coordination - -#### Level 1: Task-Based Document Generation (15-50 tasks) -When enhanced complexity detected, command automatically: - -**Updates IMPL_PLAN.md with task breakdown**: -- Adds hierarchical task structure with subtasks -- Updates requirements and acceptance criteria -- Maintains cross-references to JSON task files -- Preserves overall workflow context - -**Creates/Updates TODO_LIST.md**: -- Displays hierarchical task structure with checkboxes -- Shows progress percentages and completion status -- Cross-references task details with JSON files -- Provides at-a-glance workflow progress overview - -#### Level 2: Complete Structure Document Updates (>15 tasks) -When complex workflows detected, command automatically: - -**Expands IMPL_PLAN.md with comprehensive planning**: -- Detailed task hierarchy with up to 3 levels deep -- Complete requirements analysis and acceptance criteria -- Risk assessment and mitigation strategies -- Cross-references to all JSON task files - -**Maintains comprehensive TODO_LIST.md**: -- Full hierarchical display with progress rollups -- Multi-level task completion tracking -- Detailed progress percentages across task hierarchy -- Cross-references to .summaries/ for completed tasks - -**Manages .summaries/ directory**: -- Creates task completion documentation structure -- Maintains audit trail of implementation decisions -- Links completed tasks back to workflow session - -### JSON Task Management Integration - -#### Task JSON Structure -```json -{ - "id": "IMPL-1.1", - "title": "Design authentication schema", - "parent_id": "IMPL-1", - "status": "pending", - "type": "design", - "agent": "planning-agent", - "effort": "1h", - - "context": { - "inherited_from": "IMPL-1", - "requirements": ["User model schema", "JWT token design"], - "scope": ["src/auth/models/*", "auth-schema.md"], - "acceptance": ["Schema validates JWT tokens", "User model complete"] - }, - - "hierarchy_context": { - "parent_task": "IMPL-1", - "level": 2, - "siblings": ["IMPL-1.2", "IMPL-1.3", "IMPL-1.4"] - }, - - "dependencies": { - "upstream": [], - "downstream": ["IMPL-1.2", "IMPL-1.3"] - }, - - "metadata": { - "created_by": "task:breakdown IMPL-1 --split-docs", - "document_sync": "2025-09-05T10:35:00Z", - "splitting_level": 2 - } -} -``` - -#### TODO_LIST.md Integration -The task breakdown automatically updates TODO_LIST.md with: - -- **Hierarchical Task Display**: Shows parent-child relationships using checkbox indentation -- **Progress Tracking**: Calculates completion percentages based on subtask status -- **JSON Cross-References**: Links to .task/ JSON files for detailed task information -- **Status Synchronization**: Keeps TODO_LIST.md checkboxes in sync with JSON task status - -### Coordination with IMPL_PLAN.md - -If IMPL_PLAN.md exists (complex workflows), task breakdown validates against phase structure: - -```markdown -### Phase 1: Foundation -- **Tasks**: IMPL-1 โ†’ Now broken down to IMPL-1.1-4 -- **Validation**: โœ… All subtasks align with phase objectives -- **Dependencies**: โœ… Phase dependencies preserved -``` - -## Advanced Options - -### Depth Control -```bash -# Single level (default) -/task:breakdown IMPL-1 --depth=1 - -# Two levels (for complex tasks) -/task:breakdown IMPL-1 --depth=2 -``` - -### Custom Breakdown -```bash -/task:breakdown IMPL-1 --custom -> Enter subtask 1: Custom subtask title -> Assign agent (auto/manual): auto -> Enter subtask 2: ... -``` - -## Task Validation & Error Handling - -### Comprehensive Validation Checks -```bash -/task:breakdown impl-1 --validate - -Pre-breakdown validation: -โœ… workflow-session.json exists and is writable -โœ… .task/ directory accessible -โœ… Parent task JSON file valid -โœ… Hierarchy depth within limits (max 3 levels) -โš ๏ธ Complexity threshold reached - will generate TODO_LIST.md - -Post-breakdown validation: -โœ… All subtask JSON files created in .task/ -โœ… Parent-child relationships established -โœ… Cross-references consistent across files -โœ… TODO_LIST.md generated/updated (if triggered) -โœ… workflow-session.json synchronized -โœ… File structure matches complexity level -``` - -### Error Recovery & File Management -```bash -# JSON file conflicts -โš ๏ธ Parent task JSON structure inconsistent with breakdown -โ†’ Auto-sync parent JSON file? (y/n) - -# Missing directory structure -โŒ .task/ directory not found -โ†’ Create required directory structure? (y/n) - -# Complexity level mismatch -โš ๏ธ Task count suggests Level 1 but structure is Level 0 -โ†’ 1. Upgrade structure 2. Keep minimal 3. Manual adjustment - -# Hierarchy depth violation -โŒ Attempting to create impl-1.2.3.4 (exceeds 3-level limit) -โ†’ 1. Flatten hierarchy 2. Reorganize structure 3. Abort -``` - -## Integration - -### Workflow Updates -- Updates task count in session -- Recalculates progress metrics -- Maintains task hierarchy in both JSON and documents -- Synchronizes document references across all files - -### File System Integration -- **Real-time Sync**: JSON task files updated immediately during breakdown -- **Bidirectional Sync**: Maintains consistency between JSON, TODO_LIST.md, and session -- **Conflict Resolution**: JSON files are authoritative for task details and hierarchy -- **Version Control**: All task changes tracked in .task/ directory -- **Backup Recovery**: Can restore task hierarchy from workflow-session.json -- **Structure Validation**: Ensures compliance with progressive structure standards - -### Next Actions -After breakdown: -- `/task:execute` - Run subtasks using JSON task context -- `/task:status` - View hierarchy from JSON files and TODO_LIST.md -- `/context` - Analyze task relationships and JSON structure -- `/task:replan` - Adjust breakdown and update task structure +### Output Files +- JSON subtask files in `.task/` directory +- Updated parent task JSON with subtask references +- Updated session stats in `workflow-session.json` ## Examples -### Complex Feature +### Simple Breakdown ```bash -/task:breakdown IMPL-1 --strategy=auto --depth=2 +/task:breakdown impl-1 Result: -IMPL-1: E-commerce checkout -โ”œโ”€โ”€ IMPL-1.1: Payment processing -โ”‚ โ”œโ”€โ”€ IMPL-1.1.1: Integrate payment gateway -โ”‚ โ”œโ”€โ”€ IMPL-1.1.2: Handle transactions -โ”‚ โ””โ”€โ”€ IMPL-1.1.3: Add error handling -โ”œโ”€โ”€ IMPL-1.2: Order management -โ”‚ โ”œโ”€โ”€ IMPL-1.2.1: Create order model -โ”‚ โ””โ”€โ”€ IMPL-1.2.2: Implement order workflow -โ””โ”€โ”€ IMPL-1.3: Testing suite +impl-1: Build authentication (container) +โ”œโ”€โ”€ impl-1.1: Design auth schema +โ”œโ”€โ”€ impl-1.2: Implement auth logic +โ”œโ”€โ”€ impl-1.3: Add security middleware +โ””โ”€โ”€ impl-1.4: Write tests +``` + +### Two-Level Breakdown +```bash +/task:breakdown impl-1 --depth=2 + +Result: +impl-1: E-commerce checkout (container) +โ”œโ”€โ”€ impl-1.1: Payment processing +โ”‚ โ”œโ”€โ”€ impl-1.1.1: Integrate gateway +โ”‚ โ””โ”€โ”€ impl-1.1.2: Handle transactions +โ”œโ”€โ”€ impl-1.2: Order management +โ”‚ โ””โ”€โ”€ impl-1.2.1: Create order model +โ””โ”€โ”€ impl-1.3: Testing +``` + +## Error Handling + +```bash +# Task not found +โŒ Task impl-5 not found + +# Already broken down +โš ๏ธ Task impl-1 already has subtasks + +# Max depth exceeded +โŒ Cannot create impl-1.2.3.4 (max 3 levels) ``` ## Related Commands - `/task:create` - Create new tasks -- `/task:context` - Manage task context -- `/task:execute` - Execute subtasks -- `/task:replan` - Adjust breakdown -- `/task:status` - View task hierarchy \ No newline at end of file +- `/task:execute` - Execute subtasks +- `/context` - View task hierarchy \ No newline at end of file diff --git a/.claude/commands/task/create.md b/.claude/commands/task/create.md index 4a6ed1d1..7338f906 100644 --- a/.claude/commands/task/create.md +++ b/.claude/commands/task/create.md @@ -68,234 +68,94 @@ Context inherited from workflow - `test` - Test implementation - `docs` - Documentation -### Priority Levels -- `low` - Can be deferred +### Priority Levels (Optional - moved to context) +- `low` - Can be deferred - `normal` - Standard priority (default) - `high` - Should be done soon - `critical` - Must be done immediately -## Task Structure +**Note**: Priority is now stored in `context.priority` if needed, removed from top level for simplification. + +## Simplified Task Structure ```json { "id": "impl-1", - "parent_id": null, "title": "Build authentication module", - "type": "feature", - "priority": "normal", "status": "pending", - "depth": 1, + "type": "feature", "agent": "code-developer", - "effort": "4h", "context": { - "inherited_from": "WFS-user-auth-system", "requirements": ["JWT authentication", "OAuth2 support"], "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"] + "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], + "inherited_from": "WFS-user-auth" }, - "dependencies": { - "upstream": [], - "downstream": [], - "parent_dependencies": [] + "relations": { + "parent": null, + "subtasks": [], + "dependencies": [] }, - "subtasks": [], - "execution": { "attempts": 0, - "current_attempt": null, - "history": [] + "last_attempt": null }, - "metadata": { - "created_at": "2025-09-05T10:30:00Z", - "started_at": null, - "completed_at": null, - "last_updated": "2025-09-05T10:30:00Z", - "version": "1.0" + "meta": { + "created": "2025-09-05T10:30:00Z", + "updated": "2025-09-05T10:30:00Z" } } ``` -## Document Integration Features +## Simplified File Generation -### JSON Task File Generation -**File Location**: `.workflow/WFS-[topic-slug]/.task/impl-[N].json` -**Hierarchical Naming**: Follows impl-N.M.P format for nested tasks -**Schema Compliance**: All JSON files follow unified task schema from task-management-principles.md +### JSON Task File Only +**File Location**: `.task/impl-[N].json` +**Naming**: Follows impl-N.M.P format for nested tasks +**Content**: Contains all task data (no document coordination needed) -### Import from IMPL_PLAN.md -```bash -/task:create --from-plan +### No Document Synchronization +- Creates JSON task file only +- Updates workflow-session.json stats only +- No automatic TODO_LIST.md generation +- No complex cross-referencing needed + +### View Generation On-Demand +- Use `/context` to generate views when needed +- No persistent markdown files created +- All data stored in JSON only + +## Simplified Task Management + +### Basic Task Statistics +- Task count tracked in workflow-session.json +- No automatic complexity escalation +- Manual workflow type selection during init + +### Simple Creation Process ``` -- Reads existing IMPL_PLAN.md implementation strategy -- Creates JSON task files based on planned structure -- Maintains hierarchical relationships in JSON format -- Preserves acceptance criteria from plan in task context - -### Progressive Document Creation -Based on complexity analysis triggers: - -#### Level 0 Structure (<5 tasks) -- Creates individual JSON task files in `.task/` -- No TODO_LIST.md generation (minimal overhead) -- Updates workflow-session.json with task references - -#### Level 1 Structure (5-15 tasks) -- Creates hierarchical JSON task files (impl-N.M format) -- **Auto-generates TODO_LIST.md** when complexity threshold reached -- Creates `.summaries/` directory structure -- Enhanced cross-referencing between files - -#### Level 2 Structure (>15 tasks) -- Creates complete hierarchical JSON files (impl-N.M.P format) -- Always maintains TODO_LIST.md with progress tracking -- Full `.summaries/` directory with detailed task documentation -- Comprehensive cross-references and validation - -### Document Creation Triggers -TODO_LIST.md auto-generation conditions: -- **Task count > 5** OR **modules > 3** OR **estimated effort > 4h** OR **complex dependencies detected** -- **Always** for workflows with >15 tasks (Level 2 structure) - -### Cross-Reference Management -- All JSON files contain proper parent_id relationships -- TODO_LIST.md links to individual JSON task files -- workflow-session.json maintains task list with hierarchy depth -- Automatic validation of cross-file references - -## Dynamic Complexity Escalation (NEW FEATURE) - -### Automatic Workflow Upgrade System -After each task creation, the system automatically evaluates current workflow complexity and upgrades structure when thresholds are exceeded. - -### Escalation Process -``` -1. Create New Task โ†’ Generate JSON file -2. Count All Tasks โ†’ Read all .task/*.json files -3. Calculate Metrics โ†’ Tasks, modules, dependencies, effort -4. Check Thresholds โ†’ Compare against complexity criteria -5. Trigger Upgrade โ†’ If threshold exceeded, escalate complexity -6. Generate Documents โ†’ Auto-create missing structure documents -7. Update Session โ†’ Record complexity change in workflow-session.json -8. Notify User โ†’ Inform about automatic upgrade +1. Create New Task โ†’ Generate JSON file only +2. Update Session Stats โ†’ Increment task count +3. Notify User โ†’ Confirm task created ``` -### Escalation Triggers - -#### Simple โ†’ Medium Escalation -**Triggered when ANY condition met:** -- Task count reaches 5 (primary trigger) -- Module count exceeds 3 -- Total estimated effort > 4 hours -- Complex dependencies detected -- Cross-component changes required - -**Actions taken:** -```bash -โœ… Task created: impl-5 -โš ๏ธ Complexity threshold reached: 5 tasks (exceeds Simple limit) -๐Ÿ”„ Escalating workflow: Simple โ†’ Medium - -Auto-generating enhanced structure: -โœ… Created TODO_LIST.md with hierarchical task display -โœ… Created .summaries/ directory for task completion tracking -โœ… Updated workflow-session.json complexity level -โœ… Enabled 2-level task hierarchy (impl-N.M) - -Workflow now supports: -- Progress tracking via TODO_LIST.md -- Task decomposition up to 2 levels -- Summary generation for completed tasks -``` - -#### Medium โ†’ Complex Escalation -**Triggered when ANY condition met:** -- Task count reaches 15 (primary trigger) -- Module count exceeds 5 -- Total estimated effort > 2 days -- Multi-repository impacts detected -- Architecture pattern changes required - -**Actions taken:** -```bash -โœ… Task created: impl-15 -โš ๏ธ Complexity threshold reached: 15 tasks (exceeds Medium limit) -๐Ÿ”„ Escalating workflow: Medium โ†’ Complex - -Auto-generating comprehensive structure: -โœ… Enhanced IMPL_PLAN.md with detailed phases and risk assessment -โœ… Expanded TODO_LIST.md with progress monitoring -โœ… Created comprehensive .summaries/ structure -โœ… Updated workflow-session.json complexity level -โœ… Enabled 3-level task hierarchy (impl-N.M.P maximum) - -Workflow now supports: -- Comprehensive progress tracking and monitoring -- Full 3-level task decomposition -- Enhanced documentation and audit trails -- Advanced dependency management -``` - -### Complexity Calculation Algorithm -```javascript -function calculateComplexity(tasks, modules, effort, dependencies) { - // Primary thresholds (hard limits) - if (tasks >= 15 || modules > 5 || effort > 48) return 'complex'; - if (tasks >= 5 || modules > 3 || effort > 4) return 'medium'; - - // Override factors (can force higher complexity) - if (dependencies.includes('multi-repo') || - dependencies.includes('architecture-change')) return 'complex'; - if (dependencies.includes('cross-component') || - dependencies.includes('complex-integration')) return 'medium'; - - return 'simple'; -} -``` - -### Session State Updates During Escalation -```json -{ - "complexity": "medium", - "escalation_history": [ - { - "from": "simple", - "to": "medium", - "triggered_at": "2025-09-07T16:45:00Z", - "trigger_reason": "task_count_threshold", - "task_count_at_escalation": 5, - "auto_generated_documents": ["TODO_LIST.md", ".summaries/"], - "task_hierarchy_enabled": 2 - } - ], - "task_system": { - "max_depth": 2, - "structure_level": "enhanced", - "documents_generated": ["TODO_LIST.md"], - "auto_escalation_enabled": true - } -} -``` - -### Benefits of Dynamic Escalation -- **Seamless Growth**: Workflows grow naturally without user intervention -- **No Overhead for Simple Tasks**: Simple workflows remain minimal -- **Automatic Structure**: Enhanced documentation appears when needed -- **Progressive Enhancement**: Users get appropriate tooling for current complexity -- **Transparent Process**: All escalations logged and reversible +### Benefits of Simplification +- **No Overhead**: Just create tasks, no complex logic +- **Predictable**: Same process every time +- **Fast**: Minimal processing needed +- **Clear**: User controls complexity level ## Context Inheritance Tasks automatically inherit: -1. **Requirements** - From workflow-session.json context and IMPL_PLAN.md -2. **Scope** - File patterns from workflow and IMPL_PLAN.md strategy -3. **Standards** - Quality standards from workflow session -4. **Dependencies** - Related tasks from existing JSON task hierarchy in `.task/` -5. **Parent Context** - When created as subtasks, inherit from parent JSON file -6. **Session Context** - Global workflow context from active session +1. **Requirements** - From workflow-session.json and IMPL_PLAN.md +2. **Scope** - File patterns from workflow context +3. **Parent Context** - When created as subtasks, inherit from parent +4. **Session Context** - Global workflow context from active session ## Smart Suggestions @@ -358,46 +218,29 @@ Created 3 tasks: - impl-3: Write authentication tests ``` -## File Output Management +## File Output -### JSON Task Files -**Output Location**: `.workflow/WFS-[topic-slug]/.task/impl-[id].json` -**Schema**: Follows unified task JSON schema with hierarchical support -**Contents**: Complete task definition including context, dependencies, and metadata +### JSON Task File +**Location**: `.task/impl-[id].json` +**Schema**: Simplified task JSON schema +**Contents**: Complete task definition with context -### TODO_LIST.md Generation -**Trigger Logic**: Auto-created based on complexity thresholds -**Location**: `.workflow/WFS-[topic-slug]/TODO_LIST.md` -**Format**: Hierarchical task display with checkboxes and progress tracking - -### Summary Directory Structure -**Location**: `.workflow/WFS-[topic-slug]/.summaries/` -**Purpose**: Ready for task completion summaries -**Structure**: Created when Level 1+ complexity detected - -### Workflow Session Updates -**File**: `.workflow/WFS-[topic-slug]/workflow-session.json` -**Updates**: Task list, counters, progress calculations, hierarchy depth +### Session Updates +**File**: `workflow-session.json` +**Updates**: Basic task count and active task list only ## Integration -### Workflow Integration -- Updates workflow-session.json with new task references -- Increments task counter and updates complexity assessment -- Updates IMPLEMENT phase progress and task hierarchy depth -- Maintains bidirectional sync with TodoWrite tool - -### File System Coordination -- Validates and creates required directory structure -- Maintains cross-references between all generated files -- Ensures proper naming conventions and hierarchy limits -- Provides rollback capability for failed operations +### Simple Integration +- Updates workflow-session.json stats +- Creates JSON task file +- No complex file coordination needed ### Next Steps After creation, use: -- `/task:breakdown` - Split into hierarchical subtasks with JSON files -- `/task:execute` - Run the task with summary generation -- `/context` - View task details, status and relationships +- `/task:breakdown` - Split into subtasks +- `/task:execute` - Run the task +- `/context` - View task details and status ## Examples diff --git a/.claude/commands/task/execute.md b/.claude/commands/task/execute.md index 386c4780..337ae558 100644 --- a/.claude/commands/task/execute.md +++ b/.claude/commands/task/execute.md @@ -135,39 +135,38 @@ END FUNCTION - **Conditional Execution (`--if="..."`)**: Proceeds with execution only if a specified condition (e.g., `"tests-pass"`) is met. - **Rollback (`--rollback`)**: Reverts file modifications and restores the previous task state. -### ๐Ÿ“„ **Standard Context Structure (JSON)** +### ๐Ÿ“„ **Simplified Context Structure (JSON)** -This is the standard data structure loaded to provide context for task execution. +This is the simplified data structure loaded to provide context for task execution. ```json { "task": { - "id": "IMPL-001", + "id": "impl-1", "title": "Build authentication module", "type": "feature", "status": "active", "agent": "code-developer", "context": { - "inherited_from": "WFS-[topic-slug]", "requirements": ["JWT authentication", "OAuth2 support"], "scope": ["src/auth/*", "tests/auth/*"], - "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"] + "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented"], + "inherited_from": "WFS-user-auth" + }, + "relations": { + "parent": null, + "subtasks": ["impl-1.1", "impl-1.2"], + "dependencies": ["impl-0"] } }, "workflow": { - "session": "WFS-[topic-slug]", - "phase": "IMPLEMENT", - "global_context": ["Security first", "Backward compatible"] + "session": "WFS-user-auth", + "phase": "IMPLEMENT" }, "execution": { "agent": "code-developer", "mode": "auto", - "checkpoints": ["setup", "implement", "test", "validate"], - "attempts": 1, - "current_attempt": { - "started_at": "2025-09-05T10:35:00Z", - "completed_checkpoints": ["setup"] - } + "attempts": 0 } } ``` @@ -180,37 +179,28 @@ Different agents receive context tailored to their function: - **`test-agent`**: Test requirements, code to be tested, coverage goals. - **`review-agent`**: Quality standards, style guides, review criteria. -### ๐Ÿ—ƒ๏ธ **File Output & System Integration** +### ๐Ÿ—ƒ๏ธ **Simplified File Output** -- **Task JSON File (`.task/.json`)**: The authoritative source. Updated with status, execution history, and metadata. -- **TODO List (`TODO_LIST.md`)**: The task's checkbox is updated, progress is recalculated, and links to the summary file are added. -- **Session File (`workflow-session.json`)**: Task completion status and overall phase progress are updated. -- **Summary File**: Generated in `.workflow/WFS-[...]/summaries/` upon successful completion. +- **Task JSON File (`.task/.json`)**: Updated with status and last attempt time only. +- **Session File (`workflow-session.json`)**: Updated task stats (completed count). +- **Summary File**: Generated in `.summaries/` upon completion (optional). -### ๐Ÿ“ **Summary File Template** +### ๐Ÿ“ **Simplified Summary Template** -A summary file is generated at `.workflow/WFS-[topic-slug]/.summaries/IMPL-[task-id]-summary.md`. +Optional summary file generated at `.summaries/impl-[task-id]-summary.md`. ```markdown -# Task Summary: IMPL-001 Build Authentication Module +# Task Summary: impl-1 Build Authentication Module ## What Was Done - Created src/auth/login.ts with JWT validation -- Modified src/auth/validate.ts for enhanced security -- Added comprehensive tests in tests/auth.test.ts +- Added tests in tests/auth.test.ts ## Execution Results -- **Duration**: 23 minutes - **Agent**: code-developer -- **Tests Passed**: 12/12 (100%) -- **Coverage**: 87% +- **Status**: completed ## Files Modified - `src/auth/login.ts` (created) -- `src/auth/validate.ts` (modified) - `tests/auth.test.ts` (created) - -## Links -- [๐Ÿ”™ Back to Task List](../TODO_LIST.md#impl-001) -- [๐Ÿ“Œ Task Details](../.task/impl-001.json) ``` diff --git a/.claude/commands/task/replan.md b/.claude/commands/task/replan.md index 697d5df6..8b2a4a59 100644 --- a/.claude/commands/task/replan.md +++ b/.claude/commands/task/replan.md @@ -1,466 +1,518 @@ --- name: task-replan -description: Dynamically replan tasks based on changes, blockers, or new requirements -usage: /task:replan [task-id|--all] [--reason=] [--strategy=] -argument-hint: [task-id or --all] [optional: reason and strategy] +description: Replan individual tasks with detailed user input and change tracking +usage: /task:replan [input-source] +argument-hint: task-id [text|--from-file|--from-issue|--detailed|--interactive] examples: - - /task:replan IMPL-001 --reason="requirements changed" - - /task:replan --all --reason="new security requirements" - - /task:replan IMPL-003 --strategy=rebuild + - /task:replan impl-1 "Add OAuth2 authentication support" + - /task:replan impl-1 --from-file updated-specs.md + - /task:replan impl-1 --from-issue ISS-001 + - /task:replan impl-1 --detailed + - /task:replan impl-1 --interactive --- # Task Replan Command (/task:replan) ## Overview -Dynamically adjusts task planning based on changes, new requirements, blockers, or execution results. +Replans individual tasks based on detailed user input with comprehensive change tracking, version management, and document synchronization. Focuses exclusively on single-task modifications with rich input options. ## Core Principles -**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md +**System:** @~/.claude/workflows/unified-workflow-system-principles.md +**Task Management:** @~/.claude/workflows/task-management-principles.md +## Single-Task Focus +This command operates on **individual tasks only**. For workflow-wide changes, use `/workflow:action-plan` instead. -## Replan Triggers +โš ๏ธ **CRITICAL**: Before replanning, checks for existing active session to avoid conflicts. -โš ๏ธ **CRITICAL**: Before replanning, MUST check for existing active session to avoid creating duplicate sessions. +## Input Sources for Replanning -### Session Check Process -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it. -2. **Session Validation**: Use existing active session containing the task to be replanned -3. **Context Integration**: Load existing session state and task hierarchy - -### Automatic Detection -System detects replanning needs from file monitoring: -- Requirements changed in workflow-session.json -- Dependencies blocked in JSON task hierarchy -- Task failed execution (logged in JSON execution history) -- New issues discovered and associated with tasks -- Scope modified in task context or IMPL_PLAN.md -- File structure complexity changes requiring reorganization - -### Manual Triggers +### Direct Text Input (Default) ```bash -/task:replan IMPL-001 --reason="API spec updated" +/task:replan impl-1 "Add OAuth2 authentication support" +``` +**Processing**: +- Parse specific changes and requirements +- Extract new features or modifications needed +- Apply directly to target task structure + +### File-based Requirements +```bash +/task:replan impl-1 --from-file updated-specs.md +/task:replan impl-1 --from-file requirements-change.txt +``` +**Supported formats**: .md, .txt, .json, .yaml +**Processing**: +- Read detailed requirement changes from file +- Parse structured specifications and updates +- Apply file content to task replanning + +### Issue-based Replanning +```bash +/task:replan impl-1 --from-issue ISS-001 +/task:replan impl-1 --from-issue "bug-report" +``` +**Processing**: +- Load issue description and requirements +- Extract necessary changes for task +- Apply issue resolution to task structure + +### Detailed Mode +```bash +/task:replan impl-1 --detailed +``` +**Guided Input**: +1. **New Requirements**: What needs to be added/changed? +2. **Scope Changes**: Expand/reduce task scope? +3. **Subtask Modifications**: Add/remove/modify subtasks? +4. **Dependencies**: Update task relationships? +5. **Success Criteria**: Modify completion conditions? +6. **Agent Assignment**: Change assigned agent? + +### Interactive Mode +```bash +/task:replan impl-1 --interactive +``` +**Step-by-Step Process**: +1. **Current Analysis**: Review existing task structure +2. **Change Identification**: What needs modification? +3. **Impact Assessment**: How changes affect task? +4. **Structure Updates**: Add/modify subtasks +5. **Validation**: Confirm changes before applying + +## Replanning Flow with Change Tracking + +### 1. Task Loading & Validation +``` +Load Task โ†’ Read current task JSON file +Validate โ†’ Check task exists and can be modified +Session Check โ†’ Verify active workflow session ``` -## Replan Strategies - -### 1. Adjust Strategy (Default) -Minimal changes to existing plan: -```bash -/task:replan IMPL-001 --strategy=adjust - -Adjustments for IMPL-001: -- Updated requirements -- Modified subtask IMPL-001.2 -- Added validation step -- Kept 80% of original plan +### 2. Input Processing +``` +Detect Input Type โ†’ Identify source type +Extract Requirements โ†’ Parse change requirements +Analyze Impact โ†’ Determine modifications needed ``` -### 2. Rebuild Strategy -Complete replanning from scratch: -```bash -/task:replan IMPL-001 --strategy=rebuild - -Rebuilding IMPL-001: -- Analyzing new requirements -- Generating new breakdown -- Reassigning agents -- New execution plan created +### 3. Version Management +``` +Create Version โ†’ Backup current task state +Update Version โ†’ Increment task version number +Archive โ†’ Store previous version in versions/ ``` -## Usage Scenarios - -### Scenario 1: Requirements Change -```bash -/task:replan IMPL-001 --reason="Added OAuth2 requirement" - -Analyzing impact... -Current plan: -- IMPL-001.1: Basic login โœ… Complete -- IMPL-001.2: Session management (in progress) -- IMPL-001.3: Tests - -Recommended changes: -+ Add IMPL-001.4: OAuth2 integration -~ Modify IMPL-001.2: Include OAuth session -~ Update IMPL-001.3: Add OAuth tests - -Apply changes? (y/n): y -โœ… Task replanned successfully +### 4. Task Structure Updates +``` +Modify Task โ†’ Update task JSON structure +Update Subtasks โ†’ Add/remove/modify as needed +Update Relations โ†’ Fix dependencies and hierarchy +Update Context โ†’ Modify requirements and scope ``` -### Scenario 2: Blocked Task -```bash -/task:replan IMPL-003 --reason="API not ready" - -Task blocked analysis: -- IMPL-003 depends on external API -- API delayed by 2 days -- 3 tasks depend on IMPL-003 - -Replan options: -1. Defer IMPL-003 and dependents -2. Create mock API for development -3. Reorder to work on independent tasks - -Select option: 2 - -Creating new plan: -+ IMPL-003.0: Create API mock -~ IMPL-003.1: Use mock for development -~ Add note: Replace mock when API ready +### 5. Document Synchronization +``` +Update IMPL_PLAN โ†’ Regenerate task section +Update TODO_LIST โ†’ Sync task hierarchy (if exists) +Update Session โ†’ Reflect changes in workflow state ``` -### Scenario 3: Failed Execution -```bash -/task:replan IMPL-002 --reason="execution failed" - -Failure analysis: -- Failed at: Testing phase -- Reason: Performance issues -- Impact: Blocks 2 downstream tasks - -Replan approach: -1. Break down into smaller tasks -2. Add performance optimization task -3. Adjust testing approach - -New structure: -IMPL-002 (failed) โ†’ -โ”œโ”€โ”€ IMPL-002.1: Core functionality (smaller scope) -โ”œโ”€โ”€ IMPL-002.2: Performance optimization -โ”œโ”€โ”€ IMPL-002.3: Load testing -โ””โ”€โ”€ IMPL-002.4: Integration - -โœ… Replanned with focus on incremental delivery +### 6. Change Documentation +``` +Create Change Log โ†’ Document all modifications +Generate Summary โ†’ Create replan report +Update History โ†’ Add to task replan history ``` -## Global Replanning +## Version Management (Simplified) -### Replan All Tasks -```bash -/task:replan --all --reason="Architecture change" - -Global replan analysis: -- Total tasks: 8 -- Completed: 3 (keep as-is) -- In progress: 2 (need adjustment) -- Pending: 3 (full replan) - -Changes summary: -- 2 tasks modified -- 1 task removed (no longer needed) -- 2 new tasks added -- Dependencies reordered - -Preview changes? (y/n): y -[Detailed change list] - -Apply all changes? (y/n): y -โœ… All tasks replanned -``` - -## Impact Analysis - -### Before Replanning -```bash -/task:replan IMPL-001 --preview - -Impact Preview: -If IMPL-001 is replanned: -- Affected tasks: 4 -- Timeline impact: +1 day -- Resource changes: Need planning-agent -- Risk level: Medium - -Dependencies affected: -- IMPL-003: Will need adjustment -- IMPL-004: Delay expected -- IMPL-005: No impact - -Continue? (y/n): -``` - -## Replan Operations - -### Add Subtasks -```bash -/task:replan IMPL-001 --add-subtask - -Current subtasks: -1. IMPL-001.1: Design -2. IMPL-001.2: Implement - -Add new subtask: -Title: Add security layer -Position: After IMPL-001.2 -Agent: code-developer - -โœ… Added IMPL-001.3: Add security layer -``` - -### Remove Subtasks -```bash -/task:replan IMPL-001 --remove-subtask=IMPL-001.3 - -โš ๏ธ Remove IMPL-001.3? -This will: -- Delete subtask and its context -- Update parent progress -- Adjust dependencies - -Confirm? (y/n): y -โœ… Subtask removed -``` - -### Reorder Tasks -```bash -/task:replan --reorder - -Current order: -1. IMPL-001: Auth -2. IMPL-002: Database -3. IMPL-003: API - -Suggested reorder (based on dependencies): -1. IMPL-002: Database -2. IMPL-001: Auth -3. IMPL-003: API - -Apply reorder? (y/n): y -โœ… Tasks reordered -``` - -## Smart Recommendations - -### AI-Powered Suggestions -```bash -/task:replan IMPL-001 --suggest - -Analysis complete. Suggestions: -1. ๐Ÿ”„ Split IMPL-001.2 (too complex) -2. โฑ๏ธ Reduce scope to meet deadline -3. ๐Ÿค Parallelize IMPL-001.1 and IMPL-001.3 -4. ๐Ÿ“ Add documentation task -5. ๐Ÿงช Increase test coverage requirement - -Apply suggestion: 1 - -Splitting IMPL-001.2: -โ†’ IMPL-001.2.1: Core implementation -โ†’ IMPL-001.2.2: Error handling -โ†’ IMPL-001.2.3: Optimization -โœ… Applied successfully -``` - -## Version Control & File Management - -### JSON Task Version History -**File-Based Versioning**: Each replan creates version history in JSON metadata - -```bash -/task:replan impl-001 --history - -Plan versions for impl-001 (from JSON file): -v3 (current): 4 subtasks, 2 complete - JSON files: impl-001.1.json to impl-001.4.json -v2: 3 subtasks (archived) - Backup: .task/archive/impl-001-v2-backup.json -v1: 2 subtasks (initial) - Backup: .task/archive/impl-001-v1-backup.json - -Version files available: -- Current: .task/impl-001.json -- Backups: .task/archive/impl-001-v[N]-backup.json -- Change log: .summaries/replan-history-impl-001.md - -Rollback to version: 2 -โš ๏ธ This will: -- Restore JSON files from backup -- Regenerate TODO_LIST.md structure -- Update workflow-session.json -- Archive current version - -Continue? (y/n): -``` - -### Replan Documentation Generation -**Change Tracking Files**: Auto-generated documentation of all changes - -```bash -# Generates: .summaries/replan-[task-id]-[timestamp].md -/task:replan impl-001 --reason="API changes" --document - -Creating replan documentation... - -๐Ÿ“ Replan Report: impl-001 -Generated: 2025-09-07 16:00:00 -Reason: API changes -Version: v2 โ†’ v3 - -## Changes Made -- Added subtask impl-001.4: Handle new API endpoints -- Modified impl-001.2: Updated authentication flow -- Removed impl-001.3: No longer needed due to API changes - -## File Changes -- Created: .task/impl-001.4.json -- Modified: .task/impl-001.2.json -- Archived: .task/impl-001.3.json โ†’ .task/archive/ -- Updated: TODO_LIST.md hierarchy -- Updated: workflow-session.json task count - -## Impact Analysis -- Timeline: +2 days (new subtask) -- Dependencies: impl-002 now depends on impl-001.4 -- Resources: Need API specialist for impl-001.4 - -Report saved: .summaries/replan-impl-001-20250907-160000.md -``` - -### Enhanced JSON Change Tracking -**Complete Replan History**: All changes documented in JSON files and reports +### Version Tracking +Each replan creates a new version with complete history: ```json { - "task_id": "impl-001", + "id": "impl-1", "title": "Build authentication module", - "status": "active", "version": "1.2", - "replan_history": [ { - "version": "1.2", - "timestamp": "2025-09-07T16:00:00Z", - "reason": "API changes", - "changes_summary": "Added API endpoint handling, removed deprecated auth flow", - "backup_location": ".task/archive/impl-001-v1.1-backup.json", - "documentation": ".summaries/replan-impl-001-20250907-160000.md", - "files_affected": [ - { - "action": "created", - "file": ".task/impl-001.4.json", - "description": "New API endpoint handling subtask" - }, - { - "action": "modified", - "file": ".task/impl-001.2.json", - "description": "Updated authentication flow" - }, - { - "action": "archived", - "file": ".task/impl-001.3.json", - "location": ".task/archive/impl-001.3-deprecated.json" - } + "version": "1.1", + "date": "2025-09-08T10:00:00Z", + "reason": "Original plan", + "input_source": "initial_creation" + }, + { + "version": "1.2", + "date": "2025-09-08T14:00:00Z", + "reason": "Add OAuth2 authentication support", + "input_source": "direct_text", + "changes": [ + "Added subtask impl-1.3: OAuth2 integration", + "Added subtask impl-1.4: Token management", + "Modified scope to include external auth" ], - "todo_list_regenerated": true, - "session_updated": true + "backup_location": ".task/versions/impl-1-v1.1.json" } ], - - "subtasks": ["impl-001.1", "impl-001.2", "impl-001.4"], - - "metadata": { - "version": "1.2", - "last_updated": "2025-09-07T16:00:00Z", - "last_replan": "2025-09-07T16:00:00Z", - "replan_count": 2 + "context": { + "requirements": ["Basic auth", "Session mgmt", "OAuth2 support"], + "scope": ["src/auth/*", "tests/auth/*"], + "acceptance": ["All auth methods work"] } } ``` -## File System Integration - -### Comprehensive File Updates -**Multi-File Synchronization**: Ensures consistency across all workflow files - -#### JSON Task File Management -- **Version Backups**: Automatic backup before major changes -- **Hierarchical Updates**: Cascading changes through parent-child relationships -- **Archive Management**: Deprecated task files moved to `.task/archive/` -- **Metadata Tracking**: Complete change history in JSON metadata - -#### TODO_LIST.md Regeneration -**Smart Regeneration**: Updates based on structural changes - -```bash -/task:replan impl-001 --regenerate-todo - -Analyzing structural changes from replan... -Current TODO_LIST.md: 8 tasks displayed -New task structure: 9 tasks (1 added, 1 removed, 2 modified) - -Regenerating TODO_LIST.md... -โœ… Updated task hierarchy display -โœ… Recalculated progress percentages -โœ… Updated cross-references to JSON files -โœ… Added links to new summary files - -TODO_LIST.md updated with new structure +### File Structure After Replan +``` +.task/ +โ”œโ”€โ”€ impl-1.json # Current version (1.2) +โ”œโ”€โ”€ impl-1.3.json # New subtask +โ”œโ”€โ”€ impl-1.4.json # New subtask +โ”œโ”€โ”€ versions/ +โ”‚ โ””โ”€โ”€ impl-1-v1.1.json # Previous version backup +โ””โ”€โ”€ summaries/ + โ””โ”€โ”€ replan-impl-1-20250908.md # Change log ``` -#### Workflow Session Updates -- **Task Count Updates**: Reflect additions/removals in session -- **Progress Recalculation**: Update completion percentages -- **Complexity Assessment**: Re-evaluate structure level if needed -- **Dependency Validation**: Check all task dependencies remain valid +## IMPL_PLAN.md Updates -### Documentation Generation -**Automatic Report Creation**: Every replan generates documentation +### Automatic Plan Regeneration +When task is replanned, the corresponding section in IMPL_PLAN.md is updated: -- **Replan Report**: `.summaries/replan-[task-id]-[timestamp].md` -- **Change Summary**: Detailed before/after comparison -- **Impact Analysis**: Effects on timeline, dependencies, resources -- **File Change Log**: Complete list of affected files -- **Rollback Instructions**: How to revert changes if needed +**Before Replan**: +```markdown +## Task Breakdown +- **IMPL-001**: Build authentication module + - Basic login functionality + - Session management + - Password reset +``` -### Issue Integration +**After Replan**: +```markdown +## Task Breakdown +- **IMPL-001**: Build authentication module (v1.2) + - Basic login functionality + - Session management + - OAuth2 integration (added) + - Token management (added) + - Password reset + +*Last updated: 2025-09-08 14:00 via task:replan* +``` + +### Plan Update Process +1. **Locate Task Section**: Find task in IMPL_PLAN.md by ID +2. **Update Description**: Modify task title if changed +3. **Update Subtasks**: Add/remove bullet points for subtasks +4. **Add Version Info**: Include version number and update timestamp +5. **Preserve Context**: Keep surrounding plan structure intact + +## TODO_LIST.md Synchronization + +### Automatic TODO List Updates +If TODO_LIST.md exists in workflow, synchronize task changes: + +**Before Replan**: +```markdown +## Implementation Tasks +- [ ] impl-1: Build authentication module + - [x] impl-1.1: Design schema + - [ ] impl-1.2: Implement logic +``` + +**After Replan**: +```markdown +## Implementation Tasks +- [ ] impl-1: Build authentication module (updated v1.2) + - [x] impl-1.1: Design schema + - [ ] impl-1.2: Implement logic + - [ ] impl-1.3: OAuth2 integration (new) + - [ ] impl-1.4: Token management (new) +``` + +### TODO Update Rules +- **Preserve Status**: Keep existing checkbox states [x] or [ ] +- **Add New Items**: New subtasks get [ ] checkbox +- **Mark Changes**: Add (updated), (new), (modified) indicators +- **Remove Items**: Delete subtasks that were removed +- **Update Hierarchy**: Maintain proper indentation structure + +## Change Documentation + +### Comprehensive Change Log +Every replan generates detailed documentation: + +```markdown +# Task Replan Log: impl-1 +*Date: 2025-09-08T14:00:00Z* +*Version: 1.1 โ†’ 1.2* +*Input: Direct text - "Add OAuth2 authentication support"* + +## Changes Applied + +### Task Structure Updates +- **Added Subtasks**: + - impl-1.3: OAuth2 provider integration + - impl-1.4: Token management system +- **Modified Subtasks**: + - impl-1.2: Updated to include OAuth flow integration +- **Removed Subtasks**: None + +### Context Modifications +- **Requirements**: Added OAuth2 external authentication +- **Scope**: Expanded to include third-party auth integration +- **Acceptance**: Include OAuth2 token validation +- **Dependencies**: No changes + +### File System Updates +- **Updated**: .task/impl-1.json (version 1.2) +- **Created**: .task/impl-1.3.json, .task/impl-1.4.json +- **Backed Up**: .task/versions/impl-1-v1.1.json +- **Updated**: IMPL_PLAN.md (task section regenerated) +- **Updated**: TODO_LIST.md (2 new items added) + +## Impact Analysis +- **Timeline**: +2 days for OAuth implementation +- **Complexity**: Increased (simple โ†’ medium) +- **Agent**: Remains code-developer, may need OAuth expertise +- **Dependencies**: Task impl-2 may need OAuth context + +## Related Tasks Affected +- impl-2: May need OAuth integration context +- impl-5: Authentication dependency updated + +## Rollback Information +- **Previous Version**: 1.1 +- **Backup Location**: .task/versions/impl-1-v1.1.json +- **Rollback Command**: `/task:replan impl-1 --rollback v1.1` +``` + +## Session State Updates + +### Workflow Integration +After task replanning, update session information: + +```json +{ + "phases": { + "IMPLEMENT": { + "tasks": ["impl-1", "impl-2", "impl-3"], + "completed_tasks": [], + "modified_tasks": { + "impl-1": { + "version": "1.2", + "last_replan": "2025-09-08T14:00:00Z", + "reason": "OAuth2 integration added" + } + }, + "task_count": { + "total": 6, + "added_today": 2 + } + } + }, + "documents": { + "IMPL_PLAN.md": { + "last_updated": "2025-09-08T14:00:00Z", + "updated_sections": ["IMPL-001"] + }, + "TODO_LIST.md": { + "last_updated": "2025-09-08T14:00:00Z", + "items_added": 2 + } + } +} +``` + +## Rollback Support (Simple) + +### Basic Version Rollback ```bash -/task:replan IMPL-001 --from-issue=ISS-001 +/task:replan impl-1 --rollback v1.1 + +Rollback Analysis: +Current Version: 1.2 +Target Version: 1.1 +Changes to Revert: +- Remove subtasks: impl-1.3, impl-1.4 +- Restore previous context +- Update IMPL_PLAN.md section +- Update TODO_LIST.md structure + +Files Affected: +- Restore: .task/impl-1.json from backup +- Remove: .task/impl-1.3.json, .task/impl-1.4.json +- Update: IMPL_PLAN.md, TODO_LIST.md + +Confirm rollback? (y/n): y + +Rolling back... +โœ… Task impl-1 rolled back to version 1.1 +โœ… Documents updated +โœ… Change log created +``` + +## Practical Examples + +### Example 1: Add Feature with Full Tracking +```bash +/task:replan impl-1 "Add two-factor authentication" + +Loading task impl-1 (current version: 1.2)... + +Processing request: "Add two-factor authentication" +Analyzing required changes... + +Proposed Changes: ++ Add impl-1.5: Two-factor setup ++ Add impl-1.6: 2FA validation +~ Modify impl-1.2: Include 2FA in auth flow + +Apply changes? (y/n): y + +Executing replan... +โœ“ Version 1.3 created +โœ“ Added 2 new subtasks +โœ“ Modified 1 existing subtask +โœ“ IMPL_PLAN.md updated +โœ“ TODO_LIST.md synchronized +โœ“ Change log saved + +Result: +- Task version: 1.2 โ†’ 1.3 +- Subtasks: 4 โ†’ 6 +- Documents updated: 2 +- Backup: .task/versions/impl-1-v1.2.json +``` + +### Example 2: Issue-based Replanning +```bash +/task:replan impl-2 --from-issue ISS-001 Loading issue ISS-001... -Issue: "Login timeout too short" -Type: Bug +Issue: "Database queries too slow - need caching" Priority: High -Suggested replan: -+ Add IMPL-001.4: Fix login timeout -~ Adjust IMPL-001.3: Include timeout tests +Applying to task impl-2... -Apply? (y/n): y +Required changes for performance fix: ++ Add impl-2.4: Implement Redis caching ++ Add impl-2.5: Query optimization +~ Modify impl-2.1: Add cache checks + +Documents updating: +โœ“ Task JSON updated (v1.0 โ†’ v1.1) +โœ“ IMPL_PLAN.md section regenerated +โœ“ TODO_LIST.md: 2 new items added +โœ“ Issue ISS-001 linked to task + +Summary: +Performance improvements added to impl-2 +Timeline impact: +1 day for caching setup +``` + +### Example 3: Interactive Replanning +```bash +/task:replan impl-3 --interactive + +Interactive Replan for impl-3: API integration +Current version: 1.0 + +1. What needs to change? "API spec updated, need webhook support" +2. Add new requirements? "Webhook handling, signature validation" +3. Add subtasks? "y" + - New subtask 1: "Webhook receiver endpoint" + - New subtask 2: "Signature validation" + - Add more? "n" +4. Modify existing subtasks? "n" +5. Update dependencies? "Now depends on impl-1 (auth for webhooks)" +6. Change agent assignment? "n" + +Applying interactive changes... +โœ“ Added 2 subtasks for webhook functionality +โœ“ Updated dependencies +โœ“ Context expanded for webhook requirements +โœ“ Version 1.1 created +โœ“ All documents synchronized + +Interactive replan complete! ``` ## Error Handling +### Input Validation Errors ```bash -# Cannot replan completed task -โŒ Task IMPL-001 is completed -โ†’ Create new task instead +# Task not found +โŒ Task impl-5 not found in current session +โ†’ Check task ID with /context -# No reason provided -โš ๏ธ Please provide reason for replanning -โ†’ Use --reason="explanation" +# No input provided +โŒ Please specify changes needed for replanning +โ†’ Use descriptive text or --detailed/--interactive -# Conflicts detected -โš ๏ธ Replan conflicts with IMPL-002 -โ†’ Resolve with --force or adjust plan +# Task completed +โš ๏ธ Task impl-1 is completed (cannot replan) +โ†’ Create new task for additional work + +# File not found +โŒ File updated-specs.md not found +โ†’ Check file path and try again ``` -## File Output Summary +### Document Update Issues +```bash +# Missing IMPL_PLAN.md +โš ๏ธ IMPL_PLAN.md not found in workflow +โ†’ Task update proceeding, plan regeneration skipped -### Generated Files -- **Backup Files**: `.task/archive/[task-id]-v[N]-backup.json` -- **Replan Reports**: `.summaries/replan-[task-id]-[timestamp].md` -- **Change Logs**: Embedded in JSON task file metadata -- **Updated TODO_LIST.md**: Reflects new task structure -- **Archive Directory**: `.task/archive/` for deprecated files +# TODO_LIST.md not writable +โš ๏ธ Cannot update TODO_LIST.md (permissions) +โ†’ Task updated, manual TODO sync needed -### File System Maintenance -- **Automatic Cleanup**: Archive old versions after 30 days -- **Integrity Validation**: Ensure all references remain valid after changes -- **Rollback Support**: Complete restoration capability from backups -- **Cross-Reference Updates**: Maintain links between all workflow files +# Session conflict +โš ๏ธ Task impl-1 being modified in another session +โ†’ Complete other operation first +``` + +## Integration Points + +### Command Workflow +```bash +# 1. Replan task with new requirements +/task:replan impl-1 "Add advanced security features" + +# 2. View updated task structure +/context impl-1 +โ†’ Shows new version with changes + +# 3. Check updated planning documents +cat IMPL_PLAN.md +โ†’ Task section shows v1.3 with new features + +# 4. Verify TODO list synchronization +cat TODO_LIST.md +โ†’ New subtasks appear with [ ] checkboxes + +# 5. Execute replanned task +/task:execute impl-1 +โ†’ Works with updated task structure +``` + +### Session Integration +- **Task Count Updates**: Reflect additions/removals in session stats +- **Document Sync**: Keep IMPL_PLAN.md and TODO_LIST.md current +- **Version Tracking**: Complete audit trail in task JSON +- **Change Traceability**: Link replans to input sources ## Related Commands -- `/task:breakdown` - Initial task breakdown with JSON file creation -- `/context` - Analyze current state from file system -- `/task:execute` - Execute replanned tasks with new structure -- `/context` - View updated task structure and relationships -- `/workflow:replan` - Replan entire workflow with session updates \ No newline at end of file +- `/context` - View task structure and version history +- `/task:execute` - Execute replanned tasks with new structure +- `/workflow:action-plan` - For workflow-wide replanning +- `/task:create` - Create new tasks for additional work + +--- + +**System ensures**: Focused single-task replanning with comprehensive change tracking, document synchronization, and complete audit trail \ No newline at end of file diff --git a/.claude/commands/workflow/action-plan.md b/.claude/commands/workflow/action-plan.md index 55800cd1..b01fec3a 100644 --- a/.claude/commands/workflow/action-plan.md +++ b/.claude/commands/workflow/action-plan.md @@ -1,504 +1,386 @@ --- name: workflow-action-plan -description: Action planning phase that integrates brainstorming insights or user input to create executable implementation plans -usage: /workflow:action-plan [--from-brainstorming] [--skip-brainstorming] [--replan] [--trigger=] -argument-hint: [optional: from brainstorming, skip brainstorming, replan mode, or replan trigger] +description: Create implementation plans from various input sources +usage: /workflow:action-plan [input-source] [--complexity=] +argument-hint: [text|--from-file|--from-issue|--template|--interactive|--from-brainstorming] [optional: complexity] examples: + - /workflow:action-plan "Build authentication system" + - /workflow:action-plan --from-file requirements.md + - /workflow:action-plan --from-issue ISS-001 + - /workflow:action-plan --template web-api + - /workflow:action-plan --interactive - /workflow:action-plan --from-brainstorming - - /workflow:action-plan --skip-brainstorming "implement OAuth authentication" - - /workflow:action-plan --replan --trigger=requirement-change - - /workflow:action-plan --from-brainstorming --scope=all --strategy=minimal-disruption --- # Workflow Action Plan Command (/workflow:action-plan) ## Overview -Creates actionable implementation plans based on brainstorming insights or direct user input. Establishes project structure, understands existing workflow context, and generates executable plans with proper task decomposition and resource allocation. +Creates actionable implementation plans from multiple input sources including direct text, files, issues, templates, interactive sessions, and brainstorming outputs. Supports flexible requirement gathering with optional task decomposition. ## Core Principles **System:** @~/.claude/workflows/unified-workflow-system-principles.md -## Input Sources & Planning Approaches +## Input Sources & Processing -### Brainstorming-Based Planning (--from-brainstorming) -**Prerequisites**: Completed brainstorming session with multi-agent analysis -**Input Sources**: -- `.workflow/WFS-[topic-slug]/.brainstorming/[agent]/analysis.md` files -- `.workflow/WFS-[topic-slug]/.brainstorming/synthesis-analysis.md` -- `.workflow/WFS-[topic-slug]/.brainstorming/recommendations.md` -- `workflow-session.json` brainstorming phase results - -### Direct User Input Planning (--skip-brainstorming) -**Prerequisites**: User provides task description and requirements -**Input Sources**: -- User task description and requirements -- Existing project structure analysis -- Session context from workflow-session.json (if exists) - -### Session Context Detection - -โš ๏ธ **CRITICAL**: Before planning, MUST check for existing active session to avoid creating duplicate sessions. - -**Session Check Process:** -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it. -2. **Session Selection**: Use existing active session or create new one only if none exists -3. **Context Integration**: Load existing session state and brainstorming outputs - -```json -{ - "session_id": "WFS-[topic-slug]", - "type": "simple|medium|complex", - "current_phase": "PLAN", - "session_source": "existing_active|new_creation", - "brainstorming": { - "status": "completed|skipped", - "output_directory": ".workflow/WFS-[topic-slug]/.brainstorming/", - "insights_available": true|false - } -} -``` - -### Planning Depth & Document Generation -- **Simple**: Skip detailed planning, generate minimal IMPL_PLAN.md or go direct to IMPLEMENT -- **Medium**: Standard planning with IMPL_PLAN.md generation (1-2 agents) -- **Complex**: Full planning with comprehensive IMPL_PLAN.md (enhanced structure) - -## Execution Flow - -### Phase 1: Context Understanding & Structure Establishment -1. **Session Detection & Selection**: - - **Check Active Sessions**: Query `.workflow/session_status.jsonl` for existing active sessions. If the file doesn't exist, create it. - - **Session Priority**: Use existing active session if available, otherwise create new session - - **Session Analysis**: Read and understand workflow-session.json from selected session - - Detect existing brainstorming outputs - - Identify current phase and progress - - Understand project context and requirements - -2. **File Structure Assessment**: - - **If brainstorming exists**: Verify `.workflow/WFS-[topic-slug]/.brainstorming/` structure - - **If no structure exists**: Create complete workflow directory structure - - **Document Discovery**: Identify all existing planning documents - -3. **Input Source Determination**: - - **From Brainstorming**: Read all agent analyses and synthesis documents - - **Skip Brainstorming**: Collect user requirements and context directly - - **Hybrid**: Combine existing insights with new user input - -### Phase 2: Context Integration & Requirements Analysis -4. **Requirements Synthesis**: - - **From Brainstorming**: Integrate multi-agent perspectives and recommendations - - **From User Input**: Analyze and structure user-provided requirements - - **Gap Analysis**: Identify missing information and clarify with user - -5. **Complexity Assessment**: Determine planning depth needed based on: - - Scope of requirements (brainstorming insights or user input) - - Technical complexity indicators - - Resource and timeline constraints - - Risk assessment from available information - -### Phase 3: Document Generation & Planning -6. **Create Document Directory**: Setup `.workflow/WFS-[topic-slug]/` structure (if needed) - -7. **Execute Planning**: - - **Simple**: Minimal documentation, direct to IMPLEMENT - - **Medium**: Generate IMPL_PLAN.md with task breakdown - - **Complex**: Generate comprehensive IMPL_PLAN.md with staged approach and risk assessment - -8. **Auto-Generate Tasks (NEW)**: Parse IMPL_PLAN.md and automatically create corresponding task JSON files - - **Extract Tasks**: Parse task identifiers (IMPL-001, IMPL-002, etc.) from plan - - **Create Task Files**: Generate `.task/impl-*.json` files with plan context - - **Link to Plan**: Include `source_plan_ref` field linking tasks back to plan sections - - **Set Dependencies**: Establish task dependencies based on plan structure - -9. **Update Session**: Mark PLAN phase complete with document references and generated task list - -10. **Link Documents**: Update JSON state with generated document paths and task file references - -## Automated Task Generation (Single Source of Truth Integration) - -### Planning-to-Execution Automation -**NEW FEATURE**: Eliminates the gap between planning and execution by automatically creating executable task files from planning documents. - -### Task Extraction Process -1. **Parse IMPL_PLAN.md**: Scan for task identifiers in standardized format: - - `IMPL-001`, `IMPL-002`, etc. (main tasks) - - `IMPL-1.1`, `IMPL-1.2`, etc. (subtasks) - - Task titles and descriptions from plan sections - -2. **Generate Task JSON Files**: For each identified task, create structured JSON: -```json -{ - "id": "IMPL-001", - "title": "Foundation/Infrastructure setup", - "status": "pending", - "type": "infrastructure", - "agent": "code-developer", - "effort": "2h", - - "context": { - "inherited_from": "WFS-[topic-slug]", - "source_plan_ref": "IMPL_PLAN.md#phase-1-foundation", - "requirements": ["Extracted from plan description"], - "scope": ["Derived from plan context"], - "acceptance": ["Extracted from success criteria"] - }, - - "dependencies": { - "upstream": [], - "downstream": ["IMPL-002"], - "phase_group": "Phase 1: Foundation" - }, - - "metadata": { - "created_at": "2025-09-07T15:00:00Z", - "created_by": "workflow:action-plan", - "auto_generated": true, - "plan_version": "1.0" - } -} -``` - -3. **Link Bidirectionally**: - - Task files reference plan sections - - Session state includes all generated task IDs - - Ready for immediate execution via `/task:execute` - -### Benefits of Automation -- **Zero Manual Task Creation**: Plans immediately become executable -- **Consistency**: All tasks derive from same authoritative plan -- **Traceability**: Clear linkage from requirements through plan to tasks -- **Immediate Execution**: Can run `/task:execute IMPL-001` immediately after planning - -## Session State Analysis & Document Understanding - -### Workflow Session Discovery -**Command**: `workflow:action-plan` automatically detects and analyzes: - -**Session Detection Process**: -1. **Find Active Sessions**: Locate `.workflow/WFS-*/workflow-session.json` files -2. **Session Validation**: Verify session completeness and current phase -3. **Context Extraction**: Read session metadata, progress, and phase outputs - -**Session State Analysis**: -```json -{ - "session_id": "WFS-user-auth-system", - "current_phase": "PLAN", - "brainstorming": { - "status": "completed", - "agents_completed": ["system-architect", "ui-designer", "security-expert"], - "synthesis_available": true, - "recommendations_count": 12 - }, - "documents": { - "brainstorming": { - "system-architect/analysis.md": {"status": "available", "insights": ["scalability", "microservices"]}, - "synthesis-analysis.md": {"status": "available", "key_themes": ["security-first", "user-experience"]} - } - } -} -``` - -### Document Intelligence & Content Understanding -**Process**: Action planning reads and interprets existing workflow documents - -**Brainstorming Document Analysis**: -- **Agent Analyses**: Extract key insights, recommendations, and constraints from each agent -- **Synthesis Reports**: Understand cross-perspective themes and convergent solutions -- **Recommendation Prioritization**: Identify high-impact, actionable items -- **Context Preservation**: Maintain user requirements and constraints from discussions - -**Content Integration Strategy**: -- **Technical Requirements**: From system-architect, data-architect, security-expert analyses -- **User Experience**: From ui-designer, user-researcher perspectives -- **Business Context**: From product-manager, business-analyst insights -- **Implementation Constraints**: From all agent recommendations and user discussions - -**Gap Detection**: -- Identify missing technical specifications -- Detect undefined user requirements -- Find unresolved architectural decisions -- Highlight conflicting recommendations requiring resolution - -## Output Format - -### IMPL_PLAN.md Structure (Enhanced for Action Planning) -```markdown -# Action Implementation Plan - -## Context & Requirements -### From Brainstorming Analysis (if --from-brainstorming) -- **Key Insights**: Synthesized from multi-agent perspectives -- **Technical Requirements**: Architecture, security, data considerations -- **User Experience Requirements**: UI/UX design and usability needs -- **Business Requirements**: Product goals, stakeholder priorities, constraints -- **User Discussion Context**: Captured requirements from user interactions - -### From User Input (if --skip-brainstorming) -- **User Provided Requirements**: Direct input and specifications -- **Context Analysis**: Interpreted requirements and technical implications -- **Gap Identification**: Areas needing clarification or additional information - -## Strategic Approach -- **Implementation Philosophy**: Core principles guiding development -- **Success Metrics**: How progress and completion will be measured -- **Risk Mitigation**: Key risks identified and mitigation strategies - -## Task Breakdown -- **IMPL-001**: Foundation/Infrastructure setup -- **IMPL-002**: Core functionality implementation -- **IMPL-003**: Integration and testing -- **IMPL-004**: [Additional tasks based on complexity] - -## Dependencies & Sequence -- **Critical Path**: Essential task sequence -- **Parallel Opportunities**: Tasks that can run concurrently -- **External Dependencies**: Third-party integrations or resources needed - -## Resource Allocation -- **Technical Resources**: Required skills and expertise -- **Timeline Estimates**: Duration estimates for each phase -- **Quality Gates**: Review and approval checkpoints - -## Success Criteria -- **Functional Acceptance**: Core functionality validation -- **Technical Acceptance**: Performance, security, scalability criteria -- **User Acceptance**: Usability and experience validation -``` - -### Enhanced IMPL_PLAN.md Structure (Complex Workflows) -```markdown -# Implementation Plan - [Project Name] - -## Context & Requirements -### From Brainstorming Analysis (if --from-brainstorming) -- **Key Insights**: Synthesized from multi-agent perspectives -- **Technical Requirements**: Architecture, security, data considerations -- **User Experience Requirements**: UI/UX design and usability needs -- **Business Requirements**: Product goals, stakeholder priorities, constraints -- **User Discussion Context**: Captured requirements from user interactions - -### From User Input (if --skip-brainstorming) -- **User Provided Requirements**: Direct input and specifications -- **Context Analysis**: Interpreted requirements and technical implications -- **Gap Identification**: Areas needing clarification or additional information - -## Strategic Approach -- **Implementation Philosophy**: Core principles guiding development -- **Success Metrics**: How progress and completion will be measured -- **Risk Mitigation**: Key risks identified and mitigation strategies - -## Phase Breakdown - -### Phase 1: Foundation -- **Objective**: [Core infrastructure/base components] -- **Tasks**: IMPL-001, IMPL-002 -- **Duration**: [Estimate] -- **Success Criteria**: [Measurable outcomes] - -### Phase 2: Core Implementation -- **Objective**: [Main functionality] -- **Tasks**: IMPL-003, IMPL-004, IMPL-005 -- **Duration**: [Estimate] -- **Dependencies**: Phase 1 completion - -### Phase 3: Integration & Testing -- **Objective**: [System integration and validation] -- **Tasks**: IMPL-006, IMPL-007 -- **Duration**: [Estimate] - -## Risk Assessment -- **High Risk**: [Description] - Mitigation: [Strategy] -- **Medium Risk**: [Description] - Mitigation: [Strategy] - -## Quality Gates -- Code review requirements -- Testing coverage targets -- Performance benchmarks -- Security validation checks - -## Rollback Strategy -- Rollback triggers and procedures -- Data preservation approach -``` - -## Document Storage -Generated documents are stored in session directory: -``` -.workflow/WFS-[topic-slug]/ -โ”œโ”€โ”€ IMPL_PLAN.md # Combined planning document (all complexities) -โ””โ”€โ”€ workflow-session.json # Updated with document references -``` - -## Session Updates (Enhanced with Task Generation) -```json -{ - "phases": { - "PLAN": { - "status": "completed", - "output": { - "primary": "IMPL_PLAN.md", - "tasks_generated": [".task/impl-001.json", ".task/impl-002.json", ".task/impl-003.json"] - }, - "documents_generated": ["IMPL_PLAN.md"], - "tasks_auto_created": 3, - "completed_at": "2025-09-05T11:00:00Z", - "tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"], - "ready_for_implementation": true - } - }, - "documents": { - "planning": { - "IMPL_PLAN.md": { - "status": "generated", - "path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md", - "tasks_extracted": 3, - "auto_generation": "completed" - } - } - }, - "task_system": { - "enabled": true, - "auto_generated": true, - "directory": ".workflow/WFS-[topic-slug]/.task/", - "task_count": { - "total": 3, - "pending": 3, - "from_planning": 3 - } - } -} -``` - -## Complexity Decision Rules - -### Document Generation Matrix -| Complexity | IMPL_PLAN.md | Structure | Agent Requirements | -|------------|--------------|-----------|-------------------| -| **Simple** | Optional/Skip | Minimal | Direct to IMPLEMENT | -| **Medium** | Required | Standard | planning-agent | -| **Complex** | Required | Enhanced with phases + risk assessment | planning-agent + detailed analysis | - -### Auto-Detection Triggers -Complex planning triggered when: -- Architecture changes required -- Security implementation needed -- Performance optimization planned -- System integration involved -- Estimated effort > 8 hours -- Risk level assessed as high - -### Manual Override +### Direct Text Input (Default) ```bash -# Force complex planning even for medium tasks -/workflow:action-plan --force-complex - -# Force simple planning for quick fixes -/workflow:action-plan --force-simple +/workflow:action-plan "Build user authentication system with JWT and OAuth2" ``` +**Processing**: +- Parse natural language requirements +- Extract technical components and constraints +- Identify implementation scope and objectives +- Generate structured plan from description -## Skip Option +### File-based Input ```bash -/workflow:action-plan --skip-to-implement +/workflow:action-plan --from-file requirements.md +/workflow:action-plan --from-file PROJECT_SPEC.txt ``` -- Generates minimal plan -- Immediately transitions to IMPLEMENT -- Useful for urgent fixes +**Supported formats**: .md, .txt, .json, .yaml +**Processing**: +- Read and parse file contents +- Extract structured requirements and specifications +- Identify task descriptions and dependencies +- Preserve original structure and priorities -## Replanning Mode - -### Usage +### Issue-based Input ```bash -# Basic replanning -/workflow:action-plan --replan --trigger=requirement-change - -# Strategic replanning with impact analysis -/workflow:action-plan --replan --trigger=new-issue --scope=all --strategy=minimal-disruption --impact-analysis - -# Conflict resolution -/workflow:action-plan --replan --trigger=dependency-conflict --auto-resolve +/workflow:action-plan --from-issue ISS-001 +/workflow:action-plan --from-issue "feature-request" ``` +**Supported sources**: Issue IDs, issue titles, GitHub URLs +**Processing**: +- Load issue description and acceptance criteria +- Parse technical requirements and constraints +- Extract related issues and dependencies +- Include issue context in planning -### Replan Parameters -- `--trigger=` โ†’ Replanning trigger: `new-issue|requirement-change|dependency-conflict|optimization` -- `--scope=` โ†’ Scope: `current-phase|all|documents-only|tasks-only` -- `--strategy=` โ†’ Strategy: `minimal-disruption|optimal-efficiency|risk-minimization|time-optimization` -- `--impact-analysis` โ†’ Detailed impact analysis -- `--auto-resolve` โ†’ Auto-resolve conflicts -- `--dry-run` โ†’ Simulation mode - -### Replanning Strategies - -#### Minimal Disruption -- Preserve completed tasks -- Minimize impact on active work -- Insert changes optimally - -#### Optimal Efficiency -- Re-optimize task order -- Maximize parallelization -- Optimize critical path - -#### Risk Minimization -- Prioritize high-risk tasks -- Add buffer time -- Strengthen dependencies - -#### Time Optimization -- Focus on core requirements -- Defer non-critical tasks -- Maximize parallel execution - -### Integration with Issues -When issues are created, replanning can be automatically triggered: +### Template-based Input ```bash -# Create issue then replan -/workflow:issue create --type=feature "OAuth2 support" -/workflow:action-plan --replan --trigger=new-issue --issue=ISS-001 +/workflow:action-plan --template web-api +/workflow:action-plan --template mobile-app "user management" +``` +**Available templates**: +- `web-api`: REST API development template +- `mobile-app`: Mobile application template +- `database-migration`: Database change template +- `security-feature`: Security implementation template +**Processing**: +- Load template structure and best practices +- Prompt for template-specific parameters +- Customize template with user requirements +- Generate plan following template patterns + +### Interactive Mode +```bash +/workflow:action-plan --interactive +``` +**Guided Process**: +1. **Project Type**: Select development category +2. **Requirements**: Structured requirement gathering +3. **Constraints**: Technical and resource limitations +4. **Success Criteria**: Define completion conditions +5. **Plan Generation**: Create comprehensive plan + +### Brainstorming Integration +```bash +/workflow:action-plan --from-brainstorming +``` +**Prerequisites**: Completed brainstorming session +**Processing**: +- Read multi-agent brainstorming analyses +- Synthesize recommendations and insights +- Integrate diverse perspectives into unified plan +- Preserve brainstorming context and decisions + +### Web-based Input +```bash +/workflow:action-plan --from-url "https://github.com/project/issues/45" +/workflow:action-plan --from-url "https://docs.example.com/spec" +``` +**Processing**: +- Fetch content from web URLs +- Parse structured requirements from web pages +- Extract technical specifications +- Handle GitHub issues, documentation sites, specs + +## Complexity Levels + +### Simple (Default) +```bash +/workflow:action-plan "Build chat system" +``` +**Output**: IMPL_PLAN.md document only +**Use case**: Documentation-focused planning, quick overviews +**Content**: Structured plan with task descriptions + +### Decompose +```bash +/workflow:action-plan "Build chat system" --complexity=decompose +``` +**Output**: IMPL_PLAN.md + task JSON files +**Use case**: Full workflow execution with automated task system +**Content**: Plan document + extracted task files in .task/ directory + +## Input Processing Pipeline + +### 1. Input Detection +```pseudo +function detect_input_type(args): + if starts_with("--from-file"): + return "file" + elif starts_with("--from-issue"): + return "issue" + elif starts_with("--template"): + return "template" + elif args == "--interactive": + return "interactive" + elif args == "--from-brainstorming": + return "brainstorming" + elif starts_with("--from-url"): + return "url" + else: + return "direct_text" ``` -## Integration with Workflow System +### 2. Content Extraction +**Per Input Type**: +- **Direct Text**: Parse natural language requirements +- **File**: Read file contents and structure +- **Issue**: Load issue data and related context +- **Template**: Load template and gather parameters +- **Interactive**: Conduct guided requirement session +- **Brainstorming**: Read brainstorming outputs +- **URL**: Fetch web content and parse -### Action Planning Integration Points -**Prerequisite Commands**: -- `/workflow:session start` โ†’ Initialize workflow session -- `/brainstorm` โ†’ (Optional) Multi-agent brainstorming phase +### 3. Requirement Analysis +- Structure extracted information +- Identify tasks and dependencies +- Determine technical requirements +- Extract success criteria +- Assess complexity and scope -**Action Planning Execution**: -- `/workflow:action-plan --from-brainstorming` โ†’ Plan from completed brainstorming -- `/workflow:action-plan --skip-brainstorming "task description"` โ†’ Plan from user input -- `/workflow:action-plan --replan` โ†’ Revise existing plans +### 4. Plan Generation +- Create IMPL_PLAN.md with structured content +- Include requirements, tasks, and success criteria +- Maintain traceability to input sources +- Format for readability and execution -**Follow-up Commands**: -- `/workflow:implement` โ†’ Execute the action plan -- `/workflow:status` โ†’ View current workflow state -- `/task:create` โ†’ Create specific implementation tasks -- `/workflow:review` โ†’ Validate completed implementation +### 5. Optional Decomposition +**If --complexity=decompose**: +- Parse IMPL_PLAN.md for task identifiers +- Create .task/impl-*.json files +- Establish task relationships +- Update session with task references + +## Session Management + +### Session Check Process +โš ๏ธ **CRITICAL**: Check for existing active session before planning + +1. **Query Session Registry**: Check `.workflow/session_status.jsonl` +2. **Session Selection**: Use existing active session or create new +3. **Context Integration**: Load session state and existing context ### Session State Updates -After action planning completion: ```json { - "current_phase": "IMPLEMENT", + "current_phase": "PLAN", + "input_source": "direct_text|file|issue|template|interactive|brainstorming|url", + "input_details": { + "type": "detected_input_type", + "source": "input_identifier_or_path", + "processed_at": "2025-09-08T15:00:00Z" + }, "phases": { - "BRAINSTORM": {"status": "completed|skipped"}, "PLAN": { "status": "completed", - "input_source": "brainstorming|user_input", + "complexity": "simple|decompose", "documents_generated": ["IMPL_PLAN.md"], - "tasks_identified": ["IMPL-001", "IMPL-002", "IMPL-003"], - "complexity_assessed": "simple|medium|complex" + "tasks_created": 0, + "input_processed": true } } } ``` -### Quality Assurance -**Action Planning Excellence**: -- **Context Integration** โ†’ All brainstorming insights or user requirements incorporated -- **Actionable Output** โ†’ Plans translate directly to executable tasks -- **Comprehensive Coverage** โ†’ Technical, UX, and business considerations included -- **Clear Sequencing** โ†’ Dependencies and critical path clearly defined -- **Measurable Success** โ†’ Concrete acceptance criteria established +## IMPL_PLAN.md Template -This action planning command bridges brainstorming insights and implementation execution, ensuring comprehensive planning based on multi-perspective analysis or direct user input. \ No newline at end of file +### 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 \ No newline at end of file diff --git a/.claude/commands/workflow/implement.md b/.claude/commands/workflow/implement.md deleted file mode 100644 index c7e017e8..00000000 --- a/.claude/commands/workflow/implement.md +++ /dev/null @@ -1,345 +0,0 @@ ---- -name: workflow-implement -description: Implementation phase with simple, medium, and complex execution modes -usage: /workflow:implement [--type=] [--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 \ No newline at end of file diff --git a/.claude/commands/workflow/vibe.md b/.claude/commands/workflow/vibe.md new file mode 100644 index 00000000..879b717c --- /dev/null +++ b/.claude/commands/workflow/vibe.md @@ -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 \ No newline at end of file diff --git a/.claude/output-styles/agent-workflow-coordination.md b/.claude/output-styles/agent-workflow-coordination.md index 2d5f97be..3083901a 100644 --- a/.claude/output-styles/agent-workflow-coordination.md +++ b/.claude/output-styles/agent-workflow-coordination.md @@ -1,13 +1,7 @@ --- -name: Agent Workflow Coordination +name: Workflow Coordination description: Core coordination principles for multi-agent development workflows --- - -## System Reference -**Complete Architecture**: @~/.claude/workflows/core-principles.md - -This document defines essential coordination principles between agents. For complete system architecture, file structures, commands, and implementation details, refer to the unified workflow system principles. - ## Core Agent Coordination Principles ### Planning First Principle @@ -36,101 +30,27 @@ This document defines essential coordination principles between agents. For comp 6. **Checkpoint Safety**: State is saved automatically after each agent completes its work. 7. **Interrupt/Resume**: The system must support full state preservation and restoration. -### Implementation Prerequisites Principle +## Context Management -**Deliverable Validation**: Code modification agents can only execute when proper planning deliverables exist. +### Gemini Context Protocol +**Context Integration**: Agents use Gemini CLI for context gathering when needed, with memory-gemini-bridge agent handling complex analysis. -**Required Artifacts Before Implementation** (at least one must exist): -- `IMPL_PLAN.md`: Must contain detailed implementation strategy -- `.chat/` sessions: Context analysis supporting planning decisions -- Task definitions: JSON task files with clear acceptance criteria -- Complexity assessment: Validated task complexity and scope +**CLI Guidelines Reference**: Follow @~/.cluade/workflows/gemini-cli-guidelines.md for consistency and `memory-gemini-bridge` agent for comprehensive analysis. -**Validation Protocol**: -```pseudo -FUNCTION validate_implementation_prerequisites(): - artifacts_found = 0 - - 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 -``` +### ๐ŸŽฏ Gemini CLI Requirements by Task Complexity -### 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` - -### Interrupt & Resume Protocol - -**Checkpoint Strategy Flow:** -`Agent Completes` **->** `Save State (Todo + Context)` **->** `Check for Interrupt Signal` **->** `Continue or Stop` - -**State Components for Resume**: -- TodoWrite current state -- Agent output chain -- Accumulated context -- Planning documents -- `.chat/` analysis history - -### Agent Selection Logic - -```pseudo -FUNCTION select_agent_for_task(task_complexity): - CASE task_complexity: - WHEN 'Research/Analysis': - RETURN "General-Purpose" // For research, file analysis - WHEN 'Simple Implementation': - RETURN "Code Developer" // For implementation, TDD, algorithms - WHEN 'Complex Features (3+ components)': - RETURN ["Action Planning", "Code Developer", "Code Review"] // Multi-stage agent chain - WHEN 'Full Lifecycle': - RETURN "Boomerang" // For full workflow orchestration - WHEN 'Post-Implementation': - RETURN "Code Review" // For quality validation, security, compliance -END FUNCTION -``` - -### Agent Output Standards - -**Action Planning Agent**: -``` -PLAN_SUMMARY: [One-line summary] -STEPS: [Numbered deliverables] -SUCCESS_CRITERIA: [Measurable standards] -TODOWRITE_ENTRIES: [TodoWrite items created for each stage/subtask] -``` - -**Code Developer Agent**: -``` -PREREQUISITE_VALIDATION: [IMPL_PLAN.md and .chat/ sessions verified] -IMPLEMENTATION_SUMMARY: [What was built] -FILES_MODIFIED: [File list with changes] -CONTEXT_REFERENCES: [Links to supporting .chat/ analysis] -TODOWRITE_UPDATES: [Progress status updates made during implementation] -READY_FOR_REVIEW: [YES/NO with reason] -``` - -**Code Review Agent**: -``` -REVIEW_STATUS: [PASS/ISSUES_FOUND/CRITICAL_ISSUES] -QUALITY_SCORE: [1-10] -TODOWRITE_COMPLETION: [Tasks marked as completed after validation] -RECOMMENDATION: [APPROVE/FIX_REQUIRED/REVISION_NEEDED] -``` +#### ๐ŸŽฏ Medium Tasks (CLI Recommended) +**Task Examples**: Multi-file features, component modifications, API endpoint additions +**CLI Decision**: Recommended for consistency and quality +**Context Scope**: Guidelines + architecture + feature patterns +**Standard Context Collection**: +```bash +gemini --all-files -p "@{**/*CLAUDE.md} Guidelines for: [task]" +gemini --all-files -p "@[modules] Architecture for: [task]" +gemini --all-files -p "@[files] Patterns for: [task]" +``` \ No newline at end of file diff --git a/.claude/workflows/agent-orchestration-patterns.md b/.claude/workflows/agent-orchestration-patterns.md index c500f1fa..cc13603b 100644 --- a/.claude/workflows/agent-orchestration-patterns.md +++ b/.claude/workflows/agent-orchestration-patterns.md @@ -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]" ``` \ No newline at end of file diff --git a/.claude/workflows/file-structure-standards.md b/.claude/workflows/file-structure-standards.md index 15183914..73eab7fc 100644 --- a/.claude/workflows/file-structure-standards.md +++ b/.claude/workflows/file-structure-standards.md @@ -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 diff --git a/.claude/workflows/json-document-coordination-system.md b/.claude/workflows/json-document-coordination-system.md index b29c77e8..6650e36a 100644 --- a/.claude/workflows/json-document-coordination-system.md +++ b/.claude/workflows/json-document-coordination-system.md @@ -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. \ No newline at end of file +### 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. \ No newline at end of file diff --git a/.claude/workflows/session-management-principles.md b/.claude/workflows/session-management-principles.md index 29a0695d..fb735d26 100644 --- a/.claude/workflows/session-management-principles.md +++ b/.claude/workflows/session-management-principles.md @@ -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 \ No newline at end of file +- Fast session resume (< 1 second) +- Minimal file I/O operations +- Clear session state understanding +- No complex synchronization needed \ No newline at end of file diff --git a/.claude/workflows/task-decomposition-integration.md b/.claude/workflows/task-decomposition-integration.md index 7c94eec5..e2d74846 100644 --- a/.claude/workflows/task-decomposition-integration.md +++ b/.claude/workflows/task-decomposition-integration.md @@ -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 \ No newline at end of file +**System ensures**: Consistent hierarchical decomposition within depth limits using JSON-only data model \ No newline at end of file diff --git a/.claude/workflows/task-management-principles.md b/.claude/workflows/task-management-principles.md index a3bc6a48..da564f2b 100644 --- a/.claude/workflows/task-management-principles.md +++ b/.claude/workflows/task-management-principles.md @@ -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 \ No newline at end of file +**System ensures**: Consistent task management using simplified JSON-only data model with complete context preservation for agent execution \ No newline at end of file diff --git a/.claude/workflows/todowrite-coordination-rules.md b/.claude/workflows/todowrite-coordination-rules.md index 54e6d044..789221fc 100644 --- a/.claude/workflows/todowrite-coordination-rules.md +++ b/.claude/workflows/todowrite-coordination-rules.md @@ -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 \ No newline at end of file