Long Task Coordinator

Long Task Coordinator

Keep long-running work recoverable, stateful, and honest.

When to Use This Skill

Use this skill when the work:

• Spans multiple turns or multiple sessions
• Involves handoffs to workers, subagents, or background jobs
• Needs explicit waiting states instead of "still looking" updates
• Must survive interruption and resume from a durable state file

Skip this skill for small, single-turn tasks. Use planning-with-files when simple planning is enough and recovery logic is not the main concern.

Related Skills

• planning-with-files keeps multi-step work organized in files.
• workflow-orchestrator chains follow-up skills after milestones.
• long-task-coordinator makes long-running work resumable, auditable, and safe to hand off.

Core Rules

1. Create one source of truth

For any real long task, maintain one durable state file. Chat history is not a reliable state store.

The state file should capture at least:

• Goal
• Success criteria
• Current status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Active owners or workers

2. Separate roles only when needed

Use the smallest role model that fits the task:

• Origin: owns the goal and acceptance criteria
• Coordinator: owns state, sequencing, and recovery
• Worker: executes bounded sub-work
• Watchdog: checks liveness and recovery only

Simple tasks can collapse these roles into one agent. Long or delegated tasks should make the split explicit.

3. Run every cycle in this order

For each coordination round:

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

Do not report conclusions before the state file has been updated.

4. Treat awaiting-result as a valid state

If a worker or background job was dispatched successfully, the task is not failing just because the result is not back yet.

Valid transitions include:

• running -> awaiting-result
• awaiting-result -> running
• running -> paused
• running -> complete

5. Non-terminal rounds must create real progress

A coordination round is only valid if it does at least one of the following:

• Dispatches bounded work
• Consumes new results
• Updates the current stage or decision
• Persists a new next step or checkpoint
• Performs explicit recovery

If nothing changed, do not pretend the task advanced.

6. Keep recovery separate from domain work

Recovery answers:

• Did execution drift from the saved state?
• Is the expected worker result still pending?
• Do we need to wait, retry, or re-dispatch?

Domain work answers:

• What should we build, analyze, or deliver next?

Recover first, then continue domain work.

Operating Workflow

Step 1: Decide whether the task needs coordination

Use this skill when at least one is true:

• The task will outlive the current turn
• The task will hand off work to another execution unit
• The task needs checkpoints, polling, or scheduled follow-up
• The task has enough complexity that loss of state would be expensive

Step 2: Create or load the state file

Prefer a path that is easy to rediscover, such as:

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

If no durable state exists yet, create one from references/workflow.md.

Step 3: Recover before acting

At the start of every new round: 1. Read the state file 2. Check whether the recorded next step still makes sense 3. Confirm whether any delegated work returned 4. Repair stale assumptions before new action

Step 4: Persist before reporting

After deciding the next action: 1. Update the state file 2. Record new status, owners, blockers, and checkpoint 3. Only then report progress to the user or caller

Step 5: Close the round honestly

End each round with one of these states:

• running
• awaiting-result
• paused
• blocked
• complete

The reported status should match the persisted status exactly.

Output Expectations

When using this skill, produce updates that are grounded in saved state:

• What status the task is in now
• What changed this round
• What is expected next
• What would unblock or complete the task

Acceptance Criteria

Treat the coordination work as complete only when all relevant items below are true:

• A durable state file exists in a predictable path
• The saved status matches the real task state
• Completed work, next action, and blockers are recorded explicitly
• Any delegated work has a named owner and a return condition
• The final report is derived from the persisted state, not from transient reasoning

If the task is not truly complete, end in running, awaiting-result, paused, or blocked rather than pretending the work is done

Anti-Patterns

Avoid:

• Reconstructing progress from memory instead of the state file
• Reporting a conclusion before saving it
• Marking waiting as failure
• Ending a round with no new action and no state change
• Mixing recovery checks with domain decisions in one fuzzy step

References

• references/workflow.md - Detailed workflow, state template, and recovery checklist

Long Task Coordinator Eval Prompts

Use these prompts to smoke-test whether the skill routes to the right behavior and enforces its acceptance criteria.

Prompt 1: Resume interrupted work

We were halfway through a multi-step migration last session. Please resume it safely, and do not rely on chat memory alone.

Expected behavior:

• Recommends or uses long-task-coordinator
• Looks for or creates a durable state file
• Recovers status before proposing new work
• Reports the next step from persisted state

Prompt 2: Delegate and wait honestly

Split this long research task into worker-sized chunks, track who owns what, and tell me if we are waiting rather than pretending it failed.

Expected behavior:

• Introduces explicit ownership or worker tracking
• Uses awaiting-result as a valid state when appropriate
• Records checkpoint and return condition

Prompt 3: Close with acceptance criteria

Before you call this long-running task done, prove that the state is saved and the completion claim is justified.

Expected behavior:

