Overview

Relevant source files

• .zenodo.json
• AGENTS.md
• CHANGELOG.md
• CITATION.cff
• README.md
• docs/community/friends.md
• docs/community/walkthroughs.md
• docs/concepts/sdd.md
• docs/concepts/spec-persistence.md
• docs/docfx.json
• docs/guides/evolving-specs.md
• docs/guides/existing-projects.md
• docs/history.md
• docs/images/spec-kit-logo.webp
• docs/index.md
• docs/install/pypi.md
• docs/installation.md
• docs/quickstart.md
• docs/template/public/main.css
• docs/toc.yml
• docs/upgrade.md
• pyproject.toml
• src/specify_cli/__init__.py

Purpose and Scope

This document provides a high-level architectural overview of Spec Kit, an open-source toolkit that implements Spec-Driven Development (SDD) for AI-assisted software development. It explains the system's core components, how they interact, and the key code entities that implement the functionality.

Spec Kit flips the traditional software development script by making specifications executable, directly generating working implementations through AI agents rather than just guiding them README.md55-58 One year after its inception, Spec Kit has reached the v1.0.0 milestone README.md24-26 evolving from a set of templates into a coherent, adaptable process harness shaped by its community README.md28-30

This overview covers:

• The Spec-Driven Development methodology and workflow README.md55-80 docs/quickstart.md15-36
• System architecture and major components src/specify_cli/__init__.py14-27 AGENTS.md27-48
• How the specify CLI orchestrates project initialization src/specify_cli/__init__.py601
• Integration with 30+ AI coding agents via the INTEGRATION_REGISTRY AGENTS.md29-30 AGENTS.md47-48
• The modular extension, preset, workflow, and bundle systems for ecosystem customization src/specify_cli/__init__.py601 CHANGELOG.md9-34

Sources: README.md1-80 src/specify_cli/__init__.py14-27 AGENTS.md3-11 docs/index.md22-64

---

What is Spec-Driven Development?

Spec-Driven Development is a structured methodology where specifications and implementation plans serve as the primary artifacts that generate code README.md57-58 SDD eliminates the gap between intent and implementation by making natural language requirements precise enough for AI transformation.

The workflow progresses through core phases, often refined with quality gates docs/quickstart.md25-36:

Phase	Slash Command	Output Artifact	Purpose
Constitution	/speckit.constitution	.specify/memory/constitution.md	Ground rules and principles docs/quickstart.md54-60
Specify	/speckit.specify	specs/NNN-feature/spec.md	Natural language feature description docs/quickstart.md62-68
Clarify	/speckit.clarify	Refined spec.md	Resolve ambiguities before planning docs/quickstart.md70-76
Plan	/speckit.plan	specs/NNN-feature/plan.md	Technical stack and architecture docs/quickstart.md78-84
Checklist	/speckit.checklist	specs/NNN-feature/checklist.md	Quality gates for requirements docs/quickstart.md86-92
Tasks	/speckit.tasks	specs/NNN-feature/tasks.md	Actionable, dependency-ordered tasks docs/quickstart.md94-100
Analyze	/speckit.analyze	Consistency Report	Cross-artifact gap detection docs/quickstart.md102-108
Implement	/speckit.implement	Working Code	Build the feature based on tasks docs/quickstart.md110-116
Converge	/speckit.converge	New Tasks (if needed)	Verify codebase against spec/plan docs/quickstart.md118-124

Sources: README.md55-80 docs/quickstart.md25-36 docs/installation.md118-130 CHANGELOG.md122

---

System Architecture Overview

The following diagram maps natural language concepts to their code implementations and shows how the specify CLI bootstraps the environment for AI agents.

System Components and Code Entities

Key Code Entities:

Component	Primary Implementation	Purpose
specify CLI	src/specify_cli/__init__.py91-97	Main entry point; handles CLI arguments and command routing via typer.
INTEGRATION_REGISTRY	AGENTS.md29-30	Single source of truth for agent metadata and capability mapping AGENTS.md47-48
init_project()	src/specify_cli/__init__.py601	Core logic for scaffolding projects and installing templates.
WorkflowEngine	src/specify_cli/workflows/	Executes multi-step automation pipelines CHANGELOG.md135
ExtensionManager	src/specify_cli/extensions.py	Manages modular extensions and hook execution.
Bundler	src/specify_cli/bundler/	Composes extensions, presets, and workflows into role-oriented packages CHANGELOG.md95
Slash commands	templates/commands/	Markdown/TOML templates defining AI agent capabilities pyproject.toml38-39

Sources: src/specify_cli/__init__.py601 AGENTS.md27-48 pyproject.toml31-54 CHANGELOG.md9-104

---

Core Components

1. The specify CLI

The specify command-line tool, implemented in src/specify_cli/__init__.py is the primary interface for developers to bootstrap their projects for SDD. It is built using the typer library pyproject.toml8-9

