Agent Decision Records plugin
The AgDR standard: the agent writes a short record of a choice at decision time and commits it next to the code.
- 53 ★ on the repository
- Last commit
Minimal access
Why this level
- The plugin adds a command and a template, and the agent writes Markdown files in `docs/agdr/`.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/agent-decision-recordsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The plugin adds a command and a template, and the agent writes Markdown files in `docs/agdr/`.
This is third-party code. Review the repository files before installing.
What it does
An Agent Decision Record, or AgDR, captures the reasons behind an agent technical decisions. It is a small structured Markdown file: context, options weighed, the decision and the trade-off accepted. The agent writes it at the moment of choice, such as a library, pattern or migration, and commits it with the code. The record carries audit metadata: model, trigger and time. The idea resembles an Architecture Decision Record but the author is the agent. It is an open standard with Markdown and JSON representations, schemas for both and validators for CI. A Claude Code plugin adds the `/agent-decision-record:decide` command, Codex has `$agdr-decide`, and any other assistant gets the rule through a system prompt. Files live in `docs/agdr/AgDR-NNNN-*.md`.
Who it is for. Teams where agents make technical decisions and who will need to understand months later why a system is built a certain way.
Good fit when
- An agent chooses between two libraries and the reason is recorded before the commit.
- A new hire asks why this architecture was chosen.
- CI should reject decision records with a malformed structure.
- An audit requires the model and the moment of the decision.
Not a fit when
- You want a plain human written decision log with no agents.
- The project does not keep documentation in the repository.
- You need detailed process documentation instead of single decisions.
Example request
/agent-decision-record:decide which testing framework to choose for a TypeScript service.Limitations
The standard imposes nothing: you can take just the `agdr-template.md` template, the `schema/agdr.schema.json` schema and the `scripts/validate-agdr.js` script. Record quality depends on the agent, which can describe reasons incompletely, so review records like code. The CI check rejects only a malformed shape and does not judge content. The plugin targets Claude Code, while other assistants connect through Codex commands or a system prompt.
How to disable. Remove the plugin through `/plugin`, the `.claude/commands/decide.md` file and, if you wish, the `docs/agdr/` folder with records.
FAQ
How do I install the plugin?
Run `/plugin marketplace add me2resh/agent-decision-record` and `/plugin install agent-decision-record@agent-decision-record`.
How do I create a decision record?
In Claude Code with `/agent-decision-record:decide` and a topic, in Codex with `$agdr-decide`. The file appears in `docs/agdr/`.
Is the plugin required at all?
No, the template, schema and validator script are enough. You can also add the rule to the system prompt of any assistant.
How does AgDR differ from ADR?
The records are similar but the author is the agent and metadata includes model, trigger and time. The format is Markdown with a JSON schema.
What does CI check?
The `validate-agdr.js` script or the `validate-agdr.yml` workflow rejects records with a structure that fails the schema.
Discussion
No questions or reviews yet.
Related
PluginsArchgate turns architecture decisions into executable rules and blocks violations in CI, hooks and AI agent work
A Claude Code plugin for project architecture: ADRs, multi-role reviews, findings turned into plans, a pragmatic mode.
A CLI that analyses a repository in six model phases and writes AGENTS.md or CLAUDE.md, with ExecPlan planning on top.
Two skills for Codex and Claude Code: prd keeps a living implementation checklist and review audits designs from the user's side
Git-native project context for agents: specs, decisions and rules live in Markdown beside the code and are read before edits
Deterministic AGENTS.md and CLAUDE.md checks: compares a change with its baseline and blocks regressions in CI with no model.
README in short
The README explains the problem of lost agent decision context, shows an example record and three adoption paths: the plugin, a manual command copy and a system prompt. The normative description is in `SPEC.md`.