@hybridlabor-api/aos 4.16.0 → 4.17.0

package/.claude/hooks/go-grant.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook for the go-gate modes and grants. When the human types,
+// as the whole message (plain form, primary):
+//   gogate grant <scope[,scope...]> <15m|2h|1d|session>
+//   gogate hard|soft|off|status
+// or the slash form /bdb-aos:gogate ... (rarely verifies, the hook says so),
+// it records the request in ~/.aos/gate/<session-key>.json with a pointer to
+// the prompt (transcript, issue time, text hash). Nothing here is trusted on
+// its own: go-gate.mjs re-reads the transcript at use time and honours an
+// entry only if a human-typed (origin-checked) prompt with that hash exists.
+// A loop, peer, bus or agent prompt may reach this hook, but its transcript
+// entry is not human, so what it records never verifies.
+//
+// CLI: node go-grant.mjs --status [--session <id>]   (read-only, prints status)
+
+import { readFileSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  parseGogate, textHash, sessionKey, readState, writeState, gateLog, effectiveGate,
+  gogateCommandsFor, statusText, listStateKeys, OPENCODE_MAX_GRANT_MS,
+} from "./go-gate.mjs";
+
+const emptyState = (source) => ({ transcript: source, grants: [] });
+
+// Applies a gogate prompt to the store. `source` is the transcript path or
+// "opencode:<sessionID>"; `uuid` the message id when the harness knows it.
+// Returns the text for the model (additionalContext), or null for non-gogate prompts.
+export function applyGogate(prompt, { key, source, uuid = null, now = Date.now(), opencode = false }) {
+  const p = parseGogate(prompt);
+  if (!p) return null;
+  const slashNote = p.form === "slash"
+    ? ` Note: this was a slash command. ${opencode ? "OpenCode accepts only the plain form" : "Claude Code stores slash commands without human-origin data, so the gate will most likely ignore it"}; to make it count, type the plain form as the whole message: \`gogate ${p.cmd === "grant" ? `grant ${p.scopes.join(",")} ${p.session ? "session" : "<duration>"}` : p.cmd || "status"}\`.`
+    : "";
+  if (p.error) return `gogate: ${p.error}. Nothing changed.`;
+  if (!key || !source) return "gogate: no session id in hook input, nothing recorded.";
+  if (process.env.AOS_ACP_CLIENT) return "gogate: an aos-acp worker session cannot set modes or grants.";
+  if (p.cmd === "status") return status(key);
+  if (opencode && p.cmd === "off") return "gogate: `off` is not available on OpenCode (no human-origin signal there). Nothing changed.";
+  let st = readState(key);
+  if (!st || typeof st !== "object" || st.transcript !== source) st = emptyState(source);
+  const src = { transcript: source, uuid, issued_at: new Date(now).toISOString(), text_hash: textHash(prompt) };
+  if (p.cmd === "grant") {
+    const ms = opencode ? Math.min(p.ms, OPENCODE_MAX_GRANT_MS) : p.ms;
+    st.grants = (Array.isArray(st.grants) ? st.grants : []).filter((g) => Date.parse(g?.until) > now);
+    for (const scope of p.scopes) st.grants.push({ scope, until: new Date(now + ms).toISOString(), ...(p.session ? { session_key: key } : {}), source: src });
+  } else {
+    // Append, never overwrite: a later prompt that does not verify must not erase the
+    // store entry of the mode that is still in force.
+    st.modes = [...(Array.isArray(st.modes) ? st.modes : []), { mode: p.cmd, source: src }].slice(-20);
+  }
+  try {
+    writeState(key, st);
+  } catch (e) {
+    return `gogate: could NOT record ${p.cmd}: writing ~/.aos/gate failed (${e.code || e.message}). Nothing changed; the gate stays as it was. Tell the human.`;
+  }
+  gateLog(key, `recorded ${p.form} ${p.cmd}${p.scopes ? ` ${p.scopes.join(",")} ${p.session ? "session" : `${p.ms / 60000}m`}` : ""}`);
+  return [
+    `gogate: recorded ${p.cmd}${p.scopes ? ` for ${p.scopes.join(", ")}` : ""}${p.session ? " (session = this session id, at most 24h, survives --resume)" : ""}${opencode && p.cmd === "grant" && p.ms > OPENCODE_MAX_GRANT_MS ? " (capped at 2h on OpenCode)" : ""}.`,
+    "The gate verifies it against this prompt in the transcript on every use.",
+    slashNote,
+    "Tell the human what was recorded; never try to change modes or grants yourself.",
+  ].filter(Boolean).join(" ");
+}
+
+export function status(key) {
+  const st = readState(key);
+  const eff = st ? effectiveGate(key, { source: st.transcript, cmds: gogateCommandsFor(st.transcript), opencode: String(st.transcript).startsWith("opencode:") }) : { mode: "soft", grants: [], rejected: [] };
+  return statusText(key, eff);
+}
+
+const isMain = () => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } };
+
+if (isMain()) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--status")) {
+    const i = argv.indexOf("--session");
+    const id = i !== -1 ? argv[i + 1] : process.env.AOS_GATE_SESSION || process.env.CLAUDE_SESSION_ID;
+    const keys = id ? [sessionKey(id)] : listStateKeys();
+    console.log(keys.length ? keys.map(status).join("\n\n") : "AOS go-gate: no session state; every session runs in soft mode with no grants (behaves like hard).");
+    process.exit(0);
+  }
+  try {
+    const input = JSON.parse(readFileSync(0, "utf8"));
+    const text = applyGogate(input.prompt, { key: sessionKey(input.session_id), source: input.transcript_path });
+    if (text) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: text } }));
+  } catch { /* a failing hook must never block the prompt */ }
+  process.exit(0);
+}

