# agent-lib One Go binary, two roles: **curator** and **client**. - **Curator side** — `agent-lib vendor …` pulls external git repositories into a plain work repository under `external///`, pinned by revision, with per-source selection and collision-safe naming. Publication is nothing more than `git commit && git push`. - **Client side** — `agent-lib sync` pulls the work repository and deploys its content into the OpenCode runtime paths. Local modifications win over company updates, self-created items are never touched, and Windows toast notifications tell employees when their edits blocked an update. No Nix, no Python, no git subprocess at runtime — a single static binary for windows/amd64, linux/amd64, linux/arm64, darwin/amd64 and darwin/arm64. ## Installation Download the binary for your platform from the [GitHub releases](https://github.com/m3tam3re/agent-lib/releases), verify the checksum, and put it on your `PATH`: ```sh curl -fsSLO https://github.com/m3tam3re/agent-lib/releases/latest/download/agent-lib_linux_amd64.tar.gz tar xzf agent-lib_linux_amd64.tar.gz sha256sum -c checksums.txt --ignore-missing install -m 0755 agent-lib /usr/local/bin/ agent-lib version ``` Fleet-managed machines receive the binary via a pinned rollout — see [docs/fleet-handoff.md](docs/fleet-handoff.md). There is no self-update. From source: `go build .` (version is baked in via ldflags; `make build` uses the git description). ## Curator guide The work repository layout: ``` skills//SKILL.md own skills (folder artifacts) commands/.md own OpenCode commands agents/.md own OpenCode agents mcp/.yaml own MCP fragments (never deployed by the binary) external/// vendored content, mirrors the same four types agent-lib.lock.json lockfile v2 — pins every source agent-lib.labels.json optional — restricts items to labeled clients ``` This layout is **exactly** what OpenCode natively consumes — agent-lib is deliberately on the opencode standard, no conversion layer: | Type | Canonical form | |---|---| | skills | `/SKILL.md` folder (any depth, category nesting ok) | | commands | flat `commands/.md` | | agents | flat `agents/.md` | | mcp | flat `mcp/.yaml` (inventoried, never deployed) | **Migrating from folder-style agent repos** (e.g. `agents//AGENT.md` layouts): flatten `agents//AGENT.md` → `agents/.md`, and move documentation and manifests (`SCHEMA.md`, `agents.json`, `README.md`) out of the typed directories. No folder support for agents/commands is planned — adapting the source repo to the standard beats shipping a renderer. ### Vendoring a source ```sh agent-lib vendor add superpowers https://github.com/obra/superpowers/tree/main/skills ``` Pasted GitHub/GitLab web-tree URLs are normalized automatically. A URL pointing directly at a type directory (e.g. `…/tree/main/skills`) selects that directory as the skills root. `--ref ` pins a ref; the resolved revision is pinned in the lockfile. Discovery understands the four standard directories (`skills/`, `commands/`, `agents/`, `mcp/`); skills are folders containing `SKILL.md` — found at **any depth**, so category-nested layouts (`skills/engineering/tdd/SKILL.md`) work too, with the folder's base name as the skill id — commands and agents are flat `.md` files, MCP fragments are `.yaml`. A flat `.md` under `commands/` or `agents/` whose frontmatter contains none of the definition keys (`name`, `description`, `mode`, `agent`, `model`, `argument-hint`, `temperature`, `permission`) is treated as dropped documentation: skipped with a recorded warning, never an inventory entry. Everything is read-only scanned — upstream code is never executed. ### Selection rules - Default: vendor **everything** (`mode: all`). - `--include a,b,c` switches the source to **include mode**: only those ids arrive, and new upstream items do **not** arrive automatically. - `--exclude a,b,c` keeps **all mode** minus those ids — for taking the majority of a source while dropping a few items. - `--types skills,commands` (**allow-list**) and `--exclude-types agents,mcp` (**deny-list**) filter whole content types. The filter is stored as `exclude_types` in the lockfile and **survives updates**: new upstream items of an excluded type never enter the work repository. `--types` covering all four types normalizes to no filter; excluding all four fails at the zero-selection guard. - Hard errors, enforced by `vendor add`, `vendor update`, `vendor select` and `validate`: - `all` combined with an include list → error - an exclude list without `all` → error (not supported in v2 selections) - an include or exclude entry that no longer exists upstream → error naming the item - `--include` combined with `--exclude` → error - `--types` combined with `--exclude-types` → error - unknown type names → error listing `skills, commands, agents, mcp` - an include entry belonging to a type the type filter excludes → error (`vendor select` changes selections later — see [Changing your selection later](#changing-your-selection-later) below.) ### Changing your selection later `vendor select` manages the selection after the initial add — without ever advancing the pinned revision (that is `vendor update`'s job): ```sh agent-lib vendor select superpowers --add tdd,brainstorm # include mode: grow agent-lib vendor select superpowers --remove review,debug # include mode: shrink agent-lib vendor select superpowers --remove review # all mode: move to exclude agent-lib vendor select superpowers --types skills # replace the type filter agent-lib vendor select superpowers --mode all # reset: take everything again ``` - **include mode**: `--add` appends ids (validated against the pinned upstream — typos abort with the list of available ids), `--remove` drops ids and deletes their folders from `external/`. - **all mode**: `--remove` moves ids onto the exclude list (lockfile v2 supports exclude in all mode) and deletes their folders; `--add` is a hard error — everything is already selected. - `--types` / `--exclude-types` **replace** the content-type filter (same semantics as on `vendor add`); when neither flag is passed, the stored filter stays as-is. - `--mode all` clears include/exclude **and the type filter** and re-materializes the full pinned upstream, reporting what appeared. Every select re-runs the collision checks and honors the lockfile rename map — you can hand-add a rename for a not-yet-selected item, then `--add` it under its deployed name. Failed selects mutate nothing. ### Collisions and renames Every item deploys into a flat per-type namespace. If a vendored id collides with one of your own items (or with another source's item), the operation aborts with a hard error naming both parties — before anything is written. Resolve it with an explicit, reviewable rename: ```sh agent-lib vendor add superpowers "$URL" --rename review=superpowers-review ``` The on-disk folder always carries exactly the deployed name. Renaming onto another collision is an error. ### Friendlier names for your users Renames are not only for collisions — use them to give vendored items names your colleagues recognize. `vendor rename` changes them at any time, without moving the pinned revision or the selection: ```sh agent-lib vendor rename superpowers brainstorming=ideen-sammeln tdd=test-first agent-lib vendor rename superpowers --reset tdd # back to the upstream id agent-lib vendor rename superpowers # list current renames ``` - The rename map lives in the lockfile and survives `vendor update` and `vendor select`. - A renamed skill gets the `name:` in its `SKILL.md` frontmatter rewritten to the new folder name (OpenCode requires both to match and shows that name). Commands and agents are renamed via their file name only. - Skill names must be 1–64 lowercase letters, digits and single hyphens (`code-review`, not `Code Review`). No name of any type may contain path separators or start with a dot. - Renaming an id that is not selected yet is allowed; it applies once the item is added via `vendor select --add`. - On the next `agent-lib sync`, clients receive the item under the new name; the old name is removed from their machine like any upstream deletion (locally modified copies stay, as usual). ### The maintenance loop ```sh agent-lib vendor diff superpowers # read-only preview: new/changed/deleted vs selection agent-lib vendor update superpowers # fetch latest of the pinned ref, rewrite, report agent-lib vendor update --all # every source, reported per source agent-lib vendor remove superpowers # delete external area + lockfile entry ``` In `all` mode new upstream items arrive automatically (and appear in the update report); in include mode they deliberately do not — `vendor diff` surfaces them as `available upstream, not selected`. Every update re-runs the collision checks and honors the rename map. ### Auditing ```sh agent-lib validate # offline: rules + tree/lockfile consistency agent-lib vendor list # sources with pin, mode, item counts agent-lib vendor inspect # full inventory with metadata + warnings ``` All three accept `--json`. The lockfile is deterministic JSON (sorted keys, fixed indentation) — identical reruns produce identical bytes, so git diffs stay clean. ## Client guide Employees run two commands: ```sh agent-lib sync # pull the work repository and deploy agent-lib status # report local state; exit 1 when updates are blocked ``` Both accept `--repo ` / `--ref ` for config-free personal use — see [Configuration](#configuration) below. Deployment mapping (OpenCode target): | Type | Destination | |---|---| | skills | `~/.agents/skills//` (whole artifact folders) | | commands | `~/.config/opencode/commands/.md` | | agents | `~/.config/opencode/agents/.md` | | mcp | **never deployed** — stays under fleet-controller merge | ### Sync semantics (three-state) Sync plans before it mutates. For every item the planner compares the repository, the local manifest and the on-disk content: - new item → **deploy** - managed & unmodified, upstream changed → **update** - managed & locally modified → **skip + warn** — your version stays - on disk but never deployed by us → **leave + warn** — self-created items are safe by construction - upstream deleted & unmodified → **remove** - upstream deleted & modified → **skip + warn** — your version stays With `--force` the two skip cases turn into **update** and **remove** — the repository version wins over local modifications. Unmanaged items (leave + warn) are never touched, even with `--force`; neither are paths occupied by items agent-lib never deployed. Sync is idempotent (a second run is a byte-level no-op) and fails cleanly: an unreachable repository never leaves a half-deployed machine. The default branch is resolved from the remote's advertised `HEAD`, so a sync without `--ref` always tracks the server's current default branch — even after the cache has been re-fetched many times. ### Configuration The repository to pull comes from the first source that provides one: 1. `--repo ` flag (works with **no config file at all**) 2. `--config ` flag 3. `AGENT_LIB_CONFIG` env 4. user-level config (personal machines) 5. admin-protected platform default (fleet rollout) | Source | Linux / macOS | Windows | |---|---|---| | user-level config | `$XDG_CONFIG_HOME/agent-lib/config.json` (default `~/.config/agent-lib/config.json`) | `%AppData%\agent-lib\config.json` | | admin default | `/etc/agent-lib/config.json` | `%ProgramData%\agent-lib\config.json` | `--repo` overrides a `repo_url` from any discovered config; `--ref` narrows it to a branch or tag. When no config exists anywhere, the error lists every searched location, a minimal working example, and the `--repo` shortcut. ```json { "repo_url": "https://git.example.com/company/agent-content.git", "ref": "main", "token": "", "token_user": "oauth2" } ``` The token is used for basic auth only. It never appears in the lockfile, the manifest, logs or error messages. On `--repo` runs (or when the discovered config carries no token) `AGENT_LIB_GIT_TOKEN` / `AGENT_LIB_GIT_USER` supply credentials instead — env never overrides a configured token. **Personal quickstart (no fleet, no config):** ```sh agent-lib sync --repo https://github.com/you/your-agent-content.git ``` The work repository must be a committed git repository (sync pulls it read-only via go-git; local uncommitted state is ignored). ### Client labels Not every client needs every item. Restrict items to clients that carry a matching label with an optional `agent-lib.labels.json` at the work repository root: ```json { "version": 1, "labels": { "sales": ["crm-agent", "quote-writer"], "finance": ["officecli-financial-model", "crm-agent"] } } ``` - **Unlabeled items go to every client.** Only restricted items appear in the file; a new item needs no entry to reach everyone. - Entries are deployed item names (after renames) and match across types — one entry covers a skill and a command of the same name. MCP fragment names are allowed too (fleet tooling can scope MCP from the same file; the binary never deploys MCP). - An item under several labels reaches clients with any of them. - Labels match `^[a-z0-9][a-z0-9-]*$`; lists must be non-empty; unknown keys and unknown versions are errors. Clients opt in through `labels` in their config: | `labels` | Delivered | |---|---| | absent | everything — no filtering (default, backward compatible) | | `[]` | unlabeled items only | | `["sales", "lead"]` | unlabeled items plus items labeled `sales` or `lead` | **Admin-pinned:** when the admin default config exists and sets `labels`, that value applies no matter which config supplied `repo_url` — a user-level config, `AGENT_LIB_CONFIG` or `--config` can neither widen nor drop it. On Windows the admin location is resolved through the ProgramData known folder, not the user-controlled `ProgramData` variable. An admin config that exists but cannot be read (including permission denied) or parsed aborts the run — the admin's selection is unknown, so none is guessed. Sync filters before planning. An item that is no longer selected follows the upstream-deletion rules: unmodified copies are removed, locally modified copies are kept with a warning (`--force` removes them); the reason reads "not selected for this client's labels". Such a kept copy blocks no repository update and therefore does not count as drift in `status`. A labels file that does not validate **aborts the sync before any change** — it never falls back to delivering everything. Names that match no item only warn on clients that carry labels; `agent-lib validate` treats them as errors on the curator side (also in repositories without a lockfile). `vendor rename` rewrites matching labels entries so a renamed item keeps its labels. `sync` and `status` print the active selection (`labels: sales (admin) — 12 item(s) not selected`); `status --json` adds a `labels` object with `client`, `source`, `labels_file`, `not_selected` and `unknown_names`. Labels are a relevance filter, **not access control**: every client still fetches the whole revision into its cache. Keep confidential material in a separately authenticated repository. ### Notifications On Windows, a toast fires when (and only when) a sync kept local modifications or discovered unmanaged items — never for routine syncs. The same warnings are appended to the sync log (`~/.local/state/agent-lib/sync.log` on Linux, `%LocalAppData%\agent-lib` on Windows) and surfaced by `status`. Linux/macOS notification is a no-op. `status --json` is machine-readable: deployed revision, repository revision, pending changes, skipped and unrecognized items, and a `problematic_drift` flag that drives the non-zero exit code — suitable for headless drift checks. ## Security / trust model - External sources are **untrusted**. Discovery and vendoring never execute upstream code; only file contents are read. - The shared read-only token limits blast radius; rotation is a single fleet run (see the handoff doc). - MCP fragments from vendored sources are **never activated** by the binary; merging and vault substitution remain an explicit fleet-controller decision. - Binary updates happen exclusively via pinned fleet rollouts — there is no self-update path to abuse. ## Troubleshooting | Symptom | Cause / fix | |---|---| | `error: … no client config found. Searched (in order): …` | No config anywhere. Create one where the error suggests, or skip it: `agent-lib sync --repo `. | | `error: … include entry "x" not found upstream` | Typo, or the item was renamed/removed upstream. Fix the lockfile include list, or re-add with a corrected `--include`. | | `error: … collides with own skills "x"` | Deployed-name collision. Add `--rename =` (add) or fix the rename map (update). | | `validate` reports tree/lockfile divergence | Someone edited `external/` by hand. Re-run `vendor update ` to restore the pinned state. | | Skill didn't update, `skipped (local modifications kept): 1` | Working as designed — you edited the deployed item. Run `agent-lib sync --force` to overwrite local modifications with the repository version, or delete the local copy and re-sync. | | `status` exits 1 | Local modifications block repository updates (or occupy names the repo needs). See `status` output for the item list. | | Sync fails with clone/fetch error | Work repository unreachable, or token expired. Previous local state remains intact; fix config/network and re-run. | | No toast on Windows | Toasts need an interactive user session — the scheduled task must run as the logged-in user, not SYSTEM. | | Terminal window flashes on scheduled sync (Windows) | The task runs the console program `agent-lib.exe`. Point it at `agent-libw.exe sync` from the same zip: same commands, no window, no output. | ## Development ```sh make build # build with version ldflags make test # unit + black-box e2e (fully offline, local fixture git repos) make lint # go vet + gofmt check ./scripts/e2e-acceptance.sh # full spec walk: 60+ assertions, offline ``` Release: `goreleaser release` on a tagged commit builds all five targets with checksums and publishes to GitHub releases. Verify with `goreleaser release --snapshot --clean` or a tagged `--skip=publish` dry run. ## Scope and non-goals (v2) In scope: vendoring with selection/renames into any git work repository; OpenCode-only deployment with three-state protection; toast notifications; goreleaser/GitHub release pipeline. Client-side selection is limited to label filtering (see Client labels) — no per-client profiles, overrides or inheritance. Not in scope: additional targets (Pi, Hermes, Crush, Amp), MCP merge/vault (fleet-controller concern), binary self-update, git submodule sources, migration tooling from the Python-era lockfile.