boshu2__agentops/docs/INDEX.md

Documentation Index

Master table of contents for AgentOps documentation.

Getting Started

Pick your path: evaluating the product → README then FAQ. Installing for real work → Getting Started landing then Create Your First Skill. Orienting in the codebase as a contributor → Newcomer Guide then CONTRIBUTING. Upgrading from an older version → Upgrading.

• README — Project overview and quick start
• Getting Started — Install + first command landing page
• 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
• Upgrading — Version-to-version migration notes and breaking changes
• 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 (generated from source)
• Hooks Reference — Lifecycle events, what each hook does, how to customize
• CLI ↔ Skills/Hooks Map — Which commands are called by which skills and hooks
• Reference — Pipeline stages, execution-model table, and skill-selection matrix (deep-dive companion to SKILLS.md)
• Releasing — Release process for ao CLI and plugin
• Environment Variables — All configuration variables with defaults and precedence
• Schemas — JSON Schemas for manifests, runtime artifacts, and internal runtime contracts
• 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