• Checks acceptance criteria explicitly
• Verifies the saved status matches reality
• Confirms completed work, blockers, and next action or completion note are recorded

Long Task Coordinator

Coordinate long-running work with explicit state, recovery rules, and honest status transitions.

What this skill is for

long-task-coordinator is for work that should not depend on chat memory alone. It is useful when:

• A task spans multiple turns or sessions
• Work is delegated to subagents, background jobs, or automation
• The task needs checkpoints, retries, or waiting states
• A user may return later and ask to resume from the last known state

This skill is intentionally abstract and portable. It does not assume any specific business domain, toolchain, or runtime.

Installation

ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.claude/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.codex/skills/long-task-coordinator
ln -s /path/to/agent-playbook/skills/long-task-coordinator ~/.gemini/skills/long-task-coordinator

Core loop

Every coordination round follows the same sequence:

READ -> RECOVER -> DECIDE -> PERSIST -> REPORT -> END

The ordering matters. If you report before you persist, the next round cannot recover reliably.

What gets persisted

At minimum, the state file should record:

• Goal
• Success criteria
• Current status
• Current step
• Completed work
• Next action
• Next checkpoint
• Blockers
• Owners or delegated workers

Valid states

Use explicit status values instead of vague progress messages:

• running
• awaiting-result
• paused
• blocked
• complete

awaiting-result is important. If a worker was dispatched successfully, the task is waiting, not failing.

Acceptance criteria

The skill has done its job when:

• A durable state file was created or updated
• The task status is explicit and truthful
• The next checkpoint is recorded
• Delegated work is tracked with clear ownership
• The progress report matches the persisted state

Good use cases

Example 1: Resumable research

An agent performs research across multiple turns, saving findings and next checkpoints in a shared state file so the work can resume later without reconstructing the thread.

Example 2: Multi-agent delivery

One agent coordinates work, delegates bounded tasks to workers, records owner assignments and return conditions, then resumes when results arrive.

Example 3: Scheduled follow-up

A long-running operational task checks a queue periodically, persists each checkpoint, and reports only from the saved state.

Not the same as other skills

• Use planning-with-files for general file-based planning.
• Use workflow-orchestrator for hook-based skill chaining.
• Use long-task-coordinator when recovery and state transitions are the hard part.

References

• Detailed workflow
• Eval prompts

Long Task Coordinator Reference

Detailed workflow

1. Decide whether coordination is necessary

Use long-task coordination when the task:

• Will outlive the current turn
• Has meaningful risk if chat context is lost
• Depends on delegated work or background execution
• Needs explicit checkpoints or waiting states

If none of those are true, a simpler planning pattern is usually enough.

2. Create a durable state file

Use a path that is easy to rediscover and consistent with the workspace, for example:

• docs/<topic>-execution-plan.md
• docs/<topic>-state.md
• worklog/<topic>-state.md

Recommended template:

# Task State: <topic>

## Goal
<one sentence>

## Success criteria
- <criterion 1>
- <criterion 2>

## Status
running

## Current step
<what is actively happening now>

## Completed
- <completed item>

## Active owners
- Coordinator: <name or role>
- Worker: <name or role, if any>

## Blockers
- <blocker or "None">

## Next action
<next bounded action>

## Next checkpoint
<time, condition, or trigger>

## Notes
- <important recovery detail>

Recovery checklist

Before taking new action:

1. Read the saved state file 2. Confirm the recorded status is still accurate 3. Check whether delegated work has returned 4. Decide whether to continue waiting, retry, re-dispatch, pause, or complete 5. Remove stale assumptions before new work begins

Role model

Origin

Owns the task definition and acceptance criteria.

Coordinator

Owns the state file, sequencing, recovery, and reporting.

Worker

Owns bounded execution work only. A worker should not redefine the task state for the whole system unless explicitly assigned that responsibility.

Watchdog

Owns liveness checks only. It does not make domain decisions.

Meaningful progress test

A non-terminal round must do at least one of the following:

• Dispatch new bounded work
• Consume a returned result
• Update the status or current decision
• Save a new next step or checkpoint
• Perform recovery and correct the state

If none of those happened, the round did not make real progress.

Reporting rule

Always report from the persisted state, not from transient reasoning. A good status update mirrors the saved file:

• Current status
• What changed
• What is next
• What is blocked or waiting

Completion checklist

Use this checklist before closing a task or round:

• [ ] The state file exists and is current
• [ ] The saved status is one of running, awaiting-result, paused, blocked, or complete
• [ ] Completed work is recorded
• [ ] The next action or completion note is recorded
• [ ] Delegated owners and checkpoints are captured where relevant
• [ ] The external report matches the saved state

Portable design principles

• Make facts retrievable from files
• Keep reusable methods in skills
• Keep only stable constraints always-on
• Prefer small, focused reference files over large monoliths