@opengroundplan/core 0.1.1

package/registry/hooks/conventional-commit-check/hook.ps1

@@ -0,0 +1,68 @@
+# Dual mode: git commit-msg hook (arg = message file) or PreToolUse Bash (payload carries the command).
+param([string]$MessageFile)
+
+. (Join-Path $PSScriptRoot '..\_lib\config.ps1')
+
+$isGitHook = [bool]$MessageFile
+$message = $null
+
+if ($isGitHook) {
+    if (-not (Test-Path $MessageFile)) { exit 0 }
+    $message = (Get-Content $MessageFile -Raw)
+} else {
+    $payload = Read-GroundplanPayload
+    $command = $payload.tool_input.command
+    if (-not $command -or $command -notmatch '\bgit\s+commit\b') { exit 0 }
+    # Only -m commits are checkable here; an editor commit is caught by the git hook instead.
+    if ($command -notmatch '-m\s+(?:"([^"]*)"|''([^'']*)'')') { exit 0 }
+    $message = if ($Matches[1]) { $Matches[1] } else { $Matches[2] }
+}
+
+# Comments and trailing blanks are not part of the subject.
+$subject = ($message -split "`n" | Where-Object { $_ -notmatch '^\s*#' } | Select-Object -First 1)
+if (-not $subject) { exit 0 }
+$subject = $subject.Trim()
+
+# Merge/revert/fixup commits are generated by git, not authored.
+if ($subject -cmatch '^(Merge|Revert|fixup!|squash!)\b') { exit 0 }
+
+$types = Get-GroundplanConfig 'commitTypes'
+$maxLength = Get-GroundplanConfig 'commitSubjectMaxLength'
+$requireScope = Get-GroundplanConfig 'commitRequireScope'
+
+$scopePart = if ($requireScope) { '\([a-z0-9][a-z0-9._/-]*\)' } else { '(\([a-z0-9][a-z0-9._/-]*\))?' }
+$pattern = '^(' + ($types -join '|') + ')' + $scopePart + '!?: .+'
+
+# -cnotmatch/-cmatch throughout: the default -match is case-insensitive and would pass 'FEAT:'.
+$problems = @()
+if ($subject -cnotmatch $pattern) {
+    $problems += "does not match '<type>$(if ($requireScope) { '(scope)' } else { '[(scope)]' })[!]: <subject>'"
+}
+if ($subject.Length -gt $maxLength) {
+    $problems += "subject is $($subject.Length) chars, limit is $maxLength"
+}
+if ($subject -cmatch ':\s+[A-Z][a-z]') {
+    $problems += 'subject starts with a capital letter — use lower case'
+}
+if ($subject -cmatch '\.$') {
+    $problems += 'subject ends with a period — drop it'
+}
+
+if ($problems.Count -eq 0) { exit 0 }
+
+$report = @"
+BLOCKED: commit message is not a Conventional Commit.
+
+  subject: $subject
+$($problems | ForEach-Object { "  - $_" } | Out-String)
+Allowed types: $($types -join ', ')
+Example: feat(auth): add refresh token rotation
+
+Adjust 'commitTypes' / 'commitSubjectMaxLength' in the repo hook config to change these rules.
+"@
+
+if ($isGitHook) {
+    [Console]::Error.WriteLine($report)
+    exit 1
+}
+Deny-GroundplanTool $report

