The Problem

Teams adopting AI coding agents often find the agents produce inconsistent, low-quality code because there's no shared process for defining what to build before building it. Traditional specs are written once and discarded, so the agent's output drifts from the intended design. Spec Kit addresses this by making specifications executable — the spec becomes the input that directly drives implementation, rather than a document that merely guides it.

What This Does

Spec Kit is an open-source toolkit that provides a spec-driven development workflow for any AI coding agent. The core is a Python CLI (src/specify_cli/) that initializes projects, manages specifications, and orchestrates the build process. The repo includes a preset system (presets/) — e.g., lean and scaffold — that define phase-based workflows (plan, specify, implement, tasks), each with markdown command templates the agent executes.

Extensions (extensions/) add agent-specific capabilities: git handles commit/feature-branch automation, agent-context maintains context files, and assess/bug provide intake and bug-fix workflows. Each extension declares its commands in an extension.yml and ships scripts in bash/, powershell/, and python/. Bundles (examples/bundles/) combine presets and extensions for role-specific setups like business-analyst or security-researcher.

How It Is Wired

Execution starts with specify init, defined in src/specify_cli/commands/init. It calls into src/specify_cli/integrations/ to scaffold a project for a specific agent (e.g., Copilot). The integrations layer is the hub: integrations/base.py is imported by 41 modules and is the widest blast radius in the repo. The command layer (commands/bundle/__init__.py) imports 20 modules, making it a high-fan-out coordinator.

The module graph shows 18 modules in circular import cycles, including src/specify_cli/__init__.py and extensions/__init__.py. That means changing shared types or extension loading logic risks breaking the cycle. The integrations/__init__.py module sits at instability 0.78 — it both imports widely and is imported widely, so it's a chokepoint for any change.

The CLI's external effects are filesystem writes: it creates project directories, writes spec templates, and runs git commands via the extensions/git/scripts/. No database or network calls are mapped in the analyzed paths.

How To Use It

Setup: Install via uv (the README documents this as the primary path):

uv tool install specify-cli

Configuration: No required environment variables. Agent integrations are configured at specify init time via the --integration flag. Extensions have optional config-template.yml files (e.g., extensions/git/config-template.yml) for customization.

Running it:

specify init my-project --integration copilot
cd my-project
specify self check  # verify installation

The presets/lean/commands/ directory contains the actual workflow commands (speckit.plan, speckit.specify, speckit.implement) the agent invokes.

Real-World Use

A team standardizing on Copilot can run specify init to scaffold a repo with the lean preset. The agent then follows speckit.plan → speckit.specify → speckit.implement, producing a spec-first workflow. The git extension auto-commits and creates feature branches, so the entire process — from spec to merged code — runs through the agent with consistent structure across the team.

Code Health & Issues

Static analysis found 127 findings (45 high, 82 medium) across 7 kinds:

  • High - Oversized files — src/specify_cli/integrations/base.py (1202 lines), extensions/__init__.py, presets/__init__.py. Hard to hold in one head; changes ripple widely.
  • High - Deep nesting — max indentation depth 7 in integrations/base.py and integrations/manifest.py; control flow is hard to follow.
  • High - Hub modules — 41 modules depend on integrations/base.py; churn there is high-blast-radius.
  • High - Import cycles — 15 modules participate in circular imports, including src/specify_cli/__init__.py.
  • High - Duplicated code — 861 repeated 6-line blocks across 101 files, mostly in extensions/ scripts.
  • Medium - Broad exception handling — 8 instances of bare except swallowing errors.
  • Medium - File handles — 2 files opened without context managers (authentication/http.py, workflows/_commands.py).

SDLC observations: CI exists (GitHub Actions) but the 4 workflows read contain no test command despite 137 test files. The release workflow pushes directly to the default branch, and pyproject.toml has no lockfile, so builds aren't reproducible. No dependency vulnerability scan is gated on pull requests.

The Bottom Line

Spec Kit is a well-structured toolkit for teams that want a repeatable, agent-driven development process. The extension/preset architecture is genuinely flexible, and the docs are thorough. The main risks are the import cycles and hub modules that will make structural changes painful, plus the CI gaps that mean a green check doesn't guarantee tests ran. Teams already committed to a spec-first workflow with AI agents will find this useful; teams without that process will find the learning curve steep.