refactor: Simplify task commands and centralize documentation

- Move CORE.md to workflows/task-core.md for better organization - Significantly reduce task command file sizes: * breakdown.md: 310 → 120 lines * create.md: 326 → 100 lines * replan.md: 594 → 150 lines - Centralize task schema and implementation details in task-core.md - Update all references to use consistent ~/.claude/workflows/task-core.md paths - Maintain full functionality while improving clarity and maintainability - Separate task-level concerns from workflow-level architecture 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-13 02:41:50 +08:00 · 2025-09-14 11:00:15 +08:00
parent 56bd586506
commit 3536411419
4 changed files with 423 additions and 959 deletions
--- a/.claude/commands/task/replan.md
+++ b/.claude/commands/task/replan.md
@@ -12,583 +12,193 @@ examples:
 # Task Replan Command (/task:replan)

 ## Overview
-Replans individual tasks based on detailed user input with comprehensive change tracking, version management, and document synchronization. Focuses exclusively on single-task modifications with rich input options.
+Replans individual tasks with multiple input options, change tracking, and version management.

 ## Core Principles
-**Task Management:** @~/.claude/workflows/workflow-architecture.md
+**Task System:** @~/.claude/workflows/task-core.md

-## Single-Task Focus
-This command operates on **individual tasks only**. For workflow-wide changes, use `/workflow:action-plan` instead.
+## Key Features
+- **Single-Task Focus**: Operates on individual tasks only
+- **Multiple Input Sources**: Text, files, or issue references
+- **Version Tracking**: Backup previous versions
+- **Change Documentation**: Track all modifications

-⚠️ **CRITICAL**: Before replanning, checks for existing active session to avoid conflicts.
+⚠️ **CRITICAL**: Validates active session before replanning

-## Input Sources for Replanning
+## Input Sources

-### Direct Text Input (Default)
+### Direct Text (Default)
 ```bash
 /task:replan impl-1 "Add OAuth2 authentication support"
 ```
-**Processing**:
- Parse specific changes and requirements
- Extract new features or modifications needed
- Apply directly to target task structure

-### File-based Requirements
+### File-based Input
 ```bash
-/task:replan impl-1 --from-file updated-specs.md
-/task:replan impl-1 --from-file requirements-change.txt
+/task:replan impl-1 updated-specs.md
 ```
-**Supported formats**: .md, .txt, .json, .yaml
-**Processing**:
- Read detailed requirement changes from file
- Parse structured specifications and updates
- Apply file content to task replanning
+Supports: .md, .txt, .json, .yaml

-### Issue-based Replanning
+### Issue Reference
 ```bash
-/task:replan impl-1 --from-issue ISS-001
-/task:replan impl-1 --from-issue "bug-report"
+/task:replan impl-1 ISS-001
 ```
-**Processing**:
- Load issue description and requirements
- Extract necessary changes for task
- Apply issue resolution to task structure
-
-### Detailed Mode
-```bash
-/task:replan impl-1 --detailed
-```
-**Guided Input**:
-1. **New Requirements**: What needs to be added/changed?
-2. **Scope Changes**: Expand/reduce task scope?
-3. **Subtask Modifications**: Add/remove/modify subtasks?
-4. **Dependencies**: Update task relationships?
-5. **Success Criteria**: Modify completion conditions?
-6. **Agent Assignment**: Change assigned agent?
-7. **Implementation Details**: Update file paths, code locations, and logic flows?
+Loads issue description and requirements

 ### Interactive Mode
 ```bash
 /task:replan impl-1 --interactive
 ```
-**Step-by-Step Process**:
-1. **Current Analysis**: Review existing task structure
-2. **Change Identification**: What needs modification?
-3. **Impact Assessment**: How changes affect task?
-4. **Structure Updates**: Add/modify subtasks
-5. **Validation**: Confirm changes before applying
+Guided step-by-step modification process with validation

-## Replanning Flow with Change Tracking
+## Replanning Process

-### 1. Task Loading & Validation
-```
-Load Task → Read current task JSON file
-Validate → Check task exists and can be modified
-Session Check → Verify active workflow session
-```
+1. **Load & Validate**: Read task JSON and validate session
+2. **Parse Input**: Process changes from input source
+3. **Backup Version**: Create previous version backup
+4. **Update Task**: Modify JSON structure and relationships
+5. **Save Changes**: Write updated task and increment version
+6. **Update Session**: Reflect changes in workflow stats

