# Aidex Plan Exec > Use when the user asks to execute, implement, or continue a written multi-phase plan — typically a `.context/plans/` document or any plan with checkboxes/phases. Fires on "implement the plan", "execute plan X", "let's execute the plan", "continue with phase Y", "resume the plan", "run the plan phase by phase". Enforces between-phase discipline: code-review, commit, handoff when context grows. Not… - **Type:** Skill - **Install:** `agentstack add skill-yacb2-aidex-aidex-plan-exec` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [yacb2](https://agentstack.voostack.com/s/yacb2) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [yacb2](https://github.com/yacb2) - **Source:** https://github.com/yacb2/aidex/tree/main/skills/aidex-plan-exec - **Website:** https://aidex-lemon.vercel.app ## Install ```sh agentstack add skill-yacb2-aidex-aidex-plan-exec ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About > **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 `id`s 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.parse`s 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 `id`s — 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](https://github.com/yacb2) - **Source:** [yacb2/aidex](https://github.com/yacb2/aidex) - **License:** MIT - **Homepage:** https://aidex-lemon.vercel.app Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-yacb2-aidex-aidex-plan-exec - Seller: https://agentstack.voostack.com/s/yacb2 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.