supersede - SKILL.md Agent Skill

name: supersede description: Guided supersession of an existing Architecture Decision Record. Shows the target's dependency graph first, drafts the superseding ADR via the adr-generator subagent (Status Proposed, back-linked), and only after explicit user approval flips the old ADR's Status line to "Superseded by ADR-M", appends status_history entries on both sides, and wires Related Decisions both ways. Verifies the chain with bin/adr-related and bin/adr-lint. Refuses to overwrite an existing supersession that points at a different ADR. argument-hint: "[ADR id to supersede; e.g. "ADR-007"]" license: MIT disable-model-invocation: true allowed-tools: [Read, Bash, Edit, Write, Task]

adr-kit supersede

You are running /adr-kit:supersede. Purpose: replace an existing decision with a new one without rewriting history. The old ADR's reasoning stays immutable; only its Status line changes and its Status History grows by one entry. Everything else lands in the new ADR.

Resolve the plugin path once and reuse it:

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

Step 1 - Identify the target and show its graph

Take the ADR id from the argument; if absent, ask which ADR to supersede.
Run the graph tool on it and show the user the result:
```
python "$ADR_KIT/bin/adr-related" ADR-OLD --format json
```
Present inbound edges explicitly: these are the ADRs that point at the target and may need their Related Decisions updated after supersession. Flag any dangling references already present.
Conflict guard (hard stop). Read the old ADR. If its Status line already says Superseded by ADR-X where X is NOT the ADR you are about to create, stop and surface the conflict to the user verbatim. Never overwrite an existing supersession pointer; the user must resolve the chain (perhaps the right move is superseding ADR-X instead).
Confirm with the user: "Supersede ADR-OLD () with a new ADR about <reason>?" Do not proceed without a yes.</p> </li> </ol> <h2>Step 2 - Draft the superseding ADR (Proposed)</h2> <p>Determine the next free ADR number (highest existing + 1, no gaps, no reuse). Invoke the <code>adr-generator</code> subagent with:</p> <ul> <li><p>The user's stated reason for the change as Context input.</p> </li> <li><p>The old ADR's Decision text as background (what is being replaced and why it no longer holds).</p> </li> <li><p>An explicit instruction to include in <code>## Related Decisions</code>: <code>- **ADR-OLD (<old title>)**: Supersedes ADR-OLD.</code></p> </li> <li><p><code>Status: Proposed</code> with today's date, and a <code>status_history</code> entry:</p> <pre><code class="language-yaml">status_history: - date: YYYY-MM-DD status: Proposed changed_by: <user> reason: Drafted to supersede ADR-OLD changed_via: adr-kit /adr-kit:supersede </code></pre> </li> </ul> <p>Show the draft to the user. <strong>Never auto-accept it.</strong> The user reviews and may iterate; the new ADR is only flipped to <code>Accepted</code> (by the user or on their explicit instruction) before the old one is touched.</p> <h2>Step 3 - Flip the old ADR (only after approval)</h2> <p>Only after the user has approved the new ADR-NEW:</p> <ol> <li><p>On the OLD ADR, exactly two edits and nothing else:</p> <ul> <li><p>Change its <code>## Status</code> line to: <code>Superseded by ADR-NEW, YYYY-MM-DD.</code></p> </li> <li><p>Append one entry to its <code>status_history</code> YAML block:</p> <pre><code class="language-yaml"> - date: YYYY-MM-DD status: Superseded changed_by: <user> reason: Superseded by ADR-NEW (<new title>) changed_via: adr-kit /adr-kit:supersede </code></pre> </li> </ul> <p>Do NOT touch Context, Decision, Alternatives, Consequences, References, or Enforcement of the old ADR. Do not edit earlier status_history entries.</p> </li> <li><p>Wire Related Decisions both ways:</p> <ul> <li>New ADR already carries <code>Supersedes ADR-OLD</code> (from Step 2).</li> <li>Add to the OLD ADR's <code>## Related Decisions</code>? No: the old ADR is immutable beyond the two edits above. The back-pointer lives in its Status line (<code>Superseded by ADR-NEW</code>), which bin/adr-related reads as a <code>superseded-by</code> outbound edge. That is the wiring.</li> <li>If inbound ADRs from Step 1 reference the OLD decision in their <code>## Related Decisions</code>, list them for the user and offer to add a note pointing at ADR-NEW. Apply only the entries the user approves.</li> </ul> </li> </ol> <h2>Step 4 - Verify the chain</h2> <p>Run all three and show the results:</p> <pre><code class="language-bash">python "$ADR_KIT/bin/adr-related" ADR-OLD --format json python "$ADR_KIT/bin/adr-related" ADR-NEW --format json python "$ADR_KIT/bin/adr-lint" docs/adr/ </code></pre> <p>The chain is clean when:</p> <ul> <li>ADR-OLD shows outbound <code>superseded-by -> ADR-NEW</code> and ADR-NEW shows outbound <code>supersedes -> ADR-OLD</code> (and inbound mirrors of each other).</li> <li>Neither graph reports dangling references.</li> <li>adr-lint reports no FAIL on either file.</li> </ul> <p>If any check fails, fix the link wiring (not the old ADR's prose) and re-run until clean. Report the final state to the user.</p> <h2>Boundaries</h2> <ul> <li><strong>Immutability.</strong> The only allowed edits to the old ADR are the Status line flip and the appended status_history entry. Everything else is read-only.</li> <li><strong>Conflict guard.</strong> An existing <code>Superseded by</code> pointing at a different ADR is a stop-the-line conflict. Surface it; never overwrite.</li> <li><strong>No auto-accept.</strong> The new ADR starts as Proposed and a human approves it. Do not flip it to Accepted on your own initiative.</li> <li><strong>No silent edits to third ADRs.</strong> Updating inbound referencers happens only per-entry with user approval.</li> <li><strong>Verification is part of the job.</strong> Do not declare the supersession done before Step 4 is clean.</li> </ul> </article> </div>  <div class="w-full lg:w-80 shrink-0 flex flex-col gap-6" data-astro-cid-7zzsworf>  <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-4 shadow-sm" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-mono" data-astro-cid-7zzsworf>Install via CLI</span> <div class="flex flex-col gap-2" data-astro-cid-7zzsworf> <div id="detail-install-cmd" class="font-mono text-[11px] p-3 rounded-lg bg-black/40 border border-border select-all break-all text-primary font-bold leading-relaxed" data-astro-cid-7zzsworf> npx skills add https://github.com/rvdbreemen/adr-kit --skill supersede </div> <button id="detail-copy-btn" class="w-full py-2.5 rounded-lg bg-primary hover:bg-primary-hover text-on-primary font-sans font-bold text-sm shadow transition-all active:scale-95 flex items-center justify-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px]" data-astro-cid-7zzsworf>content_copy</span> <span data-astro-cid-7zzsworf>Copy Command</span> </button> </div> </div>  <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-4 shadow-sm text-on-surface" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-sans" data-astro-cid-7zzsworf>Repository Details</span> <div class="flex flex-col gap-3.5" data-astro-cid-7zzsworf> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>star</span> Stars </span> <span class="font-mono font-bold text-on-surface" data-astro-cid-7zzsworf>1</span> </div> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>call_split</span> Forks </span> <span class="font-mono font-bold text-on-surface" data-astro-cid-7zzsworf>0</span> </div> <div class="flex justify-between items-center text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>navigation</span> Branch </span> <span class="font-mono bg-surface border border-border px-2 py-0.5 rounded text-[11px] text-on-surface-variant" data-astro-cid-7zzsworf>main</span> </div> <div class="flex justify-between items-start text-sm" data-astro-cid-7zzsworf> <span class="text-on-surface-variant/70 flex items-center gap-1.5 mt-0.5" data-astro-cid-7zzsworf> <span class="material-symbols-outlined text-[16px] text-on-surface-variant/60" data-astro-cid-7zzsworf>article</span> Path </span> <span class="font-mono bg-surface border border-border px-2 py-0.5 rounded text-[11px] text-on-surface-variant truncate max-w-[150px]" title="SKILL.md" data-astro-cid-7zzsworf>SKILL.md</span> </div> </div> </div>   <div class="p-6 rounded-xl bg-surface-container border border-border/80 flex flex-col gap-3 shadow-sm" data-astro-cid-7zzsworf> <span class="text-xs font-bold uppercase tracking-widest text-on-surface-variant/60 font-sans" data-astro-cid-7zzsworf>More from Creator</span> <div class="flex items-center gap-2" data-astro-cid-7zzsworf> <img class="w-8 h-8 rounded-full border border-border" src="https://avatars.githubusercontent.com/u/8645876?u=71c95f7a55e939f5f98bd5c04c5e5a793166f587&v=4" alt="rvdbreemen" onerror="this.src='https://avatars.githubusercontent.com/u/9919?v=4'" data-astro-cid-7zzsworf> <div class="flex flex-col min-w-0" data-astro-cid-7zzsworf> <span class="font-bold text-sm truncate text-on-surface" data-astro-cid-7zzsworf>rvdbreemen</span> <a href="/?creator=rvdbreemen" class="text-xs text-primary hover:underline font-semibold transition-all" data-astro-cid-7zzsworf>Explore all skills →</a> </div> </div> </div> </div> </div> </div> </div> <script> const copyBtn = document.getElementById("detail-copy-btn"); const installCmd = document.getElementById("detail-install-cmd"); if (copyBtn && installCmd) { copyBtn.addEventListener("click", () => { const cmd = installCmd.textContent.trim(); navigator.clipboard.writeText(cmd).then(() => { const originalText = copyBtn.innerHTML; copyBtn.innerHTML = ` <span class="material-symbols-outlined text-[16px]">check</span> <span>Copied!</span> `; copyBtn.style.background = "#10b981"; copyBtn.style.borderColor = "#10b981"; setTimeout(() => { copyBtn.innerHTML = originalText; copyBtn.style.background = ""; copyBtn.style.borderColor = ""; }, 1500); }); }); } </script> </div>  <footer class="border-t border-border bg-surface-container-low text-on-surface-variant py-8 px-gutter mt-16 rounded-xl"> <div class="max-w-container-max mx-auto flex flex-col md:flex-row justify-between items-center gap-6"> <div class="flex items-center gap-2"> <div class="w-6 h-6 rounded bg-primary bg-opacity-20 flex items-center justify-center"> <span class="material-symbols-outlined text-primary text-sm">code_blocks</span> </div> <span class="font-bold text-on-surface text-sm">SkillMD</span> </div> <div class="flex flex-wrap justify-center gap-6 text-sm"> <a href="/about" class="hover:text-primary transition-colors">About Us</a> <a href="/contact" class="hover:text-primary transition-colors">Contact Us</a> <a href="/privacy" class="hover:text-primary transition-colors">Privacy Policy</a> <a href="/terms" class="hover:text-primary transition-colors">Terms of Service</a> <a href="/support" class="hover:text-primary transition-colors">Support</a> </div> <div class="text-xs text-on-surface-variant/80"> © 2026 SkillMD. All rights reserved. </div> </div> </footer> </main>  <script> // Theme setup const savedTheme = localStorage.getItem("theme") || "dark"; function applyTheme(theme) { document.documentElement.classList.remove("dark", "green", "dracula", "nord"); if (theme === "dark") { document.documentElement.classList.add("dark"); } else if (theme === "green") { document.documentElement.classList.add("dark", "green"); } else if (theme === "dracula") { document.documentElement.classList.add("dark", "dracula"); } else if (theme === "nord") { document.documentElement.classList.add("dark", "nord"); } document.documentElement.setAttribute("data-theme", theme); const themeMoon = document.getElementById("theme-moon"); const themeSun = document.getElementById("theme-sun"); const themeLeaf = document.getElementById("theme-leaf"); const themeDracula = document.getElementById("theme-dracula"); const themeNord = document.getElementById("theme-nord"); if (themeMoon && themeSun && themeLeaf && themeDracula && themeNord) { themeMoon.style.display = theme === "dark" ? "inline" : "none"; themeSun.style.display = theme === "light" ? "inline" : "none"; themeLeaf.style.display = theme === "green" ? "inline" : "none"; themeDracula.style.display = theme === "dracula" ? "inline" : "none"; themeNord.style.display = theme === "nord" ? "inline" : "none"; } } applyTheme(savedTheme); const themeToggleBtn = document.getElementById("theme-toggle-btn"); if (themeToggleBtn) { themeToggleBtn.addEventListener("click", () => { const currentTheme = document.documentElement.getAttribute("data-theme") || "dark"; let newTheme = "dark"; if (currentTheme === "dark") { newTheme = "light"; } else if (currentTheme === "light") { newTheme = "green"; } else if (currentTheme === "green") { newTheme = "dracula"; } else if (currentTheme === "dracula") { newTheme = "nord"; } else { newTheme = "dark"; } applyTheme(newTheme); localStorage.setItem("theme", newTheme); }); } // Mobile menu toggle and sidebar logic const mobileMenuToggle = document.getElementById("mobile-menu-toggle"); const sidebarMenu = document.getElementById("sidebar-menu"); const sidebarOverlay = document.getElementById("sidebar-overlay"); function isMobile() { return window.innerWidth < 768; // 768px is the 'md' breakpoint in Tailwind } function openSidebar() { if (sidebarMenu) { sidebarMenu.classList.remove("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.remove("hidden"); } } function closeSidebar() { if (sidebarMenu && isMobile()) { sidebarMenu.classList.add("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } if (mobileMenuToggle && sidebarMenu) { mobileMenuToggle.addEventListener("click", (e) => { e.stopPropagation(); if (isMobile()) { const isClosed = sidebarMenu.classList.contains("-translate-x-full"); if (isClosed) { openSidebar(); } else { closeSidebar(); } } }); document.addEventListener("click", (e) => { if (isMobile()) { if (!sidebarMenu.contains(e.target) && !mobileMenuToggle.contains(e.target)) { closeSidebar(); } } }); if (sidebarOverlay) { sidebarOverlay.addEventListener("click", () => { if (isMobile()) { closeSidebar(); } }); } // Collapse sidebar when clicking a filter button, creator button, or nav item inside it sidebarMenu.addEventListener("click", (e) => { if (isMobile()) { const clickTarget = e.target.closest("button, a"); if (clickTarget) { closeSidebar(); } } }); // Sync sidebar state on window resize window.addEventListener("resize", () => { if (!isMobile()) { // Desktop: sidebar should be visible, no overlay if (sidebarMenu) { sidebarMenu.classList.remove("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } else { // Mobile: start collapsed if (sidebarMenu) { sidebarMenu.classList.add("-translate-x-full"); } if (sidebarOverlay) { sidebarOverlay.classList.add("hidden"); } } }); } // If not on homepage, redirect on sidebar filter click const isHomepage = window.location.pathname === "/"; document.querySelectorAll("#occupation-filters .filter-btn").forEach(btn => { btn.addEventListener("click", (e) => { const occ = e.currentTarget.getAttribute("data-occupation"); if (!isHomepage) { window.location.href = occ ? `/?occupation=${encodeURIComponent(occ)}` : "/"; } }); }); document.querySelectorAll("#creator-filters .creator-btn").forEach(btn => { btn.addEventListener("click", (e) => { const creator = e.currentTarget.getAttribute("data-creator"); if (!isHomepage) { window.location.href = `/?creator=${encodeURIComponent(creator)}`; } }); }); </script> </body> </html>