-### 2. Input Processing
-```
-Detect Input Type → Identify source type
-Extract Requirements → Parse change requirements
-Analyze Impact → Determine modifications needed
-```
-
-### 3. Version Management
-```
-Create Version → Backup current task state
-Update Version → Increment task version number
-Archive → Store previous version in versions/
-```
-
-### 4. Task Structure Updates
-```
-Modify Task → Update task JSON structure
-Update Subtasks → Add/remove/modify as needed
-Update Relations → Fix dependencies and hierarchy
-Update Context → Modify requirements and scope
-```
-
-### 5. Document Synchronization
-```
-Update IMPL_PLAN → Regenerate task section
-Update TODO_LIST → Sync task hierarchy (if exists)
-Update Session → Reflect changes in workflow state
-```
-
-### 6. Change Documentation
-```
-Create Change Log → Document all modifications
-Generate Summary → Create replan report
-Update History → Add to task replan history
-```
-
-## Version Management (Simplified)
+## Version Management

 ### Version Tracking
-Each replan creates a new version with complete history:
-
+Tasks maintain version history:
 ```json
 {
  "id": "impl-1",
-  "title": "Build authentication module",
  "version": "1.2",
  "replan_history": [
    {
-      "version": "1.1",
-      "reason": "Original plan",
-      "input_source": "initial_creation"
-    },
-    {
-      "version": "1.2", 
-      "reason": "Add OAuth2 authentication support",
+      "version": "1.2",
+      "reason": "Add OAuth2 support",
      "input_source": "direct_text",
-      "changes": [
-        "Added subtask impl-1.3: OAuth2 integration",
-        "Added subtask impl-1.4: Token management",
-        "Modified scope to include external auth"
-      ],
      "backup_location": ".task/versions/impl-1-v1.1.json"
    }
-  ],
-  "context": {
-    "requirements": ["Basic auth", "Session mgmt", "OAuth2 support"],
-    "scope": ["src/auth/*", "tests/auth/*"],
-    "acceptance": ["All auth methods work"]
-  },
-  "implementation": {
-    "files": [
-      {
-        "path": "src/auth/oauth.ts",
-        "location": {
-          "function": "handleOAuthCallback",
-          "lines": "45-80",
-          "description": "OAuth callback handler (added in replan)"
-        },
-        "original_code": "// New file - requires creation",
-        "modifications": {
-          "current_state": "File does not exist",
-          "proposed_changes": [
-            "Create OAuth2 callback handler",
-            "Integrate with existing auth system"
-          ],
-          "logic_flow": [
-            "receiveCallback() ───► validateAuthCode()",
-            "◊─── if valid ───► exchangeForToken() ───► storeUserSession()",
-            "◊─── if invalid ───► logError() ───► redirectToLogin()"
-          ],
-          "reason": "Support external authentication providers",
-          "expected_outcome": "Seamless OAuth2 integration"
-        }
-      }
-    ],
-    "context_notes": {
-      "dependencies": ["passport-oauth2", "express-session"],
-      "affected_modules": ["auth-middleware", "user-session"],
-      "risks": [
-        "OAuth provider configuration complexity",
-        "Session management conflicts with existing auth"
-      ],
-      "performance_considerations": "External API calls may add 200-500ms latency",
-      "error_handling": "Graceful fallback to standard login on OAuth failure"
-    },
-    "analysis_source": "manual"
-  }
+  ]
 }
 ```

-### File Structure After Replan
+**Complete schema**: See @~/.claude/workflows/task-core.md
+
+### File Structure
 ```
 .task/
-├── impl-1.json                    # Current version (1.2)
-├── impl-1.3.json                  # New subtask
-├── impl-1.4.json                  # New subtask  
+├── impl-1.json                    # Current version
 ├── versions/
-│   └── impl-1-v1.1.json          # Previous version backup
-└── summaries/
-    └── replan-impl-1-20250908.md  # Change log
+│   └── impl-1-v1.1.json          # Previous backup
+└── [new subtasks as needed]
 ```

-## Implementation Field Updates
+## Implementation Updates

-### Implementation Change Detection
-When replanning, the system analyzes changes to the implementation field:
+### Change Detection
+Tracks modifications to:
+- Files in implementation.files array
+- Dependencies and affected modules
+- Risk assessments and performance notes
+- Logic flows and code locations

