[Extension]: Add adrkit

[mbeacom]

Extension ID

adrkit

Extension Name

adrkit — decision memory for spec-driven development

Version

0.1.2

Description

Pulls the decisions governing this work into agent context, checks produced plans against them, and drafts an ADR from a plan artifact.

Author

Mark Beacom (@mbeacom)

Repository URL

https://github.com/mbeacom/adrkit

Download URL

https://github.com/mbeacom/adrkit/releases/download/spec-kit-v0.1.2/adrkit.zip

License

Apache-2.0

Homepage (optional)

https://adrkit.dev

Documentation URL (optional)

https://github.com/mbeacom/adrkit/blob/main/packages/adapters/spec-kit/README.md

Changelog URL (optional)

https://github.com/mbeacom/adrkit/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.13.0,<0.16.0

Required Tools (optional)

The adr CLI (npm install -g @adrkit/cli), version >=0.3.0. Resolved in a fixed order — ADRKIT_CLI, then ./node_modules/.bin/adr, then adr on PATH — and no branch of that reaches the network: a missing CLI is reported with a message naming it, never fetched.

Number of Commands

3

Number of Hooks (optional)

1

Tags

adr, governance, decision-records, architecture, compliance

Key Features

Spec Kit takes you from specify to plan to tasks to implement. What it does not do is check the plan it just produced against the decisions you already made, or record the new decisions that plan contains — so every feature starts from an empty context and re-litigates settled questions. This closes that loop, without leaving git.

• /speckit.adrkit.context — pulls the decisions governing the paths you are about to touch, including rejected and superseded ones, into agent context before you plan. The graveyard is where "we tried that" lives, and omitting it defeats the purpose. Read-only.
• /speckit.adrkit.check — checks a produced plan against the decisions that govern it, and additionally routes it through a deterministic evaluator when an offline snapshot bundle is configured. Read-only. This is the after_plan hook target.
• /speckit.adrkit.draft — scaffolds a schema-valid draft ADR from the current plan artifact at the next free id, for the agent to fill in. Leaves status draft; ratification is a human act.
• One optional after_plan hook — never mandatory. A governance tool that seizes the plan loop is a governance tool people uninstall.
• Hooks can only reach commands that do not write. draft is the only writing command and is deliberately unreachable from any hook: a plan-phase hook creating records unprompted would manufacture decision memory rather than record it. Enforced by a test, not a convention.
• Fails loudly, never silently. No command exits 0 having found nothing because it was looking in the wrong place — "0 decisions govern this" and "I could not see the corpus" must never render as the same string.
• Git-native. No database, no service, no network, no credentials. Decisions are markdown records in your repo, enforceable in CI.

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Installation verified through all three paths: the published npm tarball, the extracted release archive, and directly from the download URL above via specify extension add adrkit --from <url>.

Behavior is continuously validated in an isolated reference repository, mbeacom/adrkit-t018-dogfood, which reinstalls the extension from a pinned commit into a real Spec Kit project and asserts 41 outcomes per upstream version, on every push and weekly. The matrix covers 0.13.0, 0.14.4, and 0.15.1 — the endpoints and midpoint of the declared range — so the compatibility claim is re-checked rather than asserted once.

Assertions cover install and rendering, the hook contract (registered, optional: true, and not pointing at the writing command), packaging hygiene, behavior against a real ADR corpus, zero mutation of the consuming project, and four consumer-facing failure modes — each of which must exit non-zero, name what is missing, and write no record before failing.

The gate itself was verified by deliberately repointing it at an older commit and confirming all three legs go red: run 30779240521. A gate only ever seen green is a gate nobody has watched work.

Example Usage

specify extension add adrkit --from https://github.com/mbeacom/adrkit/releases/download/spec-kit-v0.1.2/adrkit.zip

# Before planning — pull in what already governs these paths
/speckit.adrkit.context src/payments/api.ts src/orders/ledger.ts

# /speckit.plan then offers:
#   "Check this plan against the decisions that govern it?"

# After planning — what does this plan touch, and where does it depart?
/speckit.adrkit.check src/payments/api.ts

# Record a decision the plan made
/speckit.adrkit.draft Adopt Postgres for the read model

Configuration is environment variables only: ADRKIT_DIR (corpus, default docs/adr), ADRKIT_CLI, ADRKIT_FEATURE_DIR, ADRKIT_SNAPSHOT, ADRKIT_AS_OF.

Proposed Catalog Entry

{
  "adrkit": {
    "name": "adrkit — decision memory for spec-driven development",
    "id": "adrkit",
    "description": "Pulls the decisions governing this work into agent context, checks produced plans against them, and drafts an ADR from a plan artifact.",
    "author": "Mark Beacom (@mbeacom)",
    "version": "0.1.2",
    "download_url": "https://github.com/mbeacom/adrkit/releases/download/spec-kit-v0.1.2/adrkit.zip",
    "repository": "https://github.com/mbeacom/adrkit",
    "homepage": "https://adrkit.dev",
    "documentation": "https://github.com/mbeacom/adrkit/blob/main/packages/adapters/spec-kit/README.md",
    "changelog": "https://github.com/mbeacom/adrkit/blob/main/CHANGELOG.md",
    "license": "Apache-2.0",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=0.13.0,<0.16.0",
      "tools": [{ "name": "adr", "version": ">=0.3.0", "required": true }]
    },
    "provides": {
      "commands": 3,
      "hooks": 1
    },
    "tags": ["adr", "governance", "decision-records", "architecture", "compliance"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-08-03T00:00:00Z",
    "updated_at": "2026-08-03T00:00:00Z"
  }
}

Additional Context

category: process and effect: read-write are declared in extension.yml. read-write is the honest value even though the hook surface and two of the three commands write nothing — draft writes one record, and the field should describe the most an extension can do rather than what it usually does.

Also published on npm as @adrkit/spec-kit with signed provenance, versioned independently of the rest of the @adrkit scope: its semver contract is with Spec Kit, not with @adrkit/core.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

Pull request created: #3947

Generated by Add Community Extension from Issue Submission · 249.8 AIC · ⌖ 16.3 AIC · ⊞ 35.3K

[mnriem]

Thank you!