AgentOps Documentation

The AgentOps CLI, invoked via the ao command, provides a suite of 17 top-level command modules for managing agentic workflows, evaluating models, and inspecting system state.

Key command categories include:

• System & Configuration: config (layered source reporting), doctor (safety-focused system checks/fixes), init (evidence storage setup), and version (metadata).
• Evaluation & Execution: eval (deterministic and live substrate for evaluations), gate (deterministic-check boundary), and demo (product-boundary output).
• Observability & Provenance: status (artifact validation), provenance (hash-chain verification and tracing), capabilities (system contract projection), and flywheel (metrics and status).
• Knowledge & Skills: skills (querying and resolving agent skills), goals (measuring and validating goals), and robot-docs (command-tree projection).
• Utilities: redact (secret scrubbing), session (local bootstrap and handoff), and quick-start (orientation text).

The 'Ponytail whole-repo contraction' is a large-scale maintenance initiative (Epic ponytail-whole-repo-contraction) designed to reduce the repository size by approximately 113,000 lines of code without changing live behavior. The plan uses a 'bead' decomposition strategy, where the work is broken into small, bounded, and independently verifiable tasks (beads).

Key principles for this contraction include:

• Ground Truth: Maintaining live executable behavior, CLI contracts, and existing tests.
• Control Experiment: For deletions, developers must capture observable CLI output and narrow tests before deletion to ensure behavior is preserved.
• Deviation Ledger: Any new abstraction, dependency, or compatibility shim is considered a deviation and must be justified.
• Execution Waves: The work is sequenced into three waves:
  1. Isolated Go deletions (B1, B2, B3)
  2. User-facing and retired surfaces (B4, B5, B6)
  3. Repository and distribution shape (B7, B8, B9).

The Factory Chain is an agile-pivoted roadmap (epics E1–E10) designed to build both the gas-city factory and AgentOps itself. The roadmap is structured into three movements:

1. Trust the tool (E1–E3): Focuses on making the factory reliable, installable, and hardening its security/validation gates (the membrane) so it can be used without constant human supervision.
2. Use the tool (E4–E7): Focuses on driving real AgentOps work through the factory, scaling via concurrency, and implementing a learning loop where the factory's mistakes (escapes) are converted into new automated gate checks.
3. Give it away & self-run (E8–E10): Focuses on external distribution, cost discipline (metering cost per quest), and achieving a self-improving state where the factory proposes and builds its own improvements through its own membrane.

Each epic is governed by an evidence gate. The orchestrator uses the results of these gates to re-plan (re-scope, reorder, or drop) the remaining epics via the /rpi agile re-plan loop.

The Go CLI is undergoing a production-readiness audit to address architectural and behavioral discrepancies. Key areas of concern include:

• Semantic vs. Syntactic Validation: Current architecture checks verify module existence and syntax but do not guarantee that command effects (like cancellation or state mutation) match their declared contracts.
• Contract Recursion: The Contract() model for Module is currently top-level and does not automatically propagate to child commands, leading to potential mismatches between declared and actual command behavior.
• Stateful Root Effects: Commands declared as EffectPure may still trigger stateful side effects (e.g., Git configuration changes or environment mutations) due to universal root pre-run logic.
• Configuration Robustness: The trackerresolve package may silently fall back to lower-precedence configurations when encountering malformed YAML or file errors, rather than reporting the error.
• Context Propagation: Some command handlers (specifically in the beads module) use context.Background() instead of command.Context(), which prevents proper handling of Ctrl-C or parent cancellations.
• Output Format Fidelity: Global flags like --json or --output yaml are not uniformly supported across all commands, leading to inconsistent data formats or incorrect key naming in YAML outputs.

The AgentOps CLI is designed to be lean, relying heavily on the Go standard library and shelling out to specific ecosystem tools rather than linking them directly.

Required/Critical Dependencies:

• bd (beads CLI): Used for issue tracking. The ao beads command executes the bd binary.
• git: Required for worktrees, provenance, and all SDLC (Software Development Life Cycle) mechanics.
• codex CLI: The preferred headless agent runtime for ao compile and loops. Note: claude -p is forbidden by LAW 0.
• spf13/cobra + pflag: The underlying CLI framework.
• Config Parsers: gopkg.in/yaml.v3 and BurntSushi/toml.

Optional/Contextual Dependencies:

• tmux: Used for RPI (Remote Process Interaction) phased/legacy lane pane control via the AGENTOPS_RPI_TMUX_COMMAND variable.
• Ollama / local LLM: Can be used as an alternative for the Dream curator or compile tasks via AGENTOPS_DREAM_CURATOR_OLLAMA_URL.
• NTM + MCP Agent Mail: External substrate used for live multi-agent orchestration.

As of the July 12, 2026 audit, the AgentOps Go CLI (ao) is undergoing a large-scale migration from a monolith (cmd/ao) to a modular architecture. While core build and testing processes are stable, the CLI is not yet considered production-ready due to semantic gaps in its architecture and proof system.

Current Strengths

• Build & Test Integrity: go build, go vet, go test, and go test -race all pass. govulncheck reports no vulnerabilities.
• Compatibility: The CLI passes four-profile compatibility checks (default, flywheel, legacy, and combined).
• Module Management: cliapp.BuildRoot provides fresh trees, validates modules, detects duplicate IDs/names/aliases, and handles profile selection.
• Workspace Ownership: trackerresolve acts as the single owner for selection/workspace management, correctly modeling linked worktrees and br/bd child environments.

Known Risks & Semantic Gaps

• Cancellation Issues: Some beads command modules discard Cobra cancellation.
• Configuration Silencing: Malformed tracker configurations may fail silently instead of failing-closed.
• Contract Violations: The architecture checker verifies local syntax and ownership but does not guarantee end-to-end semantic invariants (e.g., claim adapters not honoring WorkDir or ChildEnv).