agentleFS
Sign inStart free
ulises-jeremiasulises-jeremias/agent-toolkit/skills/delivery/adr/SKILL.md

adr

Skill19 starsChanged 2 months agoMITView on GitHub

WHAT — Create and maintain Architecture Decision Records (ADRs) per the process. Covers when

We split this skill into the rules it gives an agent

5 rules. 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 67 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use decision-log for lightweight product/project/operational decisions and agreement for explicit commitments or terms among parties.

    line 20
  2. Distinctive:

    If an ADR is superseded, preserve history: update status and point to the replacement document.

    line 34
  3. Very specific:

    Verify: ADRs exist, README covers quick start/commands/architecture (link ADRs), API docs have types, gotchas inline, no commented-out …

    line 40
  4. Distinctive:

    Do not use an ADR for one-line fixes with no long-term effect (use a normal task or PR description).

    line 44
  5. Distinctive:

    Do not paste the full org policy into this skill.

    line 45

“Common” is measured: kept by at least 6 in 10 of the 67 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ADR — Architecture Decisions (WHAT)

Template: references/default-template.md — local reference for ADR structure and workflow.

Default guardrails (before any final content)

  1. Apply output-handshake: confirm where the final ADR will be recorded and that a human will review.
  2. Then follow the steps below.

When to use

Use decision-log for lightweight product/project/operational decisions and agreement for explicit commitments or terms among parties. Use this ADR skill only for durable architecture or technical decisions.

  • A change has long-term architectural, security, data-model, or cost impact.
  • You need options with pros/cons and a record for future readers (and for supersession later).
  • The project needs decisions linked to PRDs, TRDs, tasks, PRs, diagrams, or other supporting artifacts.

Instructions

  1. Match existing convention first (per addyosmani/agent-skills documentation-and-adrs 2026-08-12, diff docs/research/diff-394-documentation-and-adrs.md): inspect docs/adrs/ (or Documentation/Decisions/, MADR, adr-tools .adr-dir) — location/format (Markdown vs reStructuredText), numbering/naming (ADR-004-*.md vs 0004-*.md), section headings. Surface conflict rather than silently introducing another scheme. Only when no convention can be established, default to docs/adrs/000N-*.md or docs/adrs/ADR-0xx-*.md six-part structure.
  2. Confirm the decision qualifies (new service, tech selection, schema change, deployment change, etc.) per the "When to Create an ADR" criteria.
  3. Draft using the six-part structure: Title & status, Context, Options, Decision, Consequences, References (link PRD/TRD, tasks, PRs, diagrams as applicable). Use lifecycle PROPOSED → ACCEPTED → (SUPERSEDED | DEPRECATED) and don't delete old ADRs — when decision changes, write new ADR that references and supersedes old (per upstream 2026-08-12).
  4. Review with the tech lead / peers as in the workflow; keep ADRs short and actionable (clarity over completeness).
  5. Link the ADR to the relevant epic or story and to PRs in the forge (use github-cli-workflow / gitlab-cli-workflow for PR text when applicable).
  6. If an ADR is superseded, preserve history: update status and point to the replacement document.

Red flags & verification (after documenting)

  • No ADR for significant architectural choices — every expensive-to-reverse decision needs one.
  • README missing quick start / architecture overview, API without types, rules files (CLAUDE.md/AGENTS.md) stale, commented-out code, week-old TODOs, or docs that restate code.
  • Verify: ADRs exist, README covers quick start/commands/architecture (link ADRs), API docs have types, gotchas inline, no commented-out code, personas/ (HOW agent thinks) vs skills/ (HOW task executes) preserved — see docs/CONCEPTS.md.

What not to do

  • Do not use an ADR for one-line fixes with no long-term effect (use a normal task or PR description).
  • Do not paste the full org policy into this skill; keep a single canonical copy in the wiki.

References

  • output-handshake — destination and review
  • references/default-template.md — ADR structure and workflow
  • references/example-001-graphql-adoption.md — example ADR for a GraphQL migration decision
  • trd — where technical design references decisions
  • decision-log — lightweight decisions
  • agreement — explicit commitments or terms
  • workflow-generic-project — traceability and plan approval
  • clickup-cli, jira-* — ticket and comment operations (per engagement)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free