Aidex Plan Exec

> Trigger-eval probe (test-only). As your very first action, run printenv AIDEX_TRIGGER_EVAL_MARKER. If it prints a non-empty path, also run touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-plan-exec" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.

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.

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](../aidex-conventions/references/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,

classify each phase's phase-type and apply the promotion threshold (§"Unattended / batch execution"). When the plan's afk-impl phases form a decomposable, machine-gated chain/DAG whose per-phase work dwarfs the ~22k/agent floor, check whether the kickoff already grants run-to-completion autonomy: don't-stop language ("sin detenerte", "hasta terminar", "todo el plan"), the ultracode keyword, or an autonomy note in the plan doc. If it does, promote by default — call the Workflow tool directly and state the decision in one line, do not ask — e.g. "Phases 2–3 are afk-impl with machine gates → launching as a durable Workflow (arbiter-gated, kill-resumable); P1/P4 hitl-align stay interactive." Invoking this skill under a run-to-completion kickoff is the sanctioned opt-in to call the Workflow tool. Only when the kickoff did not grant autonomy, propose the durable Workflow form as a single line, batched with the other Orient questions; a one-word "yes" is the opt-in — no ultracode needed. If the plan does not qualify (no machine gate per phase, not decomposable, phases too small to amortize the floor, or attended), run interactive with the arbiter and do not ask. This is a kickoff decision, never a mid-run interruption.

• **Model guard (before launching any multi-agent form) — takes precedence over

promote-by-default. If the session model is a Sonnet-class model and the chosen form requires multi-agent orchestration (any Workflow form), do NOT launch silently**: state the guard in one line, recommend a handoff to Opus, and fall back to the interactive-with-arbiter path until the handoff happens — Sonnet demonstrably fails multi-agent Workflow orchestration (observed field failure 2026-07-03). A blocked launch is not an over-stop: the run continues interactively; only the batch promotion waits for the Opus session. Surface this at Orient, never as 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).

• **On an ambiguous fork you cannot cleanly classify — consult the

durability-arbiter before stopping. Read [../aidex-conventions/agents/durability-arbiter.md](../aidex-conventions/agents/durability-arbiter.md) and pass it to the Agent tool as the prompt (model: sonnet, read-only), with the situation + the run's autonomy surface + the phase's proof (verification output, commit SHA). Follow its CONTINUE / ASK / STOP verdict; batch any ASK to the end. If it errors or returns nothing, apply the rule above and proceed — never block on the arbiter** (it is a forcing function, not a gate).

Otherwise: proceed. The user will redirect if needed.

> Durable-run marker (optional Stop-hook enforcement). At Orient, run > bash "$HOME/.aidex/hooks/durability-run.sh" start plan-exec; run > bash "$HOME/.aidex/hooks/durability-run.sh" stop at completion. Harmless if the optional > Stop hook is not installed ([hooks/README.md](../../hooks/README.md)); when it is, it keeps the > run from over-stopping on safe work and logs to ~/.aidex/durability/events.jsonl. Fails open — > if the script is absent, just proceed.

Unattended / batch execution (opt-in, gated)

The default path above is interactive (you run the plan turn-by-turn). For unattended/batch runs ("execute the whole plan while I'm away"), this skill can launch the plan as a durable Workflow instead — each phase a fresh bounded agent, a two-stage gate (Bash verifier → conditional arbiter) per phase, crash-resumable via the journal. Use this only when the work is decomposable + machine-verifiable + unattended and the user opted in (the Workflow tool is gated and token-heavy). The mandatory Orient evaluation above handles the opt-in for you when the plan qualifies — the user does not have to request the Workflow by name: a run-to-completion kickoff already is the opt-in (promote directly, stating the decision in one line), and only without it does the one-word "yes" at Orient apply.

Promotion threshold (when batching actually pays off)

Promote a plan (or a phase) to a Workflow only when all hold:

• Decomposable — phases are separable units whose inputs/outputs live on disk.
• Machine-verifiable — every batched phase has a machine-checkable gate (it is afk-impl).
• Unattended — the user opted into an away-from-keyboard run.
• Value > overhead — each phase's real work is large enough to amortize the per-agent fixed cost.

