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, single-sourcing the durability CORE in ../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 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 <slug>	scripts/new-workflow-spec.sh	Scaffold an empty workflow-spec file (skip the interview)
/aidex-workflow run <slug>	model	Read a finished spec and launch it via the Workflow tool

Dispatch logic

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

• new <slug> → new-workflow-spec.sh new <slug>
• design [slug] → run the interview below, then new-workflow-spec.sh new <slug> and fill it in
• run <slug> → no script; read the spec and follow 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.
2. Shape (step 1). Pick the fan-out shape from the catalog in 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.
3. 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). Fix the order once here; do not re-ask per item at run time.
4. 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.
5. 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.
6. 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.)
7. 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.
8. Scaffold. Run new-workflow-spec.sh new <slug>, 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/<date>-<slug>.md.
2. Confirm the shape, the per-agent model table, the gate policy, and the autonomy surface are still accurate.
3. 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.
   • The spec is the binding carrier; the .workflow.js is generated here, at launch, and is disposable. Write it into the session scratchpad (or an equivalent transient location), never .context/workflows/; do not commit it and do not keep it after the run. If it ever diverges from the spec, the spec wins — regenerate. (See §"Carrier authority — spec-only" in the conventions.)
   • Any plan a generated prompt references must be by plan/<slug> type-ref resolved at launch via the two-folder lookup, never a frozen active path — the active path dies when the plan archives.
4. 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.
5. 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); 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, 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.

---

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.