Domain

Domain Skill — Ubiquitous Language for Human-AI Software Building

This is a library skill. It doesn't run standalone — it holds the shared vocabulary that you, the agent, and other skills cite when describing work.

Why this exists

AgentOps's existing skills (research, plan, crank, validate, ...) are verbs. This skill holds the nouns and the discipline they operate on. When a session talks about "this is a tracer bullet" or "we need a vertical slice through the eval surface," the meaning is fixed here, not improvised.

Status

Tracer bullet shape with one canonical operating concept. This skill currently holds:

• 6 structural primitives (Entry, Index, Citation, Primitive, Slice, Anti-Pattern)
• 1 test entry (Tracer Bullet) written using only citations to the 6 primitives
• 1 canonical operating concept (Context Density Rule)

If the test entry can describe its own concept using only the primitives, the shape works and we grow the corpus by adding more entries — never new structural primitives without operator consent.

How to use this skill

1. Read references/INDEX.md first — it lists every entry by kind and status. 2. Load only the entries relevant to the current work. Do not preload the whole corpus — that defeats the JIT purpose. 3. When applying an entry, cite it: include the entry slug in your output, plan, commit message, or bd issue body so future sessions can trace the reasoning. 4. When you find a concept missing or misnamed, add a draft entry under references/ and update INDEX.md. Promotion from draft to canonical requires operator approval.

Entries (tracer-bullet set)

Structural primitives (the architecture):

• references/domain.feature — Executable spec: load-on-demand corpus, draft→canonical ratchet, vocabulary root (soc-qk4b)
• `references/entry.md` — Entry: the atomic concept doc
• `references/index-primitive.md` — Index: the discovery surface (concept)
• `references/citation.md` — Citation: how Entries reference each other and how agents claim use

Vocabulary nouns (the working units):

• `references/primitive.md` — Primitive: atomic capability (skill, hook, CLI command, eval suite)
• `references/slice.md` — Slice: vertical work unit cutting through multiple Primitives
• `references/anti-pattern.md` — Anti-Pattern: documented mistake with cost when ignored

Test entry:

• `references/tracer-bullet.md` — Tracer Bullet: described using only citations to the six primitives above

Operating discipline:

• `references/context-density-rule.md` — Context Density Rule: every context token carries intent, boundary, evidence, decision, constraint, or next action
• `references/behavior-shaping.md` — Behavior Shaping: the ABC register (antecedent/behavior/consequence/reinforcement/extinction/shaping); building agent capability is operant conditioning, not specification
• `references/primitive-selection.md` — Primitive Selection: when to use a Skill vs CLI subcommand vs runtime hook vs local cockpit gate vs CI backstop (CLI is the deterministic core; gates are trigger surfaces that call it)
• `references/reach.md` — Reach: the blast-radius tier of a knowledge entry (bead/pull/always), orthogonal to maturity; always is computed from verification-earned canon, never authored

Loop family (the operating loop — "one loop body, two drivers, one inner tick, one config"; doctrine in docs/architecture/canonical-loop-model.md):

• `references/loop.md` — Loop: the umbrella; the same five-beat tick at every scale
• `references/evolve.md` — Evolve: the in-session driver (AgentOps-shipped, zero-dependency)
• `references/factory.md` — Factory: the out-of-session driver (substrate-owned; AgentOps deleted its daemon)
• `references/rpi.md` — RPI: the inner tick, one research-plan-implement-validate cycle over one bead
• `references/autodev.md` — Autodev: the config/intent layer the loop reads each tick (NOT a loop)
• `references/context-compiler.md` — Context-Compiler: turns the corpus into the working set and absorbs the tick's exhaust

Verification membrane:

• `references/silent-contract-violation.md` — Silent Contract Violation: tool-use code that runs clean, raises no exception, and is still wrong (wrong routing / output shape / argument provenance); the four contract-check categories that name where it lands (RubricRefine)

Catalog:

• `references/INDEX.md` — full corpus index

Domain as a scoped operating-loop contract

The Slice primitive above has a runtime counterpart: a domain slice can scope an operating-loop run. A domain is a named vertical slice with an explicit boundary contract — a manifest at docs/domains/<name>/manifest.yaml listing the Primitives the slice may touch, its goal, and its decision gate.

Use /scaffold domain <name> to write the manifest template, then fill in the boundary before running the operating loop with that manifest as explicit scope. For out-of-session execution, dispatch the scoped loop through NTM plus Agent Mail reservations so write ownership and the slice boundary are visible. The manifest schema and resolution rules are in docs/adr/ADR-0004; the /scaffold skill documents the bootstrap step.

What's NOT here

