---
name: ao-update
description: "Update AO files from a newer version while preserving project state."
---

**MANDATORY: Always use the ao-worker agent for this workflow.**

# AO Update

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

## Usage

```
/ao-update [source_path] [--dry-run] [--yes] [--from-home]
```

## Arguments

- `source_path` - (Optional) Path to AO version, or leave empty to be prompted
- `--dry-run` - Show what would change without making changes
- `--yes` - Skip confirmation prompts
- `--from-home` - Auto-clone from https://github.com/weholt/ao.git

## Interactive Mode

When no arguments are provided, you'll be prompted:

```
Where would you like to update AO from?

[1] From official repository (https://github.com/weholt/ao.git)
    - Clones to temp folder automatically
    - Uses cached clone if available (faster)
    - Always gets the latest version

[2] From local path
    - Specify a local folder path

[3] From custom URL
    - Specify a git repository URL

[4] Cancel
```

## Quick Examples

### From official repository (recommended)
```bash
/ao-update --from-home
```

### Interactive (will ask)
```bash
/ao-update
```

### From local folder
```bash
/ao-update /path/to/ao/folder
```

### Preview only (dry-run)
```bash
/ao-update --from-home --dry-run
```

### Auto-confirm (skip prompts)
```bash
/ao-update --from-home --yes
```

## What This Does

1. **Asks where to update from** (interactive by default)
2. **Creates a git branch** (`ao-update-{timestamp}`) for safety
3. **Clones the repo** if using `--from-home` (cached for faster future updates)
4. **Categorizes files**:
   - **Protected**: `.agent/ops/*` - never touched
   - **Mergeable**: Preference files - your settings preserved
   - **Overwritable**: Core AO files - copied from new version
5. **Shows summary** of what will change
6. **Executes update** after confirmation
7. **Displays rollback instructions**

## Cache Behavior

When using `--from-home`, the repository is cached at:
- Unix/Linux/Mac: `/tmp/ao-cache/repo`
- Windows: `%TEMP%\ao-cache\repo`

The cache is **kept between updates** for faster subsequent updates.

On first run: `git clone --depth 1`
On subsequent runs: `git fetch` + `git reset --hard origin/main`

## Safety Features

- ✅ Creates git branch before any changes
- ✅ Preserves all `.agent/ops/*` files
- ✅ Merges preference files (your settings win)
- ✅ Warns about local modifications
- ✅ Interactive by default (asks before making changes)
- ✅ Documents rollback steps
- ✅ Uses cached clone (faster updates)

## After Update

```bash
# Review the changes
git diff main

# If satisfied, merge to main
git checkout main && git merge ao-update-*
```

## Rollback

If something goes wrong:

```bash
git checkout main           # Return to main
git branch -D ao-update-*   # Delete update branch
```

---

## 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