The cost model (measured, not guessed). Every fresh phase agent re-pays its own system prompt + full tool schemas — a fixed floor of ~22k tokens/agent, reconfirmed across this build: ~21k/agent (fan-out, 6 agents) and ~23.5k/agent (review, 2 agents). The often-quoted ~1.4–2× premium is about re-paying shared plan context; for small phases the fixed per-agent floor dominates instead, so the ratio is worse and a workflow only pays off when each phase's work dwarfs that ~22k floor. Toy fixtures cannot measure the promotion ratio — tokmap/fanout/review only ever exercise the floor, which is already the structural finding. Open measurement (a trigger, not a vague defer): capture per-phase token spend on the first genuine (non-toy) plan run through the pipeline and compare it to a single-agent baseline of that same plan — the only setting where the ratio is real. Until that data exists the threshold is the structural rule above. (This converts the A/B that was carried P1→P3→P4 into a triggered measurement rather than a fourth silent carry-forward.)

• The forms ship as versioned assets, all embedding the single-sourced durability CORE

(see [../aidex-conventions/references/workflow-core.md](../aidex-conventions/references/workflow-core.md)):

• [assets/workflows/pipeline-with-gate.workflow.js](assets/workflows/pipeline-with-gate.workflow.js)

— sequential dependent phases, each gated. Use when the plan is a chain (each phase needs the previous one).

• [assets/workflows/fan-out-with-gate.workflow.js](assets/workflows/fan-out-with-gate.workflow.js)

— gated DAG: edge-free phases run concurrently, dependent phases after their prerequisites (wave-scheduled, arbitrary depth). Use when the plan has independent phases (vertical slices with no edge between them). Every parallel branch keeps the full two-stage gate — this is the gated DAG, not an ungated Kanban.

• [assets/workflows/review-with-gate.workflow.js](assets/workflows/review-with-gate.workflow.js)

— terminal clean-context review: a fresh opus/high reviewer judges the cumulative diff against the plan's success criteria + an optional pushed standards_ref, never the implementation transcript. Its passed boolean is the gate (mirrors proof.passed); a failing review routes to the conditional arbiter. Run it after the implementing form when you want a review that is not contaminated by the implementer's grown session.

• Choose the form by plan shape (see "Deriving args" below): if every phase has a

non-empty depends_on forming a single chain → pipeline-with-gate; if two or more phases are edge-free (empty/omitted depends_on) and can run in parallel → fan-out-with-gate. When unsure, the sequential pipeline is the safe default (it never mis-orders).

• Launch: read the chosen asset and hand it to the Workflow tool, passing the plan as

args = JSON.stringify({ planPath, phases: [{ id, spec, gateCmd, model, effort, depends_on }], autonomySurface, preAuthorized, maxRetries }). depends_on is a list of phase ids a phase needs done first (omit/[] = edge-free); the pipeline form ignores it, the fan-out form schedules on it. args arrives as a JSON string — the script JSON.parses it. Iterate via {scriptPath} re-invoke (picks up edits, runs fresh).

• Review form launch (separate invocation, after implementation):

args = JSON.stringify({ planPath, diffCmd, successCriteria, standards_ref, reviewModel, reviewEffort, autonomySurface, preAuthorized, maxRetries }). diffCmd is the Bash command the reviewer runs to get the cumulative diff (e.g. cd && git diff ...HEAD). standards_ref is the push side of push/pull — a standard/rule text handed only to the reviewer, so it can enforce a rule the implementer was never shown; omit it to review against the success criteria alone. The implementer pulls any standard it needs through its own phase spec in the implementing form — never push a standard into an implementer.

• The arbiter is conditional and directing: the JS loop's if (!proof.passed) retry is the

