Protocol for task synchronization, context handoff, and cross-session coordination using Claude Code task tools. Ensures agents properly update tasks with findings and enables seamless work continuation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Protocol for task synchronization, context handoff, and cross-session coordination using Claude Code task tools. Ensures agents properly update tasks with findings and enables seamless work continuation.
["Always call TaskList() at session start and after completion","Update task descriptions with discoveries as they happen","Use structured metadata for context handoff","Never mark complete without summary metadata","Check for blocked tasks after completing work"]
error_handling
strict
streaming
supported
verified
true
lastVerifiedAt
"2026-02-22T00:00:00.000Z"
source
builtin
trust_score
100
provenance_sha
37f35fa25a789747
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 tasksTaskList();
// Step 2: If assigned task exists, read full detailsTaskGet({ taskId: '<assigned-id>' });
// Step 3: Claim the taskTaskUpdate({
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 importantTaskUpdate({
taskId: 'X',
description: `ORIGINAL: <original-description>
## Discoveries (${newDate().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: newDate().toISOString(),
},
});
Blocker Update Pattern
// When you hit a blockerTaskUpdate({
taskId: 'X',
description: `<existing-description>
## BLOCKED (${newDate().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 subtasksTaskCreate({
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 parentTaskUpdate({
taskId: '<new-subtask-id>',
addBlockedBy: ['X'], // This subtask blocks parent completion
});
Phase 3: Completion (MANDATORY)
Never mark a task complete without structured metadata:
// Update all in-progress tasks with current stateTaskUpdate({
taskId: 'X',
description: `<existing-description>
## Session Paused (${newDate().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: newDate().toISOString(),
},
});
Context Handoff Structure
Metadata Schema for Handoff
Use this consistent structure for context handoff between agents:
When starting work on a task that another agent worked on:
// Get full task details including metadataconst task = TaskGet({ taskId: 'X' });
// Check metadata for contextif (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 sessionsexport 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 taskTaskCreate({
subject: 'Implement feature X',
description: '...',
metadata: {
owner: 'session-a',
priority: 'high',
},
});
// Session B (same CLAUDE_CODE_TASK_LIST_ID) picks up taskTaskList(); // Sees task from Session ATaskUpdate({
taskId: '1',
status: 'in_progress',
metadata: {
owner: 'session-b', // Claims ownershippreviousOwner: 'session-a',
},
});
Iron Laws (MUST FOLLOW)
1. Never Complete Without Summary
// WRONG - No context for future referenceTaskUpdate({ taskId: 'X', status: 'completed' });
// CORRECT - Full context preservedTaskUpdate({
taskId: 'X',
status: 'completed',
metadata: {
summary: 'Added auth middleware with JWT validation',
filesModified: ['src/middleware/auth.ts'],
completedAt: newDate().toISOString(),
},
});
2. Always Update on Discovery
// WRONG - Discoveries lost// ... agent finds important pattern but doesn't record it ...// CORRECT - Discoveries preservedTaskUpdate({
taskId: 'X',
metadata: {
discoveries: [...existingDiscoveries, 'Found circular dependency in module X'],
},
});
3. Always TaskList After Completion
// WRONG - May have unblocked other tasksTaskUpdate({ taskId: "X", status: "completed" });
// ... session ends ...// CORRECT - Check for follow-up workTaskUpdate({ taskId: "X", status: "completed", metadata: {...} });
TaskList(); // Find newly unblocked tasks
4. Use Metadata for Structure, Description for Prose
