# Autonomous Agent Repository Rules Template

This protocol defines the standard structure for a repository's root `AGENTS.md`
(and symlinked `CLAUDE.md`). It establishes concise behavioral baselines,
deterministic boundary tiers, and progressive disclosure pointers.

## Design imperatives

- **Length limit**: Keep the root instruction file concise ($\le 100$ lines target,
  300 lines maximum). Long rule files dilute model attention and are ignored.
- **Progressive disclosure**: Keep the root file an index of essential build/test
  commands and pointers. Direct deep subsystem knowledge or tutorials into
  specialized documents under `docs/` or `.agents/`.
- **Deterministic tooling**: Never delegate code formatting, whitespace, or import
  sorting to LLM prompt prose. Formatting and linting belong exclusively to
  deterministic CLI tools (Ruff, Biome, Prettier) run via hooks or CI.

## Three-tier operational boundaries

Root repository instructions must establish three explicit operational tiers:

### 1. ALWAYS (Autonomous Execution)
Actions the agent must execute autonomously without asking for confirmation:
- Run targeted local unit and regression tests after making code changes.
- Execute deterministic linters and formatters before staging files.
- Update relevant documentation and architectural records when public interfaces change.
- Follow existing repository patterns, conventions, and module structure.

### 2. ASK FIRST (Human Confirmation Required)
Boundary actions requiring explicit confirmation before invocation:
- Modifying database schemas or executing destructive data migrations.
- Introducing new third-party dependencies, packages, or external services.
- Altering production deployment configurations, Dockerfiles, or CI workflows.
- Deleting existing tracked source files or removing deprecated public APIs.

### 3. NEVER (Non-Negotiable Invariants)
Hard negative constraints that must never be violated under any circumstances:
- Never commit plain-text credentials, tokens, or environment files (`.env`).
- Never force-push (`git push --force` or `-f`) to any remote tracking branch.
- Never execute destructive git resets (`git reset --hard` or `git clean -f`) on uncommitted work.
- Never commit directly to primary branches (`main` or `master`).
- Never suppress compiler warnings or type errors with blanket ignores (`# noqa`, `@ts-ignore`).

## Canonical AGENTS.md template

```markdown
# [Project Name] Agent Rules

## Stack & Commands
- Language & Runtime: [e.g. Python 3.12 / Node 20 / Rust 1.80]
- Package Manager: [e.g. uv / pnpm / cargo]
- Fast Check: [e.g. pytest tests/unit/ / pnpm test / cargo test]
- Linter & Formatter: [e.g. ruff check --fix && ruff format / pnpm biome check --apply]
- Type Checker: [e.g. pyright / pnpm tsc --noEmit]

## Three-Tier Boundaries
- **ALWAYS**: Run relevant checks before declaring completion. Run deterministic formatters.
- **ASK FIRST**: Adding dependencies, altering database schemas, or changing CI/deploy configs.
- **NEVER**: Direct commits to main, force pushes, hard resets, or committing secrets/.env.

## Workflow & References
- Feature work occurs in isolated git worktrees or dedicated branches.
- Follow WHAT-WHY-HOW-LEARNINGS telemetry format for commits and pull requests.
- Subsystem details: see docs/architecture.md and docs/gotchas/.
```