README
¶
Curator
Curator is an agent environment manager (AEM): a single tool that manages what an AI coding agent gets in a project. Skills and their transitive dependencies, executable commands, MCP server requirements, per-agent delivery, and the security gates around all of it. Declarative, reproducible, verifiable.
Curator is implemented in Go and follows the Curator Specification, an open protocol for skill packages, project manifests, installation semantics, and the audit registry; sections are cited across this repository as Spec §N.M.
Status
v0.1 development complete: all twelve phases of docs/implementation-plan.md are done. CI consumes the authoritative schemas and conformance vectors from curator-spec on ubuntu, macos, and windows, plus lint and the naming gate. Work is tracked on the in-repo task board under .task-board/.
Install
# Homebrew (macOS, Linux)
brew install relux-works/tap/curator
# installer script (macOS, Linux)
curl -fsSL https://raw.githubusercontent.com/relux-works/curator/main/install.sh | sh
# Scoop (Windows)
scoop bucket add relux-works https://github.com/relux-works/scoop-bucket
scoop install curator
# Go toolchain
go install github.com/relux-works/curator/cmd/curator@latest
Debian and RPM packages ship with every release, together with SBOMs and cosign signatures. macOS binaries are Developer ID signed (Relux Works, LLC). Verify any downloaded artifact:
gh attestation verify <artifact> --owner relux-works
What Curator manages
- Skill packages:
SKILL.mdplus context directories, with an implementation-neutral machine manifest (agent-skill.json, schemas 1 through 5) declaring commands, runtime layout, capabilities, and dependencies. The legacycsk-skill.jsonfilename remains readable. - Project manifests:
Skillfile.jsonwith exact git references; non-committed development substitutions. - Resolution: transitive dependency closures unified to one commit and one source identity per name, with activation modes.
- Installation: context and runtime separation, install markers with content hashes, a commit-keyed runtime store, command shims, managed per-agent adapters.
- Scopes: project, global, and hybrid (machine-stored, per-project activation).
- MCP requirements: read-only verification of declared MCP servers against agent configuration surfaces.
- Security: source allowlists, declared capabilities, no code execution at install time, and an audit registry client (Ed25519 signed records, deny-wins federation, snapshot verification).
Registry client guarantees
Curator binds persisted rollback and equivocation state to the canonical
registry URL, so signing-key rotation never resets the highest accepted
snapshot. This durable state lives under the Curator home state/registry
directory, outside the disposable cache/registry responses; upgrades migrate
legacy state without lowering it, and corruption or write failure is
fail-closed. A protected catalog distinguishes first use from deletion of a
previously accepted registry state. Record pagination rejects repeated or oversized cursors, more than
10,000 records per artifact query, and responses larger than 16 MiB.
Registry requests use bounded per-attempt and total deadlines. GET requests
retry network failures, 429, and 503 at most twice after the first attempt.
Publication retries the exact body only with its deterministic
Idempotency-Key; other client errors and unsafe requests are never retried.
Redirects are rejected so a registry cannot move a request or bearer token to
another endpoint.
Commands without profile setup
Shell profile changes are not required. After curator install, agents can
invoke project commands through .agents/bin/<command> on Unix and
.agents\bin\<command>.cmd on Windows. Global installation publishes
non-destructive forwarding shims to a safe user directory already on PATH
when one is available; otherwise Curator reports the canonical global bin
location. Installed launchers carry the project command directory and resolved
system dependency directories themselves, preserve the inherited PATH, and
return the child command status.
Repository bootstrap can remain idempotent and non-interactive:
curator bootstrap --if-missing --non-interactive --skills-root "$HOME/src/skills"
curator upgrade .
upgrade fetches only the selected project's direct and transitive dependency
closure. upgrade --dry-run plans with temporary sources and snapshots without
changing source checkouts, caches, security state, runtime state, or project
artifacts.
Interactive users who want bare command names and automatic project switching can cache the optional hook once:
curator shell-init --install
# Add the source command printed above to .zshrc or .bashrc.
Automatic detection selects zsh or bash from SHELL, preserves Git Bash on
Windows, and otherwise selects PowerShell on Windows. The cached hook does not
start Curator during later shell launches. Curator never edits a profile
automatically. Set CURATOR_AUTO_ENV=0 to retain global activation while
disabling project-directory scans.
An open protocol
The specification is an open protocol, not an internal contract: any manager built from it interoperates with the same skills, the same project manifests, and the same audit registries. That matters when internal security policies rule out adopting an external binary and require an in-house implementation instead. One such independent implementation of the protocol is cocoaskills (Python); Curator's conformance against the shared wire formats is enforced directly from the versioned protocol suite in CI; this repository carries no private copy of the expected protocol values.
The registry-service profile is implemented by Curator Skill Registry, which serves signed audit and revocation records plus a verifiable transparency log for any conforming Curator manager.
Development
The repository uses an in-repo task board (.task-board/, epics, stories, and tasks as files) and the agent tooling connected under agents/. Go testing follows the closed-loop tooling of skill-go-testing-tools (including tuitestkit for terminal UI phases).
Contributing
See CONTRIBUTING.md for the working agreements: board-first workflow, discrete signed commits, spec-first rule.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
curator
command
Command curator is the agent environment manager CLI (Spec §15).
|
Command curator is the agent environment manager CLI (Spec §15). |
|
internal
|
|
|
adapters
Package adapters mirrors installed context into the directories each agent reads, with a managed-entries ledger per adapter root (Spec §10).
|
Package adapters mirrors installed context into the directories each agent reads, with a managed-entries ledger per adapter root (Spec §10). |
|
audit
Package audit implements the machine-local audit gate (Spec §12): the decision semantics, local revocations, operator pins, a blocking canary, a small deterministic detector set, and a verdict cache.
|
Package audit implements the machine-local audit gate (Spec §12): the decision semantics, local revocations, operator pins, a blocking canary, a small deterministic detector set, and a verdict cache. |
|
capabilities
Package capabilities parses the capability declaration of Spec §5.5.
|
Package capabilities parses the capability declaration of Spec §5.5. |
|
closure
Package closure resolves the transitive dependency closure of a project manifest (Spec §8.3, §8.4).
|
Package closure resolves the transitive dependency closure of a project manifest (Spec §8.3, §8.4). |
|
config
Package config loads the machine configuration (Spec §7.1) and applies the enforced system configuration with locked keys (Spec §7.2).
|
Package config loads the machine configuration (Spec §7.1) and applies the enforced system configuration with locked keys (Spec §7.2). |
|
devsub
Package devsub parses Skillfile.dev.json, the non-committed development substitution manifest (Spec §6.2).
|
Package devsub parses Skillfile.dev.json, the non-committed development substitution manifest (Spec §6.2). |
|
envfiles
Package envfiles generates the PATH helper files of a project or the global scope (Spec §14.2).
|
Package envfiles generates the PATH helper files of a project or the global scope (Spec §14.2). |
|
gitignore
Package gitignore enforces the managed .gitignore block (Spec §6.3).
|
Package gitignore enforces the managed .gitignore block (Spec §6.3). |
|
gitops
Package gitops shells out to system git for clone, fetch, ref resolution, and snapshot extraction (Spec §8.2).
|
Package gitops shells out to system git for clone, fetch, ref resolution, and snapshot extraction (Spec §8.2). |
|
globalbins
Package globalbins publishes non-destructive forwarding shims for global commands into an existing user PATH directory.
|
Package globalbins publishes non-destructive forwarding shims for global commands into an existing user PATH directory. |
|
hashing
Package hashing computes the deterministic content hash of an installed tree (Spec §8.5).
|
Package hashing computes the deterministic content hash of an installed tree (Spec §8.5). |
|
identifiers
Package identifiers validates the identifier alphabet of Spec §5.2 and the source path rule of Spec §6.1.
|
Package identifiers validates the identifier alphabet of Spec §5.2 and the source path rule of Spec §6.1. |
|
identity
Package identity computes the canonical source identity of git artifacts and matches identities against the machine allowlist (Spec §8.2).
|
Package identity computes the canonical source identity of git artifacts and matches identities against the machine allowlist (Spec §8.2). |
|
install
Package install orchestrates a project installation in the normative phase order of Spec §8.1.
|
Package install orchestrates a project installation in the normative phase order of Spec §8.1. |
|
locale
Package locale analyzes and renders skill localization (Spec §4.3).
|
Package locale analyzes and renders skill localization (Spec §4.3). |
|
manifest
Package manifest parses the project manifest Skillfile.json, schema 1 (Spec §6.1), and edits skill declarations in place.
|
Package manifest parses the project manifest Skillfile.json, schema 1 (Spec §6.1), and edits skill declarations in place. |
|
marker
Package marker reads and writes install markers (.csk-install.json) and implements the up-to-date and tamper-detection semantics of Spec §8.5.
|
Package marker reads and writes install markers (.csk-install.json) and implements the up-to-date and tamper-detection semantics of Spec §8.5. |
|
mcp
Package mcp verifies declared MCP server requirements against the configuration surfaces of the target agent environments (Spec §11).
|
Package mcp verifies declared MCP server requirements against the configuration surfaces of the target agent environments (Spec §11). |
|
protocoljson
Package protocoljson validates the common JSON transport requirements used by portable Curator Protocol objects before a package-specific schema parser decodes them.
|
Package protocoljson validates the common JSON transport requirements used by portable Curator Protocol objects before a package-specific schema parser decodes them. |
|
registry
Package registry implements the audit registry client (Spec §13): canonical bytes, Ed25519 verification against pinned keys, deny-wins federation, snapshot verification with persisted monotonic versions, record caching with TTL and offline grace, and record submission.
|
Package registry implements the audit registry client (Spec §13): canonical bytes, Ed25519 verification against pinned keys, deny-wins federation, snapshot verification with persisted monotonic versions, record caching with TTL and offline grace, and record submission. |
|
runtimestore
Package runtimestore keeps command runtimes once per machine, keyed by skill and commit, and writes command shims (Spec §8.6).
|
Package runtimestore keeps command runtimes once per machine, keyed by skill and commit, and writes command shims (Spec §8.6). |
|
scopes
Package scopes implements the global and hybrid install scopes, the consumer registry, and runtime garbage collection (Spec §8.7, §9).
|
Package scopes implements the global and hybrid install scopes, the consumer registry, and runtime garbage collection (Spec §8.7, §9). |
|
shell
Package shell generates and caches the optional shell hooks of Spec §8: finite upward project search, PATH save and restore, and global activation.
|
Package shell generates and caches the optional shell hooks of Spec §8: finite upward project search, PATH save and restore, and global activation. |
|
skillcheck
Package skillcheck validates one skill package without a consuming project (Spec §15, curator skill check).
|
Package skillcheck validates one skill package without a consuming project (Spec §15, curator skill check). |
|
skillspec
Package skillspec parses and validates the portable skill machine manifest, schemas 1 through 5 (Spec §4), including legacy filename and runtime fallbacks.
|
Package skillspec parses and validates the portable skill machine manifest, schemas 1 through 5 (Spec §4), including legacy filename and runtime fallbacks. |
|
snapshot
Package snapshot maintains the commit-keyed immutable snapshot cache under the machine home: cache/<source>/<commit>/snapshot (Spec §8.2).
|
Package snapshot maintains the commit-keyed immutable snapshot cache under the machine home: cache/<source>/<commit>/snapshot (Spec §8.2). |
|
ui
Package ui renders installed state as a terminal view (plan P11).
|
Package ui renders installed state as a terminal view (plan P11). |
|
verr
Package verr defines the validation error type shared by protocol parsers.
|
Package verr defines the validation error type shared by protocol parsers. |
|
version
Package version resolves the Curator build version.
|
Package version resolves the Curator build version. |
|
whitelist
Package whitelist copies the model-facing context of a skill snapshot (Spec §4.2).
|
Package whitelist copies the model-facing context of a skill snapshot (Spec §4.2). |