---
name: ao-update
description: "Update AO files from a newer version while preserving project state."
category: core
invokes: [ao-state]
invoked_by: []
state_files:
  read: [focus.json]
  write: [focus.json]
reference: [REFERENCE.md]
---

# AO Update

Update AO core files from a newer version while preserving your project-specific state.

## MANDATORY PRE-CHECK: Clean Git Status

**CRITICAL: BEFORE any update operation, the working tree MUST be clean.**

```bash
# Check git status BEFORE proceeding
git status --porcelain
```

**IF dirty working tree detected:**
- **ABORT IMMEDIATELY** with clear error message
- **NEVER auto-stash** (risk of silent data loss)
- **NEVER proceed** with dirty state (breaks rollback)
- Provide instructions to user:
  1. Commit or stash changes manually
  2. Re-run ao-update after cleaning

**IF clean working tree:**
- Proceed with update operation

## Protected Files (NEVER Overwrite)

The following files are **PROTECTED** and will NEVER be overwritten:

- `.agent/ops/*` - All operations state files
  - `constitution.md`
  - `memory.md`
  - `baseline.md`
  - `focus.json`
  - `issues/*.md`
  - `history.md`
  - Any other operations state files

- `CLAUDE.md` - User's configuration (if exists at project root)

- `AGENTS.md` - User's documentation (if exists at project root)

**These files contain user state, configurations, and documentation.**

## Update Scope

**Only updates `.ao/*` skill files:**
- `.ao/skills/*/SKILL.md`
- `.ao/skills/*/REFERENCE.md`
- `.ao/agents/*.md`
- `.ao/prompts/*.md`
- `.ao/commands/*.md`

## Usage

```
/ao-update /path/to/new/ao/version [--dry-run] [--yes]
```

## Safety Features

1. **Pre-check**: Verifies clean git status before any operation
2. **Protected files**: Never overwrites `.agent/ops/*`, `CLAUDE.md`, or `AGENTS.md`
3. **Scope limit**: Only modifies `.ao/*` skill files
4. **Rollback**: Clean working tree enables safe rollback if needed

## What Gets Updated

- Core AO skills (`.ao/skills/*`)
- AO prompts (`.ao/prompts/*`)
- Agent definitions (`.github/agents/*`, `.claude/agents/*`)
- Command files (`.claude/commands/ao-*`, `.opencode/commands/ao-*`)

## What Gets Preserved

- Project state (`.agent/ops/*`) - PROTECTED
- `CLAUDE.md` - User config - PROTECTED
- `AGENTS.md` - User docs - PROTECTED
- Your skill preferences (merged, your keys win)

## Examples

**Good (clean working tree):**
```
$ /ao-update /path/to/new/ao
✓ Clean working tree detected
✓ Backup created: .agent/ops/backups/ao-update/2025-01-15-143022/
✓ Updated 12 skill files
✓ Skipped 3 protected files
```

**Bad (dirty working tree):**
```
$ /ao-update /path/to/new/ao
✗ ERROR: Working tree is dirty
✗ Cannot proceed with update (safety check failed)

Dirty files:
  M .agent/ops/focus.json
  M CLAUDE.md

Instructions:
  1. Commit or stash your changes
  2. Re-run /ao-update

Reason: Clean working tree required for safe rollback.
```

## Reference

See [REFERENCE.md](REFERENCE.md) for detailed procedures, file lists, and rollback documentation.

---

## Next Steps

After update completes, ask what to do next:

- [Review] Review the changes with git diff
- [Commit] Create commit and merge to main
- [Rollback] Revert the update
- [Help] Show all available options
