Skip to content

openmove/engineering-design-playbook / .agents/skills/design-docs-template/new-adr

docs-template-new-adr

Verified

Scaffolds the next numbered ADR from the MADR template (minimal by default), status proposed, and updates the ADR index. Use when a decision is settled and must be recorded immutably. Invoked via design-docs-template.

new-adr — record one decision

What: Next docs/adr/NNNN-slug.md from MADR + index row, status proposed.
When: The choice is made (often after an RFC); you need a permanent record.
Not: Comparing designs still in flight (that is new-rfc) or closing a whole RFC (close-loop, which may call this).

Process

1. Locate templates

  • Default: docs/adr/adr-template-minimal.md
  • Full trade-off write-up: docs/adr/adr-template.md if they ask
  • Read docs/adr/README.md for numbering and “do not edit 0000 / upstream templates”

If docs/adr/ is missing, stop and suggest bootstrap.

2. Collect inputs

Ask what is missing:

  • Decision title (short, imperative or noun phrase per repo style) and slug
  • Minimal vs full template (default minimal)
  • Context one-liner if they already have it (optional — else leave template placeholders)
  • Supersedes ADR-NNNN? optional

3. Pick NNNN

List docs/adr/[0-9]*.md. Keep 0000 as the MADR meta-ADR; next id = max of numeric ids + 1 (if only 0000, next is 0001).

4. Write the file

  • Copy chosen template to docs/adr/NNNN-<slug>.md
  • Status: proposed
  • Fill title; leave options/consequences as template structure unless the user dictated the outcome in this turn
  • If superseding: set old ADR status to superseded by ADR-NNNN only when they confirmed the old id

5. Index

Add a row to docs/adr/README.md. Do not mark arc42 §9 updated until close-loop or they ask — linking from §9 on acceptance is a separate step.

6. Hand off

Report path, id, status. Remind: accepted ADRs are never rewritten; a later change needs a new ADR.

Hard rules

  • Do not edit adr-template.md, adr-template-minimal.md, or rewrite accepted ADRs.
  • One ADR = one decision. Split if they bundled several.
  • Prefer empty honest placeholders over invented rationale.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall