Plan Execution

Drive the implementation of a written multi-phase plan with consistent between-phase discipline: review the diff, commit, and hand off the session when context grows. This skill centralizes the workflow so the user does not have to repeat it in every prompt.

Default autonomy

On run start, apply Mode A autonomy automatically — do not wait for the user to grant it. Questions live in the initial alignment moment only; after that the run proceeds start-to-finish (deny/pre-authorized/mandated/autonomous — see "Operating mode" below).

Operating mode

Front-loaded, then autonomous start-to-finish. Resolve every question at Orient (phase 0); after that, run all phases without interrupting. Follow the shared autonomy canon (autonomy-conventions.md). The operative rule here:

• Ask everything up front, at Orient. Surface clarifications and confirm any publication the plan implies (deploy/publish/release) before phase 1. If the plan did not pre-authorize a publish step, surface it at the end — not mid-run.
• Evaluate batch-promotion at Orient (mandatory, one line). Before phase 1, decide whether the plan's afk-impl phases should run as a durable Workflow, and say so in one line. The full rule is in references/01-unattended-batch-execution.md § Promotion at Orient. It is a kickoff decision, never a mid-run interruption.
• Do not re-ask for steps this skill mandates. Invoking plan-exec authorizes you to code-review the diff, author the commit message, commit per phase, and hand off when context grows. Do them — never stop to ask "should I commit? is the message OK? should I review? should I hand off?"
• Planned migrations and dependency changes are autonomous. If the plan calls for a migration or a dep install/update/downgrade, run it — commit, deps, and additive migrations are not gated. A destructive migration (data loss) is the exception: it stays gated (global DB rule).
• A mid-run bifurcation that is not destructive → do it and document it (in the plan doc / final summary) so you can review it afterward. Don't stop for a doubt that breaks nothing; verify the assumption (investigate, don't guess).
• Only stop for: a deny-class destructive action (skip + document), an un-pre-authorized publish (surface at the end), or a genuine hard blocker you cannot resolve (missing credentials, truly unknowable intended behavior).
• A phase report is not a stop. Put the status note in the same message as the next phase's first tool call; never close a turn by announcing the next step instead of taking it (both drew a bare "continue" from the user). Waiting on a launched subagent is not a stop: one line naming it closes the turn.
• On an ambiguous fork you cannot cleanly classify — decide it yourself before stopping. Judge CONTINUE / ASK / STOP against the policy in the ARBITER block in workflow-core.md, using the run's autonomy surface and the phase's proof (verification output, commit SHA). Follow your own verdict; batch any ASK to the end. A doubt you cannot settle is not a reason to block: apply the rule above and proceed. model-policy: per-stage: every subagent this skill launches pins its own model and effort rather than inheriting the run's.

Otherwise: proceed. The user will redirect if needed.

Unattended / batch execution (opt-in, gated)

The default path above is interactive. For unattended/batch runs ("execute the whole plan while I'm away"), this skill can launch the plan as a durable Workflow — each phase a fresh bounded agent, a two-stage gate per phase, crash-resumable via the journal. Promote only when the work is decomposable + machine-verifiable + unattended and each phase's real work dwarfs the per-agent floor; the mandatory Orient evaluation is the opt-in.

Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-exec/references/01-unattended-batch-execution.md before promoting anything — promotion threshold and its measured ~22k/agent cost floor, the three shipped workflow forms and how to pick one, how to derive args from the plan, the phase tier map, and what happens when a phase fails its gate.

Workflow

0. Orient

