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
# 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/` ](https://github.com/boshu2/agentops/tree/main/schemas ) — user-facing manifests and artifacts versioned with `.v1.schema.json`
- [`lib/schemas/` ](https://github.com/boshu2/agentops/tree/main/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/` ](contracts/index.md ) and is indexed from [`contracts/index.md` ](contracts/index.md ).
## Manifests
Manifests describe installable units — skills, plugins, marketplace entries, hook bindings.
| Schema | Purpose |
|--------|---------|
| [`skill-frontmatter.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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` ](https://github.com/boshu2/agentops/blob/main/schemas/plugin-manifest.v1.schema.json ) | Claude Code plugin manifest (`plugin.json` ). |
| [`codex-plugin-manifest.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/codex-plugin-manifest.v1.schema.json ) | Codex plugin manifest — thin variant used by the Codex marketplace. |
| [`codex-marketplace.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/codex-marketplace.v1.schema.json ) | Top-level marketplace index consumed by `claude plugin marketplace add` . |
feat(hookless)!: remove all hooks — skills + CLI only (soc-57b7f #remove-all-hooks) (#511)
## What
AgentOps 3.0 goes **fully hookless**. This removes the entire hook
product surface — the product is now skills + the `ao` CLI with **zero
hooks**. CI is the authoritative gate.
## Deleted
- `hooks/` — 46 hook scripts + `hooks.json` + examples (whole directory)
- `cli/embedded/hooks/` + embedded `hooks.json` +
`embedded/lib/hook-helpers.sh`
- `lib/hook-helpers.sh`
- `ao hooks` CLI command: `cli/cmd/ao/hooks.go`, `hooks_run.go` + 5 hook
test files; `cli/internal/bridge/hooks.go`;
`cli/internal/doctor/fix_hooks.go` + test
- Codex hook manifest (`hooks/codex-hooks.json`) + handler/audit scripts
(`scripts/audit-codex-hooks.sh`, `install-dev-hooks.sh`,
`test-hooks-output.sh`, `test-codex-hookless-lifecycle.sh`,
`test-hookless-rpi-phased.sh`)
- Hook lease surface: `docs/contracts/hook-lease-*`,
`schemas/hook-lease.v1.schema.json`,
`scripts/check-hook-lease-inventory.sh`,
`check-hook-port-replacements.sh`, `generate-hook-lease-inventory.py`
- Hook docs: `docs/HOOKS.md`, `cli/docs/HOOKS.md`,
`docs/architecture/hook-noise-audit.md`,
`docs/contracts/hook-runtime-contract.md`
- `tests/hooks/` (whole dir) + hook test scripts; 5 hook eval suites +
fixtures
## CI gates removed
`hook-preflight`, `validate-hooks-doc-parity`, `hook-output-schema-lint`
(+ scripts/bats), the hook eval suites, the `test-runtime-codex-smoke` /
`test-codex-native-install` / `test-codex-plugin-install` hook-handler
assertions, the cli-integration hook-lifecycle steps, the bats
`tests/hooks/*` glob + orphan-hooks audit, and the `--with-hooks`
install path. `embedded-sync` now validates only lib/skills. Both
summary `needs:` lists + the summary echo +
`docs/contracts/ci-jobs.yaml` updated; `validate-ci-policy-parity`
passes (66 rows). `.codex-plugin/plugin.json` drops the "Hooks"
capability.
## Load-bearing PRESERVED (reported, not forced)
- **`cli/cmd/ao/codex_runtime.go`** — the codex runtime *lifecycle
profile* (`HookCapable`/`HookConfigured` detection) is a
runtime-capability abstraction used by 6 `validate-codex-*` CI gates,
distinct from the hook product. Deleting it is a separate refactor.
- **`hooks-authoring` skill** + `schemas/hooks-manifest.v1.schema.json`
— reframed as an opt-in "author your own hooks" guide. Deleting the
skill cascades into catalog/domain-map/dispositions/context-map golden
files (skill-count sync), out of scope for the hook-product removal.
- **`scripts/pre-push-gate.sh`** — retired local gate (not in CI);
self-skips deleted hook scripts via `[[ -x ]]` guards; its 55 bats tests
still pass.
- Domain-enforcement audit keeps the `enforced`-mode schema for
backward-compatible JSON readers, but the hookless resolver only returns
`audited`/`unavailable`.
## Verification
`go build` / `go vet` clean; `go test ./...` = **11849 passed, 0
failed** (68 pkgs). gofmt clean on all touched files. Green: registry
`--check` (0 hooks), `regen-codex-hashes --check`,
`validate-ci-policy-parity`, `check-wiring-closure`,
`validate-embedded-sync`, `validate-manifests`, `validate-agents-split`,
`doc-release` (0 broken links), `generate-cli-reference --check`,
`heal.sh --strict`, codex/claude/plugin smoke tests, baseline-audit (0
stale). Diff: 231 files, +354 / −39803.
Closes-scenario: soc-57b7f#remove-all-hooks
Bounded-context: BC5-Runtime
Evidence: .github/workflows/validate.yml
2026-05-24 11:19:37 -04:00
| [`hooks-manifest.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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` ](https://github.com/boshu2/agentops/blob/main/skills/hooks-authoring/SKILL.md ) skill if you choose to author your own. |
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
## Runtime artifacts
These describe data written and consumed at runtime — handoffs between sessions, evidence for closure, quality signals.
| Schema | Purpose |
|--------|---------|
2026-07-09 11:46:58 -04:00
| [`handoff.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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. |
docs(hookless): close cold-start orientation drift (soc-qh2g1 #cold-start-orientation-coherence) (#795)
## Summary
Close the hookless cold-start orientation gap for `soc-qh2g1` by making
the live startup docs and skills point at explicit `ao session
bootstrap` plus pulled context (`ao inject` / `ao lookup`) instead of
hidden SessionStart behavior.
## Changes
- Reframes live docs that still implied automatic startup/handoff
injection to the hookless explicit-command path.
- Updates source and Codex skill mirrors for `quickstart`, `inject`,
`using-agentops`, `recover`, `bug-hunt`, and `session-bootstrap`.
- Expands the cold-start and docs drift gates so `SessionStart hook`,
`startup hooks`, and `auto-inject ... hook` promises fail unless
explicitly hedged as opt-in, removed, or historical.
- Refreshes scoped Codex skill hashes for the touched mirrors.
## Test plan
- [x] `bash scripts/check-hookless-cold-start.sh`
- [x] `bash scripts/check-doc-hooks-drift.sh`
- [x] `bats tests/scripts/check-hookless-cold-start.bats
tests/scripts/check-doc-hooks-drift.bats`
- [x] `shellcheck scripts/check-hookless-cold-start.sh
scripts/check-doc-hooks-drift.sh`
- [x] `bash scripts/regen-codex-hashes.sh --check --only
session-bootstrap,quickstart,inject,using-agentops,recover,bug-hunt`
- [x] `bash scripts/validate-codex-generated-artifacts.sh`
- [x] `bash scripts/validate-codex-lifecycle-guards.sh`
- [x] `bash scripts/validate-agents-split.sh`
- [x] `git diff --check`
- [x] `bash scripts/validate-skill-runtime-parity.sh`
- [x] `bash scripts/lint-codex-native.sh`
Closes-scenario: soc-qh2g1#cold-start-orientation-coherence
Bounded-context: BC1-Corpus
Evidence: scripts/check-hookless-cold-start.sh
2026-06-06 11:23:56 -04:00
| [`memory-packet.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/memory-packet.v1.schema.json ) | Boundary-memory packet for explicit lifecycle commands and optional externally-authored hooks. |
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
| [`evidence-only-closure.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/evidence-only-closure.v1.schema.json ) | Proof artifact for issue closures that rely on validation or policy evidence instead of a code delta. |
2026-07-09 09:38:11 -04:00
| [`goal-design-intent.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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` ](contracts/goal-design-artifacts.md ). |
| [`goal-design-driver.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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` ](contracts/goal-design-artifacts.md ). |
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
| [`session-quality-signal.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/session-quality-signal.v1.schema.json ) | Per-session quality signal rolled up into the knowledge flywheel. |
| [`scenario.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/scenario.v1.schema.json ) | Behavioral validation scenarios stored in `.agents/holdout/` . |
2026-04-24 21:56:40 -04:00
| [`eval-suite.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/eval-suite.v1.schema.json ) | Public canary and private holdout evaluation suite manifests. See [`Eval Environment` ](contracts/eval-environment.md ). |
| [`eval-run.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/eval-run.v1.schema.json ) | Evaluation run records, scorecards, baseline comparisons, runtime hygiene, and artifacts. See [`Eval Environment` ](contracts/eval-environment.md ). |
2026-05-02 17:16:00 -04:00
| [`release-readiness.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/release-readiness.v1.schema.json ) | Release readiness score artifact with SIL/VIL/HIL evidence and waiver state. See [`Release Readiness` ](contracts/release-readiness.md ). |
docs(substrate): reconcile doctrine — skill-dispatch + drop Gas City reference (ag-88y5 #docs-skills-dispatch-reframe) (#696)
## What
Two bounded doctrine-reconciliation slices (one coherent arc):
**ag-88y5** — the out-of-session dispatch unit is the `/rpi`·`/evolve`
**skill**, not the `ao rpi`/`ao evolve` CLI. Per the 3.0
skills-are-the-runtime thesis (using-ntm #693 already frames it this
way), re-narrate the **live** doctrine surfaces so the substrate spawns
an agent that *runs the /rpi skill* over a bead:
- docs/3.0.md, docs/architecture/canonical-loop-model.md,
docs/runbooks/nightly-evolution.md
- skills/using-agentops, skills/agent-native,
skills/domain/references/factory.md
Historical surfaces (MIGRATION-3.0, ADR-0009, release notes) +
CLI-reference left as-is; the actual `ao rpi`/`ao evolve` CLI removal is
the **ag-iowf** epic (live automation callers — overnight-evolve,
release-smoke — must migrate first).
**ag-ogp5** — drop the 4 docs still asserting Gas City as THE reference
substrate → NTM+MCP+managed-agents:
- docs/ARCHITECTURE.md, docs/SCHEMAS.md,
docs/contracts/agents-write-surfaces.md,
docs/patterns/completion-notifications.md (Pattern C)
The ~37 historical/illustrative GC refs are intentionally retained (per
ag-ogp5 scope).
## Verification
regen-all --check, embedded-sync, heal --strict, registry-drift,
codex-rpi-contract, codex-artifacts --scope head — all green.
Closes-scenario: ag-88y5#docs-skills-dispatch-reframe
Bounded-context: BC4-Factory
Evidence: docs/3.0.md
2026-06-03 08:11:23 -04:00
| [`routing-policy.v1.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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). |
docs(destale): wave 2 + ratchet — all live docs off retired tech (age-docs-staleness-remediation-cko)
Completes the staleness epic. 42 P2/P3 files converged to current truth
(bd→br, gascity/gt-sling/mayor→NTM+Agent Mail, daemon→substrate, hooks→hookless,
CI-authoritative→push-to-main local Go gate); GLOSSARY's 18 dead skills/* links
repaired to ../skills/<name>/SKILL.md (19 links, 0 broken); contracts/runbooks
that freeze retired-system nouns bannered RETIRED/HISTORICAL rather than rewritten.
Adds the Arc-7 ratchet — scripts/check-docs-no-retired-tech.sh — which scans all
live docs (260) for retired-subsystem commands/phrases and fails on regression.
A doc opts out by carrying a RETIRED/HISTORICAL/SUPERSEDED banner (or being an
ADR / migration / upgrade / index doc), and lines that describe a removal are not
flagged. Running it caught 12 stale refs the deep-read sweep missed — a
"CI is the authoritative gate" cluster (agentops-brief, primitive-chains,
INCIDENT-RUNBOOK, knowledge-flywheel, philosophy, software-factory), stale
hook-smoke in release-e2e-checklist, and GasCity descriptors in
contracts/index + SCHEMAS + strategic-direction — now fixed. Gate: PASS.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 10:23:02 -04:00
| [`remote-compute-target.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/remote-compute-target.schema.json ) | Product-neutral remote compute target configuration (the GasCity backend was retired 2026-06-11). See [`Remote Compute` ](contracts/remote-compute.md ). |
2026-04-29 12:52:42 -04:00
| [`remote-session-event.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/remote-session-event.schema.json ) | Remote session events and idempotent command delivery records. See [`Remote Compute` ](contracts/remote-compute.md ). |
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
| [`swarm-evidence.schema.json` ](https://github.com/boshu2/agentops/blob/main/schemas/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` ](contracts/swarm-worker-result.schema.json ). |
| [`finding.json` ](https://github.com/boshu2/agentops/blob/main/schemas/finding.json ) | Canonical finding-item schema for validation skills. Compatible subset of [`contracts/finding-artifact.schema.json` ](contracts/finding-artifact.schema.json ). |
## Internal runtime contracts
Used by the `ao` CLI team runner and worker pipeline. See [`reference.md` ](reference.md ) for the team execution model.
| Schema | Purpose |
|--------|---------|
| [`lib/schemas/team-spec.json` ](https://github.com/boshu2/agentops/blob/main/lib/schemas/team-spec.json ) | Team specification consumed by `lib/scripts/team-runner.sh` when launching parallel workers. |
| [`lib/schemas/worker-output.json` ](https://github.com/boshu2/agentops/blob/main/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/` ](contracts/index.md ) (narrative + schema paired in one directory):
- [`contracts/repo-execution-profile.schema.json` ](contracts/repo-execution-profile.schema.json ) — repo bootstrap/validation/tracker/done-criteria for autonomous runs
- [`contracts/rpi-phase-result.schema.json` ](contracts/rpi-phase-result.schema.json ) — RPI phase result artifacts
- [`contracts/rpi-c2-events.schema.json` ](contracts/rpi-c2-events.schema.json ) / [`contracts/rpi-c2-commands.schema.json` ](contracts/rpi-c2-commands.schema.json ) — per-run events/commands JSONL
- [`contracts/next-work.schema.md` ](contracts/next-work.schema.md ) — `.agents/rpi/next-work.jsonl` shape
- [`contracts/swarm-worker-result.schema.json` ](contracts/swarm-worker-result.schema.json ) — strict completion contract for swarm workers
- [`contracts/finding-artifact.schema.json` ](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:
``` bash
# Validate skill frontmatter across all skills
scripts/validate-skills.sh
feat(ci): gate live-hooks reintroduction in docs/ (ag-rryf #doc-hooks-drift-gate) (#713)
## What
Adds `scripts/check-doc-hooks-drift.sh` — a CI regression guard that
fails when a **live-facing** doc reintroduces a live hooks runtime after
the 3.0 hookless teardown:
- `hooks/hooks.json` (retired manifest), a `hooks/<name>.sh` runtime
path,
- `ao hooks` (not a registered command — verified absent from
`cli/cmd/ao/`),
- a bare `session-{start,end,autostart}*.sh` hook-file ref
…unless the **same line** hedges it as hookless / opt-in / historical /
removed / a git-hook. Companion to `sync-skill-counts.sh` (skill-count
drift) and `check-hookless-cold-start.sh` (fixed-list cold-start gate).
## Scope (and why the exclusions)
`docs/` **minus** surfaces that legitimately/archivally name hooks:
- **archival history** — `CHANGELOG.md`, `releases/`, `learnings/`,
`plans/`, `adr/`, `convergence/`, `sovereignty-proof/` (document the
past / the removal itself)
- **opt-in subsystem** — `contracts/` (hooks-authoring opt-in specs),
`runbooks/` (diagnostic enumeration), `code-map/` (point-in-time audits)
The gate keeps the onboarding / operator / architecture narrative
hookless.
## Also: finishes the ag-t1ca residue the gate flags
The ag-t1ca de-hooking missed 8 live-facing lines (gate caught them);
each is reframed:
- stale `ao hooks` command/smoke refs → removed / `ao doctor`
(`cli-skills-map`, `UPGRADING`, `release-e2e-checklist`,
`contracts/release-readiness`)
- present-tense hooks-as-rules → CI gates (`strategic-direction`)
- hook-runtime mentions → `ao curate constrain` / opt-in framing
(`curation-pipeline`, `leverage-points`, `SCHEMAS` legacy-manifest
label, `workflows/session-lifecycle`)
## Verification
- `scripts/check-doc-hooks-drift.sh` → PASS on this branch (FAILed on
all 8 before the reframes)
- `tests/scripts/check-doc-hooks-drift.bats` → 8/8 (positive /
negative×3 / hedge×2 / exclusion / no-docs error)
- `shellcheck` clean · `markdownlint` 0 errors (9 docs) ·
`validate-cli-skills-map.sh` PASS · `generate-ci-jobs-table.sh --check`
PASS · existing `check-hookless-cold-start.sh` still green
- Wired into `validate.yml` lint/contracts (gated on docs/ci/shell
changes) + auto-run via the bats suite
Closes-scenario: ag-rryf#doc-hooks-drift-gate
Bounded-context: BC2-Validation
Evidence: scripts/check-doc-hooks-drift.sh
2026-06-03 22:38:26 -04:00
# 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
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
# Validate swarm evidence artifacts
scripts/validate-swarm-evidence.sh
2026-07-09 09:38:11 -04:00
# Validate a goal-design packet
scripts/check-goal-design-packet.sh .agents/goal-design/<slug>
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
```
CI enforces schema validity for everything shipped in a release — see [`CI-CD.md` ](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` ](UPGRADING.md ).
If you are adding a new schema, follow the conventions in [`CONTRIBUTING.md` ](CONTRIBUTING.md ) and link it from this page plus [`contracts/index.md` ](contracts/index.md ).
