Runners (the Registry)

A Runner is the Fleet’s unit of autonomous work: an agent that does one job. The collection of Runner declarations is the Registry, and it lives in this repo as the runners/ artifact type — declarative, PR-reviewed, validator-gated.

This is the “mandatory registry that kills shadow agents.” A Runner declared here is accountable, reviewable, and audited the same way every other catalog artifact is.

Status

The runners/ Registry is live now — declarations validate and surface in the catalog at /runners/. The runtime that executes them (the rba-runner service) is designed but not yet built — see Execution & hosting.

The split: declare here, run elsewhere

This repo declares and governs Runners. A separate service executes them. The declaration is the contract between the two:

• The repo owns the runner.json, its review, and its governance state.
• The runtime reads the Registry, runs the Runner in a Sandbox, and reports back through the Gateway.

That keeps a Runner’s accountability in git while the actual execution lives in a service built for it.

What’s in a runner.json

// runners/<slug>/runner.json
{
  "name": "release-notes-drafter",          // must equal the folder slug
  "description": "...",
  "trigger": "manual | schedule | webhook",  // what kicks it off
  "model": "claude-opus-4-8",
  "skills": ["research", "document-templates"],   // refs to catalog skills
  "allowedTools": ["gateway:jira.read", "gateway:git.read"], // SCOPED Gateway tools
  "sandboxProfile": "qa-no-egress",          // the isolated env it runs in
  "owners": [{ "team": "platform", "github": "rba-platform" }], // REQUIRED
  "maturity": "experimental",                // experimental | stable | deprecated
  "securityReview": { "status": "none" }     // none | requested | passed | failed
}

Field	Purpose
skills	Catalog skills the Runner draws on.
allowedTools	Scoped Gateway tool references (e.g. gateway:jira.read). A Runner reaches internal systems only through the Gateway, never directly.
trigger	manual, schedule, or webhook.
model	The Claude model the Runner runs on.
sandboxProfile	The isolated environment it executes in — non-optional. No production credentials, no network egress except through the Gateway.
owners, maturity, securityReview	The same governance spine as every other catalog artifact.

Why Runners are governed harder

An autonomous Runner with tools is a higher risk class than a static skill. The validator (scripts/validate-bundles.mjs) holds Runners to a stricter bar than the catalog default:

• owners is required — an error, not just a warning. An autonomous, tooled agent must route to an accountable team.
• sandboxProfile is required — the Sandbox is non-optional.
• The stable promotion gate — maturity: stable requires securityReview.status: "passed", same as the rest of the catalog.
• Write-scoped Runners are flagged — any Runner whose allowedTools include a tool that isn’t clearly read-only (*.read, *.list, *.get, …) is warned until it has a passed security review. A write-scoped Runner cannot reach stable without one.

The Sandbox plus the Gateway’s scoped, short-lived tokens are what let a Runner run without per-action permission prompts — the isolation is what makes autonomy safe.

Declaring a Runner

1. Create runners/<slug>/runner.json with the fields above (name must equal <slug>, kebab-case).
2. Keep allowedTools read-only and scoped where you can; if the Runner needs to write, plan for a security review before promoting it past experimental.
3. Run npm run validate — the validator enforces the rules above and maps any failure to the exact fix.
4. The Runner appears at /runners/<slug>/ and in unified search.

When to declare a Runner vs. a skill/agent/command

Reach for a Runner when a repeatable job should run autonomously — on a schedule, off a webhook, or on demand — interleaving Claude with deterministic steps (git, lint, test, API calls through the Gateway). For an interactive, human-in-the-loop workflow, a skill, command, or agent is the better fit. Runners are not reused from the existing agents/ artifact: Claude Code subagent definitions and autonomous Runners are semantically different.