This document provides a high-level introduction to the Spec Kit codebase—a toolkit that enables Spec-Driven Development (SDD) with AI coding agents. Spec Kit transforms natural language requirements into working software through a structured multi-phase workflow: constitutional governance → specification → planning → task breakdown → implementation.
This page covers the system architecture, core components, and how they interact. For detailed information about specific subsystems:
specify CLI tool internals: see Core CLI ToolSpec Kit operates as a three-tier system: a developer interface layer (CLI + AI agents), a core specification-driven development engine (templates, scripts, constitution), and supporting infrastructure (extensions, distribution).
Sources: src/specify_cli/__init__.py126-229 README.md1-655
| Component | Location | Purpose |
|---|---|---|
specify CLI | src/specify_cli/__init__.py | Bootstrap tool for project initialization, tool checking, extension management |
| AGENT_CONFIG | src/specify_cli/__init__.py126-229 | Single source of truth for 16+ AI agent metadata (names, directories, CLI requirements) |
| Templates | .specify/templates/ | Structured formats for spec.md, plan.md, tasks.md, constitution.md |
| Scripts | .specify/scripts/ | Bash/PowerShell helpers for feature creation, context updates, Git operations |
| Constitution | .specify/memory/constitution.md | Immutable architectural principles that govern all development decisions |
| Specifications | .specify/specs/NNN-feature-name/ | Per-feature directories containing spec, plan, tasks, contracts, data models |
| Agent Commands | .{agent}/commands/ | Agent-specific slash commands (/speckit.*) registered during init |
| Extensions | .specify/extensions/ | Modular add-ons for custom commands and workflow hooks |
Sources: src/specify_cli/__init__.py126-229 src/specify_cli/__init__.py436-442 README.md43-135
When specify init executes, it creates a standardized directory structure that serves as the foundation for spec-driven development.
Sources: src/specify_cli/__init__.py751-898 src/specify_cli/__init__.py945-979 README.md440-459
Each AI agent requires commands in a specific directory structure. The AGENT_CONFIG dictionary maps agent keys to their folder conventions:
| Agent Key | Folder | Format | CLI Required |
|---|---|---|---|
copilot | .github/agents/ | Markdown | No (IDE-based) |
claude | .claude/commands/ | Markdown | Yes |
gemini | .gemini/commands/ | TOML | Yes |
cursor-agent | .cursor/commands/ | Markdown | No (IDE-based) |
windsurf | .windsurf/workflows/ | Markdown | No (IDE-based) |
qwen | .qwen/commands/ | TOML | Yes |
codex | .codex/commands/ | Markdown | Yes |
qoder | .qoder/commands/ | Markdown | Yes |
amp | .agents/commands/ | Markdown | Yes |
shai | .shai/commands/ | Markdown | Yes |
bob | .bob/commands/ | Markdown | No (IDE-based) |
Sources: src/specify_cli/__init__.py126-229
The core workflow follows a linear progression of phases, each producing artifacts that feed into the next phase. AI agents orchestrate this workflow through slash commands.
Sources: README.md93-135 README.md246-276
The /speckit.* commands available in AI agents map to specific templates and scripts:
| Slash Command | Primary Template | Helper Scripts | Output Artifacts |
|---|---|---|---|
/speckit.constitution | constitution-template.md | None | memory/constitution.md |
/speckit.specify | spec-template.md | create-new-feature.sh | specs/NNN-name/spec.md |
/speckit.clarify | (inline prompts) | None | Updates to spec.md |
/speckit.plan | plan-template.md | update-agent-context.sh | plan.md, data-model.md, contracts/ |
/speckit.tasks | tasks-template.md | None | tasks.md |
/speckit.implement | None | Executes CLI commands | Generated code files |
/speckit.analyze | (analysis prompts) | None | Consistency report |
/speckit.checklist | (checklist prompts) | None | Quality checklist |
Sources: README.md246-276
The specify CLI tool provides initialization, validation, and extension management. It does not execute the development workflow—that responsibility belongs to AI agents.
Sources: src/specify_cli/__init__.py436-442 src/specify_cli/__init__.py980-1280 src/specify_cli/__init__.py1282-1322 src/specify_cli/__init__.py1324-1401 src/specify_cli/__init__.py1405-2035
| Function | Location | Purpose |
|---|---|---|
init() | src/specify_cli/__init__.py980-1280 | Project initialization with agent selection, template download, Git setup |
download_template_from_github() | src/specify_cli/__init__.py637-749 | Fetch latest release from GitHub API, handle rate limiting |
download_and_extract_template() | src/specify_cli/__init__.py751-898 | Extract ZIP, flatten nested directories, merge into existing projects |
check_tool() | src/specify_cli/__init__.py484-513 | Validate tool presence in PATH, special handling for Claude CLI |
select_with_arrows() | src/specify_cli/__init__.py350-423 | Interactive arrow-key selection using readchar library |
StepTracker | src/specify_cli/__init__.py245-328 | Progress tracking with hierarchical step rendering |
AGENT_CONFIG | src/specify_cli/__init__.py126-229 | Agent metadata dictionary (name, folder, install_url, requires_cli) |
Sources: src/specify_cli/__init__.py980-1280 src/specify_cli/__init__.py637-749 src/specify_cli/__init__.py751-898 src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py350-423 src/specify_cli/__init__.py245-328 src/specify_cli/__init__.py126-229
Spec Kit supports 16+ AI agents through an adapter pattern that normalizes heterogeneous conventions (Markdown vs TOML formats, different directory structures, varying placeholder patterns).
The AGENT_CONFIG dictionary serves as the single source of truth for agent metadata:
Sources: src/specify_cli/__init__.py126-229
Sources: src/specify_cli/__init__.py126-229
The memory/constitution.md file establishes immutable architectural principles that constrain AI-generated implementations. Templates enforce these principles through structured prompts.
| Article | Principle | Enforcement Mechanism |
|---|---|---|
| Article I | Library-First Principle | Template prompts require justification for new abstractions |
| Article II | CLI Interface Mandate | Templates enforce separation of library and CLI concerns |
| Article III | Test-First Imperative | Task ordering places test creation before implementation |
| Article VII | Simplicity Gate (≤3 projects) | Planning phase includes complexity tracking section |
| Article VIII | Anti-Abstraction Gate | Templates discourage custom frameworks over direct library use |
| Article IX | Integration-First Testing | Contracts defined before tasks, real dependencies over mocks |
Sources: README.md277-292
Sources: README.md277-292
Extensions provide modularity by allowing custom commands and workflow hooks without modifying the core codebase.
Sources: src/specify_cli/__init__.py1405-2035
| Command | Function | Location |
|---|---|---|
specify extension list | extension_list() | src/specify_cli/__init__.py1434-1475 |
specify extension add | extension_add() | src/specify_cli/__init__.py1477-1596 |
specify extension remove | extension_remove() | src/specify_cli/__init__.py1598-1659 |
specify extension search | extension_search() | src/specify_cli/__init__.py1661-1730 |
specify extension info | extension_info() | src/specify_cli/__init__.py1732-1838 |
specify extension update | extension_update() | src/specify_cli/__init__.py1840-1945 |
specify extension enable | extension_enable() | src/specify_cli/__init__.py1947-1989 |
specify extension disable | extension_disable() | src/specify_cli/__init__.py1991-2035 |
Sources: src/specify_cli/__init__.py1405-2035
Spec Kit uses an automated GitHub Actions pipeline to generate 32 release packages (16 agents × 2 script types: bash/PowerShell).
Sources: src/specify_cli/__init__.py637-749 README.md12
Each of the 32 release packages contains:
spec-kit-template-{agent}-{script}-vX.Y.Z.zip
├── .specify/
│ ├── memory/
│ │ └── constitution.md
│ ├── scripts/
│ │ ├── create-new-feature.{sh|ps1}
│ │ ├── update-agent-context.{sh|ps1}
│ │ └── check-prerequisites.{sh|ps1}
│ └── templates/
│ ├── spec-template.md
│ ├── plan-template.md
│ ├── tasks-template.md
│ └── constitution-template.md
└── .{agent}/
└── commands/
├── constitution.md
├── specify.md
├── plan.md
├── tasks.md
└── implement.md
Sources: src/specify_cli/__init__.py751-898
The specify CLI handles one-time project initialization and extension management. AI agents execute the actual development workflow through /speckit.* commands. This separation keeps the CLI lightweight while leveraging agent capabilities for complex, context-aware operations.
Rationale: Bootstrap complexity (template downloads, Git setup, tool validation) belongs in a Python CLI. Development workflows (specification writing, code generation) belong in AI agents that understand natural language and codebase context.
Sources: README.md43-70 src/specify_cli/__init__.py980-1280
Specifications follow structured templates rather than free-form documents. Templates include section headers, completion checklists, and placeholder patterns that guide AI agents toward consistent output.
Rationale: Structured templates reduce variance in AI-generated specifications, making them more parseable by downstream phases. Checklists serve as quality gates.
Sources: README.md407-432
The workflow enforces strict ordering: constitution → specify → plan → tasks → implement. Each phase produces artifacts that serve as inputs to the next phase.
Rationale: Linear progression prevents premature optimization and ensures specifications are validated before implementation planning begins. Constitutional gates during planning catch architectural violations early.
Sources: README.md93-135
The AGENT_CONFIG dictionary maps agent identifiers to their conventions (directory structure, file format, CLI requirements). Command templates generate agent-specific files at initialization.
Rationale: Centralizing agent metadata in a single dictionary prevents scattered configuration. The adapter pattern allows supporting new agents by adding one entry to AGENT_CONFIG without touching workflow logic.
Sources: src/specify_cli/__init__.py126-229
The release pipeline generates 32 packages (16 agents × bash/PowerShell) rather than a single universal package. Each variant contains only the files needed for that agent and script type.
Rationale: Agent-specific packages reduce project clutter—users only get commands for their chosen agent. Script type variants enable cross-platform support (bash for Unix, PowerShell for Windows/cross-platform).
Sources: src/specify_cli/__init__.py637-749
Refresh this wiki