Metadata-Version: 2.4
Name: agent-ops-cli
Version: 0.1.2
Summary: Agent Ops (AO) - high-performance JSONL issue/event store
License: GPL-3.0-or-later
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115.0
Requires-Dist: gitpython>=3.1.43
Requires-Dist: httpx>=0.28.1
Requires-Dist: jinja2>=3.1.0
Requires-Dist: msgspec>=0.18.0
Requires-Dist: mypy>=1.10.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pyperf>=2.7.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: rich>=13.7.0
Requires-Dist: ruff>=0.6.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: ai
Requires-Dist: pydantic-ai>=0.1.0; extra == 'ai'
Description-Content-Type: text/markdown

# 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)

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

### Local development checkout

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

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

### 12) Reporting and export workflows

Export machine-readable state and track performance trends.

```bash
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.

```bash
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.

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

## Quick usage

### Human developer flow

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

### Agent-friendly flow

```bash
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.
