Package Build System

Relevant source files

• .github/workflows/RELEASE-PROCESS.md
• .github/workflows/codeql.yml
• .github/workflows/docs.yml
• .github/workflows/lint.yml
• .github/workflows/publish-pypi.yml
• .github/workflows/release-trigger.yml
• .github/workflows/release.yml
• .github/workflows/stale.yml
• .github/workflows/test.yml
• AGENTS.md
• CHANGELOG.md
• pyproject.toml
• src/specify_cli/__init__.py

The Package Build System is responsible for generating pre-built template packages for all supported AI agents during the release process. This system transforms generic command templates into agent-specific formats and directory structures, producing over 60 individual ZIP packages (30+ agents × 2 shell types) that users download during specify init.

For information about triggering the build process, see Release Process. For the overall CI/CD infrastructure, see CI/CD Workflows.

Overview

The build system is centered around the create-release-packages.sh script (and its logic mirrored in the core_pack bundling), which:

1. Reads generic command templates from templates/commands/*.md.
2. Processes each template through a placeholder replacement pipeline.
3. Generates agent-specific command files in their required formats (Markdown, TOML, or Skills).
4. Creates appropriate directory structures based on the INTEGRATION_REGISTRY metadata src/specify_cli/integrations/__init__.py15-33
5. Packages everything into versioned ZIP archives or bundles them into the Python wheel pyproject.toml29-50

This approach ensures consistent output across all agent variants and allows specify init to work without network access by using the bundled core_pack pyproject.toml30

Sources: src/specify_cli/integrations/__init__.py15-33 pyproject.toml29-50 src/specify_cli/__init__.py131-150

Build Matrix Architecture

The build system operates on a multi-dimensional matrix defined by the supported integrations and shell types.

Matrix Mapping (Natural Language to Code Entities)

Matrix Configuration:

Dimension	Values	Source
Agents	30+ variants (e.g., Claude, Gemini, Zed, Hermes)	src/specify_cli/integrations/__init__.py15-33 CHANGELOG.md27 CHANGELOG.md124
Shell Types	3 variants (sh, ps, py)	src/specify_cli/_agent_config.py77-81 CHANGELOG.md9
Total Packages	60+	~30 × 2 (Standard variants)

Sources: src/specify_cli/_agent_config.py77-81 src/specify_cli/integrations/__init__.py15-33 CHANGELOG.md9 CHANGELOG.md27

Template Processing Pipeline

The _install_shared_infra function (and the underlying _install_shared_infra_impl) implements the transformation pipeline to convert generic Markdown templates into agent-specific artifacts src/specify_cli/__init__.py131-182

Transformation Logic (Code Entity Flow)

Sources: src/specify_cli/__init__.py131-150 AGENTS.md41-47 src/specify_cli/__init__.py38-41

Placeholder Replacement

The system replaces several types of placeholders during template processing to adapt to the target agent's environment:

Placeholder	Replacement	Source
__SPECKIT_COMMAND_<NAME>__	Resolved using invoke_separator (e.g., . or -)	src/specify_cli/__init__.py147-149
{ARGS}	Agent-specific argument format (e.g., $ARGUMENTS, {{args}})	AGENTS.md149
__AGENT__	The integration key	AGENTS.md147

Sources: src/specify_cli/__init__.py147-149 AGENTS.md143-151

Argument Format by Agent Type

Different agents use different argument passing conventions, defined in the registrar_config of each integration class in src/specify_cli/integrations/.

Agent Type	Format (args)	Extension	Example Agents
MarkdownIntegration	$ARGUMENTS	.md	Windsurf, Zed
TomlIntegration	{{args}}	.toml	Gemini
SkillsIntegration	$ARGUMENTS	/SKILL.md	Claude, Codex, Kimi

Sources: AGENTS.md72-77 AGENTS.md97-102 AGENTS.md124-129

Agent-Specific Build Logic

The build process implements specialized logic for each agent's directory structure and file format requirements, governed by the config and registrar_config attributes of the integration classes.

Sources: AGENTS.md143-151 AGENTS.md63-71 AGENTS.md88-96

Specialized Handlers

Skills-based Agents (Claude, Kimi, Codex)

These agents use SkillsIntegration. Commands are generated as directories where each command name is a folder containing a SKILL.md file AGENTS.md105-130

TOML-based Agents (Gemini)

Gemini uses TomlIntegration. The build system generates .toml files in the .gemini/commands/ directory AGENTS.md80-103

Markdown-based Agents (Windsurf, Zed)

Standard IDE integrations use MarkdownIntegration, placing .md files in directories like .windsurf/workflows/ or .zed/workflows/ AGENTS.md55-78 CHANGELOG.md27

Script Variant Filtering

The build system bundles only the relevant shell scripts for each variant. This is controlled by the script_type parameter in _install_shared_infra src/specify_cli/__init__.py131-139

• sh variant: Copies scripts from scripts/bash to .specify/scripts/bash/ src/specify_cli/__init__.py142-144 pyproject.toml40
• ps variant: Copies scripts from scripts/powershell to .specify/scripts/powershell/ src/specify_cli/__init__.py142-144 pyproject.toml41

Build Directory Structure (Core Pack)

The pyproject.toml file defines the core_pack structure, which is the "source of truth" for the files bundled within the specify-cli Python package pyproject.toml29-50

Sources: pyproject.toml29-50 src/specify_cli/__init__.py140-146

Version Synchronization

The build system utilizes strict validation during the release process to ensure the version string is synchronized across all components:

1. pyproject.toml: The primary version definition pyproject.toml3
2. CHANGELOG.md: Updated via the Release Trigger workflow CHANGELOG.md5 .github/workflows/release-trigger.yml84-118
3. Git Tags: Created and pushed by the release trigger .github/workflows/release-trigger.yml135-140
4. CLI Output: get_speckit_version() returns the version defined in the package metadata src/specify_cli/__init__.py97-100

Sources: pyproject.toml3 .github/workflows/release-trigger.yml79-83 .github/workflows/release-trigger.yml135-140 src/specify_cli/__init__.py97-100