Task Runner Skill

A persistent, daemon-style task queue. Users add tasks at any time. A dispatcher runs on every
heartbeat to check the queue and execute pending work via subagents. Tasks accumulate, complete,
and are archived — the queue itself never closes.

---

Two Operating Modes

This skill has two distinct modes with different triggers and behaviors:

Mode	Trigger	Purpose
INTAKE	User message containing task intent	Parse message → add tasks to queue → confirm → immediately run DISPATCHER
DISPATCHER

After INTAKE (primary) · Heartbeat/cron (backup) | Read queue → dispatch pending tasks → report completions |

Both modes read and write the same persistent queue file.

---

A1 — Triggers

Mode 1: INTAKE (user message)

Activate INTAKE mode when the user's message matches any of the following patterns:

Pattern	Examples
Explicit task add	"add task", "add these tasks", "task:", "new task"
Delegation

"do this for me", "do these for me", "handle these", "can you do X" |
| Framing | "I need you to", "help me with", "I need", "I want you to" |
| List framing | "task list", "my tasks", "queue these", "work on these" |
| Control commands | "skip T-03", "retry T-02", "mark T-01 done", "cancel T-04" |
| Status check | "show tasks", "task status", "what's in the queue", "what are my pending tasks" |
| Compound ask | Any message with 2+ distinct action items (bullets, numbers, "and also", "then") |

Do NOT activate INTAKE for:

