Metadata-Version: 2.4
Name: agent-ops-cli
Version: 0.6.0
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: pyyaml>=6.0
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 system for **humans and autonomous agents**.
It combines event-sourced issue tracking, deterministic automation, worktree-first execution,
and a web Kanban UI into one workflow.

![AO logo](assets/images/logo.png)

## Why AO

AO is designed for teams that want to:

- capture and execute work quickly
- reduce merge conflicts through explicit workflow expectations
- maintain durable, replayable issue history
- support both human and agent execution with the same commands

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

## What's New (latest additions)

### Web UI workflow improvements

- **Top-level tabs** split the interface into:
  - `Kanban Board`
  - `Branch Worktrees`
- **Single Workflow field** in issue create/edit:
  - `No special workflow requirements` (default)
  - `Separate worktree required`
  - `Stacked diffs preferred`
  - `Stacked diffs + separate worktree`
- **Workflow helper text** now updates dynamically under the dropdown.
- **Branch Worktree launch default** now prefers `Editor (config)` automatically.
- **Force remove worktree action** with confirmation for destructive cleanup.

### Code host integration (Gitea + GitHub)

- **CodeHost abstraction** — `ao stack push` works with both GitHub and Gitea via a unified provider layer.
- **Gitea support** — local Gitea instance via `docker-compose.yml` for integration testing.
- **Environment-based provider selection** — set `CODE_HOST_TARGET=gitea` and `CODE_HOST_TOKEN` to switch providers.
- **Graceful fallback** — when no token is configured, stack commands fall back to the `gh` CLI.

### Versioning behavior

- Issue `version` defaults from `.version` when omitted.
- For Python projects, `.version` must match `pyproject.toml` `project.version`.
- Added `ao version` commands for synchronized version updates.

## UI overview

### Kanban tab

Use this for triage, assignment, and status/priority movement.

![Kanban Board tab](assets/images/kanban.png)

### Branch Worktrees tab

Use this for isolated branch workspaces, launcher actions, and git worktree operations.

![Branch Worktrees tab](assets/images/worktrees.png)

## 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 below assume AO is installed as a tool.
> Use `uv run ...` for development commands (tests/lint/build).

## Quick start

### Human flow

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

### Agent/automation flow (JSON)

```bash
ao add "Fix timeout regression" --type bug --priority high
ao ls --status todo --limit 20
ao next
```

## Profiles (personal context + workspace preferences)

AO profiles let you keep reusable personal metadata and per-profile preferences,
then apply them consistently across repositories and agent workflows.

### When profiles are useful

- You work across multiple identities (personal/client/internal).
- You want deterministic `.env` materialization for common variables.
- You want a separate preferences file per profile with workspace sync.

### Typical profile workflow

```bash
ao profile init my-main \
  --full-name "Jane Doe" \
  --email "jane@example.com" \
  --github-username "janedoe" \
  --website "https://example.com" \
  --editor code \
  --var TEAM=platform \
  --var AO_MODE=agent

ao profile ls
ao profile use my-main
ao profile show
```

### Update profile fields and vars

```bash
ao profile set my-main --var TEAM=core --var LANG=python --unset-var AO_MODE
ao profile show my-main
```

### Apply profile data into `.env`

```bash
ao profile env apply my-main .env
```

This writes/updates keys like `FULL_NAME`, `EMAIL`, `GITHUB_USERNAME`, optional `WEBSITE`,
and any custom `--var` entries.

### Profile preferences commands

```bash
ao profile prefs open my-main
ao profile prefs sync my-main
```

`prefs open` opens the profile preferences markdown in your configured editor.
`prefs sync` keeps home and workspace preference files aligned (newest wins).

## Worktree + stacked-diff guide

This is the recommended model for parallel, low-conflict execution.

### Workflow modes in issues

| Workflow selection | Intended behavior |
| --- | --- |
| No special workflow requirements | Normal branch flow; no special constraints |
| Separate worktree required | Must execute in dedicated worktree |
| Stacked diffs preferred | Prefer layered PRs/commits in sequence |
| Stacked diffs + separate worktree | Layered changes plus strict workspace isolation |

### Example 1: Small standalone bug fix (no special workflow)

Use this when scope is tiny and independent.

```bash
ao add "Fix typo in API error" --type bug --priority low
ao next
ao gate
ao close BUG-0001@abc123 --log "Fixed and verified"
```

### Example 2: Isolated risky change (separate worktree required)

Use this when local changes may conflict with ongoing work.

```bash
ao add "Refactor event parser" --type refac --priority medium --separate-worktree required
ao worktree add --epic parser --step 1 --summary refactor-core --open editor
ao worktree ls
```

### Example 3: Feature split into reviewable layers (stacked diffs preferred)

Use this when one feature is best reviewed as sequential pieces.

```bash
ao add "Add notifications feature" --type feat --priority high --stacked-diff yes
ao worktree plan --epic notifications --max-files 6 --max-loc 300
ao worktree add --epic notifications --step 1 --summary schema
ao worktree add --epic notifications --step 2 --summary api
ao worktree add --epic notifications --step 3 --summary ui
```