• Procedural how-tos (those live in other skills)
• Repo conventions (those live in skills/standards/)
• Findings, learnings, patterns (those live in .agents/)
• Product framing (lives in PRODUCT.md)

See also

• skills/standards/SKILL.md — repo coding standards (sibling library skill)
• docs/architecture/primitive-chains.md — concrete AgentOps primitive layers

(Mission/Discovery/Risk/Execution/Validation/Learning/Ratchet/Continuity) that compose the domain into chains

Anti-Pattern

An Entry whose subject is a specific failure mode of agent-assisted work, named so that future sessions can recognize and refuse it.

Definition

An Anti-Pattern is an Entry with kind: anti-pattern whose body contains:

• a Signature — the surface symptom an agent or operator would see
• a Cost — what gets lost or broken when the pattern is allowed to run
• a Cause — the upstream confusion or missing primitive that produces it
• a Refusal — the concrete sentence or action an agent should take when

it detects the signature

• at least one incident citation anchored in this repo's history

(commit SHA, bd issue, learning under .agents/learnings/)

Anti-Patterns are first-class citizens in the corpus, not afterthought warnings. The lesson belongs in the vocabulary, not in scattered comments.

When to use

• When a failure mode has been observed twice or more and the next session

is at risk of repeating it.

• When a Slice has been corrupted by a recurring discipline gap and the

cheapest fix is to name the pattern so future Slices can cite the refusal.

Anti-pattern (yes, recursive)

• The unnamed Anti-Pattern. A failure described in chat or in a commit

message but never written down as an Entry. Future sessions will repeat it because the lesson lives in a non-indexed surface.

• The Anti-Pattern without an incident citation. "Don't do X" with no

link to a specific cost paid. Without evidence it gets tuned out as generic advice.

• **The Anti-Pattern that overlaps a Primitive Entry without distinguishing

itself.** Anti-Patterns describe how primitives go wrong; they should not redefine the primitives themselves.

Example in this codebase

• .agents/learnings/2026-04-19-orchestrator-compression-anti-pattern.md

names the orchestrator-compression failure with signature, cost, and refusal. It is referenced by skills/discovery/SKILL.md directly. This is the shape Anti-Pattern Entries should match (current .agents/ learnings are operator-local — the corpus equivalent here is the in-repo shipping copy).

See also

• entry.md — the shape an Anti-Pattern Entry follows
• slice.md — what an Anti-Pattern damages when triggered
• citation.md — how Anti-Patterns get applied during Slices

Autodev

The config/intent layer the Loop reads every tick, NOT a loop. Autodev is the durable intent crafted into context: PROGRAM.md / AUTODEV.md plus GOALS.md plus ADRs. The loop consumes it; it does not run it.

When to use

• Use Autodev for the config that drives the loop. Lead with "the PROGRAM.md / AUTODEV.md contract that drives the loop", never with "bounded autonomous dev loops" (that phrasing implies a loop and is the source of the original sprawl).
• Autodev is consumed by both drivers (Evolve and Factory) every tick. It is the highest-leverage antecedent: arrange it well and the loop's behavior follows.

Anti-pattern

• Treating Autodev as a fourth loop. It is config, alongside GOALS and ADRs. Calling it a loop re-creates the confusion the canonical model resolves. See Anti-Pattern.

Bounded context

BC1 Corpus / intent. Autodev is one of the durable intent sources the loop reads; it sits with GOALS.md and ADRs as the antecedent layer, not in BC3 Loop.

See also

• loop.md — Autodev is the config of the one loop
• evolve.md, factory.md — the drivers that read Autodev each tick
• rpi.md — each tick reads Autodev as part of its Research beat
• anti-pattern.md — what treating config as a loop costs

Behavior Shaping

Building agent capability is operant conditioning, not specification. You cannot compile a behavior into a non-deterministic model; you can only shape it through observable examples and reinforcement. This is the ubiquitous-language register for that frame — the fourth domain axis alongside DDD (vocabulary), Hexagonal (structure), and Gherkin (acceptance).

Doctrine: `docs/architecture/behavior-shaping-environment.md`.

The ABC register

Operant conditioning runs on Antecedent → Behavior → Consequence. Every working term maps to one of the three:

When to use

• When extending a Primitive, name the behavior (a scenario), its antecedent (what context makes it likely), and its reinforcer (which gate proves it). A behavior with no consequence drifts.
• Prefer add-and-shape over big top-down design: add a scenario and reinforce it to green, rather than rewriting prose. Behaviors compose; designs collide.
• To remove a behavior, use extinction (delete its cue and reward), not a comment that says "don't."

Relationship to other entries

