Agentops using-agentops

Meta skill explaining the AgentOps operating model. Hook-capable runtimes inject it at session start; Codex uses it through the explicit startup fallback. Covers bookkeeping, validation, primitives, flows, the RPI lifecycle, and the skill catalog.

install

source · Clone the upstream repo

git clone https://github.com/boshu2/agentops

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/boshu2/agentops "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills-codex/using-agentops" ~/.claude/skills/boshu2-agentops-using-agentops-6bb2b5 && rm -rf "$T"

manifest: skills-codex/using-agentops/SKILL.md

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
```
,
```
$validation
```
, 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
$retro                 # Quick-capture a single learning

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

$validation

$vibe

$post-mortem

$retro

$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
```
$validation
```
for the validation phase only (vibe → post-mortem → retro → forge).
Use
```
$rpi
```
for full lifecycle — delegates to
```
$discovery
```
→
```
$crank
```
→
```
$validation
```
.
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
`$research`	Deep codebase exploration
`$council`	Multi-model consensus review + finding auto-extraction
`$vibe`	Code validation (classification + suppression + domain checklists)
`$rpi`	Full RPI lifecycle orchestrator ( `$discovery` → `$crank` → `$validation` )
`$implement`	Execute single issue
`$retro --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
`$flywheel`	Knowledge flywheel health monitoring (σ×ρ > δ/100)

Advanced Skills (when you need them)

Skill	Purpose
`$compile`	Active knowledge intelligence — Mine → Grow → Defrag cycle
`$knowledge-activation`	Operationalize a mature `.agents` corpus into beliefs, playbooks, briefings, and gap surfaces
`$brainstorm`	Structured idea exploration before planning
`$discovery`	Full discovery phase orchestrator (brainstorm → search → research → plan → pre-mortem)
`$plan`	Epic decomposition into issues
`$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)
`$evolve`	Goal-driven fitness-scored improvement loop
`$autodev`	PROGRAM.md autonomous development contract setup and validation
`$dream`	Interactive Dream operator surface for setup, bedtime runs, and morning reports
`$doc`	Documentation generation
`$retro`	Quick-capture a learning (full retro → $post-mortem)
`$validation`	Full validation phase orchestrator (vibe → post-mortem → retro → forge)
`$ratchet`	Brownian Ratchet progress gates for RPI workflow
`$forge`	Mine transcripts for knowledge — decisions, learnings, patterns
`$readme`	Generate gold-standard README for any project
`$security`	Continuous repository security scanning and release gating
`$security-suite`	Binary and prompt-surface security suite — static analysis, dynamic tracing, offline redteam, policy gating

Expert Skills (specialized workflows)

Skill	Purpose
`$grafana-platform-dashboard`	Build Grafana platform dashboards from templates/contracts
`$codex-team`	Parallel Codex agent execution
`$openai-docs`	Official OpenAI docs lookup with citations
`$oss-docs`	OSS documentation scaffold and audit
`$reverse-engineer-rpi`	Reverse-engineer a product into feature catalog and specs
`$pr-research`	Upstream repository research before contribution
`$pr-plan`	External contribution planning
`$pr-implement`	Fork-based PR implementation
`$pr-validate`	PR-specific validation and isolation checks
`$pr-prep`	PR preparation and structured body generation
`$pr-retro`	Learn from PR outcomes
`$complexity`	Code complexity analysis
`$product`	Interactive PRODUCT.md generation
`$handoff`	Session handoff for continuation
`$recover`	Post-compaction context recovery
`$trace`	Trace design decisions through history
`$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
`$update`	Reinstall all AgentOps skills from latest source

Knowledge Flywheel

Every

$post-mortem

promotes learnings and patterns into

.agents/

so future

$research

starts with better context instead of zero.

Runtime Modes

AgentOps has three runtime modes. Do not assume hook automation exists everywhere.

Mode When it applies Start path Closeout path Guarantees

gc

Gas City (

gc

) binary available and

city.toml

present

gc controller manages sessions;

ao rpi

auto-selects gc executor

gc event bus captures phase/gate/failure/metric events

Default when gc is available. Phase execution via gc sessions, events via gc event bus

codex-hookless-fallback

Codex Desktop / Codex CLI without hook surfaces (no gc)

ao codex start

ao codex ensure-start

ao codex stop

ao codex ensure-stop

Explicit startup context, citation tracking, transcript fallback, and close-loop metrics without hooks

manual

Codex cannot resolve repo/runtime state automatically

ao inject

ao lookup

ao forge transcript

ao flywheel close-loop

Works everywhere, but lifecycle actions are operator-driven

In Codex hookless mode, entry skills such as

$rpi

$research

$implement

$status

$recover

, and

$discovery

should ensure the start path once per thread. Dedicated closeout skills such as

$validation

$post-mortem

, and

$handoff

should ensure the stop path once per thread.

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

The first entry skill in a Codex thread should run
```
ao codex ensure-start
```
, which records startup once per thread and skips duplicate startup automatically.
AgentOps inspects
```
.agents/
```
, runs safe close-loop maintenance, syncs MEMORY.md, and writes
```
.agents/ao/codex/startup-context.md
```
.
Surfaced learnings, patterns, and findings are cited as
```
retrieved
```
.
Use
```
ao lookup
```
for automatic citations during work, or
```
ao search --cite retrieved|reference|applied
```
when a search result is adopted.
End the session through
```
$validation
```
,
```
$post-mortem
```
, or
```
$handoff
```
, which ensure
```
ao codex ensure-stop
```
once for the current thread, then verify loop health with
```
ao codex status
```
when needed.

Result: In hookless Codex mode, the agent still gets prior context, citations, and closeout without hidden hooks.

Workflow Reference During Planning

User says: "How should I approach this feature?"

What happens:

Agent references this skill's RPI workflow section
Agent recommends Research → Plan → Implement → Validate phases
Agent suggests
```
$research
```
for codebase exploration,
```
$plan
```
for decomposition
Agent explains
```
$pre-mortem
```
for failure simulation before implementation
User follows recommended workflow with agent guidance

Result: Agent provides structured workflow guidance based on this meta-skill, avoiding ad-hoc approaches.

Troubleshooting

Problem	Cause	Solution
Skill not auto-loaded	Hook runtime unavailable or startup path not run	Hook-capable runtimes: verify `hooks/session-start.sh` exists and is enabled. Codex: let an entry skill ensure `ao codex ensure-start` , or use `ao codex status` / `ao codex start` as the manual fallback
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

Local Resources

scripts/

```
scripts/validate.sh
```