### Example 4: Full isolation + stacked delivery

Use this for high-risk or long-running epics.

```bash
ao add "Migrate auth subsystem" --type feat --priority high --stacked-diff yes --separate-worktree required
ao worktree plan --epic auth
ao worktree add --epic auth --step 1 --summary bootstrap --open opencode
ao worktree land --epic auth
ao worktree land --epic auth --final --target main --ci-green --approved
```

### Branch Worktrees tab usage (practical)

1. Open `Branch Worktrees` tab.
2. Confirm source branch and discovered worktrees.
3. Choose launcher (defaults to `Editor`) and click `Open`.
4. Choose a git action from `Git action...` and click `Run`.
5. For `Force remove`, confirm the safety prompt.

### Troubleshooting quick hits

- **Launcher unavailable**: install tool or use `Editor`.
- **Protected branch blocked**: switch to non-protected integration branch.
- **Worktree remove fails**: retry with `Force remove` only when safe.

For complete policy, recovery, and gate semantics: see `docs/worktree-stacked.md`.

## Core CLI capabilities

### Issue lifecycle

```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"
```

### Event-sourced state

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

### Prioritization and execution

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

### Dependencies and planning

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

### Acceptance criteria and gates

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

### Focus and handoff

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

### Hooks and automation

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

For an end-to-end guide to testing the standalone GitHub Copilot CLI autonomous loop, see `docs/copilot-autonomous-loop.md`.

### Workers and assignment

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

### References and traceability

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

### Reporting and export

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

### Web UI

```bash
ao web --host 127.0.0.1 --port 8042
```

## Versioning and release management

### Issue version metadata (`.version`)

- If issue `version` is omitted, AO defaults from `.version`.
- Python projects require `.version == pyproject.toml project.version`.
- Non-Python projects use `.version` as source-of-truth when present.

### Project version command

- `ao version set X.Y.Z`
- `ao version bump patch|minor|major`
- `ao version ... --dry-run` to preview file updates

You can also configure extra replacement targets in `pyproject.toml`:
`[[tool.ao.version.targets]]` with `path`, `pattern`, and `replace`.

## Code host integration

AO supports both **GitHub** and **Gitea** as code hosts for pull request operations
in stacked-diff workflows.

### Configuration

Set environment variables to select a provider:

```bash
# GitHub (default)
export CODE_HOST_TOKEN="ghp_..."

# Gitea
export CODE_HOST_TARGET=gitea
export CODE_HOST_TOKEN="your-gitea-token"
export CODE_HOST_BASE_URL="http://localhost:3000/api/v1"  # optional, defaults to localhost
```

Or configure via `~/.ao/config.json`:

```json
{
  "code_host": {
    "target": "gitea",
    "token": "your-token",
    "base_url": "http://localhost:3000/api/v1"
  }
}
```

When no token is configured, `ao stack push` falls back to the `gh` CLI.

### Local Gitea for testing

A `docker-compose.yml` is provided at the project root:

```bash
docker compose up -d     # Start Gitea on localhost:3000
docker compose down      # Stop
```

This creates a local Gitea instance with SQLite storage and an admin user,
ready for integration testing.

## Architecture at a glance

- `events.jsonl` — append-only event history
- `active.jsonl` — derived active snapshot
- `src/ao/cli.py` — command routing and UX
- `src/ao/api.py` — programmatic API client
- `src/ao/_internal/` — internal implementation modules
- `src/ao/_internal/codehost.py` — GitHub/Gitea provider abstraction
- `src/ao/web/` — web UI + API endpoints

## Skills and prompts

- Skills live in `.ao/skills/`
- Prompt shortcuts live in `.github/prompts/`
- Common prompts: `ao-plan`, `ao-task`, `ao-implement`, `ao-review`, `ao-validation`, `ao-help`

## Development notes

### Isolated workflow/integration tests (mandatory)

Before running integration/UI tests, start the test stack:

```bash
docker compose -f docker-compose.test.yml up -d
```

```bash
uv run python scripts/run_isolated_workflow_tests.py
```

This runs integration tests from an ephemeral temp working directory, not the repo root.

When finished:

```bash
docker compose -f docker-compose.test.yml down
```

### One-command local test orchestration (PowerShell)

On Windows/PowerShell, you can prepare dependencies, start the Gitea stack, launch an AO web server, and run both test lanes with:

```powershell
./scripts/run-all-tests.ps1
```

Useful switches:

- `-DryRun` — print the planned commands without executing them
- `-KeepDocker` — leave the Gitea test stack running after the script finishes
- `-KeepWebServer` — leave the AO web server running after the script finishes
- `-SkipWebServer` — run tests without starting the local AO web server helper
- `-IncludeBuild` — run the canonical build after the explicit test lanes

### Build/test commands

```bash
uv run python scripts/build.py
uv run pytest tests/ -v
```

## Publishing

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

---

Use AO as your workflow source of truth so humans and agents execute from the same issue/event substrate.
