@hybridlabor-api/aos 4.1.0 → 4.2.0

package/CLAUDE.md

@@ -15,6 +15,53 @@ Ask one question first: **do the workers need to see each other?**
 
 "Runs in parallel" is not a reason to reach for a team — subagents already run in parallel. Peer communication and dynamic task claiming are the only things a team adds.
 
+## Delegating to an external CLI
+Some work is cheaper on another provider's compute (bulk scaffolding, exhaustive
+test generation, long-context reads that distil to a digest). None of that tooling
+ships with AOS — it depends on CLIs and Claude Code plugins the user installed
+separately, so check what is actually present instead of assuming.
+
+**Prefer a plugin's delegation subagent over shelling out to its CLI.** Where one
+is installed it already handles the wrapper flags, cost discipline, and digest
+contract: `antigravity:antigravity-delegate` (agy), `opencode:opencode-rescue`,
+`codex:codex-rescue`. These are Claude Code plugins — on another harness, or a
+machine without them, calling the CLI directly is the only path.
+
+**Delegate only above the break-even.** A small, self-contained, or
+judgement-heavy task costs more to hand off and verify than to just do. Keep the
+digest, not the raw output.
+
+**Give it a real timeout.** Measured 2026-09: a trivial headless `agy` prompt
+took **605s**. `agy-delegate` defaults to `--print-timeout 5m`, so it aborts at
+300s and reports an empty body while the answer is still coming — pass
+`--timeout 15m` for anything non-trivial. A short timeout does not read as
+"slow", it reads as "broken".
+
+**Match the model to the task, not to the default.** `agy-delegate`'s tiers map
+to models that can go stale (its built-in `flash` still points at Gemini 3.7
+while 3.8 ships). Either pass `--model "<exact name from \`agy models\`>"` per
+call, or remap the tiers once via the plugin's own options — as env vars those
+belong in `~/.zshenv`, not `~/.zshrc`, since `.zshrc` is only sourced for
+interactive shells and tool-invoked ones would never see them:
+
+| Work | Model |
+|---|---|
+| media, fast/mechanical coding, boilerplate | `Gemini 3.8 Flash (Medium)` → `CLAUDE_PLUGIN_OPTION_TIER_FLASH` |
+| trivial one-liners | `Gemini 3.8 Flash (Low)` → `CLAUDE_PLUGIN_OPTION_TIER_FLASH_LO` |
+| review, architecture, hard reasoning | `Claude Sonnet 4.6 (Thinking)` → `CLAUDE_PLUGIN_OPTION_TIER_PRO` |
+
+Adversarial review is the case that most repays a stronger model: a Flash tier
+tends to agree with what it is shown, which is the one thing a reviewer must
+not do. Re-check the names against `agy models` after an agy upgrade — the id
+carries both the version and the effort suffix.
+
+**Verify the result, never the status field.** A timed-out delegation returns
+`{"status": "SUCCESS", "usage": {"total": 0}}` with an empty body — success by
+every field except the one that matters, and the zero token counts are *not*
+proof the prompt never arrived (headless usage reporting is simply unpopulated).
+Check the returned content, treat an empty body as failure regardless of status,
+and never report a delegated step as done on the strength of its own self-report.
+
 ## Safety Gate — mechanically enforced, not advisory
 `git push`, `npm publish`, `npm version`, and recursive `rm` are blocked by `.claude/hooks/go-gate.mjs` (registered in `.claude/settings.json`) unless your immediately preceding message is the literal word **GO**. This is a hook, not a rule I read and try to follow — it cannot be argued around, and it doesn't depend on this file being loaded.
 - A subagent does not inherit its orchestrator's GO.

package/GEMINI.md

@@ -47,4 +47,12 @@ Ask one question first: **do the workers need to see each other?**
 - **Yes — they must react to each other, or claim work dynamically from a shared list** → an orchestrated agent team (via `send_message`). Currently only `/bdbrainstorm` qualifies, where the spec demands a real debate rather than parallel monologues. True Agent Teams were evaluated and deferred for `/startcycle-graph` (needs an interactive session; the graph runs headless) — see `.agents/graph.md` and F-17's addendum in `docs/sessions/audit-agents.md`.
 - **Small task** → do it yourself. A two-file edit needs no agents.
 
