Initializing a Project

Relevant source files

• AGENTS.md
• CHANGELOG.md
• docs/community/friends.md
• docs/concepts/sdd.md
• docs/concepts/spec-persistence.md
• docs/docfx.json
• docs/guides/evolving-specs.md
• docs/index.md
• docs/installation.md
• docs/quickstart.md
• docs/template/public/main.css
• docs/toc.yml
• pyproject.toml
• src/specify_cli/__init__.py
• src/specify_cli/_invocation_style.py
• src/specify_cli/commands/init.py
• src/specify_cli/integrations/zcode/__init__.py
• tests/integrations/test_integration_zcode.py

This page covers the specify init command: its flags, interactive prompts, the files it installs, and the project layout produced. For installation of the specify CLI itself (prerequisites, uv tool install, specify check), see 2.1 Installation For a full flag-by-flag reference including edge cases, see 4.1 specify init

---

Overview

specify init bootstraps a directory for Spec-Driven Development (SDD). It:

1. Determines the target AI agent and script type (interactively or from flags) src/specify_cli/commands/init.py79-131
2. Extracts bundled assets (templates, scripts, commands, and workflows) from the package wheel to the project directory pyproject.toml30-50
3. Sets up the appropriate Integration (using the --integration flag, which replaced the deprecated --ai flag) to connect the project to an AI coding assistant src/specify_cli/commands/init.py126-130 CHANGELOG.md121
4. Initializes project-wide infrastructure, including shared templates and the .specify/memory/constitution.md file src/specify_cli/commands/init.py33-70

Sources: src/specify_cli/commands/init.py138-168 pyproject.toml30-50 CHANGELOG.md121

---

Basic Usage

When run without --integration, the CLI presents an interactive menu to select the agent if the session is interactive src/specify_cli/commands/init.py29-30 In non-interactive sessions, it defaults to copilot src/specify_cli/_agent_config.py79 Without --script, it defaults to ps (PowerShell) on Windows and sh (POSIX Shell) on other systems src/specify_cli/_agent_config.py80-81 docs/installation.md61-64

Sources: src/specify_cli/__init__.py17-27 src/specify_cli/commands/init.py152-163 src/specify_cli/_agent_config.py77-81

---

Flags Reference

Flag	Type	Default	Description
--integration	string	(interactive)	AI agent integration key (e.g. claude, copilot, gemini) src/specify_cli/commands/init.py126-130
--integration-options	string	None	Custom options for the integration (e.g. --skills or --commands-dir) src/specify_cli/commands/init.py131-135
--script	sh, ps, py	OS-detected	Script variant to install (sh for Bash, ps for PowerShell, py for Python) src/specify_cli/commands/init.py79-81 CHANGELOG.md9
--here	flag	false	Initialize in current working directory src/specify_cli/commands/init.py87-91
--force	flag	false	Overwrite existing project files and skip confirmation src/specify_cli/commands/init.py92-96
--no-git	flag	false	Deprecated at v0.10.0. Git functionality is now an opt-in extension CHANGELOG.md114
--branch-numbering	string	sequential	Strategy for naming feature branches (sequential or timestamp) src/specify_cli/_init_options.py82-87
--preset	string	None	Install a specific preset (e.g. lean) during initialization src/specify_cli/commands/init.py121-125
--ignore-agent-tools	flag	false	Skip CLI tool availability checks for the chosen agent src/specify_cli/commands/init.py82-86

Sources: src/specify_cli/commands/init.py74-136 CHANGELOG.md9-121

---

Selecting an AI Integration

Interactive Selection

When --integration is omitted in an interactive terminal, the CLI uses select_with_arrows to render a selection menu based on the INTEGRATION_REGISTRY src/specify_cli/commands/init.py25 src/specify_cli/integrations/__init__.py15-16

Integration Architecture

The --integration flag maps to the INTEGRATION_REGISTRY. Each integration is a subpackage under src/specify_cli/integrations/ that inherits from a base class (e.g., MarkdownIntegration, SkillsIntegration) to declare its metadata and file layout AGENTS.md13-31

Integration Key to Directory Mapping

Sources: src/specify_cli/integrations/__init__.py13-35 AGENTS.md39-105 CHANGELOG.md27

---

Script Type and Execution

The CLI supports multiple automation backends src/specify_cli/_agent_config.py80-81:

• sh: POSIX Shell (bash/zsh)
• ps: PowerShell
• py: Python (added in v0.12.4) CHANGELOG.md9

On non-Windows systems, the CLI automatically runs ensure_executable_scripts() to set the execute bit (chmod +x) on all .sh files under .specify/scripts/ and .specify/extensions/ src/specify_cli/__init__.py209-221

Sources: src/specify_cli/_agent_config.py80-81 src/specify_cli/__init__.py209-221 CHANGELOG.md9

---

Initializing in an Existing Directory (--here)

When --here (or . as the project name) is used:

• The CLI checks if the directory is empty. If not, it warns the user unless --force is used src/specify_cli/commands/init.py92-96
• A deep-merge of .vscode/settings.json is performed if it already exists, preserving user settings while adding Spec Kit defaults via handle_vscode_settings() src/specify_cli/__init__.py67
• The command ensures that .specify/memory/constitution.md is created from the template if it does not already exist, preserving any existing constitution file src/specify_cli/commands/init.py33-70

Sources: src/specify_cli/commands/init.py33-70 src/specify_cli/__init__.py67

---

Initialization Logic Flow

The following diagram illustrates the data flow from CLI flags to the final project structure, showing how the StepTracker monitors progress.

Sources: src/specify_cli/commands/init.py138-185 src/specify_cli/integrations/__init__.py15-35 pyproject.toml30-50

---

Project Directory Layout

A successfully initialized project follows this structure, driven by core assets bundled via hatchling pyproject.toml29-50:

Path	Purpose
.specify/memory/constitution.md	Project-wide principles and standards src/specify_cli/commands/init.py37
.specify/scripts/bash/	Core SDD automation scripts (Bash) pyproject.toml40
.specify/scripts/powershell/	Core SDD automation scripts (PowerShell) pyproject.toml41
.specify/templates/	Markdown templates for specs, plans, and tasks pyproject.toml32-36
.specify/workflows/speckit/	Bundled SDD workflow definitions pyproject.toml47
.<agent-folder>/	Integration files (e.g. .claude/skills/ or .github/prompts/) AGENTS.md148-154
.vscode/settings.json	VS Code integration settings pyproject.toml37
.specify/integration.json	Records the active integration and its configuration src/specify_cli/integrations/_commands.py181
.specify/init-options.json	Persists CLI flags used during init for future reference src/specify_cli/commands/init.py174

Sources: src/specify_cli/commands/init.py33-70 pyproject.toml29-50 AGENTS.md148-154 src/specify_cli/integrations/_commands.py181

---

Next Steps

After initialization, verify your installation and begin the SDD cycle:

1. Verify: Run specify version and specify check to ensure tools are found src/specify_cli/__init__.py97-106
2. Constitution: Use the /speckit.constitution slash command in your agent to set project rules docs/quickstart.md54-61
3. Specify: Use /speckit.specify to define your first feature and create a new branch docs/quickstart.md62-69

For detailed workflow steps, see 3. Spec-Driven Development