package/.claude/settings.json

@@ -123,6 +123,14 @@
           }
         ]
       },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/go-grant.mjs\""
+          }
+        ]
+      },
       {
         "hooks": [
           {

package/.codex-plugin/plugin.json

@@ -1,8 +1,38 @@
 {
-  "name": "bdb-dev-optimized-agent-skills",
-  "version": "2.3.0",
-  "description": "BDB DEV Optimized Agent Skills and MCP pack for Codex CLI, Claude, Cursor and Antigravity",
-  "author": "hybridlabor-api",
-  "skills_dir": "./skills/global_config",
-  "mcp_config": "./.codex-plugin/.mcp.json"
+  "name": "bdb-aos",
+  "version": "4.17.0",
+  "description": "Full BDB Agent OS suite for Codex: command entry points ($bdb-aos:setup, $bdb-aos:init, ...) generated from plugin-commands.json.",
+  "author": {
+    "name": "Tim Rennings / Hybridlabor Global LLC",
+    "email": "hybridlabor@gmail.com"
+  },
+  "homepage": "https://github.com/hybridlabor-api/aos",
+  "repository": "https://github.com/hybridlabor-api/aos",
+  "license": "Apache-2.0",
+  "keywords": [
+    "skills",
+    "agent-os",
+    "cicd",
+    "multiagent",
+    "startcycle",
+    "bdb"
+  ],
+  "skills": "./plugins/bdb-aos-codex/skills/",
+  "interface": {
+    "displayName": "BDB Agent OS",
+    "shortDescription": "AOS commands for setup, planning and pipelines",
+    "longDescription": "Entry-point skills for the BDB Agent OS suite: invoke $bdb-aos:<command> to run setup, project init, planning and the startcycle pipelines.",
+    "developerName": "Hybridlabor Global LLC",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/hybridlabor-api/aos",
+    "defaultPrompt": [
+      "$bdb-aos:setup",
+      "$bdb-aos:doctor"
+    ]
+  }
 }

package/.opencode/commands/bdb-aos-brainstorm.md

@@ -0,0 +1,5 @@
+---
+description: "Brainstorm a topic with the matching skill: bdbrainstorm, bdbmediastorm for event tech, grill-me for a stress test."
+---
+
+Pick by topic: `bdbmediastorm` for live event technology and show control, `grill-me` when the human wants an existing idea stress-tested, `bdbrainstorm` otherwise. Say which one you chose. Topic: $ARGUMENTS

package/.opencode/commands/bdb-aos-doctor.md

@@ -0,0 +1,5 @@
+---
+description: "Check the machine and the current project, and print suggested permissions.allow entries without writing any settings."
+---
+
+Run `aos-doctor` (machine check) and report the result. If the current folder is an AOS project, also run the project check `node <aos-project-init skill dir>/scripts/aos-project-doctor.mjs` (it covers `.aos/project.json`, AGENTS.md and the wiki). Print suggested `permissions.allow` entries as text for the human to copy. Never write to settings.json or settings.local.json. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-graph.md

@@ -0,0 +1,5 @@
+---
+description: "Run the startcycle-graph pipeline: durable state, repair loop, quality gate, escalation."
+---
+
+Run the `startcycle-graph` skill; its contract defines the flow. Task: $ARGUMENTS

package/.opencode/commands/bdb-aos-init.md

@@ -0,0 +1,5 @@
+---
+description: "Set up the current project folder for AOS: slug, wiki, memory, Synapse map, AGENTS.md."
+---
+
+Run the `aos-project-init` skill for the current project folder. This is project setup, not machine setup (that is `/bdb-aos-setup`). Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-loop.md

@@ -0,0 +1,5 @@
+---
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates."
+---
+
+OpenCode has no built-in loop. Use `opencode-loop`, the opt-in package (AOS_OPENCODE_OPTIONAL=loop, see docs/opencode-setup.md); without it, say so and stop. Do not schedule gated commands through its shell loop. Offer a `loop-templates` template when the human has no prompt yet. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-mastersession.md

@@ -0,0 +1,5 @@
+---
+description: "Supervise other Claude Code sessions on this machine: roster, status requests, GO board, idle notices."
+---
+
+Act as the master session with the `master-session` skill (ACP bridge: `bin/aos-acp.mjs`, see docs/master-session-acp.md). Keep the overview, relay the human's decisions, never decide for the human. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-memb.md

@@ -0,0 +1,5 @@
+---
+description: "Query or store long-term memory with memB."
+---
+
+Use `memb-skill` to search or remember and `memb-ingest` to import material. Never store secrets, tokens or credentials. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-orchestrator.md

@@ -0,0 +1,5 @@
+---
+description: "Coordinate parallel coding agents across repositories through the AO daemon."
+---
+
+Use the `ao-orchestrator` skill. It needs the AO daemon; check that it is running first and stop with a clear message if not. Do not confuse it with `agent-orchestrator`. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-plan.md

@@ -0,0 +1,5 @@
+---
+description: "Plan end to end: draft, render in plan-canvas or Plan Builder, annotate, await approval, then hand off."
+---
+
+Run the full planning pipeline: 1) draft the plan with `concise-planning`; 2) always offer the choice between plan-canvas and Plan Builder (`visual-plan`) for rendering; 3) collect annotations and wait for the human's approval; 4) only after approval continue with `writing-plans` or `/bdb-aos-graph`. Topic: $ARGUMENTS