• A Slice demonstrates exactly one Behavior cutting vertically through Primitives.
• A Primitive is reinforced into reliability through gates (its consequences).
• An Anti-Pattern is a behavior to keep extinguished — documented with the cost of letting it recur.
• The Context Density Rule governs what crosses a phase boundary: the antecedent for the next behavior.

Citation

The mechanism by which one Entry references another, and by which an agent records "I applied this Entry to this work."

Definition

A Citation is an explicit, traceable mention of an Entry slug from one of:

• another Entry's see-also frontmatter or body
• a skill SKILL.md, hook script, or CLI doc
• a commit message, PR description, or bd issue body
• an .agents/ artifact (plan, findings, post-mortem)
• the output an agent emits during a session

Shape

Two forms:

1. Entry-to-Entry — in see-also frontmatter (a slug list) or inline as ` entry-slug.md in prose. Always slug, never concept name in prose citations. 2. **Application** — a session/agent claims it used an Entry by writing "applied: entry-slug" (or equivalent) somewhere durable (commit body, bd notes, .agents/learnings/<date>-<topic>.md`). This is the only way the corpus compounds value over time.

When to use

• Always cite when you apply a corpus Entry to a decision. Without Citations,

the corpus accumulates entries but generates no evidence of utility.

• Cite from one Entry to another via see-also when concepts are

conjoined-meaning (e.g. an Entry on a tracer bullet must cite the Entry on vertical slice).

Anti-pattern

• Loading without citing. An agent that reads an Entry but does not record

the application makes the corpus look unused and starves the maturity- weighting signal that future retrieval depends on.

• Citing by concept name in prose, not by slug. "We followed the Tracer

Bullet principle" is unverifiable; ` tracer-bullet.md ` is.

• Citing deprecated Entries without a forward pointer to the canonical

replacement.

Example in this codebase

Every see-also: line in this corpus's frontmatter is a Citation. The deprecated ao inject command (cli/cmd/ao/inject.go:153) records citation events to .agents/ao/citations.jsonl — the same idea applied to the existing learnings/patterns corpus.

See also

• entry.md — what gets cited
• index-primitive.md — how Citations resolve to actual files

Context-Compiler

The capability that turns the .agents/ corpus into the working set a Loop tick needs, and absorbs the tick's exhaust back into the corpus. "AgentOps is the in-session agent operating loop and the context compiler that feeds it" is the product thesis; this entry names the noun.

What it does at each loop edge

Context is the artifact, not a byproduct

Context is the engineering artifact handed off at every loop edge, and it compounds at every level. The corpus is the moat: the thing that grows and the thing worth protecting. The Context Density Rule governs what is allowed to cross an edge: every high-value token carries intent, a boundary, evidence, a decision, a constraint, or a next action, and nothing else.

When to use

• Use Context-Compiler when describing how context flows through the loop. Context flows through the corpus and the bead, never through loop plumbing return values.
• The ratchet rules keep compilation honest: a learning is durable only when it compiles into a gate, a test, or a rule (knowledge becomes constraints).

Bounded context

BC1 Corpus. ao inject / ao compile / ao maturity are its CLI surface; the loop (BC3) consumes them.

See also

• loop.md — the loop the compiler feeds and absorbs from
• rpi.md — the tick whose Research and Ratchet beats call the compiler
• context-density-rule.md — what is allowed to cross a loop edge
• citation.md — how corpus entries reference each other and how agents claim use

Context Density Rule

Every context token should carry one of six payloads: intent, boundary, evidence, decision, constraint, or next action.

Definition

The Context Density Rule is the CDLC compression rule for agent work. A prompt, packet, handoff, plan, verdict, or skill section earns its place in the context window only when it changes what the agent can safely do next.

This is a rule for context units, not tokenizer math. One paragraph, table row, or bullet can be dense when it carries a payload; a long explanation is sparse when it only restates background.

When to use

• Before adding prose to a prompt, packet, handoff, plan, or skill.
• When trimming context for a phase-specific agent window.
• When deciding whether a learning should promote into a skill, template, gate,

or doctrine doc.

• When reviewing an orchestrator skill such as rpi, discovery, plan,

crank, or validation.

Payloads

Anti-pattern

• Context filler. Prose that sounds useful but does not change intent,

boundaries, evidence, decisions, constraints, or next actions.

• Packet stuffing. Adding every adjacent fact because it might help,

instead of linking to a discovery surface and loading it only if needed.

• Evidence-free doctrine. Promoting a slogan into a skill or gate without a

citation, test, incident, or operator decision behind it.

Example in this codebase

docs/cdlc.md states the rule at the product-doctrine level. /rpi applies it at the orchestration boundary: phase handoffs should preserve the objective spine, bounded context, validation evidence, decisions, constraints, and next action without carrying phase-local chat history forward.

See also

