Customizing Templates
Relevant source files
The following files were used as context for generating this wiki page:Templates are the core mechanism for enforcing structure, quality, and consistency in the Spec-Driven Development (SDD) workflow. They act as sophisticated prompts that constrain and guide Large Language Models (LLMs) to produce high-quality, executable specifications and plans. Rather than being static documents, templates in spec-kit contain executable logic, validation checklists, and structural rules that transform user input into standardized project artifacts.
This system ensures that every feature specification, implementation plan, and task list adheres to the project's architectural principles as defined in the constitution. The templates are designed to be self-contained and guide the AI through a series of steps, including analysis, generation, and self-review, effectively turning the LLM into a disciplined specification engineer.
Sources: spec-driven.md:300-307, templates/spec-template.md:1-8
Core Templates and Workflow
The SDD process is orchestrated by a series of commands (/specify, /plan, /tasks), each of which utilizes a corresponding core template to generate its output.
Sources: spec-driven.md:195-217
This diagram illustrates how user commands trigger processes that use specific templates to generate feature artifacts.
spec-template.md
This template is used by the /specify command to convert a high-level user description into a formal feature specification. Its primary goal is to define the "what" and "why" of a feature, explicitly avoiding implementation details.
Key Sections:
| Section | Purpose |
|---|---|
| Execution Flow | Defines the automated steps the LLM must follow to process the user input and generate the spec. |
| Quick Guidelines | Instructs the LLM to focus on user needs and avoid technical details, and to mark ambiguities. |
| User Scenarios & Testing | Captures the primary user story, acceptance scenarios (Given/When/Then), and edge cases. |
| Requirements | Lists testable functional requirements (e.g., FR-001). |
| Key Entities | Defines data entities involved in the feature without implementation details. |
| Review & Acceptance Checklist | A gate for the LLM to self-validate the generated spec against quality criteria. |
Sources: templates/spec-template.md:1-50
The execution flow within spec-template.md ensures a structured approach to spec generation.
Sources: templates/spec-template.md:8-20
plan-template.md
Used by the /plan command, this template translates a feature specification (spec.md) into a detailed technical implementation plan. It defines the "how" by selecting technologies, defining architecture, and creating design artifacts.
Execution Phases:
| Phase | Output | Description |
|---|---|---|
| Phase 0: Research | research.md | Resolves all NEEDS CLARIFICATION from the spec and researches technology choices. |
| Phase 1: Design | data-model.md, contracts/, quickstart.md | Creates the data model, API contracts, and validation scenarios. Also updates the agent-specific context file. |
| Phase 2: Task Planning | (Describes approach only) | Outlines the strategy for how the /tasks command will generate tasks.md. The /plan command does not execute this. |
Sources: templates/plan-template.md:40-42, templates/plan-template.md:131-173
A critical feature of this template is the Constitution Check, which acts as a gate to ensure the plan adheres to the project's architectural principles (e.g., simplicity, testability).
Sources: templates/plan-template.md:52-55
tasks-template.md
This template is the foundation for the /tasks command. It analyzes the design documents created during the planning phase (plan.md, data-model.md, etc.) and breaks them down into a list of small, ordered, and executable tasks.
Key Features:
- TDD Enforcement: Generates test creation tasks before implementation tasks.
- Parallelism: Marks independent tasks with
[P]to allow for parallel execution by an AI agent. - Dependency Management: Orders tasks sequentially based on dependencies (e.g., models before services).
- Validation Checklist: Ensures all contracts and entities from the plan have corresponding tasks.
Sources: templates/tasks-template.md:29-41, templates/tasks-template.md:88-95
The template defines a clear task generation strategy based on the available design documents.
Agent-Specific Templates
The repository uses agent-file-template.md to create and maintain context files for different AI coding agents (e.g., CLAUDE.md, GEMINI.md, .github/copilot-instructions.md). These files provide the agent with high-level project guidelines.
Sources: templates/agent-file-template.md, scripts/update-agent-context.sh:3-5
The update-agent-context.sh script automates the process of keeping these files current. When a new feature plan is created, this script is run to incrementally add new technologies, project structure details, and recent changes to the agent context file.
This sequence diagram shows how the script updates an agent file after a new plan is created.
Maintaining and Customizing Templates
Templates are not static; they must evolve with the project's core principles. The memory/constitution_update_checklist.md file provides a strict process for updating templates whenever the main constitution.md is amended.
This ensures that changes to architectural rules are consistently propagated across all templates, maintaining alignment between principles and generated artifacts.
Template Update Checklist:
| When to Update | Files to Check/Update |
|---|---|
| Any constitution change | plan-template.md, spec-template.md, tasks-template.md, command definitions (/commands/*.md) |
| Article I (Library-First) | Emphasize library creation, add llms.txt doc requirements. |
| Article III (Test-First) | Update test order, emphasize TDD, add test approval gates. |
| Article VII (Simplicity) | Update project count limits, add pattern prohibition examples. |
Sources: memory/constitution_update_checklist.md:5-20
To customize a template, a developer should:
- Identify the desired change and its impact on the SDD workflow.
- Modify the relevant
.mdfile in the/templatesdirectory. - If the change reflects a new architectural principle, first amend
memory/constitution.md. - Follow the
constitution_update_checklist.mdto ensure all dependent templates are updated consistently. - Test the changes by running the full
/specify->/plan->/tasksworkflow to verify the LLM correctly interprets the new template structure.
Sources: CONTRIBUTING.md:46-51, memory/constitution_update_checklist.md:36-43
Summary
Templates in spec-kit are the primary tool for achieving high-quality, consistent, and constitutionally-compliant software generation with AI. They provide the structure that guides LLMs through the Spec-Driven Development process, from initial idea to an executable task list. Customizing these templates allows a project to tailor the AI's behavior to its specific architectural patterns, technology stacks, and quality standards. The process for modification is itself structured, ensuring that the templates remain internally consistent and aligned with the project's core principles.
Sources: spec-driven.md:188-193, spec-driven.md:300-307