Skip to main content

ADR-0016: Agents as a First-Class Primitive

Status​

Proposed / exploring. Captured during ideation on 2026-07-04. One of the three primitives in the .stet topology (ADR-0015); extends the harness decision (ADR-0004). Revisit for promotion after the core loop (SPEC-0001..0003) is standing.

Context and Problem Statement​

ADR-0004 defined a pluggable harness — the mechanism that runs a coding agent (OpenHands, Crush, Pi). But teams need to define reusable, named agents: a configured actor with a persona, a chosen model, a set of attached skills, and the verbs it responds to. "The harness" is the engine; "an agent" is a car built on it. Agents are one of the three primitives versioned across the .stet topology (ADR-0015).

Sketch​

An Agent is a named, versioned configuration:

  • a harness (ADR-0004) — the mechanism it runs on;
  • a model endpoint (ADR-0004) — bring-your-own, OpenAI-compatible;
  • a persona / system prompt — how it behaves;
  • attached skills (ADR-0012) — resolved across the topology;
  • verbs it handles (ADR-0005) — which markup it responds to;
  • guardrails / limits — sandbox scope, cost ceilings, permissions;
  • enforcement — an optional pin marking this definition non-overridable by lower tiers (ADR-0015), the mechanism by which an org mandates an agent. Pins are set via a reviewed, voted PR to $ORG/.stet, so the mandate is auditable provenance.

Agents are defined at user / org / project tiers (ADR-0015) and resolved most-specific-wins. A dispatch selects an agent; the agent supplies the harness, model, skills, and behavior. Multiple agents can share one harness. Agents are edited, reviewed, voted on, and distilled recursively like any Stet artifact.

Why it fits​

  • Good, because it separates mechanism (harness) from configured actor (agent), which the harness ADR conflated by necessity.
  • Good, because named agents give teams reusable, shareable, versioned reviewers/ workers — e.g. a "docs agent," a "security agent," a "refactor agent."
  • Good, because agent identity is exactly what agentic voting needs for attribution (ADR-0014): a vote comes from an agent, owned by a teammate.

Open questions​

  • Per-verb agent routing. Does a verb name the agent that handles it, or does the agent declare the verbs it serves (or both)?
  • Agent identity & attribution for voting (ADR-0014) and for scoped credentials (ADR-0003) — how an agent maps to a forge identity.
  • Model credentials per agent vs. shared endpoints; secret handling.
  • Default agents shipped out of the box vs. everything user-defined.
  • Diversity for voting — encouraging a panel of agents on different models (ADR-0014) is easier when agents are first-class and explicitly configured.

Consequences (tentative)​

  • Adds an Agent primitive + open schema, resolved via the topology (ADR-0015).
  • Layers on top of the Harness protocol (ADR-0004) rather than replacing it.
  • Provides the identity that ADR-0014 (voting) and ADR-0003 (scoped credentials) need.

More Information​

Extends ADR-0004 (harness). Resolved via ADR-0015 (topology). Consumes ADR-0005 (verbs) and ADR-0012 (skills); provides identity to ADR-0014 (voting).