• citation.md - how applied entries leave evidence
• slice.md - how dense context becomes a vertical work unit
• tracer-bullet.md - the thinnest proof-bearing slice

Entry

The atomic unit of the domain corpus. Every concept, vocabulary noun, and anti-pattern in this corpus is expressed as exactly one Entry.

Definition

An Entry is a single markdown file under skills/domain/references/ with:

• Frontmatter declaring name, kind, status, and see-also
• A one-line H1 matching name
• A Definition section (≤3 sentences)
• A When to use or equivalent applied section
• An Anti-pattern or What it is not section
• Optionally an Example anchored in this codebase by file:line
• A See also section listing related Entry slugs

Shape (frontmatter contract)

name: <PascalCase concept name>
kind: primitive | concept | anti-pattern
status: tracer | draft | canonical | deprecated
see-also: [<slug>, <slug>, ...]

When to use

• Adding a vocabulary term that other Entries, skills, or agents will cite.
• Documenting a discipline (do-this) or anti-discipline (do-not-this) for

agent-assisted work.

Anti-pattern

• Multi-concept Entries. One Entry per concept; if two need to be referenced

together, link via see-also, do not merge them.

• Long-form Entries (>1 page). If the concept needs more than one page, it is

probably two concepts or it belongs in docs/ as a narrative, not in the corpus as a definition.

Example in this codebase

This file (skills/domain/references/entry.md) is itself an Entry. It uses the frontmatter shape above and stays under one page.

See also

• index-primitive.md — how Entries are discovered
• citation.md — how Entries reference each other

Evolve

The in-session driver of the Loop: an interactive agent running the loop self-paced, allowed to end with the session. Evolve runs N RPI ticks toward a goal: select the next-best work, run a tick, run a post-mortem, repeat. It is the outer loop relative to rpi, and the same loop body as Factory under a different driver.

When to use

• Use Evolve for the in-session, self-paced driver. It is the AgentOps product and zero-dependency: it runs in a plain session with no daemon and no substrate.
• Evolve's logic (which bead next, N cycles toward a goal, when to post-mortem) stays in AgentOps. Evolve's cadence, when run unattended, becomes a substrate cron Order; that cadence is orchestration, not loop logic.

Stop policy

A session may end with its budget (the session-scope discipline: 2-4 PRs per session, post-mortem at the threshold). This is the one place the loop's stop policy differs from Factory, which stops only on an operator marker.

Bounded context

BC3 Loop. The work-selection ladder and the N-cycle accounting are AgentOps domain logic.

See also

• loop.md — the umbrella; Evolve is one of its two drivers
• factory.md — the same loop body, driven by a substrate instead of a session
• rpi.md — the tick Evolve repeats
• autodev.md — the config Evolve reads each cycle

Factory

The out-of-session driver of the Loop: the loop run unattended over a bead queue, with operator-only stop. Factory is one of the two drivers of the same loop body; it runs the identical RPI tick that an in-session Evolve run does. The difference is the driver (a substrate, not a person) and the stop policy (only an operator marker halts it).

The substrate owns it, not AgentOps

AgentOps 3.0 ships no always-on daemon, scheduler, or overnight runner — those surfaces were deleted in the 3.0 rearchitecture (see `docs/adr/ADR-0009-daemon-deletion-in-session-only.md`). The Factory driver is the orchestration substrate's job. The reference substrate is the trio AgentOps actually runs on — NTM (a tmux agent swarm), MCP (ao mcp serve), and managed-agents (ao agent) — none of it AgentOps-owned: it holds the queue, supervises the agents, and they inherit the AgentOps skills via overlay. AgentOps stays zero-dependency in a plain session through the Evolve driver.

Swarm-driven dispatch (honest current state)

On the reference substrate, dispatch is swarm-driven: an NTM tmux swarm (or a lead agent) runs bd ready, then dispatches the next bead to a worker agent that runs the /rpi skill; a managed-agent driver (ao agent) or cron handles scheduled maintenance, and ao mcp serve exposes the ao tool surface across the seam. The substrate dispatches a whole loop as one unit (an agent running the skill) — it never re-expresses the rpi tick as substrate-side steps.

When to use

• Use Factory for the unattended, queue-driven driver. Do not use it for an AgentOps-shipped daemon; that surface was deleted when out-of-session orchestration moved to the substrate.
• The substrate dispatches a whole loop as one invocable unit. The Factory driver never drives the loop's insides; rpi is never re-expressed as substrate workflow steps.

Bounded context

The Factory driver is substrate-owned (orchestration). The loop it runs is BC3 Loop (AgentOps). The seam between them is the load-bearing DDD boundary: orchestration (when/where/who-supervises) versus the loop and its context (what the agent does, how context compounds).

