README
¶
sauron
Distribute skills and agents to any AI coding assistant — across provider boundaries — and keep them in sync.
sauron is a spec-driven CLI that delivers skills and agents from remote registries (git, HTTP, or filesystem) to the assistant you use (Claude, Zencoder, …). It groups them into shareable personas and reconciles your provider to a desired set with a reviewable plan, manually or on a schedule.
Registry management (add / list / describe / delete registry) ships today;
the remaining commands are specified and being built — see the
feature status index.
How it works
sauron is a command-line app — nothing runs in the background unless you schedule it.
┌──────────────────────┐ ┌──────────────────────┐
│ Registries │ │ User │
│ artifact sources │ │ a developer using │
│ git · http · fs │ │ an AI assistant │
└──────────┬───────────┘ └──────────┬───────────┘
▲ │
│ fetch artifacts │ runs `sauron`
│ (install · sync · upgrade) │ commands
┌─ User env ──┼──────────────────────────────────────────────────┼───────────┐
│ │ │ │
│ ┌────────────┐ ┌──────────────────┐ │ │
│ │ OS crontab ├──▶ │ SAURON CLI │◀───────────────────────┘ │
│ │ (optional) │ │ │ │
│ └────────────┘ └─────┬────────────┘ │
│ │ installs / removes artifacts │
│ ▼ │
│ ┌─────────────┬──────────────┐ │
│ │ Provider │ │
│ │ claude | zencoder │ │
│ │ (artifact directories) │ │
│ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Registries are external artifact sources; the CLI, the optional crontab entry,
and the provider's artifact directories all live in your environment. You
register sources, sauron validates them, and then it installs the skills and
agents you ask for and keeps them current — touching only artifacts it installed.
State lives in files under ~/.sauron/, including the track file that records
exactly what sauron installed and where it came from — the source of truth that
keeps uninstall, sync, and upgrade safe.
The full model — registries, personas, providers, the sync plan, and state — is in the domain documentation.
Who this is for
This is a spec-driven project: behavior is specified before it is built, and the documentation is organized so each reader can go straight to what they need.
- New here? Start with the domain model, then the lifecycle walkthrough to see how a change flows from requirement to shipped code.
- Developers / engineers — the architecture contract (layout, wiring, Use Case/Action), the CLI contract, and how to author specs. Day-to-day workflow is in CONTRIBUTING.
- Architects — the Constitution (governing principles) and the architecture / state contracts.
- Security analysts — the security overview: secret handling, TLS, write integrity, file permissions, and the HTTP registry API's auth model, with links to the rules that own them.
Documentation
| Doc | What it covers |
|---|---|
| Domain model & concepts | what sauron is, the model, and the feature status index |
| Glossary | the canonical domain vocabulary |
| Lifecycle walkthrough | one slice from requirement to shipped, verified code |
| Constitution | governing principles (spec-driven, contracts, implementation, traceability) |
| Spec authoring | how specs and ADRs are written |
| Contracts | the binding CLI · state · architecture · delivery contracts |
| Security overview | the security posture, for analysts |
| Contributing | branching, commits, proposals, the verification gate |
| Agent guide | how AI coding agents work in this repo; routes to every rule |
License — Apache-2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main is the entrypoint for the sauron binary.
|
Package main is the entrypoint for the sauron binary. |
|
internal
|
|
|
cmd
Package cmd assembles Sauron's cobra command tree and its fx bootstrap.
|
Package cmd assembles Sauron's cobra command tree and its fx bootstrap. |
|
config
Package config resolves and provides Sauron's runtime configuration.
|
Package config resolves and provides Sauron's runtime configuration. |
|
infrastructure/repository
Package repository wires the driven adapters — registry and agent — into a single uberfx module.
|
Package repository wires the driven adapters — registry and agent — into a single uberfx module. |
|
infrastructure/repository/agent
Package agent wires the provider adapters implementing the extension.Provider port (pkg/sauron/extension).
|
Package agent wires the provider adapters implementing the extension.Provider port (pkg/sauron/extension). |
|
infrastructure/repository/agent/claude
Package claude is the Claude provider adapter implementing extension.Provider (pkg/sauron/extension).
|
Package claude is the Claude provider adapter implementing extension.Provider (pkg/sauron/extension). |
|
infrastructure/repository/agent/zencoder
Package zencoder is the Zencoder provider adapter implementing extension.Provider (pkg/sauron/extension).
|
Package zencoder is the Zencoder provider adapter implementing extension.Provider (pkg/sauron/extension). |
|
infrastructure/repository/registry
Package registry holds the registry transport adapters implementing the extension.Registry port (pkg/sauron/extension), one file per transport over the shared primitives in registry/api.
|
Package registry holds the registry transport adapters implementing the extension.Registry port (pkg/sauron/extension), one file per transport over the shared primitives in registry/api. |
|
infrastructure/repository/registry/api
Package api holds the primitives the registry transport adapters share: the error classes they raise, the option-resolution helpers, and the directory-backed source.FileSystem.
|
Package api holds the primitives the registry transport adapters share: the error classes they raise, the option-resolution helpers, and the directory-backed source.FileSystem. |
|
infrastructure/repository/storage
Package storage owns Sauron's persisted state under the configured home.
|
Package storage owns Sauron's persisted state under the configured home. |
|
presentation
Package presentation renders Sauron's command output.
|
Package presentation renders Sauron's command output. |
|
telemetry
Package telemetry owns the ECS-encoded zap logger and its fx wiring.
|
Package telemetry owns the ECS-encoded zap logger and its fx wiring. |
|
usecase
Package usecase holds Sauron's use cases and the actions they compose.
|
Package usecase holds Sauron's use cases and the actions they compose. |
|
pkg
|
|
|
sauron/extension
Package extension defines the public ports — Registry and Provider — that external code implements to extend sauron.
|
Package extension defines the public ports — Registry and Provider — that external code implements to extend sauron. |
|
sauron/marketplace
Package marketplace is a fluent, client-go-style client for a Sauron registry's HTTP API.
|
Package marketplace is a fluent, client-go-style client for a Sauron registry's HTTP API. |
|
sauron/source
Package source defines the read-only filesystem abstraction that registry implementations expose once opened.
|
Package source defines the read-only filesystem abstraction that registry implementations expose once opened. |
|
sauron/types
Package types holds the public Go form of sauron's on-disk configuration documents.
|
Package types holds the public Go form of sauron's on-disk configuration documents. |
Click to show internal directories.
Click to hide internal directories.