agent-ops-cli 0.1.2

Agent Ops (AO) - high-performance JSONL issue/event store

AO — Agent Ops CLI

AO is a development operations tool for humans and autonomous agents.

It gives you an event-sourced issue system, deterministic JSON interfaces, built-in workflows, and a large skill library for planning, implementation, review, validation, and reporting.

Install once, then run everything through ao in your repo.

Install

Tool install (recommended)

uv tool install agent-ops-cli
ao --version

Local development checkout

git clone <repo-url>
cd agent-ops
uv sync
uv tool install .
ao --version

ao ... examples in this README assume AO is installed as a tool. Use uv run ... for development commands such as tests, lint, and build scripts.

What AO is for

AO is built for teams that want a structured workflow where both people and agents can:

• capture work as issues quickly
• execute reliably with minimal merge conflicts
• keep a durable event log of all issue operations
• automate quality gates and completion checks
• scale from one developer to many parallel agents

In short: project memory + execution workflow + agent ergonomics.

Core features

1) Issue lifecycle from terminal to done

Use AO as your execution backbone: create, prioritize, move, and close work.

ao add "Fix timeout regression" --type bug --priority high
ao show BUG-0001@abc123
ao set BUG-0001@abc123 --status in_progress --owner alice
ao close BUG-0001@abc123 --log "Validated and merged"

2) Event-sourced history and deterministic state

Every change is written as an immutable event, and current state is rebuilt deterministically.

ao event append --in -
ao rebuild
ao ls --view summary

3) Prioritization and daily execution flow

Pick the next best work and keep your board current.

ao next --limit 10
ao ls --view kanban
ao stale --days 7
ao triage

4) Dependency-aware planning

Model blockers explicitly and inspect the graph before implementation.

ao link add BUG-0004@aaaaaa --depends-on FEAT-0012@bbbbbb
ao link graph --graph-format mermaid
ao dep-tree BUG-0004@aaaaaa --depth 5

5) Acceptance criteria and quality gates

Keep completion objective by tracking AC and enforcing gate checks.

ao ac add BUG-0004@aaaaaa "Timeout test passes under load"
ao ac check BUG-0004@aaaaaa 1
ao validate
ao gate BUG-0004@aaaaaa

6) Focus and handoff state for humans + agents

Maintain explicit "doing now / next" context so sessions resume cleanly.

ao focus set-doing BUG-0004@aaaaaa --task "Patch retry strategy"
ao focus set-next "Run validation and close if gate passes"
ao focus sync

7) Worktree-based parallel development

Split concurrent work safely with isolated worktrees.

ao worktree add --epic auth --branch feat/auth-hardening
ao worktree ls
ao worktree merge

8) Hooks and automation controls

Wire AO behavior into local git lifecycle and agent loops.

ao hooks install
ao hooks status
ao hooks loop-prompt --engine copilot
ao hooks loop-run --engine copilot --max 5

9) Multi-agent worker assignment

Create worker profiles and route issues intentionally.

ao worker add reviewer --engine copilot --model gpt-5.3-codex
ao worker assign BUG-0004@aaaaaa --worker reviewer
ao worker ls

10) References/spec traceability

Attach decision docs directly to issues for reviewable context.

ao ref init BUG-0004@aaaaaa
ao ref status BUG-0004@aaaaaa
ao ref open BUG-0004@aaaaaa

11) Recovery, migration, and admin safety nets

Recover state, migrate history, and inspect lock problems.

ao admin cleanup
ao admin migrate ../old-project
ao lock status

12) Reporting and export workflows

Export machine-readable state and track performance trends.

ao export json --out reports/issues.json
ao export jsonl --out reports/issues.jsonl
ao bench rebuild --events data/events.jsonl

13) Web Kanban view for collaboration

Use the web interface for visual planning/standups while keeping CLI as source of action.

ao web --host 127.0.0.1 --port 8042

14) Human mode and agent mode (same commands)

Humans can use default rich output, while agents can switch to deterministic JSON.

