---
name: ao-help
description: "Interactive guide to find the right AO workflow step based on your current situation"
---

# AO Workflow Guide

Help me understand where you are so I can guide you to the right next step.

## Quick Assessment

I'll ask you a few questions to figure out what you need. Answer briefly:

**Question 1**: What's your situation?

A) **Starting fresh** — New project or first time using AO here
B) **Resuming work** — Continuing from a previous session
C) **Got a task** — Have something specific to implement
D) **Something broke** — Build failing, tests failing, or stuck
E) **Just exploring** — Want to understand the codebase or find improvements
F) **Reviewing code** — Need to review changes or do a quality check
G) **Finishing up** — Done with implementation, need to wrap up
H) **New Python project** — Want to create a production-ready Python project
I) **API audit** — Need to review an API for contract alignment & correctness

---

## Guided Paths

Based on your answer, here's what to do:

### A) Starting Fresh
```
1. /ao-init          → Create .agent/ops/ state files
2. /ao-constitution  → Define project boundaries & commands
3. /ao-baseline      → Capture build/test baseline
```

### B) Resuming Work
```
1. Read .agent/ops/focus.md to see where you left off
2. Continue with the appropriate workflow step
```

### C) Got a Task
```
Is the issue well-defined?
  YES → /ao-plan (create implementation plan)
  NO  → /ao-task (refine the issue first)

Do you have a baseline?
  NO  → /ao-baseline first
  YES → Proceed with planning
```

### D) Something Broke
```
1. /ao-debug    → Systematic debugging to find root cause
2. /ao-testing  → Run tests to verify fix
3. Check .agent/ops/baseline.md for comparison
```

### E) Just Exploring
```
- /ao-map         → Generate codebase overview
- /ao-review      → Deep code review of specific area
```

### G) Finishing Up
```
1. /ao-validation    → Run quality gates
2. /ao-review        → Critical review + baseline comparison
3. /ao-retrospective → Capture learnings
```

---

## All Available Commands

| Command | Purpose |
|---------|---------|
| `/ao-init` | Bootstrap .agent/ops/ state files |
| `/ao-update` | Update AO from newer version |
| `/ao-constitution` | Define project scope & commands |
| `/ao-baseline` | Capture build/test baseline |
| `/ao-plan` | Multi-iteration planning |
| `/ao-implement` | Execute approved plan |
| `/ao-task` | Create or refine issues |
| `/ao-spec` | Manage specifications |
| `/ao-validation` | Pre-commit quality checks |
| `/ao-testing` | Test strategy & execution |
| `/ao-review` | Critical review + baseline check |
| `/ao-retrospective` | Capture session learnings |
| `/ao-map` | Generate codebase overview |
| `/ao-report` | View issues and status |
| `/ao-time-report` | View accumulated time-tracking data |
| `/ao-version` | Versioning and changelog |
| `/ao-housekeeping` | Archive completed issues |
| `/ao-help` | This guide |
| `/ao-debug` | Systematic debugging |
| `/ao-api-review` | API contract & behavior audit |
| `/ao-create-python-project` | Scaffold Python project |

---

## State File Quick Reference

| File | Contains | Check when... |
|------|----------|---------------|
| `.agent/ops/constitution.md` | Commands, boundaries | Starting work, unsure what's allowed |
| `.agent/ops/focus.md` | Current status | Resuming, lost context |
| `.agent/ops/issues/events.jsonl` | Issue event log (use `ao ls` to query) | Need work items (critical/high/medium/low) |
| `.agent/ops/baseline.md` | Build/test baseline | Comparing before/after |
| `.agent/ops/memory.md` | Durable learnings | Checking conventions |
| `.agent/ops/time-tracking.json` | Session time tracking | View time spent, /ao-time-report |

## Issue ID Format

`{TYPE}-{NUMBER}@{HASH}` — e.g., `BUG-0023@efa54f`, `FEAT-0001@c2d4e6`

Types: `BUG` | `FEAT` | `CHORE` | `ENH` | `SEC` | `PERF` | `DOCS` | `TEST` | `REFAC`

---

Interview the user to determine their current situation and guide them to the appropriate AO workflow step.

---

## Next Steps

After helping the user, offer relevant next steps based on their situation.
