arpi domain ontology

Status: Superseded

Superseded by template-schema.md. The 5-domain model (cli, definitions, harnesses, registries, environments) is replaced by 6 domains (Identity, Workstation, Compute, Registry, Connectivity, Observability). definitions/ becomes templates/ in the registry. cli/ is no longer the runtime — the control plane is a server.

arpi domain ontology

Decision

arpi has 5 runtime domains, each owning files that arpi spawn reads or executes. If a folder only has docs, it is not a domain.

arpi/
├── cli/                # The Go CLI -- user interface to everything
├── definitions/        # TOML spawn specs -- the unit of composition
├── harnesses/          # Platform-specific agent configs (Claude, Codex, Cursor)
├── registries/         # Governed catalogs (MCP servers, skills)
├── environments/       # Execution backends (images, proxy, gateway config)
├── opensandbox/        # OpenSandbox fork (git submodule, inside environments/)
└── docs/               # ADRs, reference docs (not a domain)

What each domain owns

Domain	Owns	Runtime role
`cli/`	Go source code. Commands (spawn, list, show, status, login, doctor, new). Provider interfaces (IAMProvider, GatewayProvider, SandboxProvider).	IS the runtime.
`definitions/`	TOML files. One file = one `arpi spawn` target. Instructions (AGENTS.md-style markdown) paired with definitions.	`arpi spawn` reads these to know what to assemble.
`harnesses/`	Platform-specific building blocks. `claude-code/` has settings/, hooks/, agents/. Future: `codex/`, `cursor/`.	Assembly copies these into `.claude/` (or equivalent).
`registries/`	mcp.json (single MCP catalog). Skills registry (submodule with Dependabot sync).	Assembly cherry-picks MCPs and skills from here.
`environments/`	Container images, credential proxy config, Bifrost gateway config.	Sandbox mode reads images and proxy config from here.

Key structural decisions

definitions/ is top-level, not inside harnesses/. Definitions are the primary artifact users interact with. They reference harnesses, registries, AND environments — they’re cross-domain. Putting them inside harnesses/ implies they’re harness-specific, but a definition like debug-prod.toml specifies shared MCPs, Claude-specific hooks, AND sandbox config.

registries/ is absorbed into the harness assembly flow but stays separate from harnesses/ because MCPs and skills are cross-platform. The skills registry has its own sync mechanism. mcp.json is the single catalog all definitions pick from.

opensandbox/ is a git submodule inside environments/. It’s a fork of another project (sharpi/opensandbox) with its own build system, tests, CI. It doesn’t belong as a subdirectory — it’s a linked repo.

iam/ is gone as a top-level domain. IAM code lives in cli/internal/iam/ (the Go module that implements IAMProvider). IAM decisions live in ADRs. The credentials inventory is a reference doc in docs/. arpi login is CLI code, not a separate domain. IAM infrastructure (Infisical terraform, deployment, Better Auth for products, access policies) is owned by the iam/ module in the CLI.

infra/ is absorbed into environments/. Bifrost config is an execution environment concern — it’s the gateway that sandboxes route through.

The litmus test

For every folder: does arpi spawn read or execute files from here at runtime?

Folder	arpi reads at runtime?	Verdict
`cli/`	N/A — it IS the runtime	Domain (it’s the code)
`definitions/`	Yes — spawn reads TOML	Domain
`harnesses/`	Yes — assembly copies hooks/settings/agents	Domain
`registries/`	Yes — assembly picks MCPs and skills	Domain
`environments/`	Yes — sandbox uses images/proxy/bifrost config	Domain
`opensandbox/`	Indirectly — arpi calls its API	Submodule (inside environments/)
`docs/`	No — reference only	Not a domain

What is NOT in arpi/

Thing	Where it lives	Why
EventCatalog	`tools/eventcatalog/`	Internal tool, not platform
Company knowledge	`knowledge/`	arpi serves it, doesn’t own it
Products	`products/`	arpi provisions them, doesn’t own them
Data/analysis	`data/`	Separate concern
Legacy code	`legacy/`	Archive

Current Status

Updated 2026-03-27

The ontology is partially implemented. The following documents what exists versus what the ADR specifies.

Domain	ADR specifies	Current reality
`cli/`	Go CLI source	EXISTS — fully implemented
`definitions/`	TOML spawn specs	EXISTS — contains `copiloto.toml`, `debug-prod.toml`, `internal-tool.toml`
`harnesses/`	Platform-specific agent configs	EXISTS — contains `claude-code/`, `mcp.json`, `daemon/`, `docs/`
`registries/`	Governed catalogs (MCP, skills)	NOT BUILT — absorbed into `harnesses/` per design. `mcp.json` lives in `harnesses/`. Skills submodule deferred to v2.
`environments/`	Execution backends (images, proxy, gateway)	NOT BUILT — execution environment config lives in `infra/`
`opensandbox/`	Git submodule inside environments/	NOT CREATED — OpenSandbox Go SDK not yet available

Deviations from the ADR

infra/ exists as a top-level directory — the ADR says “no top-level infra/”, but Bifrost gateway config and docker-compose currently live here. Will be absorbed into environments/ when that domain is built.
registries/ does not exist — MCP catalog moved to harnesses/mcp.json. Skills registry is v2 work.
harnesses/daemon/ — an experimental PoC for a background daemon. Not described in the ontology. Needs its own ADR if it graduates.
Ungoverned top-level directories — notes/, scripts/, site/ exist at the arpi root. These are not domains and are not described in the ontology. They are workspace support files.

Verification

Every arpi/ subdirectory either contains files read by arpi spawn or is docs/
No top-level iam/ or infra/ directories exist
definitions/ contains TOML files, not harness building blocks
harnesses/ is organized by platform (claude-code/, codex/, cursor/)
registries/ contains mcp.json and the skills submodule
environments/ contains images, proxy, and gateway config
opensandbox/ is a git submodule, not a regular directory