ao ls --view table
ao --yes --format json ls --status todo --limit 20

Quick usage

Human developer flow

ao add "Implement feature flag support" --type feat --priority high
ao next
ao ls --view kanban
ao gate

Agent-friendly flow

ao --yes --format json add "Fix timeout regression" --type bug --priority high
ao --yes --format json ls --status todo --limit 20
ao --yes --format json next

Skill categories (overview)

AO skills are organized by intent. Here are the major buckets used in this repository:

1. Plan & execute — create plans, refine scope, run batch execution safely.
2. Quality & review — perform reviews, enforce gates, validate outcomes.
3. Debug & recovery — isolate failures, recover state, prevent drift.
4. Git & collaboration — branch/worktree/PR/review automation.
5. Research & discovery — turn ideas into evidence-backed actionable work.
6. Documentation & reporting — generate docs, reports, retros, narratives.
7. Web & design artifacts — frontend design, Playwright, web assets/artifacts.
8. Meta-governance — constitution, state, confidence calibration, workflow hygiene.

Skill overview (high-impact set)

• ao-task — create/refine/manage issues.
• ao-planning — produce validated implementation plans.
• ao-implementation — implement from approved plan with strict discipline.
• ao-review — depth-based code review.
• ao-validation — run quality gates before commit/merge.
• ao-focus-scan — maintain current work queue and focus state.
• ao-auto — autonomous issue execution mode with confidence controls.
• ao-recovery — recover safely from broken state/build failures.
• ao-github — synchronize AO and GitHub Issues.
• ao-report — generate progress/backlog/status reports.

Built-in skills (complete catalog, short summary)

92 skills are currently present in .ao/skills/.

