Documentation Index

July 12, 2026 · View on GitHub

Master table of contents for AgentOps documentation.

Getting Started

Pick your path: evaluating the product → README then FAQ. Installing for real work → Getting Started landing then Create Your First Skill. Orienting in the codebase as a contributor → Newcomer Guide then CONTRIBUTING. Upgrading from an older version → Upgrading.

README — Project overview and quick start
Getting Started — Install + first command landing page
PRACTICE-REGISTRY.md — Practice lineage and canonical practices: [slug] registry
AgentOps 3.0 — the north star — The single source of truth for what 3.0 is: the hookless-first CDLC loop, the four-practice waist (BDD/DDD/Hexagonal/TDD), and what "3.0-ready" means
Roadmap — Designed-but-not-built features (planned, not committed): CLI roadmap, curation pipeline later stages, hookless default-install
3.0-Readiness Level-Set — Honest box-by-box status against the 3.0 acceptance criteria after the 2026-05-23 reconciliation: what's done, fitness snapshot, named remaining work
AgentOps 3.0 Explainer Kit — Public gist/launch copy for the council-first 3.0 story
AgentOps 3.0 First-Value Path — First session via skills: /plan (Gherkin) → /implement (ATDD) → /validate (membrane vs that behavior)
Intent → Validated Code — Full product flow from intent to membrane-proven acceptance
Skills Matrix — Every skill placed on operating-loop moves 1–7
AgentOps 3.0 YouTube Starter Series — Launch video plan, scripts, clip hooks, CTAs, and PMF measurement fields
AgentOps 3.0 PMF Evidence Loop — Content-led discovery loop and claim-gated evidence plan
Behavioral Discipline — Before/after examples of good coding-agent behavior
Driving Agents Reliably — Operator's field guide: three laws, a copy-paste prompt pack, and the failure→mechanism table (companion to Behavioral Discipline)
Newcomer Guide — Fast orientation to repo structure, architecture, and contribution path
Codebase Overview — Consolidated map of subsystems, active waist, registries, gates, footguns, and reading order (humans + agents)
FAQ — Comparisons, limitations, subagent nesting, uninstall
CONTRIBUTING — How to contribute
Create Your First Skill — Fast path for authoring a first skill without tripping CI
Dependencies — Complete tool-dependency declaration (ao, git, br/bv, gh, go, and utilities) with purpose, required-vs-optional, and fallback-if-absent
Upgrading — Version-to-version migration notes and breaking changes
Migration Guide — Living map from every removed/retired surface (bd, hooks, daemon, ao rpi, corpus/flywheel, acfs) to what you use instead, plus the recommended open-source stack (br/bv, NTM, cass/cm, ubs, dcg, ACFS)
Migrating to AgentOps 3.0 — What was removed in 3.0 (hooks, daemon, scheduler, factory) and what to use instead (in-session loop + an adopted substrate: NTM / MCP / managed-agents)
AGENTS.md — Local agent instructions for this repo
Changelog — Release history
Security — Vulnerability reporting

Four Product Layers

Layer	What it does	Key surfaces
Bookkeeping (L0)	Records agent work so attempts, decisions, verdicts, and handoffs leave evidence	`.agents/`, RPI packets, council verdicts, retros, post-mortems
Context Compiler (L1)	Assembles the right context for the right phase	`ao inject`, `ao compile`, skills, execution packets
Validation Gates (L2)	Challenges plans and code before they ship	`/council`, `/vibe`, `/pre-mortem`, `/post-mortem`
Knowledge Flywheel (L3)	Extracts, scores, and resurfaces learnings	`/post-mortem --quick`, `/curate --mode=forge`, `ao lookup`, `.agents/`

