Task Management Protocol

Task Management Protocol

Standardized protocol for task synchronization, progress tracking, and context handoff between agents and sessions using Claude Code's native task tools.

Problem Statement

Background agents complete work but main sessions don't receive notifications. Agents don't update task descriptions with findings. No protocol exists for structured context handoff between agents or sessions.

This skill solves:

1. Lost context when sessions end or agents complete
2. Background agent findings not surfacing to main session
3. Duplicate work due to poor task visibility
4. No structured way to pass information between agents

Core Tools Reference

Plan File Update Protocol (IRON LAW)

When a task is part of a plan file (.claude/context/plans/*.md), the executing agent — NOT the router — is responsible for updating task markers.

On task start: Find the task line in the plan file and change - [ ] to - [~].

On task complete: Change - [~] to - [x] and append a one-line result note.

Tool: Use Edit on the specific line — do NOT rewrite the whole file.

Timing: Update the plan file BEFORE calling TaskUpdate(completed).

Silence: If the plan file does not exist, skip silently — do not error.

# Find the line number
grep -n "task subject keywords" .claude/context/plans/my-plan.md

# Then use Edit to change [ ] → [~] on start, [~] → [x] on complete

Anti-pattern: Leaving plan file updates to the router. The router only sees completed tasks — plan files must be updated live during execution.

The Protocol

Phase 1: Session Start (MANDATORY)

Before doing ANY work, execute this sequence:

// Step 1: Check existing tasks
TaskList();

// Step 2: If assigned task exists, read full details
TaskGet({ taskId: '<assigned-id>' });

// Step 3: Claim the task
TaskUpdate({
  taskId: '<assigned-id>',
  status: 'in_progress',
  activeForm: 'Working on <task-subject>',
});

Why this matters:

• Prevents duplicate work (see what's already in progress)
• Gets full context from task description
• Signals to other agents/sessions that work has started

Phase 2: During Work (Progress Updates)

Update tasks when you:

• Discover important information
• Find blockers
• Identify subtasks
• Make significant progress

Discovery Update Pattern

// When you discover something important
TaskUpdate({
  taskId: 'X',
  description: `ORIGINAL: <original-description>

## Discoveries (${new Date().toISOString().split('T')[0]})
- Found: <what you discovered>
- Files: <relevant files>
- Impact: <why this matters>`,
  metadata: {
    discoveredFiles: ['path/to/file1.ts', 'path/to/file2.ts'],
    discoveries: ['Pattern X found', 'Dependency Y required'],
    lastUpdated: new Date().toISOString(),
  },
});

Blocker Update Pattern

// When you hit a blocker
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## BLOCKED (${new Date().toISOString().split('T')[0]})
- Blocker: <what's blocking>
- Needs: <what's required to unblock>
- Workaround: <possible workaround if any>`,
  metadata: {
    status: 'blocked',
    blocker: 'Description of blocker',
    blockerType: 'dependency|permission|information|external',
    needsFrom: 'user|other-agent|external-system',
  },
});

Subtask Creation Pattern

// When you discover subtasks
TaskCreate({
  subject: 'Subtask: <specific-task>',
  description: `Parent: Task #X

## Context
<why this subtask exists>

## Scope
<specific work to be done>

## Acceptance Criteria
- [ ] <criterion 1>
- [ ] <criterion 2>`,
  activeForm: 'Working on <subtask>',
});

// Link to parent
TaskUpdate({
  taskId: '<new-subtask-id>',
  addBlockedBy: ['X'], // This subtask blocks parent completion
});

Phase 3: Completion (MANDATORY)

Never mark a task complete without structured metadata:

TaskUpdate({
  taskId: 'X',
  status: 'completed',
  description: `<original-description>

## Completed (${new Date().toISOString().split('T')[0]})
- Summary: <one-line summary of what was done>
- Files modified: <list>
- Tests: <passed/added/none>`,
  metadata: {
    summary: 'Concise summary of completed work',
    filesModified: ['path/to/file1.ts', 'path/to/file2.ts'],
    filesCreated: ['path/to/new.ts'],
    testsAdded: true,
    testsPassing: true,
    outputArtifacts: ['.claude/context/reports/backend/my-report.md'],
    nextSteps: ['Optional follow-up', 'Another consideration'],
    completedAt: new Date().toISOString(),
  },
});

// Check for newly unblocked tasks
TaskList();

Phase 4: Session End / Handoff

Before ending a session with incomplete work:

// Update all in-progress tasks with current state
TaskUpdate({
  taskId: 'X',
  description: `<existing-description>

## Session Paused (${new Date().toISOString().split('T')[0]})
- Progress: <what was accomplished>
- Current state: <where things stand>
- Next step: <immediate next action>
- Files to review: <key files>`,
  metadata: {
    sessionPaused: true,
    progress: '60%',
    currentState: 'Description of current state',
    immediateNextStep: 'The very next thing to do',
    keyFiles: ['file1.ts', 'file2.ts'],
    keyDecisions: ['Decision 1', 'Decision 2'],
    pausedAt: new Date().toISOString(),
  },
});

Context Handoff Structure

Metadata Schema for Handoff

Use this consistent structure for context handoff between agents:

interface TaskHandoffMetadata {
  // Progress tracking
  status?: 'not_started' | 'in_progress' | 'blocked' | 'completed';
  progress?: string; // e.g., "60%", "3/5 steps"

  // Discovery context
  discoveredFiles?: string[];
  discoveries?: string[];
  patterns?: string[];

  // Blocker information
  blocker?: string;
  blockerType?: 'dependency' | 'permission' | 'information' | 'external';
  needsFrom?: string;

  // Completion context
  summary?: string;
  filesModified?: string[];
  filesCreated?: string[];
  outputArtifacts?: string[];

  // Continuation context
  currentState?: string;
  immediateNextStep?: string;
  keyFiles?: string[];
  keyDecisions?: string[];

  // Timestamps
  lastUpdated?: string;
  completedAt?: string;
  pausedAt?: string;
}

Reading Handoff Context

When starting work on a task that another agent worked on:

// Get full task details including metadata
const task = TaskGet({ taskId: 'X' });

// Check metadata for context
if (task.metadata?.sessionPaused) {
  // Previous session paused - read currentState and immediateNextStep
}
if (task.metadata?.discoveries) {
  // Previous agent found things - review discoveries array
}
if (task.metadata?.blocker) {
  // Task was blocked - check if blocker is resolved
}

Cross-Session Coordination

Environment Variable: CLAUDE_CODE_TASK_LIST_ID

Use this environment variable to share task lists across sessions:

# Set shared task list for all sessions
export CLAUDE_CODE_TASK_LIST_ID="my-project-tasks"

# Start claude code - will use shared task list
claude

When to use:

• Multiple terminals working on same project
• Background agents that should share task state
• Team collaboration on task lists

Shared Task List Pattern

// Session A creates task
TaskCreate({
  subject: 'Implement feature X',
  description: '...',
  metadata: {
    owner: 'session-a',
    priority: 'high',
  },
});

// Session B (same CLAUDE_CODE_TASK_LIST_ID) picks up task
TaskList(); // Sees task from Session A
TaskUpdate({
  taskId: '1',
  status: 'in_progress',
  metadata: {
    owner: 'session-b', // Claims ownership
    previousOwner: 'session-a',
  },
});

Iron Laws (MUST FOLLOW)

1. Never Complete Without Summary

// WRONG - No context for future reference
TaskUpdate({ taskId: 'X', status: 'completed' });

// CORRECT - Full context preserved
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Added auth middleware with JWT validation',
    filesModified: ['src/middleware/auth.ts'],
    completedAt: new Date().toISOString(),
  },
});

2. Always Update on Discovery

// WRONG - Discoveries lost
// ... agent finds important pattern but doesn't record it ...

// CORRECT - Discoveries preserved
TaskUpdate({
  taskId: 'X',
  metadata: {
    discoveries: [...existingDiscoveries, 'Found circular dependency in module X'],
  },
});

3. Always TaskList After Completion

// WRONG - May have unblocked other tasks
TaskUpdate({ taskId: "X", status: "completed" });
// ... session ends ...

// CORRECT - Check for follow-up work
TaskUpdate({ taskId: "X", status: "completed", metadata: {...} });
TaskList();  // Find newly unblocked tasks

4. Use Metadata for Structure, Description for Prose

// WRONG - Structured data in prose
TaskUpdate({
  taskId: 'X',
  description: 'Files: a.ts, b.ts. Blocked by: auth issue. Progress: 50%',
});

// CORRECT - Structured metadata + prose description
TaskUpdate({
  taskId: 'X',
  description: 'Implementing auth flow. Hit a blocker with token refresh.',
  metadata: {
    filesModified: ['a.ts', 'b.ts'],
    blocker: 'auth issue',
    progress: '50%',
  },
});

Integration with Memory Protocol

Task metadata complements but does not replace Memory Protocol:

Pattern:

1. Record task-specific context in task metadata
2. Record project-wide learnings in memory files
3. Cross-reference between them

// Task completion with memory reference
TaskUpdate({
  taskId: 'X',
  status: 'completed',
  metadata: {
    summary: 'Implemented auth flow',
    memoryUpdates: ['learnings.md: JWT refresh pattern', 'decisions.md: ADR-005 auth architecture'],
  },
});

Examples

Example 1: Developer Agent Completing Feature

// Start
TaskList();
TaskGet({ taskId: '5' });
TaskUpdate({ taskId: '5', status: 'in_progress', activeForm: 'Implementing login flow' });

// Discovery during work
TaskUpdate({
  taskId: '5',
  metadata: {
    discoveries: ['Existing auth module at src/auth/', 'Uses JWT not sessions'],
    keyFiles: ['src/auth/jwt.ts', 'src/middleware/auth.ts'],
  },
});

// Completion
TaskUpdate({
  taskId: '5',
  status: 'completed',
  metadata: {
    summary: 'Added login endpoint with JWT auth',
    filesCreated: ['src/routes/login.ts', 'src/routes/login.test.ts'],
    filesModified: ['src/routes/index.ts'],
    testsAdded: true,
    testsPassing: true,
    completedAt: new Date().toISOString(),
  },
});
TaskList(); // Check for unblocked tasks

Example 2: Background Agent with Handoff

// Background agent starting long task
TaskUpdate({
  taskId: '10',
  status: 'in_progress',
  metadata: { runningInBackground: true },
});

// Progress update (multiple during execution)
TaskUpdate({
  taskId: '10',
  metadata: {
    progress: '40%',
    currentState: 'Processed 400/1000 files',
    discoveries: ['Found 12 security issues', '3 critical in auth module'],
  },
});

// Completion - main session can check this
TaskUpdate({
  taskId: '10',
  status: 'completed',
  metadata: {
    summary: 'Security scan complete: 12 issues found (3 critical)',
    outputArtifacts: ['.claude/context/reports/security/security-scan.md'],
    criticalFindings: 3,
    highFindings: 5,
    mediumFindings: 4,
    completedAt: new Date().toISOString(),
  },
});

Example 3: Multi-Agent Coordination

// Planner creates tasks with dependencies
TaskCreate({ subject: 'Design auth system', description: '...', activeForm: 'Designing auth' });
TaskCreate({
  subject: 'Implement auth backend',
  description: '...',
  activeForm: 'Implementing auth',
});
TaskCreate({ subject: 'Add auth tests', description: '...', activeForm: 'Testing auth' });

TaskUpdate({ taskId: '2', addBlockedBy: ['1'] }); // Implementation blocked by design
TaskUpdate({ taskId: '3', addBlockedBy: ['2'] }); // Tests blocked by implementation

// Architect completes design
TaskUpdate({
  taskId: '1',
  status: 'completed',
  metadata: {
    summary: 'Auth design complete - JWT with refresh tokens',
    outputArtifacts: ['.claude/context/plans/auth-design.md'],
    keyDecisions: ['JWT over sessions', 'Redis for token store'],
  },
});

// Developer can now start (task 2 unblocked)
TaskList(); // Shows task 2 now available
TaskGet({ taskId: '2' }); // Gets design context from task 1's metadata

Related Skills

• session-handoff - Creates full session handoff documents (use for complex handoffs)
• operational-modes - Self-regulates tool usage during task execution
• thinking-tools - Checkpoints for verifying task completion quality

Iron Laws

1. NEVER mark a task completed without structured metadata (summary, filesModified, completedAt)
2. ALWAYS call TaskUpdate(in_progress) before starting any work — never start without claiming
3. NEVER complete work without calling TaskList() to check for newly unblocked tasks
4. ALWAYS update task metadata with discoveries as they happen, not retrospectively
5. NEVER put structured data in description prose — use the metadata field for machine-readable fields

Anti-Patterns

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New task pattern discovered -> .claude/context/memory/learnings.md
• Issue with task tools -> .claude/context/memory/issues.md
• Decision about task structure -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in task metadata, it didn't happen.