execute-task

Files (1)

• SKILL.md

SKILL.md (first lines)

# execute-task

The execution loop. Three sources converge:

- **Plan** (HOW) — `docs/superpowers/plans/*.md` produced by GENERATE
- **TaskMaster** (WHAT) — `.taskmaster/tasks/tasks.json` with
  dependencies and complexity scores
- **CDD** (PROOF) — acceptance cards per task, evidence-gated

execute-task is the single skill that runs the full build from "tasks are
ready" to SHIP_CHECK_OK. It is autonomous — no AskUserQuestion inside the
loop. Any gap that would require user input is surfaced through the recon
escalation ladder (step 11) or the inbox (steps 4 and 8), never via a modal
prompt.

## Entry

This skill is invoked either:

1. Directly by the user once HANDOFF has completed and a task-execution
   mode (A/B/C) has been dispatched, **or**
2. By the `prd-taskmaster` orchestrator when `current_phase` is `EXECUTE`.

On entry, confirm that:

- `.atlas-ai/state/pipeline.json` exists and records `phase: EXECUTE`
- `.taskmaster/tasks/tasks.json` exists with at least one ready task
- `.atlas-ai/customizations/system-prompt-template.md` is present (may be
  empty — absence is a setup bug, empty is fine)

If any of the above are missing, report the gap and halt. Do NOT attempt to
bootstrap the missing artifact from inside this loop — that is the
orchestrator's job.

## Cycle (per iteration)

Each pass through this cycle moves exactly one TaskMaster task from `pending`
to `done`. Do the 13 steps in order. Do not skip.

> **Task-start SHA** — at the very beginning of each iteration (before step 2),
> capture the current git HEAD:
>
> ```bash
> task_start_sha=$(git rev-parse HEAD)
> ```
>
> Record `$task_start_sha` in the execute-log row for this iteration.  It is the
> oracle of truth for every reachability sweep in step 9b below: "what modules
> did THIS task add?" is `diff $task_start_sha..HEAD`.  The oracle flow already
> issues per-task start commits; this surfaces the same value in the loop prose.

1. **Heartbeat check**: verify the execute-task heartbeat timer is running.
   If missing, register one via `CronCreate("execute-task-heartbeat", "* * * * *", "echo heartbeat")`.
   Abort the iteration if the timer cannot be created — a missing heartbeat
   means a missing stuck-session detector, and that is load-bearing.

2. **Inbox reconciliation**: read `.atlas-ai/state/pipeline.json`,
   `.taskmaster/tasks/tasks.json`, and the current TodoWrite list.
   Diff them. If the three are stale by more than 5 tasks (i.e. TodoWrite
   says 10 done but tasks.json says 3 done), report the diff and halt — do
   not paper over bookkeeping drift by silently reconciling.

3. **Pick next task**: run backend op `next` with the plugin's project-root
   pointer. Use exactly this invocation:

   ```bash
   python3 script.py next-task
   ```

   Parse the JSON result.
   - If no ready tasks and all tasks are `done`, run `.atlas-ai/ship-check.py`,
     emit SHIP_CHECK_OK on success, exit the loop.
   - If no ready tasks but pending tasks exist, the dependency graph is
     deadlocked — report and halt.

4. **Load plan step**: search for the matching task ID in this priority
   order, halting only after all three fail:

   1. `docs/superpowers/plans/*.md` (the superpowers GENERATE default output)
   2. `.taskmaster/docs/plan.md` (the prd-taskmaster HANDOFF default output,
      whose path is also recorded in
      `pipeline.json:phase_evidence.HANDOFF.plan_file_path`)
   3. Any custom path declared in
      `pipeline.json:phase_evidence.HANDOFF.plan_file_path` (in case
      a future handoff variant writes elsewhere)

   If none of the three contains the matching task ID, the task was
   invented downstream of the plan — mark the task `blocked`, inbox the
   parent orchestrator with `message_type="blocker"`, and continue to the
   next iteration.

   (Codified 2026-06-04 — yesterday's ai-human-tasker run had its plan at
   `.taskmaster/docs/plan.md` only, while this step previously read
   `docs/superpowers/plans/*.md` exclusively. The controller silently
   improvised; a cold-start successor would have hit the `blocked` path on
   every task.)

5. **Generate CDD card**: convert the task's `subtasks` field into a
   `testing_plan`. Each subtask becomes a verifiable check with a concrete
   evidence path (file, command output, or test name). Write the card to
   `.atlas-ai/cdd/task-<id>.json`. A task without subtasks is treated as a
   single RED card.

6. **Set in-progress**: run backend op `set-status` from the current project
   root:

   ```bash
   python3 script.py set-status --id <N> --status in-progress
   ```

   This flip is
   observable by watchers and anchors the iteration in TaskMaster itself.

7. **Dispatch implementer subagent** — NEVER in-session. The controller
   must:

   - Provide the FULL task text to the subagent. Never tell the subagent to
     "read tasks.json" — per spec §12, the controller serialises the task
     into the dispatch prompt.

From anombyte93/prd-taskmaster, MIT.

More from anombyte93/prd-taskmaster