-
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.
-
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.
-
Pick next task: run backend op next with the plugin's project-root
pointer. Use exactly this invocation:
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.
-
Load plan step: search for the matching task ID in this priority
order, halting only after all three fail:
docs/superpowers/plans/*.md (the superpowers GENERATE default output).taskmaster/docs/plan.md (the prd-taskmaster HANDOFF default output,
whose path is also recorded in
pipeline.json:phase_evidence.HANDOFF.plan_file_path)- 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.)
-
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.
-
Set in-progress: run backend op set-status from the current project
root:
python3 script.py set-status --id <N> --status in-progress
This flip is
observable by watchers and anchors the iteration in TaskMaster itself.
-
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.
-
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>). If still
blocked, set status=blocked, inbox parent, halt this iteration.
Do NOT invent new status values. The four above are the only terminal
returns. Any other string from the subagent is a protocol violation and
should be logged + treated as BLOCKED.
-
Triple verification — the plugin's core quality gate, per spec §11.4.
Three independent checks must agree.
Hard exit-code gate (MANDATORY — bypasses agreement count). Before
invoking the three checkers, run .atlas-ai/ship-check.py --dry-run. If
it reports any non-zero Exit status N in evidence files, the task
FAILS regardless of how the agent narratives read. SHIP_CHECK_FAIL is
NOT a warning. Narrative claiming the exit code is "expected" or
"infrastructure noise" does NOT override this gate — write a separate
task-fix-N to address the underlying failure instead. There is NO
override path; Gate 5 is unfakable. (Codified 2026-06-04 after T12
in ai-human-tasker was marked DONE while pnpm test exited 1 with 11
failing tests.)
9b. Reachability sweep (MANDATORY for wired/live tasks). After the
hard exit-code gate passes, run the reachability sweep for this task:
python3 script.py reachability-sweep \
--task <task_id> \
--start-commit <task_start_sha>
This command:
- Inspects every source module added between
$task_start_sha and HEAD.
- Computes a per-task verdict:
WIRED, EXEMPT, ORPHAN, or ERROR.
- Writes the verdict dict into the task's CDD card
.atlas-ai/cdd/task-<id>.json under the "reachability" key (atomic,
additive — existing card keys are preserved).
The sweep exit code encodes the verdict:
exit 0 → WIRED or EXEMPT (pass; proceed to the three checkers).exit 1 → ORPHAN or ERROR (see step 10 for the auto-downgrade path).
For spike/domain-model tasks the sweep returns EXEMPT automatically (no
importer search is performed for those tiers).
Why sweep before the triple check? A green test on a module
imported by nothing is not "done" — it is scaffolded. The triple check
can pass for an ORPHAN module (all tests pass; doubt and validate agree).
The reachability gate closes that gap: done means the module is
reachable from real production callsites, not just reachable from tests.
Wire it or it ships as scaffold.
The three checks (run only if the hard gate AND the reachability sweep both pass):
- Plugin-native check: evidence file count vs declared subtask count
(from the CDD card in step 5). Missing evidence = fail.
-
Mark done + propagate state — branch on the sweep verdict from step 9b:
WIRED or EXEMPT (sweep exit 0) → proceed normally:
a. Run backend op set-status for the parent task. Because the sweep
already wrote the reachability block into the CDD card, the
set-status CLI auto-reads it — no --reachability flag needed:
python3 script.py set-status --id <N> --status done
If you want to be explicit (e.g. for logging), you may pass:
--reachability WIRED or --reachability EXEMPT.
b. Subtask writeback: for each subtask S in task.subtasks whose
evidence file (per the CDD card from step 5) exists, run
python3 script.py set-status --id <N>.<S> --status done. Subtasks left
pending while the parent is done are a data-integrity violation
that breaks any tool computing progress from subtask state.
(Codified 2026-06-04 — yesterday's run left all 39 subtasks
pending despite 13/13 parent tasks done.)
c. Update .atlas-ai/state/pipeline.json per-task: call
mcp__plugin_prd_go__update_pipeline_task_status(task_id=<N>, status="done") if the MCP tool is available. If not, fall back to
atomic read-modify-write using the pattern in
mcp-server/pipeline.py:locked_update() — read, append <N> to
phase_evidence.EXECUTE.tasks_completed, write to temp, rename.
Never leave pipeline.json and tasks.json mutually inconsistent.
(Codified 2026-06-04 — yesterday's run promised this write in
SKILL.md but never executed it. pipeline.json froze at HANDOFF
transition through all 85 minutes of execution.)
ORPHAN or ERROR (sweep exit 1) → auto-downgrade to scaffold:
Do NOT mark the task done. Instead:
python3 script.py set-status --id <N> --status scaffold
Then:
- Log to
execute-log.jsonl: "reachability_verdict": "ORPHAN" (or
"ERROR"), "auto_downgraded": true, and a plain-English note of
which modules are unwired (from the sweep's list in the
CDD card).
-
Check stepback triggers: if 15 minutes have passed with no task
moving to done, OR 5 consecutive iterations have failed on the same
task class, the recon escalation ladder is MANDATORY. Climb the ladder
in this exact order, not out of order:
/stepback -> /research-before-coding -> /question -> pivot
/stepback — reassess the architectural assumption. Was the plan
wrong?/research-before-coding — feed the blocker into the Perplexity +
Context7 + GitHub pipeline for fresh external context./question — batch-research the unresolved unknowns in parallel.pivot — the plan step itself is unsound; kick the task back to the
plan author (inbox parent with message_type="plan_pivot_requested").
The ladder is append-only — if /stepback surfaces a fix, apply it and
return to step 3. Only climb if the prior rung did not yield progress.
-
Render progress — show the execute progress panel: MCP
render_status(phase="EXECUTE") → print its rendered field; CLI
python3 script.py status --phase EXECUTE. Then emit the atlas-gamify
one-line score (tasks done / tasks total, complexity-weighted). This is the
human-visible progress signal and also feeds the dogfood debrief.
-
Loop: back to step 1 until SHIP_CHECK_OK or a halt condition fires.
