---
name: ao-usage
description: "How an autonomous agent should use the AO CLI (Agent Ops Issues) with plain JSON I/O, deterministic behavior, and minimal merge conflicts."
version: "0.1.0"
category: core
invokes: []
invoked_by: [ao-task, ao-planning, ao-implementation, ao-complete]
state_files:
  read: [issues/events.jsonl, issues/active.jsonl]
  write: [issues/events.jsonl, issues/active.jsonl]
entrypoint: ao
audience: [agent]
requires:
  tools:
    - ao
  files:
    - ".agent/ops/issues/events.jsonl (optional)"
    - ".agent/ops/issues/active.jsonl (optional)"
defaults:
  flags: ""
---

# AO Usage Skill

## Purpose

Use `ao` to read, create, and update issues in a deterministic, automation-safe way. Treat `events.jsonl` as append-only source of truth and `active.jsonl` as a snapshot.

## Flag Guidelines

Most `ao` commands work without any global flags:

- `--yes` is **only needed** for interactive commands: `compact`, `triage`, `worktree`, `profile create`
- When `--yes` is set, `--format json` and `--progress none` are **auto-applied** — never add them explicitly
- Commands like `add`, `set`, `close`, `log`, `ls`, `show`, `next`, `ac`, `link`, `label`, `rebuild` need **no global flags**

## Non-negotiables

- Prefer minimal-diff operations (patch/log/acceptance toggles) rather than full replacements.
- If a command fails, report `error.code`, `error.message`, and any `details`.

## Command Templates

### 1) List issues (fast path)

Get all active issues:

```bash
ao ls
```

Get only IDs (for routing/queueing):

```bash
ao ls --view ids
```

Filter (flags):

```bash
ao ls --status todo --priority high --type bug
```

Filter (query tokens):

```bash
ao ls status:todo prio:high type:bug
```

### 2) Show one issue (full data)

```bash
ao issue show ISSUE_ID
```

### 3) Create issue (plain JSON input via stdin)

Input schema: `IssueCreateInput`

```bash
printf '%s' '{"title":"<TITLE>","type":"bug","priority":"high","status":"todo","epic":"<EPIC>","owner":"agent","confidence":"normal","requirements":[],"acceptance_criteria":[],"notes":""}' | ao issue add --in -
```

### 4) Update issue (preferred: JSON patch)

Input schema: `IssuePatchInput`

```bash
printf '%s' '{"set":{"status":"in_progress","owner":"agent"},"append":{"log":[{"ts":"YYYY-MM-DD","text":"<LOG>"}]}}' | ao issue patch ISSUE_ID --in -
```

### 5) Append log entry (minimal change)

```bash
ao log add ISSUE_ID "<TEXT>"
```

### 6) Acceptance criteria operations

Check AC item by index:

```bash
ao ac check ISSUE_ID 1
```

Add new AC item:

```bash
ao ac add ISSUE_ID "<CRITERION>"
```

### 7) Dependencies / links

Add dependency:

```bash
ao link add ISSUE_ID --depends-on OTHER_ID
```

Add blocking edge:

```bash
ao link add ISSUE_ID --blocks OTHER_ID
```

### 8) Reference docs for planning

Create and attach a planning doc:

```bash
ao ref init ISSUE_ID
```

Attach an existing doc:

```bash
printf '%s' '{"set":{"references":{"spec_file":".agent/ops/issues/references/<ISSUE_ID>.md"}}}' | ao issue patch ISSUE_ID --in -
```

### 9) Close / reopen

Close with log:

```bash
ao issue close ISSUE_ID --log "<SUMMARY>" --status done
```

Reopen:

```bash
ao issue reopen ISSUE_ID --log "<WHY>"
```

### 10) Rebuild snapshot (optional)

Use if you need immediate consistency:

```bash
ao rebuild
```

## Recommended Agent Workflow

### Step A — Choose work

1. List candidate issues:
   - Prefer high priority + ready:
  - `ao next --limit 10`
2. Fetch full details for selected issue:
   - `ao issue show ISSUE_ID`

### Step B — Claim work

Set status `in_progress` and owner:

```bash
printf '%s' '{"set":{"status":"in_progress","owner":"agent"},"append":{"log":[{"ts":"YYYY-MM-DD","text":"Started work"}]}}' | ao issue patch ISSUE_ID --in -
```

### Step C — Plan and attach references (if needed)

1. If `references.spec_file` missing and planning is needed:
   - `ao ref init ISSUE_ID`
2. Add planning notes/log entries using `ao log add` or patch `notes`.

### Step D — Update during execution

- Use `ao issue patch` for scalar updates and log appends.
- Use `ao ac check` as acceptance criteria are met.
- Use `ao link add` when discovering dependencies/blocks.

### Step E — Complete

1. Ensure AC is satisfied (agent responsibility).
2. Close with clear log summary:

```bash
ao issue close ISSUE_ID --log "Completed: <what changed and why>" --status done
```

## Error Handling Protocol

- If `ok:false`, capture:
  - `error.code`
  - `error.message`
  - `error.details`
- For `VALIDATION_ERROR`, fix input and retry once.
- For `CONFLICT/LOCK` errors, retry with backoff (e.g., 250ms, 1s, 2s) up to 3 times.
- For `INTEGRITY` errors (cycles, impossible transitions), stop and report.

## Minimal JSON Schemas (for agent reference)

### IssueCreateInput

```json
{
  "title": "...",
  "type": "bug",
  "priority": "high",
  "status": "todo",
  "epic": "",
  "owner": "agent",
  "confidence": "normal",
  "requirements": [],
  "acceptance_criteria": [],
  "scope": {
    "files_to_change": [],
    "files_must_not_change": []
  },
  "dependencies": {
    "depends_on": [],
    "blocks": []
  },
  "references": {
    "spec_file": ""
  },
  "notes": ""
}
```

### IssuePatchInput

```json
{
  "set": {},
  "unset": [],
  "append": {
    "log": [
      {"ts": "YYYY-MM-DD", "text": "..."}
    ]
  }
}
```

## Safety and Merge Behavior

- Prefer `ao issue patch` and specialized subcommands (`ac`, `log`, `link`) to minimize conflicts.
- Do not attempt to edit JSONL files directly; always use `ao`.
- Treat `events.jsonl` as append-only; never rewrite it.

## Completion Criteria

- [ ] Agent uses `ao` commands without redundant flags (no `--yes` for non-interactive commands)
- [ ] No interactive prompts triggered during automated workflows
- [ ] All issue mutations go through `ao` CLI, never direct file edits
- [ ] Error responses are captured and handled per protocol
- [ ] `events.jsonl` is treated as append-only

## Anti-patterns (avoid)

- ❌ Using `--yes --format json --progress none` on every command (most don't need flags)
- ❌ Editing `events.jsonl` or `active.jsonl` directly
- ❌ Using interactive prompts in automated workflows
- ❌ Full issue replacement when a patch suffices
- ❌ Ignoring error codes from `ao` commands
- ❌ Rewriting `events.jsonl` instead of appending
