Schemas

AgentOps exposes JSON Schemas for every inter-component contract: installable manifests, runtime artifacts, and skill frontmatter. This page catalogs them and points to the right file when you need to validate or extend a contract.

Schemas live in two places. Both are source of truth:

• schemas/ — user-facing manifests and artifacts versioned with .v1.schema.json
• lib/schemas/ — internal runtime contracts used by the ao CLI and swarm runners

Narrative documentation of the contracts (who writes and reads each artifact) lives under contracts/ and is indexed from contracts/index.md.

Manifests

Manifests describe installable units — skills, plugins, marketplace entries, hook bindings.

Schema	Purpose
skill-frontmatter.v1.schema.json	YAML frontmatter block at the top of every SKILL.md. Validated by heal.sh --strict and CI.
plugin-manifest.v1.schema.json	Claude Code plugin manifest (plugin.json).
codex-plugin-manifest.v1.schema.json	Codex plugin manifest — thin variant used by the Codex marketplace.
codex-marketplace.v1.schema.json	Top-level marketplace index consumed by claude plugin marketplace add.
hooks-manifest.v1.schema.json	Legacy schema for an optional, externally-authored hooks manifest. AgentOps 3.0 ships hookless by default — see the hooks-authoring skill if you choose to author your own.

Runtime artifacts

These describe data written and consumed at runtime — handoffs between sessions, evidence for closure, quality signals.

Schema	Purpose
handoff.v1.schema.json	Session-boundary handoff artifact written by ao session handoff, pulled explicitly by ao session bootstrap / ao inject, or consumed by opt-in lifecycle hooks.
memory-packet.v1.schema.json	Boundary-memory packet for explicit lifecycle commands and optional externally-authored hooks.
evidence-only-closure.v1.schema.json	Proof artifact for issue closures that rely on validation or policy evidence instead of a code delta.
goal-design-intent.v1.schema.json	YAML frontmatter for .agents/goal-design/<slug>/intent.md, the human-shaped goal-design source of truth. See Goal Design Artifacts.
goal-design-driver.v1.schema.json	YAML frontmatter for .agents/goal-design/<slug>/driver.md, including loop routing, candidate beads, route-back rules, and intent digest integrity. See Goal Design Artifacts.
session-quality-signal.v1.schema.json	Per-session quality signal rolled up into the knowledge flywheel.
scenario.v1.schema.json	Behavioral validation scenarios stored in .agents/holdout/.
eval-suite.v1.schema.json	Public canary and private holdout evaluation suite manifests. See Eval Environment.
eval-run.v1.schema.json	Evaluation run records, scorecards, baseline comparisons, runtime hygiene, and artifacts. See Eval Environment.
release-readiness.v1.schema.json	Release readiness score artifact with SIL/VIL/HIL evidence and waiver state. See Release Readiness.
routing-policy.v1.schema.json	Historical model/provider/runtime lane policy schema. The companion daemon routing-policy contract was removed with the daemon in 3.0; out-of-session routing is now the substrate's concern (an NTM swarm / MCP / managed-agents — AgentOps adopts, does not own).
remote-compute-target.schema.json	Product-neutral remote compute target configuration (the GasCity backend was retired 2026-06-11). See Remote Compute.
remote-session-event.schema.json	Remote session events and idempotent command delivery records. See Remote Compute.
swarm-evidence.schema.json	Permissive shape for files written by swarm workers to .agents/swarm/results/<task>.json. Companion strict schema: contracts/swarm-worker-result.schema.json.
finding.json	Canonical finding-item schema for validation skills. Compatible subset of contracts/finding-artifact.schema.json.

Internal runtime contracts

Used by the ao CLI team runner and worker pipeline. See reference.md for the team execution model.

Schema	Purpose
lib/schemas/team-spec.json	Team specification consumed by lib/scripts/team-runner.sh when launching parallel workers.
lib/schemas/worker-output.json	Worker artifact written by Codex and Claude workers; watched by watch-{codex,claude}-stream.sh.

Related contracts

Machine-readable schemas that live under contracts/ (narrative + schema paired in one directory):

• contracts/repo-execution-profile.schema.json — repo bootstrap/validation/tracker/done-criteria for autonomous runs
• contracts/rpi-phase-result.schema.json — RPI phase result artifacts
• contracts/rpi-c2-events.schema.json / contracts/rpi-c2-commands.schema.json — per-run events/commands JSONL
• contracts/next-work.schema.md — .agents/rpi/next-work.jsonl shape
• contracts/swarm-worker-result.schema.json — strict completion contract for swarm workers
• contracts/finding-artifact.schema.json — full finding-artifact schema

Validating against a schema

Most schemas follow JSON Schema Draft 2020-12. Any compatible validator will work. Inside this repo:

# Validate skill frontmatter across all skills
scripts/validate-skills.sh

# Validate the legacy hooks manifest (opt-in only — AgentOps 3.0 ships zero
# hooks; you only have one if you authored it via the hooks-authoring skill)
jq -e . hooks/hooks.json           # legacy/opt-in manifest, if present

# Validate swarm evidence artifacts
scripts/validate-swarm-evidence.sh

# Validate a goal-design packet
scripts/check-goal-design-packet.sh .agents/goal-design/<slug>

CI enforces schema validity for everything shipped in a release — see CI-CD.md.

Versioning

Schemas are versioned in the filename (.v1.schema.json). Breaking changes bump the version and publish a new file; the previous version stays in place until deprecation is announced in UPGRADING.md.

If you are adding a new schema, follow the conventions in CONTRIBUTING.md and link it from this page plus contracts/index.md.