Project Initialization

Relevant source files

• README.md
• src/specify_cli/__init__.py

This document covers the specify init command and its internal implementation. Project initialization is the process of bootstrapping a new Spec Kit project by downloading templates from GitHub releases, extracting them to the target directory, and setting up Git repository infrastructure.

For information about the interactive selection UI used during initialization, see Interactive Selection System. For details on environment validation performed before initialization, see Environment Validation. For GitHub API integration and rate limiting, see GitHub API Integration.

Overview

The init command is the primary entry point for creating new Spec Kit projects. It coordinates template downloads, directory structure creation, Git initialization, and AI agent configuration. The command supports two main scenarios: creating a new project directory or initializing in the current directory.

Sources: src/specify_cli/__init__.py980-992

Command Arguments and Flags

The init command accepts the following parameters:

Parameter	Type	Purpose
project_name	Argument	Target directory name (optional with --here, or use . for current directory)
--ai	Option	AI assistant identifier (e.g., claude, gemini, copilot)
--script	Option	Script type: sh (bash/zsh) or ps (PowerShell)
--ignore-agent-tools	Flag	Skip CLI tool verification for selected AI agent
--no-git	Flag	Skip Git repository initialization
--here	Flag	Initialize in current directory instead of creating new directory
--force	Flag	Skip confirmation when current directory is non-empty
--skip-tls	Flag	Disable SSL/TLS verification (not recommended)
--debug	Flag	Enable verbose diagnostic output
--github-token	Option	GitHub API token for authenticated requests

Sources: src/specify_cli/__init__.py981-991

Initialization Flow

Initialization Command Flow

This diagram shows the complete flow from command invocation to successful project initialization, including validation, selection, download, and setup phases.

Sources: src/specify_cli/__init__.py980-1269

Directory Path Resolution

The initialization process handles three directory scenarios:

1. New directory creation: specify init project-name

   • Creates new directory at ./project-name
   • Fails if directory already exists (no --force for new directories)

2. Current directory with . syntax: specify init .

   • Sets here = True internally
   • Uses current directory name as project name
   • Allows merge into existing files

3. Current directory with --here flag: specify init --here

   • Equivalent to . syntax
   • Cannot specify both --here and project name

Sources: src/specify_cli/__init__.py1020-1060

Template Download and Package Selection

Templates are downloaded from GitHub releases as pre-packaged ZIP archives. Each release contains 32 package variants (16 AI agents × 2 script types).

Package Naming Convention

Package names follow this pattern:

spec-kit-template-{agent}-{script}-v{version}.zip

Where:

• {agent}: AI assistant identifier (e.g., claude, gemini, copilot)
• {script}: Script type (sh or ps)
• {version}: Semantic version (e.g., 0.1.0)

Example: spec-kit-template-claude-sh-v0.1.0.zip

Template Package Selection Process

This diagram illustrates how the correct template package is identified and downloaded from the latest GitHub release.

Sources: src/specify_cli/__init__.py637-683

Download Process with Rate Limiting

The download process uses the httpx library with SSL verification via truststore. It handles GitHub API rate limiting by parsing response headers and providing actionable error messages.

Rate Limit Header Parsing

The system extracts rate limit information from GitHub API responses:

Header	Purpose
X-RateLimit-Limit	Total requests allowed per hour
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Timestamp when limit resets
Retry-After	Seconds to wait before retry (on 429 errors)

When rate limits are exceeded, the error message includes:

• Current rate limit status
• Reset time in local timezone
• Recommendation to use --github-token for authenticated requests
• Difference between authenticated (5,000/hour) and unauthenticated (60/hour) limits

Sources: src/specify_cli/__init__.py68-123

Authentication

GitHub tokens can be provided via:

1. --github-token command line option
2. GH_TOKEN environment variable
3. GITHUB_TOKEN environment variable

Priority: CLI option > GH_TOKEN > GITHUB_TOKEN

Sources: src/specify_cli/__init__.py59-66

Template Extraction

Template extraction handles two distinct scenarios with different merge behaviors:

New Directory Extraction

For new project directories:

1. Extract ZIP contents to target directory
2. If ZIP contains single top-level directory, flatten structure
3. Move contents up one level to avoid nested directory

Directory Structure Flattening

This diagram shows how nested ZIP structures are automatically flattened during extraction.

Sources: src/specify_cli/__init__.py846-870

Current Directory Merge (--here flag)

For initialization in existing directories:

1. Extract ZIP to temporary directory
2. Iterate through extracted items
3. For each item:
   • If directory exists in target: merge recursively
   • If file exists: overwrite (with warning if verbose)
   • Special case: .vscode/settings.json is merged, not overwritten

Current Directory Merge Logic

This diagram shows how template files are merged into existing project directories when using --here flag.

Sources: src/specify_cli/__init__.py800-844

JSON Merge Strategy

For .vscode/settings.json, a deep merge is performed:

• New keys are added
• Existing keys are preserved unless explicitly overwritten
• Nested dictionaries are merged recursively
• Lists and primitive values are replaced (not merged)

Sources: src/specify_cli/__init__.py594-635

Post-Extraction Setup

After template extraction, three setup operations occur:

1. Script Permissions (Unix-like systems only)

On non-Windows systems, all .sh scripts under .specify/scripts/ are made executable:

Script Permission Setup

This diagram shows how shell scripts are automatically made executable on Unix-like systems.

The permission logic:

• If user has read (0o400), add user execute (0o100)
• If group has read (0o040), add group execute (0o010)
• If other has read (0o004), add other execute (0o001)
• Always ensure at least user execute (0o100) is set

Sources: src/specify_cli/__init__.py901-943

2. Constitution Template Setup

