Project Structure and Configuration

Relevant source files

• CHANGELOG.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• pyproject.toml
• spec-driven.md

This document describes the repository organization, configuration files, and directory conventions for the Spec Kit codebase. It covers the Python package structure, dependency management, testing setup, and where different types of artifacts are stored.

For information about setting up your local development environment, see Local Development Setup. For details on how to test changes to templates and commands, see Testing Template and Command Changes.

---

Repository Overview

The Spec Kit repository is organized around four primary concerns: the Python CLI tool, workflow templates, helper scripts, and the extension system. The structure supports both development of the CLI and packaging of templates for distribution.

Top-Level Structure

Sources: pyproject.toml1-54 CONTRIBUTING.md58-63

---

Python Package Structure

The Specify CLI is a Python package distributed via PyPI, structured according to modern Python packaging standards with src/ layout.

Package Configuration (pyproject.toml)

The pyproject.toml file defines the package metadata, dependencies, and tool configurations:

Section	Purpose	Key Values
[project]	Package metadata	name = "specify-cli", version = "0.1.0", requires-python = ">=3.11"
[project.dependencies]	Runtime dependencies	typer, rich, httpx[socks], platformdirs, readchar, pyyaml, packaging
[project.scripts]	CLI entry points	specify = "specify_cli:main"
[build-system]	Build backend	hatchling
[tool.hatch.build.targets.wheel]	Package structure	packages = ["src/specify_cli"]
[project.optional-dependencies]	Test dependencies	pytest>=7.0, pytest-cov>=4.0
[tool.pytest.ini_options]	Test configuration	Test paths, patterns, and options
[tool.coverage.*]	Coverage configuration	Source paths, report format

Sources: pyproject.toml1-54

Core Python Modules

Sources: pyproject.toml18-26 CHANGELOG.md14-28 CHANGELOG.md30-42

AGENT_CONFIG Dictionary

The AGENT_CONFIG dictionary in src/specify_cli/__init__.py serves as the single source of truth for all supported AI agents. Each entry defines agent-specific metadata:

Key Fields:

• cli_tool: Command-line executable name for validation
• agent_type: Either "cli" or "ide" for prerequisite checking
• commands_dir: Directory where agent command files are stored
• config_file: Agent context file name (e.g., CLAUDE.md, AGENTS.md)
• format: Either "markdown" or "toml" for command file format

Sources: CHANGELOG.md68-77 Diagram 4 from system overview

---

Core Directory Structure

Templates Directory

The templates/ directory contains reusable templates that are packaged into release artifacts and copied to user projects during specify init.

Command Template Structure: Each command template file contains YAML frontmatter followed by the command prompt:

Sources: CHANGELOG.md183-189 spec-driven.md73-104

Scripts Directory

The scripts/ directory contains cross-platform helper scripts that automate workflow tasks. Each script has both Bash and PowerShell implementations:

Script Pair	Purpose
create-new-feature.sh / .ps1	Determines next feature number, creates branch and spec directory
update-agent-context.sh / .ps1	Parses plan.md and updates agent context files with tech stack
check-prerequisites.sh / .ps1	Validates Git installation and agent CLI tools

Common Script Pattern:

1. Accept parameters (e.g., --short-name, --description)
2. Read existing project state (spec numbers, branches)
3. Perform Git operations (checkout, branch creation)
4. Generate or update files
5. Output JSON result for AI agent consumption

Sources: CHANGELOG.md144-161 CHANGELOG.md240-241

Memory Directory

The memory/ directory contains the constitution and architectural principles:

memory/
└── constitution.md      # The 9 Articles of Development

The constitution defines immutable architectural principles enforced throughout the workflow. It is referenced by the /speckit.plan command to validate implementation plans against articles like:

• Article I: Library-First Principle
• Article II: CLI Interface Mandate
• Article III: Test-First Imperative
• Article VII: Simplicity Gate (≤3 projects)
• Article VIII: Anti-Abstraction Gate
• Article IX: Integration-First Testing

Sources: spec-driven.md273-406 Diagram 6 from system overview

---

Extension System Structure

The extension system uses a well-defined directory layout within .specify/extensions/:

Extension Manifest Schema

Each extension contains an extension.yml manifest with:

Field	Required	Description
id	Yes	Unique identifier (e.g., "jira")
version	Yes	Semantic version (e.g., "1.0.0")
name	Yes	Display name
description	Yes	Short description
author	Yes	Author name
commands	Yes	List of command definitions with name, description, template
hooks	No	Lifecycle hooks with event, message, condition
config	No	Default configuration values
requires	No	Minimum Spec Kit version

Sources: CHANGELOG.md14-28 CHANGELOG.md78-87

Configuration Cascade (4 Layers)

The extension system resolves configuration through a four-layer cascade implemented by the ConfigManager class:

Sources: CHANGELOG.md78-87

---

Agent Integration Directories

When specify init runs, it creates agent-specific directories based on the selected agent. These directories are created in the project root and follow each agent's conventions:

Agent Directory Mapping

