Overview

Relevant source files

• .github/skills/add-community-extension/SKILL.md
• AGENTS.md
• CHANGELOG.md
• README.md
• docs/community/extensions.md
• docs/community/friends.md
• docs/concepts/sdd.md
• docs/concepts/spec-persistence.md
• docs/docfx.json
• docs/index.md
• docs/template/public/main.css
• docs/toc.yml
• extensions/catalog.community.json
• 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.md41-43

This overview covers:

• The Spec-Driven Development methodology and workflow README.md65-104
• System architecture and major components src/specify_cli/__init__.py14-27 AGENTS.md13-37
• How the specify CLI orchestrates project initialization src/specify_cli/__init__.py1265-1518
• Integration with 30+ AI coding agents via the INTEGRATION_REGISTRY src/specify_cli/integrations/__init__.py15-20 AGENTS.md13-16
• The modular extension, preset, and bundle systems for ecosystem customization src/specify_cli/__init__.py2603-2618 CHANGELOG.md95

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

---

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.md41-43 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:

Phase	Slash Command	Output Artifact
Constitution	/speckit.constitution	.specify/memory/constitution.md
Specify	/speckit.specify	specs/NNN-feature/spec.md
Clarify	/speckit.clarify	Refined spec.md
Checklist	/speckit.checklist	specs/NNN-feature/checklist.md
Plan	/speckit.plan	specs/NNN-feature/plan.md
Tasks	/speckit.tasks	specs/NNN-feature/tasks.md
Analyze	/speckit.analyze	Consistency Report
Converge	/speckit.converge	Resolved Implementation Gaps
Implement	/speckit.implement	Working Application Code

Sources: README.md65-104 CHANGELOG.md122 docs/concepts/sdd.md20-27

---

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__.py92-98	Main entry point; handles CLI arguments and command routing via typer.
INTEGRATION_REGISTRY	src/specify_cli/integrations/__init__.py15-20	Single source of truth for agent metadata and capability mapping AGENTS.md13-16
init_project()	src/specify_cli/__init__.py1265-1518	Core logic for scaffolding projects and installing templates.
WorkflowEngine	src/specify_cli/workflows/	Executes multi-step automation pipelines CHANGELOG.md125
ExtensionManager	src/specify_cli/extensions.py	Manages modular extensions and hook execution docs/community/extensions.md23-25
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/integrations/__init__.py15-20 src/specify_cli/__init__.py1265-1518 AGENTS.md13-37 pyproject.toml31-41 CHANGELOG.md95

---

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.toml7-10

Commands:

Command	Implementation	Purpose
specify init	src/specify_cli/__init__.py2660-2722	Bootstraps a project with templates, scripts, and agent config.
specify integration	src/specify_cli/__init__.py2083	Manages agent integration lifecycle (install, switch, upgrade).
specify workflow	src/specify_cli/__init__.py25-26	Runs and manages SDD automation pipelines CHANGELOG.md121-125
specify extension	src/specify_cli/__init__.py2603-2609	Subcommands for managing modular extensions docs/community/extensions.md23-25
specify bundle	src/specify_cli/bundler/	Manages role-based component bundles CHANGELOG.md95
specify self	src/specify_cli/_version.py77-79	Handles CLI version checks and self-upgrades README.md65-79

Key Functions:

• init_project() src/specify_cli/__init__.py1265-1518 — Orchestrates directory creation and script installation.
• _install_shared_infra() src/specify_cli/__init__.py134-185 — Installs core scripts and templates into the project.
• generate_commands() src/specify_cli/__init__.py1633-1881 — Processes generic command templates into agent-specific formats.

Sources: src/specify_cli/__init__.py92-115 src/specify_cli/__init__.py1265-1518 README.md49-79 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.md13-16 Recent additions include Zed CHANGELOG.md151 ZCode CHANGELOG.md77 and Firebender CHANGELOG.md62

Base Classes for Integrations AGENTS.md41-48:

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

Agent Metadata Example (Windsurf) AGENTS.md63-79:

• Key: windsurf
• Folder: .windsurf/
• Commands Subdir: workflows
• Format: markdown

Sources: AGENTS.md13-156 src/specify_cli/integrations/__init__.py15-20 CHANGELOG.md151

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.

Core Workflow Commands:

Command File	Slash Command	Purpose
templates/commands/constitution.md	/speckit.constitution	Establishes project principles README.md84-89
templates/commands/specify.md	/speckit.specify	Creates a new feature branch and spec file README.md91-97
templates/commands/plan.md	/speckit.plan	Generates a technical implementation plan README.md99-105
templates/commands/tasks.md	/speckit.tasks	Generates a dependency-ordered task list README.md107-113
templates/commands/converge.md	/speckit.converge	Resolves implementation/spec drift CHANGELOG.md122
templates/commands/implement.md	/speckit.implement	Executes implementation tasks README.md115-121

Sources: templates/commands/ , src/specify_cli/__init__.py1520-1631 README.md81-121 CHANGELOG.md122

4. Shell Scripts Layer

Operational logic invoked by slash commands is provided by scripts located in scripts/bash/ and scripts/powershell/ pyproject.toml40-41 This ensures cross-platform compatibility for core logic.

Key Operations:

• Branch Management: Automates feature branch numbering and creation via create-new-feature CHANGELOG.md105
• Context Synchronization: Syncs technical stacks and plans to agent memory files via update-agent-context CHANGELOG.md12
• Prerequisite Validation: Ensures the agent has completed previous phases before proceeding via check-prerequisites CHANGELOG.md49

Sources: pyproject.toml40-41 CHANGELOG.md12-105 src/specify_cli/__init__.py134-185

---

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__.py1265-1518
• Agent → Scripts: Slash commands execute shell scripts via agent tool-calling capabilities templates/commands/
• Scripts → FS: Scripts handle Git operations and directory management.

Sources: README.md65-104 src/specify_cli/__init__.py1265-1518 templates/commands/

---

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.md13-16
2. Standardizing Workflows: Defining a clear path from natural language intent to working code via slash commands README.md65-104
3. Providing Cross-Platform Logic: Offering a dual Bash/PowerShell script layer for complex operations pyproject.toml40-41
4. Enabling Customization: Offering extension, preset, and bundle systems to adapt the workflow to specific project needs extensions/catalog.community.json5-10

Sources: README.md1-43 src/specify_cli/__init__.py14-27 AGENTS.md13-16