1. Read the plan document fully (path is in the user prompt or in .context/plans/). If multi-file, read 00-index.md plus the current phase file. You may skip Execution log entries for already-completed phases (canon §Execution log) — they are proof journaling, not spec.
2. Identify: total phases, current phase (first unchecked checkbox), success criteria per phase, verification step.
3. Check whether this plan is bug work. Plans carry no type field; the back-link runs the other way, so resolve it by grep: grep -rl "escalated_to: plan/<slug>" .context/backlog/. If the originating item carries type: bug, every behavior-changing phase is bound by RED→GREEN (bugfix): the test is written and fails for the right reason before the fix, and the GREEN output is that phase's proof. No matching item → carry on normally.
4. Check the prior phase's review evidence. If a previous phase completed this session or an earlier one, confirm its Execution-log entry in 00-index.md carries a review: <verdict> · <n> findings line. A missing entry means the between-phase code-review was skipped — run it now, on the prior phase's diff, before starting the current phase; do not proceed silently on an unreviewed phase.
5. Honor the plan's Isolation surface if it declares one. If the plan already recorded an Isolation note (plan's Step 5), act on it: repair what check-overview.sh flags in the worktree index, then run the recorded worktree.sh new command before phase 1 (--no-infra only when the plan says code-only); if the project has no worktree setup, EnterWorktree and note it. With no Isolation note, run worktree bootstrap if .context/worktrees/00-index.md does not exist yet, then worktree.sh new here at Orient, before phase 1. Enter the worktree only if the plan/user authorized it — do not auto-enter one that was not approved. Before creating any worktree/branch, resolve and state its base branch and require explicit confirmation if it is not the repo's default (worktree's branch-base rule) — never fork off the ambient checkout silently. No declared surface and no plan-recorded parallelism → run in place. The plan doc stays source-of-truth in the main tree: a fresh worktree has only committed files, so update the plan and record proof_links at its main-tree path (a gitignored/uncommitted .context/ plan is absent from the worktree) — see the canon's Lifecycle note.
6. Probe for concurrent work before touching anything. The user runs parallel sessions and worktrees on the same project, and a session blind to them will take decisions another session owns. Two commands, seconds: git worktree list and git log --all --since="24 hours ago" --oneline. If another live line of work shows — a worktree you did not create, fresh commits this session did not make — name it in your first status message, keep hands off its files and branches, and route any decision that belongs to it back to the user instead of taking it here.
7. Set the run's spend before phase 1. Each phase's tier says how hard its work is; the canon's table (plan-conventions.md §"Optional phase metadata") maps that to a default model and effort level. Those cells are defaults, and this is the one moment to override them — remaining quota, model availability, or a cheaper cell the user prefers. State the override and its reason in one line and log it to the Execution log; a phase whose cell you changed is not a phase whose plan you edited. Ask nothing: an unstated tier is standard, and no override is the default. A tier row whose cell restricts tools: also needs a registered agent definition, since agent() has no tools option: the toolset travels only as agentType, the name of an agent file. One definition per tier the plan uses (never per phase) — model/effort from the canon row, tools: exactly the row's list, skills: [aidex:testing] (a restricted tier has no Skill tool), user-invocable: false — living in the project's .claude/agents/<name>.md, or ~/.claude/agents/<name>.md when several projects share it; those are the two locations an agent name resolves from, project first. Pass its name as the batch phase's agentType. No definition → the phase runs unrestricted and pays ~49k of prefix per call instead of ~14k. The definition must be on disk before this session started. The agent registry is read at session start: a stub written mid-session is invisible to the session that wrote it, and a batch naming it dies at once with agent type '<name>' not found. So check for it here, at Orient — if it is missing, write it and hand off; the next session sees it. Two things measured on a real batched run (2026-09-20): the restricted implementer's first call read 15,826 cache_creation against 50,841 for the same run's unrestricted verifier, and the phase's model cell won over the definition's model: line — agentType carries the toolset, nothing else.
8. Create a TaskList mirroring the plan's phases so progress is visible.
9. Front-load the work-list for chained multi-item runs. A single plan's phases are already an ordered queue (walk them). But when this session chains multiple plans/items (close several plans, then clear backlog), fix the cross-item order once here — via the AskUserQuestion survey → a durable .context/worklists/ work-list (see worklist-conventions.md). Then walk it with worklist-advance.sh between items instead of pausing to ask "what next?". Emergent work (class b) is appended (--append) and continued, not asked; only a class-(c) fork or the publication gate interrupts. No interactive channel (claude -p, cron): skip the survey, walk the items in the order they were given, and record the defaulting in the run's final summary — autonomy-conventions.md § When there is no interactive channel.

1. Execute each phase

Multi-file plan, interactive run: phases go in waves, not one by one: references/05-launch-waves.md.

For each phase in order:

