atlas-plan-execute

Atlas Plan Execute

Use this skill to turn a atlas-plan-handoff artifact into a controlled execution loop.

Prefer finite, stage-based execution over continuous self-critique. The goal is to finish the task with high confidence, not to keep polishing indefinitely.

---

Execution Model

Operate as a bounded state machine: ready → implementing → gating → repairing (self-repair LOCAL, gates pré-handoff) → task_done → validator_handoff_required (or blocked).

repairing cobre exclusivamente falhas de gates locais (lint, analyze, tests, diff-check) introduzidas pelo diff corrente — máximo 2 passes por task. O executor não entra em repairing pós-validação; qualquer repair pós-veredito é de responsabilidade do orquestrador via atlas-findings-repair. Após task_done para todas as tasks da slice, o executor escreve o state file e transita para validator_handoff_required — não existe slice_validating nem slice_done no escopo deste executor.

State persistence

Use atlas_run_state as the primary source of run state. Do not read or write run ledger files directly. If the MCP is unavailable, report the gate as unprovable and abort instead of continuing with a silent file fallback.

Executor liveness checkpoints

Depois de carregar esta skill e antes de qualquer discovery longo, emita um checkpoint MCP:

atlas_lock_dispatch({
  "action": "checkpoint",
  "phase": "plan_execute",
  "event": "executor_started"
})

Em seguida, emita checkpoints materiais conforme avança:

• skill_loaded — skill carregada e contrato reconhecido.
• plan_loaded — plano/PRD de entrada lido.
• handoff_accepted — plan_path, state_path alvo, boundary e tasks aceitos.
• task_started — primeira task começou.
• first_write — primeira mutação de workspace feita.
• state_path_created — state file escrito antes de devolver validator_handoff_required.

Se não conseguir emitir checkpoint por MCP, retorne blocked: liveness não é comprovável. Não fique em discovery/preflight interno sem checkpoint. O orquestrador trata ausência de checkpoint como stalled via Gate G12.

Plan path resolution

Resolve plan paths in this order:

1. .atlas/plans/
2. .cursor/plans/ with a deprecation warning
3. .codex/plans/ with a deprecation warning

New or rewritten plan artifacts must use .atlas/plans/.

Host adapter

This skill is host-agnostic. To resolve any host-specific verb (subagent dispatch, native todo tool, plan paths), call the MCP tool atlas_capabilities first and use the returned descriptor. Canonical reference: packages/orchestrator/references/host-adapters.md. Do not hardcode a host name in reasoning — read it from the descriptor.

Native todo mirror

When entering implementing for the first time in a slice, mirror the plan tasks into the native todo surface named by atlas_capabilities.todo_tool (e.g. TodoWrite on Claude Code, tasks on Codex App). If todo_tool is null, proceed without a mirror — do not invent a tool.

The plan is the SSoT. Map ready to pending, implementing/gating to in_progress, and task_done to completed. If todo state diverges, sync from the plan to todo, never from todo back to the plan. Do not create parallel todos that are not derived from plan task IDs.

Review gate

atlas-slice-review is dispatched only when --review is present in the user command or executor arguments. Without --review, the orchestrator closes the slice upon receiving pass or pass_with_observations from the validator — this executor is not involved in that decision and never observes the validator verdict directly.

Entrada via modo execute (PRD D1/D13)

Esta skill aceita entrada pelo modo execute do orquestrador: um PLAN_*.md pronto de pipeline curta, apontado diretamente e já reverificado na entrada (atlas_verify_artifact + TC) pelo orquestrador. A entrada execute é o mesmo executor, com as mesmas garantias — o contrato não muda: o state file (.atlas/state/<run_id>/<slice>.json) permanece obrigatório e o atlas-task-validator (validador frio, só state_path) permanece obrigatório antes do relatório final. Não há caminho de execução sem state file nem sem validador, em nenhum modo de entrada.

---

Required Workflow

1. Load the plan as an execution contract

First, emit executor_started, then skill_loaded, before doing any long scan.

Read the atlas-plan-handoff artifact. Extract at minimum:

• Execution metadata: Prefix, mode, and validator options.
• Executive translation and PRD links (from Section 1 — include path to PRD; cite PRD §3 D* IDs, do not paste the full D* table).
• Execution invariants (from Section 2).
• Current state at sprint opening (from Section 4 — not Section 2).
• Pitfalls (from Section 3).
• All execution tasks TNN (from Section 5).
• Technical contracts (from Section 6).
• Slices of execution (from Section 7).
• Checklist for the validator (from Section 8).

