dotagents

What this is

dotagents turns a project's agent context from one big file into a router + a library.

• The router is a slim AGENTS.md at the repo root. It is always read. It describes the agent's identity and, crucially, tells the agent where to look for deeper context — but only when a task actually needs it.
• The library is a hidden .agents/ directory holding the "heavy" context, split into small, single-purpose files organized by kind (behavioral rules vs. static reference vs. durable memory vs. task specs, etc.).

The whole point is progressive disclosure: load a screenful of routing rules up front, then pull in only the specific files the current task matches. A monolithic AGENTS.md/CLAUDE.md forces the agent to read a database schema while editing CSS, mixes "never use any" (a rule) with "we chose Postgres in 2023" (a memory), and invites a clutter of vendor folders (.claude/, .cursor/, .gemini/) in the root. dotagents fixes all three by separating by kind and loading conditionally.

The value lives entirely in that discipline. If you dump everything into AGENTS.md, you've gained nothing. If you scatter files but the router never points to them, agents won't find them. Both halves — a tight router and well-factored files — must hold.

Two related specs share the ".agents" name

Be aware there are two overlapping standards; know which one the user means:

1. dotagents (github.com/bgreenwell/dotagents, Draft 0.1.0) — the lean, hand-authored, project-scoped directory-as-context architecture described in this skill. This is "the dotagents standard" and the default subject here.
2. The .agents Protocol (dotagentsprotocol.com, Draft) — a superset that keeps the same .agents/ idea but adds machine-readable config (mcp.json, models.json), a global ~/.agents/ layer that merges with the project layer, structured sub-agents / tasks / memories with frontmatter schemas, and a public "Hub" for sharing .dotagents bundles.

They agree on the core (.agents/ + progressive disclosure). Use the core for hand-authored project context. Reach for the Protocol extensions when the user wants a global config layer, MCP wiring, structured sub-agents/tasks, or shareable config bundles — see references/protocol-extensions.md.

The directory map

.
├── AGENTS.md             # Entry point & router (Required). Always read first.
└── .agents/              # The context library (recommended; adapt to your project)
    ├── rules/            # Invariant behavioral guidelines ("No `any` types")
    ├── context/          # Static reference data, read-only (schema.sql, api.ts)
    ├── memory/           # Persistent project knowledge, read/write (decisions.md, user.md)
    ├── personas/         # Specialized agent "hats" (qa.md, architect.md)
    ├── skills/           # Executable capabilities — agentskills.io SKILL.md folders + scripts
    ├── specs/            # Current task requirements / PRDs (feature_x.md)
    └── logs/             # Session logs, thought traces, audit trails

Create only the subdirectories you need — empty scaffolding is noise. Full per-directory detail (format, naming, examples, commit guidance) is in references/directory-reference.md.

The two things you'll do

Utilize an existing setup (the common case): a repo already has AGENTS.md / .agents/ and you must do work in it correctly and efficiently. → See "Utilizing" below.

Implement a setup: create a new dotagents layout, or migrate a bloated AGENTS.md / CLAUDE.md / .cursorrules into one. → See "Implementing" below.

The decision taxonomy (the crux)

Whether reading or authoring, the key skill is knowing which kind a piece of context is. Ask, in order:

If the context is…	it's a…	goes in	read/write
An invariant behavioral rule ("always run tests before commit", "no any")	rule	rules/	read
Static reference the agent occasionally needs (DB schema, API types, config shape)	context	context/	read-only
Durable knowledge that evolves (why we chose X over Y, learned user prefs)	memory	memory/	read/write
A specialized role adopted temporarily (QA, security auditor, architect)	persona	personas/	read
A reusable, multi-step executable procedure (migration, release, codegen)	skill	skills/{id}/	read + run
The requirements of the current task (a PRD, a feature spec)	spec	specs/	read
A session record / audit trail / thought trace	log	logs/	write

The two most-confused pairs, worth internalizing:

• rule vs. memory. A rule is a standing instruction you must always obey ("prefer composition over inheritance"). A memory is a fact or decision that explains history and may change ("ADR 001: chose Postgres for JSONB"). Rules constrain behavior; memories preserve context. Mixing them is the original sin dotagents exists to prevent.
• context vs. specs. context/ is durable and read-only (the schema that's true across many tasks). specs/ is the transient "what we're building right now" and gets superseded.

When something doesn't fit cleanly, prefer the bin that makes the router rule easiest to write.

Utilizing an existing setup

When you start work in a repo that uses dotagents, practice disciplined progressive disclosure:

1. Read AGENTS.md first, fully. It's the map. Note the routing rules — keep them in working memory even before you know which you'll need. Also honor nested AGENTS.md files: the AGENTS.md convention lets subdirectories carry their own AGENTS.md, and the one nearest the file you're editing takes precedence over the root.
2. Match the task to routing rules, then load just those files. If the router says "If working on the database: READ .agents/context/schema.sql" and you're editing CSS, you do not read the schema. Pull in a file the moment its condition matches — and not before.
3. Adopt a persona only when the task calls for it. "Now put on the QA hat in .agents/personas/qa.md" is an explicit, temporary mode switch — do it when reviewing/testing, drop it afterward.
4. Run skills rather than reinventing them. If .agents/skills/ has a procedure for what you're about to hand-roll (a migration, a release), read its SKILL.md and use it. Respect its stated constraints (e.g. "never run on production without confirmation").
5. Maintain memory as you go. memory/ is read/write by design — it's how the project learns. When you make a durable decision, discover a lasting preference, or establish a new invariant, write it back: append an ADR to memory/decisions.md, note a preference in memory/user.md, or propose a new line in rules/. The next session (yours or a teammate's) inherits it. Match the existing file's format (e.g. the ADR heading style already in use).
6. Respect personal/gitignored files. memory/user.md and similar are often gitignored; read them for context but don't commit them or leak their contents into shared files.

If a task needs context the router doesn't point to, that's a gap — read the likely file anyway, complete the task, and then improve the router (add the routing rule) so it's found next time. Treat missing routing as a bug in the setup, not a dead end.

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.