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/<task-id>.json` - `state/tasks/<task-id>.events.jsonl` - `state/tasks/<task-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.