run-tasks

Run Tasks (Orchestrator)

Drive a task DAG to completion by dispatching subagents — one task at a time, serial. The orchestrator is intentionally as thin as possible: it does not read task bodies, does not understand what's being built, and does not run code itself. It does exactly three things — pick the next eligible task, dispatch the coder, dispatch the validator — and stops the moment anything looks wrong.

When this skill triggers

Use this skill for any request that boils down to "execute the task DAG." Common phrasings:

• "Run the tasks in plans/<slug>/"
• "Execute the DAG at plans/<slug>/tasks/"
• "Drain the task queue"
• "Start the autonomous coding session"
• "Kick off the autopilot for "

If the user is asking to create the DAG, use task-dag. If they're asking to flesh out skeleton task files, use task-specs. If the task files are still one-line skeletons, refuse to run and tell the user to spec them first — there's nothing for the coder to execute.

Architecture in one paragraph

The filesystem is the source of truth. Each task file's status: frontmatter field is the state machine. The orchestrator re-derives all state by reading the directory on every tick — it holds nothing important in its own context. Coder and validator are isolated subagents (their own context windows) dispatched via the Agent tool. The orchestrator never reads task bodies; only frontmatter. This makes it crash-recoverable (kill the session, re-run, it picks up where it left off) and keeps its context shallow even on long runs.

Workflow

1. Locate the tasks directory

Default: the user passes a path like plans/<slug>/ or plans/<slug>/tasks/. Resolve to the tasks/ directory. If the user didn't pass a path, look in plans/ for the most recent tasks/ directory or ask which one.

Confirm the directory contains:

• An index.md (DAG view)
• One or more T-NNN-*.md task files

If the directory is empty or missing skeleton frontmatter, stop and tell the user — there's no DAG to drive.

2. Confirm before starting

This skill kicks off an autonomous loop that will modify code, run tests, and write to memory. Before the first dispatch, tell the user what you're about to do in one or two sentences — e.g., "About to start the autopilot for plans/team-invitations/. I count 8 pending tasks, longest chain T-001 → T-003 → T-007. I'll stop and surface immediately on any failure or block."

Then proceed. Do not ask permission task-by-task — that defeats the point.

3. Tick loop

Repeat the following until the loop exits:

3a. Re-read state from disk

List every T-*.md file in the tasks directory (ignore index.md). For each, read just enough to parse the YAML frontmatter — id, depends_on, status. Do not read the body. This step happens fresh every tick; do not cache.

3b. Pick one eligible task

A task is eligible if:

• status: pending
• Every ID in depends_on has status: done

If multiple tasks are eligible, pick the one with the lowest id (ascending T-NNN). Determinism makes the loop replayable.

If no tasks are eligible:

• If every task is done: exit with success — report total tasks completed.
• If any task is failed or blocked: exit with that state — surface which task and why.
• Otherwise (mixed pending with unmet deps but no terminal state): something is wrong with the DAG. Surface and stop.

3c. Mark in-progress and dispatch coder

Flip the picked task's frontmatter from status: pending to status: in_progress using the Edit tool. Be exact — status: pending → status: in_progress on the one file.

Dispatch the task-coder subagent via the Agent tool. The dispatch prompt should be minimal and stable across tasks:

Execute the task specified at <absolute path to task file>. Read only that file; do not read sibling task files, the design doc, or the PRD. Follow its acceptance criteria. Return a status of done, failed, or blocked, plus one short sentence of context.

Wait for the subagent to return. (The Agent tool blocks.)

3d. Handle the coder's return

Three possible outcomes:

• done — proceed to validator dispatch (step 3e).
• failed — flip the task's status: to failed, exit the loop, surface the task ID and the coder's one-line reason to the user. Do not retry.
• blocked — flip the task's status: to blocked, exit the loop, surface the task ID and what the coder reported as the blocker.

3e. Dispatch validator (only on coder done)

Dispatch the task-validator subagent via the Agent tool with a minimal stable prompt:

Validate the task at <absolute path to task file>. Read the "Acceptance criteria" section, run every check, and return pass or fail with the failing commands' output if any.

Wait for the return.

• pass — flip the task's status: to done. Continue the loop (back to 3a).
• fail — flip the task's status: to failed. Exit the loop. Surface the failing checks to the user.

4. Exit and surface

When the loop exits, report concisely:

• The terminal state: all done, or stopped on a specific task
• If stopped: which task, in what state (failed / blocked), and the one-line reason
• A pointer to the task file for the user to read if they want details

Example success: "Completed 8/8 tasks for plans/team-invitations/. All done."

Example failure: "Stopped on T-004 (status: failed). Validator reported: acceptance check npm test src/services/invitations.test.ts exited 1. See plans/team-invitations/tasks/T-004-invitations-service.md for the spec."

Hard rules

These are load-bearing — break them and the architecture stops working.

• Never read task bodies. Only frontmatter. The orchestrator must not know what the work is.
• Never modify the body of a task file. Only the status: line.
• Never run code, edit source files, or run tests yourself. Subagents do the work.
• Never retry on failed or blocked. Stop and surface — the human decides what to do next. Autonomous-with-a-tripwire beats autonomous-spinning-on-bad-ground-truth.
• Re-read the directory every tick. Do not cache task state in your own context — your context is finite and the filesystem is the source of truth.
• Serial only. Dispatch one coder, wait, dispatch one validator, wait. No parallel dispatch.

State machine reference

pending ──(dispatch coder)──> in_progress
in_progress ──(coder: done, validator: pass)──> done       [continue loop]
in_progress ──(coder: failed)──────────────────> failed    [stop, surface]
in_progress ──(coder: blocked)─────────────────> blocked   [stop, surface]
in_progress ──(validator: fail)────────────────> failed    [stop, surface]

Terminal states: done, failed, blocked. The orchestrator never moves a task out of a terminal state.

Quality bar

A good run looks like a tight log of dispatches and status flips. The orchestrator's job is to be boring and predictable. Aim for:

• Every tick begins with a fresh filesystem read
• Every state transition is reflected in the task file before the next tick
• Stops are loud and specific (task ID + reason), never silent

Things to avoid:

• Reading task bodies "just to understand" — that's how the orchestrator's context bloats and how it starts second-guessing the subagents
• Heuristics about how to fix a failure — that's the human's call
• Implicit retries (e.g., "let me just try once more") — every retry has to be a human decision so the loop is auditable
• Dispatching the validator before the coder reports done — they are sequential, not concurrent