From 821c900ba0ff41fc1a9997ba9940156692ae6477 Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 26 Jan 2026 14:02:54 +0100 Subject: [PATCH] docs: add task management workflow and update guides - Add guide/workflows/task-management.md (comprehensive workflow) - Update ultimate-guide.md with task management sections - Add task management quick reference to cheatsheet - Update machine-readable/reference.yaml with new content - Update .gitignore for docs/ directory Co-Authored-By: Claude Sonnet 4.5 --- .gitignore | 2 +- guide/README.md | 1 + guide/cheatsheet.md | 41 ++ guide/ultimate-guide.md | 145 +++++- guide/workflows/plan-driven.md | 1 + guide/workflows/task-management.md | 775 +++++++++++++++++++++++++++++ guide/workflows/tdd-with-claude.md | 1 + machine-readable/reference.yaml | 34 +- 8 files changed, 997 insertions(+), 3 deletions(-) create mode 100644 guide/workflows/task-management.md diff --git a/.gitignore b/.gitignore index 66446e8..bbbd3d4 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,7 @@ __pycache__/ *.mp3 *.onnx -# Personal notes & temp files +# Personal notes & temp filesΓ  to-ignore/ .grepai/ whitepapers/ diff --git a/guide/README.md b/guide/README.md index 412d94a..8042007 100644 --- a/guide/README.md +++ b/guide/README.md @@ -46,6 +46,7 @@ Hands-on guides for effective development patterns: | [workflows/plan-driven.md](./workflows/plan-driven.md) | Using /plan mode effectively | | [workflows/iterative-refinement.md](./workflows/iterative-refinement.md) | Iterative improvement loops | | [workflows/tts-setup.md](./workflows/tts-setup.md) | Add text-to-speech narration to Claude Code (18 min) | +| [workflows/task-management.md](./workflows/task-management.md) | Multi-session task tracking, TodoWrite migration | ## Recommended Reading Order diff --git a/guide/cheatsheet.md b/guide/cheatsheet.md index ea4c58a..de0a35d 100644 --- a/guide/cheatsheet.md +++ b/guide/cheatsheet.md @@ -351,6 +351,47 @@ claude -p "fix typos" --dangerously-skip-permissions --- +## Task Management (v2.1.16+) + +**Two systems available:** + +| System | When to Use | Persistence | +|--------|-------------|-------------| +| **Tasks API** (v2.1.16+) | Multi-session projects, dependencies | βœ… Disk (`~/.claude/tasks/`) | +| **TodoWrite** (Legacy) | Simple single-session | ❌ Session only | + +### Tasks API Commands + +```bash +# Enable persistence across sessions +export CLAUDE_CODE_TASK_LIST_ID="project-name" +claude + +# Inside Claude: Create task hierarchy +> "Create tasks for auth system with dependencies" + +# Resume later (new session) +export CLAUDE_CODE_TASK_LIST_ID="project-name" +claude +> "TaskList to see current state" +``` + +**Key capabilities:** +- πŸ“ **Persistent**: Survives session end, context compaction +- πŸ”— **Dependencies**: Task A blocks Task B +- πŸ”„ **Multi-session**: Broadcast state to multiple terminals +- πŸ“Š **Status**: pending β†’ in_progress β†’ completed/failed + +**Migration flag** (v2.1.19+): +```bash +# Revert to old TodoWrite system +CLAUDE_CODE_ENABLE_TASKS=false claude +``` + +**β†’ Full workflow**: [guide/workflows/task-management.md](../workflows/task-management.md) + +--- + ## The Golden Rules 1. **Always review diffs** before accepting diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 521700a..3a6b7e2 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -3122,7 +3122,150 @@ Claude Code has 8 core tools: | `Grep` | Search file contents (ripgrep-based) | | `Glob` | Find files by pattern | | `Task` | Spawn sub-agents (isolated context) | -| `TodoWrite` | Track progress | +| `TodoWrite` | Track progress (legacy, see below) | + +### Task Management System + +**Version**: Claude Code v2.1.16+ introduced a new task management system + +Claude Code provides two task management approaches: + +| Feature | TodoWrite (Legacy) | Tasks API (v2.1.16+) | +|---------|-------------------|---------------------| +| **Persistence** | Session memory only | Disk storage (`~/.claude/tasks/`) | +| **Multi-session** | ❌ Lost on session end | βœ… Survives across sessions | +| **Dependencies** | ❌ Manual ordering | βœ… Task blocking (A blocks B) | +| **Coordination** | Single agent | βœ… Multi-agent broadcast | +| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed | +| **Enabled by** | Always available | Default since v2.1.19 | + +#### Tasks API (v2.1.16+) + +**Available tools:** +- `TaskCreate` - Initialize new tasks with hierarchy and dependencies +- `TaskUpdate` - Modify task status, metadata, and dependencies +- `TaskGet` - Retrieve individual task details +- `TaskList` - List all tasks in current task list + +**Core capabilities:** +- **Persistent storage**: Tasks saved to `~/.claude/tasks//` +- **Multi-session coordination**: Share state across multiple Claude sessions +- **Dependency tracking**: Tasks can block other tasks (task A blocks task B) +- **Status lifecycle**: pending β†’ in_progress β†’ completed/failed +- **Metadata**: Attach custom data (priority, estimates, related files, etc.) + +**Configuration:** + +```bash +# Enable multi-session task persistence +export CLAUDE_CODE_TASK_LIST_ID="project-name" +claude + +# Example: Project-specific task list +export CLAUDE_CODE_TASK_LIST_ID="api-v2-auth-refactor" +claude +``` + +**⚠️ Important**: Use repository-specific task list IDs to avoid cross-project contamination. Tasks with the same ID are shared across all sessions using that ID. + +**Task schema example:** + +```json +{ + "id": "task-auth-login", + "title": "Implement login endpoint", + "description": "POST /auth/login with JWT token generation", + "status": "in_progress", + "dependencies": [], + "metadata": { + "priority": "high", + "estimated_duration": "2h", + "related_files": ["src/auth/login.ts", "src/middleware/auth.ts"] + } +} +``` + +**When to use Tasks API:** +- Projects spanning multiple coding sessions +- Complex task hierarchies with dependencies +- Multi-agent coordination scenarios +- Need to resume work after context compaction + +#### TodoWrite (Legacy) + +**Tool**: `TodoWrite` - Creates task lists stored in session memory + +**Capabilities:** +- Simple task tracking within a single session +- Status tracking: pending/in_progress/completed +- Lost when session ends or context is compacted + +**When to use TodoWrite:** +- Single-session, straightforward implementations +- Quick fixes or exploratory coding +- Claude Code < v2.1.16 +- Prefer simplicity over persistence + +**Migration flag** (v2.1.19+): + +```bash +# Temporarily revert to TodoWrite system +CLAUDE_CODE_ENABLE_TASKS=false claude + +# Use new Tasks API (default) +claude +``` + +#### Best Practices + +**Task hierarchy design:** +``` +Project (parent) +└── Feature A (child) + β”œβ”€β”€ Component A1 (leaf task) + β”‚ β”œβ”€β”€ Implementation + β”‚ └── Tests (depends on Implementation) + └── Component A2 +``` + +**Dependency management:** +- Always define dependencies when creating tasks +- Use task IDs (not titles) for dependency references +- Verify dependencies with `TaskGet` before execution + +**Status transitions:** +- Mark `in_progress` when starting work (prevents parallel execution) +- Update frequently for visibility +- Only mark `completed` when fully accomplished (tests passing, validated) +- Use `failed` status with error metadata for debugging + +**Metadata conventions:** +```json +{ + "priority": "high|medium|low", + "estimated_duration": "2h", + "related_files": ["path/to/file.ts"], + "related_issue": "https://github.com/org/repo/issues/123", + "type": "feature|bugfix|refactor|test" +} +``` + +#### Complete Workflow + +**β†’ See**: [Task Management Workflow](./workflows/task-management.md) for: +- Task planning phase (decomposition, hierarchy design) +- Task execution patterns +- Session management and resumption +- Integration with TDD and Plan-Driven workflows +- TodoWrite migration guide +- Patterns, anti-patterns, and troubleshooting + +#### Sources + +- **Official**: [Claude Code CHANGELOG v2.1.16](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) - "new task management system with dependency tracking" +- **Official**: [System Prompts - TaskCreate](https://github.com/Piebald-AI/claude-code-system-prompts) (extracted from Claude Code source) +- **Community**: [paddo.dev - From Beads to Tasks](https://paddo.dev/blog/from-beads-to-tasks/) +- **Community**: [llbbl.blog - Two Changes in Claude Code](https://llbbl.blog/2026/01/25/two-changes-in-claude-code.html) ### Context Management diff --git a/guide/workflows/plan-driven.md b/guide/workflows/plan-driven.md index 69dc5c9..34c43f0 100644 --- a/guide/workflows/plan-driven.md +++ b/guide/workflows/plan-driven.md @@ -249,3 +249,4 @@ Plans in `.claude/plans/` serve as decision documentation: - [tdd-with-claude.md](./tdd-with-claude.md) β€” Combine with TDD - [spec-first.md](./spec-first.md) β€” Combine with Spec-First - [iterative-refinement.md](./iterative-refinement.md) β€” Post-plan iteration +- [task-management.md](./task-management.md) β€” Track plan execution across sessions with Tasks API diff --git a/guide/workflows/task-management.md b/guide/workflows/task-management.md new file mode 100644 index 0000000..a276a37 --- /dev/null +++ b/guide/workflows/task-management.md @@ -0,0 +1,775 @@ +# Task Management Workflow + +**Version**: Claude Code v2.1.16+ +**Prerequisites**: Understanding of multi-session workflows, basic CLI proficiency +**Time**: 15-30 min to learn, applies to all complex projects + +## Overview + +Task management in Claude Code evolved significantly in v2.1.16 with the introduction of the **Tasks API**, complementing the original **TodoWrite** tool. This workflow teaches you when to use each system and how to leverage multi-session task coordination for complex projects. + +**When to use this workflow:** +- Projects spanning multiple coding sessions +- Multi-agent coordination scenarios +- Complex task hierarchies with dependencies +- Need to resume work after context compaction or session interruption + +**When NOT to use:** +- Single-session, straightforward implementations +- Quick fixes or exploratory coding +- Tasks completable in <10 minutes + +--- + +## System Comparison Quick Reference + +| Feature | TodoWrite (Legacy) | Tasks API (v2.1.16+) | +|---------|-------------------|---------------------| +| **Persistence** | Session memory only | Disk storage (`~/.claude/tasks/`) | +| **Multi-session** | ❌ Lost on session end | βœ… Survives across sessions | +| **Dependencies** | ❌ Manual ordering | βœ… Task blocking (A blocks B) | +| **Coordination** | Single agent | βœ… Multi-agent with broadcast | +| **Status tracking** | pending/in_progress/completed | pending/in_progress/completed/failed | +| **When to use** | Simple single-session todos | Complex multi-session projects | + +**Migration flag** (v2.1.19+): +```bash +# Use old system (TodoWrite) +CLAUDE_CODE_ENABLE_TASKS=false claude + +# Use new system (Tasks API) - default since v2.1.19 +claude +``` + +--- + +## Workflow Phase 1: Task Planning + +**Goal**: Decompose complex work into trackable, executable units + +### Step 1: Analyze Scope + +Before creating tasks, understand what you're building: + +```bash +# Discovery pattern +claude +> "Analyze this codebase for implementing JWT authentication: + - Glob for existing auth patterns + - Grep for security-related code + - Identify integration points" +``` + +### Step 2: Design Task Hierarchy + +Break work into logical phases with dependencies: + +**Example: Authentication System** +``` +Authentication System (parent) +β”œβ”€β”€ 1. Login endpoint (no dependencies) +β”œβ”€β”€ 2. Token refresh (depends on #1) +β”œβ”€β”€ 3. Logout endpoint (depends on #1) +└── 4. Integration tests (depends on #1, #2, #3) +``` + +### Step 3: Create Task Structure + +Use `TaskCreate` to materialize your plan: + +```bash +# Session 1: Planning phase +export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2" +claude + +# Inside Claude session: +> "Create a task hierarchy for JWT authentication: + + Parent task: 'Implement JWT authentication system' + - Description: Add JWT-based auth with refresh tokens and secure storage + + Child tasks: + 1. 'Create login endpoint' (no dependencies) + 2. 'Implement token refresh logic' (depends on task 1) + 3. 'Create logout endpoint' (depends on task 1) + 4. 'Write integration tests' (depends on tasks 1, 2, 3) + + Use TaskCreate with proper metadata." +``` + +**Expected output from Claude:** +```json +{ + "tasks": [ + { + "id": "task-auth-parent", + "title": "Implement JWT authentication system", + "status": "pending", + "children": ["task-login", "task-refresh", "task-logout", "task-tests"] + }, + { + "id": "task-login", + "title": "Create login endpoint", + "status": "pending", + "dependencies": [], + "metadata": {"priority": "high", "estimated_duration": "2h"} + }, + { + "id": "task-refresh", + "title": "Implement token refresh logic", + "status": "pending", + "dependencies": ["task-login"], + "metadata": {"priority": "high", "estimated_duration": "1h"} + } + // ... other tasks + ] +} +``` + +--- + +## Workflow Phase 2: Task Execution + +**Goal**: Execute tasks systematically with progress tracking + +### Execution Pattern + +``` +TaskList β†’ TaskGet (next pending) β†’ Execute β†’ TaskUpdate β†’ Validate β†’ Repeat +``` + +### Step 1: Discover Next Task + +```bash +# Session 2: Start implementation +export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2" +claude + +> "TaskList to show all pending tasks" +``` + +**Output:** +``` +Tasks for 'auth-system-v2': +βœ… task-login: Create login endpoint [completed] +⏳ task-refresh: Implement token refresh logic [pending, blocked by: none] +⏳ task-logout: Create logout endpoint [pending, blocked by: none] +⏳ task-tests: Write integration tests [pending, blocked by: task-refresh, task-logout] +``` + +### Step 2: Get Task Details + +```bash +> "TaskGet task-refresh to see full requirements" +``` + +**Output:** +```json +{ + "id": "task-refresh", + "title": "Implement token refresh logic", + "description": "Create endpoint POST /auth/refresh that validates refresh token and issues new access token", + "status": "pending", + "dependencies": ["task-login"], + "metadata": { + "priority": "high", + "estimated_duration": "1h", + "files": ["src/auth/refresh.ts", "src/middleware/auth.ts"] + } +} +``` + +### Step 3: Execute & Update + +```bash +> "Mark task-refresh as in_progress, then implement the token refresh endpoint according to requirements" + +# Claude executes: TaskUpdate task-refresh status=in_progress +# Claude implements the feature... +# Upon completion: + +> "Mark task-refresh as completed" +# Claude executes: TaskUpdate task-refresh status=completed +``` + +### Step 4: Validate + +```bash +> "Run tests for token refresh functionality" + +# If tests pass: +# βœ… Task remains completed + +# If tests fail: +> "TaskUpdate task-refresh status=failed, add error details to metadata" +``` + +--- + +## Workflow Phase 3: Session Management + +**Goal**: Seamlessly resume work across sessions and context boundaries + +### Persistence Mechanism + +**Storage location**: `~/.claude/tasks//` + +Tasks survive: +- Session termination +- Context compaction (`/compact`) +- System restarts +- Multiple days of interruption + +### Resume Pattern + +```bash +# Days later, different terminal session +export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2" +claude + +> "TaskList to show current state" + +# Output shows exactly where you left off: +# βœ… task-login [completed] +# βœ… task-refresh [completed] +# ⏳ task-logout [pending] +# ⏳ task-tests [pending, blocked by: task-logout] + +> "Continue with next pending task that isn't blocked" +``` + +### Multi-Terminal Coordination + +**Use case**: Run multiple Claude instances working on the same project + +```bash +# Terminal 1: Frontend work +export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2" +claude +> "Work on task-logout endpoint" + +# Terminal 2: Test writing (simultaneous) +export CLAUDE_CODE_TASK_LIST_ID="auth-system-v2" +claude +> "TaskList - check what's completed so I can write tests" + +# Both terminals see real-time state updates +``` + +**⚠️ Warning**: Use repository-specific task list IDs to avoid cross-project contamination: +```bash +# ❌ BAD: Generic ID used across multiple repos +export CLAUDE_CODE_TASK_LIST_ID="my-project" + +# βœ… GOOD: Repo-specific with context +export CLAUDE_CODE_TASK_LIST_ID="mycompany-api-auth-refactor" +``` + +--- + +## Integration: TDD + Task Management + +Combine Test-Driven Development with task tracking for systematic test coverage. + +### Pattern: Test-First Task Execution + +```bash +export CLAUDE_CODE_TASK_LIST_ID="tdd-feature-x" +claude + +# Create tasks with test-first approach +> "Create task hierarchy for feature X: + + For each feature component: + 1. Task: 'Write failing tests for [component]' + 2. Task: 'Implement [component] to pass tests' (depends on #1) + 3. Task: 'Refactor [component]' (depends on #2) + + Use TDD red-green-refactor cycle per task." +``` + +### Example: Login Feature with TDD + +```bash +# Phase 1: Red (failing tests) +TaskCreate: { + title: "Write failing tests for login endpoint", + description: "Test cases: valid credentials, invalid password, user not found, rate limiting", + status: "pending" +} + +# Execute test writing +> "Implement task-login-tests, ensure all tests fail initially" + +# Phase 2: Green (minimal implementation) +TaskCreate: { + title: "Implement login endpoint (minimal)", + description: "Make tests pass with simplest possible implementation", + dependencies: ["task-login-tests"], + status: "pending" +} + +# Phase 3: Refactor +TaskCreate: { + title: "Refactor login endpoint", + description: "Optimize, remove duplication, improve readability", + dependencies: ["task-login-impl"], + status: "pending" +} +``` + +**Full workflow reference**: See [TDD with Claude](tdd-with-claude.md#task-management-integration) + +--- + +## Integration: Plan-Driven + Task Management + +Convert strategic plans into executable task hierarchies. + +### Pattern: Plan-to-Tasks Transformation + +```bash +# Step 1: Enter plan mode +claude +> "Shift+TabΓ—2" # Enter plan mode + +# Step 2: Create architectural plan +> "Design architecture for microservices migration: + - Identify service boundaries + - Plan data migration strategy + - Design API contracts" + +# Step 3: Exit plan mode with task creation +> "Convert this plan into a task hierarchy using TaskCreate" +``` + +### Example: Microservices Migration + +**Plan output:** +``` +Phase 1: Analysis (Week 1) +- Map monolith dependencies +- Identify bounded contexts +- Design service boundaries + +Phase 2: Infrastructure (Week 2) +- Set up service templates +- Configure API gateway +- Establish monitoring + +Phase 3: Migration (Week 3-6) +- Extract user service +- Extract order service +- Migrate database schemas +``` + +**Tasks transformation:** +```bash +TaskCreate: { + title: "Microservices migration", + children: [ + { + title: "Phase 1: Analysis", + children: [ + {title: "Map monolith dependencies", priority: "critical"}, + {title: "Identify bounded contexts", dependencies: ["map-deps"]}, + {title: "Design service boundaries", dependencies: ["bounded-contexts"]} + ] + }, + { + title: "Phase 2: Infrastructure", + dependencies: ["phase-1"], + children: [ + {title: "Set up service templates"}, + {title: "Configure API gateway", dependencies: ["templates"]}, + {title: "Establish monitoring"} + ] + } + // ... Phase 3 + ] +} +``` + +**Full workflow reference**: See [Plan-Driven Development](plan-driven.md#task-hierarchy-design) + +--- + +## TodoWrite Migration Guide + +### When to Migrate + +**Stay with TodoWrite if:** +- βœ… All work completes in a single session +- βœ… No multi-agent coordination needed +- βœ… Simple linear task lists (no dependencies) +- βœ… Using Claude Code < v2.1.16 + +**Migrate to Tasks API if:** +- βœ… Work spans multiple sessions +- βœ… Need task persistence across days/weeks +- βœ… Complex dependency graphs +- βœ… Multi-terminal collaboration +- βœ… Want to resume after context compaction + +### Migration Steps + +#### Step 1: Identify TodoWrite Usage + +```bash +# Find existing TodoWrite usage in your CLAUDE.md or workflows +grep -r "TodoWrite" .claude/ +``` + +#### Step 2: Convert TodoWrite Lists to Tasks + +**Before (TodoWrite):** +```markdown +- [ ] Implement user authentication +- [ ] Add password hashing +- [ ] Create session management +- [ ] Write tests +``` + +**After (Tasks API):** +```bash +export CLAUDE_CODE_TASK_LIST_ID="user-auth-2026" +claude + +> "Create tasks: + 1. 'Implement user authentication' (parent) + - Child: 'Add password hashing' + - Child: 'Create session management' (depends on hashing) + - Child: 'Write tests' (depends on auth, hashing, sessions)" +``` + +#### Step 3: Update CLAUDE.md Instructions + +**Before:** +```markdown +For complex tasks: +- Use TodoWrite to create task list +- Execute tasks sequentially +``` + +**After:** +```markdown +For complex tasks: +- Set CLAUDE_CODE_TASK_LIST_ID= +- Use TaskCreate for hierarchical planning +- Execute with TaskUpdate status tracking +- Resume with TaskList in new sessions +``` + +#### Step 4: Test Migration + +```bash +# Create test task list +export CLAUDE_CODE_TASK_LIST_ID="migration-test" +claude + +> "Create 3 test tasks with dependencies, mark one completed, then exit" + +# Relaunch in new session +export CLAUDE_CODE_TASK_LIST_ID="migration-test" +claude + +> "TaskList - verify tasks persisted correctly" + +# Expected: See all 3 tasks with correct states +``` + +--- + +## Patterns & Anti-Patterns + +### βœ… Good Patterns + +#### 1. Hierarchical Task Decomposition + +```bash +Project (parent) +└── Feature A (child of project) + β”œβ”€β”€ Component A1 (child of Feature A) + β”‚ β”œβ”€β”€ Implementation (leaf task) + β”‚ └── Tests (leaf task, depends on Implementation) + └── Component A2 + └── ... +``` + +**Why it works**: Mirrors natural project structure, makes dependencies explicit + +#### 2. Dependency-First Ordering + +```bash +# Always define dependencies when creating tasks +TaskCreate: { + title: "Deploy to production", + dependencies: ["run-tests", "code-review", "backup-database"], + metadata: {blocking_reason: "Safety checks required"} +} +``` + +**Why it works**: Prevents premature execution, enforces quality gates + +#### 3. Granular Status Updates + +```bash +# Bad: Large task marked completed without intermediate updates +TaskCreate: {title: "Build entire auth system"} +# ... hours later ... +TaskUpdate: {id: "auth-system", status: "completed"} + +# Good: Frequent status updates as work progresses +TaskUpdate: {id: "auth-system", status: "in_progress", progress: "25%"} +TaskUpdate: {id: "auth-system", status: "in_progress", progress: "50%"} +TaskUpdate: {id: "auth-system", status: "in_progress", progress: "75%"} +TaskUpdate: {id: "auth-system", status: "completed"} +``` + +**Why it works**: Provides visibility, enables context-aware resumption + +#### 4. Metadata-Rich Tasks + +```bash +TaskCreate: { + title: "Optimize database queries", + description: "Reduce query time for user dashboard from 2s to <200ms", + metadata: { + priority: "high", + estimated_duration: "3h", + related_files: ["src/db/queries.ts", "src/db/indexes.sql"], + performance_baseline: "2000ms", + performance_target: "200ms", + related_issue: "https://github.com/org/repo/issues/123" + } +} +``` + +**Why it works**: Context-rich resumption, easier delegation, better documentation + +### ❌ Anti-Patterns + +#### 1. Monolithic Tasks (>10 steps) + +```bash +# ❌ BAD: Task too large, hard to track progress +TaskCreate: { + title: "Implement entire payment system", + description: "Stripe integration, webhooks, refunds, disputes, reporting, admin UI, ..." +} + +# βœ… GOOD: Break into phases +TaskCreate: { + title: "Payment system - Phase 1: Core integration", + children: [ + {title: "Stripe SDK setup"}, + {title: "Payment intent creation"}, + {title: "Webhook handling"} + ] +} +``` + +#### 2. Missing Dependencies + +```bash +# ❌ BAD: Tasks can execute in wrong order +TaskCreate: {title: "Deploy to production"} # No dependencies +TaskCreate: {title: "Write tests"} # No dependencies + +# βœ… GOOD: Explicit ordering +TaskCreate: { + title: "Deploy to production", + dependencies: ["write-tests", "run-tests", "code-review"] +} +``` + +#### 3. Orphan Tasks Without Context + +```bash +# ❌ BAD: Future you won't remember what this means +TaskCreate: { + title: "Fix the bug", + description: "That one from yesterday" +} + +# βœ… GOOD: Self-contained context +TaskCreate: { + title: "Fix login timeout on Safari", + description: "Users on Safari 17.2+ experience session timeout after 5min. Expected: 30min timeout. Root cause: cookie SameSite=Strict not supported.", + metadata: { + browser: "Safari 17.2+", + error_message: "Session expired", + related_commit: "a1b2c3d", + slack_thread: "https://slack.com/archives/C123/p456" + } +} +``` + +#### 4. Status Mismatch + +```bash +# ❌ BAD: Task marked completed but tests fail +TaskUpdate: {id: "login-feature", status: "completed"} +# Tests run later: 3 failures + +# βœ… GOOD: Validation before completion +> "Run tests for login feature" +# If tests pass: +TaskUpdate: {id: "login-feature", status: "completed", metadata: {test_results: "pass"}} +# If tests fail: +TaskUpdate: {id: "login-feature", status: "failed", metadata: {test_results: "3 failures", error_log: "..."}} +``` + +--- + +## Troubleshooting + +### Q: Tasks don't persist across sessions + +**Symptom**: `TaskList` shows empty after restarting Claude + +**Solution**: +```bash +# Ensure CLAUDE_CODE_TASK_LIST_ID is set before launching +export CLAUDE_CODE_TASK_LIST_ID="your-project-name" +claude + +# Verify storage directory exists +ls ~/.claude/tasks/your-project-name/ +``` + +### Q: Multiple projects sharing task lists + +**Symptom**: Seeing tasks from Project A when working on Project B + +**Cause**: Using same task list ID across different repositories + +**Solution**: +```bash +# Use repo-specific IDs with context +cd ~/projects/api +export CLAUDE_CODE_TASK_LIST_ID="api-v2-migration" +claude + +cd ~/projects/frontend +export CLAUDE_CODE_TASK_LIST_ID="frontend-redesign" +claude +``` + +### Q: TodoWrite still used instead of Tasks API + +**Symptom**: Tasks not persisting even with task list ID set + +**Cause**: `CLAUDE_CODE_ENABLE_TASKS=false` set in environment + +**Solution**: +```bash +# Check environment +env | grep CLAUDE_CODE_ENABLE_TASKS + +# Unset if present +unset CLAUDE_CODE_ENABLE_TASKS + +# Or explicitly enable (v2.1.19+ defaults to enabled) +export CLAUDE_CODE_ENABLE_TASKS=true +``` + +### Q: Task dependencies not enforced + +**Symptom**: Claude executes blocked tasks before dependencies complete + +**Cause**: Dependencies not properly defined in TaskCreate + +**Solution**: +```bash +# Ensure dependencies use correct task IDs +TaskCreate: { + title: "Task B", + dependencies: ["task-a-id"], # βœ… Use actual task ID + # NOT dependencies: ["Task A"] # ❌ Task title won't work +} + +# Verify dependencies: +TaskGet task-b-id +# Should show: "blockedBy": ["task-a-id"] +``` + +--- + +## Advanced: Custom Task Metadata + +Extend tasks with domain-specific metadata for enhanced workflows. + +### Metadata Conventions + +**Performance optimization tasks:** +```json +{ + "metadata": { + "type": "performance", + "baseline_metric": "2000ms", + "target_metric": "200ms", + "profiling_tool": "Chrome DevTools", + "measurement_location": "dashboard load time" + } +} +``` + +**Security tasks:** +```json +{ + "metadata": { + "type": "security", + "severity": "critical", + "cve_id": "CVE-2024-1234", + "affected_versions": "< 2.1.0", + "mitigation": "Update package X to v3.0+" + } +} +``` + +**Bug fix tasks:** +```json +{ + "metadata": { + "type": "bugfix", + "issue_url": "https://github.com/org/repo/issues/456", + "reported_by": "user@example.com", + "reproduction_steps": "1. Login 2. Navigate to dashboard 3. Click export", + "error_message": "TypeError: Cannot read property 'map' of undefined" + } +} +``` + +### Querying by Metadata + +```bash +# Filter tasks by type (requires scripting, not built-in) +TaskList | jq '.tasks[] | select(.metadata.type == "security")' + +# Find high-priority pending tasks +TaskList | jq '.tasks[] | select(.metadata.priority == "high" and .status == "pending")' +``` + +--- + +## Related Workflows + +- **[TDD with Claude](tdd-with-claude.md)** - Test-first development with task tracking +- **[Plan-Driven Development](plan-driven.md)** - Strategic planning to task hierarchies +- **[Iterative Refinement](iterative-refinement.md)** - Incremental improvements with tasks +- **[Exploration Workflow](exploration-workflow.md)** - Discovery phase before task creation + +--- + +## Reference + +**Tool documentation**: See [Ultimate Guide Section 5.X](../ultimate-guide.md#5x-task-management-system) + +**Sources:** +- Official: [Claude Code CHANGELOG v2.1.16](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) +- Official: [System Prompts - TaskCreate](https://github.com/Piebald-AI/claude-code-system-prompts) +- Community: [paddo.dev - From Beads to Tasks](https://paddo.dev/blog/from-beads-to-tasks/) +- Community: [llbbl.blog - Two Changes in Claude Code](https://llbbl.blog/2026/01/25/two-changes-in-claude-code.html) + +**Version tracking**: This workflow documents Claude Code v2.1.16+ (released 2026-01-22). Verify latest changes in [claude-code-releases.yaml](../../machine-readable/claude-code-releases.yaml). \ No newline at end of file diff --git a/guide/workflows/tdd-with-claude.md b/guide/workflows/tdd-with-claude.md index e7724ad..1c57146 100644 --- a/guide/workflows/tdd-with-claude.md +++ b/guide/workflows/tdd-with-claude.md @@ -302,3 +302,4 @@ Run tests after each change to ensure they stay green. - [Tight Feedback Loops](../ultimate-guide.md) β€” Section 9.5 - [examples/skills/tdd-workflow.md](../../examples/skills/tdd-workflow.md) β€” TDD skill template - [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) +- [task-management.md](./task-management.md) β€” Track TDD cycles across sessions with Tasks API diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml index 88e0dbb..41df882 100644 --- a/machine-readable/reference.yaml +++ b/machine-readable/reference.yaml @@ -115,6 +115,37 @@ deep_dive: semantic_anchors: 2872 semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md" memory_files: 3160 + # Task Management System (v2.1.16+) - Added 2026-01-26 + task_management_system: 3127 + task_management_comparison: 3140 + tasks_api_overview: 3150 + tasks_api_tools: 3160 + tasks_api_capabilities: 3170 + tasks_api_configuration: 3180 + tasks_api_schema: 3195 + tasks_api_when_to_use: 3210 + todowrite_legacy: 3220 + todowrite_when_to_use: 3230 + todowrite_migration_flag: 3240 + task_best_practices: 3250 + task_hierarchy_design: 3252 + task_dependency_management: 3256 + task_status_transitions: 3260 + task_metadata_conventions: 3264 + task_complete_workflow: 3270 + task_sources: 3280 + # Task Management Workflow (guide/workflows/task-management.md) + workflows_task_management: "guide/workflows/task-management.md" + task_workflow_overview: "guide/workflows/task-management.md:15" + task_workflow_planning: "guide/workflows/task-management.md:48" + task_workflow_execution: "guide/workflows/task-management.md:160" + task_workflow_session_mgmt: "guide/workflows/task-management.md:260" + task_workflow_tdd_integration: "guide/workflows/task-management.md:370" + task_workflow_plan_integration: "guide/workflows/task-management.md:440" + task_workflow_migration: "guide/workflows/task-management.md:510" + task_workflow_patterns: "guide/workflows/task-management.md:620" + task_workflow_troubleshooting: "guide/workflows/task-management.md:740" + task_workflow_advanced: "guide/workflows/task-management.md:820" claude_folder: 3413 settings: 3464 precedence_rules: 3686 @@ -354,7 +385,8 @@ deep_dive: # ════════════════════════════════════════════════════════════════ decide: simple_task: "just ask Claude" - complex_task: "/plan first, then TodoWrite" + complex_task: "/plan first, then use Tasks API (v2.1.16+) or TodoWrite" + complex_task_multi_session: "use Tasks API with CLAUDE_CODE_TASK_LIST_ID" context_high: "/compact (>70%) or /clear (>90%)" repeating: "create agent or command" need_docs: "Context7 MCP"