• ao-adversary — adversarial reviewer to find edge-case failure modes.
• ao-article-verification — verify written claims with evidence and structured checks.
• ao-astro-docs — scaffold and maintain Astro docs sites.
• ao-auto — autonomous execution for normal/high-confidence issues.
• ao-baseline — capture baseline build/lint/test state and compare later.
• ao-branch-workflow — standardized branch/worktree setup workflow.
• ao-build — language-aware build pipeline orchestration.
• ao-calibrator — challenge and calibrate confidence estimates.
• ao-cognitive-load — track and budget complexity introduced by changes.
• ao-complete — verify completion before marking done.
• ao-confidence-decay — decay stale confidence over time.
• ao-constitution — create/update project constitution rules.
• ao-context-map — build concise LLM-optimized project map.
• ao-create-python-project — plan a production-grade Python project.
• ao-create-skill — create new AO skills via interview/clone modes.
• ao-create-technical-docs — generate focused technical documentation.
• ao-debugging — systematic defect isolation and debugging.
• ao-dependencies — dependency updates and security handling.
• ao-docs — manage README/changelog/API documentation.
• ao-docx — create/read/edit Word documents.
• ao-dogfood — baseline project understanding from public docs.
• ao-epic-analyzer — AI-assisted epic assignment suggestions.
• ao-execute — execute plans in reviewed batches.
• ao-focus-scan — update focus queues from issue state.
• ao-frontend-design — create polished, distinctive frontend UX.
• ao-gh-actionable-comments — extract actionable PR review items via gh.
• ao-gh-pr-info — pull comprehensive PR metadata/comments via gh.
• ao-gherkin-step-generator — generate SpecFlow steps from Gherkin files.
• ao-git — safe git operations and stale state checks.
• ao-git-analysis — repository insight reports from git history.
• ao-git-story — narrative summaries from git evolution.
• ao-git-worktree — manage isolated worktrees.
• ao-github — sync AO issues with GitHub issues.
• ao-guide — interactive workflow guidance.
• ao-housekeeping — hygiene checks across project/doc/git state.
• ao-idea — convert rough ideas into backlog issues.
• ao-impl-details — generate implementation detail docs by depth.
• ao-implementation — code from approved plan with small verified diffs.
• ao-improvement-discovery — discover improvement opportunities from context.
• ao-init — initialize/repair .agent/ops state files.
• ao-install — install AO into projects, including folder merges.
• ao-intent-drift — detect divergence from issue intent/spec.
• ao-interview — structured one-question-at-a-time interviewing.
• ao-issue-merge — merge/reconcile AO JSONL event streams.
• ao-junior-explain — explain solutions at junior-friendly depth.
• ao-lint-instructions — validate instruction/prompt/skill files.
• ao-llm-export — export skills/agents/prompts for LLM consumption.
• ao-markdown-jira — convert Markdown to Jira wiki markup.
• ao-mermaid — GitHub-safe Mermaid diagram guidance.
• ao-migrate — migrate projects while preserving behavior.
• ao-mkdocs — manage MkDocs sites lifecycle.
• ao-narrative-audit — ensure consistency across code/issues/docs/story.
• ao-optimize-instructions — reduce instruction context without losing meaning.
• ao-parallel — dispatch parallel agents for independent issues.
• ao-plan-integrate-review — fold review decisions back into canonical plans.
• ao-plan-preview — generate stakeholder-friendly plan previews.
• ao-plan-review-import — import PR review comments into plan-review format.
• ao-planning — produce thorough pre-implementation plans.
• ao-playwright — browser automation with Playwright.
• ao-postmortem — structured blameless failure analysis.
• ao-potential-discovery — extract potential value from incoming materials.
• ao-pptx — create/read/edit PowerPoint presentations.
• ao-project-sections — map project sections (API/frontend/db/etc.).
• ao-prove-your-worth — challenge feature value with evidence.
• ao-reality-audit — verify claims against implementation reality.
• ao-recovery — failure recovery with guarded actions.
• ao-report — issue-based markdown reporting (status/progress/backlog).
• ao-research — deep research with optional issue creation.
• ao-retrospective — capture durable learnings into memory.
• ao-review — configurable-depth code reviews.
• ao-review-domain — domain-specific review modes.
• ao-review-response — process review feedback with evidence-based responses.
• ao-selective-branch — create clean PR branches excluding AO ops files.
• ao-selective-merge — keep clean branches updated with selected changes.
• ao-shadow-plan — create dissenting alternative plans.
• ao-skill-fatigue — detect repetitive skill misuse/workflow smell.
• ao-skills-advisor — recommend external skills from context.
• ao-skills-sh — discover/fetch skills from skills.sh.
• ao-spec — manage specs in .agent/ops/specs/.
• ao-state — maintain .agent state files consistently.
• ao-task — issue management (create/refine/bulk/export).
• ao-temporal-risk — evaluate 3/6/12 month risk horizons.
• ao-testing — test strategy, execution, and coverage analysis.
• ao-time-report — time tracking summaries by issue/epic/period.
• ao-tools — detect and track available development tools.
• ao-update — update AO files from newer versions.
• ao-validation — pre-commit/pre-merge validation checks.
• ao-versioning — semantic versioning + changelog/release notes.
• ao-web-artifacts — build interactive single-page web artifacts.
• ao-web-assets — generate favicons/manifest/social images.
• ao-youtube-transcript — extract YouTube transcripts for research.
• aoi-usage — guidance for autonomous AO CLI JSON workflows.

Prompt library

AO also ships prompt shortcuts in .github/prompts/ (for example: ao-plan, ao-task, ao-implement, ao-review, ao-validation, ao-help). These prompts map common workflows to consistent issue-first execution patterns.

Architecture at a glance

• events.jsonl — append-only event history
• active.jsonl — derived active snapshot
• src/ao/cli.py — command routing and user interface
• src/ao/api.py — programmatic API client
• src/ao/_internal/ — core implementation modules
• src/ao/web/ — web UI and API surfaces

Release and publishing

• Package name: agent-ops-cli
• CLI name: ao
• GitHub workflow: .github/workflows/python-publish.yml
• Local fallback publish: uv build + uvx twine check dist/* + twine upload

---

If you want to run development with fewer surprises: keep AO as your single source of workflow truth, and let humans + agents collaborate through the same issue/event substrate.