using-agentops

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

Phase	Primary Skill	Supporting Skills
Discovery	/discovery	/brainstorm, /research, /plan, /pre-mortem
Implement	/crank	/implement (single issue), /swarm (parallel execution)
Validate	/validate	/vibe, /post-mortem, /forge

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.

Skill	Purpose
/quickstart	Guided onboarding — run this first
/bootstrap	One-command full AgentOps setup — fills gaps only
/research	Deep codebase exploration
/council	Multi-model consensus review + finding auto-extraction
/validate	Canonical PASS/WARN/FAIL verdict over an artifact, plan, code change, PR, or gate
/vibe	Code validation (classification + suppression + domain checklists)
rpi	Full RPI lifecycle orchestrator (/discovery → /crank → /validate)
/implement	Execute single issue
/post-mortem --quick	Quick-capture a single learning into the flywheel
/status	Single-screen dashboard of current work and suggested next action
/goals	Maintain GOALS.yaml fitness specification
/push	Atomic test-commit-push workflow

Advanced Skills (when you need them)

Skill	Purpose
/compile, /flywheel	Active knowledge intelligence and flywheel health — Mine → Grow → Defrag cycle
/curate	Canonical miner role for transcripts, .agents/, bd, git, skill diffs, and rare wiki entries
/curate --mode=harvest	Cross-rig knowledge consolidation — sweep, dedup, promote to global hub (folded the retired harvest lane)
/inject	Operationalize a mature .agents corpus into beliefs, playbooks, briefings, and gap surfaces (folded the retired knowledge-activation lane)
/brainstorm	Structured idea exploration before planning
/discovery	Full discovery phase orchestrator (brainstorm → search → research → plan → pre-mortem)
/plan	Epic decomposition into issues
/design	Product validation gate — goal alignment, persona fit, competitive differentiation
/pre-mortem	Failure simulation (error/rescue, scope modes, temporal, predictions)
/post-mortem	Validation + streak tracking + prediction accuracy + retro history
/bug-hunt	Root cause analysis
/release	Pre-flight, changelog, version bumps, tag
/crank	Autonomous epic loop (uses swarm for each wave)
/swarm	Fresh-context parallel execution (Ralph pattern)
/using-atm	Run AgentOps loops out of session on an ATM tmux swarm (the ATM leg of the substrate)
evolve	Goal-driven fitness-scored improvement loop
/burndown	Bounded epic-completion loop — drive a finite target to all-merged, then stop
/eval-outcomes	Grade via Outcomes as a holdout-safe projection of the locked eval substrate — one bar, many runtimes
/operating-loop-workflow	Install + run the operating-loop multi-agent Workflow (seven-move loop)
/autodev	PROGRAM.md autonomous development contract setup and validation
agy-rules-workflows	Install AGY-native rules, loop workflow, and scheduled goal controls
/curate --mode=dream	Out-of-session knowledge compounding lane
/doc	Documentation generation — repo docs (default), gold-standard README (--mode=readme), OSS doc packs (--mode=oss)
/post-mortem --quick	Quick-capture a learning (folded the retired retro lane)
/validate	Full validation phase orchestrator (vibe → post-mortem → forge)
/ratchet	Brownian Ratchet progress gates for RPI workflow
/forge	Mine transcripts for knowledge — decisions, learnings, patterns
/security	Repository security scanning and release gating, plus the composable binary/prompt-surface suite — static analysis, dynamic tracing, offline redteam, policy gating
/test	Test generation, coverage analysis, and TDD workflow
/cc-hooks	Author and validate AgentOps runtime hook behavior
/red-team	Persona-based adversarial validation — probe docs and skills from constrained user perspectives
/review	Review incoming PRs, agent output, or diffs — SCORED checklist
/refactor	Safe, verified refactoring with regression testing at each step
/deps	Dependency audit, update, vulnerability scanning, and license compliance
/perf	Performance profiling, benchmarking, regression detection, and optimization
/scaffold	Project scaffolding, component generation, and boilerplate setup
/scenario	Author and manage holdout scenarios for behavioral validation
/skill-auditor	Two-pass audit of an existing SKILL.md against the unified template (15 checks)
/skill-builder	Scaffold or absorb new SKILL.md files against the unified template
/automation-shape-routing	Front door for building agent automation — decide the SHAPE (Workflow vs ATM swarm vs plain skill), then hand off to the right builder
/workflow-builder	Scaffold a new Claude Workflow script (.claude/workflows/*.js) — deterministic multi-agent orchestration
/agent-native	Make out-of-session agents AgentOps-native via skills + ao CLI + CI, not hooks

Expert Skills (specialized workflows)

Skill	Purpose
/swarm	Parallel Codex agent execution (folded the retired codex-team lane)
/reverse-engineer-rpi	Reverse-engineer a product into feature catalog and specs
/codebase-audit	Domain-parameterized codebase auditing (security, UX, performance, API, copy, CLI)
/pr-research	Upstream repository research before contribution
/pr-implement	Fork-based PR implementation
/validate --mode=pr	PR-specific validation and isolation checks (folded the retired pr-validate lane)
/pr-prep	PR preparation and structured body generation
/ship-loop	Bot-paired internal-PR fast-lane cycle
/complexity	Code complexity analysis
/product	Interactive PRODUCT.md generation
/handoff	Session handoff for continuation
/recover	Post-compaction context recovery
/session-bootstrap	Universal init prompt — every agent runs this first (soc-vuu6.25)
/trace	Trace design decisions through history
/curate --mode=provenance	Trace artifact lineage to sources
/beads	Issue tracking operations
/heal-skill	Detect and fix skill hygiene issues
/converter	Convert skills to Codex/Cursor formats

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.

Mode	When it applies	Start path	Closeout path	Guarantees
substrate (out-of-session)	A swappable orchestration substrate available out-of-session: an ATM tmux swarm, MCP (ao mcp serve), or managed-agents (ao agent)	The operator or a lead agent runs bd ready and dispatches a whole loop per bead — an agent that runs the rpi skill; cron / managed triggers run maintenance	The substrate owns the merge gate (CI-green is the signal) and triggers the knowledge-flywheel feedback	The substrate orchestrates whole rpi/evolve loops (each an agent running the skill) — it never sees the loop's insides; the seam is substrate → agent-running-the-skill. There is no in-CLI runtime=gc executor. See agent-native and docs/3.0.md.
hook-capable	Claude/OpenCode with lifecycle hooks installed (no gc)	Runtime hook or ao inject / ao lookup	Runtime hook or ao forge transcript + ao flywheel close-loop	Automatic startup/context injection and session-end maintenance when hooks are installed
codex-native-hooks	Codex CLI v0.115.0+ with native hook support (March 2026)	Runtime hooks (same as hook-capable)	Runtime hooks (same as hook-capable)	Native lifecycle hooks — same guarantees as hook-capable mode
codex-hookless-fallback	Codex Desktop / Codex CLI pre-v0.115.0 without hook surfaces	ao codex start	ao codex stop	Explicit startup context, citation tracking, transcript fallback, and close-loop metrics without hooks
manual	No hooks and no Codex-native runtime detection	ao inject / ao lookup	ao forge transcript + ao flywheel close-loop	Works everywhere, but lifecycle actions are operator-driven

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

Problem	Cause	Solution
Skill not loaded	Startup path not run	Run ao session bootstrap, then ao inject / ao lookup; for Codex lifecycle recovery, run ao codex start explicitly
Outdated skill catalog	This file not synced with actual skills/ directory	Update skill list in this file after adding/removing skills
Wrong skill suggested	Natural language trigger ambiguous	User explicitly calls skill with /skill-name syntax
Workflow unclear	RPI phases not well-documented here	Read full workflow guide in README.md or docs/ARCHITECTURE.md