Reference

AgentSpec

Published April 2026

File: agent.yaml · Version: 1.0

The canonical OpenRig reference for a single-agent blueprint. An AgentSpec declares the available resource pool, named profiles that select from that pool, startup content, and lifecycle defaults that travel with the agent type.

This page is aligned to the shipped reference docs and code-traced parser behavior in the `openrig` repo, not the older pre-pod prototype format.

Minimal valid example

name: my-agent
version: "1.0"

profiles:
  default:
    uses:
      skills: []
      guidance: []
      subagents: []
      hooks: []
      runtime_resources: []

resources: {}

startup:
  files: []
  actions: []

This is the smallest shape the validator accepts: an identity, a profile map, a resource pool, and a startup block.

What an AgentSpec controls

name

Required agent name. Used in spec library surfaces and validation output.

version

Required spec version string. Informational, not used as a compatibility gate.

defaults

Default runtime, model, and lifecycle behavior when the rig member does not override them.

imports

Other AgentSpecs to import. Imported resources become available to profile `uses` references.

profiles

Named profile map. Profiles select which declared resources are active and may override startup/lifecycle.

resources

The available pool: skills, guidance, subagents, hooks, and runtime resources.

startup

Agent-level startup files and actions. Merged with profile startup through the layering model.

Profiles select from a declared resource pool

`resources` declares what exists. A profile's `uses` block selects which of those resources are active for a particular role. Profiles do not inject new resources; they filter and compose what the spec already declared or imported.

`uses` references may be unqualified (`vault-user`) or qualified (`shared:openrig-user`) when they come from imported specs.

profiles:
  default:
    summary: Standard operations profile
    preferences:
      runtime: claude-code
      model: claude-opus-4-6
    uses:
      skills: [openrig-user, mental-model-ha, vault-user]
      guidance: [role]
      subagents: []
      hooks: [pre-commit]
      runtime_resources: [claude-settings]
    startup:
      files: []
      actions: []
    lifecycle:
      restore_policy: resume_if_possible

Resource categories

skills

Skill directories containing `SKILL.md`. Delivered via `skill_install` and then explicitly loaded by startup guidance.

guidance

Markdown guidance files merged into `CLAUDE.md` / `AGENTS.md` as managed content.

subagents

Subagent definitions available to the active profile.

hooks

Hook scripts with optional runtime restrictions.

runtime_resources

Runtime-specific files such as Claude settings or other harness-specific config artifacts.

Lifecycle defaults

execution_mode

The current implementation accepts `interactive_resident`. Older values like `autonomous` are not canonical in the shipped schema.

compaction_strategy

Valid values are `harness_native` and `pod_continuity`. This is where an agent opts into pod-level continuity behavior.

restore_policy

Choose among `resume_if_possible`, `relaunch_fresh`, and `checkpoint_only`.

Startup model

Agent-level startup applies to every profile. Profile-level startup is layered on top of it. The file/action format is the same one used in RigSpec startup blocks: `files` with `delivery_hint`, `required`, and `applies_on`, plus `actions` with `type`, `phase`, `idempotent`, and `applies_on`.

For authoring guidance rather than raw field reference, see the Agent Startup Guide.

Validation highlights

`imports` entries must use `ref`, not the older `source` shape.

`profiles` is a map of named profiles, not an array.

`uses` references must resolve to declared resources, locally or through imports.

All resource paths must be safe relative paths.

`execution_mode` must be `interactive_resident` in the current implementation.

`compaction_strategy` accepts `harness_native` or `pod_continuity`.

`restore_policy` accepts `resume_if_possible`, `relaunch_fresh`, or `checkpoint_only`.

Startup file and action validation follows the same rules as RigSpec startup blocks.

What an AgentSpec does not contain

It does not define multi-agent topology. That belongs in RigSpec.

It does not carry live session IDs, pane refs, or other ephemeral runtime state.

It does not hardcode secrets or API keys.

It does not make the final topology binding choices for `cwd`, peer edges, or pod placement.