Definition-driven spawn model

Status: Superseded

Superseded by template-schema.md. Templates replace definitions. [harness] becomes [worker]. [shared] and [platform.*] become [workstation]. [env] is replaced by [compute]. Credentials are inferred from capabilities, not declared.

Definition-driven spawn model

Decision

arpi spawn <definition> is THE command for provisioning agent workstations. A TOML definition declares everything — no flags needed for normal use. Flags are overrides with warnings.

Definition format

[harness]
name = "debug-prod"
description = "Debugging production issues"
instructions = "debug-prod.agents.md"
model = "opus"

[shared]                                        # cross-platform (Claude, Codex, Cursor)
skills = ["sentry-workflow", "sentry-cli"]
mcps = ["sentry", "braintrust"]

[claude-code]                                   # platform-specific
settings = ["base", "backend-go"]
hooks = ["block-main-edits", "nuke-guard"]
agents = ["researchers/codebase-analyzer"]

[env]
workspace = "bare"                              # bare | worktree | sandbox
runtimes = { go = "1.22", node = "22" }
tools = ["aws-cli@2", "temporal-cli"]
required_vars = ["SENTRY_DSN", "BRAINTRUST_API_KEY"]

For sandbox definitions:

[env]
workspace = "sandbox"
image = "arpi/agent-base:latest"
host = "eks-prod"
egress = ["bifrost.internal:443"]
timeout = "4h"

[env.secrets]
keys = ["SENTRY_DSN", "PD_ROUTING_KEY"]

Design rules

• No [iam] section. IAM is runtime state (from arpi login token), not a definition property.
• required_vars for bare/worktree. arpi checks they exist in the shell and warns if missing. No fetching.
• [env.secrets] only for sandbox. arpi fetches from IAM provider and injects via credential proxy.
• workspace in the definition, not a flag. The definition knows whether it needs isolation.
• Flags are overrides with warnings. --bare on a sandbox definition warns and prompts for confirmation.
• AGENTS.md is the instruction standard. The instructions field points to an AGENTS.md-style markdown file paired with the definition.
• .agents/ for cross-platform config. Platform-agnostic agent configuration alongside .claude/.

Spawn flow

Bare:

1. Load definition. 2. Assemble .claude/ (settings, hooks, agents, skills, MCPs). 3. Check required_vars in shell. 4. Check tools exist. 5. Track in arpi status.

Worktree:

1. Load definition. 2. git worktree add .arpi-worktrees/<branch>. 3. Assemble .claude/ in worktree. 4. Check required_vars, tools.

Sandbox (local):

1. Load definition. 2. Verify arpi login token. 3. Create sandbox via OpenSandbox API. 4. Mount project directory. 5. Inject secrets via credential proxy. 6. Assemble .claude/ inside sandbox. 7. Configure egress filtering (gateway only). 8. Launch agent. 9. Track in arpi status.

Sandbox (remote): Same as local sandbox but container runs on remote host (--host). arpi logs streams output.

CLI commands

arpi spawn <definition>             # do what the definition says
arpi spawn <definition> --dry       # show what would happen
arpi spawn <def> --bare             # override workspace (warns)
arpi spawn <def> --worktree         # override to worktree
arpi spawn <def> --sandbox          # override to sandbox
arpi spawn <def> --host <name>      # run sandbox on remote host
arpi spawn <def> --as <role>        # escalate IAM role
arpi spawn <def> --platform <name>  # override agent platform (default: claude-code)

arpi list                           # available definitions
arpi show <def>                     # inspect a definition
arpi status                         # running agents (local + remote)
arpi stop <id>                      # stop a running agent
arpi logs <id>                      # stream logs

arpi login                          # authenticate to IAM provider
arpi whoami                         # show identity + role

arpi new <template> <name>          # scaffold a new project (separate concern)
arpi doctor                         # health check

What was removed

Removed	Replaced by
arpi use	arpi spawn
arpi create	arpi new (scaffolding is a separate concern)
arpi current	arpi status
--env flag	Definition declares needs. Bare = check vars. Sandbox = inject.
YAML context format	TOML definitions
profiles.yaml	IAM provider roles

Verification

• arpi spawn debug-prod loads TOML and assembles .claude/ in cwd
• arpi spawn debug-prod --dry shows what would be assembled
• arpi spawn debug-prod --worktree creates git worktree and assembles there
• arpi list shows all definitions with descriptions
• arpi show debug-prod displays definition contents
• Overriding workspace mode shows warning and prompts
• required_vars check warns on missing without failing