See also

• loop.md — the umbrella; Factory is one of its two drivers
• evolve.md — the in-session driver running the same tick
• rpi.md — the tick the Factory driver runs unattended

Index

The discovery surface for the corpus. The catalog an agent reads first to find the right Entry to load.

Definition

An Index is a markdown file at a known location that lists every Entry under its root by slug, concept name, status, and kind. Agents are expected to load the Index before loading any individual Entry, and to use it as the only authoritative listing.

Shape

• Lives at <corpus-root>/INDEX.md
• Groups Entries by structural role (primitives, vocabulary, test, ...)
• Each row: slug | concept | status | kind
• Includes a status legend and growth rules

When to use

• An agent landing in this repo for the first time should load the corpus

Index before answering any question that touches vocabulary.

• Skills, hooks, and CLI commands citing a corpus Entry should resolve the

citation through the Index, not by guessing the file path.

Anti-pattern

• A second discovery surface that duplicates Index rows (e.g., a sidebar in

a doc, a hard-coded list in a skill). The Index is the sole source of truth; anything else is a stale fork waiting to drift.

• Implicit indexing (scanning the directory). If the file is not in the Index,

it does not exist for citation purposes.

Example in this codebase

skills/domain/references/INDEX.md is the corpus Index. The file you are reading right now (index-primitive.md) is an Entry about the Index concept — distinct file, distinct slug, deliberately separated to survive case-insensitive filesystems.

See also

• entry.md — what gets listed in an Index
• citation.md — how an Index resolves citations

Domain Corpus — Index

The canonical vocabulary for building software with AI agents in this repo. Load entries on demand; do not preload the whole corpus.

Reading order for new agents

1. entry.md — what every corpus entry looks like 2. index-primitive.md — what an Index is as a concept (this file IS one) 3. citation.md — how entries reference each other and how agents claim use 4. primitive.md — atomic capabilities (skills, hooks, CLI commands) 5. slice.md — vertical work units that cut through multiple primitives 6. anti-pattern.md — documented mistakes with the cost when ignored 7. tracer-bullet.md — test entry; uses only citations to entries 1-6 8. context-density-rule.md — CDLC compression rule for agent context 9. behavior-shaping.md — the ABC register: building agent capability is operant conditioning, not specification

Naming note

INDEX.md is the catalog file (this file). The vocabulary entry describing the Index concept lives at index-primitive.md — separate slug so that case-insensitive filesystems (macOS APFS default) do not collapse the two.

Entries

Structural primitives (the architecture)

Vocabulary nouns (the working units)

Test / proof entries

Verification membrane concepts

Operating discipline concepts

Loop family (the operating loop)

"One loop body, two drivers, one inner tick, one config." Doctrine: docs/architecture/canonical-loop-model.md.

Status legend

• tracer — part of the initial tracer-bullet shape, not yet canonical
• draft — proposed but unreviewed
• canonical — operator-approved; safe to cite without caveat
• deprecated — kept for traceability; do not cite for new work

Growth rules

• Adding a new entry: write the file, add a row above, mark status draft
• Promoting draft → canonical: requires operator approval
• Adding a new structural primitive (a 7th brick): requires operator

approval AND a written rationale for why the existing 6 cannot express the new concept

• Renaming an entry: leave a deprecated stub at the old slug citing the new one

Loop

The umbrella for the AgentOps operating loop. One loop body, two drivers, one inner tick, one config. The same five-beat shape (research, plan, implement, validate, ratchet) runs at every scale; the only things that change across scales are the driver and the stop policy.

Doctrine: `docs/architecture/canonical-loop-model.md`.

The shape

Fractal

The loop is fractal: the same shape at every layer, run by a human or a stand-in agent. rpi is one tick; evolve is N ticks toward a goal; a factory is the same loop run unattended over a queue by an out-of-session substrate. Because the shape repeats, the ratchet rules (no self-grade, fresh agent on failure, knowledge becomes constraints) apply identically at every layer. That is what makes the loop compound up the layers instead of repeating flat.

When to use

• Use Loop as the umbrella noun. Do not call evolve, rpi, autodev, or factory "the loop" as bare synonyms; name the specific driver, tick, or config.
• When an agent asks "which loop do I run?", the answer is driver + tick: run the rpi tick, driven by your session (Evolve) or by a substrate (Factory).
• The in-session loop is the AgentOps product and runs zero-dependency; the Factory driver opts into an orchestration substrate.

Bounded context

Spans BC3 Loop (the loop body, drivers, and tick) and reads from BC1 Corpus (context in/out). Orchestration of the Factory driver belongs to the substrate, outside AgentOps' bounded contexts.

See also

