durable-task-runner

Use this skill to run long work with durable state and deliberate recovery, not like a goldfish.

Core stance

Act as the planner and verifier. Do not rely on conversational memory for active long-running work. Persist the working state to disk early and keep it updated.

Prefer this skill when any of these are true:

• duration will likely exceed a few minutes
• the task has multiple milestones or checkpoints
• the user wants progress reporting without repeated permission prompts
• interruption or reset would be costly
• work may need pause / stop / steer controls
• verification matters before calling the task done

Do not use it for trivial one-shot tasks.

Required baseline

Before substantial execution:

1. create a task snapshot with scripts/task_ctl.py create
2. record milestones, done criteria, constraints, execution priority, and next step
3. keep updates flowing through the helper scripts instead of hand-editing state where practical

Durable task files live under:

• state/tasks/\x3Ctask-id>.json
• state/tasks/\x3Ctask-id>.events.jsonl
• state/tasks/\x3Ctask-id>.progress.log

Required behavior

1. Plan first

Create the durable task before real work starts. At minimum capture:

• goal
• done criteria
• constraints
• desired state
• execution priority (time or tokens)
• phase
• milestones
• next step
• reporting cadence

2. Work in bounded slices

Prefer:

• scan -> checkpoint
• extract -> checkpoint
• execute -> checkpoint
• verify -> checkpoint

Each meaningful slice should end with a progress/event update.

3. Report progress without permission theater

For active long work, send informational progress updates:

• on milestone completion
• on phase change
• on blocker/retry/pause/stop/completion
• periodically for longer runs

Do not ask for permission to keep going unless the next action is risky, destructive, external, or ambiguous.

4. Respect control state

If the user pauses, stops, or steers the task:

• record it in durable state/event history
• checkpoint safely
• resume only when the durable state says to

5. Resume deliberately

After interruption or reset:

• prefer the explicit user-facing recovery move: "continue this"
• use scripts/task_continue.py to select the most relevant durable task and resume it intelligently
• review recent events and verify the last concrete step before any non-trivial follow-through
• use scripts/task_resume_bootstrap.py for restart analysis when you need to inspect the decision surface directly
• use scripts/task_resume_apply.py only for clearly low-risk follow-through

The intended model is smart resume after reset, not endless ambient scheduler theater. By default, bootstrap should prefer asking whether to continue after reset/interruption; explicit user intent like "continue this" is what should flip the task back into active execution.

6. Verify before completion

Before marking a task complete:

• verify outputs or milestone results
• record a verification event
• then update desired_state=completed

Worker-lane model

Use worker lanes only when parallelism is worth the added control surface.

Default roles:

• main agent = planner/verifier
• worker lanes = bounded workers

When using worker lanes:

• keep each worker scope narrow
• avoid overlapping write targets unless coordination is explicit
• require structured worker returns
• run dropped-line checks before ending the turn

Read references/subagent-return-protocol.md when using worker lanes.

What to read next

Read only what the current task needs:

• references/quickstart.md — minimal end-to-end usage pattern
• references/task-schema.md — snapshot/event structure
• references/control-levels.md — how much process the task earns
• references/subagent-return-protocol.md — worker return rules

Key scripts

Use these directly:

• scripts/task_ctl.py — create/update/show/progress/event/control durable tasks
• scripts/task_continue.py — smart user-facing "continue this" recovery after reset/interruption
• scripts/task_resume_bootstrap.py — analyze resumability after interruption
• scripts/task_resume_apply.py — apply low-risk resume follow-through
• scripts/task_reconcile.py — reconcile pending/idempotent action state
• scripts/task_subagent_ctl.py — manage worker-line state and structured returns
• scripts/task_subagent_run.py — prepare a ready-to-use worker payload
• scripts/task_report.py / scripts/task_ticker.py — render compact status
• scripts/task_tick_all.py — run optional due status delivery across eligible running tasks
• scripts/task_install_tick_cron.sh — optional helper to print/install a current-user cron entry for recurring ticks

Attribution discipline

Keep attribution explicit when ideas or adapted structures come from other skills. If you borrow more than general inspiration, update ATTRIBUTION.md and note it near the relevant file.