package/registry/hooks/conventional-commit-check/hook.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Dual mode: git commit-msg hook ($1 = message file) or PreToolUse Bash (payload carries the command).
+set -euo pipefail
+# shellcheck source=../_lib/config.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)/config.sh"
+
+message_file="${1:-}"
+if [ -n "$message_file" ]; then
+  is_git_hook=1
+  [ -f "$message_file" ] || exit 0
+  message="$(cat "$message_file")"
+else
+  is_git_hook=0
+  gp_json_unavailable && exit 0
+  command_line="$(cat | { jq -r '.tool_input.command // empty' 2>/dev/null || true; })"
+  printf '%s' "$command_line" | grep -Eq '\bgit[[:space:]]+commit\b' || exit 0
+  # Only -m commits are checkable here; an editor commit is caught by the git hook instead.
+  message="$(printf '%s' "$command_line" | sed -nE "s/.*-m[[:space:]]+(\"([^\"]*)\"|'([^']*)').*/\2\3/p")"
+  [ -n "$message" ] || exit 0
+fi
+
+subject="$(printf '%s' "$message" | grep -v '^[[:space:]]*#' | head -n1 | sed -E 's/^[[:space:]]+|[[:space:]]+$//g')"
+[ -n "$subject" ] || exit 0
+
+# Merge/revert/fixup commits are generated by git, not authored.
+printf '%s' "$subject" | grep -Eq '^(Merge|Revert|fixup!|squash!)\b' && exit 0
+
+types="$(gp_config commitTypes | paste -sd'|' -)"
+max_length="$(gp_config commitSubjectMaxLength)"
+require_scope="$(gp_config commitRequireScope)"
+
+if [ "$require_scope" = "true" ]; then
+  scope_part='\([a-z0-9][a-z0-9._/-]*\)'
+else
+  scope_part='(\([a-z0-9][a-z0-9._/-]*\))?'
+fi
+
+# if-blocks, not `[ ... ] && x=...` — a false test is a non-zero statement and set -e would abort.
+problems=""
+if ! printf '%s' "$subject" | grep -Eq "^($types)${scope_part}!?: .+"; then
+  problems="$problems\n  - does not match '<type>[(scope)][!]: <subject>'"
+fi
+if [ "${#subject}" -gt "$max_length" ]; then
+  problems="$problems\n  - subject is ${#subject} chars, limit is $max_length"
+fi
+if printf '%s' "$subject" | grep -Eq ':[[:space:]]+[A-Z][a-z]'; then
+  problems="$problems\n  - subject starts with a capital letter — use lower case"
+fi
+if printf '%s' "$subject" | grep -Eq '\.$'; then
+  problems="$problems\n  - subject ends with a period — drop it"
+fi
+
+if [ -z "$problems" ]; then exit 0; fi
+
+report="BLOCKED: commit message is not a Conventional Commit.
+
+  subject: $subject$(printf '%b' "$problems")
+
+Allowed types: $(gp_config commitTypes | paste -sd', ' -)
+Example: feat(auth): add refresh token rotation
+
+Adjust 'commitTypes' / 'commitSubjectMaxLength' in the repo hook config to change these rules."
+
+if [ "$is_git_hook" -eq 1 ]; then
+  printf '%s\n' "$report" >&2
+  exit 1
+fi
+gp_deny "$report"

package/registry/hooks/conventional-commit-check/hook.yaml

@@ -0,0 +1,16 @@
+id: conventional-commit-check
+kind: hook
+name: Conventional Commit Check
+description: Validates commit subjects against the Conventional Commits format, as a git commit-msg hook and as a PreToolUse guard on agent-issued git commit commands.
+tags: [git, commits, conventions, portable]
+# git-hooks target is the portable one — it runs for humans and CI, not just an agent session.
+targets: [claude-code, git-hooks]
+requiresCapability: [hooks]
+
+event: PreToolUse
+matcher: Bash
+gitHook: commit-msg
+entrypoints:
+  powershell: hook.ps1
+  bash: hook.sh
+config: [commitTypes, commitSubjectMaxLength, commitRequireScope]

package/registry/hooks/format-on-write/hook.ps1

