---
name: ao-init
description: "Create/repair .agent/ops/* state files and folders using the standard templates."
agent: AO
---

## Pre-flight: Verify `ao` CLI (HARD STOP)

Before doing anything else, run:

```bash
ao --version
```

If `ao` is **not found on PATH**, **STOP IMMEDIATELY** and display:

> ⛔ **HARD STOP**: `ao` CLI not found on PATH.
> Install with: `uv tool install ao` or `pip install ao`
> Then re-run `/ao-init`.

**Do NOT fall back to `uv run ao`.** The `ao` CLI must be directly executable.

---

## Step 1: Create folder structure

Create the required folder structure and state files under .agent/ops/ if missing:
- .agent/ops/memory.md
- .agent/ops/focus.json
- .agent/ops/issues/ (folder; ao will create events.jsonl and active.jsonl)
- .agent/ops/issues/.counter (initialized to 0)
- .agent/ops/baseline.md
- .agent/ops/constitution.md
- .agent/ops/references/ (folder)
- .agent/ops/docs/ (folder)
- .agent/ops/time-tracking.json (use template from .ao/skills/ao-state/templates/time-tracking.template.json)

Use the standard templates. Do not create any other files.

## Step 2: Generate AGENTS.md

Create (or overwrite) `AGENTS.md` at the project root. This is the **single source of truth** for agent instructions — do NOT also create `.github/copilot-instructions.md`.

If `.github/copilot-instructions.md` exists, ask the user if it should be removed (it is superseded by `AGENTS.md`).

**AGENTS.md must include (target: under 50 lines):**
- Project purpose (one-liner)
- Mandatory requirements (ao CLI, .gitignore note)
- **Authoritative References table** pointing to:
  - `.agent/ops/constitution.md` — build commands, work boundaries, code standards
  - `.agent/ops/memory.md` — durable learnings
  - `.agent/ops/focus.json` — current focus (use `ao focus`, never edit directly)
  - `.agent/ops/issues/` — issue data (use `ao` CLI, never edit JSONL directly)
  - `.ao/references/ao-workflow.md` — AO workflow documentation
  - `.ao/skill-index.md` — skill catalog and capabilities
  - `ao prime` — CLI command reference
- Quick build & test commands (3-line code block)
- Forbidden patterns (bullet list, no code blocks)
- Architecture overview (compact source tree)
- Testing conventions (2-3 lines)
- AO Workflow pointers (prompts, agents, skills paths)

**Do NOT duplicate** content from constitution.md, memory.md, or ao-workflow.md inline.

## Step 3: Post-creation

After creation:
- Update .agent/ops/focus.json indicating the repo is ready for constitution creation.
- Create an issue in .agent/ops/issues/ for completing the constitution interview.

## .gitignore audit

After creating the folder structure, analyze the project's `.gitignore` file for AO-specific paths.

Check whether **each** of the following entries is already covered by an existing `.gitignore` rule:

| Path | What it is |
|------|------------|
| `.ao/` | AO skills, templates, and configuration |
| `.agent/` | AO operational state (ops, issues, focus, memory) |
| `.claude/agents/ao-*.md` | AO agent definitions for Claude Code |
| `.claude/commands/ao-*.md` | AO commands for Claude Code |
| `.opencode/agents/ao-*.md` | AO agent definitions for OpenCode |
| `.opencode/commands/ao-*.md` | AO commands for OpenCode |
| `.github/agents/ao-*.agent.md` | AO agent definitions for VS Code / Copilot |
| `.github/prompts/ao-*.prompt.md` | AO prompt files for VS Code / Copilot |

**Important:** Only target AO-specific files (prefixed with `ao-`). Do **not** ignore the entire `.github/`, `.claude/`, or `.opencode/` directories — they may contain non-AO content that belongs in version control.

### copilot-instructions.md

`.github/copilot-instructions.md` is a standard Copilot feature file that may or may not be AO-generated. Do **not** include it in the automatic ignore list. Instead, if the file exists, ask the user separately:

> *".github/copilot-instructions.md exists. Was this generated by AO? If so, should I add it to .gitignore?"*

Only add it if the user confirms.

If **any** of those paths are not ignored:
1. List the missing entries clearly.
2. Ask the user: *"The following AO-specific paths are not in .gitignore: [list]. Should I add them?"*
3. If the user confirms, append a clearly labeled block to `.gitignore`:

```gitignore
# =============================================================================
# AgentOps (AO) — agent state & tooling (not part of the project source)
# =============================================================================
.ao/
.agent/
.claude/agents/ao-*.md
.claude/commands/ao-*.md
.opencode/agents/ao-*.md
.opencode/commands/ao-*.md
.github/agents/ao-*.agent.md
.github/prompts/ao-*.prompt.md
```

Only add the entries that are actually missing — do not duplicate existing rules.

If all paths are already ignored, report that and move on.

---

Then the next step is constitution creation (handoff button "Create/Update Constitution" or run /ao-constitution).
