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

package/.claude/workflows/startcycle-dispatch.mjs

@@ -81,6 +81,14 @@ const MAX_ITERATIONS = 3;
 // correct on the first draft.
 let iteration = 0;
 
+// Populated from a --skill=<name> flag (repeatable) in the invocation text --
+// see extractMandatorySkills() and .agents/graph.md's "Mandatory Skill
+// Injection" section. Empty when the user didn't ask for one. Module-level
+// like `iteration` above, for the same reason: skillsNote() and the Reviewer
+// prompt both need it and neither is in a position to thread it through as a
+// parameter without touching every call site.
+let mandatorySkills = [];
+
 // Every sequential (non-build-role) agent gets the same note: read the full
 // state, and explicitly set state.iteration to the dispatcher's current
 // count so the persisted file (which .claude/hooks/graph-gate.mjs reads)
@@ -149,11 +157,27 @@ function reviewerStateNote() {
 // Applies to every node, build and sequential alike.
 function skillsNote(node) {
   const skills = Array.isArray(node?.skills) ? node.skills : [];
-  if (skills.length === 0) return '';
-  return (
-    ` Use these skills for this work: ${skills.join(', ')}. ` +
-    'Do not reach for skills outside this list unless the task genuinely requires it.'
-  );
+  const parts = [];
+  if (skills.length > 0) {
+    parts.push(
+      ` Use these skills for this work: ${skills.join(', ')}. ` +
+      'Do not reach for skills outside this list unless the task genuinely requires it.'
+    );
+  }
+  // A --skill flag is a hard requirement from the user, not the registry's
+  // own suggested allowlist above -- it applies on top of, never instead of,
+  // that list. Only nodes that actually produce work get told to use it:
+  // build-role nodes, plus Architect (who should fold the skill's guidance
+  // into the plan itself, not just leave it for Build to discover cold).
+  // Reviewer gets a separate mention in its own prompt below, framed as a
+  // check rather than a use.
+  if (mandatorySkills.length > 0 && (node?.role === 'build' || node?.id === 'architect')) {
+    parts.push(
+      ` The user explicitly required this run to use the following skill(s), via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+      "This is a hard requirement, not a suggestion -- actually apply the skill's guidance in your work, and name in your returned summary how each one was applied."
+    );
+  }
+  return parts.join('');
 }
 
 // "a", "a or b", "a, b, or c" -- used for NODE_NAMES, itself derived from the
@@ -297,13 +321,97 @@ const techleadNode = { id: 'techlead', ...registryNodes.techlead };
 const reviewerNode = { id: 'reviewer', ...registryNodes.reviewer };
 const shippingNode = { id: 'shipping', ...registryNodes.shipping };
 
-const goal = typeof args === 'string' ? args : args?.goal;
-if (!goal) {
+const rawGoal = typeof args === 'string' ? args : args?.goal;
+if (!rawGoal) {
   return escalate(
     'startcycle-graph needs a goal, e.g. "Run /startcycle-graph on: add OAuth login with Google" -- nothing was invoked.'
   );
 }
 
+// --skill=<name>, repeatable, extracted out of the raw goal text before
+// anything else sees it -- e.g. "--skill=my-custom-skill Add OAuth login"
+// becomes goal "Add OAuth login" plus one mandated skill name. This is the
+// mechanism for injecting a skill this script has never heard of (a user's
+// own private skill, never part of .agents/nodes.json's registry) -- see
+// .agents/graph.md's "Mandatory Skill Injection" section.
+function extractMandatorySkills(text) {
+  // The `|--skill=(?=\s|$)` alternative deliberately matches a flag with an
+  // EMPTY value ("--skill= add OAuth"). Without it, `\S+` simply fails to
+  // match, the flag falls through as ordinary prose, and the run proceeds
+  // with no skill injected AND the literal "--skill=" still glued to the
+  // goal text handed to Architect -- a silent no-op on a typo, which is the
+  // exact failure mode the validation below exists to prevent. Capturing it
+  // as an empty name instead routes it into `malformed` and escalates.
+  const flagPattern = /--skill=("[^"]+"|'[^']+'|\S+)|--skill=(?=\s|$)/g;
+  const skills = [];
+  let malformed = 0;
+  const goal = text
+    .replace(flagPattern, (_, val) => {
+      if (val === undefined) { malformed++; return ''; }
+      const unquoted =
+        (val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))
+          ? val.slice(1, -1)
+          : val;
+      if (unquoted.trim() === '') { malformed++; return ''; }
+      skills.push(unquoted);
+      return '';
+    })
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+  return { skills, goal, malformed };
+}
+
+const { skills: skillsFromFlags, goal, malformed } = extractMandatorySkills(rawGoal);
+if (malformed > 0) {
+  return await escalate(
+    `--skill was given with an empty value (${malformed} time(s)). Write --skill=<name>, e.g. --skill=my-custom-skill. ` +
+      'Refusing to proceed rather than silently running without the skill you asked for.'
+  );
+}
+if (!goal) {
+  return await escalate(
+    'startcycle-graph needs actual goal text, not just --skill flag(s) -- e.g. "--skill=my-custom-skill add OAuth login with Google", not "--skill=my-custom-skill" alone.'
+  );
+}
+// Object-form args may also carry a structured list directly, for a future
+// caller that never goes through the string-flag convention at all.
+const skillsFromArgs = Array.isArray(args?.mandatorySkills) ? args.mandatorySkills : [];
+const mandatorySkillNames = [...new Set([...skillsFromFlags, ...skillsFromArgs])];
+
+// Validate before anything else runs -- same "never silently fall back or
+// guess" posture as the registry load above. This script has no filesystem
+// access of its own (comment block item #1), so validation is itself an
+// agent() call, not a local fs check.
+if (mandatorySkillNames.length > 0) {
+  const skillCheckResult = await agent(
+    `Check whether each of these skill names resolves to an installed skill with a real SKILL.md: ${JSON.stringify(mandatorySkillNames)}. ` +
+      'Look under ~/.claude/skills/<name>/SKILL.md first (the global install location every harness syncs to); ' +
+      'if this project has its own skills/ directory, also accept skills/<name>/SKILL.md or skills/<container>/<name>/SKILL.md. ' +
+      'This is a read-only lookup, not a reasoning task -- do not invent a path that does not exist, and do not guess a close match for a name that is not actually there.\n\n' +
+      'Return only: { "found": string[], "missing": string[] }.',
+    {
+      label: 'validate-mandatory-skills',
+      model: 'haiku',
+      schema: {
+        type: 'object',
+        required: ['found', 'missing'],
+        properties: {
+          found: { type: 'array', items: { type: 'string' } },
+          missing: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    }
+  );
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    return await escalate(
+      `--skill named skill(s) that could not be found on this machine: ${missing.join(', ')}. ` +
+        'Refusing to silently proceed without a mandated skill -- check the name (it must match an installed skill directory) and re-run.'
+    );
+  }
+  mandatorySkills = skillCheckResult?.found ?? mandatorySkillNames;
+}
+
 // ---------------------------------------------------------------------
 // Architect <-> TechLead: plan, then capability-map approval. Sequential --
 // not part of the CHANGE 1 race, writes state.json directly as before.
@@ -323,7 +431,7 @@ while (!approved) {
         : '') +
       `Turn this goal into a system plan with an explicit capability map (module boundaries, ` +
       `dependency direction, build order). Write it to production_artifacts/00_execution_plan.md. ` +
-      `Set state.goal, state.phase = "plan", state.artifacts.plan to that path. ` +
+      `Set state.goal, state.phase = "plan", state.artifacts.plan to that path, and state.mandatory_skills to ${JSON.stringify(mandatorySkills)}. ` +
       `Decide whether the goal needs the Media_EventTech build node (TouchDesigner/show-control/3D/media work) -- most goals don't.\n\n` +
       `Return only: { "planPath": string, "needsMedia": boolean }.`,
     {
@@ -349,6 +457,11 @@ while (!approved) {
     `You are acting as the ${techleadNode.label} agent (${techleadNode.personaFile}). ${dispatchNote(techleadNode)}${skillsNote(techleadNode)}\n\n` +
       `Read the plan at ${planPath}. Approve it only if it has an explicit capability map: ` +
       `module boundaries, dependency direction, and build order are all stated, not implicit. ` +
+      (mandatorySkills.length > 0
+        ? `The user also required this run to use the following skill(s) via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+          `Reject the plan if it does not actually account for them — catching that here costs one planning round, ` +
+          `whereas letting it through wastes a full build cycle before Reviewer flags it.\n`
+        : '') +
       `Record your decision in state.json (plan approval, state.phase = "build" if approved).\n\n` +
       `Return only: { "approved": boolean, "reason": string }.`,
     {
@@ -459,6 +572,11 @@ while (!reviewedClean) {
       }, and the actual code). ` +
       `Do an adversarial review against the contract: find what is wrong, do not validate, do not summarize. ` +
       `Do not assume the implementation is correct just because it exists. ` +
+      (mandatorySkills.length > 0
+        ? `The user explicitly required these skill(s) to be used this run, via /startcycle-graph's --skill flag: ${mandatorySkills.join(', ')}. ` +
+          `If an artifact shows no sign of applying a mandated skill's guidance, that is a contract misread finding (blocking), owned by whichever build node should have applied it. ` +
+          `A mandated skill being merely available is not enough -- check for it actually being used.\n`
+        : '') +
       `Classify every finding by precedence: contract misread > valid & actionable (blocking) > valid trade-off (advisory) > noise (discard). ` +
       `Each finding must name which node owns fixing it: ${NODE_NAMES} -- no other value is valid. ` +
       `If you are re-reviewing after a repair round and an issue you flagged before is still present and still unfixed, ` +

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/mcps/RhinoMCP/cc-plugin/.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls /Applications/ | grep -i rhino)",
+      "Read(//Applications/**)",
+      "Bash(lsof -nP -iTCP -sTCP:LISTEN)",
+      "Bash(awk 'NR==1 || $9 ~ /:[0-9]+$/')"
+    ]
+  }
+}