-"Runs in parallel" is not a reason to reach for a team — subagents already run in parallel. Peer communication and dynamic task claiming are the only things a team adds.
+"Runs in parallel" is not a reason to reach for a team — subagents already run in parallel. Peer communication and dynamic task claiming are the only things a team adds.
+
+## 9. Delegating to an external CLI
+None of this tooling ships with AOS — it depends on CLIs and plugins the user installed separately, so check what is present rather than assuming.
+- **Prefer a plugin's delegation subagent over shelling out to its CLI.** Where installed, it already handles the wrapper flags, cost discipline, and digest contract: `antigravity:antigravity-delegate` (agy), `opencode:opencode-rescue`, `codex:codex-rescue`. These are Claude Code plugins — on another harness, calling the CLI directly is the only path.
+- **Delegate only above the break-even.** A small, self-contained, or judgement-heavy task costs more to hand off and verify than to just do. Keep the digest, not the raw output.
+- **Give it a real timeout.** Measured 2026-09: a trivial headless `agy` prompt took **605s**. `agy-delegate` defaults to `--print-timeout 5m`, so it aborts at 300s and reports an empty body while the answer is still coming — pass `--timeout 15m` for anything non-trivial.
+- **Match the model to the task, not to the default.** The wrapper's tiers map to models that go stale (built-in `flash` still points at Gemini 3.7 while 3.8 ships). Media and fast/mechanical coding → `Gemini 3.8 Flash (Medium)`; trivial → `Gemini 3.8 Flash (Low)`; review, architecture and hard reasoning → `Claude Sonnet 4.6 (Thinking)`. Adversarial review most repays the stronger model: a Flash tier tends to agree with what it is shown, which is exactly what a reviewer must not do. Pass `--model` per call, or remap the tiers once via `CLAUDE_PLUGIN_OPTION_TIER_{FLASH,FLASH_LO,PRO}` — in `~/.zshenv`, not `~/.zshrc`, which non-interactive tool shells never source. Re-check names against `agy models` after an upgrade.
+- **Verify the result, never the status field.** A timed-out delegation returns `{"status": "SUCCESS", "usage": {"total": 0}}` with an empty body — success by every field except the one that matters, and the zero token counts are *not* proof the prompt never arrived (headless usage reporting is simply unpopulated). Treat an empty body as failure regardless of status, and never report a delegated step as done on the strength of its own self-report.

package/README.md

