Aidex Workflow

> 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-workflow" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.

Workflow — Design Multi-Agent Orchestrations

Help the user design and specify a one-shot multi-agent fan-out before running it, capture it as a .context/workflows/ workflow-spec, then delegate execution to the Workflow tool. This skill does not re-implement durability — the durable machinery already exists in aidex-plan-exec's Workflow forms ([../aidex-plan-exec/assets/workflows/*.workflow.js](../aidex-plan-exec/assets/workflows/), single-sourcing the durability CORE in [../aidex-conventions/references/workflow-core.md](../aidex-conventions/references/workflow-core.md)). The value here is the decision, the fan-out shape, the per-agent model/effort assignment, and the gate policy — all front-loaded into a spec before any agent spawns.

Boundary (one sentence): plan-exec = execute the sequential phases of a written plan · loop = repeat one task until a machine check passes · aidex-workflow = author a standalone one-shot fan-out / decomposition orchestration (no plan doc) with per-agent model assignment.

See [references/01-workflow-spec-conventions.md](references/01-workflow-spec-conventions.md) for the artifact format and the fan-out shape catalog.

---

Sub-actions

Dispatch by first argument:

| Command | Backed by | Purpose | |---|---|---| | /aidex-workflow | — | Show help + list existing .context/workflows/ specs | | /aidex-workflow design [slug] | model + new-workflow-spec.sh | Interactive: run the fan-out survey, pick the shape + per-agent models, then scaffold the spec | | /aidex-workflow new | [scripts/new-workflow-spec.sh](scripts/new-workflow-spec.sh) | Scaffold an empty workflow-spec file (skip the interview) | | /aidex-workflow run | model | Read a finished spec and launch it via the Workflow tool |

Dispatch logic

bash "${CLAUDE_SKILL_DIR}/scripts/new-workflow-spec.sh" "$@"