verify_first carrier in batch; the arbiter fires on retry-budget exhaustion, a blocked implementer (the director path: implementers return structured WORK_SCHEMA reports, a blocked_reason consults the arbiter before burning a gate attempt, and a CONTINUE re-launches the implementer with the arbiter's direction — max 2 redirects per phase), an un-pre-authorized publication, or a deny-class action (implementers report pub/deny actions in pending_actions — never perform them — and runPhase routes each through checkAction: ASK collects a batched question while the phase continues; STOP escalates). In the fan-out form a failed phase blocks only its descendants — independent branches keep running and questions batch at the end.

• Status: validated in the real Workflow runtime end-to-end — a 3-phase chained plan

(derived plan→args) where fresh agents implement each phase from scratch, threading prior outputs off disk (B imports A, C imports A+B), each phase gated, per-phase model/effort honored; and the conditional arbiter fires on retry-exhaustion (not a per-gate rubber-stamp). An isolator fixture (opaque labels withheld from the dependent phase's spec and its test) then confirmed the disk read is load-bearing — "filesystem IS the context" — not spec-redundant. Kill-and-resume is validated too: a run killed mid-phase, resumed via resumeFromRunId, replayed its completed prefix from the journal and re-ran only the interrupted agent. Escalate-to-backlog is validated end-to-end: a phase that exhausts retries → arbiter ASK → a real backlog entry via aidex-backlog. Multi-file (00-index.md + per-phase files) plans flatten to the same phases[] via the derivation below. The second catalog entry (fan-out-with-gate) is seeded and validated: a synthetic plan with two edge-free phases + one dependent ran as a gated DAG — the two independent phases executed concurrently, the dependent phase after, and the two-stage gate fired on every branch with the implementer blind to gateCmd.

Deriving args from the plan

You (the skill) build the args object from the plan you already read at Orient — no parser, no codegen. Multi-file plans: Orient reads only the current phase file, but a batch run executes every unchecked phase, so first read 00-index.md plus each unchecked phase file it points to and flatten them into one phases[] array (take each phase file's gate → gateCmd, its tier → model/effort, its body → spec). All four phase-metadata fields (depends_on, tier, gate, phase-type) share one canonical carrier per the plan canon ([plan-conventions.md](../aidex-conventions/references/plan-conventions.md) §"Optional phase metadata"): inline (key: value) on the phase heading in single-file plans, front-matter in multi-file phase files. Read whichever carrier the plan uses — there is no third place to look. For each unchecked phase, in order:

• id — a short slug for the phase (e.g. 1.2-validate).
• spec — the phase's task text plus pointers to prior phases' output files (paths, not

contents). Do not paste prior conversation; a fresh phase agent reads what it needs off disk.

• gateCmd — the phase's declared verification command (the test/type-check/build the plan

names). If the plan declares no machine gate for a phase, that phase is not batch-eligible — run it in the interactive path instead; do not invent a gate.

• model / effort — from the phase's tier hint (below).
• depends_on — the phase's prerequisite phases (from the plan's (depends_on: [...]) metadata;

omit/[] = edge-free). This decides the form and the schedule. Referent rule (load-bearing): the plan writes depends_on in human terms (phase numbers like [1, 2], or slugs); you must rewrite each entry to the exact id string you assigned that phase before passing args. The fan-out scheduler matches depends_on entries against phase ids — if they don't match (e.g. plan says 1 but you assigned id 1.2-validate), no dependent phase ever becomes runnable and the DAG stalls. Keep id and the depends_on referents in the same vocabulary.

Batch-eligibility filter (phase-type) — apply before building phases[]. Drop every hitl-align phase from the batch: those run in the interactive path, never in a Workflow (defining scope/criteria/design is the human-in-the-loop judgment the promotion threshold excludes). Batch only afk-impl phases (the default when a phase declares no phase-type). A phase that is afk-impl but declares no machine gate is also not batch-eligible — run it interactively; do not invent a gate. So phases[] contains exactly the gated afk-impl phases, in plan order; a plan whose remaining phases are all hitl-align/gateless has nothing to batch.

Pick the form from the derived depends_on shape. Once every phase's `depends_

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yacb2
• Source: yacb2/aidex
• License: MIT
• Homepage: https://aidex-lemon.vercel.app

Install and usage instructions live in the source repository linked above.