skills.rest
21StarkCom
21StarkComOFFICIAL
Explore all skills by this author →
GitHub

stark-adr

Create, list, and supersede MADR-lite Architecture Decision Records in a repository's docs/adr directory.

Updated Mar 16, 2026
Search Tags:#documentation#adr#cli#decision log#architecture decision record#madr#supersede
One-click install
npx skills add https://github.com/21StarkCom/stark-skills --skill stark-adr-21starkcom
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: stark-adr
Source: https://github.com/21StarkCom/stark-skills/tree/main/runtime-overrides/codex/skill/stark-adr
Command: npx skills add https://github.com/21StarkCom/stark-skills --skill stark-adr-21starkcom

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lose track of why architectural choices were made, and ad-hoc decision notes become inconsistent or get edited after the fact. This Skill records Architecture Decision Records in a consistent, auto-numbered, immutable format so the reasoning behind non-obvious decisions stays discoverable. ## Core Features & Use Cases - Scaffold new ADRs: Auto-numbers the next NNNN file, slugs the title, and renders the MADR-lite template (Status / Context / Decision / Alternatives / Consequences) under docs/adr/. - List the decision log: Shows number, status, and title for every ADR, with optional JSON output for scripting. - Supersede decisions: Flips an old ADR to Superseded with a link to its successor and scaffolds the replacement with a back-pointer, preserving immutability. - Use Case: After choosing PostgreSQL over DynamoDB for a service, run the skill to create an ADR capturing the context, trade-offs, and consequences so future reviewers understand the decision without re-litigating it. ## Quick Start Ask the assistant to create a new ADR titled "Use PostgreSQL for the billing service" with status Accepted in the current repository.

Frequently Asked Questions about stark-adr

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an Architecture Decision Record in a repository?▼

Run brain adr new with a quoted title, optionally passing --status Proposed or Accepted and --dir for the target repo. The command auto-numbers the file, slugs the title, and writes a MADR-lite skeleton under docs/adr/ that you then fill in.

How do I supersede an existing ADR instead of editing it?▼

Use brain adr supersede with the ADR number and a new title. It marks the old record as Superseded with a link to the successor and scaffolds the replacement ADR with a Supersedes back-pointer, keeping accepted records immutable.

What format does this ADR workflow use?▼

It uses MADR-lite: one decision per file named NNNN-kebab-title.md under docs/adr/, with Status, Context, Decision, Alternatives, and Consequences sections. Files are numbered monotonically and never edited after acceptance.

Does the ADR skill work without the brain CLI installed?▼

No. The skill is a thin wrapper over the brain adr command group from the Atlas engine, so brain must be on PATH. If it is missing, the skill stops and instructs you to build the Atlas CLI rather than hand-writing ADR files.

When should I write an ADR versus just a plan or PR?▼

Write an ADR only for non-obvious or hard-to-reverse decisions with real trade-offs, such as architectural choices, technology selection, or cross-cutting policy. Trivial work needs only a PR, and feature work needs a plan rather than an ADR.

Related Skills

Explore More Software Engineering Skills→
jeremyaryjeremyary
7

adr

Create structured Markdown Architecture Decision Records in the plans/adr/ directory.

Community
Intermediate
Clean1inesClean1ines

architecture-decision-records

Capture architectural decisions as structured ADRs with context, alternatives, and rationale.

Community
Advanced
dotCMSdotCMS
950

speckit-adr-context

Retrieves relevant Architecture Decision Records from dotCMS/platform-adrs to inform feature planning.

Official
Intermediate
JayRHaJayRHa
3

adr-author

Create immutable Architecture Decision Records with standardized structure and supersession workflow.

Community
Advanced