• factory.md, evolve.md — the two drivers
• rpi.md — the inner tick
• autodev.md — the config that drives the loop
• context-compiler.md — what handles context at each loop edge

Primitive Selection

Which behavior/enforcement Primitive to reach for. primitive.md enumerates the nouns; this entry is the decision rule for when to use which. Each primitive owns one axis.

Definition

The core relationship

*The CLI subcommand is the reusable deterministic core. Runtime hooks, the local cockpit gate, and CI backstops are trigger surfaces that call it:*

ao <cmd>   ── the deterministic logic (written ONCE)
  ├── a RUNTIME HOOK calls it  → local, instant, advisory, bypassable
  ├── the COCKPIT GATE calls it → routine AgentOps release authority
  └── a CI BACKSTOP calls it   → remote PR/tag/manual telemetry

You rarely choose "hook or CLI." You write the CLI, then choose where it fires: the cockpit gate for routine enforcement, CI for remote backstop telemetry, or a runtime hook only for instant local feedback.

When to use

1. Needs judgment / reasoning / orchestration? → Skill. 2. Deterministic + repeatable + codeable? → CLI subcommand (the default; the core). 3. Must be enforced for routine AgentOps landing? → run that CLI through the local cockpit gate / installed Git pre-push proof path. 4. Need remote PR/tag/manual evidence? → also wire a CI backstop that calls the same CLI. 5. Want instant feedback inside one runtime? → optionally wire a runtime hook that calls the same CLI — never rely on it for release authority.

AgentOps 3.0 is runtime-hookless and local-gate authoritative: routine landing goes through ao gate check plus the installed Git pre-push/pawl proof path. Runtime hooks are advisory and runtime-coupled; GitHub Actions are PR/tag/manual backstop telemetry. Deterministic behavior belongs in the CLI so both local and remote gates can call the same code.

Not in this family

Bead (unit of work / tracking) and schema / contract (data shape) are different layers — do not select among them with this rule.

Anti-pattern

• Deterministic logic as skill prose. If it is repeatable and can be coded it

belongs in a CLI subcommand; a skill that describes a mechanical step the agent must perform by hand will be skipped (skills are stochastic). Put the mechanism in ao; let the skill call it.

• Enforcement only in a runtime hook or assumed remote CI. Runtime hooks are

bypassable (AGENTOPS_HOOKS_DISABLED=1) and runtime-coupled; GitHub Actions are backstop telemetry for routine AgentOps work. Use the deterministic CLI plus the local cockpit/pre-push proof path as the gate of record, and mirror it remotely when PR/tag/manual evidence is needed.

Primitive

An atomic capability that the repo ships and that a Slice composes. The nouns of the working surface — what an agent can actually invoke.

Definition

A Primitive is one of:

• a skill under skills/<name>/
• a hook script under hooks/<name>.sh (registered in hooks/hooks.json)
• a CLI command or subcommand exposed by the ao binary
• an eval suite under evals/agentops-core/<name>.json
• a documented contract under docs/contracts/ or schemas/

Primitives are atomic in the sense that the repo ships them as one unit and agents invoke them as one unit. They are NOT atomic in implementation — a skill may have many references, a CLI command many flags.

When to use

• When designing or auditing a feature, enumerate the Primitives it touches.

If a feature lives in one Primitive only, it is probably under-integrated.

• When writing a Slice, the Slice is defined as the sequence of Primitives

it crosses.

Anti-pattern

• Half-built Primitives. A skill with no SKILL.md description, a CLI

command with help text that does not match behavior, a hook registered in hooks.json but missing the script file. Each is a Primitive that lies about its own existence.

• Primitive sprawl without an Index. When the count of skills, hooks, or

CLI commands grows past what an operator can hold in memory, and there is no Index entry under skills/domain/references/ describing them as a cohort, the surface decays into a junk drawer.

Example in this codebase

• The ao eval run CLI subcommand is one Primitive.
• The agentops:rpi skill is one Primitive.
• The precompact-snapshot.sh hook is one Primitive.
• The evals/agentops-core/skill-quality-gates.json suite is one Primitive

(it ships, it is invoked atomically, it contracts behavior).

See also

• slice.md — what composes Primitives end-to-end
• anti-pattern.md — common failure modes specific to Primitives
• entry.md — when a Primitive needs a corpus Entry to document its

vocabulary role

Reach (blast-radius tier)

Bounded context: BC1 Corpus. Ubiquitous-language term introduced by ag-bsf6

(epic ag-lhu0, memory-system re-architecture).

Reach is the blast-radius of a knowledge entry — how many agents pay the token cost of carrying it. It is orthogonal to maturity: maturity answers "is this true?"; reach answers "how widely is it injected?". An entry has exactly one reach tier:

