using-agentops

AgentOps Operating Model

AgentOps is the operational layer for coding agents.

Publicly, it gives you four things:

• Bookkeeping — captured learnings, findings, and reusable context
• Validation — plan and code review before work ships
• Primitives — single skills, hooks, and CLI surfaces
• Flows — named compositions like $research, $validation, and $rpi

Technically, AgentOps acts as a context compiler: raw session signal becomes reusable knowledge, compiled prevention, and better next work.

Core Flow: RPI

Research → Plan → Implement → Validate
    ↑                            │
    └──── Knowledge Flywheel ────┘

Research Phase

$research <topic>      # Deep codebase exploration
ao search "<query>"    # Search existing knowledge
ao search "<query>" --cite retrieved  # Record adoption when a search result is reused
ao lookup <id>         # Pull full content of specific learning
ao lookup --query "x"  # Search knowledge by relevance

Output: .agents/research/<topic>.md

Plan Phase

$pre-mortem <spec>     # Simulate failures (error/rescue map, scope modes, prediction tracking)
$plan <goal>           # Decompose into trackable issues

Output: Beads issues with dependencies

Implement Phase

$implement <issue>     # Single issue execution
$crank <epic>          # Autonomous epic loop (uses swarm for waves)
$swarm                 # Parallel execution (fresh context per agent)

Output: Code changes, tests, documentation

Validate Phase

$vibe [target]         # Code validation (finding classification + suppression + domain checklists)
$post-mortem           # Validation + streak tracking + prediction accuracy + retro history
$retro                 # Quick-capture a single learning

Output: .agents/learnings/, .agents/patterns/

Phase-to-Skill Mapping

| Phase | Primary Skill | Supporting Skills | |-------|---------------|-------------------| | Discovery | $discovery | $brainstorm, $research, $plan, $pre-mortem | | Implement | $crank | $implement (single issue), $swarm (parallel execution) | | Validate | $validation | $vibe, $post-mortem, $retro, $forge |

Choosing the skill:

• Use $implement for single issue execution. Now defaults to TDD-first — writes failing tests before implementing. Skip with --no-tdd.
• Use $crank for autonomous epic execution (loops waves via swarm until done). Auto-generates file-ownership maps to prevent worker conflicts.
• Use $discovery for the discovery phase only (brainstorm → search → research → plan → pre-mortem).
• Use $validation for the validation phase only (vibe → post-mortem → retro → forge).
• Use $rpi for full lifecycle — delegates to $discovery → $crank → $validation.
• Use $ratchet to gate/record progress through RPI.

Start Here (12 starters)

These are the skills every user needs first. Everything else is available when you need it.

| Skill | Purpose | |-------|---------| | $quickstart | Guided onboarding — run this first | | $research | Deep codebase exploration | | $council | Multi-model consensus review + finding auto-extraction | | $vibe | Code validation (classification + suppression + domain checklists) | | $rpi | Full RPI lifecycle orchestrator ($discovery → $crank → $validation) | | $implement | Execute single issue | | $retro --quick | Quick-capture a single learning into the flywheel | | $status | Single-screen dashboard of current work and suggested next action | | $goals | Maintain GOALS.yaml fitness specification | | $push | Atomic test-commit-push workflow | | $flywheel | Knowledge flywheel health monitoring (σ×ρ > δ/100) |

Advanced Skills (when you need them)

| Skill | Purpose | |-------|---------| | $compile | Active knowledge intelligence — Mine → Grow → Defrag cycle | | $knowledge-activation | Operationalize a mature .agents corpus into beliefs, playbooks, briefings, and gap surfaces | | $brainstorm | Structured idea exploration before planning | | $discovery | Full discovery phase orchestrator (brainstorm → search → research → plan → pre-mortem) | | $plan | Epic decomposition into issues | | $pre-mortem | Failure simulation (error/rescue, scope modes, temporal, predictions) | | $post-mortem | Validation + streak tracking + prediction accuracy + retro history | | $bug-hunt | Root cause analysis | | $release | Pre-flight, changelog, version bumps, tag | | $crank | Autonomous epic loop (uses swarm for each wave) | | $swarm | Fresh-context parallel execution (Ralph pattern) | | $evolve | Goal-driven fitness-scored improvement loop | | $autodev | PROGRAM.md autonomous development contract setup and validation | | $dream | Interactive Dream operator surface for setup, bedtime runs, and morning reports | | $doc | Documentation generation — repo docs (default), gold-standard README (--mode=readme), OSS doc packs (--mode=oss) | | $retro | Quick-capture a learning (full retro → $post-mortem) | | $validation | Full validation phase orchestrator (vibe → post-mortem → retro → forge) | | $ratchet | Brownian Ratchet progress gates for RPI workflow | | $forge | Mine transcripts for knowledge — decisions, learnings, patterns | | $security | Continuous repository security scanning and release gating | | $security-suite | Binary and prompt-surface security suite — static analysis, dynamic tracing, offline redteam, policy gating | | $hooks-authoring | Author and validate AgentOps runtime hooks | | $system-tuning | Restore system responsiveness via safe, ordered process cleanup and agent-swarm hygiene | | $skill-auditor | Two-pass audit of an existing SKILL.md against the unified template (15 checks) | | $skill-builder | Scaffold or absorb new SKILL.md files against the unified template |

Expert Skills (specialized workflows)

| Skill | Purpose | |-------|---------| | $grafana-platform-dashboard | Build Grafana platform dashboards from templates/contracts | | $codex-team | Parallel Codex agent execution | | $openai-docs | Official OpenAI docs lookup with citations | | $reverse-engineer-rpi | Reverse-engineer a product into feature catalog and specs | | $pr-research | Upstream repository research before contribution | | $pr-implement | Fork-based PR implementation | | $pr-validate | PR-specific validation and isolation checks | | $pr-prep | PR preparation and structured body generation | | $ship-loop | Bot-paired internal-PR fast-lane cycle | | $complexity | Code complexity analysis | | $product | Interactive PRODUCT.md generation | | $handoff | Session handoff for continuation | | $recover | Post-compaction context recovery | | $session-bootstrap | Universal init prompt — every agent runs this first (soc-vuu6.25) | | $trace | Trace design decisions through history | | $provenance | Trace artifact lineage to sources | | $beads | Issue tracking operations | | $heal-skill | Detect and fix skill hygiene issues | | $converter | Convert skills to Codex/Cursor formats |

To update installed skills: re-run the install one-liner — bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh). (There is no $update skill; skill refresh is an install-script concern.)

Knowledge Flywheel

Every $post-mortem promotes learnings and patterns into .agents/ so future $research starts with better context instead of zero.

Inspect, lint, and triage the .agents/ write surface contract via ao agents inspect | lint | doctor (doctor rolls up inspect + lint + orphan/stray-dir report; --strict fails on orphans).

Runtime Modes

AgentOps has three runtime modes. Do not assume hook automation exists everywhere.

| Mode | When it applies | Start path | Closeout path | Guarantees | |------|-----------------|------------|---------------|-