package/.opencode/commands/bdb-aos-playbooks.md

@@ -0,0 +1,5 @@
+---
+description: "List all pb-* playbooks with duration, difficulty and requirements, and start one."
+---
+
+Run `node <bdb-aos skill dir>/scripts/list-playbooks.mjs` and show its output (name, est_time, difficulty, requires of every `pb-*` skill). If the human names a playbook in the arguments or picks one, start that `pb-*` skill; start nothing otherwise. Each playbook keeps its own go-gate points. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-setup.md

@@ -0,0 +1,5 @@
+---
+description: "Bring this machine to a complete, verified AOS installation (skills, MCP servers, gate hooks, memB, OpenWiki, Synapse)."
+---
+
+Run the `aos-setup` skill for this machine. Report what is installed, what was repaired and what is still missing. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-shipping.md

@@ -0,0 +1,5 @@
+---
+description: "Pre-ship framing and the technical release gate, with approvals under the go-gate rules."
+---
+
+Use `bdb-shipping-skill` for the pre-flight and `godmode-shipping` for the gate. The playbook `pb-ship` can drive the whole flow. Push, merge and publish need the human's GO under the go-gate rules; never request one on the human's behalf. Arguments: $ARGUMENTS

package/.opencode/commands/bdb-aos-startproject.md

@@ -0,0 +1,5 @@
+---
+description: "Start a new composition: project init, brainstorm, then ask whether graph or startcycle follows."
+---
+
+Sequence: 1) `aos-project-init`; 2) `bdbrainstorm`; 3) stop and ask the human whether `/bdb-aos-graph` (startcycle-graph) or `startcycle` follows. Do not start a pipeline on your own. Idea: $ARGUMENTS

package/.opencode/commands/bdb-aos-store.md

@@ -0,0 +1,5 @@
+---
+description: "Browse and preview AOS skills, agents and playbooks in the local store UI."
+---
+
+Start the `aos-store` interface. Preview freely, but install nothing until the human says yes for that specific item. Arguments: $ARGUMENTS

package/.opencode/plugins/bdb-aos.js

@@ -23,8 +23,11 @@ import path from 'node:path';
 // so a broken installed hook fails loudly instead of silently falling back.
 const HOOKS = existsSync(new URL('./aos-hooks/go-gate.mjs', import.meta.url)) ? './aos-hooks/' : '../../.claude/hooks/';
 const hook = (f) => import(new URL(HOOKS + f, import.meta.url).href);
-const [{ GUARDED_PATTERNS, tokenGrantsGo }, { issueGoToken }, { checkConventionalCommit }, { envFileReason }, { buildMemoryBlock }, bus] =
-  await Promise.all(['go-gate.mjs', 'go-token.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs', 'memb-inject.mjs', 'aos-bus.mjs'].map(hook));
+// `opencode run "..."` is scriptable by an agent, so it never sets gogate modes or grants
+const OPENCODE_RUN = process.argv.slice(1, 4).includes('run');
+const [gate, { issueGoToken }, { checkConventionalCommit }, { envFileReason }, { buildMemoryBlock }, bus, { applyGogate }] =
+  await Promise.all(['go-gate.mjs', 'go-token.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs', 'memb-inject.mjs', 'aos-bus.mjs', 'go-grant.mjs'].map(hook));
+const { GUARDED_PATTERNS, tokenGrantsGo, isHumanPart, parseGoText, goAllows, isGuardedCommand, gateStoreReason, effectiveGate, opencodeGogateCommands, grantsCover, sessionKey, gateLog } = gate;
 
 // ---------------------------------------------------------------------------
 // Graph gate (W-5, W-6)
