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.claude/skills/aid-detail/SKILL.md
GitHubDetail — 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
- If arg provided → use that work directory
- 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 onmaster), taking each record's field-1work_id - Single record → auto-select it
- Multiple records → list them, ask user to choose
- Zero records on any worktree → STOP. "No works found. Run
/aid-describefirst."
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
- Check for
.aid/works/{work}/PLAN.md - If missing → STOP. "No PLAN.md found. Run
/aid-planfirst."
Check 3: Verify Not in Plan Mode
- ✅
DefaultorAuto-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.mdexists under.aid/works/{work}/→ FIRST-RUN - At least one
deliveries/delivery-NNN/tasks/task-NNN/DETAIL.mdexists → 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).