Dotagents Standard

Writing context back (the append trap)

The most common way a dotagents setup decays: an agent learns something durable and puts it somewhere convenient instead of somewhere correct. Two sinks compete with .agents/, and both lose the value:

• AGENTS.md itself — it's already in context, so appending feels natural. Do it a few times and the router is the monolith again, the exact failure this standard prevents.
• Host agent-memory (Claude Code's ~/.claude/ memory, or any tool-local memory feature) — silent, machine-local, never committed, invisible to every other tool and teammate. This one is worse because nothing in the repo shows it happened.

.agents/ files aren't loaded until a routing rule pulls them in, so the pull toward both sinks is constant. Resist it deliberately.

AGENTS.md is a router, not a store. The only thing you ever add to it is a routing line. Content — rules, decisions, preferences, reference data — goes in .agents/, in the repo, where it gets committed and every tool can read it.

When you need to persist something, in order:

1. Classify it with the taxonomy table above: rule, memory, context, or spec?
2. Write it to the matching .agents/ file, creating the file if needed. Match the format already in use (the ADR heading style, the way existing rules are phrased).
3. Only then look at the router. If a routing rule already points at that file, you're done — leave AGENTS.md alone. If nothing points at it, add one conditional line with an action verb, and nothing else.

Self-check before any AGENTS.md write: is what I'm adding a pointer, or is it content? Content belongs in .agents/. If the file has grown past roughly a screenful (~50 lines), content has already leaked in — move it out.

Worked example — "we chose Kysely over Drizzle because the generated SQL is more readable". The trap:

  # AGENTS.md
  ## Context routing
  - **If working on the data layer:** READ `.agents/context/schema.sql`.
+
+ ## Decisions
+ - 2026-07-31: chose Kysely over Drizzle — generated SQL is easier to read and the
+   query-builder ergonomics suit our reporting endpoints better.

A new section, growing every session, unreachable by any routing rule. What to do instead:

  # .agents/memory/decisions.md
+ ## ADR 004: Kysely over Drizzle
+ **Date:** 2026-07-31
+ **Decision:** Replace Drizzle with Kysely in the data layer.
+ **Rationale:** Generated SQL is easier to read; query-builder ergonomics suit the
+ reporting endpoints.

AGENTS.md is untouched — its routing table already says to CONSULT .agents/memory/decisions.md, so the new ADR is reachable with no router change.

Implementing / migrating a setup

To set up dotagents in a repo (or split up a monolithic context file):

1. Inventory every source of agent context: AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md, README "development" sections, and scattered vendor folders.
2. Classify each chunk using the taxonomy table above. Read README.md prose, code standards, architecture notes, and to-do specs as different kinds even if they currently live in one file.
3. Create .agents/ with only the subdirs you need, and move the heavy/conditional content into small single-purpose files. Name files for their topic (coding.md, schema.sql, decisions.md), lowercase-with-hyphens for compound names (database-migration/).
4. Leave a tight router in AGENTS.md. After the move, AGENTS.md should be roughly a screenful: identity + a routing table + capabilities + a short maintenance rule saying that new context goes in .agents/, not in the router. If it's longer, you haven't moved enough out. That maintenance rule is what keeps the file from silently refilling — see "Writing context back" above.
5. Write conditional routing rules that point to the moved files. A good rule states a trigger and an action verb: **If touching auth:** READ .agents/context/auth-flow.md. Avoid unconditional "always read everything" — that recreates the monolith.
6. Promote repeatable procedures to skills. Any multi-step thing an agent will do more than once (run migrations, cut a release) becomes skills/{id}/SKILL.md (+ scripts/), following the agentskills.io format. See the template in assets/templates/skill-SKILL.md.
7. Decide commit vs. gitignore per file. Commit .agents/ generally — shared context is the payoff for team alignment. Gitignore genuinely personal files (.agents/memory/user.md).
8. Keep AGENTS.md spec-compatible. AGENTS.md is the cross-vendor agents.md standard, read by Claude, Cursor, Gemini CLI, Copilot, and more. Staying compatible is what makes dotagents vendor-agnostic. If a tool insists on CLAUDE.md, make it a one-liner: See AGENTS.md.

Copy-paste starters live in assets/templates/ — start from assets/templates/AGENTS.md.

The AGENTS.md router pattern

The router is the heart of the standard. Minimal, high-signal, conditional:

# AGENTS.md

## Identity
You are a Senior Rust Engineer focused on safety and performance.

## Context routing
- **If working on the database:** READ `.agents/context/schema.sql`.
- **If writing new features:** CHECK `.agents/specs/` for the active PRD.
- **If facing an architectural choice:** CONSULT `.agents/memory/decisions.md` for consistency.
- **If reviewing or testing:** ADOPT the persona in `.agents/personas/qa.md`.

## Capabilities
- You may execute scripts under `.agents/skills/` to validate your work.

## Maintenance
- Durable knowledge goes in `.agents/` (rules / memory / context) — never appended to this
  file, never into host-local agent memory. Add a routing line here only if none points at
  it yet.

What makes routing rules good:

• Conditional, not unconditional. Every line names a when. That's what preserves the token savings.
• An action verb per pointer — READ (load reference), CHECK (scan a folder), CONSULT (cross-check for consistency), ADOPT (switch persona), RUN (execute a skill). The verb tells the agent what to do with the file, not just that it exists.
• Specific paths, so there's no ambiguity about what to open.
• Short. If the router grows past a screenful, push detail down into .agents/ files and leave a pointer.

Conventions to hold to

• Keep the root clean. The reason .agents/ is hidden and consolidated is to avoid a litter of .claude/, .cursor/, .gemini/ folders. Route everything through AGENTS.md + .agents/.
• Markdown-first, human-readable. Prefer Markdown; use native formats in context/ where they're the natural fit (.sql, .ts, .json). No binary blobs, no proprietary schemas.
• One file, one purpose. Small single-topic files are what make conditional loading possible.
• Commit for the team; gitignore the personal. Shared context aligns collaborators; keep personal preferences out of the shared tree.
• .agents/ is not .github/. .github/ is platform-specific; .agents/ is platform-agnostic and meant for every kind of agent (IDE, CLI, local LLM).

Where to go next

• references/directory-reference.md — every subdirectory in depth: purpose, file format, naming, examples, and commit/gitignore guidance. Read it when authoring or when you hit an unfamiliar subdir.
• references/protocol-extensions.md — the broader .agents Protocol (dotagentsprotocol.com): global ~/.agents/ layer + merge order, mcp.json / models.json, structured sub-agents / tasks / memories, and the .agents Hub. Read it when the user wants machine config, a global layer, or shareable bundles.
• assets/templates/ — copy-paste starter files: AGENTS.md, rules-coding.md, memory-decisions.md, personas-qa-engineer.md, skill-SKILL.md.