AgentOps

AgentOps is the operations layer for agentic engineering.

AgentOps connects intent, coding agents, software factories, context sources, and independent judgment through portable skills and evidence contracts without replacing the systems that own work, execution, or delivery.

The architecture is a federated integration graph: your tracker keeps the work, Git keeps the history, your coding agents and factories run the execution, deterministic checks prove facts, and a fresh validator judges meaning. AgentOps supplies the semantic work-and-proof protocol that joins those nodes — exact intent, exact subject, evidence, fresh judgment, honest outcomes. The standard traversal through the graph is RPI, one experiment at a time:

RPI -> Plan -> Implement -> fresh Validate -> report and stop

For contested calls, opt into council (independent judges) or idea-genie duel mode (sealed perspectives before Plan).

Quickstart

npx skills@latest add boshu2/agentops --all -g

One command installs the skill bundle into every coding agent you use. The skills run inside your coding agent (Claude Code, Codex, Cursor, …): type /rpi in that agent's chat, or ask for plan, implement, validate, and learn by name. No other runtime is required.

Plugins (Claude Code / Codex)

Prefer a managed bundle that updates with the release:

# Claude Code
claude plugin marketplace add boshu2/agentops
claude plugin install agentops@agentops-marketplace

# Codex
codex plugin marketplace add boshu2/agentops
codex plugin add agentops@agentops-marketplace

Three install paths:

• npx / skills.sh: universal; copies skills you can edit.
• Plugins: a read-only bundle that stays current with the repo.
• Checkout + ao skills link: source-tracked symlinks for contributors (see Install and day-2 operations).

Admission-control hooks (on by default)

AgentOps ships a PreToolUse policy dispatcher: deterministic guards that block a small set of known-destructive commands (staging the private bead ledger, hand-editing the hash-chained provenance ledger, overwriting installed skill copies) and route you to the correct tool instead. Silent on every clean call; every block is one line.

• Claude Code plugin installs: active automatically; nothing to run.
• npx / skills.sh copies: run ~/.claude/skills/cc-hooks/scripts/install-hooks.sh once.
• git clone / brew: run scripts/install-policy-dispatch.sh once.

Disable anytime (/plugin disable agentops, or remove the two PreToolUse matchers from settings). Policy list and design: skills/cc-hooks/SKILL.md.

Remove with your runtime's plugin uninstall, or delete the linked skill directories.

Intent lives in a bead

Beads is the preferred tracker (optional; brew install beads). Plan writes BDD acceptance and DDD ubiquitous language into the bead; Implement builds against it; Validate judges a hashed snapshot under .agents/ao/intents/sha256/. No beads? Plan shapes the caller's issue or chat text and the runtime snapshots those bytes the same way.

validate must run in a fresh context (not the author session). It can use the same model as the author or a different one.

Multi-agent systems

The default is one agent, one writer. When you need a fleet, swarm, agent-native, ntm, and using-gc orchestrate multi-agent work. They dispatch; they do not own the verdict.

Choose a software factory

AgentOps supplies skills and evidence contracts, not another software-factory runtime or a competing Gas City pack. Install the skills in the agent runtime used by the factory you choose; its Mayor, coordinator, and workers can then use plan, implement, test, validate, and the rest of the catalog.

Two factory stacks are supported:

• Gas City is the preferred choice for durable, supervised workflows. Use the upstream gascity build pack, the workflow family used by Maintainer City. It owns formulas, roles, worktrees, dispatch, draining, and run state. The using-gc skill covers installation, launch, observation, and recovery.
• Jeffrey Emanuel's Agentic Coding Flywheel is a supported alternative built from Beads, Agent Mail, NTM, and the wider Flywheel tool stack. Use its native workflow and let its agents consume the same AgentOps skills. The using-flywheel skill covers provisioning, skill visibility, and the evidence boundary.

AgentOps does not wrap either factory or translate factory completion into semantic PASS. When proof is required, a fresh validate context judges the exact candidate and evidence.

Optional: ao CLI

Deterministic checks, inspection, and skill linking. Skip it if you only need the skills.

brew tap boshu2/agentops https://github.com/boshu2/homebrew-agentops
brew install agentops

Without Homebrew: go install github.com/boshu2/agentops/cli/cmd/ao@latest

To track skills from a local checkout instead of a release bundle, run ao skills link from that checkout.

Why AgentOps exists

1. The agent said it was done

Same session that wrote the code also declared victory. AgentOps separates authorship from judgment: implement produces a candidate; validate must run in a fresh context and may use a different model. It issues PASS, FAIL, or NOT_PROVEN.

2. One perspective rubber-stamped another

A single context can share blind spots with the author. Opt into idea-genie or council for sealed or multi-judge review. They return a report; an author-distinct validate context issues the binding result.

3. Acceptance drifted mid-flight

Without a fixed behavior and write scope, "done" is whatever the agent improvised. plan locks acceptance in the bead before anyone builds. Later phases bind to that digest.

4. Nobody can replay what was judged

Chat scrolls away. When replay or automation needs durable evidence, validate writes a content-addressed verdict.v2 under .agents/ao/verdicts/sha256/ with checked scope, omissions, and evidence refs. Plain JSON. No hosted service required. Interactive validation does not create one unless requested.

Core skills

Optional later: learn. Strategies: council, idea-genie, premortem, postmortem.

One skill, many shapes

AgentOps prefers a smaller skill set you can steer over dozens of near-duplicate skills. Modes and flags change behavior inside one contract.

Read the skill's mode table before inventing a sibling skill. Full inventory: Skill Router.

Evidence contract

A PASS binds unchanged acceptance, a deterministic subject manifest, complete changed-path coverage inside write scope, distinct author and validator context IDs, a freshness attestation, and criterion-level evidence.

Missing identity, mutation, or incomplete coverage → NOT_PROVEN. Proven out-of-scope change or failed criterion → FAIL.

RPI traversal · CLI · Docs

Contributing: docs/CONTRIBUTING.md. License: Apache-2.0.