| name | using-agentops |
| description | Explain AgentOps workflows. |
| practices | ["wiki-knowledge-surface","pragmatic-programmer","agile-manifesto"] |
| hexagonal_role | generic |
| consumes | [] |
| produces | ["documentation"] |
| context_rel | [] |
| skill_api_version | 1 |
| user-invocable | false |
| context | {"window":"isolated","intent":{"mode":"none"},"sections":{"exclude":["HISTORY","INTEL","TASK"]},"intel_scope":"none"} |
| metadata | {"tier":"meta","dependencies":[],"internal":true} |
| output_contract | stdout: operating guide |
AgentOps is the operational layer for coding agents.
Publicly, it gives you four things:
/research, /validation, and /rpiTechnically, AgentOps acts as a context compiler: raw session signal becomes reusable knowledge, compiled prevention, and better next work.
Research → Plan → Implement → Validate
↑ │
└──── Knowledge Flywheel ────┘
/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
/pre-mortem <spec> # Simulate failures (error/rescue map, scope modes, prediction tracking)
/plan <goal> # Decompose into trackable issues
Output: Beads issues with dependencies
/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
/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 | 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:
/implement for single issue execution. Now defaults to TDD-first — writes failing tests before implementing. Skip with --no-tdd./crank for autonomous epic execution (loops waves via swarm until done). Auto-generates file-ownership maps to prevent worker conflicts./discovery for the discovery phase only (brainstorm → search → research → plan → pre-mortem)./validation for the validation phase only (vibe → post-mortem → retro → forge)./rpi for full lifecycle — delegates to /discovery → /crank → /validation./ratchet to gate/record progress through RPI.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 → /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 |
| 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 |
/llm-wiki | External reading wiki proposal — raw sources to compiled wiki |
/harvest | Cross-rig knowledge consolidation — sweep, dedup, promote to global hub |
/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 |
/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) |
/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 |
/dream | Interactive Dream operator surface for setup, bedtime runs, and morning reports |
/doc | Documentation generation — repo docs (default), gold-standard README (--mode=readme), OSS doc packs (--mode=oss) |
/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 |
/security | Continuous repository security scanning and release gating |
/security-suite | Binary and prompt-surface security suite — static analysis, dynamic tracing, offline redteam, policy gating |
/test | Test generation, coverage analysis, and TDD workflow |
/hooks-authoring | Author and validate AgentOps runtime hooks |
/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 |
/system-tuning | Restore system responsiveness via safe, ordered process cleanup and agent-swarm hygiene |
/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 NTM 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 |
| 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 |
/reverse-engineer-rpi | Reverse-engineer a product into feature catalog and specs |
/pr-research | Upstream repository research before contribution |
/pr-implement | Fork-based PR implementation |
/pr-validate | PR-specific validation and isolation checks |
/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 |
/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.)
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).
AgentOps has several runtime modes. Do not assume hook automation exists everywhere.
| Mode | When it applies | Start path | Closeout path | Guarantees |
|---|---|---|---|---|
gc (reference City) | Gas City (gc) binary available, used out-of-session via the reference City (packs/agentops/) | A long-lived mayor agent dispatches whole ao rpi loops to refinery workers (bd ready → gc sling → ao rpi <bead>); cron exec Orders run maintenance | The mayor owns the merge gate (CI-green is the signal) and triggers the knowledge-flywheel feedback | gc orchestrates whole ao rpi/ao evolve loops — it never sees the loop's insides. There is no in-CLI runtime=gc executor (removed); the seam is gc → ao as a subprocess. Dispatch is mayor-driven today; order-auto-dispatch is an upstream-GC gap (soc-5jwah). See the using-gc skill. |
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 |
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)
Startup context loading. Hook-capable runtimes run session-start.sh at session start (manual mode auto-loads MEMORY.md and points to ao search/ao lookup; lean mode injects prior learnings on a reduced token budget). Codex v0.115.0+ fires hooks automatically; pre-v0.115.0 runs ao codex start / ao codex stop explicitly. 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.
| 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: 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 |
Review completed work and learn.
Make an out-of-session Claude (Managed Agent or Agent SDK loop) AgentOps-native — via skills + the ao CLI + CI, not hooks.
Make an out-of-session agent AgentOps-native via skills + ao CLI + CI, not hooks.
Explain AgentOps workflows.
Run autonomous improvement loops.
Scaffold or absorb new SKILL.md files against the unified AgentOps template. Triggers: "create a skill", "scaffold skill", "absorb external skill", "new skill".