execute-task

# 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.

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.
   - Inject the plugin customisation block at `.atlas-ai/customizations/system-prompt-template.md`
     into the subagent's system prompt. If the file is empty, inject nothing
     and continue.
   - Tier the model by TaskMaster complexity score:
     - `1-4 fast` — use the fast tier (Haiku-class)
     - `5-7 standard` — use the standard tier (Sonnet-class)
     - `8-10 capable` — use the capable tier (Opus-class)
   - Wait for the subagent to return a terminal status: `DONE`,
     `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.

   Rationale: complexity-tiered dispatch keeps the dollars-per-task curve
   sensible. A complexity-2 boilerplate task does not need Opus; a
   complexity-9 architectural task should not be given to Haiku.

8. **Route by status**: the subagent's return status drives the next move.

   - **DONE** — proceed to the spec gate, then the quality gate. If both
     pass, advance to step 9.
   - **DONE_WITH_CONCERNS** — the subagent completed but flagged concerns.
     Address each concern before advancing; re-dispatch if needed.
   - **NEEDS_CONTEXT** — the subagent requested more context. Provide the
     requested context and re-dispatch. Retry cap at 2 — if the subagent
     still returns NEEDS_CONTEXT after two re-dispatches, escalate via the
     recon ladder (step 11).
   - **BLOCKED** — the subagent cannot proceed. Try one model-tier upgrade
     first (e.g. standard -> capable). If still blocked, break the task
     into smaller subtasks via backend op `expand`
     (`python3 script.py expand --id <N>`