Codebase Overview

July 14, 2026 · View on GitHub

Audience: contributors, operators, and agents orienting in this repo.
Scope: what the repository is, how major pieces connect, and where to look first.
When docs disagree: executable code and generated artifacts win — see Source-of-truth precedence.

For product doctrine read AgentOps 3.0 — the north star. For how work flows read Operating Loop. This page is the map of the territory.

For agents (quick facts)

Fact	Value
Product	In-session autonomous code validation for coding agents
Active waist	`ao session bootstrap` → operating loop → `ao gate check --fast` → push to `main`
Issue tracker	br (beads_rust) in `_beads/` — `BEADS_DIR="$(ao beads dir)" br <cmd>` until legacy `.beads/` retires
Skills SSOT	`skills/<slug>/SKILL.md` — never edit `~/.claude/skills/`
Release gate	Local cockpit: `ao gate check --fast --scope head` (Go registry in `cli/internal/gates/`)
CI	Backstop only — not routine release authority for every `main` push
Hooks	AgentOps 3.0 ships zero hooks; context is pulled explicitly
`.agents/`	Runtime knowledge — gitignored; durable public truth goes to `docs/`, `GOALS.md`, or provenance ledger
Worktrees	Mandatory for bead work when canonical root is contended — do not edit shared checkout
RPI CLI	`ao rpi` was removed in 3.0 (commit f61c5f0e7) — the RPI engine is gone; in-session navigation is the operating loop, out-of-session is NTM + Agent Mail
Regen after inventory edits	`make regen-all` then `make regen-check`

What this repository is

AgentOps is the operational layer for coding agents: skills + the ao Go CLI + a repo-local .agents/ corpus. It answers two questions before you grant more autonomy:

Is the code right? (validation membrane — tests, gates, council, vibe)
Is the proof durable? (evidence trail — verdicts, learnings, provenance)

The 3.0 identity is hookless and in-session. AgentOps does not ship a daemon, scheduler, or hosted control plane. Out-of-session always-on work is delegated to an external substrate (reference: NTM + MCP Agent Mail + ao agent).

Four product layers (public framing):

Layer	Problem	Key surfaces
Bookkeeping	work vanishes between sessions	`.agents/`, RPI packets, council verdicts
Context compiler	agents start cold	`ao session bootstrap`, skills, execution packets
Validation gates	plausible ≠ correct	`/council`, `/vibe`, `/premortem`, `ao gate`
Knowledge flywheel	lessons don't compound	`/postmortem`, `/pattern-mining`, `/operationalize`, promotion ratchet, `ao lookup`

Honest fitness posture: the apparatus to measure corpus delta exists; live-agent uplift is not yet proven. See AgentOps effectiveness evidence.

Scale (measured)

