ADR-013: Spec Kit is a vendored, pinned engine - ours to patch, synced at release time


Status	Superseded by ADR-015 (2026-07-22)
Date	2026-07-22
Author	Łukasz Bodurka
Tags	spec-kit, engine, dependencies, naming, skills, vendoring

Context

The standard's spec flow runs on GitHub Spec Kit (specify -> clarify -> plan -> tasks), and the owner asked: should our skills carry the Spec Kit name, do we track upstream, is the dependency even needed? The facts:

Our skills never were Spec Kit's. spec-impact, spec-update, spec-analyze, spec-converge, spec-reconcile are this standard's own layer - they wrap the engine, they did not come from it.
On the agent side, Spec Kit is mostly prompt files and helper scripts (the speckit.* command templates, .specify/ scripts, the constitution template) - the owner's observation "to tylko skille w sumie" is essentially correct; the Python CLI exists to install and template them.
Upstream is very alive and volatile: 55+ releases in H1 2026, ~111k stars, and a real breaking change (v0.10.0 dropped the --ai flags for --integration + extensions/hooks). Fast-moving cuts both ways: maintained, and breaking.
We already patch around it (capability paths instead of NNN- dirs; the clarify gate wired via extensions/hooks) - overrides that today live outside the engine's own files.

Options considered

A - Fork / absorb the whole project. Full control; inherits a 55-releases-a-quarter maintenance treadmill including the CLI and 30+ agent integrations we do not need.
B - Chase upstream continuously. Pure cost; almost none of upstream's churn touches our surface.
C - Engine by reference (this record's first draft): consumers install upstream via its CLI at a pinned version; the standard names its surface and re-tests at release time. Low cost, but consumers stay exposed to CLI breaking changes and our patches live awkwardly around the engine's files instead of in them.
D - Vendored, pinned, patched copy (chosen - owner amendment, 2026-07-22). The standard carries a local copy of the agent-side Spec Kit assets (command prompts, scripts, constitution template) at a pinned upstream version, patched for our conventions (capability paths, the clarify-gate hooks pre-wired, statuses), and ships them in dist/ like everything else. Upstream is re-synced only when the standard cuts a release. Attribution: MIT, "based on github/spec-kit vX.Y".

Decision

Option D. Concretely:

Vendor the agent-side assets at the current tested version (0.13.x line) into a zone-2 source dir, patched: capability paths (ADR-002), the clarify gate as mandatory hooks (not an optional add-on), spec Status wiring (ADR-010). Consumers no longer need upstream's CLI at all - dist/ carries a working, pre-patched engine. Executed as ENG-5 (its own PR - it fetches and tests real upstream files).
Sync cadence: upstream checked when the standard releases, never continuously. Each sync records "based on github/spec-kit vX.Y" + the patch list; a breaking upstream change is absorbed here once, and consumers get it via update-to-version - they are never exposed to upstream directly.
Naming: our spec-* skills stay our own and are never called "speckit"; the vendored files keep upstream's speckit.* command names (honest attribution both ways: "the engine is based on Spec Kit vX.Y; the standard's layer is ours").
Exit clause unchanged: the gate, statuses, and spec-* skills survive an engine swap; with a vendored copy the standard even survives upstream vanishing.

Consequences

Positive: consumers get a deterministic, pre-patched engine with zero install dependency on upstream's CLI and zero exposure to its breaking changes; our overrides live in the engine files instead of around them; independence with honest attribution.
Negative: the standard owns the sync work each release (bounded: prompts + scripts, not the CLI); vendored files can drift from upstream improvements between releases - accepted, that is the point; the MIT license + notice must ship alongside.

Confirmation

Landed 2026-07-22 (ENG-5): standard/spec-kit/ (v0.13.2, 4 marked patches) renders to dist/.claude/skills/speckit-* - the skills layout, per the owner's simplification call (one distribution mechanism beside the standard's own skills; upstream v0.13.2 itself installs skills) - plus the shared runtime in dist/.specify/ with the MIT license and per-file provenance notes. spec-kit-setup.md no longer requires the upstream CLI; the gate and capability-path behavior are verified by scripted tests.

Revisit when

Upstream stabilizes into a boring, slow-moving spec (then by-reference gets cheap again), or the vendored surface grows beyond prompts + scripts (then we are forking, and should say so).

ADR-002 (capability paths - now patched in, not fought around), ADR-009 (our skills ship, transition skills do not), ADR-010 (statuses + gate), ENG-5 in backlog.md; spec-kit-setup.md.