@@ -131,9 +134,26 @@ async function ownSessionName(client, sessionID) {
 }
 
 // Only plain text parts are human turns: synthetic = model-only, ignored = display-only,
-// aos_bus = bus delivery (both copies). Each excluded on its own, so safety never hangs on one flag.
-const isHumanText = (p) => p && p.type === 'text' && typeof p.text === 'string' && !p.synthetic && !p.ignored && !p.metadata?.aos_bus;
-const isNonHuman = (p) => p && (p.synthetic || p.ignored || p.metadata?.aos_bus);
+// aos_bus / aos_loop (any loop|aos_ metadata key) = plugin-injected. Each excluded on its own,
+// so safety never hangs on one flag.
+const isHumanText = isHumanPart;
+const isNonHuman = (p) => !!p && !!(p.synthetic || p.ignored || (p.metadata && typeof p.metadata === 'object' && Object.keys(p.metadata).some((k) => /loop|aos_/i.test(k))));
+const ocKey = (id) => sessionKey(`oc-${id}`);
+
+// Root of a session tree (grants live on the root, subagents may use them). null when unknown.
+async function rootSessionId(client, id, parentID) {
+  for (let i = 0; i < 10 && id; i++) {
+    if (parentID === null) return id;
+    try {
+      const res = await client?.session?.get?.({ path: { id } });
+      if (!res?.data) return null;
+      if (!res.data.parentID) return id;
+      id = res.data.parentID;
+      parentID = undefined;
+    } catch { return null; }
+  }
+  return null;
+}
 
 // A plugin reload (SIGUSR2) re-runs init on the cached module in the same process:
 // stop the previous instance's timers and keep its bus names alive. Keyed by directory.
