📋 Table of Contents

  1. Before You Start

  2. Installation

  3. Setup Step by Step

  4. Prompts to Use It

  5. Commands Table

  6. Daily Workflow

  7. Tips

  8. Troubleshooting

  9. Quick Reference

Before we dive in, did you know there is a way to code and ship faster?

Millions of developers use Wispr Flow to dictate code, write docs, and give coding agents better context. 89% of messages sent with zero edits. 4x faster than typing. Free on Mac, Windows, and iPhone. Try Wispr Flow free.

Okay, back to the guide!

✅ Before You Start

  • Python 3.11+ installed (python3 --version)

  • Git installed (git --version)

  • uv installed (recommended) — fast Python package manager (install guide)

  • OR pipx as an alternative to uv

  • At least one supported AI coding agent: Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, Cursor, or 25+ others

  • A project directory ready to initialize

❝

⚠️ Do NOT install from PyPI. The only official package is installed directly from GitHub as shown below. Any PyPI package with the same name is unaffiliated and unmaintained.

🛠️ Installation

macOS / Linux

bash

# Option 1: Persistent install with uv (recommended)
# Replace vX.Y.Z with the latest tag — check https://github.com/github/spec-kit/releases
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# Option 2: Persistent install with pipx
pipx install git+https://github.com/github/[email protected]

# Option 3: One-time use (no install required)
uvx --from git+https://github.com/github/[email protected] specify init my-project

# Verify install
specify version

Windows

powershell

# Option 1: Persistent install with uv
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

# Option 2: Persistent install with pipx
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

# Verify
specify version

Enterprise / Air-Gapped Environments

bash

# On a connected machine: download wheel bundles
pip download git+https://github.com/github/[email protected] -d ./spec-kit-wheels

# Transfer wheels to air-gapped machine, then:
pip install --no-index --find-links ./spec-kit-wheels specify-cli

Full air-gapped guide: docs/installation.md

Upgrade

bash

# uv
uv tool install specify-cli --force --from git+https://github.com/github/[email protected]

# pipx
pipx install --force git+https://github.com/github/[email protected]

🚀 Setup Step by Step

Step 1 — Initialize your project

bash

# New project
specify init my-project --integration copilot

# Existing project directory
specify init . --integration copilot
# or
specify init --here --integration copilot

# Force init into non-empty directory
specify init . --force --integration copilot

# For Claude Code specifically
specify init . --integration copilot

# For Codex CLI in skills mode
specify init . --integration codex --integration-options="--skills"
❝

⚠️ Run specify check after init to verify all dependencies are detected correctly.

Step 2 — Establish your project constitution

Open your AI coding agent inside the project directory. You'll see /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, and /speckit.implement available as slash commands.

Run this first:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for how these principles should guide technical decisions and implementation choices.

This creates .specify/memory/constitution.md — the governing document every subsequent AI action references.

Step 3 — Write your spec

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping. Photos are previewed in a tile interface within each album.

Focus on what and why. Do NOT mention tech stack here. The agent creates a branch (001-feature-name) and a spec.md in .specify/specs/001-feature-name/.

Step 4 — Clarify before planning

/speckit.clarify

