new-adr
Skill1 starsChanged 5 months agoApache-2.0View on GitHub
Scaffold a new Architecture Decision Record from the repo template, fill every section (incl. Reasoning + Review-trigger), and wire it into the ADR index and assumptions log. Use whenever you make ANY design/architecture/ops choice in this repo — the enforced rule is "no decision lands without an ADR stating its reasoning.
12 other projects use a version of this.
Adopted by
Most recently taken up by
- eugenelim/agent-ready-repotheir own version, first seen Nov 14, 2026
- jamesmccomish/mp-mcptheir own version, first seen Oct 20, 2026
- shubhsha/ai-engineer-2030their own version, first seen Oct 15, 2026
- maaferna/job-search-agent-systemtheir own version, first seen Oct 15, 2026
- RemiMyrset/rootstheir own version, first seen Oct 2, 2026
- pjlangley/fftheir own version, first seen Sep 23, 2026
Used with
Projects with it also use new-spec and release.
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.
eugenelimSkillnew-spec
Use this skill when the user wants to start a new feature with a spec, or wants to write a spec for something they're about to build. Triggers on "new spec", "write a spec for X", "let's spec this out", "start a feature for…". Spec-driven development; the spec drives implementation. Do NOT use for cross-cutting proposals (use `new-rfc`) or recording decisions (use `new-adr`).
Also in 5 projects that use this
MicrosoftSkillrelease
Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).
Also in 3 projects that use this
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- eugenelim/agent-ready-repo★ 31same name
- brayandiazc/project-starter-template-es-ai★ 15same name
- eugenelim/llm-wiki-kit★ 12same name
- pjlangley/ff★ 4same name
- brayandiazc/project-starter-template-en-ai★ 2same name
- jamesmccomish/mp-mcp★ 2same name
- maaferna/job-search-agent-system★ 1same name
- MetaMindTeam/ssot-kit★ 1same name
- tstephx/book-mcp-server★ 1same name
- Luis85/agentic-workflow★ 0same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- control-plane/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- helm/CLAUDE.mdCLAUDE.md
- terraform/CLAUDE.mdCLAUDE.md
- add-cellSkill
- cell-capacity-reportSkill
- deprovision-tenantSkill
- dr-drillSkill
- incident-triageSkill
- migrate-schemaSkill
- provision-tenantSkill
- restore-tenantSkill
- retire-cellSkill
- review-terraform-planSkill
- rotate-secretsSkill
- security-baseline-checkSkill
- tenant-erasureSkill
- tenant-usage-reportSkill
- upgrade-arcadedbSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 0 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 12 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 64
Assumption links resolve both ways: every A# cited in the ADR exists in assumptions.md, and each of those rows' Links column references …
- Very specific: line 65
No dangling links: every relative link in the new ADR resolves (template uses ../ from docs/adr/).
- Very specific: line 73
Index/assumptions drift: if architecture.md §9 or assumptions.md got out of sync, fix them in the same PR — never merge an ADR without its …
“Common” is measured: kept by at least 6 in 10 of the 12 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.
Files
Scaffold a new ADR
Create a new Architecture Decision Record so a choice is captured with its reasoning, alternatives, and review-trigger, then link it into the HLD index and the assumptions log. Phase note: this is a BUILD-TIME, docs-only skill — it edits files in
docs/and creates no AWS/cluster resources, so it is in scope in every phase (including pre-CTO-sign-off). It mutates nothing outside the repo and needs no approval gate.
Prerequisites
- Repo write access on a feature branch (these are docs changes; commit them with the change they justify — the ADR and the code/IaC land together).
- You have read the directory rules in
../../../docs/CLAUDE.md: no decision lands without an ADR that states its reasoning, and no assumption stands without adocs/assumptions.mdentry (a CLAUDE.md convention and a CI check). - Familiarity with the template:
../../../docs/adr/0000-template.md. - You know which prime directives / ArcadeDB facts (F1–F7) and which assumptions (A1–A17) the decision touches.
Inputs
| Input | Example | Notes |
title | External vector store fallback | The decision in a few words. Kebab-cased for the filename. |
kebab_title | external-vector-store-fallback | Derived from title: lowercase, words joined by -, no punctuation. |
status | Proposed | Accepted | Superseded by ADR-NNNN | Deprecated | New ADRs are usually Proposed until reviewed, then Accepted. |
type | ✅ decided by the business | ⭐ recommended (overridable) | Use ✅ only for business-confirmed choices; default to ⭐. |
decision | one line | The choice made, unambiguous, with scope (e.g. "for prod cells only"). |
deciders | roles | Roles not names where possible (e.g. "Platform owner, Security"). |
assumption_ids | A2, A6 | The assumptions.md IDs this rests on. Add a NEW one there first if it doesn't exist. |
superseded_target | ADR-0024 | Only if this ADR replaces an existing decision (see Safety checks). |
Safety checks (MUST pass before proceeding)
- The enforced repo rule (
docs/CLAUDE.md): no decision lands without an ADR that states its reasoning. If you are making a choice anywhere in this repo and there is no ADR for it, you MUST create one with this skill in the same change — not later. CI checks for it. - Next free number, no collision: the new
NNNNmust be exactlymax(existing) + 1, zero-padded to 4 digits, and theNNNN-<kebab-title>.mdfilename must not already exist. ADR numbers are never reused (even for retired/superseded ADRs). - Never edit a decided ADR's decision (immutability): a
0000-template.mdrule — if you are changing or reversing an already-AcceptedADR, do NOT edit it. Create a NEW ADR, set the old one's Status toSuperseded by ADR-NNNN, and set this new ADR's Context to reference it. The old ADR stays as the historical record. - Every section filled — especially the load-bearing ones: Context · Assumptions it rests on · Options considered (with pros/cons) · Decision · Reasoning (why this beats the alternatives) · Consequences · Status · Review-trigger. An ADR with an empty Reasoning or Review-trigger is incomplete and will fail review/CI. Tie Context + Reasoning back to the relevant prime directives and ArcadeDB facts (F1–F7) where they bound the choice (e.g. residency for a region choice, F5 "no PITR / restore requires the DB not to exist" for a backup/restore choice).
- Assumptions are real and linked both ways: every ID in "Assumptions it rests on" must exist in
assumptions.md. If the decision rests on a NEW assumption, add a row to the assumptions register FIRST (with: assumption · why we chose it · impact if wrong · confidence · validation owner/when · linked ADR), then reference its ID here. The link is bidirectional — the ADR lists the assumption, the assumption row lists the ADR. - Index stays in sync: the ADR index in
architecture.md§9 must get a new row in the same change. A diagram or index that lies is worse than none (docs/CLAUDE.md). - Docs-only, no infra: this skill must touch ONLY files under
docs/. If your diff creates or mutates Terraform/Helm/control-plane resources, that is a different skill — STOP and split the change (the ADR documents the decision; the IaC implements it).
Steps
- Pick the next free number. List the ADR directory and find the highest
NNNN:ls ../../../docs/adr/ | grep -E '^[0-9]{4}-' | sort | tail -1The new number is that value+ 1, zero-padded to 4 (e.g. last is0029-...→ new is0030). Confirm../../../docs/adr/NNNN-<kebab-title>.mddoes NOT already exist. - Copy the template to the new file (do not author from scratch — preserve the section structure):
cp ../../../docs/adr/0000-template.md ../../../docs/adr/NNNN-<kebab-title>.md - Fill the header table: Status, Decision (one line), Date (today, absolute —
2026-06-13format, never a relative date), Deciders (roles), Type (✅/⭐). Remove the template's "How to use" callout block (lines about copying/filling) — it belongs only in0000-template.md. - Fill
## Context— the forcing function + the constraints that bound the choice (residency, quorum, sizing, hand-over, ArcadeDB engine limits). Cite the relevant prime directives and facts F1–F7. - Fill
## Assumptions it rests on— theassumptions.mdIDs. If a NEW assumption is needed, add it toassumptions.mdfirst (see step 9), then list its ID here. - Fill
## Options considered— at least two real options, each with Pros and Cons; include the "do nothing / status quo" option where meaningful; mark which was chosen/rejected. - Fill
## Decision(unambiguous, scoped), then## Reasoning — why this beats the alternatives— the heart of the ADR: why, given the Context + Assumptions, this option wins over the rejected ones. Tie back to F1–F7 / prime directives. - Fill
## Consequences(Positive · Negative/costs · Follow-ups/what this obliges us to build) and## Review-trigger(the concrete signal — a metric threshold, version bump, cost line, invalidated assumption, or date — that should make us revisit). Never leave Reasoning or Review-trigger empty. - Link assumptions both ways. For each assumption the ADR rests on, ensure its row in
../../../docs/assumptions.mdlists this ADR in its Links column. If you added a new assumption, complete every column (why / impact if wrong / confidence / validation owner+when) and add it to the Validation milestones table; add a Change log entry at the bottom. - Add a row to the ADR index in
../../../docs/architecture.md§9, matching the existing table columns:| [NNNN](adr/NNNN-<kebab-title>.md) | <decision> | <✅/⭐ choice> | <main alternative> |. Keep rows in numeric order. - If superseding: open the superseded ADR, set its Status to
Superseded by ADR-NNNN, and leave its decision/reasoning intact (immutable history). - Self-review then commit the ADR + the
architecture.mdandassumptions.mdedits together with the change they justify (same branch/PR).
Verification
- File + naming:
../../../docs/adr/NNNN-<kebab-title>.mdexists,NNNNis unique and ismax+1, kebab title matches the H1 (# ADR-NNNN — <Title>). - No empty sections: grep the file for each required heading and confirm each has content — especially Reasoning and Review-trigger:
grep -n '^## ' ../../../docs/adr/NNNN-<kebab-title>.mdshould list Context, Assumptions it rests on, Options considered, Decision, Reasoning, Consequences, Review-trigger. - Index row present: the new
[NNNN](...)row appears inarchitecture.md§9, in order, with all four columns. - Assumption links resolve both ways: every
A#cited in the ADR exists inassumptions.md, and each of those rows' Links column references this ADR. - No dangling links: every relative link in the new ADR resolves (template uses
../fromdocs/adr/). - CI green: the "no decision without an ADR / no assumption without an entry" CI check (per
docs/CLAUDE.md) passes on the branch.
Rollback / if it goes wrong
- This is docs-only and reversible with git — nothing in AWS or the cluster is touched.
- Wrong number / collision:
git rmthe new file, delete the index row, redo step 1. Do not renumber an already-merged ADR (numbers are stable); supersede instead. - Accidentally edited a decided ADR's decision:
git checkout -- ../../../docs/adr/<that-file>.mdto restore it, then capture the change as a NEW superseding ADR. - Index/assumptions drift: if
architecture.md§9 orassumptions.mdgot out of sync, fix them in the same PR — never merge an ADR without its index row and assumption links (CI will block it anyway).
Related
../../../docs/adr/0000-template.md— the template this skill copies and fills.../../../docs/CLAUDE.md— the enforced ADR/assumptions rules and required sections.../../../docs/assumptions.md— assumptions register (link new/affected assumptions here).../../../docs/architecture.md§9 — the ADR index (HLD) you add a row to.- Skills that should TRIGGER a new ADR when their decision logic changes:
add-cell,upgrade-arcadedb,migrate-schema,restore-tenant— e.g. changing a capacity cap, durability tier, or backup/restore strategy.
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
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.

