This page provides a high-level overview of setting up a new Spec Kit project and understanding the basic workflow. It covers the essential steps from installation through your first feature implementation.
For detailed installation instructions and options, see Installation. For a comprehensive guide to the specify init command and all its options, see Initializing a Project. For in-depth information about the Spec-Driven Development methodology, see Spec-Driven Development.
The typical path from zero to a working project follows this sequence:
Installation and Initialization Diagram
Sources: docs/quickstart.md8-110 docs/installation.md1-31 docs/quickstart.md15-17
Install the specify-cli command globally using uv (recommended) or pipx. The only official packages are maintained at github/spec-kit Any package named specify-cli on PyPI is not affiliated with this project docs/installation.md13-14
Or use it without installation for one-time setup:
See Installation for alternative methods, including enterprise/air-gapped options using locally built wheels docs/installation.md37-41
Sources: docs/installation.md11-31 docs/quickstart.md21-46 README.md46-54
Create a new project or initialize in an existing directory. The init command sets up the necessary scaffolding for your chosen AI agent. Note that the --ai flag is now deprecated in favor of the more robust --integration system docs/installation.md42-55
The --integration flag selects your AI agent. Supported values include claude, copilot, gemini, codebuddy, pi, omp, zed, and shai docs/installation.md42-55 README.md58-61
See Initializing a Project for all options including --script (sh/ps), --no-git, --force, and --branch-numbering.
Sources: docs/installation.md42-69 docs/quickstart.md21-52 README.md58-61
After initialization, launch your AI agent (e.g., Claude Code, GitHub Copilot, Gemini CLI) in the project directory. The agent will have access to /speckit.* commands that guide the Spec-Driven Development workflow.
See Spec-Driven Development for the methodology and Slash Commands Reference for command documentation.
Sources: docs/quickstart.md43-110 docs/installation.md89-94 README.md81-122
When you run specify init, the CLI extracts core assets into your directory, including templates, scripts, and agent-specific configurations README.md58-61
Project Directory Structure
| Directory/File | Purpose |
|---|---|
.claude/commands/, .github/agents/, etc. | Agent-specific slash command definitions. Path varies by agent integration docs/installation.md107-110 |
CLAUDE.md, GEMINI.md, etc. | Agent context files providing project metadata and instructions docs/installation.md6 |
.specify/memory/constitution.md | Project governing principles created by /speckit.constitution docs/quickstart.md54-60 |
.specify/scripts/ | Automation scripts. Includes both bash/ (.sh) and powershell/ (.ps1) variants docs/installation.md99-102 |
.specify/templates/ | Markdown templates for specs, plans, and tasks docs/quickstart.md120-122 |
specs/NNN-feature-name/ | Feature-specific artifacts (spec.md, plan.md, tasks.md) created during the SDD workflow docs/quickstart.md11-12 |
Sources: docs/installation.md89-110 docs/quickstart.md8-18 docs/guides/evolving-specs.md85-93
The specify init command determines where to place command files for your selected AI agent based on its integration type docs/installation.md42-55
Agent Configuration Flow
Key mappings for common agents:
| Agent Key | Folder | Commands Subdir | Context File |
|---|---|---|---|
claude | .claude/ | commands | CLAUDE.md |
copilot | .github/ | agents | .github/copilot-instructions.md |
gemini | .gemini/ | commands | GEMINI.md |
windsurf | .windsurf/ | workflows | .windsurf/rules/specify-rules.md |
zed | .zed/ | agents | ZED.md |
Sources: docs/installation.md42-55 docs/index.md32-38 README.md26-27
After initialization, you follow a structured workflow using slash commands in your AI agent. The process is defined as Constitution → Specify → Clarify → Plan → Checklist → Tasks → Analyze → Implement → Converge docs/quickstart.md13-19
| Phase | Slash Command | Primary Artifact |
|---|---|---|
| Constitution | /speckit.constitution | .specify/memory/constitution.md |
| Specify | /speckit.specify | specs/NNN-feature/spec.md |
| Clarify | /speckit.clarify | specs/NNN-feature/spec.md |
| Plan | /speckit.plan | specs/NNN-feature/plan.md |
| Checklist | /speckit.checklist | specs/NNN-feature/checklist.md |
| Tasks | /speckit.tasks | specs/NNN-feature/tasks.md |
| Analyze | /speckit.analyze | N/A (Validation) |
| Implement | /speckit.implement | Application Source Code |
| Converge | /speckit.converge | specs/NNN-feature/tasks.md |
The automation scripts in .specify/scripts/ (e.g., bash/, powershell/) provide shared utilities to ensure consistency across the workflow docs/installation.md107-110
Sources: docs/quickstart.md8-114 docs/installation.md89-100 README.md81-122
After initializing your project:
specify version docs/installation.md83-87 or specify self check README.md66-67/speckit.constitution to establish project principles README.md81-89/speckit.specify to create your first feature specification README.md91-97For detailed command documentation, see:
/speckit.* command details.Sources: docs/quickstart.md54-114 docs/installation.md81-94 README.md63-80
Refresh this wiki