-**Implementation Changes Tracked**:
- New files added to implementation.files array
- Modified file paths or locations
- Updated original_code snippets (via gemini re-analysis if needed)
- Changed logic flows and data flow diagrams
- Modified dependencies and risk assessments
- Updated performance considerations and error handling
+### Analysis Triggers
+May require gemini re-analysis when:
+- New files need code extraction
+- Function locations change
+- Dependencies require re-evaluation

-**Gemini Re-analysis Triggers**:
- New file paths that need code extraction
- Changed function locations requiring updated code snippets
- Modified scope requiring dependency re-evaluation
- When analysis_source was "gemini" and major changes occur
+## Document Updates

-**Example Implementation Update**:
-```json
-"implementation": {
-  "files": [
-    {
-      "path": "src/auth/oauth.ts", // NEW FILE ADDED
-      "original_code": "// New file - requires creation",
-      "modifications": {
-        "logic_flow": [
-          "// NEW FLOW ADDED FOR OAUTH"
-        ]
-      }
-    }
-  ],
-  "context_notes": {
-    "dependencies": ["passport-oauth2"], // NEW DEPENDENCY
-    "risks": [
-      "OAuth provider configuration complexity" // NEW RISK
-    ]
-  }
-}
-```
+### Planning Document
+May update IMPL_PLAN.md sections when task structure changes significantly

-## IMPL_PLAN.md Updates
-
-### Automatic Plan Regeneration
-When task is replanned, the corresponding section in IMPL_PLAN.md is updated:
-
-**Before Replan**:
-```markdown
-## Task Breakdown
- **IMPL-001**: Build authentication module
-  - Basic login functionality
-  - Session management
-  - Password reset
-```
-
-**After Replan**:
-```markdown
-## Task Breakdown
- **IMPL-001**: Build authentication module (v1.2)
-  - Basic login functionality
-  - Session management  
-  - OAuth2 integration (added)
-  - Token management (added)
-  - Password reset
-
-*Last updated via task:replan*
-```
-
-### Plan Update Process
-1. **Locate Task Section**: Find task in IMPL_PLAN.md by ID
-2. **Update Description**: Modify task title if changed
-3. **Update Subtasks**: Add/remove bullet points for subtasks
-4. **Add Version Info**: Include version number and update timestamp
-5. **Preserve Context**: Keep surrounding plan structure intact
-
-## TODO_LIST.md Synchronization
-
-### Automatic TODO List Updates
-If TODO_LIST.md exists in workflow, synchronize task changes:
-
-**Before Replan**:
-```markdown
-## Implementation Tasks
- [ ] impl-1: Build authentication module
-  - [x] impl-1.1: Design schema
-  - [ ] impl-1.2: Implement logic
-```
-
-**After Replan**:
-```markdown
-## Implementation Tasks
- [ ] impl-1: Build authentication module (updated v1.2)
-  - [x] impl-1.1: Design schema
-  - [ ] impl-1.2: Implement logic  
-  - [ ] impl-1.3: OAuth2 integration (new)
-  - [ ] impl-1.4: Token management (new)
-```
-
-### TODO Update Rules
- **Preserve Status**: Keep existing checkbox states [x] or [ ]
- **Add New Items**: New subtasks get [ ] checkbox
- **Mark Changes**: Add (updated), (new), (modified) indicators
- **Remove Items**: Delete subtasks that were removed
- **Update Hierarchy**: Maintain proper indentation structure
+### TODO List Sync
+If TODO_LIST.md exists, synchronizes:
+- New subtasks (with [ ] checkbox)
+- Modified tasks (marked as updated)
+- Removed subtasks (deleted from list)

 ## Change Documentation

-### Comprehensive Change Log
-Every replan generates detailed documentation:
+### Change Summary
+Generates brief change log with:
+- Version increment (1.1 → 1.2)
+- Input source and reason
+- Key modifications made
+- Files updated/created
+- Backup location