Deep dives: CDLC (AgentOps' context-native SDLC under token scarcity), Knowledge Flywheel, Context Lifecycle, Assurance Profile, PRODUCT.md

Bridge / framing docs:

A wiki for your agents — .agents/ as a markdown wiki agents read, traverse, and contribute to (deflationary framing for the busy buyer)
AgentOps as a Trust Factory — Mapping AgentOps to the five-step trust-factory primitive (identity, reproducibility, evaluation, evidence, recovery)

Architecture

Codebase Overview — Consolidated repo map: bounded contexts, directory ownership, active CLI waist, registries, gates, knowledge flywheel, footguns, reading order
How It Works — Brownian Ratchet, Ralph Wiggum Pattern, agent backends, context windowing
Software Factory Surface — Explicit automation surface for briefings, RPI flows, and operator-controlled closeout
Assurance Profile — High-assurance operating posture, authority boundaries, and evidence artifact expectations for constrained environments
Architecture — System design and component overview
Architecture Folder Index — Architecture subdocs overview
Codex Hookless Lifecycle — Runtime-aware lifecycle fallback for Codex when hooks are unavailable
Codex Task Packet Contract — Non-mutating Codex dispatch packet, auth guard, sandbox, stdin, timeout, resume, and run-receipt contract
Codex Fanout Approval Packet — PerspectivePlan, SynthesisPacket, and ApprovalEdge contract for Fable-gated Codex discovery before bead creation
Primitive Chains — Audited primitive set, lifecycle chains, and terminology drift ledger
Ports and Adapters — Hexagonal seam: inner-hexagon domain, driving/driven adapters, ports, and how to add a new adapter
Hexagon Port-Realness Audit — Empirical 2026-05-23 inventory of all 26 declared ports (real vs in-memory vs bypassed), direct-coupling hotspots (git/bd/loop/corpus) with file:line, and the recommended adapter build order for epic soc-zvhsl
Operating Loop — Operational discipline every process skill executes: BDD intent → vertical slices → conflict-free wave → bead acceptance → evidence (cleanroom companion to ports-and-adapters)
The Canonical Loop Model — "One loop body, two drivers, one inner tick, one config": how rpi/evolve/factory/crank/swarm/autodev relate; the in-session loop is AgentOps-shipped, the out-of-session Factory driver is substrate-owned (reference: NTM / MCP / managed-agents)
Intent-to-Loop Hexagon — Process-level ports/adapters from BDD intent through beads, slices, validation, ratchet evidence, and loop steering
Fungibility Charter — AgentOps 3.0's six doctrinal commitments (single-model RPI default, role-free claiming, stateless agents, universal init, automatic death recovery, opt-in specialization); fungible by default, specialized when you opt in
Behavior-Shaping Environment — The why beneath the loop: AgentOps as an operant-conditioning system (Antecedent → Behavior → Consequence); arrange the environment + reinforce/stop the behaviors you agree on
ADR-0001: Adopt DDD + Hexagonal Architecture — Decision record for encoding DDD + Hexagonal with ExecutionPacket as the tracer-bullet aggregate
ADR-0002: AgentOps 3.0 Hookless-First CDLC Rearchitecture — Proposed 3.0 direction: demote hooks to optional runtime adapters and center CDLC bounded contexts
ADR-0003: Executable-Spec Artifact Durability — Where executable-spec scenarios and domain manifests live: promoted spec scenarios in tracked spec/scenarios/, ad hoc holdout scenarios stay in .agents/holdout/
ADR-0013: Domain-Slice Manifest Contract — Schema and resolution rules for docs/domains/<name>/manifest.yaml, the domain-scoped boundary contract consumed by ao rpi phased --domain (formerly ADR-0004; renumbered to resolve a duplicate number)
ADR-0005: Trace-Link Convention — The directive→scenario→bead→verdict→learning link grammar that ao goals trace renders and audits, including warning/error defect classes and --strict escalation
ADR-0006: Re-Steer Policy and Mutation Safety — The docs/re-steer-policy.json engine, human-gate, and non-lossy GOALS.md patcher that govern ao goals steer recommend/apply
ADR-0007: Deterministic /evolve Loop — Only the Operator Stops It — Mechanical pre-cycle gate (scripts/evolve/halt-check.sh): operator-only markers, goal-regression halt, revert-on-red; ported from the mt-olympus unbounded-evolve substrate
ADR-0008: /evolve Operating Model — Intelligent-Agile, Not Waterfall — Three-layer loop contract (intent re-read each cycle / locked architecture / bounded shaping authority) + the scope-precondition audit that prevents building-the-wrong-thing drift
ADR-0009: Delete the Daemon — AgentOps Is In-Session Only — Why the standalone daemon/scheduler/overnight-runner was deleted (not deprecated): AgentOps is a Gas City reference config with no core to protect, the in-session loop is the zero-dependency sovereignty floor, always-on opts into Gas City; names the rejected deprecate-keep-standalone alternative and the e2e-proof GC dispatch gap
ADR-0010: E6 Session-Log Miner Is Build-Native — The E6.0 spike decision (cross-family): build the session-JSONL→typed-PROV-O miner native over cli/internal/parser + the ASSAY --mine-cmd slot; cass/cm stay adopted for search/memory only (neither owns the provenance graph). Steals cass's incremental-index discipline; no langchain core dep; scopes ao provenance mine-session (E6.1/...6.2)
ADR-0011: Escape-Corpus Compounding Unproven — Structural Data-Starvation — The self-improvement mechanism is proven e2e (escape→check→block), but "the escape-corpus compounds" is demoted to an unproven hypothesis: a competent membrane catches at review, so it self-starves its own escape supply (self-improvement anti-correlated with membrane quality). Records revival conditions; the proven claim — independent verification, no verdict = not done — is unchanged
ADR-0012: Focus the Surface on Membrane + Bookkeeper; Archive the Satellites — Re-headline the public surface on the two proven cores (validation membrane + hash-chained bookkeeper); archive the unproven corpus/flywheel (behind //go:build flywheel) and RPI/factory (behind legacy) satellites rather than delete them, because the ADR-0004/0009/0011 revival conditions require the code to stay buildable; targets a ~22-command / ~15-skill spine
PDC Framework — Prevent, Detect, Correct quality control approach
FAAFO Alignment — FAAFO promise framework for vibe coding value
Failure Patterns — The 12 failure patterns reference guide

Skills

Skills Reference — Complete reference for all AgentOps skills
Skills Decision Tree — "Which skill do I need next?" — single source of truth linked from harvest, compile, knowledge-activation, and quickstart SKILL.md
Skill API — Frontmatter fields, context declarations, enforcement status
Critical Skills Policy — Human-supervised skill-edit denylist consumed by ao skills edit seal
Skill Quality Rubric — Scoring rubric for repo-runtime, export, and mega-skill readiness
AgentOps Domain Evolution BDD — Gherkin acceptance contract for skill, CLI, and hook evolution
AgentOps Skill Domain Map — All 62 checked-in skills mapped to Corpus, Validation, Loop, Factory, and Runtime domains (drift-checked by scripts/check-registry-drift.sh)
AgentOps Hexagonal Architecture Map — Bounded contexts, ports, adapters, and proof gates for the evolution program
AgentOps Domain Evolution Plan — Sequenced bootstrap and evolution plan anchored to soc-y5vh
Skill Tiers — Taxonomy and dependency graph
skill-builder — Scaffold or absorb new SKILL.md files against the unified template
heal-skill (deep audit mode) — Two-pass audit of an existing SKILL.md against the unified template (absorbed from the retired skill-auditor)
Tier-S Audit Pilot 2026-05-06 — Empirical baseline of 5 Tier-S skills against the auditor
Claude Code Skills Docs — Official Claude Code skills documentation (upstream)

Workflows

Agent Workflow Reference — On-demand deep detail behind the thin CLAUDE.md router: building the CLI, key scripts, CI-validation rules, testing rules, release pipeline, ao goals surface
Workflow Guide — Decision matrix for choosing the right workflow
Complete Cycle — Full Research, Plan, Implement, Validate, Learn workflow
Session Lifecycle — Runtime-aware session start and closeout across hook-capable and Codex hookless runtimes
Quick Fix — Fast implementation for simple, low-risk changes
Debug Cycle — Systematic debugging from symptoms to root cause to fix
Knowledge Synthesis — Extract and synthesize knowledge from multiple sources
Assumption Validation — Validate research assumptions before planning
Post-Work Retro — Systematic retrospective after completing work
Multi-Domain — Coordinate work spanning multiple domains
Continuous Improvement — Ongoing system optimization and pattern refinement
Infrastructure Deployment — Orchestrate deployment with validation gates
Meta-Observer Pattern — Autonomous multi-session coordination

Meta-Observer

Meta-Observer README — Complete workflow package overview
Pattern Guide — Autonomous multi-session coordination guide
Example Session — Real example from 2025-11-09
Showcase — Distributed intelligence for multi-session work

Concepts

Philosophy — Five validated principles for building with coding agents, with evidence from five months of production use
Sovereignty Proof — Falsifiable case studies showing where independent-vendor review caught what same-vendor review missed (2026-05-15 RPI reframe, 2026-05-16 F6/F7 findings). CI gate validate-sovereignty-proof-citations keeps the cited file:line evidence honest.
Assurance Profile — High-assurance operating posture for local, auditable, constrained-environment agent work
Context Lifecycle Contract — Internal proof contract behind the compounding product loop
Knowledge Flywheel — How every session makes the next one smarter
The Science — Research behind knowledge decay and compounding
Effective Feedback Compute — Imported doctrine: validation quality over raw token volume (η = EFC/C_raw); not locally proven
AgentOps Effectiveness Evidence — Honest audit: what we can and cannot claim about live-agent uplift
Brownian Ratchet — AI-native development philosophy
Evolve Setup — GOALS.md, fitness loop, overnight runs
Seed Definition — What ao seed creates and why
Scale Without Swarms — Single-agent scaling patterns
Curation Pipeline — Six-stage knowledge curation lifecycle
Context Packet — Agent context assembly specification
Domain and Practice Packets — Product-facing contract for the shared engineering domain agents judge work against
Strategic Direction — Product strategy and roadmap
Leverage Points — Meadows-inspired system intervention points

Patterns

.agents/ Hygiene Contract — Five-ring layering for taking native ownership of structural surfaces
Completion Notifications — Off-API webhook-equivalent patterns (GitHub Actions, post-commit hook, daemon log tail)

Standards

Standards Overview — Coding standards index
Go Style Guide — Go coding conventions
TypeScript Standards — TypeScript coding conventions
Python Style Guide — Python coding conventions
Shell Script Standards — Shell script conventions
Markdown Style Guide — Markdown formatting conventions
JSON/JSONL Standards — JSON and JSONL conventions
YAML/Helm Standards — YAML and Helm chart conventions
Tag Vocabulary — Standard tag definitions

Testing & CI

Testing Guide — Umbrella guide for all test types, tiers, and conventions
CI/CD Architecture — Workflow map, job graph, blocking vs soft gates, local CI
Testing Skills — Guide for writing and running skill integration tests
Release E2E Checklist — Fast/full local gate commands and release smoke expectations

Levels

Levels Overview — Progressive learning path

L1 — Basics

L1 README — Single-session work with Claude Code
Research — Explore a codebase to understand how it works
Implement — Make changes, validate, commit
Demo: Research Session — Example research session
Demo: Implement Session — Example implement session

L2 — Persistence

L2 README — Cross-session bookkeeping with .agents/
Research — Explore codebase and save findings
Retro — Extract session learnings
Demo: Research Session — Example persistent research
Demo: Retro Session — Example retro session

L3 — State Management

L3 README — Issue tracking with beads
Plan — Decompose goals into tracked issues
Implement — Execute, validate, commit, close
Demo: Plan Session — Example planning session
Demo: Implement Session — Example implement session

L4 — Parallelization

L4 README — Wave-based parallel execution
Implement Wave — Execute unblocked issues in parallel
Demo: Wave Session — Example wave execution

L5 — Orchestration

L5 README — Full autonomous operation with /crank
Crank — Execute epics to completion
Demo: Crank Session — Example crank session

Profiles

Activation Profiles — 3.0 first-value workflow recipes with explicit inputs, commands, artifacts, and fallbacks
Profiles Overview — Role-based profile organization
Profile Comparison — Workspace profiles vs 12-Factor examples
Meta-Patterns — Patterns extracted from role-based taxonomy
Example: Software Dev — Software development session
Example: Platform Ops — Platform operations session
Example: Content Creation — Content creation session

Comparisons

Comparisons Overview — AgentOps vs the competition
Competition RPI: Memory, Learning, Wiki, Dream, and Pruning Pipelines — Cross-product primitive and pipeline audit
vs SDD — AgentOps vs Spec-Driven Development
vs GSD — AgentOps vs Get Shit Done
vs Superpowers — AgentOps vs Superpowers plugin
vs Claude-Flow — AgentOps vs Claude-Flow orchestration
vs Compound Engineer — AgentOps vs Compound Engineering plugin
vs hosted AI code review — AgentOps vs CodeRabbit, Qodo, and Copilot code review
vs Tons-of-Skills — AgentOps vs jeremylongshore/claude-code-plugins-plus-skills (volume marketplace lane)
vs everything-claude-code — AgentOps vs affaan-m/everything-claude-code (cross-harness lane)
Competitive Radar — Current market read and improvement pressure

Convergence

Convergence Overview — The industry arriving at the structure AgentOps runs (vindication, not competition)
The Reading — Living thesis: the industry is converging, and here's the mechanism why
Convergence Ledger — Dated receipts: external parties independently arriving at the AgentOps thesis
Google SRE — Encoding map: where Google's 2026 SRE AI whitepaper aligns with AgentOps doctrine, point by point

Positioning

Positioning Overview — Product and messaging foundations
DevOps for Vibe-Coding — Strategic foundation document
12 Factors Validation Lens — Shift-left validation for coding agents

Plans

Plans Overview — Time-stamped plans index
Validated Release Pipeline — Release pipeline design (2026-01-28)
All Improvements — Comprehensive improvement plan (2026-02-24)
AO Search as an Upstream CASS Wrapper — Make ao search broker to upstream cass plus AO-local fallback (2026-03-22)
AgentOps 3.0 Hookless CDLC Rearchitecture — Hookless-first 3.0 plan with bounded contexts, hook lease disposition, and migration waves

Templates

Templates Overview — Templates index
Intent Issue Template — BDD-shaped intent issue (Given/When/Then acceptance examples, bounded context, slice candidates) — produced by /discovery, consumed by /plan
Goal Design Intent Template — Schema-backed .agents/goal-design/<slug>/intent.md template for objective, BDD behavior, boundaries, evidence, stale inputs, and hard rules
Goal Design Driver Template — Schema-backed .agents/goal-design/<slug>/driver.md template for four-loop routing, candidate beads, route-back rules, digest integrity, and validation policy
Slice Validation Plan Template — Per-slice proof with first failing test, write-scope, wave-validity check, and roll-up acceptance — produced by /plan, executed by /validate
Workflow Template — Template for new workflows
Agent Template — Template for new agents
Skill Template — Template for new skills
Command Template — Template for new commands
Kernel Template — Template for new project kernels
AgentOps 3.0 Domain/Practice Packet — Tracked launch-demo packet example
AgentOps 3.0 Council Demo Storyboard — Canonical council-first launch demo script
AgentOps 3.0 Council Verdict Example — Public sample verdict artifact for the explainer kit
Product Template — Template for writing a PRODUCT.md

Reference

Agent Footguns — Common agent failure modes and mitigations
AgentOps Brief — Executive summary
AgentOps System Map — Visual system map
Working with .agents/ — Operator guide for .agents/ state, write surfaces, and contributor flow
Glossary — Definitions of domain-specific terms (Beads, Brownian Ratchet, RPI, etc.)
CLI Reference — Complete ao command reference (generated from source)
CLI Command Surface — Generated classification of leaf commands by coverage and runtime safety
CLI ↔ Skills Map — Which commands are called by which skills
Reference — Pipeline stages, execution-model table, and skill-selection matrix (deep-dive companion to SKILLS.md)
Releasing — Release process for ao CLI and plugin
Environment Variables — All configuration variables with defaults and precedence
Schemas — JSON Schemas for manifests, runtime artifacts, and internal runtime contracts
Skill Router — Which skill to use for which task
Troubleshooting — Common issues and quick fixes
Incident Runbook — Operational runbook for incidents and recovery
Autonomy Runtime Cycle-1 Runbook — Safe activation/rollback/evidence checks for RPI, evolve, and daemon-backed autonomy work
bd Server-Mode Tracker Closeout — Historical closeout note for retired bd/Dolt tracker deployments; not the current AgentOps tracker path
Release Process Runbook — Step-by-step release runbook for gates, version injection, goreleaser, and post-release checks; complements RELEASING.md
PR Creation From Linked Worktrees — Root-cause + verified fix for linked-worktree PR branch inference issues; retained as historical PR-flow guidance
AO Command Customization Matrix — External command dependencies and customization policy tiers
Contracts Index — Landing page for all inter-component contracts
Pawls — the one-way doors — The ratchet's static map: the short list of irreversible actions (mutate-shared-trunk · delete · external-send/shared-state-mutation · schema/contract change · credential/authority change · spend) where the cross-family gate fires; everything else runs as ungated chaos
Operating Discipline (D1–D16) — The general, substrate-neutral fleet-operating rules (admission-first · author≠judge · fail-closed · evidence-bound · single-writer · typed transitions) folded from the mt-olympus triangulated kernel; each rule marked embodied-in-gate (cited to pawls.md / pawl-verdict.sh / reconcile-pr.sh), advisory doctrine, or dropped-as-cathedral
Lesson Format — Schema for .agents/learnings/ entries with frontmatter (id/severity/trigger/verifiable/rule/falsified_by/practice/related) and graduation path (unassigned → proposed → accepted → encoded)
Corpus Learning Seam — Field-level public/private boundary for learning records (epic ag-k7tq9 S3): the sensitivity + publishable promote-gate fields, what crosses the seam (the abstracted lesson) vs what never does (evidence/provenance/source_session), and the ao corpus classify migration; cites the cross-family council verdict
bd remember Migration Manifest — Lineage-preserving manifest contract for classifying bd remember notes into bead-scoped, pull-learning, or discard dispositions before migration
Bounded Contexts (yaml) — Canonical BC1-BC6 definitions (id/name/responsibility/ports/center-of-gravity); registry doc prose must match this yaml (drift-checked by scripts/check-bounded-contexts-drift.sh, soc-zxia.2)
add-validate-job scaffolder — CI integration scaffolder; emits all 5 touch-points (workflow + summary needs + summary echo + pre-push + bats stub + AGENTS table) atomically when adding a new validate-* job (soc-3oij)
CI Jobs Manifest (yaml) — Canonical reason+failure for every validate.yml CI job; AGENTS.md ### CI Jobs and What They Check table is rendered from this yaml + workflow summary.needs via scripts/generate-ci-jobs-table.sh (golden-file gate enforced by validate-ci-policy-parity, soc-3oij)
Scenario → Test Linkage — Every Gherkin scenario in skills/*/references/*.feature must declare its covering test via a @covered-by:<test-path> tag or be allowlisted as doc-only in scripts/.scenario-linkage-allow; gate is scripts/check-scenario-test-linkage.sh / validate-scenario-test-linkage (sibling to executable-spec-link-integrity; links scenarios→tests, soc-63xfx)
@claude Bot Delegation — Operational runbook for the @claude GitHub App: permissions, triggers, status decoding, gotchas, when to delegate
Local Pre-Push Gate Retirement — Historical ADR superseded by the local cockpit gate posture; retained for lineage, not current release authority
Skill Dispositions (yaml) — Canonical per-skill domain/disposition/rationale data; source-of-truth for agentops-skill-domain-map.md. Hand-edits to the .md forbidden — edit yaml and run scripts/generate-skill-domain-map.sh (golden-file gate, soc-zxia.3)
Context Map — Auto-generated bounded-context map of skills by hexagonal role with relationship and data-flow views (see ADR-0001)
Skill-Flow Connectivity — Closed consumes vocabulary + cross-layer connectivity model (consumes/context_rel/metadata.dependencies); gate scripts/validate-skill-flow.sh (validate-skill-flow) fails on unresolved tokens or un-allowlisted orphans; standalone leaves in scripts/skill-flow-standalone.txt
PMF Evidence Gate — Public docs (PRODUCT.md, README, launch artifacts) must promote .agents/ evidence to docs/evidence/<bead-id>/ via scripts/export-evidence.sh; scripts/check-pmf-evidence.sh is the gate (soc-m6v5.8)
Claim-Eval-Promote Policy — CEP policy overlay: 4-tier claim lifecycle (UNPROVEN/PILOT/NULL/PROVEN), curated registry at docs/contracts/claim-registry.yaml, additive regen from agentops:claim:* markers, drift gate + WARN-only PMF evidence gate in ao gate check (age-6sg)
Claim Registry (yaml) — Curated claim policy overlay: per-claim tier/surfaces/owner/evidence/eval-binding; additive regen from agentops:claim:* markers via scripts/regen-claim-registry.sh; drift-gated by claim.registry-drift (age-6sg)
Skill Domain Map — V0 DDD map assigning every shared skill to one explicit skill domain with ports, artifacts, and adapters
Registry as derived artifact — Design contract (soc-jbea, status:design): move registry.json out of version control to eliminate sibling-PR conflict cascade (40-50% of waste in the 2026-05-20 PR-cleanup session per Council 220-240). Same pattern for skills-codex/.agentops-manifest.json and skills-codex/*/.agentops-generated.json. Implementation deferred to soc-jbea.1 through soc-jbea.7.
SKU Capability Catalog — registry.json schema_version 2: the generated SKU catalog (skills + CLI commands + gates + reference-impls) as a 4th derived JOIN projection. Defines the SKU entry schema, the drives_commands skill↔command join key (derived from skill bodies), status derivation, and the validate-sku-catalog-drift gate's three checks (drift + linkage-integrity + BC/loop-move coverage). Retires the bogus "163 cli_commands" count (ag-cbm).
Skill Ports and Adapters — V0 skill-boundary vocabulary for inbound ports, outbound ports, adapters, context packets, and guard surfaces
Skill Lease Audit — V0 lease-on-life audit classifying all shared skills as keep, merge, split, retire, or unknown
Repo Execution Profile — Repo-local bootstrap, validation, tracker, and done-criteria contract for autonomous orchestration
Repo Execution Profile Example — Concrete repository execution profile used by local autonomous orchestration
Autodev Program Contract — Repo-local operational contract for bounded autonomous development
AO / MTO Seam — Reduction contract separating the lean AO image from the outer MTO factory and routing RELOCATE surfaces through MTO, vendor-adapter, or defer-load-bearing seams
.agents/ Write Surfaces — Catalogued top-level subdirs that production code writes under .agents/, gated by scripts/check-agents-write-surfaces.sh
Goal Design Artifacts — Two-artifact contract for .agents/goal-design/<slug>/intent.md and driver.md, including schemas, digest integrity, validation, lifecycle, and route-back rules
CI Path-Filter / Gate-Target Coverage Audit — Repo-wide audit (ag-g9ex) of the invariant "a CI gate that reads a file must be triggered by a path-filter covering that file" (the #634/#638 class). Findings table for every file-reading gate in validate.yml, the two gaps fixed (AGENTS tiered-split siblings; wiring-closure GOALS.md de-wire), and the --admin self-merge governance policy. Guarded by tests/scripts/test-pathfilter-gate-coverage.bats.
Update Principles Contract — Five operator-exemplar properties every commit must demonstrate (single concern, drift-blocking test, sibling citation, fitness delta, clean branch point); sourced from commit 1b9d139c
Ubiquitous Language Contract — Canonical names per bounded context (BC1 Corpus, BC2 Validation, BC3 Loop, BC4 Factory, BC5 Runtime) for the 5 ranked drifts (Gate/Check, Cycle/Loop, Claim/Evidence, Skill/Pattern/Practice, Session); rename schedule bound to soc-5yuy children
BC1 Corpus Ports Contract — Core BC1 corpus ports scaffolded under cli/internal/ports/; semantics cheat-sheet, adapter triplet pattern, soc-pm5t wire-up order
BC Ports Inventory — Roster of all 20 BC ports with per-port adapter contracts, the universal triplet construction pattern, and per-BC wire-up order.
Orchestration Ports — OrchestrationPort dual-runtime selection seam: the 3-category model (Claude Workflow / NTM swarm / plain skill), the NTM → Claude-native → beads-floor degradation ladder, AGENTOPS_ORCHESTRATION=off opt-out, capability detection via ntm --robot-capabilities, output-contract parity (orchestration-result.v1), and the two-ladders distinction. Paired schemas schemas/orchestration-backend.v1.schema.json + schemas/orchestration-result.v1.schema.json.
Orchestration Profiles (yaml) — SOT for portable NTM worker and pawl-review role profiles plus structured spawn arguments; drift-gated against skills/agent-native/SKILL.md and skills/pawl-review/SKILL.md via scripts/check-orchestration-profiles.sh
Orchestration Tools (yaml) — Tool matrix contract for ao orchestrate tools; drift-gated via scripts/check-orchestration-contracts.sh
Orchestration Instrument Schema — JSON schema for ao orchestrate preflight/verify/tools/route/status JSON output (orchestration-instrument.v1)
Orchestration Backend Selection Contract — wire shape of one OrchestrationPort selection decision (chosen/reason/considered/opt_out/pin); pairs schemas/orchestration-backend.v1.schema.json for structural-floor validation.
Orchestration Result Parity Contract — the output-contract parity shape every tier (NTM/Claude/beads) must emit; pairs schemas/orchestration-result.v1.schema.json; enforced by the degradation-conformance test.
Remote Compute Contract — Product-neutral RemoteTarget, RemoteSession, command ledger, recovery, and GasCity-first remote execution contract
Rubric Schema — JSON Schema for rubric files (outcome rubric → target → grader → retry loop)
Worker Spec Schema — JSON Schema for per-worker model/tool/prompt isolation specs
Repo Execution Profile Schema — Machine-readable schema for repo execution profiles
RPI Run Registry — RPI run registry specification
Eval Environment Contract — Evaluation suite, run, scorecard, baseline, canary, and holdout contract
Eval Baseline-A/B Contract — ao eval run --baseline-mode semantics, DeltaScorecard schema, hook-suppression scope
Context Usefulness Eval Contract — Wave 0 deterministic context_off versus context_on evaluation, scorecard fields, hook-preservation boundaries
Eval Verdict Pipeline Contract — Verdict compiler pipeline from eval run manifests to learning utility and retirement signals
Outcomes Rubric Projection Contract — Holdout-safe projection of the locked eval substrate into an Outcomes-style grading payload (schemas/outcomes-rubric.v1.schema.json); additionalProperties:false at every level forbids target/ground_truth/expected_output (Managed Agents are not ZDR); validator scripts/validate-outcomes-rubric.sh + Go schema↔struct drift guard (ag-hguuf)
Agent-Native Mechanism Contract — Decision doc mapping each old-hook intent (orientation, standards, scope guard, commit-review, holdout-isolation) to its hookless equivalent (skill + ao subcommand + gate job) across both runtimes; retained with historical substrate notes
Retrieval Comparison Contract — Deterministic search-eval backend comparison, promotion thresholds, optional rerank behavior, and deferred vector/graph-store policy
Release Readiness Contract — 8/10 release readiness score, SIL/VIL/HIL evidence, artifact manifest requirements, and HIL waiver policy
MemRL Policy Schema — Machine-readable retry/escalation policy profile for memory-reinforcement feedback loops
MemRL Policy Profile Example — Example deterministic MemRL retry/escalation policy profile
Eval Workbench — Known-good fixture project (Go CLI, Python FastAPI, DevOps scripts) with 12 behavioral eval tasks and scoring scripts
Eval Suite Schema — JSON Schema for public canary and private holdout evaluation suites
Eval Run Schema — JSON Schema for evaluation run records and scorecards
Remote Compute Target Schema — JSON Schema for product-neutral GasCity-backed remote compute targets
Remote Session Event Schema — JSON Schema for remote session event and idempotent command ledger records
Next-Work Queue Schema — Contract for .agents/rpi/next-work.jsonl
RPI Phase Result Schema — Machine-readable schema for RPI phase results
RPI C2 Events Schema — Machine-readable schema for per-run .agents/rpi/runs/<run-id>/events.jsonl
RPI C2 Commands Schema — Machine-readable schema for per-run .agents/rpi/runs/<run-id>/commands.jsonl
Swarm Worker Result Schema — Machine-readable schema for .agents/swarm/results/<task-id>.json worker artifacts (strict completion contract)
Swarm Evidence Contract — Permissive shape covering all historical swarm result files; enforced by scripts/validate-swarm-evidence.sh
Swarm Evidence Schema — JSON Schema for the permissive swarm evidence shape
Multi-Runtime Tier Charter — Explicit Tier S/I/E declaration: Tier S structural blocks CI; Tier E live execution is opt-in (Directive D1)
v2.39.0 README claim evidence manifest — Maps each AOP-CLAIM-README-* marker to its evidence file and verification gate (PG4)
AgentOps 3.0 PMF Scenario — evidence bundle — Single-day autonomous /evolve drain record: 11 P1 closures, 11 commits, friction modes, durable artifacts (PG2)
Scope Escape Report — Structured template for agent scope-escape reporting
Dream Report Contract — Canonical summary.json and summary.md schema for Dream outputs
Dreaming/Memory Writers Characterization — Spike (ag-cj8mk): the three foreign Dreaming/memory writers (Anthropic Managed-Agents Dreaming /v1/dreams→memory store, OpenClaw memory-wiki indexer, local gc-dream/T3 synthesis), their output shapes/destinations, the normalized .agents/learnings/*.md target via ao corpus capture, the NOT-ZDR holdout/PII constraint enforced by the ag-onf37 leak guard, and GO on the Claude-side REST pull feeder
dispatch-checklist.md — Standard references for agent dispatch prompts
Headless Invocation Standards — Required flags, tool allowlists, and timeout strategy for non-interactive Claude/Codex execution
Codex Skill API Contract — Source of truth for Codex runtime skill structure, frontmatter, discovery paths, and multi-agent primitives
Context Assembly Interface — Interface contract for adaptive context assembly and mechanical token budgeting
Session Intelligence Trust Model — Artifact eligibility contract for runtime context assembly, explainability, and startup suppression rules
Finding Registry Contract — Canonical intake-ledger contract for reusable findings in .agents/findings/registry.jsonl
Finding Registry Schema — Machine-readable schema for the finding intake ledger
Finding Artifact Schema — Machine-readable schema for promoted finding artifacts under .agents/findings/*.md
Finding Item Schema — Canonical finding-item schema for validation skill outputs (compatible subset of finding-artifact)
Finding Compiler Contract — V2 promotion ladder, executable constraint index contract, and lifecycle rules for turning findings into prevention artifacts

Migration Trackers

resolve-project-dir.md — os.Getwd() → resolveProjectDir() migration status