1. Implement the tasks in the phase. Plan code is a sketch, not a paste source: any code block or line reference in the plan was frozen at plan-write time — before applying one, read the current file, confirm the surrounding code still matches, and check for sibling call-sites/branches the plan did not enumerate. The phase's acceptance criteria and gate are the contract; the plan's code is illustrative except inside a Contract block (exact signatures/shapes/DDL), which is binding. A shared-component primitive gets one real-framework test per merge-dependent behaviour (attrs/class fallthrough, slot defaults), named required in the impl brief.
2. Run the verification step the plan declares (tests, type-check, build, manual check). If none is declared, run the minimum that proves the change works (relevant test suite + type-check). Iterate on the selection, not the whole suite: ${CLAUDE_PLUGIN_ROOT}/skills/audit/scripts/affected-tests.sh --command prints one runnable command for the tests covering the phase's diff; exit 3 means no selection is available, so run everything and say so. The between-phase checkpoint commits on the selection, stated rather than silent — say which subset ran and that the full suite has not. The full suite gates the INTEGRATION boundary: the merge, the push, or the end of the run (decision/2026-08-24-full-suite-gate-moves-from-commit-to-integration). An # INCOMPLETE selection is the exception — unmapped scope forces the full suite in-phase. It also names changed files that measurably break and have no E2E — write that spec in-phase.
3. If verification fails: fix root cause. After 3 failed attempts on the same approach, stop and ask the user.
4. Mark the phase's checkboxes as done in the plan file. Record the phase's proof — the verification output, the commit SHA, a request/response payload, or a screenshot of the flow — in the plan front-matter proof_links (or under .context/proofs/<slug>/ for larger captures) per conventions (00-global.md §7.1). Don't mark a phase done you can't show works.
5. When execution departs from the plan, the plan edit ships in the commit that departs — not in the close-out commit. Otherwise the phase diff is reviewed against a stale plan, and the reviewer cannot tell a deliberate change of course from an omission. Same coupling plan-conventions.md already applies to tests. Where the plan is not committable this collapses to editing it before the commit, in the same turn: aidex's own repo gitignores .context/, and it is the exception — 1,135 plan files are tracked across the six fleet repos, 0 here (census 2026-09-07).
6. Tests and bugs met mid-phase. Tests follow testing; every delegate brief names aidex:testing. An in-scope bug is fixed RED-first (bugfix). An out-of-scope one — found here or reported by a delegate (batch: the result's outOfScopeBugs) — is never patched inline: route it with its reproduction to a bugfix delegate (aidex:bugfix-opus where defined) or register it (03). If it blocks the phase's gate, the phase stays blocked until that fix lands, then resumes.

Scoped plans carry a file contract. When the plan's front-matter says mode: scoped, its **Files:** list is the declared blast radius, written on deliberately incomplete investigation — so it will sometimes be wrong. The contract makes that visible, not impossible: (1) log any file you touch outside the list in the Execution log, one line; (2) re-apply the five triage signals (plan-conventions.md §The five signals) to that file — if any flips to full, stop and re-triage the whole plan with plan; (3) independently, if the file list has doubled, stop and re-triage. Six extra trivial files trip no signal but mean the contract misread the change — a failure rule (2) cannot see.

Loop (opt-in, per phase only): if a single phase is mechanical and its verification is a pure machine gate (e.g. "make all <suite> pass" / "type-check clean"), that one phase may be spec'd as a loop via loop and run by /goal/ralph-loop — mirroring the plan → loop pointer at the phase level. Do not loop the executor itself: the between-phase checkpoint (review/commit/handoff) is judgment work, and irreversible steps (push/release/deploy) stay outside any auto-loop and human-gated. (commit is not irreversible — it is part of the checkpoint, not a gated step.)

2. Between-phase checkpoint (MANDATORY)

After each phase passes verification, before starting the next phase, run the shared checkpoint — read ${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/checkpoint-conventions.md and follow its four moves (scoped review with its recorded anchor and findings addressed by remedy · commit · register-don't-discuss · auto-handoff without asking). It is one canon with two consumers (this skill and the backlog sweep) and is not restated here; test_checkpoint_lockstep.sh fails this file if it grows its own copy. What is plan-specific:

• Scope. ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/resolve-review-scope.sh --files working-diff, or --base <phase-start-sha> branch-vs-main for a phase that spans commits — and ${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/review-scope-conventions.md owns which reviewer covers which scope. Exit 3 is an empty scope, never a passing review.
• Where the evidence goes. The Execution log in the plan's 00-index.md takes the review: <verdict> · <n> findings · scope=<scope> anchor=<anchor> line before the commit.
• A UI phase does not close on prose. Before the commit, run ${CLAUDE_PLUGIN_ROOT}/skills/plan-exec/scripts/check-ui-evidence.sh <plan file> <phase> (the plan or its 00-index.md). It owns which phase is UI and the ui-* lines "verified" needs; non-UI exits 0. Exit 1 or 2 keeps the phase open. An unattended run may queue a non-final phase's page as pending-owner (script header); the last phase fails while any is open.
• Deferrals use register-item.sh --origin plan --plan <this plan> (references/03-deferring-emergent-work.md).
• Which model runs which step — orchestrate, implement, and do the mechanical work with different models (references/04-model-tiering.md).
• The seed's slug: line is the PLAN's name plus the phase — the name existed before the first handoff and does not move. CHARTER comes from the plan's name and goal.

3. Final phase

After the last phase:

1. Run the full verification the plan declares (or the project's standard pre-deploy check: tests + build + lint).
2. Code-review and commit as above.
3. If the plan implies a release (user-facing changes, feature complete): surface the project's release command as an option (detect it — many projects expose a /release-style command). Do not run it without explicit user approval — releases are deploy-coupled.
4. Update the plan document: mark all phases complete, add a closing note with the final commit SHAs if useful.
5. Close out the run: tear down isolation if a worktree was entered at Orient, log the worktree usage line, suggest a coverage sweep if the plan touched mapped src paths, run guided human verification — it emits a proof artifact, and a plan with nothing human-visible skips it by recording the reason, never by omission — reconcile deferrals to a BL-NNN or a CLOSE, and fire the notifier. Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-exec/references/02-close-out.md and follow it step by step — each step has a guard and an ordering that matter, and doing them from memory is how a worktree survives its plan.

Per-project adjustments

This skill ships stack-agnostic defaults; detect the project's own conventions:

• Review/commit/release commands. Use the project's own slash commands or helpers (.claude/, CLAUDE.md); never assume a name.
• Stricter project rules. Read the project's CLAUDE.md (and memory) before the first phase — test runners, commit style, version bumps, release gates.

If the project's CLAUDE.md or memory contradicts this skill, the project wins.

What this skill does NOT do

• It does not create plans (use plan).
• It does not skip verification to move faster — every phase is verified.
• It does not deploy or release without explicit user approval.
• It does not run E2E tests against dev environments — use the project's isolated test runner if E2E is required by a phase.