-```markdown
-# Task Replan Log: impl-1
-*Date: 2025-09-08T14:00:00Z*
-*Version: 1.1 → 1.2*
-*Input: Direct text - "Add OAuth2 authentication support"*
+## Session Updates

-## Changes Applied
+Updates workflow-session.json with:
+- Modified task tracking
+- Task count changes (if subtasks added/removed)
+- Last modification timestamps

-### Task Structure Updates
- **Added Subtasks**:
-  - impl-1.3: OAuth2 provider integration
-  - impl-1.4: Token management system
- **Modified Subtasks**:
-  - impl-1.2: Updated to include OAuth flow integration
- **Removed Subtasks**: None
+## Rollback Support

-### Context Modifications
- **Requirements**: Added OAuth2 external authentication
- **Scope**: Expanded to include third-party auth integration
- **Acceptance**: Include OAuth2 token validation
- **Dependencies**: No changes
-
-### File System Updates
- **Updated**: .task/impl-1.json (version 1.2)
- **Created**: .task/impl-1.3.json, .task/impl-1.4.json
- **Backed Up**: .task/versions/impl-1-v1.1.json
- **Updated**: IMPL_PLAN.md (task section regenerated)
- **Updated**: TODO_LIST.md (2 new items added)
-
-## Impact Analysis
- **Timeline**: +2 days for OAuth implementation
- **Complexity**: Increased (simple → medium)
- **Agent**: Remains code-developer, may need OAuth expertise
- **Dependencies**: Task impl-2 may need OAuth context
-
-## Related Tasks Affected
- impl-2: May need OAuth integration context
- impl-5: Authentication dependency updated
-
-## Rollback Information
- **Previous Version**: 1.1
- **Backup Location**: .task/versions/impl-1-v1.1.json
- **Rollback Command**: `/task:replan impl-1 --rollback v1.1`
-```
-
-## Session State Updates
-
-### Workflow Integration
-After task replanning, update session information:
-
-```json
-{
-  "phases": {
-    "IMPLEMENT": {
-      "tasks": ["impl-1", "impl-2", "impl-3"],
-      "completed_tasks": [],
-      "modified_tasks": {
-        "impl-1": {
-          "version": "1.2", 
-          "last_replan": "2025-09-08T14:00:00Z",
-          "reason": "OAuth2 integration added"
-        }
-      },
-      "task_count": {
-        "total": 6,
-        "added_today": 2
-      }
-    }
-  },
-  "documents": {
-    "IMPL_PLAN.md": {
-      "last_updated": "2025-09-08T14:00:00Z",
-      "updated_sections": ["IMPL-001"]
-    },
-    "TODO_LIST.md": {
-      "last_updated": "2025-09-08T14:00:00Z", 
-      "items_added": 2
-    }
-  }
-}
-```
-
-## Rollback Support (Simple)
-
-### Basic Version Rollback
 ```bash
 /task:replan impl-1 --rollback v1.1

-Rollback Analysis:
-Current Version: 1.2
-Target Version: 1.1
-Changes to Revert:
- Remove subtasks: impl-1.3, impl-1.4
- Restore previous context
- Update IMPL_PLAN.md section
- Update TODO_LIST.md structure
-
-Files Affected:
- Restore: .task/impl-1.json from backup
- Remove: .task/impl-1.3.json, .task/impl-1.4.json
- Update: IMPL_PLAN.md, TODO_LIST.md
+Rollback to version 1.1:
+- Restore task from backup
+- Remove new subtasks if any
+- Update session stats

 Confirm rollback? (y/n): y

-Rolling back...
-✅ Task impl-1 rolled back to version 1.1
-✅ Documents updated
-✅ Change log created
+✅ Task rolled back to version 1.1
 ```

-## Practical Examples
+## Examples

-### Example 1: Add Feature with Full Tracking
+### Text Input
 ```bash
-/task:replan impl-1 "Add two-factor authentication"
+/task:replan impl-1 "Add OAuth2 authentication support"

-Loading task impl-1 (current version: 1.2)...
-
-Processing request: "Add two-factor authentication"
-Analyzing required changes...
-
-Proposed Changes:
-+ Add impl-1.5: Two-factor setup
-+ Add impl-1.6: 2FA validation
-~ Modify impl-1.2: Include 2FA in auth flow
+Processing changes...
+Proposed updates:
+ Add OAuth2 integration
+ Update authentication flow

 Apply changes? (y/n): y

-Executing replan...
-✓ Version 1.3 created
-✓ Added 2 new subtasks
-✓ Modified 1 existing subtask
-✓ IMPL_PLAN.md updated
-✓ TODO_LIST.md synchronized
-✓ Change log saved
-
-Result:
- Task version: 1.2 → 1.3
- Subtasks: 4 → 6
- Documents updated: 2
- Backup: .task/versions/impl-1-v1.2.json
+✓ Version 1.2 created
+✓ Context updated
+✓ Backup saved
 ```