Agent	Commands Directory	Config File	Format
Claude Code	.claude/commands/	CLAUDE.md	Markdown
Gemini CLI	.gemini/commands/	GEMINI.md	TOML
GitHub Copilot	.github/agents/	AGENTS.md	Markdown
Cursor	.cursor/commands/	CURSOR.md	Markdown
Windsurf	.windsurf/workflows/	WINDSURF.md	Markdown
Qwen Code	.qwen/commands/	QWEN.md	TOML
Codex	.codex/commands/	AGENTS.md	Markdown
...	(14+ agents total)	...	...

Command Format Variations

Markdown Format (Most Agents):

TOML Format (Gemini, Qwen):

Sources: Diagram 4 from system overview, CHANGELOG.md68-77

---

GitHub Workflows and Release Automation

The .github/workflows/ directory contains CI/CD pipelines:

Release Package Structure

Each release package contains:

spec-kit-template-{agent}-{script}-v{version}.zip
├── .specify/
│   ├── templates/          # Command templates
│   ├── scripts/           # Helper scripts (bash or ps1)
│   └── memory/            # Constitution
├── .{agent}/              # Agent-specific directory
│   └── commands/          # Generated command files
└── {AGENT}.md            # Agent context file

Sources: Diagram 5 from system overview, CHANGELOG.md124-131

---

Testing Configuration

The testing setup is configured in pyproject.toml and uses pytest with coverage reporting.

Test Structure

tests/
├── test_extensions.py     # Extension system tests
├── test_catalog.py        # Extension catalog tests
└── fixtures/             # Test data and mocks

Pytest Configuration

Coverage Configuration

Running Tests Locally

Test Coverage: As of version 0.1.0, the extension module has 83% test coverage with 39 total tests.

Sources: pyproject.toml33-52 CHANGELOG.md115-118 CONTRIBUTING.md39-55

---

Development Dependencies

Runtime Dependencies

The package requires these runtime dependencies (pyproject.toml6-15):

Package	Purpose
typer	CLI framework with command routing and argument parsing
rich	Terminal formatting, tables, progress bars
httpx[socks]	HTTP client with SOCKS proxy support for GitHub API
platformdirs	Cross-platform directory paths for cache/config
readchar	Interactive selection UI with arrow keys
truststore	SSL certificate validation
pyyaml>=6.0	YAML parsing for extension manifests and config
packaging>=23.0	Semantic version comparison for extensions

Development Dependencies

For local development and testing (pyproject.toml27-31):

Package	Purpose
pytest>=7.0	Test framework
pytest-cov>=4.0	Coverage reporting plugin

Installation Methods

Sources: pyproject.toml6-31 CONTRIBUTING.md8-14

---

Version Management

Version information is stored in two locations:

1. Package Version: pyproject.toml3 - version = "0.1.0"
2. CHANGELOG: CHANGELOG.md10 - ## [0.1.0] - 2026-01-28

Version Update Process

When a new release is created:

1. get-next-version.sh determines the next semantic version based on Git tags
2. check-release-exists.sh verifies the version doesn't already exist
3. update-version.sh updates pyproject.toml3
4. generate-release-notes.sh compiles entries from CHANGELOG.md
5. create-github-release.sh publishes to GitHub Releases with all 32 packages

The project follows Semantic Versioning 2.0.0:

• MAJOR: Breaking changes to CLI commands or workflow
• MINOR: New features (e.g., extension system in 0.1.0)
• PATCH: Bug fixes and minor improvements

Sources: CHANGELOG.md1-9 Diagram 5 from system overview

---

Configuration File Reference

pyproject.toml

The central configuration file defining the Python package, dependencies, and tool configurations. See Python Package Structure section above for detailed breakdown.

Location: pyproject.toml (repository root)

Sources: pyproject.toml1-54

.gitignore Patterns

Key patterns for ignored files:

# Python
__pycache__/
*.pyc
.pytest_cache/
.coverage
htmlcov/

# Build artifacts
dist/
build/
*.egg-info/

# Extension local config
.specify/extensions/*/local-config.yml

# Agent directories (recommended to add)
.claude/
.gemini/
.cursor/
.github/agents/

Note: Users are warned to add agent directories to .gitignore to prevent accidental credential leakage, as some agents may store auth tokens in these directories.

Sources: CHANGELOG.md221-227

devcontainer.json

Provides a pre-configured development environment with Docker:

Location: .devcontainer/devcontainer.json

Includes:

• Python 3.11+
• uv package manager
• Git
• VS Code extensions for Python development

Usage:

1. Open repository in VS Code
2. Select "Dev Containers: Open Folder in Container..."
3. Environment automatically provisions with all tools

Sources: CONTRIBUTING.md16-31

---

Directory Conventions Summary

Key Conventions:

1. Source code: Lives in src/specify_cli/ with proper package structure
2. Templates: Stored in templates/, copied to .specify/templates/ in user projects
3. Scripts: Paired Bash/PowerShell in scripts/, copied to .specify/scripts/
4. Constitution: Single file in memory/, copied to .specify/memory/
5. Extensions: Installed to .specify/extensions/{extension-id}/
6. Agent files: Created in agent-specific directories (.claude/, .github/agents/, etc.)
7. Feature specs: Created in specs/{feature-number}-{feature-name}/

Sources: All sections above, Diagram 1 from system overview