@@ -0,0 +1,36 @@
+# PostToolUse (Edit|Write): run the declared formatter for the file's extension. Never blocks.
+. (Join-Path $PSScriptRoot '..\_lib\config.ps1')
+
+$payload = Read-GroundplanPayload
+$path = Get-GroundplanPayloadPath $payload
+if (-not $path -or -not (Test-Path $path)) { exit 0 }
+
+$extension = [System.IO.Path]::GetExtension($path).ToLowerInvariant()
+if (-not $extension) { exit 0 }
+
+$formatters = Get-GroundplanConfig 'formatters'
+$command = $formatters.$extension
+if (-not $command) { exit 0 }
+
+$parts = $command -split '\s+'
+$exe = $parts[0]
+$arguments = @($parts[1..($parts.Length - 1)]) + $path
+
+# Temp files, not 'NUL' — the device name only exists on Windows and would litter a Linux CI box.
+$stdout = [System.IO.Path]::GetTempFileName()
+$stderr = [System.IO.Path]::GetTempFileName()
+try {
+    $process = Start-Process -FilePath $exe -ArgumentList $arguments `
+        -NoNewWindow -PassThru -RedirectStandardOutput $stdout -RedirectStandardError $stderr
+    if (-not $process.WaitForExit([int](Get-GroundplanConfig 'formatTimeoutMs'))) {
+        $process.Kill()
+        [Console]::Error.WriteLine("format-on-write: '$exe' timed out on '$path' — left unformatted.")
+    }
+} catch {
+    # A missing formatter is a config gap, not a reason to fail the write.
+    [Console]::Error.WriteLine("format-on-write: '$exe' unavailable — skipped '$path'.")
+} finally {
+    Remove-Item $stdout, $stderr -Force -ErrorAction SilentlyContinue
+}
+
+exit 0

package/registry/hooks/format-on-write/hook.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# PostToolUse (Edit|Write): run the declared formatter for the file's extension. Never blocks.
+set -uo pipefail
+# shellcheck source=../_lib/config.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)/config.sh"
+
+gp_json_unavailable && exit 0
+
+path="$(cat | gp_json_field path)"
+[ -n "$path" ] && [ -f "$path" ] || exit 0
+
+extension=".${path##*.}"
+[ "$extension" = ".$path" ] && exit 0
+
+command_line="$(gp_config formatters | awk -F'\t' -v ext="$extension" '$1==ext {print $2}')"
+[ -n "$command_line" ] || exit 0
+
+exe="${command_line%% *}"
+command -v "$exe" >/dev/null 2>&1 || {
+  # A missing formatter is a config gap, not a reason to fail the write.
+  printf "format-on-write: '%s' unavailable — skipped '%s'.\n" "$exe" "$path" >&2
+  exit 0
+}
+
+timeout_s=$(( $(gp_config formatTimeoutMs) / 1000 ))
+if command -v timeout >/dev/null 2>&1; then
+  timeout "${timeout_s}s" $command_line "$path" >/dev/null 2>&1 \
+    || printf "format-on-write: '%s' failed or timed out on '%s'.\n" "$exe" "$path" >&2
+else
+  $command_line "$path" >/dev/null 2>&1 || true
+fi
+
+exit 0

package/registry/hooks/format-on-write/hook.yaml

@@ -0,0 +1,14 @@
+id: format-on-write
+kind: hook
+name: Format On Write
+description: Runs the declared formatter for a file's extension after Edit/Write. Advisory only — a missing or failing formatter never blocks the write.
+tags: [formatting, posttooluse, quality]
+targets: [claude-code]
+requiresCapability: [hooks]
+
+event: PostToolUse
+matcher: Edit|Write
+entrypoints:
+  powershell: hook.ps1
+  bash: hook.sh
+config: [formatters, formatTimeoutMs]

package/registry/hooks/guard-protected-paths/hook.ps1

@@ -0,0 +1,34 @@
+# PreToolUse (Edit|Write): block writes to declared protected or read-only paths.
+. (Join-Path $PSScriptRoot '..\_lib\config.ps1')
+
+$payload = Read-GroundplanPayload
+$path = Get-GroundplanPayloadPath $payload
+if (-not $path) { exit 0 }
+
+$norm = ConvertTo-GroundplanSlashPath $path
+
+# Allowlist first — .env.example must stay writable even though .env* is protected.
+if (Test-GroundplanAnyMatch $norm (Get-GroundplanConfig 'protectedAllowlist')) { exit 0 }
+
+if (Test-GroundplanAnyMatch $norm (Get-GroundplanConfig 'protectedPaths')) {
+    Deny-GroundplanTool @"
+BLOCKED: '$path' is a protected file.
+
+Protected paths hold credentials, lockfiles, or build/package config — an agent edit here has
+blast radius beyond the current task. Ask the user for explicit permission for THIS file, then retry.
+
+To change the rule instead of the file, edit the 'protectedPaths' key in the repo hook config.
+"@
+}
+
+if (Test-GroundplanAnyMatch $norm (Get-GroundplanConfig 'readOnlyPaths')) {
+    Deny-GroundplanTool @"
+BLOCKED: '$path' is in a READ-ONLY layer.
+
+This layer is declared read-only in the repo's architecture boundaries (see AGENTS.md).
+If the change is genuinely required, ask the user and explain WHY the boundary must move —
+not merely that it is convenient.
+"@
+}
+
+exit 0

package/registry/hooks/guard-protected-paths/hook.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# PreToolUse (Edit|Write): block writes to declared protected or read-only paths.
+set -euo pipefail
+# shellcheck source=../_lib/config.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)/config.sh"
+
+gp_security_unavailable "guard-protected-paths" "writes to protected and read-only paths" && exit 0
+
+payload="$(cat)"
+path="$(printf '%s' "$payload" | gp_json_field path)"
+[ -n "$path" ] || exit 0
+
+norm="$(gp_slash_path "$path")"
+
+# Allowlist first — .env.example must stay writable even though .env* is protected.
+gp_config protectedAllowlist | gp_match_any "$norm" && exit 0
+
+if gp_config protectedPaths | gp_match_any "$norm"; then
+  gp_deny "BLOCKED: '$path' is a protected file.
+
+Protected paths hold credentials, lockfiles, or build/package config — an agent edit here has
+blast radius beyond the current task. Ask the user for explicit permission for THIS file, then retry.
+
+To change the rule instead of the file, edit the 'protectedPaths' key in the repo hook config."
+fi
+
+if gp_config readOnlyPaths | gp_match_any "$norm"; then
+  gp_deny "BLOCKED: '$path' is in a READ-ONLY layer.
+
+This layer is declared read-only in the repo's architecture boundaries (see AGENTS.md).
+If the change is genuinely required, ask the user and explain WHY the boundary must move —
+not merely that it is convenient."
+fi
+
+exit 0

package/registry/hooks/guard-protected-paths/hook.yaml

@@ -0,0 +1,14 @@
+id: guard-protected-paths
+kind: hook
+name: Guard Protected Paths
+description: Blocks Edit/Write against declared protected paths (secrets, lockfiles, build config) and read-only architecture layers.
+tags: [safety, boundaries, pretooluse]
+targets: [claude-code]
+requiresCapability: [hooks]
+
+event: PreToolUse
+matcher: Edit|Write
+entrypoints:
+  powershell: hook.ps1
+  bash: hook.sh
+config: [protectedPaths, protectedAllowlist, readOnlyPaths]

package/registry/hooks/no-secrets/hook.ps1

@@ -0,0 +1,67 @@
+# Dual mode: git pre-commit (scans the staged diff) or PreToolUse Edit|Write (scans the pending content).
+param([switch]$GitHook)
+
+. (Join-Path $PSScriptRoot '..\_lib\config.ps1')
+
+$patterns = Get-GroundplanConfig 'secretPatterns'
+$allowlist = Get-GroundplanConfig 'secretAllowlist'
+$placeholder = Get-GroundplanConfig 'secretPlaceholderPattern'
+
+# Placeholder test runs on the matched token, not the line — otherwise the word "example"
+# anywhere on a line would suppress a real key sitting next to it.
+function Find-Secrets([string]$Text, [string]$Origin) {
+    $findings = @()
+    if (-not $Text) { return $findings }
+    $lineNumber = 0
+    foreach ($line in ($Text -split "`r?`n")) {
+        $lineNumber++
+        foreach ($pattern in $patterns) {
+            # -cmatch: token shapes like AKIA/ghp_ are case-sensitive, and patterns opt into (?i).
+            if ($line -cmatch $pattern) {
+                $matched = $Matches[0]
+                if ($matched -match $placeholder) { continue }
+                $findings += "  ${Origin}:${lineNumber} — matched /$pattern/"
+                break
+            }
+        }
+    }
+    return $findings
+}
+
+$findings = @()
+
+if ($GitHook) {
+    $staged = @(& git diff --cached --name-only --diff-filter=ACM)
+    foreach ($file in $staged) {
+        if (-not $file) { continue }
+        if (Test-GroundplanAnyMatch $file $allowlist) { continue }
+        $content = & git show ":$file" 2>$null
+        $findings += Find-Secrets ($content -join "`n") $file
+    }
+} else {
+    $payload = Read-GroundplanPayload
+    $path = Get-GroundplanPayloadPath $payload
+    if (-not $path) { exit 0 }
+    $norm = ConvertTo-GroundplanSlashPath $path
+    if (Test-GroundplanAnyMatch $norm $allowlist) { exit 0 }
+    $findings += Find-Secrets (Get-GroundplanPayloadContent $payload) $norm
+}
+
+if ($findings.Count -eq 0) { exit 0 }
+
+$report = @"
+BLOCKED: content matches a known secret pattern.
+
+$($findings -join "`n")
+
+Move the value to an environment variable and commit only a key-less example file.
+A committed secret is compromised even if the commit is amended away — rotate it.
+
+False positive? Add the path to 'secretAllowlist' or refine 'secretPatterns' in the repo hook config.
+"@
+
+if ($GitHook) {
+    [Console]::Error.WriteLine($report)
+    exit 1
+}
+Deny-GroundplanTool $report

