“Which version of the reviewer ran last night?”
Agent files live in each laptop's repo. Everyone edits their own copy and nobody can say which one ran.
agents: Your agents, versioned, and named on every step.
Keep every agent your team uses in one catalog. Each save is a numbered revision, teams pin the ones they tested, and each workflow step names the agent that does it.
catalog · revisions · teams · step agents · tiers
parts
- Review a diff against the standardsReview a diffdescription
- Prerequisites · Role · RulesThree sectionsbody
- balancedtier
- claude-code: opuspin
agent catalogcode-reviewer · r3
draft- descriptionReview a diff against the standards
- bodyPrerequisites · Role · Rules
- tierbalanced
- pinclaude-code: opus
- three sections present
- name is a safe file name
- tier exists in this workspace
in short
How do you version and share AI agents across a team?
Keep them in one ConvOps agent catalog. Every save is a numbered revision, teams pin the revisions they tested, and each workflow step names the agent that does it.
ConvOps is the operations layer for AI agents: an MCP server that holds your team's process as workflows, with approval gates, a shared memory and an audit trail. It does not sell or host models.
key facts · october 2026
- An agent has a description, a model tier and a body with Prerequisites, Role and Rules sections. Revisions are immutable, and one of them is active.
- Setting an older revision active rolls an agent back without deleting anything. Agents are disabled, never deleted.
- A team member is pinned to one revision by default, or follows the agent's active revision. A workflow step gets the agent's active revision.
- An isolated run receives the environment's team, or every enabled agent, plus each step agent. The task previews that set before dispatch.
- Each agent runs on its pin for the runtime, else its tier's model, else the executor's own model. Provider connections hold the keys; executors hold none.
best for
- Teams whose Claude Code or OpenCode agent files have drifted between repositories and laptops.
- Choosing a model per agent and seeing on every run which model it used and why.
not for
- Hosting models. ConvOps does not sell or host models: agents run on your own provider keys or subscription.
updated
the problem
Which agent did that, at which version?
Agent files live in each repository and on each laptop. Everyone edits their own copy, and nobody can say which one ran.
“Who changed the prompt that broke the release?”
There is no history. A bad edit replaces the good one, and there is nothing to roll back to.
“Why did that step run on the expensive model?”
The model hides in a header in one file, and every machine resolves it a little differently.
the catalog
One catalog, every revision kept.
Each agent has a description, a model tier and a body in three sections. Every save is a numbered revision. Roll back by setting an older one active.
- r1Review a diffbalanced
- r2Review a diff, be briefbalanced
## Prerequisites Read the diff and the standards it touches. ## Role You review diffs before a person approves. ## Rules - Name the file and line for every finding.
r2 is active: every run gets it.
- Every save is a revisionNumbered, immutable, readable forever. A save that changes nothing writes nothing.
- Roll back by moving one pointerSet an older revision active. The newer one stays in the history.
- Disable, never deleteRefused while an enabled workflow step still names the agent.
teams
Teams pin what they tested.
A team groups agents for one kind of work. Each member is pinned to a revision by default, or follows the agent's active one. An environment names its team.
tester r5 saved
teamreview-squadReview a merge request end to end
- final-checkcode-reviewerreviews last, read-onlypinned r2
- testerwrites the missing testsfollows active r4
- security-scanchecks the diff for secretspinned r1
environment app-dev · runs receive this team
step agents
Each step names its agent.
A workflow step names the catalog agent that does it, and gets that agent's active revision. Improve an agent once, and every step that names it runs the new text next.
planplanner
implementdeveloper
reviewcode-reviewer
approveapproval
mergedone
- The active revision runsA step gets the agent's active revision. Save a better reviewer once, and every workflow that names it gets it on the next run.
- In use is protectedDisabling code-reviewer is refused while an enabled step names it. The refusal names every workflow and step.
- Find broken bindingsAn imported workflow can name agents you lack. One filter lists every workflow with a missing step agent.
the run's agents
Every run gets a known set.
An isolated run hands the environment's team plus every step agent to Claude Code or OpenCode. Preview the set on the task first: each agent, its revision and its model.
- final-checkr2teamincludedclaude-opus-5-5 · pin
- testerr5teamincludedclaude-sonnet-4-6 · tier balanced
- developerr7stepincludedclaude-sonnet-4-6 · tier balanced
- plannerr3stepleft outdisabled: enable it or unbind it from the step
delivered to Claude Code~/.claude/agents/<name>.mdheader: name · description · model
- Into Claude Code or OpenCodeEach agent becomes a subagent file of the run's runtime, beside the engine's own agents, with the model picked for that runtime.
- Team, or every enabled agentThe environment's team, or the whole enabled catalog when it names none. Step agents join either way.
- Preview before you dispatchThe task shows what a dispatch now would get: names, revisions, models and the reason for each.
- Never in your repositoryAgent files go to the run's home folder, not the checkout. A repository agent with the same name blocks the task and names the file.
import and export
Your agent files, both ways.
Bring the agents you already keep in .claude/agents or .opencode/agents into the catalog, and write the catalog back as files. Preview either direction first: nothing is written.
.claude/agentsClaude Code · name from the name header
.opencode/agentsOpenCode · name from the file name
agent catalognew agents created · changed ones revised
.claude/agentsagent catalog
- reviewer.mdnew agent, pin opusstrongadd
- planner.mdtext changed, new revisionbalancedupdate
- helper.mdcatalog already holds itinheritunchanged
add 1 · update 1 · unchanged 1
models
A model for each agent.
Each agent names a tier, and a tier sets a model per runtime. An agent can pin its own. Your provider connections hold the keys.
checked top to bottomfirst set wins
01Agent pinfor this runtimeclaude-opus-5-5
02Tier modelstrong · balanced · fast · yoursclaude-sonnet-4-6
03Executor modelthe executor's ownclaude-haiku-4-5
runs on
checking layers
from Agent pin
The pin is ready on a connection, so it runs.
- A registry that stays currentThe models.dev catalog every day, plus models you add, inside your workspace allowlist.
- Connections hold the keysEach provider connection proves which models answer with one real call. Executors hold no keys.
- Recorded on the runEvery run records each agent's model and why: pin, tier or the executor's own.
questions
Agent catalog questions, answered.
What is an agent in ConvOps?
A named definition in your workspace catalog: a description of when to use it, a model tier, and a body with its prerequisites, role and rules. Every save is a numbered revision, and one revision is active.
How do I roll an agent back?
Set an older revision active. Nothing is deleted: the newer revision stays in the history, and the next save builds on the one you chose.
Does changing an agent change my workflows?
A workflow step gets the agent's active revision, so the next run of every step that names it uses the new text. A team member pinned to a revision keeps that revision until you change the pin.
Can I keep my existing Claude Code or OpenCode agent files?
Yes. The convops command line imports .claude/agents and .opencode/agents into the catalog and exports the catalog back as files, with a preview that writes nothing in both directions.
Which model does each agent run on?
Its pin for the run's runtime, else its tier's model, else the executor's own model. A pin or tier model counts only once a real call has worked on one of the executor's provider connections. The run records which model each agent used and why.
Who holds the model keys?
Your provider connections, as secret references. Executors hold no keys; they link connections. ConvOps does not sell or host models.