Dimension	Size
Go source files	1643 (`git ls-files '*.go'`)
Active skills	63 (`git ls-files skills
Codex skill twins	62 (`git ls-files skills-codex
CLI top-level commands	32 default / 89 with `flywheel legacy` (`go run [-tags profile] ./cmd/ao --help`)
Gate checks	83 (`rg -c 'ID:' cli/internal/gates/checks/seed.go`)
Shell scripts	329 (`git ls-files scripts
Bats test files	240 (`git ls-files tests
Claude workflows	4 (`git ls-files .claude/workflows
Registry capabilities	98 (`jq '.capabilities

Six bounded contexts

Product and code route through six DDD bounded contexts. Full routing: Component Map. Contract: docs/contracts/bounded-contexts.yaml.

BC	Name	Center of gravity
BC1	Corpus	`.agents/`, `ao inject`, `/postmortem`, `/pattern-mining`, `/operationalize`, `/harvest`
BC2	Validation	`ao gate check`, `/validate`, `/council`, `/vibe`
BC3	Loop	operating loop, `/evolve`, `br`, goals, autodev
BC4	Factory	skill-builder, registries, standards, dispositions
BC5	Runtime	CLI, installers, plugin manifests
BC6	Orchestration	NTM, Agent Mail, swarm — substrate boundary

BC3 Loop ──▶ BC1 Corpus (compounding context)
          ──▶ BC2 Validation (proof before land)
BC4 Factory ──▶ skills/registries
BC5 Runtime ──▶ ao CLI + plugins
BC6 Orchestration ──▶ dispatches whole skills (never decomposes RPI internals)

Directory map

Path	Owns
`skills/`	Skill SSOT — `SKILL.md`, references, Gherkin `.feature` acceptance
`skills-codex/`	Checked-in Codex runtime twins (62); maintained with refresh scripts
`skills-codex-overrides/`	Durable Codex tailoring when runtime must diverge
`cli/`	Go control plane — `cmd/ao/`, `internal/`, gates, corpus, RPI legacy
`scripts/`	Validation, regen, release (375 shell scripts)
`tests/`	Bats gate tests, integration, e2e, docs validation
`schemas/`	JSON schemas for config, provenance, packets
`docs/`	Narrative architecture, ADRs, contracts, MkDocs site
`.agents/`	Runtime knowledge (gitignored) — learnings, council, RPI queue
`_beads/`	Private br ledger (nested git repo) — never stage it from the public repo
`.beads/`	Pre-br bd config for this repo's tracking — preserved, not authoritative (bd/dolt itself is the gascity substrate store)
`registry.json`	Generated SKU catalog — do not hand-edit
`.claude/workflows/`	Claude-only workflow scripts (kind: `workflow`)
`.claude-plugin/`, `.codex-plugin/`, `.agy-plugin/`	Runtime install manifests

Source-of-truth precedence

When narrative docs disagree with executable behavior:

Executable + generated — cli/**, scripts/**, cli/docs/COMMANDS.md, generated registries
Contracts — skills/**/SKILL.md, schemas/**, docs/contracts/**
Narrative — docs/**, README.md, AGENTS*.md

Report mismatches; do not silently follow stale docs.

The active waist (what actually runs today)

ao session bootstrap          # explicit orientation (replaces hook injection)
        ↓
Operating loop                # BDD → br bead → slice → TDD → validate
        ↓
ao gate check --fast --scope head   # local cockpit gate (BC2)
        ↓
git push → main               # rebase-on-reject; no routine PR wall
        ↓
validate.yml (optional)       # CI backstop on tags, PRs, manual dispatch

Primary CLI commands (active)

Command	Role
`ao session bootstrap`	Universal init prompt for any agent runtime
`ao gate check --fast`	Pre-push release authority
`ao gate check --full`	CI-parity local proof
`ao goals measure`	Fitness against `GOALS.md`
`ao doctor`	Self-healing cockpit
`ao capabilities` / `ao robot-docs`	Machine-readable CLI contract

Full surface: generated cli/docs/COMMANDS.md.

Legacy but load-bearing (do not delete casually)

Surface	Status
`ao codex *`	`legacy`-tagged archive; absent from the default spine
`ao inject`, `ao lookup`, `ao corpus *`	Tagged archives; `ao session bootstrap` is the default-spine orientation path
`ao mcp serve`, `ao agent`	`legacy`-tagged optional substrate surfaces; absent from the default spine
`ao rpi phased/loop/serve/stream`	Removed in 3.0 (f61c5f0e7) — engine gone; use the operating loop in-session, NTM + Agent Mail out-of-session
`scripts/pre-push-gate.sh`	Bash escape hatch — `AGENTOPS_GATE_BASH=1` only
Gas City (`runtime=gc`)	Removed — bridge deleted. gc itself lives beside as a blessed coexisting substrate (owned fork; drive via `skills/using-gc` + `packs/agentops-membrane`)
In-repo daemon/scheduler	Removed — ADR-0009

Navigation rule: Operating Loop is primary navigation for how work flows. /rpi is one turn's executor skill — not the primary substrate. Live multi-agent orchestration runs on NTM + Agent Mail under .agents/agent-constitution.md.

RPI terminology

These names overlap in docs and code but are not contradictory. Use this table when routing:

Term	Status	Meaning
Operating loop	Primary navigation	Seven-move doctrine in operating-loop.md — how work flows in-session
`/rpi` skill	Live inner loop	One-turn executor skill; not primary navigation
`ao rpi` CLI	Removed (3.0)	Engine removed in f61c5f0e7 — was a load-bearing legacy lane; superseded by the operating loop (in-session) and NTM + Agent Mail (out-of-session)
Substrate dispatch	Out-of-session	`/agent-native` drives portable roles through NTM and uses Agent Mail only for contested writes; GC remains an explicit coexisting adapter (the `ao rpi` loop once wrapped here was removed in 3.0)

Skills ecosystem

Structure per skill

skills/<slug>/
  SKILL.md              # invocable contract (frontmatter + body)
  references/           # overflow, templates, *.feature acceptance
  scripts/              # validate.sh, helpers (optional)

Frontmatter carries DDD/hex edges (hexagonal_role, consumes, produces, context_rel), practice lineage (practices: [slug]), and tier metadata.

Three drift-gated registries

Edit sources, then regenerate:

make regen-all      # write mode
make regen-check    # drift gate (CI uses this)

Registry	Sources	Generated
Skills	`skills/**/SKILL.md`	`registry.json`, `docs/contracts/context-map.md`, domain map
Workflows	`.claude/workflows/*.js` + `skill-dispositions.yaml`	`registry.json` workflows[]
CLI	`cli/cmd/ao/`	`cli/docs/COMMANDS.md`, `docs/cli-surface.{json,md}`

Curated routers (editable, gated for refs): docs/SKILLS.md, skills/SKILL-TIERS.md, docs/contracts/skill-dispositions.yaml.

Retirement: ao skills retire <slug> [--into <target>] — flips ledger to historical, regens, scans for stale refs.

Gate architecture

The Go gate (cli/internal/gates/) is the routine release authority (ag-qidx push-to-main model).

Check { ID, Tiers (Fast|Full), Match[] globs, Blocking, Backing | Run }
  → Registry (103 checks in checks/seed.go)
  → Orchestrator (serial; changed-file routing in Fast mode)
  → Report (PASS / WARN / FAIL / SKIP)

Fast mode (--fast --scope head): runs always-on structural checks + checks whose Match globs hit changed files.

Full mode (--full): all registry checks — CI parity lane.

Implementation styles:

Shell-backed → scripts/check-*.sh (majority)
Native Go → go.build, go.vet, learning.coherence, etc.

Triple orchestration (migration in progress):

Go gate — primary, growing
YAML purpose jobs in .github/workflows/validate.yml — CI backstop
Bash monolith scripts/pre-push-gate.sh — legacy escape hatch only

Local commands:

ao gate check --fast --scope head                    # routine pre-push
ao gate check --full --workflow-coverage             # CI-parity proof
cd cli && go test ./internal/gates/checks -count=1   # registry parity tests

Knowledge flywheel

Work → /postmortem → /pattern-mining → /operationalize
     → .agents/learnings/pending/
     → pool score → promote (gold/silver/bronze)
     → ao lookup (decay-ranked, cited) → next session
     → gates enforce promotion ratchet

Surface	Path	Tracked in git?
Runtime corpus	`.agents/`	No (policy)
Findings ledger	`.agents/findings/registry.jsonl`	No
RPI work queue	`.agents/rpi/next-work.jsonl`	No
Provenance	`docs/provenance/ledger.jsonl`	Yes — append-only, ledger wins over tracker
Goals fitness	`GOALS.md`	Yes

Write contract for .agents/ surfaces: docs/contracts/agents-write-surfaces.md.

Doctrine import (not locally proven): Effective Feedback Compute.

Documentation altitude stack

Read the right layer for your question:

Altitude	Files
Router	`AGENTS.md`, `CLAUDE.md` (≤250 lines; pointers only)
Detail owners	`agent-workflow-reference.md`, `CI-CD.md`, `codex-skill-api.md`, `repo-execution-profile.md`
Contributor onboarding	`newcomer-guide.md`, this page
Doctrine	`3.0.md`, `operating-loop.md`, `GOALS.md`, `PRODUCT.md`
Full catalog	`documentation-index.md`

Work lifecycle (contributor path)

Claim — BEADS_DIR="$(ao beads dir)" br ready --json → BEADS_DIR="$(ao beads dir)" br update <id> --claim --json
Scope — read bead acceptance (.feature or embedded ## Scenarios)
Implement in worktree — git worktree add wt-<bead-id> -b <type>/<bead-id>-<slug>
Verify — ao gate check --fast --scope head (+ targeted tests for touched surfaces)
Land — push to main; cockpit pre-push hook runs gate; rebase-on-reject on conflict

Branch shape, provenance trailers, and session scope rules: agent-workflow-reference.md.

Known footguns (read before you edit)

These recur in audits and findings registries:

Footgun	Correct behavior
Editing `~/.claude/skills/`	Edit `skills/` in this repo only
Using `bd` / Dolt for this repo's tracking	Use `br` with `BEADS_DIR="$(ao beads dir)"` — bd/dolt is the gascity substrate store, a different layer, not this repo's tracker
Editing canonical root under swarm load	Use a worktree per bead
Staging the private ledger from the parent repo	Never — private nested repo; sync with `git -C "$(ao beads dir)" push`
Hand-editing `registry.json` or context-map	Run `make regen-all` from source edits
Assuming CI blocks every `main` push	Local gate is routine authority; CI is backstop
Treating `/rpi` as the live orchestration substrate	NTM + Agent Mail for out-of-session; operating loop for in-session navigation
Running `claude -p` / `claude --print`	Forbidden — burns quota; use Codex exec or interactive panes
Trusting narrative over executable behavior	Check `cli/`, generated docs, and gates first

Some older docs (ARCHITECTURE.md, ports-and-adapters.md) still mention hooks, bd, or PR-per-change — treat as historical unless reconciled. cli/AGENTS.md is a pointer stub to root AGENTS.md (Wave A).

Strengths and open debt

Strengths

Clear 3.0 product identity (validation-centered, hookless, in-session)
Declarative gate registry with Fast/Full tiers and workflow parity tests
Skill factory with disposition ledger and multi-runtime Codex parity
Hexagonal CLI with strong agent ergonomics (capabilities, robot-docs, --json)
Honest eval posture — refuses to market ahead of measured uplift

Open debt

Gate migration: collapse YAML/bash triple orchestration into Go registry (Wave E drained 2 deferred scripts; 11 remain)
Doc reconciliation: Wave C landed; docs/3.0-readiness.md checklist items still open
Disposition debt: ~34 skills marked update/refactor — triage checklist at docs/audits/2026-06-16-skill-disposition-triage.md
Worktree hygiene: 27 merge-eligible worktrees in dry-run — audit at docs/audits/2026-06-16-worktree-disposition-audit.md; no --apply without human ACK

Task	Read
Pick a skill	`SKILLS.md`, `skills-decision-tree.md`
CLI behavior	`cli/docs/COMMANDS.md`
CI / gates	`CI-CD.md`, `agent-workflow-reference.md`
Codex parity	`codex-skill-api.md`
Fitness / honesty	`GOALS.md`, `evals/agentops-effectiveness-evidence.md`
`.agents/` writes	`contracts/agents-write-surfaces.md`