Commands:

Command	Implementation	Purpose
specify init	src/specify_cli/__init__.py601	Bootstraps a project with templates, scripts, and agent config.
specify integration	src/specify_cli/__init__.py601	Manages agent integration lifecycle (install, switch, upgrade).
specify workflow	src/specify_cli/workflows/	Runs and manages SDD automation pipelines CHANGELOG.md135
specify extension	src/specify_cli/__init__.py601	Subcommands for managing modular extensions.
specify bundle	src/specify_cli/bundler/	Manages role-based component bundles CHANGELOG.md95
specify self	src/specify_cli/_version.py73-76	Handles CLI version checks and self-upgrades docs/upgrade.md24-40

Key Functions:

• init_project() src/specify_cli/__init__.py601 — Orchestrates directory creation and script installation.
• _install_shared_infra() src/specify_cli/__init__.py135-188 — Installs core scripts and templates into the project.
• generate_commands() src/specify_cli/__init__.py601 — Processes generic command templates into agent-specific formats.

Sources: src/specify_cli/__init__.py91-115 src/specify_cli/__init__.py601 docs/upgrade.md24-87 CHANGELOG.md95

2. AI Agent Integration Architecture

Spec Kit supports 30+ AI agents by abstracting their directory conventions and command formats. Each agent is a self-contained subpackage under src/specify_cli/integrations/ AGENTS.md29-30

Base Classes for Integrations AGENTS.md79-85:

• MarkdownIntegration: For standard markdown commands (.md).
• TomlIntegration: For TOML-format commands (e.g., Gemini).
• YamlIntegration: For YAML recipe files.
• SkillsIntegration: For skill-based agents (e.g., Claude Code, Codex, Kimi).

Agent Metadata Example (Markdown agent) AGENTS.md93-117:

• Key: kilocode
• Folder: .kilo/
• Commands Subdir: commands
• Format: markdown

Sources: AGENTS.md13-156 src/specify_cli/__init__.py77-83 CHANGELOG.md9-10

3. Slash Commands and Artifact Templates

Slash commands are the primary way users interact with Spec Kit through an AI agent's chat interface. These are defined as templates in templates/commands/ and processed during initialization into the agent's native format src/specify_cli/__init__.py601

Core Workflow Commands:

Command File	Slash Command	Purpose
templates/commands/constitution.md	/speckit.constitution	Establishes project principles docs/quickstart.md54-60
templates/commands/specify.md	/speckit.specify	Creates a new feature branch and spec file docs/quickstart.md62-68
templates/commands/plan.md	/speckit.plan	Generates a technical implementation plan docs/quickstart.md78-84
templates/commands/tasks.md	/speckit.tasks	Generates a dependency-ordered task list docs/quickstart.md94-100
templates/commands/converge.md	/speckit.converge	Resolves implementation/spec drift docs/quickstart.md118-124
templates/commands/implement.md	/speckit.implement	Executes implementation tasks docs/quickstart.md110-116

Sources: templates/commands/ , src/specify_cli/__init__.py601 README.md91-133 docs/quickstart.md15-36

---

Developer Workflow Sequence

The following diagram illustrates the interaction between the developer, the CLI, and the AI agent during a typical feature development cycle.

Developer Journey Through Code Entities

Key Integration Points:

• CLI → FS: init_project() populates the infrastructure src/specify_cli/__init__.py601
• Agent → Scripts: Slash commands execute shell scripts via agent tool-calling capabilities templates/commands/
• Scripts → FS: Scripts handle directory management and feature tracking state in .specify/feature.json docs/quickstart.md13

Sources: README.md91-133 src/specify_cli/__init__.py601 docs/quickstart.md13-36

---

Summary

Spec Kit provides a robust foundation for Spec-Driven Development by:

1. Abstracting AI Agents: Providing a unified INTEGRATION_REGISTRY for 30+ coding assistants AGENTS.md27-48
2. Standardizing Workflows: Defining a clear path from natural language intent to working code via slash commands README.md91-133
3. Providing Cross-Platform Logic: Offering a multi-variant script layer (Bash/PowerShell/Python) for core operations src/specify_cli/__init__.py145-150
4. Enabling Customization: Offering extension, preset, and bundle systems to adapt the workflow to specific project needs src/specify_cli/__init__.py601

For more information, see the following pages:

• Getting Started: Initial setup and your first project.
• Spec-Driven Development: Deep dive into the SDD methodology.
• specify CLI Reference: Detailed command documentation.
• Slash Commands Reference: Documentation of /speckit.* agent commands.
• AI Agent Integration: Details on configuration and agent context management.
• Extension, Preset, and Bundle Systems: Documentation on the modular ecosystem.

Sources: README.md1-47 src/specify_cli/__init__.py14-27 AGENTS.md3-11