---
name: ao-guide
description: "Interactive workflow guide. Use when user is unsure what to do next, needs help navigating AO, or wants to understand available tools."
category: utility
invokes: [ao-interview, ao-state]
invoked_by: []
state_files:
  read: [constitution.md, focus.json, issues/*.md, baseline.md, memory.md]
  write: [focus.json]
---

# AO Workflow Guide

## Purpose

Help users navigate the AO workflow by asking diagnostic questions and recommending the appropriate next step.

## When to Use

- User says "help", "what should I do", "where do I start"
- User seems lost or confused about workflow
- User wants to understand available tools
- First time using AO in a project

## Diagnostic Procedure

### Step 1: Assess State Files

First, silently check which state files exist:

```
□ .agent/ops/constitution.md  → Project setup complete?
□ .agent/ops/baseline.md      → Baseline captured?
□ .agent/ops/focus.json         → Has session context?
□ .agent/ops/issues/          → Has defined issues?
□ .agent/ops/memory.md        → Has learned conventions?
```

### Step 2: Ask Situational Question

Ask ONE question to understand user's intent:

> "What brings you here today?"
> 
> **A)** Starting a new project or first time here
> **B)** Returning to continue previous work
> **C)** Have a specific task or feature to implement
> **D)** Something's broken and need to fix it
> **E)** Want to explore or understand the codebase
> **F)** Need to review code quality
> **G)** Wrapping up work, ready to commit
> **H)** Want to create a new Python project
> **I)** Need to review/audit an API

### Step 3: Recommend Based on State + Intent

| Intent | Missing Constitution | Missing Baseline | Has Tasks | Recommendation |
|--------|---------------------|------------------|-----------|----------------|
| A (new) | ✗ | — | — | `/ao-init` then `/ao-constitution` |
| A (new) | ✓ | ✗ | — | `/ao-baseline` |
| B (resume) | — | — | — | Read focus.json, summarize status |
| C (task) | ✗ | — | — | `/ao-constitution` first |
| C (task) | ✓ | ✗ | — | `/ao-baseline` first |
| C (task) | ✓ | ✓ | ✗ | `/ao-task` to define task |
| C (task) | ✓ | ✓ | ✓ | `/ao-plan` for next task |
| D (broken) | — | — | — | `/ao-debug` then `/ao-recover` |
| E (explore) | — | — | — | `/ao-map` or `ao-critical-review` |
| F (review) | — | — | — | `/ao-review` or `/ao-validation` |
| G (finish) | — | ✗ | — | `/ao-baseline` then `/ao-review` |
| G (finish) | — | ✓ | — | `/ao-validation` then `/ao-review` |
| H (python) | — | — | — | `/ao-create-python-project` |
| I (api) | — | — | — | `/ao-api-review` |

### Step 4: Provide Clear Next Step

Format your recommendation as:

```markdown
## Your Situation
[One sentence summary of what I detected]

## Recommended Next Step
**Run:** `/ao-[command]`
**Why:** [Brief reason]

## After That
[What comes next in the workflow]
```

## Decision Trees

### "I'm new here"

```
Has .agent/ops/ folder?
├─ NO → /ao-init
└─ YES
   Has constitution.md with CONFIRMED commands?
   ├─ NO → /ao-constitution
   └─ YES
      Has baseline.md?
      ├─ NO → /ao-baseline
      └─ YES → Ready! Ask what they want to build
```

### "I have a task"

```
Task well-defined (clear acceptance criteria)?
├─ NO → /ao-task (refine it)
└─ YES
   Have baseline?
   ├─ NO → /ao-baseline
   └─ YES
      Have approved plan?
      ├─ NO → /ao-plan
      └─ YES → /ao-implement
```

### "Something's broken"

```
What's broken?
├─ Build fails → /ao-debug then /ao-recover
├─ Tests fail → /ao-debug (compare to baseline)
├─ Agent stuck → Read focus.json, identify blocking issue
├─ Git issues → ao-git skill
└─ Unknown cause → /ao-debug (systematic isolation)
```

### "I want to create a Python project"

```
Have requirements/discussion?
├─ YES → /ao-create-python-project (with input)
└─ NO → /ao-create-python-project (will interview)
```

### "I need to review an API"

```
Has OpenAPI spec?
├─ YES → /ao-api-review
└─ NO 
   Has API endpoints?
   ├─ YES → /ao-api-review (will identify spec gaps)
   └─ NO → Not an API project, use /ao-review
```

### "I'm done"

```
Changes validated?
├─ NO → /ao-validation
└─ YES
   Critical review done?
   ├─ NO → /ao-review
   └─ YES
      Retrospective done?
      ├─ NO → /ao-retrospective
      └─ YES → Ready to commit (with confirmation)
```

## Quick Reference Card

Present this when user asks for overview:

```
┌───────────────────────────────────────────────────────────────┐
│                     AO Workflow                         │
├───────────────────────────────────────────────────────────────┤
│  SETUP          │  WORK             │  FINISH                 │
│─────────────────│───────────────────│─────────────────────────│
│  /ao-init    │  /ao-task      │  /ao-validation      │
│  /ao-const   │  /ao-plan      │  /ao-review          │
│  /ao-base    │  /ao-impl      │  /ao-retrospective   │
├───────────────────────────────────────────────────────────────┤
│  UTILITIES                                                    │
│───────────────────────────────────────────────────────────────│
│  /ao-help        Interactive guide (you are here)          │
│  /ao-map         Understand codebase                       │
│  /ao-testing     Test strategy                             │
│  /ao-spec        Manage requirements                       │
│  /ao-report      View issues and status                    │
│  /ao-version     Versioning and changelog                  │
├───────────────────────────────────────────────────────────────┤
│  SPECIALIZED                                                  │
│───────────────────────────────────────────────────────────────│
│  /ao-debug                Systematic debugging             │
│  /ao-api-review           API contract & behavior audit    │
│  /ao-create-python-project   Scaffold Python project       │
└───────────────────────────────────────────────────────────────┘
```

## Anti-Patterns

- ❌ Overwhelming user with all options at once
- ❌ Recommending steps when prerequisites aren't met
- ❌ Skipping constitution/baseline for "quick" tasks
- ❌ Assuming user knows the workflow

## Output

After guiding user, update `.agent/ops/focus.json`:
```markdown
## Doing now
- Guided user to [recommended step]
- Reason: [why this step]
```