Default is `pull`. An entry with no reach: frontmatter is read as pull (see SanitizeReach, cli/internal/search/learnings.go).

`always` is computed, never authored. A learning may not set reach: always by hand. The always tier is a projection of maturity == established ∩ canon-promoted (the verification-earned team canon) — the anti-self-certification invariant (ag-oqha). The T2 always-set is hard-capped at 1200 tokens at session bootstrap (ag-11bi). This keeps the always-on injection cost bounded and earns its place by verification rather than assertion.

Relates to: [[citation]] (use signals feed promotion), [[anti-pattern]] (canon-promoted high-severity anti-patterns are always-eligible guardrails), [[context-density-rule]] (reach is the per-entry expression of the density budget).

RPI

The inner tick of the Loop: one Research → Plan → Implement → Validate cycle over one bead, one behavior, one acceptance proof. RPI is the unit both drivers run. Evolve runs N rpi ticks in a session; Factory runs them unattended over a queue.

The five beats

RPI is one invocable unit

A substrate dispatches the /rpi loop (an agent running the skill) as one unit; it does not drive the five beats as separate substrate steps. Decomposing rpi across the substrate seam would duplicate the loop shape and pit substrate retry against the ratchet rules. Whoever owns the loop owns its invariants, and AgentOps owns rpi.

When to use

• Use RPI (or "the rpi tick") for one cycle over one bead. It is the Slice of the loop: one coherent arc with a single rollback semantic.
• Do not call rpi "the loop"; rpi is the inner tick of the loop.

Bounded context

BC3 Loop, reading from BC1 Corpus at the Research beat and writing to it at the Ratchet beat.

See also

• loop.md — the umbrella tick lives here
• evolve.md, factory.md — the two drivers that run rpi
• slice.md — a single rpi arc is one slice
• context-compiler.md — what feeds rpi's Research beat and absorbs its Ratchet beat

Silent Contract Violation

A failure mode of tool-use agents where generated code runs to completion, raises no exception, and is still wrong — so execution-based feedback (tests, exit codes, CI green) cannot see it. The failure the verification membrane exists to catch.

Definition

An agent composes calls to tools/skills and the program executes "successfully," but a contract between calls was violated invisibly. Four contract categories (adopted from RubricRefine, Anduril, arxiv 2605.09730v3) name where the violation lands — and are the category enum on a verdict.v1 finding:

• tool-choice — the wrong tool/skill was routed for the task.
• output-contract — the produced artifact's shape does not match the declared

output_contract / produces.

• call-signature — a call's inputs do not satisfy the callee's declared

consumes.

• data-provenance — a call consumes an argument no upstream step produced

(hallucinated or orphaned input).

Signature

Green tests, zero raised exceptions, a clean exit — yet wrong routing, a mismatched output shape, or an argument with no real source. The tell is that nothing failed loudly; the defect is in the seams between calls, not inside any one call.

Cost

The most expensive class of failure to catch late: it survives every execution-based gate and only surfaces downstream as corrupt data, a wrong action already taken (especially in stateful/expensive environments where retry is unsafe), or a confidently-wrong result a human trusts because "it ran."

Cause

Verification that fires only after execution, plus reliance on exceptions as the failure signal. The contracts exist (every SKILL.md declares consumes/produces/output_contract) but nothing scores a plan against them before dispatch. Unstructured self-critique misses it; structured, registry-conditioned contract checks catch it.

Refusal

