global-skills/protocols/agents-template.md

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

# [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/.