-### Example 2: Issue-based Replanning
+### File Input
 ```bash
-/task:replan impl-2 --from-issue ISS-001
+/task:replan impl-2 requirements.md

-Loading issue ISS-001...
-Issue: "Database queries too slow - need caching"
-Priority: High
+Loading requirements.md...
+Applying specification changes...

-Applying to task impl-2...
-
-Required changes for performance fix:
-+ Add impl-2.4: Implement Redis caching
-+ Add impl-2.5: Query optimization
-~ Modify impl-2.1: Add cache checks
-
-Documents updating:
-✓ Task JSON updated (v1.0 → v1.1)  
-✓ IMPL_PLAN.md section regenerated
-✓ TODO_LIST.md: 2 new items added
-✓ Issue ISS-001 linked to task
-
-Summary:
-Performance improvements added to impl-2
-Timeline impact: +1 day for caching setup
-```
-
-### Example 3: Interactive Replanning
-```bash
-/task:replan impl-3 --interactive
-
-Interactive Replan for impl-3: API integration
-Current version: 1.0
-
-1. What needs to change? "API spec updated, need webhook support"
-2. Add new requirements? "Webhook handling, signature validation"  
-3. Add subtasks? "y"
-   - New subtask 1: "Webhook receiver endpoint"
-   - New subtask 2: "Signature validation"
-   - Add more? "n"
-4. Modify existing subtasks? "n"
-5. Update dependencies? "Now depends on impl-1 (auth for webhooks)"
-6. Change agent assignment? "n"
-
-Applying interactive changes...
-✓ Added 2 subtasks for webhook functionality
-✓ Updated dependencies  
-✓ Context expanded for webhook requirements
+✓ Task updated with new requirements
 ✓ Version 1.1 created
-✓ All documents synchronized
-
-Interactive replan complete!
 ```

 ## Error Handling

-### Input Validation Errors
 ```bash
 # Task not found
-❌ Task impl-5 not found in current session
+❌ Task impl-5 not found
 → Check task ID with /context

-# No input provided
-❌ Please specify changes needed for replanning
-→ Use descriptive text or --detailed/--interactive
-
 # Task completed
 ⚠️ Task impl-1 is completed (cannot replan)
 → Create new task for additional work

 # File not found
-❌ File updated-specs.md not found
-→ Check file path and try again
+❌ File requirements.md not found
+→ Check file path
+
+# No input provided
+❌ Please specify changes needed
+→ Provide text, file, or issue reference
 ```

-### Document Update Issues
-```bash
-# Missing IMPL_PLAN.md
-⚠️ IMPL_PLAN.md not found in workflow
-→ Task update proceeding, plan regeneration skipped
-
-# TODO_LIST.md not writable
-⚠️ Cannot update TODO_LIST.md (permissions)
-→ Task updated, manual TODO sync needed
-
-# Session conflict
-⚠️ Task impl-1 being modified in another session
-→ Complete other operation first
-```
-
-## Integration Points
-
-### Command Workflow
-```bash
-# 1. Replan task with new requirements
-/task:replan impl-1 "Add advanced security features"
-
-# 2. View updated task structure  
-/context impl-1
-→ Shows new version with changes
-
-# 3. Check updated planning documents
-cat IMPL_PLAN.md
-→ Task section shows v1.3 with new features
-
-# 4. Verify TODO list synchronization
-cat TODO_LIST.md
-→ New subtasks appear with [ ] checkboxes
-
-# 5. Execute replanned task
-/task:execute impl-1
-→ Works with updated task structure
-```
-
-### Session Integration
- **Task Count Updates**: Reflect additions/removals in session stats
- **Document Sync**: Keep IMPL_PLAN.md and TODO_LIST.md current
- **Version Tracking**: Complete audit trail in task JSON
- **Change Traceability**: Link replans to input sources
-
 ## Related Commands

- `/context` - View task structure and version history
- `/task:execute` - Execute replanned tasks with new structure  
- `/workflow:action-plan` - For workflow-wide replanning
- `/task:create` - Create new tasks for additional work
-
---
-
-**System ensures**: Focused single-task replanning with comprehensive change tracking, document synchronization, and complete audit trail
+- `/context` - View updated task structure
+- `/task:execute` - Execute replanned task
+- `/task:create` - Create new tasks
+- `/workflow:action-plan` - For workflow-wide changes