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
specifyCLI orchestrates project initialization src/specify_cli/__init__.py1265-1518 - Integration with 30+ AI coding agents via the
INTEGRATION_REGISTRYsrc/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:
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:
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-featureCHANGELOG.md105 - Context Synchronization: Syncs technical stacks and plans to agent memory files via
update-agent-contextCHANGELOG.md12 - Prerequisite Validation: Ensures the agent has completed previous phases before proceeding via
check-prerequisitesCHANGELOG.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:
- Abstracting AI Agents: Providing a unified
INTEGRATION_REGISTRYfor 30+ coding assistants AGENTS.md13-16 - Standardizing Workflows: Defining a clear path from natural language intent to working code via slash commands README.md65-104
- Providing Cross-Platform Logic: Offering a dual Bash/PowerShell script layer for complex operations pyproject.toml40-41
- 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
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.
On this page
- Overview
- Purpose and Scope
- What is Spec-Driven Development?
- System Architecture Overview
- System Components and Code Entities
- Core Components
- 1. The `specify` CLI
- 2. AI Agent Integration Architecture
- 3. Slash Commands and Artifact Templates
- 4. Shell Scripts Layer
- Developer Workflow Sequence
- Developer Journey Through Code Entities
- Summary
