Decision record · ADR
ADR-0007: distribute the operator skill as a self-installing plugin package
Status: accepted | Date: 2026-07-04
References: RFC-0008:C-AGENT-PLUGIN, RFC-0004:C-INFERLAB-TOOLCHAIN, ADR-0009
Context
Section titled “Context”InferLab is being published to GitHub, and agents (Claude Code, Codex) are first-class operators of the CLI. Shipping an operator skill as a bare skills/ directory with manual copy installation offers no lifecycle: no update, no uninstall, no diagnosis, and copies drift silently from the shipped content. A maintained distribution pattern exists: the repository root doubles as a plugin marketplace (.claude-plugin/marketplace.json for Claude, .agents/plugins/marketplace.json for Codex), the plugin package lives under plugins/claude plugin / codex plugin CLIs for install, update, uninstall, and doctor. The skill content itself is written against the current CLI surface.
Amended 2026-07-08: this amendment narrows the install-source default within the distribution architecture accepted above — the marketplace layout, the agent-plugin-installer library, and the command group itself are unchanged. It was revised by operator direction after installing the binary itself (a single curl step) and installing the plugin (requiring an explicit path to a local checkout or unpacked release tarball) turned out to be asymmetric in a way operators felt directly. scripts/install.sh already downloads and unpacks the release plugin tarball to a local directory before printing a next-step hint naming the exact inferlab agent install --from-checkout <dir> command to run — the checkout requirement was never actually load-bearing for that path, only the last, unautomated step was missing. Two network-fetch alternatives were weighed to close that last step (install.sh auto-invoking the install command against the directory it already unpacked; a new –from-release fetch mode in the binary) and rejected in favor of a compile-time-embedded default, following the precedent already established by inferlab toolchain install (crates/inferlab/src/toolchain.rs), which materializes release-owned content from binary-embedded sources with no path argument at all and no reproducibility conflict, since — unlike the workspace-side adapter packages ADR-0009 addresses — neither the plugin package nor the toolchain payload is referenced by any workspace-committed, content-hash-pinned lock.
Decision
Section titled “Decision”Ship the operator skill as a repo-root plugin package and add an inferlab agent install|update|uninstall|doctor command group embedding the agent-plugin-installer library (pinned in the workspace Cargo.toml; the lock selects the exact version). Concrete layout in this repository: .claude-plugin/marketplace.json (Claude marketplace), .agents/plugins/marketplace.json (Codex marketplace), and the package under plugins/inferlab/ with per-runtime plugin manifests and skills/inferlab/SKILL.md. Install defaults to a package embedded in the binary at compile time: a single reproducibly-packed tar.gz built at compile time from a crate-local resource copy under crates/inferlab/resources/ (a published crate’s build script cannot reach outside its own crate directory, the same constraint inferlab toolchain install’s embedded payload already satisfies), packed with the same reproducibility discipline as scripts/pack-plugin.sh (sorted members, a fixed timestamp) but implemented directly against that crate-local copy rather than by invoking the script, embedded via include_bytes!, and decompressed to a working directory at install time. A packaging test pins the resource copy byte-identical to the canonical repository-root plugin source. --from-checkout <DIR> remains available as an explicit override supplying a local checkout or unpacked release tarball by path, for local development against a modified plugin package; validate-before-invoke applies identically to both sources. Reasons over the alternatives: (1) one code path gives both runtimes the full lifecycle instead of copy-time-only installation; (2) validate-before-invoke turns a broken package into a precise error; (3) the embedded default removes the checkout requirement entirely rather than only automating around it, and needs no network access, matching the offline-capable goal more directly than a release-tarball fetch would; (4) the plugin package carries no workspace-committed, lock-pinned reference the way ADR-0009’s adapter packages did, so the dual-authority conflict that motivated rejecting embedding there does not apply here. The normative obligations of the command group live in RFC-0008:C-AGENT-PLUGIN; this ADR records why that surface exists and why this shape won.
Consequences
Section titled “Consequences”Positive:
- One command installs, updates, or removes the skill on both runtimes, with doctor diagnosing missing native CLIs; no manual file copying.
- The package is validated before the native CLI runs, so a broken checkout or a corrupted embedded payload fails loudly with the missing path or content named.
- Install needs no checkout, no release tarball download, and no network access by default: the embedded package is offline-capable unconditionally, strengthening the original offline-capability goal rather than only preserving it.
- The embedded package and the running binary are always the same version by construction — the lockstep release versioning ADR-0009 already requires (“every tag stamps the binary…and the agent plugin package with one version”) becomes a physical guarantee instead of a release-process convention.
Negative:
- The plugin lifecycle still depends on the native CLIs’ plugin subcommands remaining stable; a breaking change there surfaces as loud agent-command failures until the pinned library is bumped.
- The skill text can drift from the CLI surface as it evolves — the standing failure mode of shipped operator documentation. No mechanical guard is built (per the ADR-0006 bar); release-time review of the skill against the command surface owns this explicitly.
- A plugin-content-only fix (e.g. a SKILL.md wording correction) now requires a full binary rebuild and release to ship; it can no longer be corrected by publishing a new release tarball alone.
--from-checkoutis the escape hatch for testing an unreleased change without a rebuild. - The crate-local resource copy under
crates/inferlab/resources/duplicates the repository-root plugin source; a packaging test carries the burden of keeping them in sync, the same maintenance cost the toolchain payload already accepts. - One more public command group to document and keep small.
Neutral:
- The skill content is versioned with the repo and pinned into release artifacts; updating an installed skill is an explicit
inferlab agent update. - The release-published
inferlab-plugin.tar.gzasset remains, built by the same script, now serving manual and--from-checkout-style use rather than acting as the primary way to avoid a checkout.
Alternatives Considered
Section titled “Alternatives Considered”Embedded installer command over a repo-root marketplace package: plugins/inferlab with per-runtime manifests, .claude-plugin and .agents/plugins marketplace files, and an inferlab agent command group embedding agent-plugin-installer (accepted)
Section titled “Embedded installer command over a repo-root marketplace package: plugins/inferlab with per-runtime manifests, .claude-plugin and .agents/plugins marketplace files, and an inferlab agent command group embedding agent-plugin-installer (accepted)”- Pros: full lifecycle (install/update/uninstall/doctor) on both runtimes through one code path, package validated before the native CLI runs, offline-capable (the amendment below makes this the unconditional default rather than a checkout-dependent property)
- Cons: depends on native plugin CLI stability and one crates.io library
Raw-copy installation: install.sh copies SKILL.md into each agent’s skills directory (rejected)
Section titled “Raw-copy installation: install.sh copies SKILL.md into each agent’s skills directory (rejected)”- Pros: no new command or dependency
- Cons: no update or uninstall lifecycle; copies drift silently from plugin-managed state; per-runtime layouts hand-maintained
Central marketplace distribution only: publish the plugin to an external marketplace and point users there (rejected)
Section titled “Central marketplace distribution only: publish the plugin to an external marketplace and point users there (rejected)”- Pros: discoverable without cloning the repo
- Cons: adds an external distribution dependency; a checkout or tarball must stay installable without network anyway
install.sh downloads and unpacks the release plugin tarball, then automatically invokes inferlab agent install –from-checkout itself (rejected)
Section titled “install.sh downloads and unpacks the release plugin tarball, then automatically invokes inferlab agent install –from-checkout itself (rejected)”- Pros: reuses install.sh’s already-working fetch/verify/unpack logic with no Rust changes, solves the friction for the curl|sh entry point specifically
- Cons: only fixes the install.sh entry point; a binary obtained any other way (built from source, copied, a future package manager) is still stuck needing an explicit checkout path, keeps two parallel implementations of materializing the plugin package – install.sh’s shell fetch and the binary’s own local-path install – in sync forever
- Rejected because: Fixes only one entry point and leaves the underlying command still checkout-dependent for every other way of obtaining the binary; embedding removes the dependency at its source instead of automating around it for a single caller.
Add a –from-release fetch mode to inferlab agent install that downloads and verifies the matching-version release plugin tarball over the network (rejected)
Section titled “Add a –from-release fetch mode to inferlab agent install that downloads and verifies the matching-version release plugin tarball over the network (rejected)”- Pros: works for any way of obtaining the binary, not only install.sh, keeps the binary itself free of plugin content, so a content-only fix ships without a binary rebuild
- Cons: introduces network dependency, checksum verification, and release-tag-matching logic (including the undefined case of a binary built from an untagged commit) where none existed before, regresses offline capability by making the default path network-dependent unless a checkout is already at hand, no precedent in this codebase for this shape; the toolchain payload’s already-accepted pattern is embed-and-materialize, not fetch-and-verify
- Rejected because: Trades a small, well-understood checkout/tarball-path requirement for new network, checksum, and version-matching failure modes, and moves the default away from offline-capable rather than toward it. inferlab toolchain install’s embedded, path-argument-free precedent already exists in this codebase for exactly this shape of release-owned, non-workspace-pinned content and carries none of these costs.
Embed the plugin package in the binary at compile time as the default install source, keeping –from-checkout as an explicit override (accepted)
Section titled “Embed the plugin package in the binary at compile time as the default install source, keeping –from-checkout as an explicit override (accepted)”- Pros: removes the checkout requirement unconditionally, for every way the binary is obtained, with no network access needed, the embedded content and the binary version are identical by construction, turning the lockstep release convention into a physical guarantee, follows the already-accepted, already-shipped pattern in inferlab toolchain install rather than introducing a new distribution shape
- Cons: a plugin-content-only fix requires a full binary rebuild and release; –from-checkout is the escape hatch for testing unreleased changes, the plugin source is duplicated as a crate-local resource copy so a published crate’s build script can reach it, carrying the same sync-test maintenance cost the toolchain payload already accepts