Dotagents Standard

---
name: dotagents-standard
version: 0.2.0
description: >-
  Set up, author, and navigate the dotagents standard — a slim AGENTS.md "router" at the
  repository root plus a hidden .agents/ directory (rules, context, memory, personas, skills,
  specs, logs, tasks) that splits agent context into small per-topic files loaded on demand
  (progressive disclosure). Use this WHENEVER the user mentions dotagents, dotagentsprotocol.com,
  the .agents/ directory, or an "AGENTS.md router"; wants to organize, split, slim down, or
  migrate a monolithic AGENTS.md / CLAUDE.md / .cursorrules into structured context; wants
  vendor-agnostic agent configuration that every tool (Claude, Cursor, Gemini, Copilot, local
  LLMs) can read; or is working inside a repository that ALREADY contains an AGENTS.md or a
  .agents/ directory and needs to know how to discover and load the right context. Also covers
  the broader ".agents Protocol" superset (global ~/.agents/ layer, mcp.json, structured
  sub-agents / tasks / memories, and the .agents Hub for sharing configs).
---

# 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

```text
.
├── 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:

```diff
  # 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:

```diff
  # .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](https://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:

```markdown
# 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`.