Artifact

RigSpec

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

A declarative artifact that describes a rig's desired state. Agents are organized into pods with explicit edges, continuity policies, and layered startup.

Full example

# rig.yaml — declarative topology
version: "0.2"
name: adversarial-review
culture_file: culture.md

pods:
  - id: review
    label: Review Pod
    continuity_policy: ha_pair
    members:
      - id: reviewer-1
        agent_ref: local:agents/reviewer
        profile: thorough
        runtime: claude-code
        model: opus
        cwd: .
      - id: reviewer-2
        agent_ref: local:agents/reviewer
        profile: thorough
        runtime: codex
        cwd: .
    edges:
      - kind: collaborates_with
        from: reviewer-1
        to: reviewer-2

  - id: orch
    label: Orchestration
    continuity_policy: ha_pair
    members:
      - id: lead
        agent_ref: local:agents/orchestrator
        profile: default
        runtime: claude-code
        cwd: .
      - id: backup
        agent_ref: local:agents/orchestrator
        profile: default
        runtime: codex
        cwd: .

edges:
  - kind: delegates_to
    from: orch.lead
    to: review.reviewer-1
  - kind: delegates_to
    from: orch.lead
    to: review.reviewer-2

What it contains

pods

Bounded context groups. The unit of shared working context and continuity.

id—Unique identifier within the rig. Used in cross-pod edge references: orch.lead

label—Human-readable name: 'Review Pod', 'Development', 'Orchestration'

continuity_policy—ha_pair (shared memory HA), checkpoint_all (all agents checkpoint), none

members—The agents in this pod. Each references an AgentSpec + profile + runtime.

edges (pod-local)—Relationships within the pod: collaborates_with, can_observe

members

Individual agents within a pod.

agent_ref—Reference to an AgentSpec. local:agents/reviewer, path:../shared/reviewer

profile—Which profile to activate from the AgentSpec: thorough, quick, default

runtime—Which harness runtime: claude-code, codex, terminal

model—Optional model override: opus, sonnet, gpt-5.4

cwd—Working directory for this agent. Can use worktrees for isolation.

edges

Relationships between agents across pods. Qualified references: pod_id.member_id

delegates_to—Orchestrator assigns work to a member. Primary coordination edge.

can_observe—One agent can read another's output. QA observing implementation.

collaborates_with—Bidirectional peer relationship. Two reviewers debating.

escalates_to—Agent raises issues to a higher authority. Worker to orchestrator.

spawned_by—Tracks which agent created which. For subagent lineage.

culture_file

Sets behavioral norms for the entire topology. Delivered to every agent during startup.

Example—culture.md might say: 'Move fast, ship incremental PRs, trust but verify each other's work, always write tests.'

Startup layering

Startup files are delivered in a fixed additive order. Each layer builds on the previous — later layers never replace earlier ones:

1. Agent base startup from AgentSpec
2. Profile startup from selected profile
3. Rig culture file culture.md delivered to every agent
4. Rig-level startup rig-wide overrides
5. Pod-level startup pod-specific context
6. Member-level startup individual agent priming
7. Operator debug append human overrides

Session naming

Sessions are named {pod}-{member}@{rig}. Examples: review-reviewer-1@adversarial-review, orch-lead@adversarial-review. Human-authored, not generated.