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, /validate, 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
/post-mortem --quick   # Quick-capture a single learning (folded the retired retro lane)

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

Phase-to-Skill Mapping

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 /validate for the validation phase only (vibe → post-mortem → forge).
• Use rpi for full lifecycle — delegates to /discovery → /crank → /validate.
• 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.

Advanced Skills (when you need them)

Expert Skills (specialized workflows)

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 several runtime modes. Do not assume hook automation exists everywhere.

Issue Tracking

This workflow uses beads for git-native issue tracking:

bd ready              # Unblocked issues
bd show <id>          # Issue details
bd close <id>         # Close issue
bd vc status          # Inspect Dolt state if needed (JSONL auto-sync is automatic)

Examples

Startup context loading. AgentOps 3.0's default path is explicit: run ao session bootstrap, then pull prior context with ao inject / ao lookup or a phase-scoped packet. Optional hook-capable runtimes may run an authored session-start.sh, and Codex CLI can use opt-in native hooks via install-codex.sh --with-hooks; those are compatibility/adaptor paths, not the default. Either way the agent gets the RPI workflow, prior context, and a citation path.

Workflow reference during planning. When a user asks how to approach a feature, the agent uses this skill's RPI section to recommend Research → Plan → Implement → Validate — /research for exploration, /plan for decomposition, /pre-mortem for failure simulation — instead of an ad-hoc approach.

Troubleshooting