| name | vs-setup-adr |
| description | Set up ADR support in the current repository. Creates an `adr/` directory with a README, adds an adoption ADR, and updates the repo's existing guidance surfaces so architecture-impacting or hard-to-reverse decisions live in ADRs. Use when user says 'setup adr', 'add adr support', 'adopt adrs', 'create adr directory', 'architecture decision records', or wants to bootstrap ADRs in a repo. |
| disable-model-invocation | true |
| metadata | {"verified":true} |
Setup ADR
Install a minimal ADR surface for the current repo.
This skill is for one explicit job: make ADRs the durable home for repo-level decisions without turning the repo into a planning graveyard.
Default outcome
Unless the user asks for something broader, set up ADRs with the smallest useful change set:
- Add
adr/README.md
- Add one adoption ADR such as
adr/adopt-adrs-for-repo-level-decisions.md
- Update the repo's existing guidance files so they point architecture-impacting repo decisions at ADRs
Do not default to migrating or deleting old RFC/spec/planning docs in the same run.
Phase 1: Inspect before editing
Before creating files:
- Check
git status --short and treat unfamiliar edits as in-progress work from someone else
- Inspect the repo's existing guidance surfaces and contributor docs
- Inspect the repo root to see whether
adr/, docs/decisions/, or another ADR-like location already exists
- Search for
ADR, decision record, RFC, design doc, adr/, and docs/decisions
Goal: understand the repo's current document surfaces before you add a new one.
Phase 2: Choose the target shape
Use these rules:
- If the repo already has a healthy ADR surface, do not create a duplicate. Fill the missing pieces instead.
- If the repo has repo-level policy scattered across root docs and PR lore, create
adr/ at the repo root.
- Default ADR filenames to lowercase, dash-separated, present-tense imperative verb phrases.
- Do not use numeric prefixes; use the slug alone as the identifier to avoid merge conflicts when multiple ADRs land in parallel.
- Do not add a
Status field by default; treat merge as approval unless the repo already has a stronger existing ADR convention.
Do not ask the user for naming or template preferences unless the repo already has conflicting conventions that make the choice genuinely strategic.
Phase 3: Add the ADR scaffolding
Read these bundled references before writing:
Adapt them to the current repo rather than copying blindly.
Requirements:
adr/README.md explains when an ADR is required, when it is not required, how ADRs are named, and how superseding works- The adoption ADR explains why this repo is using ADRs and what kinds of decisions belong there
- Do not add a target-repo
template.md file unless the user explicitly wants one
Phase 4: Align root guidance
Update only the files that exist.
Priority order:
- Repo-specific agent instructions if they exist (
AGENTS.md, CLAUDE.md, or equivalent)
- Contributor docs (
CONTRIBUTING.md or equivalent)
- The root
README.md, only if it currently misdescribes the role of adr/ or docs/
Agent or repo instructions
Add or update concise rules that:
- point architecture-impacting or hard-to-reverse repo decisions at
adr/
- keep session artifacts or temporary exploration out of ADRs
- keep the root file short and navigational
Contributor docs
Add one concise contributor-facing rule:
- add or update an ADR when a change introduces a cross-cutting or hard-to-reverse repo decision
Root README.md
Only touch the README if it currently misdescribes the role of adr/ or if the repo layout section should mention ADRs separately from docs/.
Do not bloat the README with ADR process detail.
Phase 5: Preserve scope
This skill sets up the ADR surface. It does not automatically:
- delete legacy RFC/spec docs
- migrate historical docs into ADRs
- add CI validation
- create a full governance framework
Those can be follow-up changes if the user asks.
Verification
After editing:
- Re-run targeted searches for
adr/, ADR, and root guidance mentions
- Review the diff for scope creep
- Confirm the setup is internally consistent: root docs,
adr/README.md, and the adoption ADR should all say the same thing
Output
Report:
- which files were added or updated
- whether the repo already had ADR-related conventions
- any legacy docs you intentionally left untouched
Workflow
Direct: emit Next only. Composed: return to caller.
Prev: architecture decision | /vs-shape-it
Next: /vs-shape-it
Relevant: /vs-rfc-research | /vs-to-issues
