Template System
Relevant source files
The following files were used as context for generating this wiki page:The Template System is a core component of the Spec-Driven Development (SDD) methodology within spec-kit. It provides a set of structured Markdown files that serve as blueprints for generating key development artifacts. These templates enforce consistency, guide AI agent behavior, and automate the creation of specifications, implementation plans, task lists, and agent context files. By constraining the output of Large Language Models (LLMs), the templates ensure that all generated documents adhere to the project's architectural principles and quality standards.
The system is designed to transform high-level user descriptions into a series of increasingly detailed and executable documents. This process is orchestrated by a series of commands (/specify, /plan, /tasks) that use the templates to manage the development lifecycle from initial idea to a concrete implementation plan. The templates act as a "lingua franca" that standardizes the communication between developers, stakeholders, and AI agents.
Sources: spec-driven.md:213-221, templates/spec-template.md:15-17, templates/plan-template.md:4-18
Template-Driven Workflow
The templates are used sequentially in the SDD workflow, with each step's output serving as the input for the next. This creates a traceable and structured path from a feature idea to an executable set of tasks.
The diagram below illustrates the flow of control and data as a feature progresses through the SDD lifecycle, driven by commands that invoke the corresponding templates.
Core Templates
The system is composed of four primary templates, each serving a distinct purpose in the development lifecycle.
| Template File | Purpose | Triggering Command | Key Outputs |
|---|---|---|---|
spec-template.md | Defines the structure for a feature specification, focusing on user needs and requirements ("what" and "why"). | /specify | spec.md |
plan-template.md | Guides the creation of a technical implementation plan from a specification. | /plan | plan.md, research.md, data-model.md, contracts/ |
tasks-template.md | Structures the breakdown of an implementation plan into a list of executable development tasks. | /tasks | tasks.md |
agent-file-template.md | Creates or updates a context file for an AI coding agent, summarizing the project's state. | /plan (via update-agent-context.sh) | CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md |
Sources: templates/spec-template.md, templates/plan-template.md, templates/tasks-template.md, templates/agent-file-template.md
Feature Specification Template (spec-template.md)
This template is the starting point for any new feature. It is used by the /specify command to translate a user's natural language description into a formal specification.
Key Principles:
- Focus on WHAT, not HOW: The template explicitly forbids implementation details like languages, frameworks, or APIs.
- Clarity and Unambiguity: It forces the identification of unclear aspects using
[NEEDS CLARIFICATION: specific question]markers to prevent the AI from making incorrect assumptions. - Testability: It requires that all functional requirements are testable and that user scenarios include acceptance criteria.
Structure:
- User Scenarios & Testing: Describes the main user story, acceptance scenarios (Given/When/Then), and edge cases.
- Requirements: Lists functional requirements (e.g., "System MUST...") and identifies key data entities.
- Review & Acceptance Checklist: An automated gate to ensure content quality and completeness before the spec can be used for planning.
The internal execution flow of this template is designed to parse a user description and systematically build the structured specification.
Implementation Plan Template (plan-template.md)
Used by the /plan command, this template takes a completed spec.md and a user's technical preferences to generate a detailed implementation plan. It translates the "what" from the spec into the "how" of implementation.
Key Principles:
- Constitutional Compliance: The plan must pass a "Constitution Check" against the project's core principles (e.g., simplicity, testability) defined in
memory/constitution.md. - Phased Generation: The process is broken into distinct phases (Research, Design) to ensure a logical progression from high-level architecture to detailed contracts.
- Structured Artifacts: It orchestrates the creation of multiple design documents, including
research.md,data-model.md, and API contracts.
Structure:
- Technical Context: Captures all technology choices, versions, and constraints. Unresolved items are marked
NEEDS CLARIFICATION. - Constitution Check: A checklist to validate the plan against architectural rules.
- Project Structure: Defines the repository's directory layout based on the project type (e.g., web, mobile, single project).
- Phases (0-2):
- Phase 0 (Research): Identifies and resolves unknowns.
- Phase 1 (Design): Generates data models and API contracts.
- Phase 2 (Task Planning Approach): Describes the strategy for the
/taskscommand.
The diagram below shows the execution flow defined within the plan-template.md.
Tasks Template (tasks-template.md)
This template is invoked by the /tasks command to break down the plan.md and its associated design documents into a numbered, sequential list of executable tasks.
Key Principles:
- Test-Driven Development (TDD): The template enforces a "Tests First" approach, ensuring that test creation tasks appear before their corresponding implementation tasks.
- Parallelism: It identifies independent tasks (those modifying different files) and marks them with
[P]to enable parallel execution by AI agents. - Dependency Management: Tasks are ordered based on dependencies (e.g., models before services, services before endpoints).
Structure:
- Phased Task List: Tasks are grouped into logical phases: Setup, Tests First, Core Implementation, Integration, and Polish.
- Format: Each task has a unique ID, an optional
[P]marker, and a clear description including file paths. - Dependencies & Parallel Examples: Provides explicit guidance on task ordering and how to group parallel tasks.
- Validation Checklist: A final gate to ensure all contracts and entities have corresponding tasks and that TDD principles are followed.
Sources: templates/tasks-template.md:19-74
Agent File Template (agent-file-template.md)
This template is used by the update-agent-context.sh script (typically run during the /plan phase) to generate a high-level context file for an AI agent. This file provides the agent with a concise summary of the project's current state, helping it make better decisions during code generation.
Structure:
- Active Technologies: A list of languages, frameworks, and databases in use, extracted from all
plan.mdfiles. - Project Structure: A high-level view of the repository's directory layout.
- Commands: Common commands for testing and linting.
- Code Style: Pointers to language-specific conventions.
- Recent Changes: A list of the last 3 features and what they added.
- Manual Additions: A designated section for developers to add persistent, custom instructions for the agent that are preserved across updates.
The update-agent-context.sh script reads the new plan.md and incrementally updates the agent file, adding new technologies and recent changes without overwriting manual additions.
Sources: templates/agent-file-template.md, scripts/update-agent-context.sh:1-10, 31-100
Automation and Scripting
The templates are not used manually; they are processed by scripts and command definitions that automate the SDD workflow.
scripts/create-new-feature.sh: When the/specifycommand is run, this script is executed. It creates a new feature branch and directory, then copiestemplates/spec-template.mdto create the initialspec.mdfile for the feature.templates/commands/*.md: These files define the behavior for the/specify,/plan, and/taskscommands. They explicitly reference which template to load and how to process it. For example,templates/commands/plan.mdinstructs the agent to load and execute theplan-template.md.scripts/update-agent-context.sh: This script is responsible for maintaining the agent context file (e.g.,CLAUDE.md). It can be invoked with an agent type (claude,gemini,copilot) and usestemplates/agent-file-template.mdas the basis for creating or updating the context file.
Sources: scripts/create-new-feature.sh:60-66, templates/commands/specify.md:10-12, templates/commands/plan.md:16-18, scripts/update-agent-context.sh:2-5, 41-47
Conclusion
The Template System is the engine of the Spec-Driven Development process in spec-kit. By providing a rigid yet flexible structure for key development artifacts, it ensures that every feature is specified, planned, and tasked in a consistent and high-quality manner. The templates are a powerful tool for guiding LLMs, transforming them from simple code generators into disciplined engineering partners that adhere to the project's architectural constitution. This structured approach is fundamental to the project's goal of building high-quality software faster by focusing on executable specifications.
Sources: spec-driven.md:213-221, 276-284