Reference

RigSpec

Published April 2026

File: rig.yaml · Version: "0.2" (pod-aware)

The canonical OpenRig reference for a multi-agent topology. A RigSpec defines pods, members, startup layering, cross-pod relationships, and optional managed services.

This page reflects the shipped pod-aware schema and validator behavior from the new `docs/reference/rig-spec.md` source of truth.

Minimal valid example

version: "0.2"
name: my-rig

pods:
  - id: dev
    label: Development
    members:
      - id: impl
        agent_ref: "local:agents/impl"
        profile: default
        runtime: claude-code
        cwd: "."
    edges: []

edges: []

A valid RigSpec needs a pod-aware topology, not just a flat list of agents.

What a RigSpec controls

version

Required. Must be `"0.2"` for the pod-aware RigSpec shape.

name

Required rig name used in session naming, snapshots, and spec-library lookup.

summary

Optional human-readable description shown in review and library surfaces.

culture_file

Optional safe relative path to a rig-wide culture or constitution file.

docs

Optional supporting docs that travel with the rig and bundle.

startup

Rig-level startup files and actions applied to every member through the layering model.

services

Optional managed services block for service-backed rigs and managed apps.

pods

Required non-empty pod array. Pods are the bounded context units.

edges

Optional cross-pod edges using fully-qualified `pod.member` IDs.

Pods and members

Pod

A pod is a bounded context group. It carries member definitions, pod-local edges, optional startup overlays, and an optional structured `continuity_policy`.

pods:
  - id: dev
    label: Development
    summary: Implementation and QA pair
    continuity_policy:
      enabled: true
      sync_triggers: [pre_compaction, pre_shutdown]
      artifacts:
        session_log: true
        restore_brief: true
      restore_protocol:
        peer_driven: true
        verify_via_quiz: false

Member

A member binds an AgentSpec + profile to a runtime and working directory within the pod.

members:
  - id: impl
    agent_ref: "local:agents/impl"
    profile: default
    runtime: claude-code
    cwd: "."
    label: "Implementation Lead"
    model: claude-opus-4-6
    restore_policy: resume_if_possible

Terminal nodes are an exact special case

Infrastructure processes are represented as terminal nodes. The validator requires the exact triple below; any partial combination is rejected.

runtime: terminal
agent_ref: "builtin:terminal"
profile: none

Edges

Pod-local edges

Inside a pod, use unqualified member IDs.

pods:
  - id: dev
    members:
      - id: impl
      - id: qa
    edges:
      - kind: delegates_to
        from: impl
        to: qa

Cross-pod edges

Across pods, use fully-qualified `pod.member` IDs.

edges:
  - kind: delegates_to
    from: orch.lead
    to: dev.impl
  - kind: can_observe
    from: rev.r1
    to: dev.impl

For the meaning and current runtime behavior of each edge kind, see Edge Types.

Startup, services, and continuity

startup

Startup blocks can appear at rig, pod, and member level. Files and actions merge additively through the startup layering model.

services

The services block is how a rig becomes service-backed. In the current implementation, `kind: compose` is the supported path.

continuity_policy

Continuity is now a structured object with triggers, artifacts, and restore protocol, not the older scalar `ha_pair` / `checkpoint_all` shape.

For authoring guidance on what should actually go into startup files, see Agent Startup Guide.

Validation highlights

Pod IDs and member IDs must not contain dots.

Terminal nodes require the exact triple: `runtime: terminal`, `agent_ref: builtin:terminal`, `profile: none`.

`agent_ref` must use `local:` or `path:` unless it is the `builtin:terminal` exception.

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

Pod-local edges use unqualified member IDs; cross-pod edges use `pod.member` IDs.

`services.kind` must be `compose` in the current implementation.

Startup actions require `idempotent`, and non-idempotent actions cannot apply on `restore`.

Session naming

The canonical session name is {podId}-{memberId}@{rigName}. Example: pod dev, member impl, rig my-team becomes dev-impl@my-team.