mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00

Files

T

Claude c4166a5c51 docs: fix broken CLI links, add HOOKS/SCHEMAS/UPGRADING pages, expand GLOSSARY

Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.

Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
  the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
  Replace with the canonical github URL so both mkdocs and raw-GitHub
  readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
  router so evaluators, installers, contributors, and upgraders don't
  have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
  orphaned) and add an "Install verification" block pointing at ao doctor.

New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
  install/uninstall, customization env vars, and common failure modes,
  pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
  lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
  contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
  Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
  --no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
  swarm-evidence schema enforcement, and pre-mortem gate tightening.

Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
  Compile, Context Window, Discovery, Dream/Overnight Run alias,
  Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
  go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
  an easily-missed sentence to a bold callout with CI-failure rationale.

mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.

Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
  single remaining preexisting warning about index.md is out of scope).

2026-04-22 05:01:02 +00:00

6.2 KiB

Raw Permalink Blame History

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`	Schema for `hooks/hooks.json`. See `HOOKS.md`.

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 handoff`, read by the `SessionStart` hook.
`memory-packet.v1.schema.json`	Boundary-memory packet emitted by lifecycle hooks for cross-session continuity.
`evidence-only-closure.v1.schema.json`	Proof artifact for issue closures that rely on validation or policy evidence instead of a code delta.
`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/`.
`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`.

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 hooks manifest
jq -e . hooks/hooks.json           # well-formed JSON
ao hooks show --validate           # schema-aware check

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

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.

6.2 KiB Raw Permalink Blame History