# AGENTS — AO Protocol

## Core Principles (always apply)

1. **Never assume or guess** — ask clarifying questions until explicit
2. **Minimal changes only** — no refactors without permission
3. **Constitution before baseline** — baseline before code changes (mandatory for LOW confidence, recommended for NORMAL, optional for HIGH)
4. **Validate before done** — compare final state vs baseline
5. **Evidence over speculation** — cite sources for decisions
6. **Issues before action** — all work should be tracked as issues for auditability
7. **Test isolation is mandatory** — tests must NEVER affect the project folder
8. **NEVER push to protected branches** — main, master, develop/next, develop, next, release/* are FORBIDDEN push targets
9. **`focus.json` via `ao focus` CLI only** — NEVER edit `focus.json` directly (no Python JSON writes, no shell writes, no text editors). Use `ao focus set-doing`, `ao focus set-next`, `ao focus set-just-did`, `ao focus iteration`, `ao focus sync`.

## Issue-First Workflow

**All work must be captured as issues PRIOR to implementation.** 

This ensures:

- Focused agentic work, less drift.
- Audit trail of decisions and work done
- Ability to prioritize and defer work
- Clear handoff between sessions
- Memory of what was discovered vs. what was done
- Clear time-tracking

## State Files

Persist working state in `.agent/ops/`:

- `constitution.md` — project authority (scope, commands, constraints)
- `memory.md` — durable workflow learnings
- `focus.json` — session state (just did / doing now / next)
- `baseline.md` — build/lint/test baseline for comparison

Issue tracking in `.agent/ops/issues/`:

- `events.jsonl` — append-only event log (source of truth, never mutated)
- `active.jsonl` — deterministic snapshot rebuilt via `ao rebuild`
- `.counter` — monotonic issue number counter
- `references/` — detailed specs for complex issues

### Issue Storage Rules (MANDATORY)

**Issues are stored as JSONL events, not markdown files.** The `events.jsonl` file is the source of truth — it is append-only and never edited directly. Use `ao` CLI commands for all issue operations:

- `ao add "Title" --type feat --priority high` — create an issue
- `ao set ISSUE_ID --priority medium` — update fields
- `ao close ISSUE_ID` — close an issue
- `ao ls` — list active issues
- `ao rebuild` — rebuild `active.jsonl` from events

**NEVER edit events.jsonl or active.jsonl directly.** Always use `ao` CLI commands.

**Separate files are ONLY allowed in `issues/references/`** for detailed specs, research, or long-form content linked from the issue.

Issue ID format: `{TYPE}-{NUMBER}@{HASH}` (e.g., `FEAT-0042@c2d4e6`)

Additional locations:

- `.agent/ops/docs/` — new markdown documentation
- `.agent/ops/references/` — local copies of external references

## Workflow Order

```bash
Constitution → Baseline → Plan → Implement → Test → Validate → Review → Retrospective
```

**Step clarifications:**

- **Test** (`ao-testing`) — Write and run tests (TDD cycle) after implementation
- **Validate** (`ao-validation`) — Run full build/lint/test suite, compare against baseline
- **Review** (`ao-critical-review`) — Deep code review for correctness, security, design

> `ao-review` is the **automated subagent review** (lighter, can run during implementation).
> `ao-critical-review` is the **deep post-implementation review** used in the workflow order above.

## Skill Tiers

See [`skill-index.md`](.ao/skill-index.md) for the complete skill index with descriptions and direct links to all skill files.

**Quick reference:**

| Tier | Skills |
|------|--------|
| **Tier 1: Core Workflow** | ao-constitution → ao-baseline → ao-planning → ao-implementation → ao-testing → ao-validation → ao-critical-review → ao-retrospective |
| **Tier 2: State Management** | ao-state, ao-focus-scan, ao-housekeeping, ao-tools |
| **Tier 3: Utility Skills** | ao-interview, ao-task, ao-spec, ao-docs, ao-dependencies, ao-guide, ao-debugging, ao-research, ao-review-response |
| **Tier 4: Git & Recovery** | ao-git, ao-recovery, ao-git-analysis, ao-git-story, branch operations |
| **Tier 5: Analysis** | ao-context-map, ao-improvement-discovery, ao-review-domain, ao-project-sections, ao-potential-discovery |
| **Extended/Special** | ao-install, ao-create-skill, ao-migrate, ao-build, ao-idea, ao-report, ao-github |
| **Documentation** | ao-versioning, ao-mkdocs, ao-astro-docs, ao-create-technical-docs |

**Invocation rules, installation groups, and tier definitions**: See [`skill-index.md`](.ao/skill-index.md) for complete documentation.

## Confidence Levels

See `.ao/references/confidence.md` for full canonical definitions.

| Level | Batch size | Planning | Approval gates | Review depth |
|-------|-----------|----------|----------------|-------------|
| LOW | 1 issue only | 3+ iterations | Hard (wait for approval) | Exhaustive |
| NORMAL | Up to 3 | 2 iterations | Soft (ask, continue) | Standard |
| HIGH | Up to 5 | 1 or skip | Minimal | Quick check |

- Agent may suggest lowering confidence for risky changes.
- User may override confidence per task.
- Default confidence is set in `.agent/ops/constitution.md`.

## Special Modes

### API Review Mode
When reviewing or implementing APIs, apply `.ao/references/api-guidelines.md`:
- Use as checklist during planning and review
- Validate security, error handling, versioning

### Cautious Reasoning Mode
For complex decisions with high uncertainty, apply `.ao/references/cautious-reasoning.md`:
- Enumerate multiple hypotheses before evaluating
- Use conditional reasoning (IF/THEN)
- Rate confidence explicitly (0-100%)

## Test Isolation (MANDATORY)

Tests must NEVER create, modify, or delete files in the project folder.

### Principles (Language-Agnostic)

**Unit Tests:**
- Mock/stub file system operations
- Use in-memory data structures
- Never perform real I/O to project directory
- Never create temp files in project directory

**Integration Tests:**
- Use framework-provided temporary directories (auto-cleanup)
- Use containers for service dependencies
- Use isolated temp directories outside project
- Ensure cleanup on both success and failure

**Key Rules:**
1. Tests must not pollute the project folder
2. Tests must clean up after themselves
3. Tests must not depend on execution order
4. Hardcoded project paths are forbidden

### Language-Specific Patterns

For detailed test patterns and examples, use `read_file` to load:
- **Python**: `.ao/references/lang-python.md` — pytest, tmp_path, fixtures
- **TypeScript/Node.js**: `.ao/references/lang-typescript.md` — vitest/jest, fs/promises
- **C#/.NET**: `.ao/references/lang-csharp.md` — xUnit, IDisposable, temp directories

### Universal Anti-Patterns (FORBIDDEN)
```
// ❌ NEVER do this in any language
write_file(".agent/ops/test.md", "test data")     // Pollutes project
write_file("./temp/test.txt", "data")         // Not isolated
read_file("./src/real_config.json")           // Depends on project state
```

## User interaction

- Use the best tools for interacting with the user
- Always be precise and give a short summary of what you need to clarify
- **IMPORTANT** If asked to interview or question the user:
    - In claude code use the AskUserQuestion tool for single- or multiple-choice questions
    - In opencode use the question tool for single- or multiple-choice questions
    - I VS Code/Copilot use the best you can. 

## Language-Specific Guidelines

AO is language-agnostic. For language-specific tooling, commands, and patterns, use `read_file` to load:

| Language | Reference File (load on demand) |
|----------|--------------------------------|
| Python | `.ao/references/lang-python.md` |
| TypeScript/Node.js | `.ao/references/lang-typescript.md` |
| C#/.NET | `.ao/references/lang-csharp.md` |

These documents cover:
- Testing frameworks and patterns
- Package management commands
- Code quality tools (linters, formatters)
- Build system commands
- Common idioms and patterns

## Reference Documents (in .ao/references/)
- `api-guidelines.md` — API development checklist
- `cautious-reasoning.md` — epistemic reasoning framework
- `code-review-framework.md` — code review methodology
- `issue-handling.md` — AO CLI issue handling (index + 6 sub-documents)
