catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

Initial release: Claude Code Workflow (CCW) v2.0

Browse Source 
🚀 Revolutionary AI-powered development workflow orchestration system

## 🔥 Core Innovations
- **Document-State Separation**: Markdown for planning, JSON for execution state
- **Progressive Complexity Management**: Level 0-2 adaptive workflow depth
- **5-Agent Orchestration**: Specialized AI agents with context preservation
- **Session-First Architecture**: Auto-discovery and state inheritance

## 🏗️ Key Features
- Intelligent workflow orchestration (Simple/Medium/Complex patterns)
- Real-time document-state synchronization with conflict resolution
- Hierarchical task management with 3-level JSON structure
- Gemini CLI integration with 12+ specialized templates
- Comprehensive file output generation for all workflow commands

## 📦 Installation
Remote one-liner installation:
```
iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-CCW/main/install-remote.ps1)
```

## 🎯 System Architecture
4-layer intelligent development architecture:
1. Command Layer - Smart routing and version management
2. Agent Layer - 5 specialized development agents
3. Workflow Layer - Gemini templates and task orchestration
4. Memory Layer - Distributed documentation and auto-sync

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-09-07 17:39:54 +08:00
commit 445ac823ba
87 changed files with 19076 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

466
.claude/commands/task/breakdown.md Normal file
View File

