This page documents the local testing workflow for contributors who are modifying templates, commands, or scripts in the Spec Kit repository. When you make changes to files in templates/, scripts/, memory/, or other packaged assets, you need to test them before submitting a pull request. This page explains how to bypass the standard release pipeline and test your local changes directly.
For information about general contributing guidelines, see Contributing Guidelines. For details about project structure, see Project Structure and Configuration.
specify init Doesn't Test Local ChangesWhen you run uv run specify init, the CLI downloads pre-built release packages from GitHub. These packages are created by the automated release pipeline and published to GitHub Releases. Your local uncommitted changes are not included in these packages.
Standard Init Flow: Downloads released, versioned packages that don't include your local changes.
Local Testing Flow: Builds packages from your local repository state, including uncommitted changes.
Sources: CONTRIBUTING.md65-87
The local testing process consists of three steps: building packages, copying them to a test project, and verifying functionality.
Run the package creation script from the repository root:
The version number (v1.0.0) is arbitrary for local testing—it's only used to name the output directories. The script performs the following operations:
Package Generation Process: The script loops through all agents defined in AGENT_CONFIG, creating both Bash and PowerShell variants for each.
Sources: CONTRIBUTING.md70-76 .github/workflows/scripts/create-release-packages.sh1
After building, packages are located in .genreleases/. The directory naming convention is:
| Pattern | Example | Contents |
|---|---|---|
sdd-{agent}-package-sh/ | sdd-copilot-package-sh/ | Bash script variant |
sdd-{agent}-package-ps/ | sdd-copilot-package-ps/ | PowerShell script variant |
Copy the relevant package to your test project:
The -r flag copies recursively, and the trailing /. ensures the contents are copied directly into the target directory without creating a nested folder.
Sources: CONTRIBUTING.md78-82
Navigate to your test project and open your chosen AI agent. The agent will now have access to your locally modified commands and templates.
Verification checklist:
/speckit.* commands in its command paletteSources: CONTRIBUTING.md84-86
Understanding what gets packaged helps you verify that your changes are included correctly.
Package Contents: Each package contains the .specify/ directory with shared resources and an agent-specific directory with generated commands.
| Directory | Files | Purpose |
|---|---|---|
.specify/memory/ | constitution.md | Immutable architectural principles |
.specify/scripts/ | *.sh or *.ps1 | Cross-platform helper scripts |
.specify/templates/ | spec-template.mdplan-template.mdtasks-template.md | Workflow phase templates |
.specify/templates/commands/ | *.md with YAML frontmatter | Command template sources |
.{agent}/commands/ | Agent-specific command files | Generated from templates |
| Root | {AGENT}.md | Agent context file with project info |
Sources: CONTRIBUTING.md65-87
The system supports 16+ AI agents with different conventions. When testing your changes, consider which agents might be affected.
Agent Format Variations: The template processor generates different command formats based on agent requirements.
| Change Type | Agents to Test | Reason |
|---|---|---|
| Template content changes | At least 1 Markdown + 1 TOML agent | Verify both format outputs |
| Script logic changes | Both Bash + PowerShell variants | Cross-platform compatibility |
| Constitutional changes | Any 1 agent | Constitution is format-agnostic |
| Command frontmatter changes | Markdown + TOML agents | Frontmatter parsed differently |
| Path-specific changes | Affected agents only | Some agents use unique directories |
Sources: CONTRIBUTING.md65-87
Understanding how templates become agent commands helps you verify that your changes propagate correctly.
Template Processing: Commands are generated from unified templates with agent-specific formatting and placeholder substitution.
Command templates use YAML frontmatter to define metadata:
The processor:
$ARGUMENTS → agent-specific placeholder.specify/templates/ → {{project_dir}}/.specify/templates/Sources: .github/workflows/scripts/create-release-packages.sh1
After copying a package to your test project, verify these aspects:
.specify/templates/[NEEDS CLARIFICATION]) work correctly.sh).specify/memory/constitution.mdSources: CONTRIBUTING.md65-87
Symptom: create-release-packages.sh exits with error
Common causes:
templates/ or memory/AGENT_CONFIGResolution: Check script output for specific error. Validate YAML with a linter. Ensure all expected files exist.
Symptom: Agent doesn't show /speckit.* commands after copying package
Common causes:
{AGENT}.md) missing or malformedResolution:
ls -la .{agent}/commands/Symptom: Agent uses old template content despite copying new package
Common causes:
Resolution:
.genreleases/ before copyingSymptom: Scripts work on one platform but fail on another
Common causes:
/ vs \)Resolution:
.sh and .ps1 variantsfile commandSources: CONTRIBUTING.md65-87
The local testing workflow integrates with the broader contribution process:
Development to Distribution Flow: Local testing precedes PR submission, which eventually triggers automated release for all users.
Sources: CONTRIBUTING.md33-55
To verify cross-agent compatibility, test multiple agent variants:
For rapid iteration on scripts only:
This bypasses full package generation for faster testing cycles when only modifying scripts.
Constitutional changes affect plan generation and validation gates:
memory/constitution.md/speckit.specify to create a spec/speckit.plan to verify constitutional enforcementSources: CONTRIBUTING.md56-64
Refresh this wiki