Treat headings as semantic. If the plan uses equivalent wording but carries the same contract, continue. If the plan is missing the substance, stop and report. The old Gate of Readiness (§15) and Handoff Prompt (§16) are no longer required in the compact template. If optional Section 9 (open questions / real blockers — not PRD §7 Apêndice/Referências) has active blocking items, stop execution and request clarification.

When Section 8 checklist is thin, read PRD §4–6 from the PRD path in the plan header for business acceptance.

After the plan is loaded, emit plan_loaded. After validating the execution boundary and state_path target, emit handoff_accepted.

2. Create a task-scoped execution contract

Before editing code, write a short task contract for the current task only (objective, files, invariants, local checks, and repair budget).

3. Implement in the smallest coherent slice

Do not implement the entire feature before validating anything. Prefer one task at a time. Follow closed decisions from the plan.

Before the first concrete task, emit task_started. After the first workspace mutation, emit first_write.

4. Run a focused quality gate after each task slice

Run only the checks that are relevant to the current diff and task risks (linter, analyze of the affected package, or tests).

5. Repair only what the current diff introduced

If the gate fails, classify the outcome as fixable (maximum 2 repair passes per task) or blocked.

6. Enforce hard stop conditions

Stop repair and move to blocked when budget is exhausted, the same failure repeats twice, or the fix requires reopening closed plan decisions.

7. Close the task with evidence

Mark a task complete and move to the next. Once all tasks are completed, write the state file and transition to validator_handoff_required.

8. Write the state file and hand off to the orchestrator

After all tasks in the current slice are complete, write the state file boundary. The cold validation runs as an isolated sibling dispatched by the orchestrator — never by this executor (see below).

State file boundary

Create .atlas/state/<run_id>/<slice>.json following packages/templates/STATE_FILE_SCHEMA.md:

{
  "run_id": "<run_id>",
  "slice": "<slice id>",
  "tasks": ["T01"],
  "files_changed": ["relative/path.ext"],
  "diff_stat": "N files, +X -Y",
  "plan_path": ".atlas/plans/<id>.plan.md",
  "boundary_refs": ["§2.I1", "§6.1", "§8"],
  "executed_at": "ISO8601",
  "executor_skill": "atlas-plan-execute"
}

Validation is always sibling, on every host. The validator is registered as a real subagent on every host, but this executor never dispatches it and never validates its own work. After tasks and local gates pass and the state file is written, this executor stops mutation and returns validator_handoff_required with the state_path. The orchestrator dispatches atlas-task-validator as the next isolated sibling phase, locks it via atlas_lock_validator, and — if the verdict is fail — dispatches atlas-findings-repair (not this executor) before the 2nd and last validator.

After writing the state file and before returning, emit state_path_created with the same state_path. Without this exact checkpoint, atlas_lock_validator(start) blocks in G12 and the orchestrator cannot dispatch the cold validator.

The only handoff input is state_path. Do not paste the contract, diff, or task list inline. The validator reads everything it needs from the state file and the plan it points to. (atlas_capabilities is the runtime source of truth for the dispatch mechanism the orchestrator uses — see references/host-adapters.md.)

Finish all local work before the handoff — then stop idle. Finish every local gate (lint, analyze, tests, git diff --check, diff-stat) and write the state file before returning the handoff. After returning validator_handoff_required, the executor must not mutate anything: the orchestrator now owns the slice, and any mutation here would change what the sibling validator reads and breaks determinism (same failure class as the orchestrator's G9).

9. The orchestrator consumes the verdict

This executor does not parse the validator output — the orchestrator does, deciding only from verdict:

• pass / pass_with_observations: terminal — close the slice. Observations and boundary_violations returned alongside a non-fail verdict are reported residuals, never a trigger for another validator dispatch.
• fail: the orchestrator opens repair_start, dispatches atlas-findings-repair, closes with repair_run_id, then runs the 2nd and last validator (max 2 cycles total). This executor is not reused for the retry.

Never decide by substring matching prose. Once the slice is closed, do not edit code, tests, or boundary files just to satisfy an observation; that reopens the slice and forces an avoidable re-validation. Real follow-up from an observation goes to the final report or a backlog item, not into an extra in-slice change.

10. Report final outcome

At the end of execution, report completed tasks, validations run, validator outcome, and any residual gaps.