@@ -0,0 +1,466 @@
---
name: task-breakdown
description: Intelligent task decomposition with context-aware subtask generation
usage: /task:breakdown <task-id> [--strategy=<auto|interactive>] [--depth=<1-3>]
argument-hint: task-id [optional: strategy and depth]
examples:
- /task:breakdown IMPL-1
- /task:breakdown IMPL-1 --strategy=auto
- /task:breakdown IMPL-1.1 --depth=2 --strategy=interactive
---
# Task Breakdown Command (/task:breakdown)
## Overview
Intelligently breaks down complex tasks into manageable subtasks with automatic context distribution and agent assignment.
## Core Principles
**System:** @~/.claude/workflows/unified-workflow-system-principles.md
**Task Schema:** @~/.claude/workflows/task-management-principles.md
## Features
⚠️ **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
2. **Session Validation**: Use existing active session containing the parent task
3. **Context Integration**: Load existing session state and task hierarchy
### Smart Decomposition
- **Auto Strategy**: AI-powered subtask generation based on title
- **Interactive Mode**: Guided breakdown with suggestions
- **Context Distribution**: Subtasks inherit parent context
- **Agent Mapping**: Automatic agent assignment per subtask
### Built-in 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
### 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)
- Maximum depth: 3 levels (impl-N.M.P)
- Parent task progress = average of subtask progress
- Automatically updates TODO_LIST.md with hierarchical structure
## Usage
### Basic Breakdown
```bash
/task:breakdown IMPL-1
```
Interactive prompt with automatic task management:
```
Task: Build authentication module
Workflow: 28 total tasks (Complex workflow detected)
Suggested subtasks:
1. Design authentication schema
2. Implement login endpoint
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
```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
```
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
Agents assigned:
- 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
```
## Decomposition Patterns
### Feature Task Pattern
```
Feature: "Implement shopping cart"
├── Design data model
├── Build API endpoints
├── Add state management
├── Create UI components
└── Write tests
```
### Bug Fix Pattern
```
Bug: "Fix performance issue"
├── Profile and identify bottleneck
├── Implement optimization
├── Verify fix
└── Add regression test
```
### Refactor Pattern
```
Refactor: "Modernize auth system"
├── Analyze current implementation
├── Design new architecture
├── Migrate incrementally
├── Update documentation
└── Deprecate old code
```
## Context Distribution
Parent context is intelligently distributed:
```json
{
"parent": {
"id": "IMPL-1",
"context": {
"inherited_from": "WFS-[topic-slug]",
"requirements": ["JWT auth", "2FA support"],
"scope": ["src/auth/*"],
"acceptance": ["Authentication system works"]
}
},
"subtasks": [
{
"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"]
}
}
]
}
```
## Agent Assignment Logic
Based on subtask type:
- **Design/Planning** → `planning-agent`
- **Implementation** → `code-developer`
- **Testing** → `test-agent`
- **Documentation** → `docs-agent`
- **Review** → `review-agent`
## Validation
### Pre-breakdown Checks
1. Task exists and is valid
2. Task status is `pending`
3. Not already broken down
4. Workflow in IMPLEMENT phase
### 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
## Execution Planning
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)
```
.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
└── .task/
├── 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
- `/task:context` - Analyze task relationships and JSON structure
- `/task:replan` - Adjust breakdown and update task structure
## Examples
### Complex Feature
```bash
/task:breakdown IMPL-1 --strategy=auto --depth=2
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
```
## 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

349
.claude/commands/task/context.md Normal file
View File

@@ -0,0 +1,349 @@
---
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.

303
.claude/commands/task/create.md Normal file
View File

@@ -0,0 +1,303 @@
---
name: task-create
description: Create implementation tasks with automatic context awareness
usage: /task:create "<title>" [--type=<type>] [--priority=<level>]
argument-hint: "task title" [optional: type and priority]
examples:
- /task:create "Implement user authentication"
- /task:create "Build REST API endpoints" --type=feature
- /task:create "Fix login validation bug" --type=bugfix --priority=high
---
# Task Create Command (/task:create)
## Overview
Creates new implementation tasks during IMPLEMENT phase with automatic context awareness and ID generation.
## Core Principles
**System:** @~/.claude/workflows/core-principles.md
**Task Management:** @~/.claude/workflows/task-management-principles.md
## Features
### Automatic Behaviors
- **ID Generation**: Auto-generates impl-N hierarchical format (impl-N.M.P max depth)
- **Context Inheritance**: Inherits from workflow session and IMPL_PLAN.md
- **JSON File Creation**: Generates task JSON in `.workflow/WFS-[topic-slug]/.task/`
- **Document Integration**: Creates/updates TODO_LIST.md based on complexity triggers
- **Status Setting**: Initial status = "pending"
- **Workflow Sync**: Updates workflow-session.json task list automatically
- **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
### Context Awareness
- Detects current workflow phase (must be IMPLEMENT)
- Reads existing tasks from `.task/` directory to avoid duplicates
- Inherits requirements and scope from workflow-session.json
- Suggests related tasks based on existing JSON task hierarchy
- Analyzes complexity for structure level determination (Level 0-2)
## Usage
### Basic Creation
```bash
/task:create "Build authentication module"
```
Output:
```
✅ Task created: impl-1
Title: Build authentication module
Type: feature
Status: pending
Depth: 1 (main task)
Context inherited from workflow
```
### With Options
```bash
/task:create "Fix security vulnerability" --type=bugfix --priority=critical
```
### Task Types
- `feature` - New functionality (default)
- `bugfix` - Bug fixes
- `refactor` - Code improvements
- `test` - Test implementation
- `docs` - Documentation
### Priority Levels
- `low` - Can be deferred
- `normal` - Standard priority (default)
- `high` - Should be done soon
- `critical` - Must be done immediately
## Task Structure
```json
{
"id": "impl-1",
"parent_id": null,
"title": "Build authentication module",
"type": "feature",
"priority": "normal",
"status": "pending",
"depth": 1,
"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"]
},
"dependencies": {
"upstream": [],
"downstream": [],
"parent_dependencies": []
},
"subtasks": [],
"execution": {
"attempts": 0,
"current_attempt": null,
"history": []
},
"metadata": {
"created_at": "2025-09-05T10:30:00Z",
"started_at": null,
"completed_at": null,
"last_updated": "2025-09-05T10:30:00Z",
"version": "1.0"
}
}
```
## Document Integration Features
### 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
### Import from IMPL_PLAN.md
```bash
/task:create --from-plan
```
- 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
## 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
## Smart Suggestions
Based on title analysis:
```bash
/task:create "Write unit tests for auth module"
Suggestions:
- Related task: impl-1 (Build authentication module)
- Suggested agent: test-agent
- Estimated effort: 2h
- Dependencies: [impl-1]
- Suggested hierarchy: impl-1.3 (as subtask of impl-1)
```
## Validation Rules
1. **Phase Check** - Must be in IMPLEMENT phase (from workflow-session.json)
2. **Duplicate Check** - Title similarity detection across existing JSON files
3. **Session Validation** - Active workflow session must exist in `.workflow/`
4. **ID Uniqueness** - Auto-increment to avoid conflicts in `.task/` directory
5. **Hierarchy Validation** - Parent-child relationships must be valid (max 3 levels)
6. **File System Validation** - Proper directory structure and naming conventions
7. **JSON Schema Validation** - All task files conform to unified schema
## Error Handling
```bash
# Not in IMPLEMENT phase
❌ Cannot create tasks in PLAN phase
→ Use: /workflow implement
# No workflow session
❌ No active workflow found
→ Use: /workflow init "project name"
# Duplicate task
⚠️ Similar task exists: impl-3
→ Continue anyway? (y/n)
# Maximum depth exceeded
❌ Cannot create impl-1.2.3.1 (exceeds 3-level limit)
→ Suggest: impl-1.2.4 or promote to impl-2?
```
## Batch Creation
Create multiple tasks at once:
```bash
/task:create --batch
> Enter tasks (empty line to finish):
> Build login endpoint
> Add session management
> Write authentication tests
>
Created 3 tasks:
- impl-1: Build login endpoint
- impl-2: Add session management
- impl-3: Write authentication tests
```
## File Output Management
### 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
### 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
## 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
### Next Steps
After creation, use:
- `/task:breakdown` - Split into hierarchical subtasks with JSON files
- `/task:execute` - Run the task with summary generation
- `/task:context` - View task details and file references
- `/task:sync` - Validate file consistency across system
## Examples
### Feature Development
```bash
/task:create "Implement shopping cart functionality" --type=feature
```
### Bug Fix
```bash
/task:create "Fix memory leak in data processor" --type=bugfix --priority=high
```
### Refactoring
```bash
/task:create "Refactor database connection pool" --type=refactor
```
## Related Commands
- `/task:breakdown` - Break task into hierarchical subtasks
- `/task:context` - View/modify task context
- `/task:execute` - Execute task with agent
- `/task:status` - View task status and hierarchy

216
.claude/commands/task/execute.md Normal file
View File

@@ -0,0 +1,216 @@
---
name: task-execute
description: Execute tasks with appropriate agents and context-aware orchestration
usage: /task:execute <task-id> [--mode=<auto|guided|review>] [--agent=<agent-type>]
argument-hint: task-id [optional: mode and agent override]
examples:
- /task:execute impl-1
- /task:execute impl-1 --mode=guided
- /task:execute impl-1.2 --agent=code-developer --mode=review
---
### 🚀 **Command Overview: `/task:execute`**
- **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
- **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
### ⚙️ **Execution Modes**
- **auto (Default)**
- Fully autonomous execution with automatic agent selection.
- Provides progress updates at each checkpoint.
- Automatically completes the task when done.
- **guided**
- Executes step-by-step, requiring user confirmation at each checkpoint.
- Allows for dynamic adjustments and manual review during the process.
- **review**
- Executes under the supervision of a `review-agent`.
- Performs quality checks and provides detailed feedback at each step.
### 🤖 **Agent Selection Logic**
The system determines the appropriate agent for a task using the following logic.
```pseudo
FUNCTION select_agent(task, agent_override):
// A manual override always takes precedence.
// Corresponds to the --agent=<agent-type> flag.
IF agent_override IS NOT NULL:
RETURN agent_override
// If no override, select based on keywords in the task title.
ELSE:
CASE task.title:
WHEN CONTAINS "Build API", "Implement":
RETURN "code-developer"
WHEN CONTAINS "Design schema", "Plan":
RETURN "planning-agent"
WHEN CONTAINS "Write tests":
RETURN "test-agent"
WHEN CONTAINS "Review code":
RETURN "review-agent"
DEFAULT:
RETURN "code-developer" // Default agent
END CASE
END FUNCTION
```
### 🔄 **Core Execution Protocol**
`Pre-Execution` **->** `Execution` **->** `Post-Execution`
### ✅ **Pre-Execution Protocol**
`Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
- **Validation**: Checks for the task's JSON file in `.task/` and resolves its dependencies.
- **Context Preparation**: Loads task and workflow context, preparing it for the selected agent.
- **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
### 🏁 **Post-Execution Protocol**
`Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
- Updates status in the task's JSON file and `TODO_LIST.md`.
- Creates a summary in `.summaries/`.
- Stores outputs and syncs progress across the entire workflow session.
### 🧠 **Task & Subtask Execution Logic**
This logic defines how single, multiple, or parent tasks are handled.
```pseudo
FUNCTION execute_task_command(task_id, mode, parallel_flag):
// Handle parent tasks by executing their subtasks.
IF is_parent_task(task_id):
subtasks = get_subtasks(task_id)
EXECUTE_SUBTASK_BATCH(subtasks, mode)
// Handle wildcard execution (e.g., IMPL-001.*)
ELSE IF task_id CONTAINS "*":
subtasks = find_matching_tasks(task_id)
IF parallel_flag IS true:
EXECUTE_IN_PARALLEL(subtasks)
ELSE:
FOR each subtask in subtasks:
EXECUTE_SINGLE_TASK(subtask, mode)
// Default case for a single task ID.
ELSE:
EXECUTE_SINGLE_TASK(task_id, mode)
END FUNCTION
```
### 🛡️ **Error Handling & Recovery Logic**
```pseudo
FUNCTION pre_execution_check(task):
// Ensure dependencies are met before starting.
IF task.dependencies ARE NOT MET:
LOG_ERROR("Cannot execute " + task.id)
LOG_INFO("Blocked by: " + unmet_dependencies)
HALT_EXECUTION()
FUNCTION on_execution_failure(checkpoint):
// Provide user with recovery options upon failure.
LOG_WARNING("Execution failed at checkpoint " + checkpoint)
PRESENT_OPTIONS([
"Retry from checkpoint",
"Retry from beginning",
"Switch to guided mode",
"Abort execution"
])
AWAIT user_input
// System performs the selected action.
END FUNCTION
```
### ✨ **Advanced Execution Controls**
- **Dry Run (`--dry-run`)**: Simulates execution, showing the agent, estimated time, and files affected without making changes.
- **Custom Checkpoints (`--checkpoints="..."`)**: Overrides the default checkpoints with a custom, comma-separated list (e.g., `"design,implement,deploy"`).
- **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)**
This is the standard data structure loaded to provide context for task execution.
```json
{
"task": {
"id": "IMPL-001",
"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"]
}
},
"workflow": {
"session": "WFS-[topic-slug]",
"phase": "IMPLEMENT",
"global_context": ["Security first", "Backward compatible"]
},
"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"]
}
}
}
```
### 🎯 **Agent-Specific Context**
Different agents receive context tailored to their function:
- **`code-developer`**: Code patterns, dependencies, file scopes.
- **`planning-agent`**: High-level requirements, constraints, success criteria.
- **`test-agent`**: Test requirements, code to be tested, coverage goals.
- **`review-agent`**: Quality standards, style guides, review criteria.
### 🗃️ **File Output & System Integration**
- **Task JSON File (`.task/<task-id>.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.
### 📝 **Summary File Template**
A summary file is generated at `.workflow/WFS-[topic-slug]/.summaries/IMPL-[task-id]-summary.md`.
```markdown
# Task Summary: IMPL-001 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
## Execution Results
- **Duration**: 23 minutes
- **Agent**: code-developer
- **Tests Passed**: 12/12 (100%)
- **Coverage**: 87%
## 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)
```

