AgentOps

DevOps discipline for AI coding agents: shape the work, track it as a graph, and get each change judged by a fresh agent session that didn't write it.

Install · The loop · Goals · Try it · Skills

AgentOps provides optional skills and a CLI (ao). The same SKILL.md skills work with coding agents (Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Pi and others) and personal assistants (OpenClaw, Grok Bot). You state intent as behavior in your domain's words. The skills carry it through one change (Plan → Implement → Validate, an RPI) or, for bigger work, a goal made of many RPIs tracked in Beads, a dependency-aware issue tracker.

Why use AgentOps?

Quickstart

Pick one method per agent: a plugin plus npx on the same agent gives you every skill twice.

claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace
claude plugin details agentops@agentops-marketplace

codex plugin marketplace add boshu2/agentops
codex plugin add agentops@agentops-marketplace
codex plugin list --json

npx skills@latest add boshu2/agentops

Start a new session so the skills load. Most skills need only your coding agent; Validate also needs the ao CLI. Invocation names vary by agent: this README shows Claude Code's /agentops:<skill>; Codex uses $agentops:<skill>.

The operational loop

Each change is shaped, built and judged. You (or Plan) write intent as behavior (BDD), using one word per concept (DDD's ubiquitous language). For a system that calls queued work a Job, in Gherkin:

Feature: Job redelivery is idempotent
  A Job is one unit of queued work. Delivering it again never repeats its side effect.

  Scenario: A completed Job is delivered again
    Given Job "J-42" completed and charged the customer $20
    When the worker receives Job "J-42" again
    Then it returns the completed result of "J-42"
    And the customer has been charged $20 exactly once

  Scenario: A Job that failed before charging is delivered again
    Given Job "J-43" failed before charging the customer $20
    When the worker receives Job "J-43" again
    Then Job "J-43" completes
    And the customer has been charged $20 exactly once

The feature defines the domain term once; each scenario has concrete data, one action and an observable result. Keep scenarios in the issue or conversation; no .feature file is required.

Enter at the step you need; an existing change goes straight to Validate. The author never approves its own work. Merging and releasing follow your repo's rules.

Goals

rpi runs Plan → Implement → Validate for one outcome without check-ins (your agent's permission prompts still apply) and stops at acceptance, a blocker or a spent limit. Bigger work becomes a goal (experimental; needs Beads: brew install beads, then bd init in your repo):

1. Interview. One question at a time, each with a recommended answer. You settle the outcome, its examples, domain terms, non-goals, authority and budget before agents go autonomous.
2. Craft Goal. Returns SAFE_TO_CREATE plus a prompt to paste into /goal (Claude Code or Codex), USE_RPI (small enough for rpi), or UNSAFE_GOAL plus what's undecided. It creates nothing itself.
3. Navigate each round. Picks a few ready work items (beads); each gets one RPI and a fresh Validate. The goal ends ACHIEVED, NOT_ACHIEVED or NEEDS_OPERATOR.

Beads holds the plan. Beads (bd) keeps work as a dependency graph outside any conversation, so a goal survives compaction and restarts. The root epic holds acceptance; each child bead is one RPI with its question, scope, notes and verdict. bd ready lists what can start now.

One bead per worker. When the goal delegates, the orchestrator holds the graph and verdicts, and each worker starts with one bead instead of the orchestrator's transcript. Validators start fresh.

bd create "Job redelivery is idempotent" -t epic
bd create "Return the completed result on redelivery" --parent <epic-id>
bd dep add <later-id> <earlier-id>         # real ordering only
bd ready --parent <epic-id>                # the frontier

Navigate shows bd commands; another tracker with status, dependencies and notes works if you map them. AgentOps never builds a second work index.

Try it

Start read-only in any repo, then swap the Job example for your own change.

# First look (changes nothing)
/agentops:research how does this repo validate input? cite files and lines, change nothing

# One change
/agentops:plan make Job redelivery return the completed result without repeating the side effect
/agentops:implement
/agentops:validate     # new session: paste the scenarios, the commit, and the authoring session's ID (your name for a hand-written change)

# One outcome, end to end
/agentops:rpi make Job redelivery return the completed result without repeating the side effect

# A goal
/agentops:interview make the job worker safe under redelivery, retries and crash recovery
/agentops:craft-goal   # then paste its prompt into /goal

Use the AgentOps Validate skill to judge this finished change.
Original accepted behavior: [issue link or original request text]
Candidate: [commit, branch or working tree; list every changed path]
Author context ID: [task/session ID that made the change]
Checks run: [commands and results]
I opened this new conversation for fresh review. Derive the exact subject
identity at the start and end, inspect every changed path against the original
behavior, and do not modify the candidate. Report PASS, FAIL or NOT_PROVEN with
evidence for each criterion, checked, not_checked, author and reviewer context
IDs, and freshness attestation.

Use the AgentOps Research skill to trace how this repository validates user
input. Follow one path from the input through its checks and tests. Cite the
files and line numbers, explain one edge case, and identify missing coverage.
Name the Research skill file you loaded. Answer here without changing files.

Skills at a glance

All skills are optional. Load one when it answers a specific question. Full catalog: docs/SKILL-ROUTER.md.

Where AgentOps fits

AgentOps grew from applying DevOps experience and established engineering practice to agents. The Practice Registry records the lineage; how it works covers responsibilities.

ao CLI (needed for Validate)

Most skills need only your coding agent. Validate uses ao to identify the exact change it judges.

brew tap boshu2/agentops
brew trust --tap boshu2/agentops
brew install agentops
ao version

With Go installed: go install github.com/boshu2/agentops/cli/cmd/ao@latest. ao init is optional evidence setup; ao config --show inspects configuration; ao gate check runs this repository's own gates (mainly for contributors). See the command reference and installation guide.

Updating and advanced setup

Troubleshooting

Limits

Skills guide agents; installation alone does not enforce their instructions. A green test suite or an agreeing model can still miss a defect. Missing proof stays NOT_PROVEN. Saving notes does not establish improved outcomes or automatic knowledge compounding. See product evidence and limits.

FAQ

Recommended tools and skills

These independent projects can extend your AgentOps setup. Get their tools and skills directly from their authors; they are not bundled with AgentOps.

• Gas City, from the organization behind Beads, provides the building blocks for a software factory. AgentOps includes Gas City guidance and an executor integration pack.
• Agentic Coding Flywheel is Jeffrey Emanuel's (Dicklesworthstone) ecosystem for planning and coordinating coding agents. Follow his site for the tools, methodology and upstream skills.
• Destructive Command Guard (dcg) is a strong recommendation for checking agent shell commands and blocking destructive operations covered by its rules.
• Coding Agent Session Search (cass) is a strong recommendation for indexing and searching session histories across coding agents, including finding episodes worth mining for lessons.
• Meta Skill (ms) is a strong recommendation for finding, managing and building skills from context, including CASS session mining. Review generated guidance before reuse.

DCG, CASS and MS are Jeffrey Emanuel's projects. Their upstream documentation and distribution terms govern their tools and skills.

Contributing

Contributions are welcome: documentation fixes, reproducible bug reports, tests, CLI improvements and skills. Read the contribution guide; to work on skills from a checkout, link them with ao skills link.

Licensed under Apache-2.0.