aid-detail

Break deliverables into small, dependency-driven, typed tasks -- each one a reviewable unit. The ultimate breakdown. Use this skill when a delivery has been planned and the actual work items are neede

SKILL.md

GitHub

Detail — The Ultimate Breakdown

Break each deliverable from PLAN.md into small, sequential, testable tasks. Each task = one agent session = one reviewable unit = one human review.

⚠️ Pre-flight Checks

Check 1: Locate Work

  1. If arg provided → use that work directory
  2. If no arg → 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
  3. Single record → auto-select it
  4. Multiple records → list them, ask user to choose
  5. Zero records on any worktree → STOP. "No works found. Run /aid-describe first."

Locate + Enter the Work's Worktree

As soon as Check 1 resolves the work id and before Check 2 checks for .aid/works/{work}/PLAN.md, follow .aid/runtime/templates/downstream-worktree-entry.md to normalize <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.

Check 2: Verify PLAN.md Exists

  1. Check for .aid/works/{work}/PLAN.md
  2. If missing → STOP. "No PLAN.md found. Run /aid-plan first."

Check 3: Verify Not in Plan Mode

  • ✅ Default or Auto-accept edits → Proceed.
  • ❌ Plan mode → STOP.

State Detection

State detection reads the files on disk, every run; nothing remembered from an earlier run counts as state.

  • No deliveries/delivery-NNN/tasks/task-NNN/DETAIL.md exists under .aid/works/{work}/ → FIRST-RUN
  • At least one deliveries/delivery-NNN/tasks/task-NNN/DETAIL.md exists → REVIEW
  • Tasks complete and grade ≥ minimum → DONE

Print the state-entry line and "you are here" map:

FIRST-RUN:

[State: FIRST-RUN] — No task files yet; begin proposing task breakdown per deliverable.
aid-detail  ▸ you are here
  [● FIRST-RUN ] → [ REVIEW ] → [ DONE ]

REVIEW:

[State: REVIEW] — Existing tasks found; re-review against current PLAN.md and SPECs.
aid-detail  ▸ you are here
  [✓ FIRST-RUN ] → [● REVIEW ] → [ DONE ]

DONE:

[State: DONE] — Task list approved and meets minimum grade.
aid-detail  ▸ you are here
  [✓ FIRST-RUN ] → [✓ REVIEW ] → [● DONE ]

Dispatch

State Detail Worker Advance
FIRST-RUN references/first-run.md aid-architect → REVIEW
REVIEW references/review.md aid-reviewer → DONE
DONE — inline → halt

Load the Detail file for the detected state and execute it.

On state completion, route by its **Advance:** type (per state-machine-chaining.md):

  • CHAIN → begin the next state's reference doc within the same invocation; no exit.
  • PAUSE-FOR-USER-ACTION / PAUSE-FOR-USER-DECISION → print the pause reason + resume command and exit.
  • HALT → print the closing summary and exit (DONE prints the task summary).