Documentation Index¶

Master table of contents for AgentOps documentation.

Getting Started¶

README — Project overview and quick start
Behavioral Discipline — Before/after examples of good coding-agent behavior
Newcomer Guide — Fast orientation to repo structure, architecture, and contribution path
FAQ — Comparisons, limitations, subagent nesting, uninstall
CONTRIBUTING — How to contribute
Create Your First Skill — Fast path for authoring a first skill without tripping CI
AGENTS.md — Local agent instructions for this repo
Changelog — Release history
Security — Vulnerability reporting

Architecture¶

How It Works — Brownian Ratchet, Ralph Wiggum Pattern, agent backends, hooks, context windowing
Software Factory Surface — Explicit automation surface for briefings, RPI flows, and operator-controlled closeout
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
Primitive Chains — Audited primitive set, lifecycle chains, and terminology drift ledger
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
Skill Tiers — Taxonomy and dependency graph
Claude Code Skills Docs — Official Claude Code skills documentation (upstream)

Workflows¶

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
Context Lifecycle Contract — Internal proof contract behind the public bookkeeping, validation, primitives, and flows story
Knowledge Flywheel — How every session makes the next one smarter
The Science — Research behind knowledge decay and compounding
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
Strategic Direction — Product strategy and roadmap
Leverage Points — Meadows-inspired system intervention points

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¶

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
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

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)

Templates¶

Templates Overview — Templates index
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
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
Glossary — Definitions of domain-specific terms (Beads, Brownian Ratchet, RPI, etc.)
CLI Reference — Complete ao command reference
CLI ↔ Skills/Hooks Map — Which commands are called by which skills and hooks
Reference — Deep documentation and pipeline details
Releasing — Release process for ao CLI and plugin
Environment Variables — All configuration variables with defaults and precedence
Skill Router — Which skill to use for which task
Troubleshooting — Common issues and quick fixes
Incident Runbook — Operational runbook for incidents and recovery
AO Command Customization Matrix — External command dependencies and customization policy tiers
Contracts Index — Landing page for all inter-component contracts
Repo Execution Profile — Repo-local bootstrap, validation, tracker, and done-criteria contract for autonomous orchestration
Autodev Program Contract — Repo-local operational contract for bounded autonomous development
Repo Execution Profile Schema — Machine-readable schema for repo execution profiles
RPI Run Registry — RPI run registry specification
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
Hook Runtime Contract — Canonical event mapping across Claude, Codex, and manual runtimes
Scope Escape Report — Structured template for agent scope-escape reporting
Dream Run Contract — Process model, locking, keep-awake, and artifact floor for private overnight runs
Dream Report Contract — Canonical summary.json and summary.md schema for Dream outputs
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