Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/specify_cli/init.py
• spec-driven.md
• templates/plan-template.md
• templates/spec-template.md
• templates/tasks-template.md
• memory/constitution.md
• scripts/update-agent-context.sh
• templates/agent-file-template.md
• templates/commands/specify.md
• templates/commands/plan.md
• templates/commands/tasks.md
• README.md

The spec-kit project implements a methodology called Specification-Driven Development (SDD), which inverts the traditional software development lifecycle. Instead of specifications being static guides for human developers, they become executable artifacts that directly generate implementation plans and, ultimately, code. This is achieved through a combination of a command-line interface (CLI), structured templates, automation scripts, and a set of guiding principles, all designed to be orchestrated by an AI coding agent.

The core architecture revolves around a structured, multi-step refinement process that transforms a high-level feature description into a detailed, actionable implementation plan. This process is facilitated by a series of commands (/specify, /plan, /tasks) that use templates to constrain and guide an AI's output, ensuring consistency, completeness, and adherence to architectural principles. The system is designed to be technology-agnostic, focusing on the process of development rather than a specific tech stack.

Sources: spec-driven.md, README.md

Core Philosophy: Spec-Driven Development (SDD)

SDD's fundamental principle is that specifications are the source of truth, and code is a generated expression of that truth. This approach aims to eliminate the gap between intent and implementation by making the specification and its derived plans executable. The workflow is designed to be iterative, allowing for continuous refinement and even parallel exploration of different implementation strategies from a single specification.

The entire development workflow is reorganized around specifications as the central artifact. Debugging involves fixing the specification or plan, and refactoring means restructuring the specification for clarity. This process is supported by a series of commands that guide the AI agent through the development lifecycle.

Sources: spec-driven.md:7-22

The following diagram illustrates the high-level workflow of the SDD process as implemented in spec-kit.

System Components

The spec-kit architecture is composed of several key components that work together to facilitate the SDD workflow.

specify CLI

The specify CLI is a Python-based tool built with Typer that serves as the entry point for bootstrapping a new project. Its primary function is to initialize a project directory with the necessary templates and structure for a chosen AI agent.

Sources: src/specify_cli/init.py

init Command

The init command is the main utility. It handles project creation, AI assistant selection, and template downloading.

Option	Description
project_name	The name for the new project directory.
--ai	Specifies the AI assistant: claude, gemini, or copilot.
--here	Initializes the project in the current directory instead of creating a new one.
--ignore-agent-tools	Skips the check for required AI agent CLI tools (e.g., claude CLI).
--no-git	Skips the initialization of a new Git repository.

Sources: src/specify_cli/init.py:608-620

The init process involves fetching the latest release from the github/spec-kit repository, downloading the correct template .zip archive for the selected AI agent, extracting it, and optionally initializing a git repository.

This sequence diagram shows the flow of the specify init command.

Command Abstraction Layer

A key architectural pattern in spec-kit is the abstraction of commands like /specify, /plan, and /tasks. These are not hardcoded functions but are defined in Markdown files within the templates/commands/ directory. These files instruct an AI agent on how to execute a step in the SDD workflow, often by running a shell script and processing its output. This makes the system extensible and keeps the core logic transparent.

Sources: templates/commands/specify.md, templates/commands/plan.md, templates/commands/tasks.md

This diagram shows how a user's command is processed through the abstraction layer.

Template Engine

The templates/ directory is the heart of spec-kit. It contains structured Markdown templates that guide the AI agent's generation process for each major artifact: the specification, the plan, and the task list. These templates act as sophisticated, constrained prompts, ensuring that the output is consistent, complete, and follows the SDD methodology.

Template File	Purpose
spec-template.md	Defines the structure for a feature specification, focusing on user scenarios and requirements.
plan-template.md	Defines the structure for an implementation plan, including technical context and design artifacts.
tasks-template.md	Defines the structure for a list of executable tasks derived from the plan.
agent-file-template.md	A template for the AI agent's context file (e.g., CLAUDE.md).

Sources: templates/spec-template.md, templates/plan-template.md, templates/tasks-template.md, templates/agent-file-template.md

The Constitution

The memory/constitution.md file serves as the architectural "DNA" for any project created with spec-kit. It contains a set of immutable principles and rules that the AI agent must follow during the planning and implementation phases. This ensures architectural consistency, simplicity, and quality across all generated code. The plan-template.md explicitly includes a "Constitution Check" section to enforce these rules.

Key principles include:

• Library-First: Every feature must be a standalone library.
• CLI Interface: Every library must expose a CLI.
• Test-First (Non-negotiable): Tests must be written and fail before implementation code is written.
• Simplicity: Start simple and avoid over-engineering.

Sources: memory/constitution.md, spec-driven.md:255-316, templates/plan-template.md:40-69

Automation Scripts

The scripts/ directory contains shell scripts that automate key parts of the workflow. These scripts are designed to be called by the AI agent as instructed by the command templates.

A critical script is update-agent-context.sh, which incrementally updates the agent's main context file (e.g., CLAUDE.md, GEMINI.md) based on the technical decisions made in a new plan.md. This keeps the agent's knowledge of the project's tech stack, structure, and recent changes current in a token-efficient manner.

Sources: scripts/update-agent-context.sh

The SDD Workflow in Practice

The architecture is best understood by following the practical workflow enforced by the commands and templates.

Step 1: Specification (/specify)

The process begins with the /specify command. The user provides a natural language description of the feature. The AI agent, guided by templates/commands/specify.md, runs a script to create a new feature branch and a spec.md file. It then populates this file using templates/spec-template.md, translating the user's request into structured user stories, functional requirements, and acceptance criteria, while explicitly avoiding implementation details.

The execution flow within spec-template.md is as follows:

Step 2: Planning (/plan)

Once the spec.md is complete and refined, the user invokes the /plan command, providing technical stack choices. Guided by templates/plan-template.md, the agent analyzes the spec, checks for constitutional compliance, and generates a series of design artifacts.

The execution flow for the /plan command is a multi-phase process that stops before task generation.

Step 3: Task Generation (/tasks)

With a complete plan, the /tasks command is used. The agent, guided by templates/commands/tasks.md, reads the plan.md and its associated design documents. It then uses templates/tasks-template.md to generate a detailed, ordered list of executable tasks, marking independent tasks for parallel execution. This tasks.md file is the final input for the AI agent to begin implementation.

Sources: templates/tasks-template.md, templates/commands/tasks.md

Agent Context Management

To ensure the AI agent has an up-to-date, high-level understanding of the project without consuming excessive tokens, spec-kit uses a dedicated context file (e.g., CLAUDE.md). This file is managed by the scripts/update-agent-context.sh script.

After a plan.md is created for a new feature, this script is run. It parses the new plan for technology choices (language, framework, database) and incrementally updates the agent context file. This process preserves manual additions and keeps a running list of recent changes.

The following diagram illustrates this update flow.

Conclusion

The architecture of spec-kit is a well-defined system for implementing Specification-Driven Development. It leverages a CLI for project setup, a series of abstracted commands for workflow orchestration, and a powerful template-based system to guide AI code generation. By enforcing a structured process, architectural principles via a "Constitution," and continuous context management, spec-kit aims to produce high-quality, maintainable software faster by shifting the developer's focus from writing boilerplate code to defining clear, executable specifications.