agentops

AgentOps

Agent work you can verify and build on.

AgentOps means agent operations: applying years of DevOps experience to how coding agents plan, implement, validate, and hand off work.

A coding agent can finish a task and pass its tests while missing the behavior you asked for. AgentOps gives Claude Code and Codex engineering guidance for defining that behavior, implementing it in your domain's language, and having a fresh reviewer check the result against the original request.

Engineering effort should leave reusable improvements behind: working code, regression tests, useful tools, and decisions the next task can build on. Start with one task and the guidance it needs; your repository keeps its tests, tracker, and Git workflow.

Quickstart · BDD example · Ecosystem · Choose a skill · Optional CLI · FAQ · Documentation

Why use AgentOps?

When the agent…	Reach for…	What you can inspect
Builds something different from what you meant	Behavior-driven planning	A concrete acceptance example used by both implementation and review
Uses three names for the same domain concept	Shared domain language	Consistent terms and rule ownership across the request, code, and tests
Says “done” after a green test run	Fresh independent validation	Evidence for each requested behavior, with missing coverage called out
Leaves the next session to repeat the investigation	Reusable checks and useful work records	Regression tests, tools, and decisions kept with their existing owners

The 34-skill library packages established engineering practices. Select what helps the current task; a clear change can proceed directly in your coding agent.

Quickstart

Use an installed Claude Code or Codex with plugin support. Run the commands for one runtime in your terminal. They install the full managed skill bundle; ao is not needed for the first task below.

Claude Code

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

Codex

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

The plugin should appear as agentops. Claude's inventory includes 34 skills and four agents; Codex exposes 34 skills with agentops: names. Start a new session in a project you already work on to load the installed skills.

Skills run inside your coding agent with its normal permissions. The Claude plugin also installs its policy dispatcher. Optional limits on source reads and Codex's additional agent roles have separate setup. To remove the bundle, use claude plugin uninstall agentops@agentops-marketplace or codex plugin remove agentops@agentops-marketplace in your terminal.

Try one task

Paste this into your Claude Code session, not your terminal:

/agentops:research Find how this repository validates user input. Trace one
path from the input through validation and its tests. Cite the relevant files
and line numbers, explain one edge case, and identify any missing coverage.
Answer in this conversation without changing files.

In a Codex session, use the same request with its skill prefix:

$agentops:research Find how this repository validates user input. Trace one
path from the input through validation and its tests. Cite the relevant files
and line numbers, explain one edge case, and identify any missing coverage.
Answer in this conversation without changing files.

Expect a trace you can inspect: where input enters, which checks accept or reject it, and what the tests cover. If a step cannot be established, the answer should say what is missing. You can then request a fix or a regression test using those file references. Research itself does not authorize a code change.

From behavior to verified change

Behavior-driven development (BDD) means agreeing on concrete examples of what the software should do before coding, then checking the result against those same examples. Given describes the starting situation, When the action, and Then the observable result. For example, in a system that calls queued work a Job:

Given a Job has already completed
When the worker receives that Job again
Then it returns the completed result without repeating the side effect

Keep that example in the existing issue or conversation. The implementer fixes the relevant path and adds a regression test that checks both the returned result and the absence of a repeated side effect. A fresh reviewer examines the exact change and its evidence against the same example. Passing an unrelated test suite does not fulfill the promise.

Domain-driven design (DDD) keeps the meaning of Job consistent across the request, code, tests, and review. Use the repository's established vocabulary and rule owners; clarify a term when ambiguity would change the behavior. Plain-text examples suffice. No .feature file or glossary is required.

The resulting fix and regression test remain available for future changes. Record useful decisions and handoffs in the caller's existing tools. This is the engineering value AgentOps aims to preserve across sessions; a saved note alone does not establish that later work improved.

Use this in a repository with a Job worker, adapting the domain terms to the actual system. These are prompts for your coding agent, not shell commands. Here is the Codex form; in Claude Code, replace $agentops: with /agentops:.

