# 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 significant work must be captured as issues.** This ensures:
- 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

**When to suggest issue creation:**
- After baseline capture (findings, warnings, failures)
- During planning (sub-tasks, dependencies, risks)
- After code review (bugs, improvements, tech debt)
- After implementation (follow-up work, documentation needs)
- When user mentions something that sounds like work

**After creating issues, always offer:**
1. Start working on highest priority issue
2. Create more issues (if more work was discovered)
3. Continue with original task (if any)

## 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/`:
- `critical.md` — blockers, production issues, security vulnerabilities
- `high.md` — important, address soon
- `medium.md` — standard work items
- `low.md` — nice-to-have, when time permits
- `backlog.md` — unprioritized ideas awaiting triage
- `history.md` — archived completed issues
- `index.md` — issue ID → file lookup table
- `references/` — detailed specs for complex issues

### Issue Storage Rules (MANDATORY)

**Issues are ALWAYS appended INSIDE priority files.** Each priority file (critical.md, high.md, medium.md, low.md, backlog.md) contains ALL issues of that priority level as sections within a single file.

**NEVER create separate per-issue files** (e.g., `BUG-0001.md`, `FEAT-0042.md`) in the `issues/` directory. The ONLY files allowed directly in `issues/` are the priority files, history.md, index.md, events.jsonl, and active.jsonl.

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

**When a priority file exceeds 100 KB**, split into numbered files (`critical-1.md`, `critical-2.md`), keeping the most recent issues in the unnumbered file.

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

```
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.

## Special Modes

### API Review Mode
When reviewing or implementing APIs, apply `.ao/reference/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/reference/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/reference/lang-python.md` — pytest, tmp_path, fixtures
- **TypeScript/Node.js**: `.ao/reference/lang-typescript.md` — vitest/jest, fs/promises
- **C#/.NET**: `.ao/reference/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/reference/lang-python.md` |
| TypeScript/Node.js | `.ao/reference/lang-typescript.md` |
| C#/.NET | `.ao/reference/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/reference/)
- `api-guidelines.md` — API development checklist
- `cautious-reasoning.md` — epistemic reasoning framework
- `code-review-framework.md` — code review methodology
