@hybridlabor-api/aos 4.15.0 → 4.17.0

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.

package/docs/opencode-setup.md

@@ -0,0 +1,36 @@
+# OpenCode setup
+
+The AOS installer copies these into `~/.config/opencode` (`%APPDATA%\opencode` on Windows):
+
+- `plugins/bdb-aos.js` with `plugins/aos-hooks/` and `plugins/lib/` (go-gate, loop keeper, bus)
+- `commands/startcycle-graph.md` and one generated `commands/bdb-aos-<cmd>.md` per AOS command, called as `/bdb-aos-<cmd>` (flat hyphen names; a colon is not valid in Windows file names)
+
+The command files are generated from `plugin-commands.json` by `node scripts/build-plugin-manifest.mjs` and checked by `--check`. A command may carry `bodies.opencode`; without it the Claude body is used with `/bdb-aos:<cmd>` rewritten to `/bdb-aos-<cmd>`.
+
+## Updating and your edits
+
+- A command file you edited is kept; the shipped version lands next to it as `<file>.new`.
+- A file that already existed under a shipped name but was never installed by AOS is kept the same way.
+- The installer never deletes files it did not create.
+
+## Lean MCP set
+
+OpenCode deliberately runs a small MCP set (`memb_mcp`, `deja`, `zavora_computer_use`). AOS never copies other harnesses' MCP lists into OpenCode and never adds ComfyUI or show-control MCPs there. Media playbooks stop with "Missing MCP" on OpenCode by design.
+
+## Optional components (off by default)
+
+```bash
+AOS_OPENCODE_OPTIONAL=ponytail,loop,rtk aos        # or: aos --opencode-optional=ponytail,loop,rtk
+```
+
+- `ponytail`: appends `@dietrichgebert/ponytail@4.10.0` to `plugin[]`
+- `loop`: appends `@bybrawe/opencode-loop@0.6.2` to `plugin[]`
+- `rtk`: prints `brew install rtk && rtk init -g --opencode`; AOS installs nothing
+
+Entries are appended only when no entry for that package exists, after a timestamped `opencode.jsonc.<ts>.bak` backup. AOS never runs foreign installers (the `opencode-loop` npx installer rewrites the config) and skips `orca-opencode-status.js` (the Orca app maintains it) and `dag.jsonc` / GraphAgent (AGPL engine, different program).
+
+## Known limits
+
+- **`/loop-shell` and the go-gate (unverified).** `opencode-loop` can run shell commands as child processes. `tool.execute.before`, where the AOS go-gate sits, may never see them. Do not schedule `git push`, publish or other gated commands through them. The installer prints this warning whenever `opencode-loop` is in `plugin[]`.
+- **Machine prompts are never human.** Every prompt the plugin sends itself (loop nudge, bus wake) is `synthetic` and carries `aos_loop` or `aos_bus` metadata, so it cannot count as a GO. A test scans the plugin source for this.
+- **Double loading of `bdb-aos.js`.** OpenCode auto-loads `plugins/*.{ts,js}` and also loads paths in `plugin[]`. From the 1.18.30 binary strings: both lists are merged through one de-duplication keyed on the `file://` URL, so the same absolute path loads once (read from the binary, not observed by running OpenCode). A differently spelled second path (checkout path, symlinked config dir) would load twice, giving two gates and two loop keepers. The installer registers exactly one path, `<config>/plugins/bdb-aos.js`, and warns when `plugin[]` holds another spelling.

package/docs/plugin-migration.md