• - Pure single-question lookups answered in one sentence ("what time is it?")
• Scheduling-only requests with no actual task ("remind me in 20 min")
• Single web search requests ("google X")
• The heartbeat systemEvent (that's DISPATCHER mode)

Mode 2: DISPATCHER (inline after INTAKE, heartbeat, or cron)

Activate DISPATCHER mode when triggered by:

• - Immediately after INTAKE — runs in the same turn, right after tasks are queued (primary path)
• INLINECODE0 check during a heartbeat poll (backup: catches retries and completions)
• systemEvent: "TASK_RUNNER_DISPATCH: check queue and run pending tasks" (backup)
• Any scheduled/cron trigger registered for task-runner (backup)

---

Configuration

Variable	Location	Default	Description
INLINECODE2	TOOLS.md	INLINECODE3	Directory for queue file and deliverables
INLINECODE4

TOOLS.md | 2 | Max tasks running simultaneously |
| TASK_RUNNER_MAX_RETRIES | TOOLS.md or env | 3 | Max retry attempts before marking blocked |
| TASK_RUNNER_ARCHIVE_DAYS | TOOLS.md | 7 | Days after which done/blocked tasks are archived |

How to configure — add to TOOLS.md:
CODEBLOCK0

Queue file path: ${TASK_RUNNER_DIR}/task-queue.json
(single persistent file, NOT dated — accumulates all tasks over time)

---

A3 — Outputs

Output	Path / Channel	Description
Queue file	INLINECODE12	Single persistent queue; all tasks
Per-task completion message

Chat notification | Sent immediately when a task finishes (done or blocked) |
| Deliverable files | Task-specific paths | Files produced by tasks (when applicable) |
| INTAKE confirmation | Chat | Sent after adding tasks to queue |

---

Mode 1: INTAKE — Step-by-Step

Goal: Convert user message into structured task objects, append to queue, confirm.

Step 0 — First Run Setup (auto-configure on first use)

Run this check before anything else, every INTAKE invocation:

CODEBLOCK1

Idempotency rule: Step 0 only fires on true first run (queue file absent).
It will never double-register the heartbeat entry or create duplicate cron jobs.

---

Step 1 — Load queue

CODEBLOCK2

Step 2 — Parse tasks from message

Split user message into individual tasks using these cues:

• - Numbered lists (1., 2., 3.)
• Bulleted lists (-, *, •)
• Explicit separators ("first", "also", "and then", "next")
• Compound sentences with multiple imperatives
• Single task: entire message is one task

Step 3 — Assign IDs

Continue from lastId in the queue file:

• - If lastId = "T-05", next task is INLINECODE15
• If lastId = null, start at INLINECODE17
• Format: T-NN (zero-padded, minimum 2 digits; expand to 3 when N > 99)

Step 4 — Build task objects

For each parsed task, create a JSON object (schema in references/queue-schema.md):

• - Set id, description, goal, status = "pending", INLINECODE24
• Set retries = 0, maxRetries from config
• Leave execution fields null

Step 5 — Append to queue and save

CODEBLOCK3

Step 6 — Confirm to user

CODEBLOCK4

For multiple tasks:
CODEBLOCK5

Then immediately run DISPATCHER mode (Steps 1–5 below) in the same turn.
Do not exit and wait for the next heartbeat. Tasks must start executing immediately.
The heartbeat/cron dispatcher is a backup for retries and completion checks — not the primary execution path.

Step 7 — Handle control commands

Command	Action
INLINECODE27	Set status = "skipped"; save; confirm
INLINECODE28

Reset status = "pending", retries = 0; save; confirm | | cancel T-NN | Set status = "skipped", blocked_reason = "cancelled by user"; save; confirm | | mark T-NN done | Set status = "done", completed_at = now; save; confirm | | show tasks / task status | Read queue; render status table (see A5 templates) |

---

Mode 2: DISPATCHER — Step-by-Step

Goal: Check queue, dispatch pending tasks, track running tasks, report completions.

Step 1 — Load queue

CODEBLOCK6

Step 2 — Check for work

CODEBLOCK7

Step 3 — Check running tasks for completion

For each task with status = "running":

CODEBLOCK8

Step 4 — Dispatch pending tasks

CODEBLOCK9

Subagent instructions template:
CODEBLOCK10

Step 5 — Save and exit

CODEBLOCK11

If any notifications were sent (done/blocked), this is an active heartbeat response.
If only silent dispatching occurred, this is still a heartbeat response (not HEARTBEAT_OK).
Only return HEARTBEAT_OK when there was truly nothing to do (no pending, no running tasks).

---

A5 — Output Format Templates

INTAKE confirmation (single task)

CODEBLOCK12

INTAKE confirmation (multiple tasks)

CODEBLOCK13

Task status table (on demand)

CODEBLOCK14

Task done notification

CODEBLOCK15

Task blocked notification

CODEBLOCK16

Task skipped

CODEBLOCK17

---

A6 — Heartbeat Integration

Heartbeat and cron setup is automatic. Step 0 of INTAKE mode handles this on first use —
no manual configuration required.

Role of heartbeat/cron (backup only)

Tasks are dispatched immediately after INTAKE — heartbeat and cron are backups only.

The backup dispatcher handles:

• - Retry dispatch: tasks that failed and were reset to pending
• Completion checks: polling running subagent sessions for done/blocked status
• Recovery: tasks that were pending when no user message triggered INTAKE

Users should never need to wait for a heartbeat for a freshly added task.

What gets configured automatically

HEARTBEAT.md entry (injected on first INTAKE):
CODEBLOCK18

Backup cron job (registered on first INTAKE):
CODEBLOCK19

Manual setup (if needed)

If for any reason auto-setup did not run (e.g., queue file was pre-created externally),
delete ${TASK_RUNNER_DIR}/task-queue.json and send any task — Step 0 will fire.

---

A7 — Success Criteria

INTAKE mode succeeds when:

1. 1. All tasks from user message parsed and assigned IDs
2. Tasks appended to queue file (file saved to disk)
3. Confirmation sent to user with task IDs and count
4. DISPATCHER mode triggered immediately in the same turn
5. Subagents spawned for pending tasks before INTAKE turn ends

DISPATCHER mode succeeds when:

1. 1. Queue file read without error
2. All running tasks checked for completion (done/blocked notifications sent as needed)
3. Pending tasks dispatched up to maxConcurrent slots
4. Queue file saved with updated states
5. User notified for every task that reached a terminal state this cycle

Ongoing system health:

• - Queue file is never corrupted (always valid JSON)
• Tasks older than archiveDays days with terminal status are archived/removed
• INLINECODE37 always increments (no ID reuse)
• INLINECODE38 respected before any task is marked blocked

---

Edge Cases

Situation	Behavior
Queue file missing (first run)	Run Step 0 auto-setup: create dir, init queue, register heartbeat + cron; notify user
Queue file missing (manually deleted)

Step 0 re-fires: re-initializes queue; does NOT re-register heartbeat/cron (idempotent check) | | Queue file corrupt/invalid JSON | Log error, notify user, do not overwrite; ask user to inspect | | Task description is ambiguous | Assign unknown type; dispatcher will attempt classification + fallback | | maxConcurrent already reached | Dispatcher skips dispatching; checks again next heartbeat | | User adds task while dispatcher is running | Race-safe: dispatcher reads, processes, writes atomically per cycle | | Task depends on another task's output | Set blocked_reason = "depends on T-NN-1 which is pending/blocked" | | User says "retry T-NN" | Reset to pending, retries = 0, strategies_tried = [] | | All tasks blocked | Notify user: "All tasks are blocked. Review unblock instructions above." | | 20+ tasks added at once | Dispatcher dispatches in batches of maxConcurrent; all tasks eventually run | | Subagent session ID lost | Mark task as pending again; will re-dispatch next cycle | | Archive: done tasks > archiveDays old | Move to ${TASK_RUNNER_DIR}/archive/YYYY-MM.json; remove from main queue |

---

A8 — File Organization

CODEBLOCK20

Queue file schema is documented in references/queue-schema.md.

---

References

• - references/queue-schema.md — Queue JSON format (complete field reference)
• INLINECODE46 — Task type catalog and strategy selection
• INLINECODE47 — Verification logic per task type
• INLINECODE48 — Trigger test cases (positive and negative)