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
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
:
'
Discoveries (
${
new
Date
(
)
.
toISOString
(
)
.
split
(
'T'
)
[
0
]
}
)
- Found: ,
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
:
BLOCKED (
${
new
Date
(
)
.
toISOString
(
)
.
split
(
'T'
)
[
0
]
}
)
- Blocker: ,
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
Scope
Acceptance Criteria
- [ ]
- [ ]
, 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 :
Completed (
${
new
Date
(
)
.
toISOString
(
)
.
split
(
'T'
)
[
0
]
}
)
- Summary:
- Tests:
,
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
:
Session Paused (
${
new
Date
(
)
.
toISOString
(
)
.
split
(
'T'
)
[
0
]
}
)
- Progress:
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