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:

• Lost context when sessions end or agents complete

• Background agent findings not surfacing to main session

• Duplicate work due to poor task visibility

• No structured way to pass information between agents

Core Tools Reference

Tool Purpose When to Use

TaskList()

List all tasks with status Start of work, after completion

TaskGet(id)

Get full task details Before starting assigned task

TaskCreate(...)

Create new task Planning phase, discovered subtasks

TaskUpdate(...)

Update status/metadata Progress, discoveries, completion

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:

Information Type Task Metadata Memory Files

Task-specific discoveries Yes No

Project-wide patterns Reference only Yes (learnings.md)

Architecture decisions Reference only Yes (decisions.md)

Blocking issues Yes Yes (issues.md)

Progress state Yes No

Completion summary Yes Yes (learnings.md)

Pattern:

• Record task-specific context in task metadata

• Record project-wide learnings in memory files

• 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

• NEVER mark a task completed without structured metadata (summary, filesModified, completedAt)

• ALWAYS call TaskUpdate(in_progress) before starting any work — never start without claiming

• NEVER complete work without calling TaskList() to check for newly unblocked tasks

• ALWAYS update task metadata with discoveries as they happen, not retrospectively

• NEVER put structured data in description prose — use the metadata field for machine-readable fields

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

No summary metadata on completion Future agents have no context for continuation Always include summary, filesModified, and completedAt in completion metadata

Skipping in_progress before work Task appears unowned; duplicate work begins Always call TaskUpdate(in_progress) before starting

Not checking TaskList after completion Newly unblocked tasks remain stalled Always call TaskList() after every task completion

Structured data in description prose Cannot be parsed by agents; context lost Use metadata field for structured data, description for narrative

Missing discovery updates Context accumulated during work is lost on session end Update metadata with discoveries as they happen, not retrospectively

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.