The constitution is initialized from the template:

Constitution Initialization

This diagram shows the constitution setup logic, which preserves existing constitutions during re-initialization.

Sources: src/specify_cli/__init__.py945-978

3. Git Repository Initialization

Git initialization follows this decision tree:

Git Initialization Decision Tree

This diagram shows the complete Git initialization logic including error handling and skip conditions.

The is_git_repo() function checks if a directory is within a Git working tree by running:

Sources: src/specify_cli/__init__.py515-568 src/specify_cli/__init__.py1169-1183

Progress Tracking Integration

The initialization process integrates with StepTracker for live progress display. The tracker manages these steps:

Step Key	Label	Status Updates
precheck	Check required tools	Complete after environment validation
ai-select	Select AI assistant	Complete after selection (interactive or CLI)
script-select	Select script type	Complete after selection
fetch	Fetch latest release	Running → Complete (with version info)
download	Download template	Complete (with filename)
extract	Extract template	Running → Complete
zip-list	Archive contents	Complete (with entry count)
extracted-summary	Extraction summary	Complete (with item count)
chmod	Ensure scripts executable	Complete (with count) or Error (with failures)
constitution	Constitution setup	Complete, Skip, or Error
cleanup	Cleanup	Complete after ZIP removal
git	Initialize git repository	Complete, Skip, or Error (with message)
final	Finalize	Complete or Error

The tracker is attached to a Live display that auto-refreshes as steps complete. See StepTracker and Progress Display for implementation details.

Sources: src/specify_cli/__init__.py1129-1202

Directory Structure After Initialization

After successful initialization, the project contains:

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Copied from constitution-template.md
│   ├── scripts/
│   │   ├── check-prerequisites.{sh,ps1}
│   │   ├── common.{sh,ps1}
│   │   ├── create-new-feature.{sh,ps1}
│   │   ├── setup-plan.{sh,ps1}
│   │   └── update-agent-context.{sh,ps1}
│   └── templates/
│       ├── constitution-template.md
│       ├── plan-template.md
│       ├── spec-template.md
│       └── tasks-template.md
├── .{agent}/                         # Agent-specific directory
│   └── commands/                     # Slash commands for AI agent
│       ├── constitution.{md,toml}
│       ├── specify.{md,toml}
│       ├── clarify.{md,toml}
│       ├── plan.{md,toml}
│       ├── tasks.{md,toml}
│       └── implement.{md,toml}
├── {AGENT}.md                        # Agent context file (e.g., CLAUDE.md)
├── .vscode/                          # VS Code settings (if applicable)
│   └── settings.json
└── .git/                             # Git repository (unless --no-git)

Where:

• {agent}: Actual agent folder name from AGENT_CONFIG[selected_ai]["folder"]
• {sh,ps1}: Script type selected during initialization
• {md,toml}: Command format based on agent requirements

Sources: src/specify_cli/__init__.py126-229

Error Handling and Recovery

Initialization Failures

If initialization fails after directory creation:

• For new directories: directory is removed automatically
• For --here initialization: files are left in place (no automatic rollback)

Error Recovery Logic

This diagram shows the cleanup behavior when initialization fails.

Sources: src/specify_cli/__init__.py1186-1200

Git Initialization Failures

Git initialization failures are handled gracefully:

1. Error is captured during initialization
2. Tracker shows error status for git step
3. After successful initialization, detailed error panel is displayed
4. Panel includes manual Git initialization commands

The error panel persists after the Live display closes, ensuring users see the Git error details.

Sources: src/specify_cli/__init__.py1174-1222

Post-Initialization Messages

After successful initialization, three panels are displayed:

1. Agent Folder Security Notice

Warns users about potential credential storage in agent folders:

Some agents may store credentials, auth tokens, or other identifying and private 
artifacts in the agent folder within your project.
Consider adding {agent_folder} (or parts of it) to .gitignore to prevent 
accidental credential leakage.

Sources: src/specify_cli/__init__.py1224-1236

2. Next Steps Panel

Provides sequential commands for getting started:

1. Navigate to project directory (if new directory created)
2. Set agent-specific environment variables (if required, e.g., CODEX_HOME)
3. Core workflow commands: /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Sources: src/specify_cli/__init__.py1238-1268

3. Enhancement Commands Panel

Lists optional quality-improvement commands:

• /speckit.clarify: Structured clarification before planning
• /speckit.analyze: Cross-artifact consistency checking
• /speckit.checklist: Quality validation checklists

Sources: src/specify_cli/__init__.py1270-1279

Agent-Specific Configuration

The AGENT_CONFIG dictionary defines properties for each supported AI agent:

Where:

• name: Human-readable agent name for UI display
• folder: Directory name within project for agent-specific files
• install_url: Installation documentation URL (None for IDE-based agents)
• requires_cli: Whether agent requires CLI tool verification

For IDE-based agents (requires_cli: False):

• Tool check is skipped automatically
• --ignore-agent-tools flag is not needed
• Tracker shows "IDE-based, no CLI check" status

Sources: src/specify_cli/__init__.py126-229

Special Cases

Codex Environment Variable Setup

The Codex CLI requires setting CODEX_HOME environment variable to the project's .codex directory. The next steps panel includes platform-specific commands:

• Unix-like: export CODEX_HOME=/path/to/project/.codex
• Windows: setx CODEX_HOME C:\path\to\project\.codex

The path is properly shell-quoted using shlex.quote() to handle spaces and special characters.

Sources: src/specify_cli/__init__.py1246-1256

Amazon Q Developer CLI Limitations

Amazon Q Developer CLI does not support custom arguments for slash commands. This limitation is documented in the supported agents table and reflected in template generation.

Sources: README.md148