A command that creates one proposed architecture decision record (ADR) from a current decision or a selected audit finding.

Use it to draft a record from a named decision or backfill candidate, including its context, alternatives, evidence, and affected files.

It preserves important technical choices and their supporting evidence instead of leaving them only in a plan or audit report.

adr-draft — Command by mbeacom

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add commands/mbeacom/adrkit/adr-draft

Clone the repo

git clone --depth 1 https://github.com/mbeacom/adrkit

Per session 25 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 1,777 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00025	$0.01777
Opus 5	$0.00013	$0.00889
Sonnet 5	$0.00005	$0.00355
Haiku 4.5	$0.00003	$0.00178

Measured yesterday against content hash 2a57870847b7, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

adr-draft scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

packages/adapters/agent-plugin/commands/adr-draft.md · 146 lines

How it starts

The opening of the file, as written. The whole thing — 146 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Resolve the CLI first

Try, in order: $ADRKIT_CLI, then ./node_modules/.bin/adr, then adr on PATH. @adrkit/cli is normally a dev dependency, so a bare adr is not on PATH in most projects — trying only that and concluding "no CLI is available" is a false negative. If all three fail, say so and tell the user to install @adrkit/cli. Never fall back to reading ADR frontmatter by hand: it cannot expand glob matchers, cannot read inbound @adr markers, and has no exit code, so it produces an answer that looks complete and is not.

Draft one architecture decision record for $ARGUMENTS.

Backfill mode

When $ARGUMENTS names a candidate key such as BF-001, resolve it only from the most recent /adr-backfill report still present in context. Require one complete backfillHandoff containing:

candidateKey
title
corpusDir
candidatePaths
sourceArtifact
citations
missingEvidence
affects
alternatives
reconciliation
reconciliationSnapshot with corpusFingerprint, governing, activeProposals, and history
statusTreatment: proposed

If the handoff is absent, ambiguous, stale, marked covered or unverified, or missing any field, stop without writing and ask the caller to rerun /adr-backfill or provide the complete block. Do not reconstruct provenance, paths, alternatives, or gaps from memory.

In backfill mode, use the handoff title for the scaffold, set provenance.sourceArtifact, cite every source and known gap in the body, copy the reviewed affects matchers, and state the reconciliation result. The handoff supplies evidence, not authority: the new record remains proposed. Use the handoff's corpusDir as ADR_DIR. Honor the trust confirmation recorded by /adr-backfill; if the resolved writer is inside the worktree and no explicit confirmation is present, stop before executing it.

Check first, then write. Before scaffolding anything:

Outside backfill mode, resolve ADR_DIR from $ADRKIT_DIR, defaulting to docs/adr.

Read the full file on GitHub · 146 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 146 lines · 25 tokens per session scan A 2a57870847b7

Subscribe to this mod's changes

adr-draft is a command published in the GitHub repository mbeacom/adrkit (11 stars, last pushed 2d ago), licensed Apache-2.0. It adds 25 tokens to every session and 1,777 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Planning adr ai-agents architecture architecture-decision-records backstage developer-experience

adr-draft

Getting it into your agent

What it costs to keep this loaded

Grade A, and why

Nothing flagged

How it starts

Resolve the CLI first

Backfill mode

What this file has done since we first saw it

Other commands, from other repositories

release-adr-kit

adr-export

adr-search

adr-setup

adr-supersede

adr-update