---
name: ao-install
description: "Install AO into a new or existing project. Handles .agent/ops/ setup and .github/ merging."
category: extended
invokes: [ao-interview]
invoked_by: []
state_files:
  read: []
  write: [constitution.md, memory.md, focus.json, baseline.md, issues/*.md]
---

# AO Installation

## Purpose
Install the AO framework into any project—new or existing—with intelligent merging.

## Installation Modes

### Mode 1: Fresh Install (empty or new folder)
Creates full structure from scratch.

### Mode 2: Merge Install (existing .github/)
Preserves existing content, adds AO alongside it.

### Mode 3: Update Install (existing AO)
Updates skills/prompts to latest versions without touching state files.

---

## Pre-Installation Checklist

Before installing, gather:

1. **Project type** — What language/framework? (affects gitignore suggestions)
2. **Existing CI/CD** — Any workflows in .github/workflows/?
3. **Existing instructions** — Is there a copilot-instructions.md?
4. **Git status** — Is this a git repo? Any uncommitted changes?

---

## Installation Structure

### .agent/ops/ (State - Created Fresh)

```
.agent/ops/
├── constitution.md      # Project-specific rules (from template)
├── memory.md            # Empty, grows over time
├── focus.json             # Empty, session state
├── baseline.md          # Empty, captured on first baseline
├── docs/                # ao-generated documentation
├── issues/
│   ├── critical.md      # P0 issues
│   ├── high.md          # P1 issues
│   ├── medium.md        # P2 issues
│   ├── low.md           # P3 issues
│   ├── history.md       # Archived issues
│   └── references/      # Detailed specs for complex issues
│       └── README.md
└── specs/               # Requirement specifications
```

### .ao/ (Framework - Merged)

```
.ao/
├── copilot-instructions.md   # MERGE with existing or create
├── skill-index.md            # Complete skill catalog with invocation rules
├── skills/                   # All AO skills
│   ├── ao-baseline/
│   ├── ao-constitution/
│   ├── ao-critical-review/
│   ├── ao-dependencies/
│   ├── ao-docs/
│   ├── ao-focus-scan/
│   ├── ao-git/
│   ├── ao-guide/
│   ├── ao-housekeeping/
│   ├── ao-implementation/
│   ├── ao-improvement-discovery/
│   ├── ao-install/
│   ├── ao-interview/
│   ├── ao-planning/
│   ├── ao-recovery/
│   ├── ao-retrospective/
│   ├── ao-spec/
│   ├── ao-state/
│   ├── ao-task/
│   ├── ao-testing/
│   └── ao-validation/
├── prompts/                  # Prompt files (additive)
│   ├── ao-*.prompt.md
│   └── ... 
├── agents/                   # Agent definitions
│   └── AO.md
└── reference/                # Reference documents
    ├── api-guidelines.md
    ├── cautious-reasoning.md
    └── code-review-framework.md
```

---

## Merge Strategy for copilot-instructions.md

### If NO existing file:
Create from AO template.

### If existing file WITHOUT AO:
```markdown
# Original content preserved above

---

# AO Protocol (appended)

[AO instructions here]
```

### If existing file WITH older AO:
Replace AO section only, preserve user customizations above the `---` separator.

---

## Installation Procedure

### Step 1: Detect Environment
```
□ Check if .agent/ops/ exists
□ Check if .github/ exists  
□ Check if copilot-instructions.md exists
□ Check if git repository
□ Identify project type (package.json, pyproject.toml, etc.)
```

### Step 2: Report & Confirm
```
📦 AO Installation

Target: /path/to/project
Mode: [Fresh | Merge | Update]

Will create:
  ✚ .agent/ops/ (full structure)
  ✚ .ao/skills/ (21 skills)
  ✚ .github/prompts/ (17 prompts)
  ✚ .github/agents/AO.md
  ✚ .ao/reference/ (3 docs)

Will merge:
  ⊕ .github/copilot-instructions.md (append AO section)

Will preserve:
  ○ .github/workflows/ (untouched)
  ○ .github/CODEOWNERS (untouched)
  ○ Existing prompts with same names (skip)

Proceed? [Y/n]
```

### Step 3: Create .agent/ops/ Structure
Always created fresh (never merge state files).

### Step 4: Copy/Merge .github/ Content
- Skills: Copy all (overwrite if updating)
- Prompts: Copy new only (skip existing with same name)
- Agents: Copy AO.md
- Reference: Copy all
- Instructions: Merge per strategy above

### Step 5: Post-Install Setup
```
□ Run initial constitution interview (optional)
□ Capture baseline (optional)
□ Add .agent/ops/ paths to .gitignore if desired
□ Create initial focus.json entry
```

### Step 6: Verify Installation
```
□ All required files exist
□ copilot-instructions.md valid
□ Skills readable
□ Report success
```

---

## Invocation

### Interactive (recommended for first install)
```
/ao-install
```
Walks through options, asks questions, confirms before acting.

### Quick Install (defaults)
```
/ao-install --quick
```
Uses defaults, minimal prompts, good for experienced users.

### Update Only
```
/ao-install --update
```
Updates skills/prompts/references only, doesn't touch .agent/ops/ state.

### Dry Run
```
/ao-install --dry-run
```
Shows what would be created/modified without making changes.

---

## Gitignore Recommendations

Suggest adding to .gitignore:

```gitignore
# AO state (optional - some teams prefer to track)
# .agent/ops/

# Always ignore (contains sensitive session data)
.agent/ops/focus.json
.agent/ops/baseline.md

# Or track everything for team visibility:
# (no ignores)
```

**Decision factors:**
- Solo project → ignore .agent/ops/ (personal state)
- Team project → track .agent/ops/ (shared context)
- Open source → ignore .agent/ops/ (contributor-specific)

---

## Uninstall

To remove AO:
```
□ Delete .agent/ops/ folder
□ Delete .ao/skills/ao-*/ folders
□ Delete .ao/prompts/ao-*.prompt.md files
□ Delete .ao/agents/AO.md
□ Delete .ao/reference/ folder
□ Remove AO section from copilot-instructions.md
```

---

## Troubleshooting

### "Skills not loading"
- Check copilot-instructions.md has skill references
- Verify skill files have correct frontmatter
- Restart VS Code / Copilot

### "Prompts not appearing"
- Prompts need `.prompt.md` extension
- Check prompts are in `.github/prompts/`
- Verify frontmatter format

### "Agent mode not available"
- Check `.github/agents/AO.md` exists
- Verify VS Code Copilot Chat extension is current
- Agent mode may need enabling in settings
