---
name: ao-init
description: "Create/repair .agent/ops/* state files and folders using standard templates. Initializes ao JSONL event store for issue tracking."
category: core
invokes: [ao-state, ao-task]
invoked_by: []
state_files:
  read: []
  write: [memory.md, focus.json, constitution.md, baseline.md, issues/events.jsonl, issues/active.jsonl, time-tracking.jsonl]
references: [.ao/reference/confidence.md]
---

# AO Init — Initialize AO State

## Purpose

Create or repair the complete `.agent/ops/` directory structure with all required state files and folders, including the ao JSONL event store.

**Files Created:**

| File/Folder | Purpose |
|-------------|---------|
| `.agent/ops/memory.md` | Durable learnings storage |
| `.agent/ops/focus.json` | Current work state and next steps |
| `.agent/ops/constitution.md` | Project authority and rules |
| `.agent/ops/baseline.md` | Known-good state for regression detection |
| `.agent/ops/issues/` | Issue tracking directory |
| `.agent/ops/issues/events.jsonl` | Append-only event log (source of truth) |
| `.agent/ops/issues/active.jsonl` | Rebuilt active issue index |
| `.agent/ops/constitution.md` | Project constitution |
| `.agent/ops/references-index.md` | References index |
| `.agent/ops/time-tracking.jsonl` | Append-only time tracking event log |
| `.agent/ops/references/` | References folder |
| `.agent/ops/docs/` | Documentation folder |

## Preconditions

- None (can run on any repository)

## Procedure

### Step 1: Create Directory Structure

```bash
# Create .agent/ops directory if it doesn't exist
mkdir -p .agent/ops

# Create issues subdirectory
mkdir -p .agent/ops/issues

# Create references subdirectory
mkdir -p .agent/ops/references

# Create docs subdirectory
mkdir -p .agent/ops/docs
```

### Step 2: Initialize ao JSONL Event Store

Create the ao issue tracking files:

```bash
# Create empty event log (append-only, source of truth)
touch .agent/ops/issues/events.jsonl

# Create empty active index (rebuilt by: ao rebuild)
touch .agent/ops/issues/active.jsonl
```

After init, use `ao issue add` to create issues and `ao rebuild` to refresh the active index.

### Step 2b: Create Time Tracking File

Create `.agent/ops/time-tracking.jsonl` (empty append-only event log):

```bash
touch .agent/ops/time-tracking.jsonl
```

Events are appended by `ao-state` as `session_start`, `session_heartbeat`, and `session_end` — no manual initialization required.

### Step 3: Create State Files

```markdown
# 1. Memory (.agent/ops/memory.md)

# Memory

Durable learnings and context for this project.

---

*(No learnings yet)*

---

# 2. Focus (.agent/ops/focus.json)

# Focus

Current work state and next steps.

## Doing now
*None*

## Next
*Run /ao-constitution to initialize the project*

---

# 3. Constitution (.agent/ops/constitution.md)

---
# Project Constitution

**Status:** Not yet initialized

Run `/ao-constitution` to create the project constitution.

---

# 4. Baseline (.agent/ops/baseline.md)

---
# Baseline

**Status:** Not yet captured

Run `/ao-baseline` after constitution is created to capture the current state.

---

# 5. References Index (.agent/ops/references-index.md)

# References Index

List of reference documents available for this project.

---

*(No references yet)*

---

```

### Step 4: Create References Directory Structure

```bash
# Create placeholders if needed
touch .agent/ops/references/.gitkeep
```

### Step 5: Update Focus

After successful initialization, update focus.json:

```markdown
# Focus

## Just did
*Initialized AO state files and folder structure*

## Doing now
*None*

## Next
*Run /ao-constitution to create the project constitution*
```

### Step 6: Report Completion

```
✅ AO Initialization Complete

Created:
- .agent/ops/ directory structure
- ao JSONL event store (events.jsonl, active.jsonl)
- State files (memory.md, focus.json)
- Time tracking (time-tracking.jsonl)
- References structure

Next Steps:
1. Run /ao-constitution to create project rules
2. Run /ao-baseline to capture initial state
3. Use /ao-task (or `ao issue add`) to create first issues
4. Use /ao-focus-scan (or `ao ls --ready`) to select issues to work on
```

## Integration Notes

- Works standalone to create directory structure
- Does NOT create issues themselves - that's done by /ao-task
- Creates ao JSONL event store (events.jsonl, active.jsonl)
- Issues are created via `ao issue add` or /ao-task
- State files use ao-state for consistent updates

## Error Handling

If any file already exists:
- Skip creation (don't overwrite)
- Log warning about existing file

If directory creation fails:
- Report error and stop
- Recommend creating .agent/ops manually

## Issue Store

Issues are managed via the `ao` CLI:

| Action | Command |
|--------|----------|
| Add issue | `ao issue add TITLE priority:high` |
| List issues | `ao ls` |
| Show issue | `ao --yes issue show <ID>` |
| Rebuild index | `ao rebuild` |

## Usage

```bash
# Initialize AO for a new project
/ao-init

# Result: Creates complete directory structure
# Then continue with constitution creation
```

## Verification

After running ao-init, verify:

```bash
# Check directory structure
ls -la .agent/ops/

# Verify ao files exist
ls -la .agent/ops/issues/

# Check state files
cat .agent/ops/memory.md
cat .agent/ops/focus.json

# Check time tracking
cat .agent/ops/time-tracking.jsonl

# Test ao CLI
ao ls

# Should see:
# - issues/ directory with events.jsonl, active.jsonl
# - State files (memory.md, focus.json)
# - Time tracking (time-tracking.jsonl)
# - References directory structure
```