@@ -336,9 +356,10 @@ export default async function bdbAosPlugin(input) {
         if (nudges >= MAX_NUDGES) return;
 
         nudgeState.set(sessionID, { signature: gate.signature, nudges: nudges + 1 });
+        // Synthetic + aos_loop: the nudge is plugin-written and must never count as a human turn (GO, gogate).
         await input.client.session.prompt({
           path: { id: sessionID },
-          body: { parts: [{ type: 'text', text: buildGraphNudge(gate) }] },
+          body: { parts: [{ type: 'text', text: buildGraphNudge(gate), synthetic: true, metadata: { aos_loop: { source: 'graph-gate', nudge: nudges + 1 } } }] },
           query: directory ? { directory } : undefined,
         });
       } catch {
@@ -361,6 +382,12 @@ export default async function bdbAosPlugin(input) {
         if (!s.parentID) issueGoToken(fullText, { session_id: msgInput.sessionID, message_id: msgInput.messageID || msgOutput.message?.id });
       } catch {}
 
+      // plain `gogate ...` message from the human in a root session: record it; the gate verifies it against opencode.db at use.
+      try {
+        const reply = s.parentID || OPENCODE_RUN ? null : applyGogate(fullText, { key: ocKey(msgInput.sessionID), source: `opencode:${msgInput.sessionID}`, uuid: msgInput.messageID || msgOutput.message?.id || null, opencode: true });
+        if (reply) msgOutput.parts.unshift({ id: `gogate-${Date.now()}`, sessionID: msgInput.sessionID, messageID: msgInput.messageID || '', type: 'text', text: reply, synthetic: true });
+      } catch {}
+
       try {
         const event = s.identitySent || s.parentID ? 'UserPromptSubmit' : 'SessionStart';
         s.identitySent = true;
@@ -415,7 +442,9 @@ export default async function bdbAosPlugin(input) {
       // Intercept bash, terminal, or command execution tools
       if (toolName === 'bash' || toolName === 'terminal' || toolName === 'shell' || toolName === 'exec' || toolName === 'run_command') {
         const cmd = toolOutput?.args?.command || toolOutput?.args?.cmd || toolOutput?.args?.script || '';
-        if (typeof cmd === 'string' && GUARDED_PATTERNS.some((re) => re.test(cmd))) {
+        const storeReason = gateStoreReason(cmd);
+        if (storeReason) throw new Error(storeReason);
+        if (typeof cmd === 'string' && (GUARDED_PATTERNS.some((re) => re.test(cmd)) || isGuardedCommand(cmd))) {
           const s = sess(toolInput.sessionID);
           // An unanswered lookup is not proof of a root session: token-only for this call, not cached.
           let tokenOnly = !!s.parentID;
@@ -427,8 +456,9 @@ export default async function bdbAosPlugin(input) {
             } catch { tokenOnly = true; }
             tokenOnly = tokenOnly || !!s.parentID;
           }
-          // Subagent prompts are agent-written, so only a token can open their gate.
-          let authorized = !tokenOnly && s.prompt.toUpperCase() === 'GO';
+          // Subagent prompts are agent-written, so only a token or a grant can open their gate.
+          const goOk = (text) => goAllows(parseGoText(text), cmd);
+          let authorized = !tokenOnly && goOk(s.prompt);
 
           // If this session's cached prompt wasn't GO, query recent session messages via OpenCode client as fallback
           if (!authorized && !tokenOnly && input.client && toolInput.sessionID) {
@@ -440,13 +470,27 @@ export default async function bdbAosPlugin(input) {
                 if ((m.info?.role ?? m.role) === 'user') {
                   const parts = m.parts || [];
                   const text = parts.filter(isHumanText).map((p) => p.text).join('\n').trim();
-                  authorized = text.toUpperCase() === 'GO';
+                  authorized = goOk(text);
                   break;
                 }
               }
             } catch {}
           }
 
+          // Modes and grants of the root session (verified against opencode.db); usable by its subagents.
+          if (!authorized) {
+            const root = await rootSessionId(input.client, toolInput.sessionID, tokenOnly ? undefined : s.parentID);
+            if (root) {
+              const key = ocKey(root);
+              const eff = effectiveGate(key, { source: `opencode:${root}`, cmds: opencodeGogateCommands(root), opencode: true });
+              for (const r of eff.rejected) gateLog(key, `rejected: ${r}`);
+              if (eff.mode === 'soft' && grantsCover(cmd, eff.grants)) { // `off` is never honoured on OpenCode
+                gateLog(key, `grant: allowed ${JSON.stringify(cmd.slice(0, 200))}`);
+                authorized = true;
+              }
+            }
+          }
+
           if (!authorized) {
             authorized = tokenGrantsGo(await ownSessionName(input.client, toolInput.sessionID)).ok;
           }

package/README.md

@@ -110,9 +110,9 @@ What the installer writes for each target. Paths are the defaults; the installer
 | Harness | Skills | Subagents | Hooks | Plugin / rules |
 |---|---|---|---|---|
 | Claude Code / Claude Desktop | `~/.claude/skills` | `~/.claude/agents` | `~/.claude/hooks` + `settings.json` (GO gate, graph gate, env-file protection, Conventional Commits, memB inject, trail relay) | `.claude-plugin/` manifest ships in the repo (see Contributing) |
-| Google Antigravity | `~/.gemini/config/skills` | `~/.gemini/config/agents` | `~/.gemini/config/hooks.json` and `~/.gemini/antigravity-cli/hooks.json` | — |
-| Codex CLI | `~/.codex/skills` | `~/.codex/agents` | `~/.codex/hooks` + `config.toml` | `.codex-plugin/` |
-| OpenCode | `~/.config/opencode/skills` | `~/.opencode/agents` | via plugin | `bdb-aos.js` plugin + `/startcycle-graph` command, registered in `opencode.jsonc`; keeps a `/startcycle-graph` run moving on `session.idle` |
+| Google Antigravity | `~/.gemini/config/skills` | `~/.gemini/config/agents` | `~/.gemini/config/hooks.json` and `~/.gemini/antigravity-cli/hooks.json` | root `plugin.json` / `plugins/bdb-aos/plugin.json`, commands `/bdb-aos:<cmd>`, see [docs/codex-agy-setup.md](docs/codex-agy-setup.md) |
+| Codex CLI | `~/.codex/skills` | `~/.codex/agents` | `~/.codex/hooks` + `config.toml` | `.codex-plugin/` + `.agents/plugins/marketplace.json`, commands `$bdb-aos:<cmd>`, see [docs/codex-agy-setup.md](docs/codex-agy-setup.md) |
+| OpenCode | `~/.config/opencode/skills` | `~/.opencode/agents` | via plugin | `bdb-aos.js` plugin + `/startcycle-graph` command, registered in `opencode.jsonc`; keeps a `/startcycle-graph` run moving on `session.idle`; generated `/bdb-aos-<cmd>` commands; opt-in extras, see [docs/opencode-setup.md](docs/opencode-setup.md) |
 | Cursor | `~/.cursor/skills` | — | — | `.cursor/rules` (project) |
 | Windsurf | `~/.windsurf/bdb-skills` | — | — | `mcp.json` |
 | Roo Code / Cline | `~/.roo/skills` | — | — | `.roomodes` (project) |
@@ -431,7 +431,7 @@ aos-uninstall --purge      # also removes ~/.MemBDB, ~/.openwiki, ~/.synapse, ~/
 aos-uninstall --dry-run    # list everything, delete nothing
 ```
 
-The uninstaller works from the install manifest: a file that still matches the hash AOS wrote is removed, a file you edited is backed up instead, a file AOS never wrote is not touched. The same action is in the installer menu.
+The uninstaller works from the install manifest: a file that still matches the hash AOS wrote is removed, a file you edited is backed up instead, a file AOS never wrote is not touched. The same action is in the installer menu. `aos-uninstall --restore-plugin-backup` restores the loose skill copies the installer removed when it registered the plugin; see [docs/plugin-migration.md](docs/plugin-migration.md).
 
 ---
 

package/agy-commands/loop.md

@@ -0,0 +1,5 @@
+---
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates."
+---
+
+Unverified, no loop mechanism confirmed for agy. Manual repeat: fill a `loop-templates` template, re-send it yourself at each interval, and stop at its limits or stop condition. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: whatever the user wrote after the command name

package/bin/aos-doctor.mjs

@@ -12,6 +12,7 @@ import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 
+const pm = createRequire(import.meta.url)('../lib/plugin-migration.js');
 const HOME = os.homedir();
 const JSON_OUT = process.argv.includes('--json');
 const NET = process.argv.includes('--net');
@@ -183,10 +184,11 @@ function checkHarnesses() {
     const exists = existsSync(hr.path);
     const count = dirCount(hr.path);
     const hasSentinel = existsSync(path.join(hr.path, SENTINEL, 'SKILL.md'));
-    const ok = exists && count > 0 && hasSentinel;
+    const viaPlugin = hr.name === 'Claude Code' && !hasSentinel && pm.pluginInstalled(HOME, [SENTINEL]);
+    const ok = viaPlugin || (exists && count > 0 && hasSentinel);
     add('harnesses', `${hr.name} Skills`, ok,
-      ok ? `${tilde(hr.path)} (${count} skills, sentinel verified)` : (exists ? `${tilde(hr.path)} (${count} skills, sentinel missing)` : `${tilde(hr.path)} not synced`),
-      `Run 'npx @hybridlabor-api/aos@latest' and select ${hr.name} to sync skills.`, !exists);
+      viaPlugin ? 'delivered by the bdb-aos Claude Code plugin (installed_plugins.json / plugin cache)' : ok ? `${tilde(hr.path)} (${count} skills, sentinel verified)` : (exists ? `${tilde(hr.path)} (${count} skills, sentinel missing)` : `${tilde(hr.path)} not synced`),
+      `Run 'npx @hybridlabor-api/aos@latest' and select ${hr.name} to sync skills.`, !exists && !viaPlugin);
   }
 
   // OpenCode Plugin check

package/bin/aos-uninstall.mjs

@@ -5,6 +5,9 @@
 //   aos-uninstall --purge      also the memory store, wikis and credentials
 //   aos-uninstall --dry-run    list everything, delete nothing
 //   aos-uninstall --yes        skip the confirmations (CI only)
+//   aos-uninstall --restore-plugin-backup
+//                              put back the loose skill copies the installer removed when it
+//                              registered the bdb-aos plugin (never overwrites an existing file)
 //
 // The file-level install manifest records every path AOS wrote together with
 // the sha256 it wrote. That is what makes a precise uninstall possible: a file
@@ -19,6 +22,9 @@ import { createHash } from 'node:crypto';
 import { createInterface } from 'node:readline/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const pm = createRequire(import.meta.url)('../lib/plugin-migration.js');
 
 const HOME = os.homedir();
 const h = (...p) => path.join(HOME, ...p);
@@ -27,6 +33,7 @@ const tilde = (p) => p.replace(HOME, '~');
 const PURGE = process.argv.includes('--purge');
 const DRY = process.argv.includes('--dry-run');
 const YES = process.argv.includes('--yes');
+const RESTORE = process.argv.includes('--restore-plugin-backup');
 
 const MANIFEST = h('.agents', '.bdb-install-manifest.json');
 
@@ -238,13 +245,19 @@ function execute(p) {
   for (const l of legacy) { try { rmSync(l); } catch { /* already gone */ } }
   if (legacy.length) console.log(`  ${legacy.length} Installations-Marker entfernt`);
 
+  const reg = pm.readState(HOME).registered.claudecode;
+  if (reg) {
+    const r = pm.deregisterClaude({ home: HOME, record: reg });
+    if (r.changed) console.log(`  bdb-aos Plugin-Registrierung aus settings.json entfernt${reg.replaced ? ` (externer Marketplace ${reg.replaced.key} wiederhergestellt)` : ''}`);
+  }
+
   // Only the BDB hook entries leave settings.json; everything else in it is
   // the user's and must survive an uninstall exactly as it survives an install.
   const settings = h('.claude', 'settings.json');
   if (existsSync(settings)) {
     try {
       const s = JSON.parse(readFileSync(settings, 'utf8'));
-      const bdb = ['go-gate.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
+      const bdb = ['go-gate.mjs', 'go-token.mjs', 'go-grant.mjs', 'graph-gate.mjs', 'memb-inject.mjs', 'trail-relay.mjs', 'trail-autostart.mjs', 'conventional-commits.mjs', 'env-file-protection.mjs'];
       let touched = false;
       for (const [event, entries] of Object.entries(s.hooks || {})) {
         const kept = entries.filter((e) => !(e.hooks || []).some((x) => bdb.some((n) => String(x.command).includes(n))));
@@ -266,6 +279,7 @@ function execute(p) {
   for (const f of [MANIFEST, h('.agents', '.bdb-manifest.json')]) {
     try { rmSync(f); } catch { /* already gone */ }
   }
+  pm.retireState(HOME);
 }
 
 // ---------------------------------------------------------------------- main
@@ -276,6 +290,16 @@ const ask = async (q) => {
   return a;
 };
 
+if (RESTORE) {
+  const r = pm.restorePluginBackups({ home: HOME });
+  if (!r.dirs.length) { console.log('Keine Plugin-Migrations-Sicherung gefunden.'); process.exit(1); }
+  console.log(`  ${r.files.length} Dateien aus ${r.dirs.length} Sicherung(en) wiederhergestellt, im Install-Manifest erfasst`);
+  console.log('Vorhandene Dateien wurden nicht überschrieben.');
+  if (r.deregistered) console.log('  bdb-aos Plugin-Registrierung entfernt, damit die Skills nicht doppelt geladen werden. Setze AOS_PLUGIN_MIGRATION=off, damit der Installer sie nicht erneut entfernt.');
+  else if (r.files.length && r.stillEnabled) console.log('  WARNUNG: das bdb-aos Plugin ist weiterhin aktiv, die Skills erscheinen doppelt. Plugin in Claude Code deaktivieren und AOS_PLUGIN_MIGRATION=off setzen.');
+  process.exit(0);
+}
+
 const p = plan();
 console.log(PURGE ? '\x1b[31mAOS UNINSTALL — PURGE\x1b[0m' : 'AOS Uninstall');
 if (!describe(p)) process.exit(1);

package/commands/brainstorm.md

@@ -0,0 +1,5 @@
+---
+description: "Brainstorm a topic with the matching skill: bdbrainstorm, bdbmediastorm for event tech, grill-me for a stress test."
+---
+
+Pick by topic: `bdbmediastorm` for live event technology and show control, `grill-me` when the human wants an existing idea stress-tested, `bdbrainstorm` otherwise. Say which one you chose. Topic: $ARGUMENTS

package/commands/doctor.md

@@ -0,0 +1,5 @@
+---
+description: "Check the machine and the current project, and print suggested permissions.allow entries without writing any settings."
+---
+
+Run `aos-doctor` (machine check) and report the result. If the current folder is an AOS project, also run the project check `node <aos-project-init skill dir>/scripts/aos-project-doctor.mjs` (it covers `.aos/project.json`, AGENTS.md and the wiki). Print suggested `permissions.allow` entries as text for the human to copy. Never write to settings.json or settings.local.json. Arguments: $ARGUMENTS

package/commands/graph.md

@@ -0,0 +1,5 @@
+---
+description: "Run the startcycle-graph pipeline: durable state, repair loop, quality gate, escalation."
+---
+
+Run the `startcycle-graph` skill; its contract defines the flow. Task: $ARGUMENTS

package/commands/init.md

@@ -0,0 +1,5 @@
+---
+description: "Set up the current project folder for AOS: slug, wiki, memory, Synapse map, AGENTS.md."
+---
+
+Run the `aos-project-init` skill for the current project folder. This is project setup, not machine setup (that is `/bdb-aos:setup`). Arguments: $ARGUMENTS

package/commands/loop.md

@@ -0,0 +1,5 @@
+---
+description: "Run a prompt repeatedly on an interval, using the harness built-in plus loop templates."
+---
+
+Use the built-in `/loop <interval> <prompt>` (omit the interval to self-pace). Offer a `loop-templates` template when the human has no prompt yet. Safety: a loop prompt never issues a GO, never types or runs `gogate`, never sets a mode or grant, and never merges, pushes or publishes unless a valid grant covers the action. Act on a guarded step only if the human's immediately preceding message is a literal GO or a valid grant covers it; a loop iteration never satisfies the first condition, so it must STOP and report instead of continuing a blocked guarded step. Templates (CI until green, follow a PR to merge, review rounds until no blockers, daily session summary) live in the `loop-templates` skill with run and duration limits and a stop condition each. Arguments: $ARGUMENTS

package/commands/mastersession.md

@@ -0,0 +1,5 @@
+---
+description: "Supervise other Claude Code sessions on this machine: roster, status requests, GO board, idle notices."
+---
+
+Act as the master session with the `master-session` skill (ACP bridge: `bin/aos-acp.mjs`, see docs/master-session-acp.md). Keep the overview, relay the human's decisions, never decide for the human. Arguments: $ARGUMENTS

package/commands/memb.md

@@ -0,0 +1,5 @@
+---
+description: "Query or store long-term memory with memB."
+---
+
+Use `memb-skill` to search or remember and `memb-ingest` to import material. Never store secrets, tokens or credentials. Arguments: $ARGUMENTS

package/commands/orchestrator.md

@@ -0,0 +1,5 @@
+---
+description: "Coordinate parallel coding agents across repositories through the AO daemon."
+---
+
+Use the `ao-orchestrator` skill. It needs the AO daemon; check that it is running first and stop with a clear message if not. Do not confuse it with `agent-orchestrator`. Arguments: $ARGUMENTS

package/commands/plan.md

@@ -0,0 +1,5 @@
+---
+description: "Plan end to end: draft, render in plan-canvas or Plan Builder, annotate, await approval, then hand off."
+---
+
+Run the full planning pipeline: 1) draft the plan with `concise-planning`; 2) always offer the choice between plan-canvas and Plan Builder (`visual-plan`) for rendering; 3) collect annotations and wait for the human's approval; 4) only after approval continue with `writing-plans` or `/bdb-aos:graph`. Topic: $ARGUMENTS

package/commands/playbooks.md

@@ -0,0 +1,5 @@
+---
+description: "List all pb-* playbooks with duration, difficulty and requirements, and start one."
+---
+
+Run `node <bdb-aos skill dir>/scripts/list-playbooks.mjs` and show its output (name, est_time, difficulty, requires of every `pb-*` skill). If the human names a playbook in the arguments or picks one, start that `pb-*` skill; start nothing otherwise. Each playbook keeps its own go-gate points. Arguments: $ARGUMENTS

package/commands/setup.md

@@ -0,0 +1,5 @@
+---
+description: "Bring this machine to a complete, verified AOS installation (skills, MCP servers, gate hooks, memB, OpenWiki, Synapse)."
+---
+
+Run the `aos-setup` skill for this machine. Report what is installed, what was repaired and what is still missing. Arguments: $ARGUMENTS

package/commands/shipping.md

@@ -0,0 +1,5 @@
+---
+description: "Pre-ship framing and the technical release gate, with approvals under the go-gate rules."
+---
+
+Use `bdb-shipping-skill` for the pre-flight and `godmode-shipping` for the gate. The playbook `pb-ship` can drive the whole flow. Push, merge and publish need the human's GO under the go-gate rules; never request one on the human's behalf. Arguments: $ARGUMENTS

package/commands/startproject.md

@@ -0,0 +1,5 @@
+---
+description: "Start a new composition: project init, brainstorm, then ask whether graph or startcycle follows."
+---
+
+Sequence: 1) `aos-project-init`; 2) `bdbrainstorm`; 3) stop and ask the human whether `/bdb-aos:graph` (startcycle-graph) or `startcycle` follows. Do not start a pipeline on your own. Idea: $ARGUMENTS

package/commands/store.md

@@ -0,0 +1,5 @@
+---
+description: "Browse and preview AOS skills, agents and playbooks in the local store UI."
+---
+
+Start the `aos-store` interface. Preview freely, but install nothing until the human says yes for that specific item. Arguments: $ARGUMENTS

package/docs/codex-agy-setup.md

@@ -0,0 +1,16 @@
+# Codex and Antigravity (agy) plugin setup
+
+Both manifests are generated from `plugin-commands.json` by `node scripts/build-plugin-manifest.mjs` and checked by `--check` (stale or missing files, version drift against `package.json`, referenced files, no `disable-model-invocation` in any Codex output).
+
+## Codex
+
+- **Load:** `codex plugin marketplace add <path-to-this-repo>` (it reads `.agents/plugins/marketplace.json`), then `codex plugin add bdb-aos@bdb-aos`.
+- **Invoke:** `$bdb-aos:<cmd>`, for example `$bdb-aos:setup`. Codex has no `/` command for plugin skills.
+- **How it is built:** each command becomes a wrapper skill in `plugins/bdb-aos-codex/skills/<cmd>/SKILL.md`. The plugin ships only these wrappers; the 200+ AOS skills reach Codex through the installer's `~/.codex/skills` copies, and a wrapper tells the model which one to run.
+- **Bodies:** `bodies.codex` is optional; without it the Claude body is used with `/bdb-aos:<cmd>` rewritten to `$bdb-aos:<cmd>`.
+
+## Antigravity (agy)
+
+- **Load:** `agy plugin install` against `plugins/bdb-aos` (its `plugin.json` sits at the plugin root), or `agy plugin validate plugins/bdb-aos` to check it.
+- **Invoke:** `/bdb-aos:<cmd>`, for example `/bdb-aos:setup`.
+- **Bodies:** commands reuse `commands/<cmd>.md`. A command with `bodies.agy` is written to `agy-commands/<cmd>.md` and wired instead.