Package & Ship

State machine: IDLE → SELECTING → VERIFYING → PACKAGING → DONE.

Package completed deliveries into a release.

Agents Involved

Default executor: aid-operator (orchestrates the release: verifies build, packages artifacts, updates statuses).
Specialist consults (optional): aid-tech-writer for release notes / changelog, aid-operator if CI/CD configuration changes are needed during release, aid-reviewer for final pre-release verification.

Argument-Hint

/aid-deploy work-NNN
/aid-deploy "<free-form description of what to ship>"

Two invocation modes (invocation-context detection; see ## ⚠️ Pre-flight Checks Step 0):

work-NNN present -- the existing pipeline path below runs unchanged (IDLE -> SELECTING -> VERIFYING -> PACKAGING -> DONE, post-Execute). Required: work ID. If only one work exists, auto-select it.
No work-NNN, a free-form description instead -- the Lite-path direct-entry shortcut: binds {name}=aid-deploy, {verb}=deploy, {artifact}="" (bare verb), {description}=<the given text>, then delegates to the shared shortcut engine (.aid/runtime/templates/shortcut-engine.md, INTAKE -> ... -> APPROVAL-HALT), scaffolding a flattened Lite work and running the grading gates. Never executes -- it halts for approval; this shortcut entry does not replace the pipeline role below, it adds a second, independent entry point to the same skill directory.

Workspace

.aid/
  knowledge/
    STATE.md                   ← Q&A, Review History (settings → .aid/settings.yml), Q&A (Pending)
.aid/works/{work}/
  STATE.yml                     ← Deploy State (current operation status, history)
  packages/                    ← product (one file per release)
    package-001-{name}.md
    package-002-{name}.md
  PLAN.md                      ← deliveries and sequencing
  deliveries/delivery-NNN/tasks/task-NNN/  ← full path: task files with statuses
  tasks/task-NNN/                          ← lite path: task files with statuses (no delivery-NNN/ nesting)
  features/                    ← feature SPECs

Accuracy note (schema shape mismatch, not resolved by this task). work-state-template.yml does carry a deploy key, but its shape is a sequence of per-delivery records (delivery / state / pr / kb_updated / tag / notes, "aid-deploy only... never derived from child files"), not the single Status/Active-Package/History state machine this skill's Deploy State below describes (Idle -> Selecting -> Verifying -> Packaging -> Done, with an active-package pointer). The two shapes do not line up key-for-key; this is a schema gap surfaced by the refactor, flagged here rather than papered over. The deploy key is the closest real target and the sole legal AUTHORED write point for this skill's state, but a literal "Status:"/"Active Package:" read/write against it does not map one-to-one onto its declared fields.

⚠️ Pre-flight Checks

Step 0: Invocation-context mode detection

work-NNN argument present → proceed with Steps 1–6 below (the existing pipeline path; untouched).
No work-NNN argument, but a free-form description was given instead → the shortcut-scaffold path (see ## Argument-Hint above): bind {name}=aid-deploy, {verb}=deploy, {artifact}="", {description}=<the given text>, then delegate directly to .aid/runtime/templates/shortcut-engine.md § State: INTAKE — Steps 1–6 below do not run for this path (that pre-flight belongs to the post-Execute pipeline role, not the shortcut entry).
Neither work-NNN nor a description → print the ## Argument-Hint usage block and exit.

Verify .aid/ workspace exists.
Resolve work directory: if the work-NNN argument was given, use that work directory; if not (single-work auto-select), 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." Then locate + enter the work's worktree, before item 3 below reads work STATE.yml: 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. (Applies only to this work-NNN pipeline path — the free-form shortcut mode in Step 0 does not reach here.)
Read work STATE.yml's Deploy State (deploy key -- see the Workspace accuracy note above) (or create it if absent).
Read PLAN.md — identify deliveries and their statuses.
Check work STATE.yml's Tasks State (derived view) — check statuses and grades.
If Deploy State shows an active package → resume from that step (see State Detection).

State Detection

Read work STATE.yml's Deploy State (deploy key):

Status: Idle → IDLE state (start new package; see references/state-idle.md)
Status: Selecting → SELECTING state (resume delivery selection; see references/state-selecting.md)
Status: Verifying → VERIFYING state (resume verification; see references/state-verifying.md)
Status: Packaging → PACKAGING state (resume packaging; see references/state-packaging.md)
Status: Done → Re-run mode (see Re-run section)

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

IDLE / first run:

[State: IDLE] — No active release; begin assessing eligible deliveries.
aid-deploy  ▸ you are here
  [● IDLE ] → [ SELECTING ] → [ VERIFYING ] → [ PACKAGING ] → [ DONE ]

SELECTING:

[State: SELECTING] — Presenting eligible deliveries for user to include in this release.
aid-deploy  ▸ you are here
  [✓ IDLE ] → [● SELECTING ] → [ VERIFYING ] → [ PACKAGING ] → [ DONE ]

VERIFYING:

[State: VERIFYING] — Running full build, tests, and lint against selected deliveries.
aid-deploy  ▸ you are here
  [✓ IDLE ] → [✓ SELECTING ] → [● VERIFYING ] → [ PACKAGING ] → [ DONE ]

PACKAGING:

[State: PACKAGING] — Producing release artifacts per infrastructure.md § Deployment.
aid-deploy  ▸ you are here
  [✓ IDLE ] → [✓ SELECTING ] → [✓ VERIFYING ] → [● PACKAGING ] → [ DONE ]

DONE:

[State: DONE] — Release complete; all deliveries and tasks marked Shipped.
aid-deploy  ▸ you are here
  [✓ IDLE ] → [✓ SELECTING ] → [✓ VERIFYING ] → [✓ PACKAGING ] → [● DONE ]

Inputs

.aid/works/{work}/PLAN.md — deliveries, sequencing, success criteria
Per-task DETAIL.md — task scope; full path: .aid/works/{work}/deliveries/delivery-NNN/tasks/task-NNN/DETAIL.md; lite path: .aid/works/{work}/tasks/task-NNN/DETAIL.md
.aid/works/{work}/REQUIREMENTS.md § 11 — the ### Feature NNN sections; what was specified
Work STATE.yml ## Tasks State table — task statuses and review grades per task (both paths derive into this same rollup)
known-issues.md — if exists, check for Critical/High blockers
KB via INDEX.md — Read .aid/knowledge/INDEX.md, pull:
- infrastructure.md § Deployment — how to package, where to publish
- infrastructure.md § Source Control — VCS commands, branching strategy
- technology-stack.md § Commands — build, lint, test commands
- Any other docs INDEX summaries indicate are relevant

Dispatch Protocol

This skill follows the L1+L2+L3 subagent-visibility protocol (heartbeats, ETA timers, calibration). The full checklist lives in .aid/runtime/templates/dispatch-protocol-checklist.md; read it before any subagent dispatch in this skill.

Dispatch

State	Detail	Worker	Advance
IDLE	`references/state-idle.md`	`aid-operator`	→ SELECTING
SELECTING	`references/state-selecting.md`	`aid-operator`	→ VERIFYING
VERIFYING	`references/state-verifying.md`	`aid-operator`	→ PACKAGING
PACKAGING	`references/state-packaging.md`	`aid-operator`	→ DONE
DONE	`references/state-done.md`	`inline`	→ halt
RE-RUN	`references/state-re-run.md`	`inline`	→ halt

On state entry, print [State: NAME] + the "you are here" map from State Detection above. When a state completes, 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.

Quality Checklist

All selected deliveries have all tasks complete
All task grades meet minimum (from bash .aid/runtime/scripts/config/read-setting.sh --skill deploy --key minimum_grade --default A)
No Critical/High known-issues unresolved
Full build passes (not incremental)
Full test suite passes
Lint/format clean
Package created per infrastructure.md § Deployment
Package file saved with all sections filled
Release notes generated in package file
KB updates routed to .aid/knowledge/STATE.md ## Q&A (Pending) (not direct edits)
Delivery and task statuses updated to Shipped in work STATE.md
Work STATE.md ## Deploy State updated (Done + History entry)

aid-deploy

SKILL.md.claude/skills/aid-deploy/SKILL.md