466
.claude/commands/task/replan.md Normal file
View File

@@ -0,0 +1,466 @@
---
name: task-replan
description: Dynamically replan tasks based on changes, blockers, or new requirements
usage: /task:replan [task-id|--all] [--reason=<reason>] [--strategy=<adjust|rebuild>]
argument-hint: [task-id or --all] [optional: reason and strategy]
examples:
- /task:replan IMPL-001 --reason="requirements changed"
- /task:replan --all --reason="new security requirements"
- /task:replan IMPL-003 --strategy=rebuild
---
# Task Replan Command (/task:replan)
## Overview
Dynamically adjusts task planning based on changes, new requirements, blockers, or execution results.
## Core Principles
**System Architecture:** @~/.claude/workflows/unified-workflow-system-principles.md
## Replan Triggers
⚠️ **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
2. **Session Validation**: Use existing active session containing the task to be replanned
3. **Context Integration**: Load existing session state and task hierarchy
### Automatic Detection
System detects replanning needs from file monitoring:
- Requirements changed in workflow-session.json
- Dependencies blocked in JSON task hierarchy
- Task failed execution (logged in JSON execution history)
- New issues discovered and associated with tasks
- Scope modified in task context or IMPL_PLAN.md
- File structure complexity changes requiring reorganization
### Manual Triggers
```bash
/task:replan IMPL-001 --reason="API spec updated"
```
## 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. 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
```
## 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
```
### 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
```
### 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
```
## Global Replanning
### 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
```json
{
"task_id": "impl-001",
"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"
}
],
"todo_list_regenerated": true,
"session_updated": true
}
],
"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
}
}
```
## 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
```
#### 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
### Documentation Generation
**Automatic Report Creation**: Every replan generates documentation
- **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
### Issue Integration
```bash
/task:replan IMPL-001 --from-issue=ISS-001
Loading issue ISS-001...
Issue: "Login timeout too short"
Type: Bug
Priority: High
Suggested replan:
+ Add IMPL-001.4: Fix login timeout
~ Adjust IMPL-001.3: Include timeout tests
Apply? (y/n): y
```
## Error Handling
```bash
# Cannot replan completed task
❌ Task IMPL-001 is completed
→ Create new task instead
# No reason provided
⚠️ Please provide reason for replanning
→ Use --reason="explanation"
# Conflicts detected
⚠️ Replan conflicts with IMPL-002
→ Resolve with --force or adjust plan
```
## File Output Summary
### 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
### 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
## Related Commands
- `/task:breakdown` - Initial task breakdown with JSON file creation
- `/task:context` - Analyze current state from file system
- `/task:execute` - Execute replanned tasks with new structure
- `/task:sync` - Validate file consistency after replanning
- `/workflow:replan` - Replan entire workflow with session updates

280
.claude/commands/task/sync.md Normal file
View File

@@ -0,0 +1,280 @@
---
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