Setup

adr-kit setup

You are running the one-time project setup for the adr-kit plugin. Your job is to:

1. Drop the canonical guide at .claude/adr-kit-guide.md (copied from the plugin's templates/adr-kit-guide.md).
2. Append a slim ADR-kit stub to the project's CLAUDE.md so future Claude Code sessions auto-load the guide.

This is the lightweight counterpart to /adr-kit:init. Use setup when the user has an existing project, already understands their architecture, and just wants the kit registered. Use init when the user wants the kit to also audit the codebase and propose ADRs.

Backwards compatibility (v0.11 footprint)

A project that ran v0.11 /adr-kit:setup has an inline ## ADR Kit Rules section in CLAUDE.md. This skill detects that footprint and leaves it untouched — telling the user to run /adr-kit:upgrade to migrate to the v0.12 marker-bracketed stub + external guide layout. Do not silently rewrite a v0.11 footprint. The upgrade skill exists for that explicit migration.

Steps

1. Resolve the plugin path.

``bash ADR_KIT=$(ls -d ~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/*/ | sort -V | tail -1) ``

If empty, abort: the plugin install is broken; tell the user to reinstall via /plugin install adr-kit@rvdbreemen-adr-kit.

1. Locate CLAUDE.md. It lives at the project root (pwd). The user is expected to run /adr-kit:setup from there. Read it if it exists.

1. Detect existing footprint. Three cases:

• v0.11 inline ## ADR Kit Rules section present. Stop and tell the user: Detected v0.11 ADR Kit Rules section in CLAUDE.md at line . Run /adr-kit:upgrade to migrate to v0.12 (slim stub + external guide). /adr-kit:setup is leaving the v0.11 footprint untouched. Exit without changes.
• v0.12 ... block present. Read it. If its content matches the canonical stub below, no-op. If it differs (e.g., from a partial earlier run, or a manual edit), refresh just the block contents — do not touch surrounding CLAUDE.md content. Confirm with Refreshed v0.12 ADR-kit stub in CLAUDE.md at line .
• No ADR-kit footprint. Proceed to step 4 (write the v0.12 stub) and step 5 (write the guide).

1. Append the v0.12 stub to CLAUDE.md. If CLAUDE.md exists, append the block below at the end with one blank line of separation. If it does not exist, create it containing only the block.

Stub:

```markdown

## ADR Kit

This project uses adr-kit. All architectural decisions live as ADRs in docs/adr/. Full guide: @.claude/adr-kit-guide.md Decision index: @docs/adr/ADR-INDEX.md (compact one-row-per-ADR map; regenerate with bin/adr-index -o docs/adr/ADR-INDEX.md).

Authoring: /adr-kit:adr (or the adr-generator subagent). Pre-commit verification: bin/adr-judge runs declarative Enforcement rules at commit time. ADRs with llm_judge: true are reviewed in-session via /adr-kit:judge. Edit-tier injection: when an [adr-inject] ADR-NNN ... governs block appears before an edit, treat the quoted Decision as a binding constraint for that file and comply with it.

```

1. Drop the canonical guide. Copy $ADR_KIT/templates/adr-kit-guide.md to project .claude/adr-kit-guide.md (mkdir .claude/ if needed). Three sub-cases:

• No project guide. Write the plugin template verbatim.
• Project guide exists, byte-identical to plugin template. No-op.
• Project guide exists and differs. Read both. Show the user a unified diff (3 context lines) and ask: keep project version | replace with plugin version | merge by hand. Apply.

The first line of the plugin template is ` — preserve it so future /adr-kit:upgrade` runs can detect freshness.

1. Confirm. One line summarising both writes:

``` Setup complete.

• CLAUDE.md:
• .claude/adr-kit-guide.md:

```

Constraints

• Two coordinated writes. v0.12 setup writes both the stub AND the guide file. Either-or is incomplete.
• Never silently migrate v0.11. A v0.11 footprint requires explicit /adr-kit:upgrade. Leave v0.11 alone here.
• Idempotent. Re-running on a v0.12 project where everything is current is a no-op.
• Read before write. Always read CLAUDE.md and .claude/adr-kit-guide.md before editing.
• Preserve surrounding content. Only the marker-bracketed stub and the guide file may be touched. Everything else stays byte-exact.
• No em dashes in any text the skill writes (per adr-kit style).

When the user is in the wrong directory

If pwd lacks all of CLAUDE.md, .git/, and a recognisable project manifest (package.json, pyproject.toml, Cargo.toml, platformio.ini, etc.), stop and ask: I do not see a project root here (no CLAUDE.md, no .git, no manifest). Confirm you want to set up adr-kit in ? Do not silently create files in unexpected locations.

Cross-references

• /adr-kit:init — full bootstrap including audit and hook installation.
• /adr-kit:upgrade — migrate v0.11 → v0.12 footprint without re-auditing.
• /adr-kit:install-hooks — install the pre-commit hook independently.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rvdbreemen
• Source: rvdbreemen/adr-kit
• License: MIT

Install and usage instructions live in the source repository linked above.