@hybridlabor-api/aos 4.0.2 → 4.2.0-beta.0

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

@@ -1,30 +1,23 @@
 ![AOS — BDB Agent OS](assets/header-v4.jpg)
 
 🌐 **Language / Sprache / Idioma**: **English** | [ 🇩🇪 Deutsch ](README.de.md) | [ 🇵🇹 Português ](README.pt.md)
-
----
-
-```text
-█████▄ ████▄  █████▄   ▄████▄  ▄████  ██████ ███  ██ ██████   ▄████▄ ▄█████
-██▄▄██ ██  ██ ██▄▄██   ██▄▄██ ██  ▄▄▄ ██▄▄   ██ ▀▄██   ██     ██  ██ ▀▀▀▄▄▄
-██▄▄█▀ ████▀  ██▄▄█▀   ██  ██  ▀███▀  ██▄▄▄▄ ██   ██   ██     ▀████▀ █████▀
-
-──────────────────────────── N O D E F O R G E ─────────────────────────────
-
-                 BDB AGENT OS · CORE KERNEL · AOS -  v4.0.0
-```
-
 # 🚀 AOS — BDB Agent OS · Optimized Creative & Full-Stack Skills Pack
 
 [![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.
 
@@ -108,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

@@ -0,0 +1,133 @@
+# Third-Party Notices
+
+`@hybridlabor-api/aos` is licensed under Apache-2.0. It additionally bundles
+third-party source code that carries its own license. That code, and the
+license it ships under, is listed here.
+
+Each vendored file also carries a one-line pointer back to this document, so
+provenance survives the file being read in isolation.
+
+---
+
+## affaan-m/ECC
+
+- **Upstream:** <https://github.com/affaan-m/ECC>
+- **License:** MIT
+- **Copyright:** Copyright (c) 2026 Affaan Mustafa
+
+Two independent deliverables were ported from this project.
+
+### 1. Auxiliary agents
+
+Ported from ECC `agents/<name>.md` to `.claude/agents/<name>.md`:
+
+| File | Upstream source |
+|---|---|
+| `.claude/agents/silent-failure-hunter.md` | `agents/silent-failure-hunter.md` |
+| `.claude/agents/security-reviewer.md` | `agents/security-reviewer.md` |
+| `.claude/agents/go-build-resolver.md` | `agents/go-build-resolver.md` |
+| `.claude/agents/database-reviewer.md` | `agents/database-reviewer.md` |
+| `.claude/agents/opensource-forker.md` | `agents/opensource-forker.md` |
+| `.claude/agents/opensource-sanitizer.md` | `agents/opensource-sanitizer.md` |
+
+**Changes made:** frontmatter only. Upstream `name`, `description`, `model`
+and `tools` are preserved verbatim; the AOS-convention `skills:` key and the
+three house body lines (`Primary skills` / `MCP servers used` /
+`Output artifact(s)`) were added, along with a source-pointer YAML comment.
+The agent bodies — including ECC's "Prompt Defense Baseline" block — are
+unmodified.
+
+These 6 agents are standalone subagent types. They are deliberately **not**
+registered in `.agents/nodes.json` or `.agents/graph.md`; the AOS pipeline
+graph remains 7 nodes.
+
+Note that `opensource-forker` and `opensource-sanitizer` describe themselves in
+their `description:` frontmatter as the first and second stage of an
+`opensource-pipeline` skill. That is an upstream ECC concept with **no AOS
+equivalent** — no such skill exists in this repo's `skills/` tree. The
+descriptions are left verbatim as ported; the two agents work fine invoked
+directly, in that order. Do not go looking for `opensource-pipeline` here.
+
+### 2. Plan Canvas
+
+Ported to `skills/global_config/plan-canvas/`:
+
+| File | Upstream source |
+|---|---|
+| `skills/global_config/plan-canvas/SKILL.md` | `skills/plan-canvas/SKILL.md` |
+| `skills/global_config/plan-canvas/scripts/plan-canvas.js` | `scripts/plan-canvas.js` |
+| `skills/global_config/plan-canvas/scripts/lib/loopback-guard.js` | `scripts/lib/loopback-guard.js` |
+| `skills/global_config/plan-canvas/scripts/lib/plan-canvas/markdown.js` | `scripts/lib/plan-canvas/markdown.js` |
+| `skills/global_config/plan-canvas/scripts/lib/plan-canvas/sdk.js` | `scripts/lib/plan-canvas/sdk.js` |
+| `skills/global_config/plan-canvas/scripts/lib/plan-canvas/server.js` | `scripts/lib/plan-canvas/server.js` |
+| `skills/global_config/plan-canvas/scripts/lib/plan-canvas/sessions.js` | `scripts/lib/plan-canvas/sessions.js` |
+| `skills/global_config/plan-canvas/scripts/lib/plan-canvas/ui.js` | `scripts/lib/plan-canvas/ui.js` |
+
+The directory layout mirrors ECC's `scripts/` shape so every relative
+`require()` resolves unchanged. Changes made:
+
+- **`plan-canvas.js`** — `const VERSION = require('../package.json').version`
+  replaced with the literal `const VERSION = '1.0.0'`. The skill tree is
+  relocated by the installer, so a require walking above the skill directory
+  is wrong at any depth. `VERSION` only has to be stable and self-consistent.
+  It is kept in sync with `metadata.version` in the skill's `SKILL.md`.
+- **Rebrand**, exact-token only, so a co-installed ECC and AOS do not collide
+  over the same port, state directory, or health identity:
+  - env prefix `ECC_PLAN_CANVAS_*` → `AOS_PLAN_CANVAS_*`
+    (`plan-canvas.js`, `server.js`, `sessions.js`, `ui.js`)
+  - health app id `'ecc-plan-canvas'` → `'aos-plan-canvas'`
+    (`server.js`, `plan-canvas.js`)
+  - CLI name in guidance strings `ecc-plan-canvas` → `aos-plan-canvas`
+    (`plan-canvas.js`)
+  - `DEFAULT_PORT` `4517` → `4519` (`server.js`)
+  - state dir `~/.claude/plan-canvas` → `~/.claude/aos-plan-canvas`
+    (`sessions.js`)
+- **`SKILL.md`** — plan-artifact references rewritten from ECC's
+  `.claude/plans/*.plan.md` to AOS's `production_artifacts/00_execution_plan.md`,
+  port `4517` → `4519`, ECC-install prose replaced with AOS install prose, and
+  two upstream claims corrected for this repo: the `stop:plan-canvas-pending`
+  hook is not vendored, and the referenced `frontend-design-direction` /
+  `artifact-design` skills do not exist in AOS (replaced with `godmode-ui-ux` /
+  `ui-component`).
+
+Upstream provenance comments inside the vendored sources — including the
+`affaan-m/ECC#2702` reference in `ui.js` — are left intact, as are
+browser-internal identifiers private to the served page
+(`window.__eccPlanCanvasSdk`, `data-ecc-plan-canvas`, and the
+`ecc-plan-canvas:queue:` / `ecc-plan-canvas:theme` localStorage keys).
+
+No ECC tests, hooks (`scripts/hooks/plan-canvas-*.js`), or the
+`commands/plan-canvas.md` wrapper were ported.
+
+### License text
+
+```
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+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
+their own directories and are not restated here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.0.2",
+  "version": "4.2.0-beta.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": {
@@ -8,7 +8,8 @@
     "bdb-dev-optimized-agent-skills": "installer.js",
     "bdb-agent-skills-pro": "installer.js",
     "bdb-agent-skills": "installer.js",
-    "setup-saas": "bin/setup-saas.mjs"
+    "setup-saas": "bin/setup-saas.mjs",
+    "aos-plan-canvas": "skills/global_config/plan-canvas/scripts/plan-canvas.js"
   },
   "publishConfig": {
     "access": "public"
@@ -29,6 +30,7 @@
     "GEMINI.md",
     "CODEX.md",
     "CLAUDE.md",
+    "THIRD_PARTY_NOTICES.md",
     ".agents/",
     ".claude/",
     ".codex-plugin/",

package/skills/basic/bdbmediastorm/SKILL.md

@@ -72,7 +72,13 @@ Define hardware and software nodes as strict bounded contexts:
 
 ---
 
-## 5. Execution Rules
+## 5. Mandatory — Plan Canvas Review
+
+Before this session concludes, run `aos-plan-canvas open <file>` against `signal-flow.md` (or the combined show-control spec), then `aos-plan-canvas await <file>` and leave it running. The user reviews the signal flow diagram, hardware topology, and failover matrix in the browser (Mermaid renders live, click-to-annotate, chat rail). Do not consider the show architecture finalized before an `approve` verdict. A `request_changes` verdict means revise the artifact and reopen — it live-reloads. This is a plain CLI tool, identical regardless of which agent harness runs this skill. See the `plan-canvas` skill.
+
+---
+
+## 6. Execution Rules
 
 1. **Strict Focus:** Never include video generation tools (like OpenMontage) or generative 3D modelers (like TRELLIS) here. Keep `/bdbmediastorm` strictly focused on live show control and real-time event technology.
 2. **Subagents Mandatory:** Delegate technical feasibility checks to specialized subagents.

package/skills/basic/startcycle/SKILL.md

@@ -67,6 +67,8 @@ A straight-line run through the BDB agent roster. Whoever invokes this skill inv
 - **Action**: reviews the plan for module boundaries, dependency direction, and build order. Approves it, or sends it back to Architect once for a revision. This is a gate, not a deliverable — TechLead does not invoke Architect itself; the invoker re-runs step 1 if TechLead rejects.
 - **Writes**: no separate file; approval is just the invoker's own record of the gate having passed.
 
+> **Optional — Plan Canvas.** Before or alongside TechLead's gate, the plan can be reviewed in the browser: `aos-plan-canvas open production_artifacts/00_execution_plan.md`, then `aos-plan-canvas await …`. An `approve` verdict is a human confirmation of the gate. This is optional; the pipeline runs unchanged without it. See the `plan-canvas` skill.
+
 ### 3. Build (parallel, stream-selective)
 Run only the streams the goal actually needs. A plain backend feature does not need step 3a or 3c; a pure copy change does not need 3b. Each stream's `skills:` frontmatter already lists what it should reach for — the invoker passes that list through rather than restating it here.
 
@@ -78,6 +80,25 @@ 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
+> `~/.claude/skills/<name>/` 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,20 @@ 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. 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,24 @@ 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
+`~/.claude/skills/<name>/` 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 +57,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 +154,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 +167,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.

package/skills/bdbrainstorm/SKILL.md

@@ -35,6 +35,7 @@ You are strictly required to enforce the following 6 pillars in your process:
 
 ### 6. Shipping Godmode & Pipeline Hand-off
 - Before the brainstorm concludes, verify that the plan satisfies the `godmode-shipping` rules (Spec-Driven Development, feature flags, rollback strategies).
+- **Mandatory — Plan Canvas review.** Write the aligned plan to a file, then run `aos-plan-canvas open <file>` followed by `aos-plan-canvas await <file>` and leave it running. The user reviews and annotates in the browser (Mermaid diagrams render live, click-to-annotate, chat rail); do not write `state.goal` or hand off to `/startcycle-graph` before an `approve` verdict comes back. A `request_changes` verdict means revise the plan file and reopen the session — it live-reloads. This runs identically regardless of which agent harness is executing this skill; it is a plain CLI, not a Claude-Code-specific mechanism. See the `plan-canvas` skill.
 - Present the aligned plan and hand off to `/startcycle-graph` for execution — write `state.goal` from this session's output and let `/startcycle-graph`'s dispatcher take it from there (see `.agents/graph.md`). This skill does not invoke `/startcycle-graph`'s agents itself; it produces the goal they read.
 
 ## Execution Rules