# Issue Organization — Epics, Labels, Links, Dependencies, Acceptance Criteria

## Epics

Epics group related issues under a shared name.

```bash
# Set epic on issue creation
ao --yes add "Optimize parser" --epic "Performance Sprint"

# Change epic on existing issue
ao --yes set PERF-0050@aaa111 --epic "Performance Sprint"

# List all epics with counts
ao epic ls

# Show issues in a specific epic
ao epic show "Performance Sprint"

# Epic status/priority breakdown
ao epic summary "Performance Sprint"

# Rename an epic across all issues
ao --yes epic rename "Old Name" "New Name"

# AI-assisted epic assignment
ao epic analyze
```

## Labels

Labels are free-form tags on issues.

```bash
# Add a label
ao --yes label add FEAT-0042@abc123 "security"

# Remove a label
ao --yes label rm FEAT-0042@abc123 "security"

# List labels on an issue
ao label ls FEAT-0042@abc123

# Filter issues by label
ao ls --label "security"
```

## Dependency Links

Dependencies model `depends_on` / `blocks` relationships between issues.

```bash
# Add dependency: FEAT-0042 depends on FEAT-0001
ao --yes link add FEAT-0042@abc123 --depends-on FEAT-0001@aaa111

# Add reverse: FEAT-0001 blocks FEAT-0042
ao --yes link add FEAT-0001@aaa111 --blocks FEAT-0042@abc123

# Remove dependency
ao --yes link rm FEAT-0042@abc123 --depends-on FEAT-0001@aaa111

# Show dependency info for an issue
ao link show FEAT-0042@abc123

# Generate dependency graph
ao link graph

# Show dep tree with cycle detection
ao dep-tree FEAT-0042@abc123
```

### Typed Links

Beyond depends_on/blocks, typed links model other relationships:

```bash
# Mark as related
ao --yes link typed-add FEAT-0042@abc123 --related FEAT-0043@bbb222

# Mark as duplicate
ao --yes link typed-add BUG-0005@ccc333 --duplicate-of BUG-0003@ddd444

# Mark as discovered from
ao --yes link typed-add BUG-0010@eee555 --discovered-from FEAT-0042@abc123

# Parent/child
ao --yes link typed-add REFAC-0694@fff666 --child REFAC-0696@ggg777

# Remove typed link
ao --yes link typed-rm FEAT-0042@abc123 --related FEAT-0043@bbb222
```

Link types: `related`, `duplicate_of`, `discovered_from`, `parent`, `child`.

## Acceptance Criteria

Acceptance criteria are checklist items on issues.

```bash
# Add criterion
ao --yes ac add FEAT-0042@abc123 "All tests pass"
ao --yes ac add FEAT-0042@abc123 "Coverage >= 80%"

# List criteria
ao ac ls FEAT-0042@abc123

# Check (mark done)
ao --yes ac check FEAT-0042@abc123 1    # 1-based index

# Uncheck
ao --yes ac uncheck FEAT-0042@abc123 1

# Remove
ao --yes ac rm FEAT-0042@abc123 1
```

## Operational State

Dimension-value labels for cross-cutting state tracking:

```bash
# Set state dimension
ao --yes state set FEAT-0042@abc123 env:production

# Get state dimension
ao state get FEAT-0042@abc123 env
```
