# Issue Lifecycle — Create, Update, Close

## Creating Issues

```bash
ao --yes add "Title" --type feat --priority medium --epic "My Epic" --confidence normal
```

| Flag | Default | Values |
|------|---------|--------|
| `--type` | feat | feat, bug, refac, perf, docs, test, chore, sec, idea, enh, plan |
| `--priority` | backlog | critical, high, medium, low, backlog |
| `--status` | todo | todo, in_progress, blocked, review, pull_request, done, cancelled, dropped |
| `--epic` | — | Any string |
| `--owner` | agent | Any string |
| `--confidence` | normal | low, normal, high |
| `--label` | — | Comma-separated labels (e.g. `--label "ui,api"`) |
| `--body` | — | Body text stored as first log entry |
| `--stacked-diff` | optional | yes, no, optional |
| `--separate-worktree` | optional | required, optional, no |
| `--version` | from project | Semver string |

Returns: `{"ok": true, "result": {"issue_id": "FEAT-0042@abc123", "event_id": "evt-00000001", ...}}`

### Quick Capture with `idea`

Shortcut to create a backlog IDEA issue:

```bash
ao idea "Support webhooks" --epic "API" --body "Details here"
```

Equivalent to `ao add TITLE --type idea --priority backlog`.

## Viewing Issues

```bash
ao show FEAT-0042@abc123          # Full issue details (table)
ao --format json show FEAT-0042   # JSON output (short ID works too)
ao issue show FEAT-0042@abc123    # Same via issue subcommand
```

## Updating Issues

### Quick Scalar Updates

```bash
ao --yes set FEAT-0042@abc123 --status in_progress
ao --yes set FEAT-0042@abc123 --priority high --confidence low
ao --yes set FEAT-0042@abc123 --epic "New Epic" --notes "Updated scope"
```

### Batch Updates (comma-separated IDs)

```bash
# Update multiple issues at once
ao --yes set FEAT-0042,BUG-0005,ENH-0010 --priority high
ao --yes set FEAT-0042,FEAT-0043 --status in_progress --epic "Sprint 5"
```

| Flag | Description |
|------|-------------|
| `--status` | Change status |
| `--priority` | Change priority |
| `--owner` | Change owner |
| `--confidence` | Change confidence |
| `--epic` | Change epic |
| `--title` | Change title |
| `--notes` | Set/replace notes |
| `--external-ref` | External reference (JIRA-123, URL) |
| `--stacked-diff` | Stacked diff expectation |
| `--separate-worktree` | Worktree expectation |
| `--version` | Version metadata |

### Structured Patch (JSON)

```bash
echo '{"status": "in_progress", "notes": "Starting work"}' | ao --yes --in - issue patch FEAT-0042@abc123
```

## Adding Log Entries

```bash
ao --yes log add FEAT-0042@abc123 "Started implementation"
ao --yes log add FEAT-0042@abc123 "Fixed edge case in parser"
```

Log entries are timestamped and append-only. They appear in `ao show` output.

## Closing Issues

```bash
ao --yes close FEAT-0042@abc123 --log "Completed implementation"
ao --yes close BUG-0005@def456 --status cancelled --log "Duplicate of FEAT-0042"
ao --yes close IDEA-0010@ghi789 --status dropped --solution "Not feasible"
```

| Flag | Default | Description |
|------|---------|-------------|
| `--status` | done | Terminal status: done, cancelled, dropped |
| `--log` | — | Log message appended before close |
| `--solution` | — | Solution notes |

## Completion Verification

```bash
ao --yes complete FEAT-0042@abc123
```

Runs the completion gate: verifies issue is done, no open blockers, and optional validation commands pass.

## Typical Agent Workflow

```bash
# 1. Create issue
ao --yes add "Optimize query parser" --type perf --priority high

# 2. Start work
ao --yes set PERF-0050@aaa111 --status in_progress

# 3. Log progress
ao --yes log add PERF-0050@aaa111 "Profiled: 80% time in regex compilation"

# 4. Close when done
ao --yes close PERF-0050@aaa111 --log "Reduced query time by 60%"
```
