From adr-kit
Guided rewrite of legacy-shaped ADRs into the canonical-seven-section template enforced by /adr-kit:lint. Promotes inline status / date lines to a
npx claudepluginhub rvdbreemen/adr-kitThis skill is limited to using the following tools:
You are running `/adr-kit:migrate`. The user wants to rewrite one or more legacy-shaped ADRs into the canonical template that `/adr-kit:lint` enforces. This is a write skill: you propose targeted structural edits, the user confirms, then you apply them.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
You are running /adr-kit:migrate. The user wants to rewrite one or more legacy-shaped ADRs into the canonical template that /adr-kit:lint enforces. This is a write skill: you propose targeted structural edits, the user confirms, then you apply them.
docs/adr/ (the whole tree).If the path does not exist or contains no ADR files, say so plainly and stop.
<!-- TODO: populate --> placeholder so a human author can fill it in later.<!-- adr-kit-lint: skip --> is left untouched. A file with <!-- adr-kit-lint: advisory --> gets a warning ("this file is currently in advisory mode; migrating will make the marker meaningless") and a confirmation prompt.Look for docs/adr/.adr-kit.json (relative to project root, or the directory passed). If template.required_sections is set, target that list. Otherwise target the canonical seven:
## Status## Context## Decision## Alternatives Considered## Consequences## Related Decisions## ReferencesOrder matters. The migration must end with sections in the configured order.
For each file, determine:
The skill body below documents the patterns observed in real-world legacy ADRs. Apply each pattern that fits, in this order. Do not invent new transformations.
Source:
# ADR-NNN Title
**Status:** Accepted
**Date:** 2026-04-25
**Supersedes:** ADR-XXX (optional)
Target:
# ADR-NNN Title
## Status
Accepted, 2026-04-25. Supersedes ADR-XXX (optional).
If only **Status:** exists with no **Date:**, the Status section reads Accepted (without date).
Source has a ### Alternatives considered: (or ### Alternatives considered and rejected) heading nested inside ## Context. Target: lift the entire block out, change ### to ## , and place the new top-level ## Alternatives Considered heading between ## Decision and ## Consequences. Preserve content verbatim; only the heading level and position change.
Same as Pattern B but the source nests alternatives inside ## Consequences. Target: same restructure, place between Decision and Consequences.
Source: a ## Related section that mixes ADR/TASK references with file paths, PR links, vendor doc URLs, internal docs.
Target: rename to ## Related Decisions. Move pure-external references (files, URLs, PRs that are not ADR or TASK identifiers) to a new ## References section that follows. Keep ADR-NNN and TASK-NNN entries in ## Related Decisions.
Heuristic for splitting:
ADR-, TASK-, or referencing those identifiers -> ## Related Decisions.PR /Issue references -> ## References.## Related Decisions (safer default).If after Pattern D there are no external references to populate ## References, create the section with a placeholder:
## References
<!-- TODO: populate from inline citations or external sources cited in the body. -->
Never invent references. The placeholder makes it clear to a human reviewer that this is a known gap.
If the source legitimately has no alternatives discussion anywhere, create the section with a placeholder:
## Alternatives Considered
<!-- TODO: document at least 2 alternatives that were considered and rejected, with reasoning. -->
This is a real gap a human should fill, but the skill must not fabricate.
Before applying any edit, show the user a per-file summary:
Proposed migration plan (3 files):
ADR-007-timer-based-task-scheduling.md
Pattern A: inline `**Status:**` -> `## Status` heading
Pattern D: `## Related` -> `## Related Decisions` + new `## References`
ADR-029-simple-xhr-ota-flash.md
Pattern A: inline `**Status:**` -> `## Status` heading
Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
ADR-058-nonblocking-pic-command-response.md
Pattern A: inline `**Status:**` -> `## Status` heading
Pattern F: missing `## Alternatives Considered`, will create with TODO placeholder
Pattern E: missing `## References`, will create with TODO placeholder
No `## Related Decisions` content found in source; will create with `- None.`
Confirm to apply (y/n)?
If the user declines, stop without writing.
After confirmation, apply each transformation via Edit. One Edit per logical change, so the diff is reviewable. Report what was changed per file.
After all edits, suggest the user run /adr-kit:lint <path> to confirm the migrated files now PASS strictly. Do NOT run lint yourself: that is a separate skill the user invokes.
/adr-kit:lint after migration. The user decides when to verify.Single-file migration:
ADR-007-timer-based-task-scheduling.md migrated.
Applied: Pattern A (Status promotion), Pattern D (Related split).
Run /adr-kit:lint on this file to verify.
Directory migration:
Migrated 3 of 80 candidate files. 1 already canonical (skipped). 76 deferred (no patterns matched, manual review needed).
Applied:
ADR-007 (A, D)
ADR-029 (A, F)
ADR-058 (A, F, E, no Related content)
Skipped:
ADR-022 (already canonical)
Deferred (manual review): 76 files.
Reason: complex shape that did not match any of patterns A through F. Inspect by hand.
Run /adr-kit:lint docs/adr/ to confirm overall result.
The aggregate's bottom line tells the user one concrete next step (run lint), never invents a status the migration did not actually achieve.
**Status:**, **Date:**, **Supersedes:**, **Amended by:**, etc. Fold all into the new ## Status section as a comma-separated sentence. Order: Status, date, supersedes/amended.## Related with no body or only whitespace. Target: ## Related Decisions with - None. body.Renumbered from ADR-XXX ... line before **Date:**. Fold into the new ## Status section as a trailing sentence: "Renumbered from ADR-XXX on YYYY-MM-DD to resolve duplicate numbering. Content unchanged."## inside a fenced code block. The skill treats only headings outside code fences as canonical sections. If unsure, ask the user.## Pros and Cons or ## Decision drivers: do not rename these; they are project-specific. The migration concerns the canonical-required sections only. The user can address custom subsections in a follow-up pass.If the migration would require any of these, refuse and explain:
/adr-kit:lint automatically after migration. The user decides.