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).
## Docs site — boshu2.github.io/agentops
- Replace Jekyll minima with MkDocs Material (slate dark palette default)
- Landing hero scoped to .landing-hero (no gradient bleed on inner pages)
- Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes
- Generate skill catalog + per-skill pages from skills/*/SKILL.md at build
- Generate CLI reference from cli/docs/ at build (fails build on missing source)
- Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py)
- Wire mkdocs build --strict into pre-push gate (Check 25a)
- Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages)
- README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp
- tests/docs/validate-links.sh patched to understand mkdocs-generated paths
## RPI orchestrator strict-delegation contract
- Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on.
- Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror)
- Forged learning with detection phrases + corrective actions (ao-inject-ready)
- Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0
- Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer
- Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized
- CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred
## fix(hooks): go-test-precommit skips when no Go files staged
- Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version
- Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged
- Applied to both hooks/ (source) and cli/embedded/hooks/ (synced)
Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Defines a tracked contract for swarm worker result files living under
.agents/swarm/results/<task>.json. These files were implicitly shaped
but never validated — misshapen packets could silently break crank
result ingestion.
- schemas/swarm-evidence.schema.json: JSON Schema. Required: task,
status, files_changed, notes. Optional: tests, gate, evidence,
before/after counters. additionalProperties=true permits task-specific
extensions.
- scripts/validate-swarm-evidence.sh: jq-based validator accepting a
file or directory. ajv fallback when available. Exit 0 pass, 1 fail.
- docs/contracts/swarm-evidence.md: human-readable contract doc with
example and schema link. Added to docs/INDEX.md catalog.
- scripts/pre-push-gate.sh: new section 26b ('swarm evidence schema')
invokes the validator on every push.
- scripts/check-contract-compatibility.sh: extended ref resolution to
also search schemas/ so docs/contracts/*.md can cite
schemas/*.schema.json without tripping the cataloguing check.
Consumes ag-yhr 'Implement executable swarm evidence schema validation'.
Create docs/skills-decision-tree.md as the single source of truth for
"which skill do I need?". Replace duplicate tables in harvest SKILL.md,
knowledge-activation SKILL.md, and skills-codex mirrors with a pointer
link. Add INDEX.md entry.
Four files used to carry the same table; future edits now go in one
place. Quickstart already surfaces the individual skills under its
GIT=false + GLOBAL_AGENTS=true branch, so it does not need the
expanded reference — it is the entry point, not the index.
Closes na-pmx1.7.
Five-month retrospective distilled into docs/philosophy.md (five validated
principles for building with coding agents) and a personal observations
section in the README. Links added to INDEX.md and README footer.
- docs/contracts/codex-skill-api.md: source of truth for Codex runtime
skill structure, frontmatter, discovery paths, multi-agent primitives
- scripts/validate-codex-api-conformance.sh: checks generated codex
skills against actual Codex API (baseline: 12 failures, 124 refs)
- Add contract to docs/INDEX.md
Wave 1 of ag-1rh (Skill Output Standardization):
- Add output_contract optional field to skill-frontmatter.v1.schema.json
- Add optional finding id field to verdict.json for cross-skill correlation
- Create schemas/finding.json as canonical finding-item schema
- Document output_contract in SKILL-API.md
- Add finding.json link to docs/INDEX.md
Add context: frontmatter blocks to 40 skills that were missing them,
bringing coverage from 13/52 to 52/52. Each skill gets a context
policy based on its behavior:
- Orchestration (crank, swarm, evolve): fork + exclude HISTORY + full intel
- Execution (bug-hunt, doc, complexity): fork + exclude HISTORY + topic intel
- Session (handoff, recover, status): inherit + no intel
- Background (push, ratchet, update): isolated + exclude all + no intel
- Knowledge (forge, athena, flywheel): fork + exclude TASK + full intel
- Contribute (pr-*): fork + exclude HISTORY + topic intel
- Cross-vendor (openai-docs, grafana): fork + exclude HISTORY/TASK + no intel
- Library/Meta (shared, standards): isolated + exclude all + no intel
- Product (product, readme, release): fork + exclude HISTORY + full intel
New docs/SKILL-API.md provides the definitive reference for all
frontmatter fields, context declaration semantics, and a quick-reference
table of all 52 skills with their policies.
Epic: ag-6e0
Contract-compatibility gate failed because docs/contracts/context-assembly-interface.md
was on disk but not catalogued in docs/INDEX.md. Athena-freshness gate failed because
defrag report was 27h old (max 26h). Both fixed — 17/17 goals now pass.
- Add bin/run-rpi-headless.sh: chains RPI phases as separate headless
Claude invocations, each invoking the actual skills (/research, /plan,
/crank, /vibe, /post-mortem) so the full skill chain executes
- Add docs/contracts/headless-invocation-standards.md: documents when to
use --dangerously-skip-permissions (skill chains) vs --allowedTools
(controlled prompts), timeout strategy, and session chaining
- Update test-helpers.sh: add --no-session-persistence, --max-budget-usd,
configurable ALLOWED_TOOLS env var (default: skip-permissions for tests)
- Update release-smoke-test.sh: add --no-session-persistence,
--max-budget-usd, scoped --allowedTools for fast test (no skill exec)
Key insight: skills chain skills — --allowedTools constrains the entire
session including tools used inside skill execution, so skill-invoking
workflows must use --dangerously-skip-permissions with timeout/budget
as the safety rails instead.
Replace hardcoded file list with dynamic checks:
- INDEX.md link resolution (all contracts/ refs verified)
- Bridge doc cross-reference verification
- Contract .md embedded schema reference resolution
- JSON schema/example validity (jq validation)
- Orphan detection (files on disk not in INDEX.md)
- Also catalogue rpi-run-registry and rpi-phase-result in INDEX.md
Declutter repo root — keep only AGENTS.md, CLAUDE.md, README.md, LICENSE,
GOALS.yaml, PRODUCT.md at top level. All cross-references updated across
README, .github templates, docs/, scripts/, skills/, and tests/.
Claude