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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybridlabor-api/aos",
-  "version": "4.1.0",
+  "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": {

package/skills/basic/startcycle/SKILL.md

@@ -80,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.