package/registry/hooks/no-secrets/hook.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Dual mode: git pre-commit (scans the staged diff) or PreToolUse Edit|Write (scans the pending content).
+set -euo pipefail
+# shellcheck source=../_lib/config.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)/config.sh"
+
+git_hook=0
+[ "${1:-}" = "--git-hook" ] && git_hook=1
+
+placeholder="$(gp_config secretPlaceholderPattern)"
+findings=""
+
+# Placeholder test runs on the matched token (-o), not the line — otherwise the word "example"
+# anywhere on a line would suppress a real key sitting next to it.
+scan() {
+  local text="$1" origin="$2" pattern hit
+  while IFS= read -r pattern; do
+    [ -n "$pattern" ] || continue
+    hit="$(printf '%s' "$text" | grep -noP "$pattern" 2>/dev/null \
+          | grep -vP "$placeholder" 2>/dev/null | head -n1 || true)"
+    if [ -n "$hit" ]; then findings="$findings\n  $origin:${hit%%:*} — matched /$pattern/"; fi
+  done < <(gp_config secretPatterns)
+  return 0   # a no-match loop ends non-zero and set -e would abort the scan
+}
+
+if [ "$git_hook" -eq 1 ]; then
+  while IFS= read -r file; do
+    [ -n "$file" ] || continue
+    if gp_config secretAllowlist | gp_match_any "$file"; then continue; fi
+    scan "$(git show ":$file" 2>/dev/null || true)" "$file"
+  done < <(git diff --cached --name-only --diff-filter=ACM)
+else
+  gp_security_unavailable "no-secrets" "content for credential patterns" && exit 0
+  payload="$(cat)"
+  path="$(printf '%s' "$payload" | gp_json_field path)"
+  [ -n "$path" ] || exit 0
+  norm="$(gp_slash_path "$path")"
+  gp_config secretAllowlist | gp_match_any "$norm" && exit 0
+  scan "$(printf '%s' "$payload" | gp_json_field content)" "$norm"
+fi
+
+[ -z "$findings" ] && exit 0
+
+report="BLOCKED: content matches a known secret pattern.
+$(printf '%b' "$findings")
+
+Move the value to an environment variable and commit only a key-less example file.
+A committed secret is compromised even if the commit is amended away — rotate it.
+
+False positive? Add the path to 'secretAllowlist' or refine 'secretPatterns' in the repo hook config."
+
+if [ "$git_hook" -eq 1 ]; then
+  printf '%s\n' "$report" >&2
+  exit 1
+fi
+gp_deny "$report"