@@ -0,0 +1,61 @@
+# Plugin registration and loose-copy migration
+
+The installer registers the `bdb-aos` plugin for Claude Code, then removes only its own loose skill copies there. Hooks, MCP servers, `trail-autostart` and the bus stay in the installer, so disabling the plugin never disables the go-gate.
+
+| Harness | Loose copies | Why |
+|---|---|---|
+| Claude Code | **removed** from `~/.claude/skills` only after registration **and** evidence that Claude Code installed the plugin | the plugin bundles the skills |
+| Codex | stay (`~/.codex/skills`) | the Codex plugin bundles only the command wrapper skills; nested skill scanning is unverified |
+| agy | stay (`~/.gemini/config/skills`) | skill bundling is unverified (`agy plugin validate` processed 9 skills) |
+| OpenCode | stay | plugins cannot bundle skills |
+| all | `~/.agents/skills` always stays as the shared store | |
+
+## Rules
+
+- **Registration first, evidence second.** Registration means `settings.json` holds the marketplace and `enabledPlugins` keys; that alone proves nothing about an installed plugin. Copies are removed only when Claude's plugin state shows the install: an entry for `bdb-aos@bdb-marketplace` in `~/.claude/plugins/installed_plugins.json`, or a cache directory `~/.claude/plugins/cache/bdb-marketplace/bdb-aos/<version>`. Either way the directory must resolve (realpath) under `~/.claude/plugins`, must not be cached from another (older external) marketplace, and must contain `skills/<name>/SKILL.md` for a skill the install manifest lists for `~/.claude/skills`. `installPath: "/"`, an empty `skills` dir or a path elsewhere do not count. The `installed_plugins.json` shape (`{version, plugins: {"<name>@<marketplace>": [{installPath, ...}]}}`) is verified against other plugins on a local machine; that `bdb-aos` writes the same shape and the cache layout fallback are **inferred**, not observed.
+- **Not verifiable yet.** The installer registers the plugin, keeps every copy and prints "restart Claude Code, then run the installer again to retire the loose copies". The retirement happens on a later run once the evidence exists. Until then the installer keeps writing `~/.claude/skills` as before.
+- **Ordering.** The migration runs before the install target loop. Once Claude is covered, `~/.claude/skills` is not written again, so a rerun changes nothing and creates no backup.
+- **Merge, never overwrite.** Other keys survive. `settings.json` is backed up (`settings.json.<ts>.bak`) before a change; an unchanged file is not rewritten. A symlinked `settings.json` is written through to its real file and stays a link.
+- **Opt-out.** `"bdb-aos@bdb-marketplace": false` in `enabledPlugins` (or `bdb-aos@<old external key>: false`): nothing is registered, nothing is removed.
+- **Own copies only, safely resolved.** A file is removed when the install manifest lists it and its bytes still match the recorded hash. Keys with `..` or relative paths are rejected; each file and the root are resolved with `path.resolve` and `fs.realpathSync`, the real file must be a regular file under the real root. If `~/.claude/skills` itself is a symlink, nothing is removed. Edited files and files not in the manifest stay.
+- **All or nothing.** If any listed copy is edited or unsafe, nothing is removed, Claude is not treated as covered, the installer names the skills involved and keeps updating the copies it owns. Move your edits out and run the installer again to retire them.
+- **OpenWiki daemon.** `openwiki-skill/scripts/` is never retired, and the daemon is installed and run from the installer-owned `~/.agents/skills/openwiki-skill/scripts` (copied there when missing), so scheduled jobs never point into `~/.claude/skills`.
+- **Malformed settings.** If `enabledPlugins` or `extraKnownMarketplaces` exists but is not a plain object, registration is refused and nothing is written.
+- **One at a time.** A lock file (`~/.agents/.bdb-plugin-migration.lock`, stale after ten minutes or a dead pid) keeps two migrations apart; a file that vanishes mid-run is skipped.
+- **Backup before removal.** Removed files are copied to `~/.agents/backups/plugin-migration-<timestamp>/` keeping their path relative to `$HOME`.
+- **External marketplace.** An entry pointing at `hybridlabor-api/bdb-marketplace` is replaced by this repo's marketplace (`hybridlabor-api/aos`) only when no other plugin id uses it. Only `bdb-aos@<oldkey>` is renamed to `bdb-aos@bdb-marketplace`; other plugins' ids are never renamed. A foreign marketplace that also lists other plugins stays in place. If the name `bdb-marketplace` itself is that external marketplace with other plugins, or points at another source, registration is refused with a message and nothing changes. Nothing on GitHub is changed.
+- **Old command files.** Command files from earlier versions that are no longer in the generated table are not touched by the migration; they are neither removed nor backed up. Only the generated `commands/` set is kept in sync by `scripts/build-plugin-manifest.mjs`.
+- **State.** `~/.agents/.bdb-plugin-migration.json` records each change: `addedMarketplace`, `addedEnabled`, `replaced`, `renames`, `keptForeign`. Deregistering reverses exactly those.
+
+## Packaging
+
+The npm package ships `plugins/bdb-aos-codex/` (a real directory) and the root manifests (`plugin.json`, `.codex-plugin/`, `.agents/plugins/marketplace.json`, `commands/`, `agy-commands/`). `plugins/bdb-aos/` is built from symlinks and is **not** in the npm package. The Claude Code plugin directory (`.claude-plugin/` and `plugins/bdb-aos/`) is git-only: Claude installs it from the GitHub marketplace `hybridlabor-api/aos`, not from npm. `.agents/plugins` (the Codex marketplace file) is excluded from the `.agents` copies into `~/.agents` and project directories.
+
+The root `.codex-plugin/.mcp.json` is no longer referenced: the previous manifest pointed at it through an `mcp_config` key, which real Codex plugins do not use (they use `mcpServers`). It stays unreferenced on purpose, because the installer already registers the MCP servers in Codex's config and the plugin would register them twice. The plugin therefore delivers no MCP servers.
+
+## Opt out and preview
+
+```bash
+AOS_PLUGIN_MIGRATION=off   npx -y @hybridlabor-api/aos@latest   # skip entirely
+AOS_PLUGIN_MIGRATION=check npx -y @hybridlabor-api/aos@latest   # report only
+npx -y @hybridlabor-api/aos@latest --plugin-migration=off|check
+```
+
+`--dry-run` implies `check`. Default is on.
+
+## Undo
+
+```bash
+aos-uninstall --restore-plugin-backup   # puts removed files back, never overwrites an existing file
+aos-uninstall                           # also removes the plugin registration it added and restores a replaced external marketplace
+```
+
+## Known limits
+
+- The lock guards migrations only. An installer copy running at the same moment in another process is not serialized; a file removed under it is skipped, and the next run reconciles.
+- Until Claude Code shows the plugin as installed, both copies exist; skills may then appear twice after the plugin loads and before the next installer run retires the copies.
+- `aos-doctor` accepts the plugin evidence as Claude having the skills.
+- A deregister that reverses a marketplace rename keeps the content of `enabledPlugins` but may reorder its keys (cosmetic).
+- Restoring a backup after an uninstall creates a new install manifest and puts the legacy `~/.claude/skills/startcycle` marker back, so AOS is detected as installed again.
+
+Backups survive uninstall (the state keeps its backup index and `~/.agents/backups/plugin-migration-*` is scanned), so `--restore-plugin-backup` also works afterwards. Restored files are recorded in the install manifest, and the restore deregisters the plugin so skills are not loaded twice; the restore also sets `bdb-aos@bdb-marketplace` to `false` in `settings.json` (the opt-out), so the next installer run does not register the plugin or retire the restored files. Set it back to `true` to migrate again.