agentleFS
pandazkipandazki/pneuma-skills/.agents/skills/create-adr/SKILL.md

create-adr

Skill161 starsChanged 11 days agoMITView on GitHub

Create an Architecture Decision Record for Pneuma Skills. Use when the user asks to document an architecture decision or author an ADR.

18 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-plan.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • JetBrainsSkill

    create-plan

    Research the codebase and create an implementation plan with architecture notes, design document, and track decomposition. Use when starting a new feature or large change.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    Create a new ADR under docs/adr/ following the project's conventions.

    line 8
  2. Very specific:

    Read docs/adr/README.md (index + conventions) and skim the most recent ADR for format.

    line 12
  3. Very specific:

    Write the ADR matching the structure of existing ones (title, status, date, context, decision, consequences, alternatives considered).

    line 15
  4. Very specific:

    Add a row to the index table in docs/adr/README.md (number, title, status, date).

    line 16

“Common” is measured: kept by at least 6 in 10 of the 14 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

/create-adr — Author a new Architecture Decision Record

Create a new ADR under docs/adr/ following the project's conventions.

Steps

  1. Read docs/adr/README.md (index + conventions) and skim the most recent ADR for format.
  2. Determine the next number: files are adr-NNN-kebab-title.md, zero-padded, sequential — check for gaps/duplicates before picking.
  3. Scope the decision with the user if not already clear from context: one decision per ADR. Context (forces, constraints) is distinct from the decision itself; rejected alternatives must be documented with honest trade-offs.
  4. Write the ADR matching the structure of existing ones (title, status, date, context, decision, consequences, alternatives considered). Status starts as Proposed unless the user says it is already decided (Accepted).
  5. Add a row to the index table in docs/adr/README.md (number, title, status, date).
  6. ADRs are immutable once Accepted — never edit an accepted ADR's decision; supersede it with a new one and add a supersession marker to the old entry (see ADR-008's annotation for precedent).
  7. Show or link the result for review. Commit only if the active task already includes committing; do not ask again for authorization already provided.

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.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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.