# Amadeus > Run or resume the AI-DLC workflow on Pi Coding Agent. Use for structured product and software delivery, status, doctor, stage, phase, and scope flows, plus the intent and space verbs. - Skill: `amadeus-dlc/amadeus` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add amadeus-dlc/amadeus` - Raw SKILL.md: https://api.skillmd.com/api/skills/amadeus-dlc/amadeus/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: amadeus-dlc (https://skillmd.com/u/amadeus-dlc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/amadeus-dlc/amadeus --- # AI-DLC orchestrator for Pi This skill is the Pi-native entry to Amadeus. The deterministic engine owns all between-stage routing. Ask it for one directive, execute only that directive, report the result once, and repeat until it returns a terminal directive. Delegated implementation outside a named lifecycle stage — including swarm units, reviewed fixes, call-site migrations, and test builds — uses `amadeus-builder-agent`. Named `reverse-engineering` and `code-generation` lifecycle stages remain owned by `amadeus-developer-agent`. Project-local `.pi` skills and extensions run only after Pi's native project trust decision. Never approve that decision automatically, never edit Pi's trust store, and never describe project trust as a sandbox. ## Forwarding loop Forward the user's invocation text unchanged on the first call: ```sh bun .pi/tools/amadeus-orchestrate.ts next ``` ``, ``, and similar notation below denotes separate argv values, not shell text interpolation. Never concatenate external text into a command string. Use the host tool's argv form when available; when Pi exposes only its shell command field, apply POSIX shell quoting to every external value before constructing the command. Shell metacharacters in a user description are data and must never become syntax. This is a hard routing rule for every invocation, including after compaction and while an intent is active. The first engine call must contain every token from the current skill invocation. A bare `next` is a protocol violation when the invocation contains flags or free text. In particular: - `--status` → `bun .pi/tools/amadeus-orchestrate.ts next --status` - `--doctor` → `bun .pi/tools/amadeus-orchestrate.ts next --doctor` - `--resume` → `bun .pi/tools/amadeus-orchestrate.ts next --resume` - `--autonomy ` → `bun .pi/tools/amadeus-orchestrate.ts next --autonomy ` `--autonomy` declares the Intent's autonomy mode as part of the invocation, including the invocation that births the intent. Forward it unchanged; the engine owns the decision. `none` / `semi` are recorded through the canonical write path and take effect at once. `full` is never granted by the flag — the run prints the grant ceremony (`bun .pi/tools/amadeus-bolt.ts preview-autonomy`, then `bun .pi/tools/amadeus-bolt.ts set-autonomy --mode full --confirmed-display-digest `) and stops there. Never supply the flag on the user's behalf, and never infer autonomy from a previous answer: an autonomous ruling is only ever the engine executing a recorded human declaration. See `docs/reference/24-intent-autonomy.md`. An active intent does not override a utility flag. A terminal utility directive must be printed and stopped; it never falls through to the current stage. For a stage directive, report exactly once after its declared completion conditions are satisfied: ```sh bun .pi/tools/amadeus-orchestrate.ts report --stage --result ``` Treat the directive returned by `report` as the next loop step. Continue for `committed`, `run-stage`, `invoke-swarm`, and `print`. Stop for `ask`, `select-intent`, `error`, `parked`, `await-completion`, and `done`. Never call state-transition tools directly. ## Directive handling - `print`: run exactly the command named in the message. If it says to continue, run `next` again; otherwise print the result and stop. - `run-stage`: read the named persona, support personas, stage file, present consumes, and applicable rules. Produce only the declared outputs. Respect `consumes_absent`; never invent an absent artifact; required output paths are mandatory; optional output paths are candidates governed by the stage instructions. Pass only artifact paths that exist to reviewers and completion checks. `directive.depth` (when present) is the workflow's resolved depth level — pass it to the stage body's depth-scaled guidance instead of re-deriving depth. - `invoke-swarm`: use the Pi child-execution resource at `.pi/drivers/amadeus-pi-driver.ts` through the deterministic swarm protocol. Resolve the driver before preparing worktrees. Never pretend dispatch succeeded when the driver is missing, incompatible, or returns no accepted native handle. When the directive carries both `prepared_batch` and `retry_unit`, skip driver resolution and preparation. Acquire from the existing batch with `bun .pi/tools/amadeus-swarm.ts acquire --batch --idempotency-key `, verify the unconfirmed permit names `directive.retry_unit`, dispatch only that permit, and immediately confirm it with the accepted native handle. A partial pair is an invalid directive. - `ask`: render `directive.question` as numbered prose using `question-rendering.md`, then end the turn. For a fresh-workflow routing question (`Starting a ...` or `No stock scope clearly fits ...`), preserve the original description from the first invocation. After a scope confirmation, re-run `next --scope `; after a compose choice, re-run `next compose `. Do not send either answer to verdict-only `report`. For a resume question, pass the resolved answer through `report --user-input ""`. When another question names a continuation command, run that exact command once. - `execute-advisory-handoff`: the advisories at `directive.stage` were already answered `run-now` — the choice is on the record, so do NOT present a question. Run `/amadeus --stage --single` once for each slug in `directive.handoff_stages`, in array order, then re-run `next`; do not call `report`. If `directive.handoff_stages` is empty, no advisory names a destination: report the standing hold using each `directive.advisories[].message` and `directive.advisories[].result`, and stop. Opening a handoff stage never releases the hold — the hold lifts only when the declaring plugin's own evaluator returns no-hold on a later `next`. - `execute-failure-election`: Construction Unit failure with an Intent Autonomy Mode of `semi` or `full` (which derive an `auto` solo-election trigger; `none` derives `manual`). This is work, not a question: do NOT present Retry/Skip/Abort. Write a definition JSON carrying `electionId`, `kind`, `voters` and a one-element `questions[]` whose entry sets `questionId` to the fixed id `q-failure-ruling`, `text` to the failure summary the directive carries, and `choices` mapped deterministically from `directive.choices` (`internalNo` = 1-based position, `label` = the choice text), plus `schemaVersion: 2`, then run `bun .pi/tools/amadeus-election.ts open --trigger auto --file `. `--file` is REQUIRED. Drive the election to a ruling, then commit it through the ordinary ask report path: `report --user-input` with the ruling (`retry` / `skip` / `abort`). If the CLI answers `{"opened":null,"reason":"solo-election-manual-trigger-required"}`, or the election does not converge (hold / split / interrupt / CLI error), fall back to the existing halt-and-ask and commit the human ruling the same way. - `await-advisory-choice`: this is the human question route only; an advisory that already carries its answer arrives as `execute-advisory-handoff` instead. Run `bun .pi/tools/amadeus-log.ts advisory-decision --stage "" --instances ""` first, then render `directive.question` and its two `directive.options` as numbered prose using `question-rendering.md`, and end the turn. On the answer turn, confirm the choice deterministically: run `bun .pi/tools/amadeus-advisory-choice.ts record --advisory-instance "" --choice ""` once per answered instance, then re-run `next`. `record` binds the receipt to the latest real human turn and refuses with a reason on stderr rather than dropping the choice; a repeat of the same choice is idempotent, so a retry never re-asks the human. Never paraphrase the answer into a choice the human did not pick, and never re-present an instance `record` has already accepted. - `select-intent`: render the supplied options and stop. Pass the opaque selection token and the exact answer as separately quoted argv values to the command named by the directive. - `error`: Print `directive.message` verbatim and STOP. Do not recover, retry, or smooth it over, and do not invent a new question or a new gate — the message is the user-facing error. - `parked`: state that the workflow is parked and can resume with `/skill:amadeus --resume`. - `await-completion`: the workflow's terminal completion transaction has not settled yet — it is still uncommitted, or a completion authority declined to settle it. Print `directive.reason` verbatim (it names the reason and the command that settles it) and stop. This is an expected waiting state, not a failure. - `committed`: a `report` transition landed and the loop continues. Run `next` again; never present it as a completion. - `done`: present the completion summary and stop. Only a terminal completion emits this; a successful `report` acks with `committed`. Only Pi input events whose native source is `interactive` establish a human turn. RPC input, extension input, tool results, and custom messages do not answer questions or approve gates. ## Stage execution Load `.pi/amadeus-common/protocols/stage-protocol.md` for every stage. Load its recovery companion on resume or after a mid-stage change, and its governance companion at phase boundaries. When a `run-stage` directive carries `directive.phase_boundary`, load the governance companion and write `/verification/phase-check-.md` before reporting approval. The field is computed after scope overrides, so it also covers an early phase exit where the phase's usual final stage was skipped. Never report first and try to repair a rejected transition afterward. For a per-unit directive, write only beneath the current unit's declared construction path. On a normal per-unit directive, run the body and any declared reviewer inside its runtime-scoped read-only evidence boundary, then re-run `next` without reporting. `gate:false` suppresses only the human gate and §13; it never suppresses the reviewer. `review_only:true` skips the stage body and runs only the declared reviewer for the current unit, then re-runs `next` without reporting. A `gate:true` per-unit re-entry means every body and verdict already exists: do not regenerate either; run completion verification and §13, then present the single stage gate. A validated `READY` verdict is required; a failed review validation establishes no trustworthy verdict. When a stage gate is open, present exactly: 1. Approve — commit the stage transition 2. Request Changes — remain in the stage and revise An approval is reported with the exact human choice. A rejection stays within the stage's Keep/Modify/Redo loop and is not reported as completion. ## Pi lifecycle contract The project extension at `.pi/extensions/amadeus.ts` adapts Pi's public Extension API to the shared core. It is required infrastructure, not an optional enhancement. - Registration is all-or-nothing. Partial lifecycle registration must block progression and remain visible through read-only diagnostics. - Mandatory lifecycle events are journaled before commit. The core commit receipt, not the journal alone, establishes success. - `agent_settled` is the only automatic continuation trigger. - Tool start/end identities must match. Raw arguments and results do not belong in audit output. - Compaction recovery uses the canonical core checkpoint, never the model's summary as authoritative state. - A required extension or driver failure is fail-closed. Do not silently fall back to a manual or unsupported path and report success. ## Construction swarm on Pi Pi has no built-in subagent primitive. The packaged child driver is the native execution binding; the deterministic swarm referee remains the authority on queueing, dependency readiness, convergence, and merge eligibility. For each granted batch: 1. Resolve with `bun .pi/tools/amadeus-swarm.ts resolve --harness pi`. A `claude-ultra` request degrades only through the referee's declared path; `codex-ultra` and unsupported values must follow the same shared resolution contract. 2. Prepare the exact batch and concurrency granted by the directive. For a multi-repository intent, pass the directive's repository as `--repo `; never guess an omitted repository. 3. Acquire one permit per ready unit — keep acquiring until the referee reports `capacity-exhausted` or `no-ready-unit`, and acquire again after each settle frees a slot; `finalize` rejects a pool that still holds queued units — and dispatch each permit through the packaged Pi child driver with `persona: "amadeus-builder-agent"`. Confirm only a driver-accepted dispatch with its native handle. 4. Run the referee's declared check, then settle and release the corresponding attempt exactly once. 5. Finalize only after the pool is terminal, using `bun .pi/tools/amadeus-swarm.ts finalize --batch --units --claimed --check-cmd "" [--repo ] [--target ] [--strategy ]`. A failed or unverifiable unit halts for the shared failure protocol; it is never promoted as converged. 6. `--batch` is never guessed or re-derived: pass `directive.batch`, the engine's 1-origin batch identity and the durable Unit Pool id every later call for this batch is keyed by. `--check-cmd` and the optional `--test-file` are the opposite — the engine never supplies them, the convergence check is conductor knowledge: take the project's own build/test command from the team practice files under `amadeus/spaces//memory/` (Testing Posture / Tech Stack) and the protected spec from the unit's own test plan in the intent record. When neither names one, ask the human before dispatching rather than inventing a command. **Swarm source handoff.** After the assigned verification succeeds and before reporting success, each Unit worker creates a source-only Git commit in its assigned worktree containing only implementation and test changes. Workers never stage or commit `amadeus/` state, audit, runtime, or other workflow metadata. For a multi-repository batch, the conductor passes the same `--repo ` to `finalize` that it passed to `prepare`. `finalize` accepts optional `[--target ] [--strategy ]`; the default target is the base captured by `prepare` (target `main` for a default prepare) and the default strategy `squash`. When `prepare` uses a non-default `--base `, that captured base is already the delivery target — passing the same branch explicitly as `finalize --target ` is redundant but harmless. `finalize` reconciles workflow metadata first, then integrates the committed worker source. If a source merge fails, do not report success or continue the forwarding loop; use the shared `halt-and-ask` failure seam. Every child is confined to its assigned worktree and must not run Git operations outside it. Retry authority comes only from the referee's retry command and its finite budget. ## Native resource and trust rules The packaged harness descriptor is generated from the authored manifest and is the expected resource catalog. Never derive expected files from an observed installation or distribution tree. All resource paths must remain normalized, project-relative, and beneath `.pi/`. Missing, extra, changed, case-fold-colliding, symlinked, or non-regular resources are a hard compatibility failure. The extension and skill are loaded by Pi after native project trust. The driver is an Amadeus-internal resource and must not be auto-loaded as an extension. ## Resume and status Use the same engine entry for all utilities: ```sh bun .pi/tools/amadeus-orchestrate.ts next --resume bun .pi/tools/amadeus-orchestrate.ts next --status bun .pi/tools/amadeus-orchestrate.ts next --doctor ``` If an active intent exists, default to continuing it. Offer a new intent only for clearly unrelated work. Route explicit workflow-plan reshaping through the engine's compose path; never edit stage status fields by hand. ## Intent birth and unrelated work On a fresh workspace, follow the engine's `print` directive and run the exact `intent-birth` command it names. When unrelated work arrives while an intent is active, offer a second intent and wait for explicit confirmation. On approval, route it through: ```sh bun .pi/tools/amadeus-orchestrate.ts next --new-intent --scope "" ``` Then run the `intent-birth` command named by the returned directive. Do not construct or mutate intent state directly.