mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
Add session status file creation rule across workflow commands
Updates all workflow commands to create .workflow/session_status.jsonl if it doesn't exist when checking for active sessions. This ensures consistent behavior across: - gemini-chat.md: Added creation rule and updated workflow pseudocode - gemini-execute.md: Added session file creation requirement - gemini-mode.md: Updated session check process - workflow/action-plan.md: Updated both session check locations - task/replan.md: Added creation rule to session validation - task/breakdown.md: Updated session check process - workflow/brainstorm.md: Added creation rule to session registry query Also includes cleanup of deprecated command files (context.md, sync.md) and documentation updates for task creation complexity escalation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -23,7 +23,7 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic
|
||||
⚠️ **CRITICAL**: Before breakdown, 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
|
||||
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 parent task
|
||||
3. **Context Integration**: Load existing session state and task hierarchy
|
||||
|
||||
|
||||
@@ -1,349 +0,0 @@
|
||||
---
|
||||
name: task-context
|
||||
description: Unified task context analysis, status management, and intelligent execution support
|
||||
usage: /task:context [task-id|--filter=<filter>] [--analyze] [--update] [--sync] [--format=<tree|list|json>] [--detailed]
|
||||
argument-hint: [task-id or filter] [optional: actions and format options]
|
||||
examples:
|
||||
- /task:context
|
||||
- /task:context IMPL-001 --analyze --detailed
|
||||
- /task:context --filter="status:active" --format=tree
|
||||
- /task:context IMPL-001 --update
|
||||
- /task:context --sync
|
||||
---
|
||||
|
||||
### 🚀 Command Overview: /task:context
|
||||
|
||||
- **Purpose**: Provides unified task context analysis, status visualization, progress tracking, and intelligent execution support.
|
||||
- **Core Function**: Acts as a central hub for understanding and managing the state of tasks within a workflow.
|
||||
|
||||
### 📜 Core Principles
|
||||
|
||||
- **Task Management**: @~/.claude/workflows/task-management-principles.md
|
||||
- **File Structure**: @~/.claude/workflows/file-structure-standards.md
|
||||
- **Session Management**: @~/.claude/workflows/session-management-principles.md
|
||||
|
||||
### ✨ Core Capabilities
|
||||
|
||||
- **Context Awareness**
|
||||
- Analyzes current state and progress from JSON task files.
|
||||
- Tracks hierarchical task dependencies.
|
||||
- Detects changes in JSON files and status.
|
||||
- Assesses the impact of changes across tasks and files.
|
||||
- Suggests next actions based on current context.
|
||||
- Monitors compliance with file structure standards.
|
||||
- **Status Management**
|
||||
- Visualizes task status in `tree`, `list`, and `json` formats.
|
||||
- Tracks hierarchical progress from task files.
|
||||
- Performs batch operations on tasks using filters.
|
||||
- Monitors file integrity and task health.
|
||||
- Exports analysis and status data to various file formats.
|
||||
- Generates status reports and analysis documents.
|
||||
|
||||
### 🧠 Primary Operations Logic
|
||||
|
||||
The command's behavior is determined by the provided arguments.
|
||||
|
||||
```pseudo
|
||||
FUNCTION main(arguments):
|
||||
// Options like --filter and --format modify the behavior of display functions.
|
||||
|
||||
IF --sync is present:
|
||||
// Corresponds to: /task:context --sync
|
||||
run_context_synchronization()
|
||||
ELSE IF --update is present AND task_id is given:
|
||||
// Corresponds to: /task:context <task-id> --update
|
||||
run_interactive_update_for(task_id)
|
||||
ELSE IF --analyze is present AND task_id is given:
|
||||
// Corresponds to: /task:context <task-id> --analyze
|
||||
run_detailed_analysis_for(task_id)
|
||||
ELSE IF --health, --progress, --timeline, etc. are present:
|
||||
// Corresponds to specific reporting sub-commands
|
||||
generate_specific_report(report_type)
|
||||
ELSE IF task_id is provided without other primary action flags:
|
||||
// Corresponds to: /task:context <task-id>
|
||||
display_task_context_and_quick_actions(task_id)
|
||||
ELSE:
|
||||
// Default action with no arguments or only filters/formatters
|
||||
// Corresponds to: /task:context
|
||||
display_global_context_view(filters, format)
|
||||
END FUNCTION
|
||||
```
|
||||
|
||||
### 🎯 Main Usage Modes & Examples
|
||||
|
||||
#### 1. Global Context View
|
||||
- **Command**: `/task:context`
|
||||
- **Description**: Provides a high-level overview of the entire workflow's task status.
|
||||
- **Example Output**:
|
||||
```
|
||||
📊 Task Context Overview
|
||||
━━━━━━━━━━━━━━━━━━━━━━
|
||||
Workflow: WFS-[topic-slug]
|
||||
Phase: IMPLEMENT
|
||||
Progress: 45% (5/11 tasks)
|
||||
|
||||
Summary:
|
||||
✅ Completed: 5
|
||||
🔄 Active: 2
|
||||
⏳ Pending: 3
|
||||
🚫 Blocked: 1
|
||||
|
||||
Active Context:
|
||||
- Current focus: IMPL-002 (In Progress)
|
||||
- Dependencies clear: Yes
|
||||
- Blockers: IMPL-004 blocked by IMPL-003
|
||||
|
||||
Critical Path:
|
||||
IMPL-001 → IMPL-003 → IMPL-006
|
||||
|
||||
Next Actions:
|
||||
1. Complete IMPL-002 (90% done)
|
||||
2. Unblock IMPL-004
|
||||
3. Start IMPL-005 (ready)
|
||||
```
|
||||
|
||||
#### 2. Task-Specific Analysis
|
||||
- **Command**: `/task:context IMPL-001 --analyze`
|
||||
- **Description**: Shows a detailed breakdown of a single task's context, dependencies, and related changes.
|
||||
- **Example Output**:
|
||||
```
|
||||
📋 Task Context: IMPL-001
|
||||
━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Status: In Progress
|
||||
Started: 2h ago
|
||||
Progress: 60% (2/3 subtasks complete)
|
||||
|
||||
Dependencies:
|
||||
✅ No upstream dependencies
|
||||
⬇️ Blocks: IMPL-003, IMPL-004
|
||||
|
||||
Context Data:
|
||||
- Requirements: [inherited from workflow]
|
||||
- Scope: src/auth/*, tests/auth/*
|
||||
- Agent: code-developer
|
||||
- Priority: high
|
||||
|
||||
Related Changes:
|
||||
- src/auth/login.ts modified 30m ago
|
||||
- New issue: "Login timeout too short"
|
||||
- Workflow update: Security requirement added
|
||||
|
||||
Impact if delayed:
|
||||
⚠️ Will block 2 downstream tasks
|
||||
⚠️ Critical path - affects timeline
|
||||
```
|
||||
|
||||
#### 3. Interactive Context Update
|
||||
- **Command**: `/task:context IMPL-001 --update`
|
||||
- **Description**: Initiates an interactive prompt to modify a task's context data.
|
||||
- **Example Interaction**:
|
||||
```
|
||||
Current context for IMPL-001:
|
||||
1. Requirements: [JWT, OAuth2]
|
||||
2. Scope: [src/auth/*]
|
||||
3. Priority: normal
|
||||
|
||||
What to update?
|
||||
1. Add requirement
|
||||
2. Modify scope
|
||||
3. Change priority
|
||||
4. Add note
|
||||
> 1
|
||||
|
||||
Enter new requirement: Add 2FA support
|
||||
✅ Context updated
|
||||
```
|
||||
|
||||
#### 4. Context Synchronization
|
||||
- **Command**: `/task:context --sync`
|
||||
- **Description**: Reconciles context across the entire task hierarchy, propagating changes and resolving conflicts.
|
||||
- **Example Output**:
|
||||
```
|
||||
🔄 Synchronizing task contexts...
|
||||
- Workflow → Tasks: Updated 3 tasks
|
||||
- Parent → Children: Propagated 2 changes
|
||||
- Dependencies: Resolved 1 conflict
|
||||
✅ All contexts synchronized
|
||||
```
|
||||
|
||||
### 🖥️ Display Formats (`--format`)
|
||||
|
||||
#### Tree Format (`--format=tree`)
|
||||
```
|
||||
📁 IMPLEMENT Tasks
|
||||
├── ✅ IMPL-001: Authentication [Complete]
|
||||
│ ├── ✅ IMPL-001.1: Design schema
|
||||
│ ├── ✅ IMPL-001.2: Core implementation
|
||||
│ └── ✅ IMPL-001.3: Tests
|
||||
├── 🔄 IMPL-002: Database layer [60%]
|
||||
│ ├── ✅ IMPL-002.1: Models
|
||||
│ ├── 🔄 IMPL-002.2: Migrations
|
||||
│ └── ⏳ IMPL-002.3: Seeds
|
||||
├── ⏳ IMPL-003: API endpoints [Pending]
|
||||
└── 🚫 IMPL-004: Integration [Blocked by IMPL-003]
|
||||
```
|
||||
|
||||
#### List Format (`--format=list`)
|
||||
```
|
||||
ID | Title | Status | Progress | Agent | Priority
|
||||
---------|--------------------------|-----------|----------|-----------------|----------
|
||||
IMPL-001 | Authentication | completed | 100% | code-developer | normal
|
||||
IMPL-002 | Database layer | active | 60% | code-developer | high
|
||||
IMPL-003 | API endpoints | pending | 0% | planning-agent | normal
|
||||
IMPL-004 | Integration | blocked | 0% | - | low
|
||||
```
|
||||
|
||||
#### JSON Format (`--format=json`)
|
||||
- **Description**: Outputs machine-readable JSON, suitable for scripting and tool integration.
|
||||
|
||||
### 🔍 Filtering (`--filter`)
|
||||
|
||||
- **By Status**:
|
||||
- `status:active`
|
||||
- `status:pending`
|
||||
- `status:blocked`
|
||||
- `status:completed`
|
||||
- **By Other Attributes**:
|
||||
- `type:feature`
|
||||
- `priority:high`
|
||||
- **Combining Filters**:
|
||||
- `status:active,priority:high`
|
||||
|
||||
### 🧠 Context Intelligence Features
|
||||
|
||||
- **Change Detection**: Automatically detects file modifications, new issues, workflow updates, and dependency status changes.
|
||||
- **Impact Analysis**: Assesses the effect of delays or failures on downstream tasks and the overall timeline (`--impact`).
|
||||
- **Smart Recommendations**: Provides actionable suggestions like which task to focus on, what can be parallelized, or which tasks need breaking down (`--recommend`).
|
||||
|
||||
### 📄 Context Data Structure (JSON Schema)
|
||||
|
||||
This is the standard schema for a task's context data stored in JSON files.
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "IMPL-001",
|
||||
"title": "Build authentication module",
|
||||
"type": "feature",
|
||||
"status": "active",
|
||||
"priority": "high",
|
||||
"agent": "code-developer",
|
||||
|
||||
"context": {
|
||||
"inherited_from": "WFS-[topic-slug]",
|
||||
"requirements": ["JWT authentication", "OAuth2 support", "2FA support"],
|
||||
"scope": ["src/auth/*", "tests/auth/*"],
|
||||
"acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented", "2FA integration works"]
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
"upstream": [],
|
||||
"downstream": ["IMPL-003", "IMPL-004"]
|
||||
},
|
||||
|
||||
"execution": {
|
||||
"attempts": 1,
|
||||
"current_attempt": {
|
||||
"started_at": "2025-09-05T10:35:00Z",
|
||||
"checkpoints": ["setup", "implement", "test", "validate"],
|
||||
"completed_checkpoints": ["setup", "implement"]
|
||||
},
|
||||
"history": []
|
||||
},
|
||||
|
||||
"environment": {
|
||||
"files_modified": ["src/auth/login.ts", "src/auth/middleware.ts"],
|
||||
"issues": ["ISS-001"],
|
||||
"last_activity": "2025-09-05T12:15:00Z"
|
||||
},
|
||||
|
||||
"recommendations": {
|
||||
"next_action": "Complete test checkpoint",
|
||||
"risk": "low",
|
||||
"priority_adjustment": "none"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 📊 Analysis & Monitoring
|
||||
|
||||
- **Progress Report (`--progress`)**: Shows overall progress broken down by type, priority, and velocity.
|
||||
- **Health Checks (`--health`)**: Reports on task health, highlighting issues like blockers, delays, and repeated failures.
|
||||
- **Timeline View (`--timeline`)**: Displays a chronological view of recent and upcoming task activities.
|
||||
|
||||
### 🛠️ Advanced Features
|
||||
|
||||
- **Conflict Detection (`--conflicts`)**: Identifies potential conflicts, such as multiple tasks modifying the same file.
|
||||
- **Historical Context (`--history`)**: Shows the version history of a task's context data.
|
||||
- **Context Validation (`--validate`)**: Checks a task's context for completeness and validity against defined rules.
|
||||
|
||||
### 🚦 Status Management
|
||||
|
||||
- **Update Status**: Change a single task's status using `--set`. Example: `/task:context IMPL-002 --set=active`
|
||||
- **Bulk Update**: Update multiple tasks matching a filter. Example: `/task:context --filter="status:pending" --set=blocked --reason="Waiting for API"`
|
||||
|
||||
- **Valid Status Transitions**:
|
||||
`pending` -> `active` -> `completed`
|
||||
`pending` -> `blocked`
|
||||
`active` -> `blocked`
|
||||
`active` -> `failed` -> `pending`
|
||||
|
||||
### 💾 File Output Generation
|
||||
|
||||
- **Analysis Report (`--report --save`)**:
|
||||
- Generates a comprehensive markdown report.
|
||||
- **Output**: `.workflow/WFS-[topic-slug]/.summaries/analysis-[timestamp].md`
|
||||
- **Data Export (`--export=<format>`)**:
|
||||
- Exports task data to various formats (`markdown`, `json`, `csv`).
|
||||
- **Output**: `.summaries/[output-name]-[timestamp].[format]`
|
||||
- **Validation Report (`--validate --save`)**:
|
||||
- Saves the output of context validation to a file.
|
||||
- **Output**: `.summaries/validation-report-[timestamp].md`
|
||||
- **TODO_LIST.md Generation (`--generate-todo-list`)**:
|
||||
- Creates a `TODO_LIST.md` file from the current state of JSON task files.
|
||||
- **Output**: `.workflow/WFS-[topic-slug]/TODO_LIST.md`
|
||||
|
||||
### 🔗 Integration Points
|
||||
|
||||
- **Workflow**: Inherits context from the main workflow and updates `session.json`.
|
||||
- **Task Relationships**: Manages parent-child and sibling dependencies, including circular dependency detection.
|
||||
- **Agent Context**: Prepares and optimizes context data for execution by different agent types.
|
||||
- **TodoWrite Tool**: Coordinates bidirectionally with the TodoWrite tool and `TODO_LIST.md` for seamless status updates (`--sync-todos`).
|
||||
|
||||
### ⚠️ Error Handling Examples
|
||||
|
||||
- **No Active Workflow**:
|
||||
- `❌ No workflow context found`
|
||||
- `→ Initialize with: /workflow init`
|
||||
- **Task Not Found**:
|
||||
- `❌ Task IMPL-999 does not exist`
|
||||
- `→ View tasks with: /task:status`
|
||||
- **Context Conflict**:
|
||||
- `⚠️ Context conflict detected`
|
||||
- `→ Resolve with: /task:context --resolve`
|
||||
|
||||
### ⚡ Quick Actions
|
||||
|
||||
- **Description**: When viewing a single task, an interactive menu of relevant actions is presented.
|
||||
- **Example Interaction**:
|
||||
```bash
|
||||
/task:context IMPL-002
|
||||
|
||||
Quick actions available:
|
||||
1. Execute task (/task:execute IMPL-002)
|
||||
2. Analyze context (/task:context IMPL-002 --analyze)
|
||||
3. Replan task (/task:replan IMPL-002)
|
||||
4. Break down (/task:breakdown IMPL-002)
|
||||
|
||||
Select action: 1
|
||||
→ Executing IMPL-002...
|
||||
```
|
||||
|
||||
### 🤝 Related Commands
|
||||
|
||||
- `/task:create`: Creates new tasks.
|
||||
- `/task:execute`: Executes a specific task.
|
||||
- `/task:replan`: Replans a task.
|
||||
- `/task:breakdown`: Breaks a task into subtasks.
|
||||
- `/task:sync`: Synchronizes all file systems.
|
||||
- `/workflow:context`: Provides overall workflow status.
|
||||
@@ -30,6 +30,7 @@ Creates new implementation tasks during IMPLEMENT phase with automatic context a
|
||||
- **Agent Assignment**: Suggests agent based on task type
|
||||
- **Hierarchy Support**: Creates parent-child relationships up to 3 levels
|
||||
- **Progressive Structure**: Auto-triggers enhanced structure at complexity thresholds
|
||||
- **Dynamic Complexity Escalation**: Automatically upgrades workflow complexity when thresholds are exceeded
|
||||
|
||||
### Context Awareness
|
||||
- Detects current workflow phase (must be IMPLEMENT)
|
||||
@@ -165,6 +166,127 @@ TODO_LIST.md auto-generation conditions:
|
||||
- workflow-session.json maintains task list with hierarchy depth
|
||||
- Automatic validation of cross-file references
|
||||
|
||||
## Dynamic Complexity Escalation (NEW FEATURE)
|
||||
|
||||
### Automatic Workflow Upgrade System
|
||||
After each task creation, the system automatically evaluates current workflow complexity and upgrades structure when thresholds are exceeded.
|
||||
|
||||
### Escalation Process
|
||||
```
|
||||
1. Create New Task → Generate JSON file
|
||||
2. Count All Tasks → Read all .task/*.json files
|
||||
3. Calculate Metrics → Tasks, modules, dependencies, effort
|
||||
4. Check Thresholds → Compare against complexity criteria
|
||||
5. Trigger Upgrade → If threshold exceeded, escalate complexity
|
||||
6. Generate Documents → Auto-create missing structure documents
|
||||
7. Update Session → Record complexity change in workflow-session.json
|
||||
8. Notify User → Inform about automatic upgrade
|
||||
```
|
||||
|
||||
### Escalation Triggers
|
||||
|
||||
#### 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
|
||||
|
||||
## Context Inheritance
|
||||
|
||||
Tasks automatically inherit:
|
||||
|
||||
@@ -23,7 +23,7 @@ Dynamically adjusts task planning based on changes, new requirements, blockers,
|
||||
⚠️ **CRITICAL**: Before replanning, 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
|
||||
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
|
||||
|
||||
|
||||
@@ -1,280 +0,0 @@
|
||||
---
|
||||
name: task-sync
|
||||
description: Synchronize task data with workflow session
|
||||
usage: /task:sync [--force] [--dry-run]
|
||||
argument-hint: [optional: force sync or dry run]
|
||||
examples:
|
||||
- /task:sync
|
||||
- /task:sync --force
|
||||
- /task:sync --dry-run
|
||||
---
|
||||
|
||||
# Task Sync Command (/task:sync)
|
||||
|
||||
## Overview
|
||||
Ensures bidirectional synchronization between hierarchical JSON tasks, TODO_LIST.md, and workflow-session.json.
|
||||
|
||||
## Core Principles
|
||||
**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md
|
||||
|
||||
|
||||
## Bidirectional Sync Operations
|
||||
|
||||
### 1. JSON Task Files → TODO_LIST.md Sync
|
||||
**Authoritative Source**: JSON task files in `.task/` directory
|
||||
- **Status Updates**: pending → active → completed reflected in checkboxes
|
||||
- **Hierarchical Progress**: Parent progress = average of children (up to 3 levels)
|
||||
- **Structure Sync**: TODO_LIST.md hierarchy matches JSON parent_id relationships
|
||||
- **Cross-References**: Links to JSON files and summary files validated
|
||||
- **Progress Rollup**: Automatic calculation from leaf tasks to root
|
||||
|
||||
### 2. JSON Task Files → Workflow Session Sync
|
||||
**Session State Updates**: workflow-session.json reflects current task state
|
||||
- **Task Lists**: Main task IDs updated per phase
|
||||
- **Progress Metrics**: Overall and phase-specific completion percentages
|
||||
- **Complexity Assessment**: Structure level based on current task count
|
||||
- **Blocked Task Detection**: Dependency analysis across entire hierarchy
|
||||
- **Session Metadata**: Last sync timestamps and validation status
|
||||
|
||||
### 3. Workflow Session → JSON Task Sync
|
||||
**Context Propagation**: Session context distributed to individual tasks
|
||||
- **Global Context**: Workflow requirements inherited by all tasks
|
||||
- **Requirement Updates**: Changes in session context propagated
|
||||
- **Issue Associations**: Workflow-level issues linked to relevant tasks
|
||||
- **Phase Transitions**: Task context updated when phases change
|
||||
|
||||
### 4. TodoWrite Tool → File System Sync
|
||||
**Real-time Coordination**: TodoWrite tool state synced with persistent files
|
||||
- **Active Task Sync**: TodoWrite status reflected in JSON files
|
||||
- **Completion Triggers**: TodoWrite completion updates JSON and TODO_LIST.md
|
||||
- **Progress Coordination**: TodoWrite progress synced with file-based tracking
|
||||
- **Session Continuity**: TodoWrite state preserved in TODO_LIST.md
|
||||
|
||||
## Sync Rules
|
||||
|
||||
### Automatic Sync Points
|
||||
- After `/task:create` - Add to workflow
|
||||
- After `/task:execute` - Update progress
|
||||
- After `/task:replan` - Sync changes
|
||||
- After `/workflow:*` commands - Propagate context
|
||||
|
||||
### Conflict Resolution
|
||||
Priority order:
|
||||
1. Recently modified (timestamp)
|
||||
2. More complete data
|
||||
3. User confirmation (if needed)
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Standard Sync with Report Generation
|
||||
```bash
|
||||
/task:sync
|
||||
|
||||
🔄 Comprehensive Task Synchronization
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Analyzing file system state...
|
||||
- JSON task files: 8 tasks across 3 levels in .task/
|
||||
- TODO_LIST.md: Present, 8 displayed tasks, last modified 2h ago
|
||||
- workflow-session.json: 3 main tasks tracked, Level 1 structure
|
||||
- Summary files: 3 completed task summaries in .summaries/
|
||||
|
||||
Validating cross-references...
|
||||
✅ Parent-child relationships: All valid
|
||||
✅ Hierarchy depth: Within limits (max 3 levels)
|
||||
✅ File naming: Follows impl-N.M.P format
|
||||
|
||||
Found synchronization differences:
|
||||
- Task impl-1.2: completed in JSON, pending in TODO_LIST.md checkbox
|
||||
- Progress: impl-1 shows 75% (from subtasks) vs 45% in session
|
||||
- Hierarchy: impl-2.3.1 exists in JSON but missing from TODO_LIST.md
|
||||
- Cross-refs: Summary link for impl-1.2 missing in TODO_LIST.md
|
||||
|
||||
Synchronizing files...
|
||||
✅ Updated impl-1.2 checkbox: [ ] → [x] in TODO_LIST.md
|
||||
✅ Recalculated hierarchical progress: impl-1 = 75%
|
||||
✅ Added impl-2.3.1 to TODO_LIST.md hierarchy display
|
||||
✅ Updated summary link: impl-1.2 → .summaries/IMPL-1.2-summary.md
|
||||
✅ Propagated context updates to 3 task files
|
||||
✅ Updated workflow-session.json progress metrics
|
||||
|
||||
Generating sync report...
|
||||
✅ Sync report saved: .summaries/sync-report-20250907-160000.md
|
||||
|
||||
Sync complete: 6 updates applied, 0 conflicts resolved
|
||||
Next sync recommended: In 1 hour or after next task operation
|
||||
```
|
||||
|
||||
### Dry Run with Detailed Analysis
|
||||
```bash
|
||||
/task:sync --dry-run
|
||||
|
||||
🔍 Sync Analysis (Dry Run Mode)
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Scanning .task/ directory: 8 JSON files found
|
||||
Analyzing TODO_LIST.md: Last modified 2h ago
|
||||
Checking workflow-session.json: In sync
|
||||
Validating .summaries/: 3 summary files present
|
||||
|
||||
Potential changes identified:
|
||||
ℹ️ Update 2 task statuses: impl-1.2, impl-1.3
|
||||
ℹ️ Recalculate progress for parent: impl-1 (67% → 75%)
|
||||
ℹ️ Add 1 missing cross-reference in TODO_LIST.md
|
||||
ℹ️ Update workflow session progress: 45% → 62%
|
||||
ℹ️ Generate missing summary link for impl-1.2
|
||||
|
||||
File changes would be made to:
|
||||
- TODO_LIST.md (3 line changes)
|
||||
- workflow-session.json (progress update)
|
||||
- No JSON task files need changes (already authoritative)
|
||||
|
||||
Conflicts detected: None
|
||||
Risk level: Low
|
||||
Estimated sync time: <5 seconds
|
||||
|
||||
(No actual changes made - run without --dry-run to apply)
|
||||
```
|
||||
|
||||
### Force Sync with Backup
|
||||
```bash
|
||||
/task:sync --force
|
||||
|
||||
⚠️ Force Sync Mode - Creating Backups
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Backing up current state...
|
||||
✅ TODO_LIST.md → .summaries/backup-TODO_LIST-20250907-160000.md
|
||||
✅ workflow-session.json → .summaries/backup-session-20250907-160000.json
|
||||
|
||||
Force sync operations:
|
||||
❗ Using JSON task files as authoritative source
|
||||
❗ Overwriting TODO_LIST.md without conflict resolution
|
||||
❗ Rebuilding workflow-session.json task data
|
||||
❗ Regenerating all cross-references
|
||||
❗ Recalculating all progress from scratch
|
||||
|
||||
Sync completed with authority conflicts resolved:
|
||||
✅ 3 conflicts overwritten in favor of JSON files
|
||||
✅ TODO_LIST.md completely regenerated
|
||||
✅ workflow-session.json task list rebuilt
|
||||
✅ All cross-references validated and updated
|
||||
|
||||
Backup files available for rollback if needed:
|
||||
- .summaries/backup-TODO_LIST-20250907-160000.md
|
||||
- .summaries/backup-session-20250907-160000.json
|
||||
|
||||
Force sync report: .summaries/force-sync-20250907-160000.md
|
||||
```
|
||||
|
||||
## Data Integrity Checks
|
||||
|
||||
### Validation Steps
|
||||
1. **File Existence**: Both JSON files exist
|
||||
2. **Session Match**: Same session_id
|
||||
3. **ID Consistency**: All task IDs valid
|
||||
4. **Status Logic**: No impossible states
|
||||
5. **Progress Math**: Calculation accurate
|
||||
|
||||
### Error Recovery
|
||||
```bash
|
||||
❌ Sync failed: tasks.json corrupted
|
||||
→ Attempting recovery from backup...
|
||||
✅ Restored from backup
|
||||
→ Retry sync? (y/n)
|
||||
```
|
||||
|
||||
## Progress Calculation
|
||||
```javascript
|
||||
progress = (completed_tasks / total_tasks) * 100
|
||||
|
||||
// With subtasks
|
||||
weighted_progress = sum(task.weight * task.progress) / total_weight
|
||||
```
|
||||
|
||||
## JSON Updates
|
||||
|
||||
### workflow-session.json
|
||||
```json
|
||||
{
|
||||
"phases": {
|
||||
"IMPLEMENT": {
|
||||
"tasks": ["IMPL-001", "IMPL-002", "IMPL-003"],
|
||||
"completed_tasks": ["IMPL-001", "IMPL-002"],
|
||||
"progress": 67,
|
||||
"last_sync": "2025-01-16T14:00:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Individual Task Files
|
||||
Each task file maintains sync metadata:
|
||||
```json
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"title": "Build authentication module",
|
||||
"status": "completed",
|
||||
"type": "feature",
|
||||
"agent": "code-developer",
|
||||
|
||||
"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",
|
||||
"last_sync": "2025-09-05T13:15:00Z",
|
||||
"version": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Performance & File Management
|
||||
|
||||
### Sync Performance
|
||||
- **Incremental Analysis**: Only processes changed files since last sync
|
||||
- **Cached Validation**: Reuses validation results for unchanged files
|
||||
- **Batch File Updates**: Groups related changes for efficiency
|
||||
- **Typical Sync Time**: <100ms for standard workflows, <500ms for complex
|
||||
|
||||
### Generated Reports
|
||||
**Automatic Documentation**: Every sync creates audit trail
|
||||
|
||||
- **Standard Sync Report**: `.summaries/sync-report-[timestamp].md`
|
||||
- **Dry Run Analysis**: `.summaries/sync-analysis-[timestamp].md`
|
||||
- **Force Sync Report**: `.summaries/force-sync-[timestamp].md`
|
||||
- **Conflict Resolution Log**: Embedded in sync reports
|
||||
- **Backup Files**: Created during force operations
|
||||
|
||||
### File System Maintenance
|
||||
- **Cleanup Policy**: Keep last 10 sync reports, archive older ones
|
||||
- **Backup Management**: Automatic cleanup of force sync backups after 7 days
|
||||
- **Error Recovery**: Complete rollback capability from backup files
|
||||
- **Integrity Monitoring**: Continuous validation of file system consistency
|
||||
|
||||
## File System Integration
|
||||
|
||||
### Integration Points
|
||||
- **JSON Task Files**: Authoritative source for all task data
|
||||
- **TODO_LIST.md**: Display layer synchronized from JSON files
|
||||
- **workflow-session.json**: High-level session state and progress
|
||||
- **Summary Files**: Completion documentation linked from TODO_LIST.md
|
||||
- **TodoWrite Tool**: Real-time task management interface
|
||||
|
||||
### File Output Summary
|
||||
**Generated Files**:
|
||||
- **Sync Reports**: `.summaries/sync-report-[timestamp].md`
|
||||
- **Backup Files**: `.summaries/backup-[file]-[timestamp].[ext]`
|
||||
- **Analysis Reports**: `.summaries/sync-analysis-[timestamp].md`
|
||||
- **Updated TODO_LIST.md**: Refreshed with current task state
|
||||
- **Updated workflow-session.json**: Current progress and task references
|
||||
|
||||
### Quality Assurance
|
||||
- **Pre-sync Validation**: File existence and format checks
|
||||
- **Post-sync Verification**: Cross-reference validation
|
||||
- **Rollback Testing**: Backup restoration validation
|
||||
- **Performance Monitoring**: Sync time and efficiency tracking
|
||||
|
||||
## Related Commands
|
||||
- `/task:context --sync-check` - Validate current sync status
|
||||
- `/task:create` - Creates tasks requiring sync
|
||||
- `/task:execute` - Generates summaries requiring sync
|
||||
- `/task:replan` - Structural changes requiring sync
|
||||
- `/workflow:sync` - Full workflow document synchronization
|
||||
Reference in New Issue
Block a user