# 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. An admin config that exists but cannot be parsed aborts the run. 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". 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 the client; `agent-lib validate` treats them as errors on the curator side. `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.