AI Agent Integration
Relevant source files
The following files were used as context for generating this wiki page:The spec-kit project is designed to work with various AI coding agents to facilitate Spec-Driven Development (SDD). The integration allows developers to use their preferred AI assistant to execute the core SDD workflow commands (/specify, /plan, /tasks). The system is bootstrapped using the specify CLI, which prepares the project environment with the necessary templates and scripts tailored to the chosen AI agent.
This integration is central to the project's philosophy of using AI to translate high-level specifications into working code. The specify tool ensures that the AI agent has the correct context and commands available to follow the structured SDD process, from creating a feature specification to generating an executable task list.
Sources: README.md:1-11, spec-driven.md:1-18
Supported AI Agents
spec-kit provides explicit support for several major AI coding agents. The specify init command allows users to select one of these agents, which then configures the project with the appropriate templates and command structures.
The supported agents are defined in the specify CLI:
| Agent Key | Full Name | Required Tool |
|---|---|---|
copilot | GitHub Copilot | N/A (IDE integration) |
claude | Claude Code | claude CLI |
gemini | Gemini CLI | gemini CLI |
Sources: src/specify_cli/init.py:52-56, README.md:88-89
During initialization, unless the --ignore-agent-tools flag is used, the CLI will check if the required tool for the selected agent is installed and available in the system's PATH.
Sources: src/specify_cli/init.py:603-622
Project Initialization and Agent Selection
The primary entry point for integrating an AI agent is the specify init command. This command bootstraps a new project, and a key part of this process is selecting and configuring the environment for a specific AI agent.
Initialization Flow
The user can specify an agent directly using the --ai flag (e.g., specify init my-project --ai claude) or select one interactively via an arrow-key menu if the flag is omitted.
This diagram illustrates the agent selection and project setup logic within the specify init command.
Sources: src/specify_cli/init.py:570-698
Key CLI Options
The specify init command includes several options relevant to AI agent integration:
| Option | Description |
|---|---|
--ai <assistant> | Specifies the AI assistant to use (claude, gemini, or copilot). |
--ignore-agent-tools | Skips the check for required AI agent command-line tools. |
--here | Initializes the project in the current directory, merging template files. |
--no-git | Skips the automatic initialization of a Git repository. |
Sources: src/specify_cli/init.py:571-577
Agent-Specific Context Files
To provide the AI agent with relevant project information, spec-kit generates and maintains agent-specific context files in the root of the repository. These files are updated throughout the development lifecycle to reflect the current state of the project's technology stack, structure, and recent changes.
The following files are managed:
| Agent | File Path |
|---|---|
| Claude Code | CLAUDE.md |
| Gemini CLI | GEMINI.md |
| GitHub Copilot | .github/copilot-instructions.md |
Sources: scripts/update-agent-context.sh:11-13, templates/plan-template.md:28-29
These files are created from a common template, templates/agent-file-template.md, which defines the structure for the context file.
# [PROJECT NAME] Development Guidelines
Auto-generated from all feature plans. Last updated: [DATE]
## Active Technologies
[EXTRACTED FROM ALL PLAN.MD FILES]
## Project Structure
[ACTUAL STRUCTURE FROM PLANS]
<!-- ... -->
Sources: templates/agent-file-template.md:1-12
Context Update Process
The context files are updated by the scripts/update-agent-context.sh script, which is typically called during the /plan command execution. The script parses the plan.md for the current feature to extract technical details and incrementally updates the agent's context file.
This sequence diagram shows how the script updates an agent's context file.
The script extracts the following information from plan.md:
Language/VersionPrimary DependenciesTestingStorageProject Type
Sources: scripts/update-agent-context.sh:23-28, templates/plan-template.md:100-101
Agent Commands (/specify, /plan, /tasks)
The core of the AI agent integration is the set of custom commands that guide the agent through the SDD workflow. When a project is initialized, it includes definitions for /specify, /plan, and /tasks.
These commands are not built into the AI agents themselves but are defined in markdown files (e.g., templates/commands/plan.md) that instruct the agent on how to behave when the user types the command. The agent reads these instructions and executes the described steps, which often involve running shell scripts and processing template files.
Workflow Overview
- /specify: The user provides a high-level feature description. The AI agent uses this to populate
spec-template.md, creating a newspec.mdfile in a new feature branch. - /plan: The user provides technical stack details. The agent uses this input to execute the logic in
plan-template.md, which results in the creation of several design artifacts likeresearch.md,data-model.md, and API contracts. This step also updates the agent's context file. - /tasks: The agent analyzes the generated plan and design documents. It uses
tasks-template.mdto break down the implementation into a detailed, ordered list of executable tasks, creating atasks.mdfile.
This structured interaction ensures that the AI's creative generation capabilities are channeled into a repeatable and predictable development process.
Sources: spec-driven.md:126-157, README.md:29-47