AGENT SKILL

vs-setup-adr

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.

License 许可
MIT
所属仓库
vltansky/vs
最近更新
2026-11-06
Stars
★ 0
Forks
1

01 前言 Front Matter

name
vs-setup-adr
metadata
{ "verified": true }
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

02 资源文件 5

03 SKILL.md 正文

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:

  1. Add adr/README.md
  2. Add one adoption ADR such as adr/adopt-adrs-for-repo-level-decisions.md
  3. 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:

  1. Repo-specific agent instructions if they exist (AGENTS.md, CLAUDE.md, or equivalent)
  2. Contributor docs (CONTRIBUTING.md or equivalent)
  3. 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

Output style

Apply the shared output style to every user-facing message.

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

04 同仓库更多 Skills