• new → new-workflow-spec.sh new
• design [slug] → run the interview below, then new-workflow-spec.sh new and fill it in
• run → no script; read the spec and follow [run](#run) below
• no args → list specs (ls .context/workflows/*.md) and show this help

---

design — the survey

Run the survey first and to completion (the transversal front-loading principle: AskUserQuestion is a planning-time survey, not a mid-run interrupt), then write the spec and proceed headless. Walk these one at a time; do not skip step 0 or step 1.

1. Fan-out suitability (step 0). Is the work genuinely decomposable into

independent sub-units that gain from running concurrently or from different models? If it is really the sequential phases of a written plan → hand to aidex-plan-exec. If it is repeat one task until a check passes → hand to aidex-loop. If it is a single unit of work → just do it. Only a real fan-out / decomposition belongs here.

1. Shape (step 1). Pick the fan-out shape from the catalog in

[references/01-workflow-spec-conventions.md](references/01-workflow-spec-conventions.md) §"Fan-out shape catalog": review-by-dimension · migrate-N-sites · research-N-sources · decompose-impl. The shape fixes how items map to agents and whether stages pipeline or fan out behind a barrier.

1. Work-list. Enumerate the concrete items (dimensions / call-sites / sources /

sub-tasks). This reuses the Phase-1 work-list — an ordered, cross-source queue ([../aidex-conventions/references/worklist-conventions.md](../aidex-conventions/references/worklist-conventions.md)). Fix the order once here; do not re-ask per item at run time.

1. Per-agent model + effort. For each stage, assign model + effort and say why

(breadth → sonnet/medium; adversarial verify / synthesis → opus/high; mechanical transform → sonnet/low). This table is the spec's distinctive payload — see §"Per-agent model table" in the conventions.

1. Stop condition + gate policy. The machine gate each agent's output must pass, and

the run's publication gate (publish: ask | preauthorized). Mirror the work-list's gate-policy.

1. Autonomy surface (step 1.5). Resolve the permission borders so the run is

unattended. Use Claude Code's native allow/ask/deny — do NOT enumerate an allowlist. Pin: (a) any workflow-specific deny; (b) the pre-authorized ops; (c) the always-ask set (defaults: push/publish/deploy/release only — NOT commit, deps, or additive migrations). Everything else safe + additive is autonomous: proceed, verify the assumption, log it. (See [../aidex-conventions/references/autonomy-conventions.md](../aidex-conventions/references/autonomy-conventions.md).)

1. Isolation surface. If the workflow's agents mutate files in parallel, they

need isolation: 'worktree' (the Workflow tool's per-agent worktree) so they do not collide — the strongest case for review/migrate fan-outs that write. Read-only fan-outs (review-by-dimension, research) need none. Record it in the spec's Guardrails.

1. Scaffold. Run new-workflow-spec.sh new , then fill every section from the

answers. Leave nothing as a placeholder. If a spec with that slug already exists (new-workflow-spec.sh refuses to overwrite), refine the existing spec in place.

run

1. Read .context/workflows/-.md.
2. Confirm the shape, the per-agent model table, the gate policy, and the autonomy

surface are still accurate.

1. Launch via the Workflow tool — do not rebuild durability. Reuse the

aidex-plan-exec forms keyed off the shape:

• review-by-dimension / research-N-sources → the pipeline pattern (each dimension

reviews, then verifies as soon as its review completes), or parallel() behind a barrier when a synthesis stage needs all results at once.

• migrate-N-sites / decompose-impl that writes files → pipeline()/parallel()

with isolation: 'worktree' per agent, each gated by the spec's machine gate. Translate the spec's per-stage model/effort directly into the agent(prompt, {model, effort}) options, and the work-list into the items array. The two-stage gate (Bash verifier → conditional durability-arbiter) and kill-resume come from the plan-exec CORE — cite it, do not re-author it.

1. Model guard. If the session model is a Sonnet-class model, **recommend a

handoff to Opus before launching** — Sonnet demonstrably fails multi-agent Workflow orchestration (observed field failure 2026-07-03). State it with the launch plan, never mid-run.

1. Only execute the Workflow call if the user explicitly asks you to start it now;

otherwise print the launch plan (form + args shape) for them to confirm.

> Durable-run marker (optional Stop-hook enforcement). When you launch the workflow, > run bash "$HOME/.aidex/hooks/durability-run.sh" start workflow; run > bash "$HOME/.aidex/hooks/durability-run.sh" stop when it ends. Harmless if the optional > Stop hook is not installed ([hooks/README.md](../../hooks/README.md)); fails open — if the > script is absent, just proceed.

Run doctrine — autonomy during the run

Once the spec's Autonomy surface is declared, the workflow runs to its stop condition without interrupting the user:

• Do not pause for anything outside the declared ask-set. Routine, safe, additive

work proceeds — including an unforeseen non-breaking micro-decision under your authorship (class b: append to the work-list, continue silently).

• Pause only for the deny set and the ask set (push/publish/deploy/release,

plus any the spec declared). Commit, deps, and additive migrations are not gated.

• Proceed + log, don't halt: on a safe additive decision, verify the assumption

(investigate, don't guess) and log it — do not stop.

• A genuine emergent decision the work itself revealed (class c) is the one

legitimate mid-run interrupt — rare; preserve it. The goal is removing the avoidable "what next?" questions, not reaching zero.

• **Ambiguous consent point not in the ask-set → consult the durability-arbiter, do not

deadlock.** Read [../aidex-conventions/agents/durability-arbiter.md](../aidex-conventions/agents/durability-arbiter.md), pass it to the Agent tool (model: sonnet, read-only) with the situation + the spec's autonomy surface + proof, follow its verdict, batch any ASK to the end. If it errors, apply the rule above and proceed — never block on it.

This is the workflow's instance of the shared autonomy canon — full decision rule, the commit-is-not-gated policy, the three-class model, and the durability-arbiter live in [autonomy-conventions.md](../aidex-conventions/references/autonomy-conventions.md).

---

Boundaries

| The user wants to… | Route to | |---|---| | Execute a written multi-phase plan (there is a plan doc) | aidex-plan-exec | | Repeat one task until a machine check passes (tests/typecheck/build green) | aidex-loop | | Plan multi-step work (no orchestration yet) | aidex-plan | | Run a prompt on a recurring interval | native /loop | | Record a decision / ADR | aidex-decision | | Investigate how something works | aidex-research | | Audit the Claude Code ecosystem | aidex | | Audit project state (UX/security/perf) | aidex-audit | | A single unit of work, no fan-out | (just do the work) |

Related

• aidex-plan-exec — owns the durable Workflow forms (pipeline / fan-out / review)

and the durability CORE this skill delegates to. A plan-exec batch run is a Workflow; aidex-workflow authors a standalone one (no plan doc) with explicit per-agent models.

• aidex-loop — the sibling designer for repeat-until-green loops; same designer

pattern (survey → spec → delegate), different execution shape.

• aidex-conventions — owns the shared .context/ canon, the work-list, the autonomy

surface, and workflow-core.md.

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.