When composing or reviewing a multi-step tool/skill plan, do not treat "it ran without error" as evidence of correctness. Score the plan against the four contract categories before the expensive/stateful action — a pre-execution contract gate — and record violations as verdict.v1 findings with the matching category. Single-step calls are exempt (the failure mode is inter-tool; see RubricRefine's flat single-step result).

When to use

• Reviewing a Workflow script, rpi/crank wave, or any composed tool plan

before it spends tokens or takes a live action.

• Triaging "it passed but produced the wrong thing" reports — name the category

rather than re-describing the symptom.

What it is not

• Not a runtime crash or a raised exception (those are caught by execution).
• Not a style/quality nit — it is a contract violation between calls.
• Not a substitute for the author≠judge independence invariant; the

pre-execution check is structured self-grade, a cheaper inner rung beneath cross-model verification, never a replacement for it.

Incident citation

• bd epic ag-5elx (RubricRefine integration) / bead ag-twl8 — this

entry and the verdict.v1 category enum were added together so the membrane has a name for the run-clean-but-wrong class it is built to catch.

See also

• anti-pattern.md — the shape this Entry follows
• slice.md — what a Silent Contract Violation corrupts when it triggers
• citation.md — how this anti-pattern is applied during a Slice

Slice

A vertical work unit that cuts through multiple Primitives end-to-end.

Definition

A Slice is a unit of change defined by the Primitives it crosses, not by the files it modifies. A Slice has:

• a goal stated in one sentence
• a Primitive set it must traverse (skill + hook + CLI + eval + doc, or

any subset, listed explicitly)

• a decision gate at the end: ship, defer to bd, or mark dead
• a single durable artifact (the diff, the audit doc, the council report)

A Slice is the unit of progress. A PR is one shape of Slice. A tech-debt-audit pass over one feature is another shape. A bug fix that touches only one Primitive is not a Slice — it is a patch.

When to use

• When the scope of work crosses more than one Primitive. Bundle them into

one Slice rather than threading state across many small PRs.

• When the question is "is this done?" — a Slice is done when its decision

gate has fired and the artifact is committed.

Anti-pattern

• Horizontal slicing. Editing 50 files but staying entirely within one

Primitive layer (e.g. "rename all variables across all skills"). This is refactoring, not a Slice; it accumulates churn without proving any end-to-end behavior.

• Slice without decision gate. Work that crosses Primitives but ends in

"we'll keep going" — the next session inherits ambiguous state. Every Slice must end with a yes/no, even if the answer is "defer."

• Slice without artifact. A session that touched code but produced no

reviewable artifact (no diff, no audit doc, no committed plan). The Slice did not happen.

Example in this codebase

• The CI eval-drift fix that landed this session is a Slice: it crossed

evals (the suites), CLI (ao eval run was used to verify), CI workflow (artifact upload added), and docs (commit message), with a clear ship decision and a commit pair as artifact.

• The proposed tech-debt audit is a sequence of Slices, one per repo

feature.

See also

• primitive.md — the atomic units a Slice crosses
• tracer-bullet.md — the thinnest possible Slice (the test entry)
• anti-pattern.md — what horizontal slicing and gateless slicing cost

Tracer Bullet

The thinnest possible Slice that touches every layer of Primitive the larger feature will eventually need, shipped as one Entry so the architecture proves itself before any layer thickens.

Definition

A Tracer Bullet is a Slice (see slice.md) constrained by three additional rules:

1. It must traverse every Primitive type the eventual feature touches — one Entry per Primitive type, not one per Primitive instance. 2. It must produce a single artifact that can be cited (see citation.md) by every subsequent Slice in the feature, so growth happens by thickening, not by re-architecting. 3. The Index (see index-primitive.md) for the feature's corpus surface must be updated by the Tracer Bullet itself; new Entries added later register against the existing Index, not a new one.

If any of those three rules cannot be satisfied, the work is not a Tracer Bullet — it is a regular Slice, and the architecture has not yet been proven.

When to use

• When starting a new domain area in the repo: design the corpus, the

retrieval surface, the schema, and the consumer all together, but at minimum depth, in one Slice.

• When the operator and the agent do not yet share vocabulary for a

feature: the Tracer Bullet doubles as the first Entry set (see entry.md) that future sessions cite.

Anti-pattern

• Tracer bullet that skips a Primitive type (see anti-pattern.md for

the corpus shape). If the Tracer Bullet covers skills + CLI + docs but omits a hook layer the eventual feature needs, the omitted layer's architecture is unproven and the next Slice has to back-fill from a position of weakness.

• Tracer bullet without a registered Index update. The shape works in

isolation but is not discoverable, so the corpus does not actually compound. Identical-in-effect to no Tracer Bullet at all.

• Multiple Tracer Bullets ahead of one consumer. Architecting three

parallel domain corpuses before any one has a citing skill is just speculation — pick one and prove a citation path through it first.

Example in this codebase

This Entry is the Tracer Bullet for the skills/domain/ corpus itself. It traverses every structural Primitive of the corpus:

• entry.md (the Entry primitive — this file is one)
• index-primitive.md (the Index — this file is registered there)
• citation.md (every see-also and every backtick-slug in this file is a

Citation)

• primitive.md (this Entry was composed by treating each prior Entry as a

Primitive)

• slice.md (this Entry IS a Slice, scoped to the domain skill creation)
• anti-pattern.md (the Anti-pattern section above cites it by slug)

If you can read this file end-to-end and reconstruct what a Tracer Bullet is using only the linked Entries, the corpus architecture has cleared its first proof. If you cannot, one of the six primitives is wrong or missing and we revise before writing any further Entries.

See also

• slice.md — Tracer Bullets are a constrained Slice
• primitive.md — what the Tracer Bullet must traverse
• entry.md / index-primitive.md / citation.md — the corpus structure

the Tracer Bullet proves

• anti-pattern.md — failure modes specific to the Tracer Bullet shape