@@ -5,13 +5,19 @@
 
 [![CI](https://github.com/hybridlabor-api/aos/actions/workflows/ci.yml/badge.svg)](https://github.com/hybridlabor-api/aos/actions)
 [![NPM Version](https://img.shields.io/npm/v/@hybridlabor-api/aos.svg)](https://www.npmjs.com/package/@hybridlabor-api/aos)
-[![runtime](https://img.shields.io/badge/node-20+-blue.svg)](https://github.com/hybridlabor-api/aos)
+[![NPM Downloads](https://img.shields.io/npm/dw/@hybridlabor-api/aos.svg)](https://www.npmjs.com/package/@hybridlabor-api/aos)
 [![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![skills](https://img.shields.io/badge/skills-154%20curated-brightgreen.svg)](https://github.com/hybridlabor-api/aos)
+[![GitHub stars](https://img.shields.io/github/stars/hybridlabor-api/aos?style=flat&color=gold)](https://github.com/hybridlabor-api/aos/stargazers)
+[![last commit](https://img.shields.io/github/last-commit/hybridlabor-api/aos.svg)](https://github.com/hybridlabor-api/aos/commits/main)
+
+[![skills](https://img.shields.io/badge/skills-169%20curated-brightgreen.svg)](docs/skills_table.md)
+[![MCPs](https://img.shields.io/badge/local%20MCPs-21-brightgreen.svg)](mcps/)
+[![harnesses](https://img.shields.io/badge/harnesses-9%20supported-blueviolet.svg)](#-installation)
+[![runtime](https://img.shields.io/badge/node-20+-blue.svg)](https://github.com/hybridlabor-api/aos)
 
-> **Supercharging AI coding agents with 154 hyper-curated skills, 21 local MCP wrappers, and a runnable multi-agent dispatcher graph.**
+> **Supercharging AI coding agents with 169 hyper-curated skills, 21 local MCP wrappers, and a runnable multi-agent dispatcher graph.**
 
-Welcome to **BDB Agent OS — AOS v4.0.0**: 154 curated skills, 21 local MCP wrappers, and a dispatcher graph that turns them into a real multi-agent build pipeline, not just a prompt library. Point it at a goal and it plans, builds, reviews, and ships through seven coordinated agent nodes — with a mechanically enforced gate before anything actually goes live.
+Welcome to **BDB Agent OS — AOS v4.0.0**: 169 curated skills, 21 local MCP wrappers, and a dispatcher graph that turns them into a real multi-agent build pipeline, not just a prompt library. Point it at a goal and it plans, builds, reviews, and ships through seven coordinated agent nodes — with a mechanically enforced gate before anything actually goes live.
 
 It is harness-neutral by design, not "optimized for one tool with others as an afterthought": the dispatcher graph runs on Claude Code's Dynamic Workflows, the same skills and MCP configuration install natively into **Google Antigravity, ChatGPT Codex / Codex CLI, Claude Desktop, Cursor, Aider, Roo Code, Cline, and Windsurf**, and the lightweight `/startcycle-graph-user` variant falls back to Claude Code's own subagents on any machine that has none of the above installed.
 
@@ -95,9 +101,9 @@ below for how the pipeline itself works.
 
 ---
 
-## 🌟 154 Optimized Skills
+## 🌟 169 Optimized Skills
 
-We started with a massive pool of over 1,400 raw AI skills. After rigorous testing, filtering, and refinement, we've distilled them down to a hyper-curated set of **154 Optimized Skills** (featuring a native OpenWiki documentation engine, the **memB local semantic memory brain**, and **Universal Agent Harness synchronization**).
+We started with a massive pool of over 1,400 raw AI skills. After rigorous testing, filtering, and refinement, we've distilled them down to a hyper-curated set of **169 Optimized Skills** (featuring a native OpenWiki documentation engine, the **memB local semantic memory brain**, and **Universal Agent Harness synchronization**).
 
 These skills are precision-engineered to ensure agents waste no time on redundant tasks and instead operate with maximum agency, strict architectural constraints, and robust context awareness.
 

package/THIRD_PARTY_NOTICES.md

@@ -127,6 +127,56 @@ SOFTWARE.
 
 ---
 
+## mattpocock/skills
+
+<https://github.com/mattpocock/skills> — MIT.
+
+The grilling family and the domain-modeling discipline it composes with:
+
+| In AOS | Upstream |
+|---|---|
+| `skills/global_config/grilling/` | `skills/productivity/grilling/` |
+| `skills/global_config/grill-me/` | `skills/productivity/grill-me/` |
+| `skills/global_config/grill-with-docs/` | `skills/engineering/grill-with-docs/` |
+| `skills/global_config/domain-modeling/` | `skills/engineering/domain-modeling/` (incl. `ADR-FORMAT.md`, `CONTEXT-FORMAT.md`) |
+
+`grilling`'s interview protocol and `domain-modeling` are carried over
+essentially verbatim; `grill-me` and `grill-with-docs` are rewritten to name AOS's
+own pipelines in their hand-off sections, but keep upstream's composition — both
+are thin wrappers that invoke the primitive rather than restating it. Upstream's
+`agents/openai.yaml` under `domain-modeling` is harness-specific to that project
+and was not carried over.
+
+`skills/global_config/ask-tim/` is derived from upstream's `ask-matt` router. It
+is not a copy: the flow it maps is AOS's own, since most of the skills on
+upstream's main flow have no AOS equivalent.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
 ## Note on `mcps/`
 
 Sub-repositories vendored under `mcps/` carry their own `LICENSE` files in

package/docs/skills_table.md

@@ -48,6 +48,7 @@
 | `subagent-driven-development` | Use when executing implementation plans with independent tasks in the current session |
 | `tdd-workflow` | Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle. |
 | `tmux` | Expert tmux session, window, and pane management for terminal multiplexing, persistent remote workflows, and shell scripting automation. |
+| `teamwork-preview` | Interactive 9-step prompt crafting and delegation protocol for autonomous multi-agent teams across harnesses. |
 
 #### 🎨 Frontend & UI/UX
 | Skill Name | Description |

package/installer.js

@@ -2554,6 +2554,21 @@ function injectHarnessRules() {
             log.step(`Installed GEMINI.md to ${path.join(geminiDir, 'GEMINI.md')}`);
         }, 'The harness injection below still runs.');
 
+        // Dispatcher scripts must land in ~/.claude/workflows/, because that is
+        // where the skills that route to them look: startcycle-graph's SKILL.md
+        // and teamwork-preview's both tell the model to call `Workflow` with
+        // scriptPath `$HOME/.claude/workflows/<name>.mjs`. installProjectHarness()
+        // copies them into a *project*, which only helps a project that opted into
+        // the local harness -- on a plain global install those paths did not exist
+        // at all, so the skill pointed at a file that was never delivered.
+        installStep(`install dispatcher workflows to ${path.join(homeDir, '.claude', 'workflows')}`, () => {
+            const workflowsSrc = path.join(srcDir, '.claude', 'workflows');
+            if (fs.existsSync(workflowsSrc)) {
+                copyDirRecursiveSync(workflowsSrc, path.join(homeDir, '.claude', 'workflows'));
+                log.step(`Installed dispatcher workflows to ${path.join(homeDir, '.claude', 'workflows')}`);
+            }
+        }, '/startcycle-graph and /teamwork-preview fall back to their prose protocols.');
+
         const startcycleWorkflowSrc = path.join(srcDir, '.agents', 'workflows', 'startcycle.md');
         const sources = installStep('read the global rule sources', () => ({
             globalRules: fs.readFileSync(geminiMdSrc, 'utf8'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "AOS — A Curated AI AGENT OS. Optimized agent skills and add-ons like memB, OpenWiki, Heimdall Token Saver, and Godmode architectures.",
   "main": "installer.js",
   "bin": {

package/skills/basic/bdbmediastorm/SKILL.md

@@ -26,9 +26,11 @@ Ideation must never be performed in isolation. Spawn specialized subagents to an
 
 ---
 
-## 2. Interactive `/grill-me` Technical Interview
+## 2. Interactive Technical Interview
 
-Before drafting signal flow diagrams or system configs, execute a mandatory `/grill-me` interactive interview. Deeply challenge the user's technical assumptions and hardware readiness by asking targeted questions:
+Before drafting signal flow diagrams or system configs, **invoke the `grill-with-docs` skill** (or `grill-me` when there is no working directory) and run it to completion. Those skills hold the interview protocol — design tree, frontier rounds, numbered questions each with a recommended answer — and it is not restated here.
+
+What this domain adds to that protocol: deeply challenge the user's technical assumptions and hardware readiness. The frontier questions for a show-control build are:
 
 * **Signal & Network Protocols:**
   - What protocols govern data movement? (OSC, Art-Net, sACN, MIDI, SMPTE Timecode, NDI)?
@@ -48,7 +50,7 @@ Before drafting signal flow diagrams or system configs, execute a mandatory `/gr
 
 ## 3. Target Directory & Scaffolding
 
-After aligning on system architecture through the `/grill-me` process:
+After aligning on system architecture through the grilling interview:
 1. **Confirm Output Directory:** Ask the user: *"In which project directory should the output show-control plan and architecture files be stored?"*
 2. **Scaffold Foundational Files:** Once confirmed, write the core show specification files (`agent.md`, `signal-flow.md`, `network-patch.json`, `failover-matrix.md`).
 
@@ -94,7 +96,7 @@ BDB MediaStorm is the master ideation and brainstorming engine for live show-con
 - **Exclude:** Do not use for generating video timelines or 3D meshes.
 
 ## Core Process
-1. Run an interactive `/grill-me` session to challenge assumptions about protocols, hardware, and bandwidth.
+1. Run `grill-with-docs` (or `grill-me`) to challenge assumptions about protocols, hardware, and bandwidth.
 2. Scaffold foundational files (`agent.md`, `signal-flow.md`, `network-patch.json`).
 3. Generate a strict Mermaid.js signal flow diagram mapping all protocols.
 4. Document a main/backup redundancy and failover matrix.
@@ -115,7 +117,7 @@ BDB MediaStorm is the master ideation and brainstorming engine for live show-con
 
 ## Verification
 
-- [ ] `/grill-me` session was completed with answers regarding protocols and bandwidth.
+- [ ] The grilling interview was completed with answers regarding protocols and bandwidth.
 - [ ] Output includes a Mermaid.js signal flow diagram.
 - [ ] A dedicated failover/blackout mechanism is documented.
 

package/skills/basic/startcycle/SKILL.md

@@ -80,6 +80,27 @@ Run only the streams the goal actually needs. A plain backend feature does not n
 
 3c is for TouchDesigner, show-control, DMX/grandMA3, 3D, or other media-pipeline goals — most goals are not this. Skip it unless the plan actually calls for it.
 
+> **Injecting a specific skill.** `/startcycle --skill=<name> <goal>`
+> (repeatable, quote a name with spaces) forces that skill into this run as
+> a hard requirement — for a private skill of your own that isn't part of
+> any build agent's own `skills:` frontmatter. Since this variant has no
+> dispatcher script or `state.json` to carry it automatically, the invoker
+> does the work `startcycle-graph`'s script does for you: extract the
+> `--skill=` flag(s) from the invocation text before anything else runs,
+> confirm each name resolves to a real `SKILL.md` (under
+> any harness's global skills directory — `~/.claude/skills/<name>/`,
+> `~/.agents/skills/`, `~/.codex/skills/`, `~/.cursor/skills/` or `~/.roo/skills/`
+> — or this project's own `skills/` tree) — stop
+> and tell the user if one doesn't, don't silently proceed without it —
+> note the validated list in `00_execution_plan.md`, and include it as a
+> **hard requirement, not a suggestion** in each Build stream's dispatch
+> prompt at step 3. Reviewer (step 4) checks the resulting artifacts for
+> evidence the skill was actually applied, not just available, and treats
+> an ignored mandate as a contract-misread finding. See
+> [`.agents/graph.md`](../../../.agents/graph.md)'s "Mandatory Skill
+> Injection" section for the full rationale — this is the same mechanic,
+> just invoker-driven instead of script-driven.
+
 ### 4. Reviewer
 - **Agent**: `reviewer`
 - **Reads**: the artifacts each build stream produced (01/02/03) and the plan's stated contract (`00_execution_plan.md`) — nothing else. Never the goal directly, never a build agent's own claim that it's done; passing that claim through biases the review toward agreement.

package/skills/basic/startcycle-graph/SKILL.md

@@ -21,12 +21,21 @@ several fields the schema doesn't define at all). Fix it first:
 mkdir -p .agents
 [ -f .agents/graph.md ] || cp "$HOME/.agents/graph.md" .agents/graph.md
 [ -f .agents/state.schema.json ] || cp "$HOME/.agents/state.schema.json" .agents/state.schema.json
+[ -f .agents/nodes.json ] || cp "$HOME/.agents/nodes.json" .agents/nodes.json
 ```
 
-If `$HOME/.agents/graph.md` or `$HOME/.agents/state.schema.json` doesn't
-exist either, stop and tell the user: this machine has no canonical copy of
-the graph contract to bootstrap from, and `/startcycle-graph` will produce a
-non-conforming `state.json` until one is installed. Don't silently proceed.
+`nodes.json` is not optional and is the one that fails loudest: it is the
+node registry the dispatcher loads as its very first step, and without it
+the run escalates immediately with *"`.agents/nodes.json` failed to load, or
+is missing required node id(s)"* — before Architect or any other agent has
+run. (Found exactly that way: a first run in a project that had followed
+this bootstrap step as it was previously written, which copied only the
+other two files.)
+
+If any of the three doesn't exist under `$HOME/.agents/` either, stop and
+tell the user: this machine has no canonical copy of the graph contract to
+bootstrap from, and `/startcycle-graph` cannot run correctly until one is
+installed. Don't silently proceed.
 (`.claude/agents/*.md`, the seven agent persona files, do NOT need this
 treatment — Claude Code resolves subagents from the user-level
 `~/.claude/agents/` fine without a project-local copy.)
@@ -37,9 +46,36 @@ yourself (e.g. `echo $HOME` or your own environment info) rather than
 hardcoding a username, giving
 `$HOME/.claude/workflows/startcycle-dispatch.mjs` — and `args` set to the
 goal text that follows `ARGUMENTS:` below this file's content. Pass the goal
-through verbatim. If there is no `ARGUMENTS:` text, pass no `args` (or
-`args: undefined`) — the workflow itself asks for a goal in that case rather
-than guessing one.
+through verbatim, including any `--skill=<name>` flag(s) it contains — the
+dispatcher script parses those itself (see below), do not strip or
+interpret them yourself. If there is no `ARGUMENTS:` text, pass no `args`
+(or `args: undefined`) — the workflow itself asks for a goal in that case
+rather than guessing one.
+
+**Injecting a specific skill.** `/startcycle-graph --skill=<name> <goal>`
+(repeatable, quote a name with spaces) forces that skill into this run as a
+hard requirement for the build nodes, validated to exist before anything
+else runs — this is how you make the pipeline use your own private skill
+that isn't part of `.agents/nodes.json`'s registry.
+
+`<name>` is the **exact skill directory name**, not a description — `ui-component`,
+not "the UI one". Two ways to find it without leaving the terminal:
+
+- `/ask-tim` — the routing skill; start there when you know the *job* but not the name
+- list the installed skills directly, if you half-remember the spelling. The installer
+  syncs the same set to every harness it detects, so use whichever path is yours:
+  `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.cursor/skills`, or
+  `~/.roo/skills`. `ls ~/.agents/skills` is the safest guess on an unknown machine —
+  that one is written on every install regardless of harness.
+
+A name that does not resolve halts the run before any agent works, and the
+error now lists installed near-misses rather than only saying "not found".
+That is deliberate: silently running without a skill you explicitly demanded
+is worse than stopping.
+
+See [`.agents/graph.md`](../../../.agents/graph.md)'s "Mandatory Skill
+Injection" section for the full mechanics; nothing about it needs handling
+in this router file, since `args` is passed through as raw text either way.
 
 Use `scriptPath`, not `name: "startcycle-dispatch"` — by-name lookup for a
 custom (non-built-in) workflow script has been observed to fail with

package/skills/basic/startcycle-graph-user/SKILL.md

@@ -29,6 +29,26 @@ Do not invent more structure than the task has. A two-file edit doesn't need
 a Plan node — just do it. This skill is for the cases actually shaped like a
 small graph, not an excuse to always draw one.
 
+## 1b. Injecting a specific skill (optional)
+
+`/startcycle-graph-user --skill=<name> <task>` (repeatable, quote a name
+with spaces) forces that skill into this run as a hard requirement — for a
+private skill of the user's own this throwaway graph would otherwise never
+know to reach for. Extract any `--skill=` flag(s) from the invocation text
+before step 1, confirm each name resolves to a real `SKILL.md` (under
+any harness's global skills directory — `~/.claude/skills/<name>/`,
+`~/.agents/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.roo/skills/` —
+or this project's own `skills/` tree if it has
+one) — stop and tell the user if one doesn't, never silently proceed
+without it — and include it as a **hard requirement, not a suggestion** in
+the Plan node's and every Worker node's prompt. The Review node checks the
+combined output for evidence the skill was actually applied, not just
+mentioned, and calls that out explicitly if it wasn't. Nothing about this
+gets persisted, same as everything else in this skill — it's a per-run
+instruction, not a contract. See
+[`.agents/graph.md`](../../../.agents/graph.md)'s "Mandatory Skill
+Injection" section for the same mechanic in the durable graph variant.
+
 ## 2. Detect what's available — before deciding how workers run
 
 ```bash
@@ -39,21 +59,53 @@ command -v codex     >/dev/null 2>&1 && echo codex
 
 This machine may have none of these — the skill (and whoever installed this
 package) cannot assume Antigravity, OpenCode, or a Codex plugin connector is
-present. Pick the worker path in this priority order, first one found wins:
-
-1. **agy present** → workers run via `agy-job start --tier flash [--yolo] "<task>"`
-   (or `pro` for harder reasoning) — see the `antigravity` skill for the exact
-   invocation pattern and cost discipline. Separate compute pool, zero
-   Anthropic tokens for the work itself.
-2. **opencode present** → route worker tasks through it the same way (its own
-   subagent/session primitive), if the project already uses it.
-3. **codex present** → same idea, via the Codex CLI's own task-delegation
-   surface if this project has that plugin wired up.
-4. **none present** → fall back to Claude Code's own `Agent` tool for each
+present.
+
+**Prefer a plugin's own delegation subagent over shelling out to its CLI.**
+If a delegation plugin is installed, it exposes a subagent that already
+handles the wrapper flags, the cost discipline, and the digest contract for
+you — reach for that first, and only drop to a raw CLI call when no such
+subagent exists:
+
+| CLI | Plugin subagent (preferred) | Raw fallback |
+|---|---|---|
+| agy | `antigravity:antigravity-delegate` | `agy-job start --tier flash [--yolo] "<task>"` |
+| opencode | `opencode:opencode-rescue` | the CLI's own session primitive |
+| codex | `codex:codex-rescue` | the Codex CLI's task-delegation surface |
+
+These subagents are **Claude Code plugins**, so they exist only when that
+harness is running *and* the plugin is installed. Check what is actually
+available rather than assuming — on any other harness, or a machine without
+the plugins, the raw CLI column is the only path. Neither column ships with
+AOS: both depend on tooling the user installed separately.
+
+Pick the worker path in this priority order, first one found wins:
+
+1. **A delegation plugin subagent is available** → use it (table above).
+   Separate compute pool, zero Anthropic tokens for the work itself, and the
+   wrapper reports failures in a shape the plugin already knows how to read.
+2. **The CLI is present but its plugin subagent is not** → call the CLI
+   directly per the raw-fallback column, following the `antigravity` skill's
+   invocation pattern and cost discipline.
+3. **None present** → fall back to Claude Code's own `Agent` tool for each
    worker, with an explicit `model: "haiku"` override. This is the only path
    that costs Anthropic tokens for the worker step, and the only one
    guaranteed to exist everywhere — it is the floor, not the default.
 
+**Give the delegation a real timeout.** Measured 2026-09: a trivial headless
+`agy` prompt took **605s**. `agy-delegate` defaults to `--print-timeout 5m`,
+so it aborts at 300s and reports an empty body while the answer is still on
+its way — pass `--timeout 15m` for anything non-trivial. Budget worker
+wall-clock accordingly; this is the single most likely reason a fan-out
+"fails" on a machine where the CLI is perfectly healthy.
+
+**Verify the delegation actually produced content — a status string is not a
+result.** A timed-out delegation returns `{"status": "SUCCESS", "usage":
+{"total": 0}}` with an *empty* body: success by every field except the one
+that matters. The zero token counts are not proof the prompt never arrived —
+headless usage reporting is simply unpopulated. Check the returned text
+itself, and treat an empty body as a failure no matter what the status says.
+
 **This decision happens here, in your own turn, via Bash — never inside a
 `Workflow` script.** A `Workflow` script's body has no shell or filesystem
 access (ambient `agent()`/`pipeline()` globals only), so it cannot itself
@@ -104,6 +156,8 @@ graph (`.agents/graph.md`) already does properly.
 | "The session is already on Opus, so the worker call inherits it fine." | That's exactly the cost this skill exists to avoid — force the tier explicitly every time. |
 | "This task has one obvious step, but a 3-node graph looks more thorough." | More nodes than the task needs is overhead, not rigor. Size the graph to the work. |
 | "I'll just call the Workflow tool and let the script figure out which backend to use." | The script can't — it has no shell access. That decision is yours, before the Workflow call, or not via Workflow at all. |
+| "The CLI is on PATH, so I'll shell out to it directly." | If its plugin subagent is installed, that's the supported path — it already handles the wrapper flags and cost discipline. Shell out only when no subagent exists. |
+| "The wrapper returned SUCCESS, so the work is done." | A failing delegation has returned `SUCCESS` with zero tokens and an empty body. Check the actual content, not the status field. |
 
 ## 7. Red Flags
 
@@ -115,5 +169,7 @@ graph (`.agents/graph.md`) already does properly.
 ## 8. Verification
 
 - [ ] Detection step actually ran (`command -v` checks), not assumed.
+- [ ] A plugin delegation subagent was preferred where one was available, rather than shelling out to the CLI anyway.
 - [ ] Each node's model was explicitly forced, not inherited.
+- [ ] Each worker's returned **content** was checked, not just its status field — an empty body is a failure regardless of a `SUCCESS` status.
 - [ ] Nothing persistent was left behind after the task completed.