aid-execute

Execute Task

Read the type. Do the work. Review it. Fix it. Ship it.

⚠️⚠️ MANDATORY: write task State AS IT CHANGES -- read this first

Whoever executes this task -- the main/orchestrator agent running it DIRECTLY, or a dispatched sub-agent -- MUST write the task's State field the instant it changes: In Progress before starting work, In Review before dispatching the reviewer, and a terminal value (Done / Failed) when finished. No agent may skip, batch, or defer these writes, on the flat OR full layout, whether this task is run alone or as part of a pool dispatch. The full mandate, the exact command for each transition, and the why lives in references/state-execute.md § MANDATORY: State-Write Protocol -- read it before Step 1 below. Skipping these writes is the single most common root cause of a task that shows Pending in the dashboard for its entire execution and then jumps straight to Done.

⚠️ Pre-flight Checks

Check 1: Locate Work and Task

1. Read first arg: if it starts with work- → use that work directory; if it starts with task- → treat as shorthand (single-work auto-select below)

2. If work arg not provided (or shorthand): enumerate works cross-worktree: run bash .aid/runtime/scripts/works/enumerate-works.sh (main tree + every git worktree; never the local .aid/works/ glob, which is empty on master), taking each record's field-1 work_id — single record → auto-select; multiple records → list them, ask user to choose; zero records on any worktree → STOP. "No works found. Run /aid-describe first."

3. Read second arg (or first arg when shorthand): the task-NNN identifier; also resolve delivery-NNN from the task identifier or from the Source field

   Locate + enter the work's worktree. Now that the work id is resolved (steps 1-3 above) and before step 4 below reads anything under .aid/works/{work}/…, follow .aid/runtime/templates/downstream-worktree-entry.md to normalize the work id to its bare work-NNN branch name, locate the worktree (which always exits 0 and returns <path>\t<status>), and enter the returned path. Keep the defensive empty-path/non-zero backstop that stops rather than operate blindly — it should not fire against the real helper. Never create a new worktree — creation belongs to the work-starting skills only.

4. Detect the layout (per-work, DECLARED first; additive — does not change the full-path resolution below). Read pipeline.path from the work-root STATE.yml: lite → flat, full → nested. Infer from file presence ONLY when no value is declared, which means an un-migrated work:

   • Full path (nested): .aid/works/{work}/deliveries/ exists → tasks live at deliveries/delivery-NNN/tasks/task-NNN/DETAIL.md.
   • Flat path (feature-001, single-delivery): .aid/works/{work}/tasks/task-NNN/DETAIL.md exists directly under the work root AND no deliveries/ wrapper under it → the delivery is always the synthesized delivery-001 (no per-task STATE.yml; task mutable cells live in the work-root STATE.yml's tasks_lifecycle mapping instead — see ## Workspace below).

5. Find the task definition at the layout-appropriate path from step 4.

6. Task not found → STOP. List available tasks.