Creating New Automation Scripts

Relevant source files

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

• scripts/create-new-feature.sh
• scripts/check-task-prerequisites.sh
• scripts/update-agent-context.sh
• templates/commands/specify.md
• templates/commands/tasks.md
• src/specify_cli/init.py
• spec-driven.md

Automation in the spec-kit project is a multi-layered system designed to streamline the Spec-Driven Development (SDD) workflow. It combines a Python-based CLI, declarative command definitions in Markdown, and a suite of shell scripts to handle repository operations. This architecture allows AI agents to execute complex, multi-step tasks like creating feature branches, generating plans, and updating project context files in a structured and repeatable manner.

The core idea is to provide high-level commands (e.g., /specify, /plan, /tasks) that an AI agent can invoke. These commands are defined in simple Markdown files that instruct the agent on which shell scripts to run and how to process their outputs. The shell scripts perform the "heavy lifting" of file system manipulation and Git operations, providing a stable interface for the AI.

Architecture Overview

The automation framework consists of three primary components that work in concert:

1. specify CLI (src/specify_cli/__init__.py): The main entry point for project initialization. It handles user interaction, downloads templates, and sets up the initial project structure.
2. Command Definitions (templates/commands/*.md): These are Markdown files that define the steps an AI agent should take when a command like /specify is invoked. They act as a "prompt-within-a-prompt" to guide the LLM.
3. Shell Scripts (scripts/*.sh): A collection of Bash scripts that perform specific, atomic operations on the repository, such as creating branches, copying templates, or parsing files. They are designed to be called by the AI agent as instructed by the command definitions.

The following diagram illustrates the interaction between these components when a user initiates a command via an AI agent.

The specify CLI

The specify CLI, implemented in src/specify_cli/__init__.py, is the primary tool for bootstrapping a new spec-kit project. It is built using Python with the typer library for the command-line interface and rich for enhanced console output.

Key Responsibilities

• Project Initialization (init command): Creates a new project directory (or initializes in the current one), prompts the user to select an AI assistant, and downloads the appropriate template from the project's GitHub releases.
• Prerequisite Checks (check command): Verifies that necessary tools like git and optional AI agent CLIs (claude, gemini) are installed.
• Git Integration: Automatically initializes a new Git repository in the created project unless disabled with the --no-git flag.

The init command is the most significant part of the CLI. Its parameters are detailed below.

Parameter	Type	Description
project_name	string	The name for the new project directory. Not used if --here is specified.
--ai	string	The AI assistant to use (claude, gemini, or copilot). If not provided, the user is prompted to choose.
--ignore-agent-tools	bool	Skips the check for installed AI agent tools.
--no-git	bool	Skips the initialization of a Git repository.
--here	bool	Initializes the project in the current directory instead of creating a new one.

Sources: src/specify_cli/init.py:575-598

The CLI uses a StepTracker class to provide a clean, tree-like progress display during initialization, showing steps like fetching the release, downloading, and extracting the template.

Sources: src/specify_cli/init.py:59-133

Command Definitions

Command definitions are Markdown files located in templates/commands/ that provide explicit, step-by-step instructions for an AI agent. Each file corresponds to a high-level command (e.g., /specify, /tasks).

Structure

A command definition file has two parts:

1. YAML Frontmatter: Contains the name of the command and a description.
2. Instructional Body: A numbered list of actions the AI agent must perform. This typically involves running a shell script and parsing its output.

For example, the specify.md command instructs the agent to run scripts/create-new-feature.sh and use its JSON output to understand the newly created branch and spec file path.

---
name: specify
description: "Start a new feature by creating a specification and feature branch. This is the first step in the Spec-Driven Development lifecycle."
---

Start a new feature by creating a specification and feature branch.

This is the first step in the Spec-Driven Development lifecycle.

Given the feature description provided as an argument, do this:

1. Run the script `scripts/create-new-feature.sh --json "{ARGS}"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
2. Load `templates/spec-template.md` to understand required sections.
3. Write the specification to SPEC_FILE using the template structure...
4. Report completion...

Sources: templates/commands/specify.md:1-17

This structured approach ensures that the AI agent's behavior is predictable and constrained, forcing it to use the provided automation scripts as the source of truth for repository operations.

Shell Scripts (/scripts)

The /scripts directory contains the operational logic of the automation framework. These are Bash scripts designed to be robust and provide clear output, often in JSON format for easy parsing by the AI agent.

create-new-feature.sh

This script automates the creation of a new feature. It is invoked by the /specify command.

Logic Flow:

1. Parses a feature description from the command-line arguments.
2. Scans the specs/ directory to find the highest existing feature number.
3. Calculates the next feature number (e.g., 001, 002).
4. Generates a sanitized, kebab-case branch name from the feature description (e.g., 003-real-time-chat).
5. Creates and checks out the new Git branch.
6. Creates a corresponding directory inside specs/.
7. Copies the spec-template.md into the new feature directory.
8. Outputs the new branch name and spec file path, either in a legacy key-value format or as a JSON object if the --json flag is used.

The following diagram shows the script's execution flow.

update-agent-context.sh

This script is responsible for keeping the AI agent's context files (e.g., CLAUDE.md, GEMINI.md) up-to-date. It incrementally adds information about new technologies introduced by a feature.

Key Functions:

• It is triggered after a /plan command is successfully executed.
• It reads the plan.md for the current feature branch.
• It extracts technical details like Language/Version, Primary Dependencies, and Storage.
• It parses the existing agent context file (e.g., CLAUDE.md).
• It adds the new technologies to the "Active Technologies" section if they are not already present.
• It updates the "Recent Changes" section with a summary of the new feature.
• It preserves any manual additions made to the context file.

This script is crucial for creating a "living" context that evolves with the project, ensuring the AI agent is always aware of the current tech stack.

Sources: scripts/update-agent-context.sh:1-196

check-task-prerequisites.sh

This script acts as a guard before the /tasks command can be executed. Its purpose is to verify that all necessary design documents have been created by the /plan command.

Execution Steps:

1. Identifies the current feature branch and paths.
2. Checks for the existence of the feature directory (specs/[branch-name]).
3. Critically, it verifies that plan.md exists. If not, it exits with an error, instructing the user to run /plan first.
4. If plan.md exists, it checks for optional documents like research.md, data-model.md, and files in the contracts/ directory.
5. If the --json flag is provided, it outputs a JSON object containing the feature directory path and a list of available design documents.

This script ensures the SDD workflow is followed in the correct order (/specify -> /plan -> /tasks).

Sources: scripts/check-task-prerequisites.sh, templates/commands/tasks.md:9-19

Summary

The automation script framework in spec-kit is a well-defined system that separates concerns effectively. The specify CLI provides a user-friendly entry point for project setup. Declarative command definitions guide the AI agent's behavior, while robust shell scripts execute the underlying repository and file system operations. This layered architecture is fundamental to the Spec-Driven Development methodology, enabling rapid, consistent, and automated software construction from high-level specifications.