This runs structured Q&A to surface ambiguities. Answer all questions. Only skip this for quick spikes or exploratory prototypes (and say so explicitly so the agent doesn't block).

Step 5 — Generate technical plan

/speckit.plan The application uses Vite with vanilla HTML, CSS, and JavaScript. Images are not uploaded anywhere. Metadata is stored in a local SQLite database.

Outputs: plan.md, data-model.md, api-spec.json, research.md, quickstart.md. Check research.md to verify the tech stack is correct.

Step 6 — Generate tasks

/speckit.tasks

Creates tasks.md with:

  • Tasks organized by user story

  • Dependency ordering

  • Parallel execution markers [P]

  • Exact file paths per task

Step 7 — Implement

/speckit.implement

The agent validates all prerequisites (constitution, spec, plan, tasks) then executes in order. Make sure all required CLI tools for your stack (e.g., dotnet, npm, python) are installed locally.

Step 8 — (Optional) Add extensions

bash

# Search available extensions
specify extension search

# Install a specific extension
specify extension add spec-kit-jira
specify extension add spec-kit-security-review
specify extension add spec-kit-qa

Browse all 80+ community extensions: speckit-community.github.io/extensions

💬 Prompts to Use It

Constitution

/speckit.constitution Create principles for a SaaS B2B product: API-first, 100% test coverage on business logic, strict TypeScript, no external state management libraries, all UI components accessible to WCAG 2.1 AA.

Specify

/speckit.specify Build a team task manager where users can create projects, add team members, assign tasks, and move tasks between Kanban columns (To Do, In Progress, In Review, Done) with drag-and-drop. Users are predefined — no auth required. Comments per task are unlimited. Users can edit/delete their own comments only.

Clarify

/speckit.clarify

Plan

/speckit.plan Use Next.js 14 App Router, TypeScript, Supabase for auth and database, Tailwind CSS, shadcn/ui components. Deploy to Vercel.

Analyze (run after tasks, before implement)

/speckit.analyze

Implement with checkpoint

/speckit.implement

After implementation, ask Claude Code to check browser console errors and fix them before closing the feature.

Research prompt for fast-moving frameworks

Go through the implementation plan and identify areas that need research because [framework] is rapidly changing. For each area, spawn a parallel research task and update research.md with specific version details we'll use.

📋 Commands Table

specify init <name> Bootstrap a new project with spec-kit structure.

specify init . Initialize in the current directory.

specify init --here --integration copilot Init here and set GitHub Copilot as the agent.

specify check Verify all prerequisites and installed tools.

specify version Show installed version.

specify extension search Browse available community extensions.

specify extension add <name> Install an extension.

specify preset search Browse available community presets.

specify preset add <name> Install a preset.

specify integration list List all supported AI agent integrations.

/speckit.constitution Create or update your project governing principles.

/speckit.specify Define what to build — requirements and user stories.

/speckit.clarify Structured gap-filling before planning.

/speckit.plan Create the technical implementation plan.

/speckit.analyze Cross-artifact consistency check before implementing.

/speckit.tasks Generate ordered task breakdown.

/speckit.taskstoissues Convert tasks to GitHub Issues.

/speckit.implement Execute all tasks and build the feature.

/speckit.checklist Generate a quality checklist for requirements.

🗓️ Daily Workflow

Starting a new feature:

  1. specify init --here --integration copilot (first time only)

  2. /speckit.constitution → set your project principles once

  3. /speckit.specify → describe the feature

  4. /speckit.clarify → resolve ambiguities

  5. /speckit.plan → give it the tech stack

  6. /speckit.tasks → break it into tasks

  7. /speckit.implement → build it

Iterating on an existing feature:

  • Run /speckit.clarify again if requirements change

  • Update spec.md manually, then re-run /speckit.plan and /speckit.tasks

  • Use spec-kit-iterate extension for mid-implementation spec updates

Team collaboration:

  • Use /speckit.taskstoissues to push tasks to GitHub Issues

  • Use spec-kit-jira or spec-kit-azure-devops extensions for enterprise project boards

  • PR descriptions auto-generated with spec-kit-pr-bridge extension

💡 Tips

  • Don't spec the how. /speckit.specify works best when you describe user behavior, not implementation details. Save the tech stack for /speckit.plan.

  • Run /speckit.clarify every time. Skipping it is the #1 source of rework. 10 minutes of structured Q&A saves hours of implementation drift.

  • Check research.md before implementing. Especially for fast-moving frameworks (.NET Aspire, Next.js App Router, etc.). Ask the agent to do parallel web research for the specific versions you're using.

  • Catch over-engineering early. After /speckit.plan, ask: "Is anything here over-engineered for this spec?" Claude Code adds components you didn't ask for — the plan review step is where you catch it.

  • Extensions are modular. Install only what your project needs. spec-kit-security-review for anything user-facing. spec-kit-qa for projects with acceptance criteria. spec-kit-jira for enterprise teams.

  • Parallel tasks with [P] in tasks.md can be handed to multiple agents simultaneously if you're using an orchestration extension like spec-kit-maqa.

🔧 Troubleshooting

command not found: uv Install uv first: curl -LsSf https://astral.sh/uv/install.sh | sh

command not found: specify Restart your terminal after installing, or run source ~/.bashrc.

Installed the wrong package from PyPI Uninstall it with pip uninstall specify-cli, then reinstall directly from GitHub using the commands in the Installation section.

Agent doesn't show /speckit.* commands Run specify check — a prerequisite is likely missing. Re-run specify init with the correct --integration flag.

specify init defaults to Copilot unexpectedly You're in a non-interactive session like CI or a pipe. Pass the flag explicitly: specify init . --integration copilot

Git auth fails on Linux Install Git Credential Manager:

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager

Agent adds components you didn't ask for Ask it directly: "Read the constitution and the spec. Is anything in this plan over-engineered or not in the spec? List everything."

Tasks are out of order Your research.md has gaps. Ask the agent to re-audit the plan with dependency ordering before re-running /speckit.tasks.

⚡ Quick Reference

# Full new project flow
uv tool install specify-cli --from git+https://github.com/github/[email protected]
specify init my-project --integration copilot
specify check
specify version

# In your agent:
/speckit.constitution   # Step 1: Principles
/speckit.specify        # Step 2: What to build
/speckit.clarify        # Step 3: Resolve gaps
/speckit.plan           # Step 4: Tech stack + architecture
/speckit.analyze        # Step 5: Cross-check artifacts
/speckit.tasks          # Step 6: Task breakdown
/speckit.implement      # Step 7: Build it

# Extensions
specify extension search
specify extension add <name>
specify integration list

# Maintenance
uv tool install specify-cli --force --from git+https://github.com/github/[email protected]

@bestapps.ai — we find tools before everyone else

Keep Reading

View more
caret-right