$agentops:plan Clarify this behavior and its scope: given a Job has completed,
when the worker receives it again, return the completed result without
repeating the side effect. Reuse our existing domain terms and identify the
smallest check that distinguishes correct behavior from the current code.

After agreeing on the scope:

$agentops:implement Implement the accepted Job behavior within the agreed scope.
Add a regression check for the returned result and the absence of a repeated
side effect. Run the owning checks and report their results.

Then use a fresh reviewer context, with access to the exact change, the accepted scope, and the check results. Validate requires the optional ao CLI.

$agentops:validate Review this change against the accepted scope and behavior:
a completed Job received again returns its result without repeating its side
effect. Inspect the implementation and check evidence; report PASS, FAIL, or
NOT_PROVEN with checked scope and any missing evidence. Do not change the code.

These prompts illustrate a workflow; they are not a transcript or a claim that the example has run in your repository. Individual skills can also be used on their own.

Design principles

1. Agree on behavior before implementation. Keep accepted examples in the existing conversation or issue. Tests added later can extend the evidence; they cannot redefine what was promised.
2. Use the domain's own language. Clarify consequential ambiguity and respect boundaries where the same word has different meanings.
3. Separate authorship from acceptance. A fresh reviewer checks the exact change. The author cannot issue its own binding PASS.
4. Leave useful improvements behind. Preserve regression checks, tools, and supported decisions where later work can use them. Add guidance when it resolves a real need; a new worksheet is not required for every task.

These practices come from BDD, DDD, design by contract, testing, refactoring, and other established engineering work. The Practice Registry records their lineage and how skills apply them. See how it works for the planning, implementation, and validation responsibilities.

Where AgentOps fits

AgentOps grew independently from applying DevOps experience and established engineering practices to agents. Projects such as Compound Engineering and Matt Pocock's skills have converged on similar approaches. There is substantial overlap: AgentOps covers planning, implementation, testing, review, and deliberate reuse. Use it across that workflow, or combine selected practices with other libraries.

Project or tool	What it provides	How the pieces can work together
AgentOps	Skills for planning, implementation, testing, review, and reuse, plus CLI checks and evidence tools	Use the full workflow or selected skills, with BDD examples and fresh judgment tied to the accepted behavior
Compound Engineering	A connected brainstorm, plan, build, review, and learning-capture workflow	Can supply the development loop and reusable solution records; carry the accepted behavior and evidence into independent judgment
Matt Pocock's skills	Composable practices for clarifying intent, domain modeling, TDD, and review	Callers can select relevant practices alongside AgentOps skills
Beads or your existing tracker	Work status, dependencies, and handoffs	Keeps ownership of work while AgentOps reads the accepted intent and cites its source
Software factories such as Gas City	Coordinating and running agents	Own execution through their native control plane; AgentOps supplies guidance, checks, and independent review of results

For example, a factory can coordinate a Beads-tracked task, an implementer can use a TDD skill, and a fresh reviewer can check the result against the accepted BDD example. Choose which workflow leads the task and make those handoffs explicit. The Compound Engineering and Matt Pocock combinations are ways to compose practices; the linked factory skill documents its supported integration.

Review and durable context are shared ideas across these projects. See the validation contract for AgentOps' review requirements.

Choose skills by the work

Pick guidance for the task in front of you. These are independent choices, not steps you must run in order.

What you need	Skill	What to expect
Understand a behavior before changing it	research	An answer grounded in code and tests, with file references and gaps
Add tests for a behavior or regression	test	Tests using your repository's framework, plus the commands and results
Simplify code while preserving behavior	refactor	A focused change checked against the existing behavior
Clarify what a change should do	plan	Observable behavior, acceptance examples, and an agreed scope
Implement an accepted change	implement	A scoped implementation, relevant checks, and direct repair of known defects