Remove granular progress tracking across workflow system

- Remove detailed progress views (Total Tasks: X, Completed: Y %) from all templates - Simplify TODO_LIST.md structure by removing Progress Overview sections - Remove stats tracking from session-management-principles.json schema - Eliminate progress format and calculation logic from context command - Remove percentage-based progress displays from action-planning-agent - Simplify vibe command coordination by removing detailed task counts - Focus on essential JSON state changes rather than UI progress metrics 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-12 02:37:45 +08:00 · 2025-09-08 15:26:01 +08:00
parent da717546f8
commit 9502741d50
17 changed files with 2064 additions and 3449 deletions
--- 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
+**System ensures**: Consistent task management using simplified JSON-only data model with complete context preservation for agent execution