Spec-Kit Integration

If you already use spec-kit — GitHub's open-source spec-driven development workflow — you can author SPECLAN specifications from inside any of the 30+ AI coding agents spec-kit supports. Claude, Cursor, Codex, Cline, Windsurf, Gemini — they all become SPECLAN-aware once the speckit-speclan extension is installed.

This is the spec-kit-first path into SPECLAN. The VS Code extension is still the richest way to browse and review specs, but the spec-kit integration lets you do the authoring from whichever agent you already work in.

What You Get

The speckit-speclan extension composes spec-kit's slash-command workflow with SPECLAN's typed entity model and status lifecycle:

Typed entities — Goals, Features, Requirements, Change Requests with collision-checked IDs (G-###, F-####, R-####, CR-####) instead of folder numbers.
Status lifecycle — every entity moves through draft → review → approved → in-development → under-test → released → deprecated. /implement is gated on approved.
CR-gated edits — once a spec is locked (in-development or later), edits must go through a Change Request whose lifecycle governs the merge.
Pure shell — bash + yq + jq; no Node, no Python on your machine.
Drop-in hooks — /specify, /clarify, and /implement participate in the SPECLAN lifecycle automatically.

Prerequisites

spec-kit ≥ 0.8.0 installed (specify CLI on PATH).
An AI coding agent spec-kit supports.
bash ≥ 4, yq ≥ 4, jq ≥ 1.6, git ≥ 2.30.

Installation

Once the extension is listed in spec-kit's community catalog:

specify extension add speclan

Before the catalog PR is merged, install directly from the GitHub Release:

specify extension add speclan --from https://github.com/thlandgraf/speckit-speclan/releases/latest/download/speckit-speclan.zip

For contributors testing a local clone:

specify extension add --dev /path/to/speckit-speclan

Then verify:

specify extension list
# → speclan  0.1.0  Apache-2.0

If you previously installed an earlier build and need to refresh, remove first — specify extension remove keeps a backup at .specify/extensions/.backup/ so you can roll back:

specify extension remove speclan
specify extension add --dev /path/to/speckit-speclan

You may see ⚠ Configuration may be required after install. That message is a generic hint that fires whenever an extension declares provides.config entries — the speclan-config.yml this extension ships is required: false, so safe to ignore unless you want to override the defaults (spec_root, locked statuses, gate behaviour, etc.) baked into data/format-spec.json.

Spec-kit version floor

This extension declares requires.speckit_version: ">=0.8.15". If your specify CLI is older, install a newer version with force-reinstall (uv tool upgrade does NOT accept --from):

uv tool install --force specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.16

Commands

The extension contributes 11 commands. Seven are user-facing; the other four (intake, gate, migrate, plan) are typically run via hooks or for one-shot operations.

`/speckit.speclan.specify <description>`

Create a Goal, Feature, or Requirement from a natural-language description. The extension picks the entity type from cues in the prompt and assigns a collision-checked ID.

> /speckit.speclan.specify a magic-link login flow for the web app

✓ Created speclan/features/F-7421-magic-link-login/F-7421-magic-link-login.md
✓ Wrote pointer specs/001-magic-link-login/SPECLAN.md

`/speckit.speclan.clarify <ID>`

Refine an entity. Behaviour depends on the entity's current status:

Unlocked (draft / review / approved) — direct edit. The body is updated and the updated: frontmatter is bumped.
Locked (in-development / under-test / released) — a Change Request is created under <parent>/change-requests/. The CR body is pre-populated with the current spec and a description of the proposed change.
Deprecated — refused.

> /speckit.speclan.clarify R-3094 also support magic links sent via SMS

✓ R-3094 is approved → direct edit applied
✓ updated: 2026-05-22

`/speckit.speclan.status <ID> <new-status>`

Advance an entity through the lifecycle. Transitions are forward-only — you cannot move a released spec back to approved.

> /speckit.speclan.status R-3094 approved

✓ R-3094: review → approved

`/speckit.speclan.implement <R-####>`

Implement an approved Requirement. The command is gated on status: approved; non-approved requirements are refused with a clear error. On success the status transitions to in-development.

> /speckit.speclan.implement R-3094

✓ Gate passed (R-3094 is approved)
…agent implements…
✓ R-3094: approved → in-development

`/speckit.speclan.cr-create <ID> <change-type>`

Open a Change Request against a locked spec. change-type is one of enhancement, bugfix, breaking, deprecation, documentation, artifact.

> /speckit.speclan.cr-create R-3094 enhancement add SMS magic-link support

✓ Created speclan/features/F-7421-…/requirements/R-3094-…/change-requests/CR-0567-sms-magic-link/CR-0567-sms-magic-link.md

`/speckit.speclan.cr-merge <CR-####>`

Merge an approved CR back into its parent. The original parent body is archived to a .pre-CR-####.bak file in the same directory; the parent's body is replaced with the CR's body verbatim.

> /speckit.speclan.cr-merge CR-0567

✓ Archived parent → R-3094-…/R-3094-….pre-CR-0567.bak
✓ Merged CR-0567 into R-3094
✓ CR-0567: approved → released

`/speckit.speclan.cr-close <CR-####> --reason <reason>`

Close a CR without merging. Reason is one of rejected, cancelled, superseded, duplicate, obsolete.

> /speckit.speclan.cr-close CR-0567 --reason duplicate

✓ CR-0567: review → deprecated (reason: duplicate)

The Composition Model

The integration solves the two-stores problem by making each tool own its own surface:

Concern	Owner	Where it lives
Spec body (the WHAT)	SPECLAN	`speclan/features/F-####-slug/F-####-slug.md`
Working artifacts (the HOW)	spec-kit	`specs/NNN-feature/plan.md`, `tasks.md`, `data-model.md`, …
Lifecycle & governance	SPECLAN	YAML frontmatter, status DAG, Change Requests
Agent UX	spec-kit	slash commands, agent rendering, plan/tasks/implement workflow
Cross-link	`SPECLAN.md` pointer	`specs/NNN-feature/SPECLAN.md`

When you run /specify (vanilla spec-kit), the after_specify hook silently moves the generated spec.md into the SPECLAN tree, replaces it with a SPECLAN.md pointer, and assigns an ID. From that point forward, every command — vanilla spec-kit or /speckit.speclan.* — reads the spec body from the canonical SPECLAN location.

speclan/                                  ← canonical store (SPECLAN owns)
  features/F-7421-login/
    F-7421-login.md                       ← THE spec
    requirements/R-3094-token-issuance/
      R-3094-token-issuance.md
    change-requests/CR-0567-sms/
      CR-0567-sms.md

specs/                                    ← working dir (spec-kit owns)
  001-login/
    SPECLAN.md                            ← pointer to speclan/features/F-7421-login/
    plan.md                               ← references F-7421 / R-3094
    tasks.md                              ← references R-3094
    data-model.md

Hook Integration

Three spec-kit hooks are wired automatically:

Hook	Dispatches	What it does
`after_specify`	`/speckit.speclan.intake`	Moves `specs/NNN/spec.md` into the SPECLAN tree; writes `SPECLAN.md` pointer. No-op on projects without `speclan/`.
`after_clarify`	`/speckit.speclan.clarify`	Routes the clarification through SPECLAN's status dispatch (direct edit if unlocked, CR if locked). Optional — prompts the user.
`before_implement`	`/speckit.speclan.gate`	Blocks `/implement` unless every referenced entity is in `approved` status. Non-SPECLAN projects pass through silently.

The hooks degrade gracefully — if the project has no speclan/ directory, every hook exits 0 silently and vanilla spec-kit behaviour is preserved.

Migrating Existing Projects

If you already have specs/NNN-feature/ directories from previous spec-kit work, run:

/speckit.speclan.migrate 001-login

The command converts the existing spec.md into a SPECLAN entity (preserving the body byte-for-byte) and writes the SPECLAN.md pointer. Every other file in the directory (plan.md, tasks.md, data-model.md, …) is preserved unchanged.

Status Lifecycle

draft → review → approved → in-development → under-test → released → deprecated

draft → review → approved — edits are direct.
in-development → under-test → released — the spec is locked; every edit must go through a Change Request. /clarify and /implement route appropriately.
deprecated — terminal. No further mutations allowed.

See the Status Lifecycle reference for the full state machine and transition rules.

Configuration

Defaults are sensible out of the box. To override, edit .specify/extensions/speclan/speclan-config.yml after installation. The full default template lives in config-template.yml inside the public repo.

Resources

thlandgraf/speckit-speclan on GitHub — source, releases, issue tracker.
spec-kit community catalog entry — find the speclan entry alongside other extensions.
spec-kit documentation — base workflow this extension extends.
SPECLAN VS Code Extension — rich UI for SPECLAN specs.
thlandgraf/speclan-essentials — SPECLAN public docs and issue tracker.

Feedback

Bug reports and feature requests are tracked on the thlandgraf/speckit-speclan issues page. For SPECLAN format questions, use thlandgraf/speclan-essentials.