package/registry/hooks/no-secrets/hook.yaml

@@ -0,0 +1,16 @@
+id: no-secrets
+kind: hook
+name: No Secrets
+description: Blocks writes and commits containing credential-shaped strings, with a placeholder filter so example files stay usable.
+tags: [security, secrets, git, portable]
+# git-hooks target is the portable one — it also protects humans and CI, not just an agent session.
+targets: [claude-code, git-hooks]
+requiresCapability: [hooks]
+
+event: PreToolUse
+matcher: Edit|Write
+gitHook: pre-commit
+entrypoints:
+  powershell: hook.ps1
+  bash: hook.sh
+config: [secretPatterns, secretAllowlist, secretPlaceholderPattern]

package/registry/skills/adr-write/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: adr-write
+description: "Author an Architecture Decision Record at docs/adr/NNNN-title.md in MADR style. Use when the user says ADR, record this decision, why did we choose X, document the trade-off, supersede that decision, /adr — or when a choice will constrain future changes. NOT for choices a code comment can carry."
+metadata:
+  version: 1.0.0
+  category: architecture
+  updated: 2026-07-18
+---
+
+# ADR Author
+
+You are an expert at capturing a technical decision so that the person who inherits it — human or agent — understands *why*, not just *what*. Your goal is a short, honest record with real rejected alternatives and real consequences, including the bad ones.
+
+## Before Starting
+
+1. Read `docs/adr/` — list what exists, find the highest `NNNN`, and check whether this decision is already recorded or contradicts an accepted ADR.
+2. Read the ADR index in `AGENTS.md`. **The index belongs in `AGENTS.md`, not in ADR bodies.** ADRs are the archive; the index is the pointer.
+3. Read `AGENTS.md` `boundaries[]` and `conventions[]` — an ADR that changes either must say so explicitly, because those fields are what agents actually read.
+4. If a spec is in flight, read `specs/NNN-slug/plan.md` — the decision usually originates there.
+
+Ask only for what those do not answer: the forces in tension, the options genuinely considered, and who accepts the consequences.
+
+## How This Skill Works
+
+**Mode 1 — New ADR.** A decision has been made or is about to be. Write `docs/adr/NNNN-title.md`, status `proposed`, and update the `AGENTS.md` index.
+
+**Mode 2 — Supersede.** An accepted ADR no longer holds. Write the new one, link both directions, flip the old one to `superseded`. Never edit the old decision's body.
+
+**Mode 3 — Backfill.** The decision was made long ago and lives only in people's heads or a chat log. Reconstruct it, mark reconstructed reasoning 🔴 assumed, and get it confirmed before setting status to `accepted`.
+
+## Does this earn an ADR?
+
+| Signal | Verdict |
+|---|---|
+| Changes a declared boundary, or adds/removes a layer or module | ADR |
+| Picks a framework, datastore, protocol, or auth model | ADR |
+| Locks in a data shape others will build on | ADR |
+| Costs real money or real migration effort to reverse | ADR |
+| Someone will ask "why on earth is it like this?" in a year | ADR |
+| Two reasonable engineers would disagree | ADR |
+| Explains one confusing function or a workaround for a known upstream bug | Code comment |
+| A naming or formatting convention | `AGENTS.md` `conventions[]` |
+| Scoped to a single spec and dead when it ships | `specs/NNN-slug/plan.md` |
+| Reversible in an afternoon by one person | No record needed |
+
+The test: **is the cost of reversal high, or is the reasoning non-obvious?** Either one is enough. Neither means no ADR. See [references/when-to-write-an-adr.md](references/when-to-write-an-adr.md) for worked examples and the borderline cases.
+
+## Numbering and titles
+
+- `docs/adr/NNNN-kebab-title.md` — four digits, zero-padded, monotonic, **never reused**. Superseded records keep their number and stay on disk.
+- Title states the **decision**, not the topic. `0007-use-append-only-event-log-for-audit` beats `0007-audit-logging`. A reader scanning filenames should learn the decisions without opening anything.
+- One decision per ADR. If the title needs "and", split it.
+
+## Structure (MADR)
+
+Use [references/adr-template.md](references/adr-template.md) verbatim. The sections that carry the weight:
+
+- **Context and problem** — the forces in tension, stated so the decision looks difficult. If it reads obvious, you left out the pressure that made it hard.
+- **Considered options** — at least two real ones. "Do nothing" counts and is often the strongest rejected option. An ADR with one option is an announcement, not a decision.
+- **Decision** — one sentence, active voice, present tense: "We use X."
+- **Consequences** — split good and bad. **An ADR with no negative consequences is not finished.** Every real decision costs something; naming the cost is what makes the record trustworthy later.
+- **Confirmation** — how anyone checks the decision is actually being followed (a boundary rule, a lint rule, a test, a review checklist item).
+
+## Status lifecycle
+
+```
+proposed ──accepted──> accepted ──superseded by NNNN──> superseded
+    │
+    └──rejected──> rejected   (keep the file; the reasoning is the value)
+```
+
+- **proposed** — written, not yet agreed. Safe to revise the body.
+- **accepted** — agreed. **The body is now immutable.** Fix typos, nothing else. Changing an accepted ADR erases the history it exists to hold.
+- **superseded** — replaced. Add only the pointer line; leave the original reasoning intact.
+- **rejected** — considered and declined. Keep it. "We already looked at that and here's why not" is one of the highest-value things in the archive.
+- **deprecated** — no longer relevant, nothing replaced it (the subsystem is gone).
+
+## How to supersede
+
+1. Write the new ADR at the next number. Its **Context** explains what changed since the old one — new constraint, new information, or the original assumption proving false.
+2. In the new ADR: `Supersedes: [NNNN](NNNN-old-title.md)`.
+3. In the old ADR: change status to `superseded`, and add one line under it — `Superseded by [MMMM](MMMM-new-title.md) on YYYY-MM-DD`. Touch nothing else in that file.
+4. Update the `AGENTS.md` index: the old entry moves out of the recency window; the new one enters.
+5. If the decision changed a declared boundary, update `boundaries[]` in the same change — otherwise **architecture-guard** enforces a rule the team has abandoned.
+
+## The AGENTS.md index and the recency window
+
+ADR bodies are archive material — agents should rarely load them. What agents need is the *current* decision surface, and it lives in `AGENTS.md` as a compact index:
+
+- One line per ADR: number, title, status, and the one-sentence decision.
+- **Keep the last 3-5 accepted ADRs in the window, not the full history.** Recent decisions describe the system as it is now; a full list of thirty dilutes the signal and burns context on every request without changing behavior.
+- Superseded and rejected ADRs drop out of the window. They stay on disk and stay linked from the ADR that replaced them — reachable when someone asks "why not X?", absent otherwise.
+- Anything that must apply to *every* change is not index material: promote it into `conventions[]` or `boundaries[]`, where it is enforced, and let the ADR remain the rationale behind it.
+
+## Proactive Triggers
+
+- **A `plan.md` chooses a framework, datastore, protocol, or auth model** → propose an ADR before tasks are written.
+- **A change would move a declared boundary** → stop; that is an ADR, not a diff.
+- **A code comment starts explaining a trade-off over more than three lines** → the reasoning belongs in an ADR; leave a one-line pointer in the code.
+- **The same "why is it like this?" question comes up twice** → the decision was never recorded. Backfill it.
+- **A new change contradicts an accepted ADR** → flag it before implementation; either the change is wrong or the ADR needs superseding.
+- **The `AGENTS.md` index has grown past ~5 entries** → prune to the recency window; the archive keeps the rest.
+
+## Output Artifacts
+
+| When you ask for... | You get... |
+|---|---|
+| "Record this decision" | `docs/adr/NNNN-title.md` in MADR form, status proposed, plus the `AGENTS.md` index line |
+| "Should this be an ADR?" | Ruling with the reason, and the right home if not (comment / conventions / plan.md) |
+| "We changed our minds about X" | New ADR + supersede edits on the old one + index update + boundary sync if needed |
+| "Why do we do X?" | The relevant ADR quoted, or a statement that no ADR exists and an offer to backfill |
+| "Clean up our ADRs" | Index pruned to the recency window, orphaned supersede links repaired, statuses reconciled |
+
+## Communication
+
+Bottom line first: the decision in one sentence. Then the strongest rejected alternative — that is what a reader actually wants. Tag confidence: 🟢 stated by the team, 🟡 inferred from code, 🔴 reconstructed. Never write a consequences section that is all upside.
+
+## Related Skills
+
+- **architecture-guard**: Use to enforce boundaries an ADR established. NOT for deciding whether to change one.
+- **spec-driven**: Use when the decision is scoped to one spec — `plan.md` holds it. NOT for choices outliving the spec.
+- **handoff**: Use to carry an *undecided* question across tools; `.agent/DECISIONS.md` holds day-to-day calls, ADRs hold the durable ones.
+- **onboard**: Use to find decisions that were never recorded in an unfamiliar repo. NOT once the archive is current.
+- **security-review**: Use when the decision has a threat-model consequence worth naming in the ADR.
+- **perf-budget**: Use when the decision trades latency, bundle size, or vitals — the number belongs in Consequences.
+- **test-first**: Use when the ADR's Confirmation section should be a test rather than a review checklist item.
+- Commands: `/adr` scaffolds the record, `/plan` is where ADR candidates surface, `/review` flags changes contradicting an accepted ADR, `/handoff` carries an open decision to the next tool.