---
name: ao-init
description: "Create/repair .agent/ops/* state files and folders. Initializes ao JSONL event store. Scans existing instruction files, extracts project content to .agent/ops/references/, and optimizes originals for all editors."
category: core
invokes: [ao-state, ao-task, ao-optimize-instructions]
invoked_by: []
state_files:
  read: []
  write: [memory.md, focus.json, constitution.md, baseline.md, issues/events.jsonl, issues/active.jsonl, time-tracking.jsonl, references/]
references: [.ao/references/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/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 Directory

References are stored in `.agent/ops/references/` — one file per complex issue.

---

```

### 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
*Scanning instruction files*

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

### Step 6: Scan and Optimize Instruction Files

Detect existing editor instruction files and extract project-specific content.

#### 6a: Discovery — Scan for Instruction Files

Check for ALL known instruction files:

| File | Editor | Type |
|------|--------|------|
| `.github/copilot-instructions.md` | VS Code Copilot | Always-loaded |
| `AGENTS.md` | Copilot agent mode, OpenCode | Always-loaded |
| `CLAUDE.md` | Claude Code | Always-loaded |
| `.cursorrules` | Cursor | Always-loaded |
| `.windsurfrules` | Windsurf | Always-loaded |
| `.github/instructions/*.instructions.md` | Copilot | Path-scoped |
| `.claude/rules/*.md` | Claude Code | Path-scoped |

Record which files exist and their line counts.
Skip this step if no instruction files are found.

#### 6b: Parse — Identify Project-Specific Content Blocks

For each detected file, identify extractable sections by scanning for:

- **Build commands**: Build, test, lint, deploy commands
- **Code standards**: Style rules, naming conventions, max line length, forbidden patterns
- **Architecture**: Directory trees, module descriptions, layer definitions
- **Testing conventions**: Test frameworks, fixtures, isolation rules, coverage targets
- **Forbidden patterns**: Anti-patterns, wrong import paths, banned APIs
- **Dependencies/tooling**: Package manager, CI/CD, required tools

Classify each section:
- **Extract** (>50 lines, project-specific, reference-style) → `.agent/ops/references/`
- **Keep inline** (<20 lines, critical workflow) → leave in place
- **Consider** (20-50 lines) → extract if duplicated across files

#### 6c: Extract — Move Content to .agent/ops/references/

For each extractable section, create a reference file:

```
.agent/ops/references/
├── code-standards.md       # Coding conventions, style rules
├── architecture.md         # Directory structure, module descriptions
├── testing-conventions.md  # Test framework, fixtures, patterns
├── build-commands.md       # Build, test, lint, deploy commands
└── forbidden-patterns.md   # Anti-patterns, wrong imports
```

Each file uses the template:
```markdown
---
title: {Section Title}
extracted_from: {source file path}
extracted_date: {YYYY-MM-DD}
---

# {Section Title}

{Full original content}
```

**Rule:** No content may be lost. Every line from the original instruction file
must exist in exactly one `.agent/ops/references/` file or remain inline.

#### 6d: Enrich — Update constitution.md with Project Facts

Extract key project facts and append to `.agent/ops/constitution.md`:

```markdown
## Project Facts (extracted from instruction files)

- **Language**: {detected language}
- **Framework**: {detected framework}
- **Build command**: {build command}
- **Test command**: {test command}
- **Package manager**: {detected package manager}
- **Key constraints**: {important rules extracted from forbidden patterns}
```

#### 6e: Rewrite — Optimize Instruction Files

Replace each instruction file with a minimal version (target: ≤50 lines):

**copilot-instructions.md** — Prose references (no import mechanism):
```markdown
# Project Name — Copilot Instructions
{2-3 line project summary}

## AO Framework
See .ao/references/ao-workflow.md for core workflow, principles, and protocol.
See .ao/skill-index.md for available skills and invocation rules.

## Code Standards
See .agent/ops/references/code-standards.md for full conventions.
Key: {1-line summary of most important rules}

## Architecture
See .agent/ops/references/architecture.md
Key: {1-line layout summary}

## Testing
See .agent/ops/references/testing-conventions.md
Key: {1-line testing summary}
```

**CLAUDE.md** — @-imports (auto-resolved by Claude Code):
```markdown
# Project Name
@.ao/references/ao-workflow.md
@.ao/skill-index.md
@.agent/ops/references/code-standards.md
@.agent/ops/references/architecture.md
@.agent/ops/references/testing-conventions.md

## Quick Reference
{Build/test commands only}
```

**AGENTS.md** — Markdown links:
```markdown
# Project Name — Agent Guidelines
{2-3 line project summary}

## AO Framework
See [ao-workflow.md](.ao/references/ao-workflow.md) — core workflow and principles
See [skill-index.md](.ao/skill-index.md) — available skills and invocation rules

## Project References
See [code-standards.md](.agent/ops/references/code-standards.md)
See [architecture.md](.agent/ops/references/architecture.md)
```

**.cursorrules / .windsurfrules** — Inline summary (no import mechanism):
```markdown
# Project Name
{Condensed key rules — these editors cannot reference external files}

## AO Framework
See .ao/references/ao-workflow.md for core workflow, principles, and protocol.
See .ao/skill-index.md for available skills and invocation rules.
```

#### 6f: Generate — Path-Scoped Files

For editors that support path-scoped instructions, generate focused files:

**Copilot** — `.github/instructions/{concern}.instructions.md`:
```yaml
---
applyTo: "**/*.py"
---
# Python Conventions
{Short summary referencing .agent/ops/references/code-standards.md}
```

**Claude Code** — `.claude/rules/{concern}.md`:
```yaml
---
paths:
  - "tests/**"
---
# Testing Conventions
{Short summary referencing .agent/ops/references/testing-conventions.md}
```

Only generate path-scoped files for editors that are detected (have an
always-loaded file present).

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

Instruction File Optimization:
- Scanned: {N} instruction files
- Extracted: {N} sections to .agent/ops/references/
- Original files rewritten to ≤50 lines each
- Path-scoped files generated: {list}
- Constitution enriched with project facts

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 next`) 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

# Check extracted references
ls -la .agent/ops/references/

# Verify instruction files are within budget
wc -l .github/copilot-instructions.md AGENTS.md CLAUDE.md 2>/dev/null

# Verify no project content in .ao/
# .ao/references/ should only contain framework docs

# 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 with extracted project content
# - Optimized instruction files (≤50 lines each)
```
