If present, agent context is stored in .agents/.
Agents MAY initialize or update this system only when explicitly instructed by a human.
AGENTS.md # root, committed, stable
.agents/
registry.md # index of all sessions + decisions
handoff.md # current working state (mutable)
sessions/
YYYY-MM-DD-HHMM-task-name.md
decisions/
YYYY-MM-DD-short-slug.md
Lives at repo root. Keep under 80 lines. Never use as a changelog or scratchpad.
Include:
- 2–4 sentence project overview
- Key directories and entry points
- Common commands (build, test, lint)
- Pointer to
.agents/registry.md - Link to relevant docs or ADRs
Do not include: inline code snippets (go stale), full file contents, style guides (link instead), or changelogs.
A flat index agents read instead of scanning all sessions and decisions. Hard limit: 50 lines of decisions.
YYYY-MM-DD [session] task-name
YYYY-MM-DD [decision] short-slug accepted
YYYY-MM-DD [decision] prior-slug superseded → YYYY-MM-DD-new-slug
Update whenever a session or decision file is created.
Agents SHOULD periodically compress old decisions into concise summaries if going over the decision lines limit. This summary should be concise 50 lines max.
One file per continuous work session in .agents/sessions/.
YYYY-MM-DD-HHMM-task-name.md
Required fields:
## Goal
One sentence.
## Actions taken
What was done and why — not a diff, not a log dump.
## Files changed
Bullet list of paths with one-line reason each.
## Decisions
Brief rationale for any non-obvious choices. Link to a decisions file if major.
## Blockers
Anything that stopped or slowed progress.
## Next steps
Concrete, actionable. What the next agent or human should do first.Session logs are append-only. If a correction is needed, append it with a timestamp — don't rewrite.
Do not log: raw diffs, full file contents, test output, or anything retrievable from source control.
One file per major decision in .agents/decisions/.
YYYY-MM-DD-short-slug.md
Required fields:
## Context
What situation prompted this decision.
## Decision
What was decided, in one sentence.
## Rationale
Why this option over alternatives.
## Status
accepted | proposed | superseded | deprecated
## Superseded by
(if applicable) link to newer decision filePrefer new files over editing history. Mark stale records explicitly — don't delete them.
Status vocabulary (use exactly these values):
| Status | Meaning |
|---|---|
proposed |
Under consideration |
accepted |
In effect |
superseded |
Replaced by a newer decision |
deprecated |
No longer relevant |
The single source of current working state. Mutable — update in place, don't append.
## Last worked on
ISO date · human or agent identifier
## Current status
One sentence: what state the work is in right now.
## Blockers
Anything preventing forward progress.
## Assumptions
What the last worker assumed that isn't obvious from the code.
## Next action
The single most important thing to do next.Keep it under 30 lines. If it grows longer, the status belongs in a session log, not here.
When records conflict, use this priority order:
- Source code and tests
- Human instructions
- Newer
.agents/records - Older
.agents/records
When you encounter a contradiction:
- Do not silently reconcile it.
- Append a correction to the relevant session log, or create a new superseding decision file.
- Update
handoff.mdto reflect the current true state. - Add a
⚠️ superseded bynote on the stale record.
Unless prompted otherwise, add .agents to gitignore.
| Don't log | Why |
|---|---|
| Raw diffs or patches | Retrievable from git |
| Full file contents | Retrievable from git |
| Test output | Retrievable from CI |
| Style guide rules | Keep in a linked doc, not context files |
| Changelogs | That's what commits are for |
| Anything over 5KB | Use a pointer/link instead |