Automation Scripts

Relevant source files

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

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

The automation scripts in the scripts/ directory are a collection of shell scripts that form the backbone of the Spec-Driven Development (SDD) workflow. They are designed to be executed by an AI coding agent in response to specific commands like /specify, /plan, and /tasks. These scripts handle repository operations, file management, and context updates, ensuring a consistent and automated process for feature development from specification to task generation.

The overall workflow is initiated by the specify init command, which sets up the project environment. Subsequent development cycles rely on the agent invoking these scripts to manage feature branches, create specification documents, and update contextual information for the AI.

Core Components

Common Utilities (common.sh)

This script provides a library of shared bash functions used by other automation scripts to ensure consistent behavior for common tasks like path resolution and repository checks.

Sources: scripts/common.sh

Function	Description
get_repo_root()	Returns the absolute path to the git repository root.
get_current_branch()	Returns the name of the current git branch.
check_feature_branch()	Checks if the current branch name follows the feature branch format (e.g., 001-feature-name).
get_feature_paths()	Sets environment variables for all standard paths related to the current feature (e.g., FEATURE_DIR, FEATURE_SPEC, IMPL_PLAN).
check_file()	Checks if a given file exists and prints a status message.
check_dir()	Checks if a directory exists and is not empty, then prints a status message.

Script Invocation

The automation scripts are not intended to be run manually by the user. Instead, they are invoked by the AI agent, which is guided by instructions in the templates/commands/ directory. For example, when the user issues the /specify command, the agent follows the instructions in templates/commands/specify.md to execute the corresponding script.

This diagram illustrates the high-level interaction between the user, the AI agent, command templates, and the automation scripts.

Feature Initialization (/specify)

The create-new-feature.sh script automates the setup for a new feature. It is triggered by the /specify command.

Sources: scripts/create-new-feature.sh, templates/commands/specify.md

Logic Flow

The script performs the following actions:

1. Determines the next sequential feature number (e.g., 003) by scanning the specs/ directory.
2. Generates a git branch name from the user's feature description (e.g., 003-new-feature).
3. Creates and checks out the new git branch.
4. Creates a corresponding directory for the feature under specs/.
5. Copies the spec-template.md into the new feature directory to bootstrap the specification document.
6. Outputs the new branch name and the path to the spec.md file in JSON format for the AI agent to use.

This flowchart visualizes the process of the create-new-feature.sh script.

Arguments and Output

Type	Name	Description
Argument	FEATURE_DESCRIPTION	A string describing the new feature, passed as an argument.
Argument	--json	An optional flag to format the output as a single JSON object.
Output	BRANCH_NAME	The name of the newly created git branch.
Output	SPEC_FILE	The absolute path to the newly created spec.md file.

Implementation Planning (/plan)

During the planning phase, the update-agent-context.sh script is used to keep the AI agent's long-term memory or context file (e.g., CLAUDE.md) synchronized with the technical decisions made for the current feature.

Sources: scripts/update-agent-context.sh, templates/plan-template.md:105-112

Logic Flow

This script reads the plan.md for the current feature branch to extract key technical details and incrementally updates the agent's context file.

1. Extracts Tech Stack: It parses the plan.md file to find the Language/Version, Primary Dependencies, Testing, and Storage details.
2. Updates Context File: It locates the agent-specific context file (e.g., CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md).
3. Incremental Update: It adds the newly identified technologies to the "Active Technologies" section if they are not already present. It also updates the "Recent Changes" list with the current feature.
4. Preserves Manual Edits: The script is designed to preserve any manual additions made to the context file within designated <!-- MANUAL ADDITIONS START --> and <!-- MANUAL ADDITIONS END --> comment blocks.

The following sequence diagram shows how the script interacts with project files.

Task Generation (/tasks)

Before generating tasks, the check-task-prerequisites.sh script is run to verify that the necessary planning documents are in place. It is invoked as part of the /tasks command.

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

Logic Flow

The script checks for the existence of required and optional design documents within the current feature's specs/ directory.

1. Check for plan.md: It first verifies that the implementation plan (plan.md) exists, as it is a mandatory prerequisite. If not found, it exits with an error.
2. Find Optional Docs: It then checks for optional documents like research.md, data-model.md, contracts/, and quickstart.md.
3. Output Available Docs: If the --json flag is provided, it outputs a JSON object containing the feature directory path and a list of the available design documents. This structured output is easily parsable by the AI agent.

This flowchart shows the script's validation process.

Project Bootstrapping (specify init)

The specify CLI, defined in src/specify_cli/__init__.py, is the entry point for creating a new spec-kit project. The init command automates the initial setup, creating the directory structure and files where the other automation scripts will be used.

Sources: src/specify_cli/init.py

Logic Flow

The init command is an interactive process that guides the user through setting up a new project.

1. Argument Parsing: It determines if the project should be created in a new directory or the current one (--here).
2. AI Assistant Selection: It prompts the user to select an AI assistant (Claude, Gemini, or Copilot).
3. Prerequisite Checks: It verifies that required tools for the selected agent (e.g., claude CLI) are installed, unless --ignore-agent-tools is used.
4. Template Download: It fetches the latest release of the appropriate template .zip file from the github/spec-kit repository.
5. Extraction: It extracts the template files into the target project directory.
6. Git Initialization: It initializes a new git repository and creates an initial commit, unless --no-git is specified.

Conclusion

The automation scripts are a critical component of the spec-kit project, enabling the practical application of the Spec-Driven Development methodology. By providing a clear, scriptable interface for repository and file system operations, they allow the AI agent to reliably manage the development lifecycle. This combination of declarative command templates and imperative shell scripts creates a robust system for translating high-level user intent into a structured and version-controlled set of project artifacts.