# AGENTS — Atomic AO Protocol

The `atomic` workflow is a minimal approach to agentic development, keeping instructions to a minimum.

## Core Principles (always apply)

1. **Never assume or guess** — ask clarifying questions about tasks or issues until explicit clarity is achieved and documented properly.
2. **Minimal changes only** — no refactors without permission.
3. **All code should be tested** - if possible, write the test first, then implement the code.
4. **NEVER push to protected branches** — main, master, develop/next, develop, next, release/* are FORBIDDEN push targets
5. **EVERTHING IS AN ISSUE** - This is the foundation of the Atomic workflow; no matter what we do, it is **ALWAYS** based on an issue in the issue tracker. This is to *keep focus*, *avoid drift*, have a clear *audit trail*, *accumulate knowledge* from learned lessons, and *track time*.

## State Files

### Memory

- Durable workflow learnings are written to `.agent/ops/memory.md` — and nowhere else.
- If the user corrects you, make a note of that in your memory and do not repeat it.
- Keep your memory clean and concise, remove any fluff.

### Issue Storage Rules (MANDATORY)

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

**Separate files are ONLY allowed in `.agent/ops/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`)

## IMPORTANT - Generated output

The agent is **NOT** allowed to write files in random places. All extra files, like markdown documents, helper scripts or anything not directly related to changes in the codebase, should go into these folder:

- `./scripts` - scripts of any kind
- `.agent/ops/logs` - **ALL* logging generated should be organized in this folder.
- `.agent/ops/docs/` — new markdown documentation
- `.agent/ops/references/` — local copies of external references
- `.agent/ops/issues/references/` — extra implementation or planning details related to specific issues

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