Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: streamline install section and add community overview (#2561)

Manfred Riem707e929c2ab9
diff --git a/EOF b/EOF
deleted file mode 100644
index e69de29bb..000000000
diff --git a/README.md b/README.md
index b0a474888..6128ff8f2 100644
--- a/README.md
+++ b/README.md
@@ -35,8 +35,7 @@
- [πŸ”§ Prerequisites](#-prerequisites)
- [πŸ“– Learn More](#-learn-more)
- [πŸ“‹ Detailed Process](#-detailed-process)
-- [πŸ” Troubleshooting](#-troubleshooting)
-- [πŸ’¬ Support](#-support)
+- [ Support](#-support)
- [πŸ™ Acknowledgements](#-acknowledgements)
- [πŸ“„ License](#-license)
@@ -48,83 +47,22 @@ Spec-Driven Development **flips the script** on traditional software development
### 1. Install Specify CLI
-Choose your preferred installation method:
-
-> **Important:** The only official, maintained packages for Spec Kit are published from this GitHub repository. Any packages with the same name on PyPI are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. Always install directly from GitHub as shown below.
-
-#### Option 1: Persistent Installation (Recommended)
-
-Install once and use everywhere. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
-
-> [!NOTE]
-> The `uv tool install` commands below require **[uv](https://docs.astral.sh/uv/)** β€” a fast Python package manager. If you see `command not found: uv`, [install uv first](./docs/install/uv.md). The `pipx` alternative does not require uv.
+Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md)). Replace `vX.Y.Z` with the latest tag from [Releases](https://github.com/github/spec-kit/releases):
```bash
-# Install a specific stable release (recommended β€” replace vX.Y.Z with the latest tag)
uv tool install specify-cli --from git+https://github.com/github/[email protected]
-
-# Or install latest from main (may include unreleased changes)
-uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
-
-# Alternative: using pipx (also works)
-pipx install git+https://github.com/github/[email protected]
-pipx install git+https://github.com/github/spec-kit.git
-```
-
-Then verify the correct version is installed:
-
-```bash
-specify version
-```
-
-And use the tool directly:
-
-```bash
-# Create new project
-specify init <PROJECT_NAME>
-
-# Or initialize in existing project
-specify init . --integration copilot
-# or
-specify init --here --integration copilot
-
-# Check installed tools
-specify check
```
-To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade:
-
-```bash
-uv tool install specify-cli --force --from git+https://github.com/github/[email protected]
-# pipx users: pipx install --force git+https://github.com/github/[email protected]
-```
+See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting.
-#### Option 2: One-time Usage
-
-Run directly without installing:
+### 2. Initialize a project
```bash
-# Create new project (pinned to a stable release β€” replace vX.Y.Z with the latest tag)
-uvx --from git+https://github.com/github/[email protected] specify init <PROJECT_NAME>
-
-# Or initialize in existing project
-uvx --from git+https://github.com/github/[email protected] specify init . --integration copilot
-# or
-uvx --from git+https://github.com/github/[email protected] specify init --here --integration copilot
+specify init my-project --integration copilot
+cd my-project
```
-**Benefits of persistent installation:**
-
-- Tool stays installed and available in PATH
-- No need to create shell aliases
-- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
-- Cleaner shell configuration
-
-#### Option 3: Enterprise / Air-Gapped Installation
-
-If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](./docs/installation.md#enterprise--air-gapped-installation) guide for step-by-step instructions on using `pip download` to create portable, OS-specific wheel bundles on a connected machine.
-
-### 2. Establish project principles
+### 3. Establish project principles
Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.
@@ -134,7 +72,7 @@ Use the **`/speckit.constitution`** command to create your project's governing p
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
```
-### 3. Create the spec
+### 4. Create the spec
Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
@@ -142,7 +80,7 @@ Use the **`/speckit.specify`** command to describe what you want to build. Focus
/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 on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
```
-### 4. Create a technical implementation plan
+### 5. Create a technical implementation plan
Use the **`/speckit.plan`** command to provide your tech stack and architecture choices.
@@ -150,7 +88,7 @@ Use the **`/speckit.plan`** command to provide your tech stack and architecture
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
```
-### 5. Break down into tasks
+### 6. Break down into tasks
Use **`/speckit.tasks`** to create an actionable task list from your implementation plan.
@@ -158,7 +96,7 @@ Use **`/speckit.tasks`** to create an actionable task list from your implementat
/speckit.tasks
```
-### 6. Execute implementation
+### 7. Execute implementation
Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan.
@@ -639,26 +577,7 @@ Once the implementation is complete, test the application and resolve any runtim
---
-## πŸ” Troubleshooting
-
-### Git Credential Manager on Linux
-
-If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
-
-```bash
-#!/usr/bin/env bash
-set -e
-echo "Downloading Git Credential Manager v2.6.1..."
-wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
-echo "Installing Git Credential Manager..."
-sudo dpkg -i gcm-linux_amd64.2.6.1.deb
-echo "Configuring Git to use GCM..."
-git config --global credential.helper manager
-echo "Cleaning up..."
-rm gcm-linux_amd64.2.6.1.deb
-```
-
-## πŸ’¬ Support
+## Support
For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development.
diff --git a/docs/community/overview.md b/docs/community/overview.md
new file mode 100644
index 000000000..99804be3c
--- /dev/null
+++ b/docs/community/overview.md
@@ -0,0 +1,27 @@
+# Community
+
+The Spec Kit community builds extensions, presets, walkthroughs, and companion projects that expand what you can do with Spec-Driven Development. All community contributions are independently created and maintained by their respective authors.
+
+## Extensions
+
+Extensions add new capabilities to Spec Kit β€” domain-specific commands, external tool integrations, quality gates, and more. Over 90 community extensions are available from 50+ authors, covering everything from accessibility governance to multi-agent orchestration.
+
+[Browse community extensions β†’](extensions.md)
+
+## Presets
+
+Presets customize how Spec Kit behaves β€” overriding templates, commands, and terminology without changing any tooling. Community presets range from language localizations to entirely different development methodologies.
+
+[Browse community presets β†’](presets.md)
+
+## Walkthroughs
+
+Step-by-step guides that show Spec-Driven Development in action across different scenarios, languages, and frameworks.
+
+[Browse community walkthroughs β†’](walkthroughs.md)
+
+## Friends
+
+Community projects that extend, visualize, or build on Spec Kit β€” including VS Code extensions, Claude Code plugins, and more.
+
+[Browse friend projects β†’](friends.md)
diff --git a/docs/index.md b/docs/index.md
index dba3b2c55..e44bebd24 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -43,7 +43,9 @@ Run `specify init` with your agent of choice and Spec Kit sets up the right comm
### Make it your own
-<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing β€” including entirely different SDD processes:
+<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
+
+Including entirely different SDD processes:
- **AIDE** β€” 7-step AI-driven engineering lifecycle
- **Canon** β€” baseline-driven workflows (spec-first, code-first, spec-drift)
@@ -51,8 +53,6 @@ Run `specify init` with your agent of choice and Spec Kit sets up the right comm
- **FX→.NET** — end-to-end .NET Framework migration across 7 phases
- **MAQA** β€” multi-agent orchestration with quality assurance gates
-Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own.
-
<a href="community/presets.md" class="pillar-link">Browse community presets β†’</a>
</div>
@@ -124,9 +124,9 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
<strong>Reference</strong>
<span>Core commands, integrations, extensions, presets, and workflows</span>
</a>
- <a href="community/presets.md" class="nav-card">
+ <a href="community/overview.md" class="nav-card">
<strong>Community</strong>
- <span>Presets, walkthroughs, and friend projects</span>
+ <span>Extensions, presets, walkthroughs, and friend projects</span>
</a>
<a href="local-development.md" class="nav-card">
<strong>Development</strong>
diff --git a/docs/install/air-gapped.md b/docs/install/air-gapped.md
new file mode 100644
index 000000000..bf2a46380
--- /dev/null
+++ b/docs/install/air-gapped.md
@@ -0,0 +1,59 @@
+# Enterprise / Air-Gapped Installation
+
+If your environment blocks access to PyPI or GitHub, you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
+
+## Step 1: Build the wheel on a connected machine
+
+> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
+
+```bash
+# Clone the repository
+git clone https://github.com/github/spec-kit.git
+cd spec-kit
+
+# Build the wheel
+pip install build
+python -m build --wheel --outdir dist/
+
+# Download the wheel and all its runtime dependencies
+pip download -d dist/ dist/specify_cli-*.whl
+```
+
+## Step 2: Transfer the `dist/` directory
+
+Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
+
+## Step 3: Install on the air-gapped machine
+
+```bash
+pip install --no-index --find-links=./dist specify-cli
+```
+
+## Step 4: Initialize a project
+
+No network access is required β€” bundled assets are used by default:
+
+```bash
+specify init my-project --integration copilot
+```
+
+> **Note:** Python 3.11+ is required.
+
+> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
+
+## Git Credential Manager on Linux
+
+If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
+
+```bash
+#!/usr/bin/env bash
+set -e
+echo "Downloading Git Credential Manager v2.6.1..."
+wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
+echo "Installing Git Credential Manager..."
+sudo dpkg -i gcm-linux_amd64.2.6.1.deb
+echo "Configuring Git to use GCM..."
+git config --global credential.helper manager
+echo "Cleaning up..."
+rm gcm-linux_amd64.2.6.1.deb
+```
diff --git a/docs/install/one-time.md b/docs/install/one-time.md
new file mode 100644
index 000000000..134cb0b11
--- /dev/null
+++ b/docs/install/one-time.md
@@ -0,0 +1,32 @@
+# One-time Usage (uvx)
+
+If you want to try Spec Kit without installing it permanently, use `uvx` to run it directly. This downloads the tool into a temporary environment that is discarded after the command finishes.
+
+> [!NOTE]
+> The commands below require **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uvx`, [install uv first](uv.md).
+
+## Run Specify CLI
+
+```bash
+# Create a new project (latest from main)
+uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+
+# Or target a specific release (replace vX.Y.Z with a tag from Releases)
+uvx --from git+https://github.com/github/[email protected] specify init <PROJECT_NAME>
+
+# Initialize in the current directory
+uvx --from git+https://github.com/github/spec-kit.git specify init . --integration copilot
+
+# Or use the --here flag
+uvx --from git+https://github.com/github/spec-kit.git specify init --here --integration copilot
+```
+
+## When to use persistent installation instead
+
+If you plan to use Spec Kit regularly, a persistent installation is recommended:
+
+- Tool stays installed and available in PATH
+- No re-download on every invocation
+- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
+
+See the main [Installation Guide](../installation.md) for persistent installation instructions.
diff --git a/docs/install/pipx.md b/docs/install/pipx.md
new file mode 100644
index 000000000..68c55bd9c
--- /dev/null
+++ b/docs/install/pipx.md
@@ -0,0 +1,37 @@
+# Installing with pipx
+
+[pipx](https://pypa.github.io/pipx/) is a tool for installing Python CLI applications in isolated environments. It does not require [uv](https://docs.astral.sh/uv/).
+
+## Install Specify CLI
+
+Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
+
+```bash
+# Install a specific stable release (recommended β€” replace vX.Y.Z with the latest tag)
+pipx install git+https://github.com/github/[email protected]
+
+# Or install latest from main (may include unreleased changes)
+pipx install git+https://github.com/github/spec-kit.git
+```
+
+## Verify
+
+```bash
+specify version
+```
+
+## Upgrade
+
+```bash
+pipx install --force git+https://github.com/github/[email protected]
+```
+
+## Uninstall
+
+```bash
+pipx uninstall specify-cli
+```
+
+## Next steps
+
+Head to the [Quick Start](../quickstart.md) to initialize your first project.
diff --git a/docs/installation.md b/docs/installation.md
index 86ad35559..06f5de471 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -10,38 +10,35 @@
## Installation
-> **Important:** The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
+> [!IMPORTANT]
+> The only official, maintained packages for Spec Kit come from the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository. Any packages with the same name available on PyPI (e.g. `specify-cli` on pypi.org) are **not** affiliated with this project and are not maintained by the Spec Kit maintainers. For normal installs, use the GitHub-based commands shown below. For offline or air-gapped environments, locally built wheels created from this repository are also valid.
-### Initialize a New Project
+### Persistent Installation (Recommended)
-The easiest way to get started is to initialize a new project. Pin a specific release tag for stability (check [Releases](https://github.com/github/spec-kit/releases) for the latest):
+Install once and use everywhere. Replace `vX.Y.Z` with a tag from [Releases](https://github.com/github/spec-kit/releases):
> [!NOTE]
-> The `uvx` commands below require **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uvx`, [install uv first](./install/uv.md). The `pipx` alternative does not require uv.
+> The command below requires **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uv`, [install uv first](./install/uv.md).
```bash
-# Install from a specific stable release (recommended β€” replace vX.Y.Z with the latest tag)
-uvx --from git+https://github.com/github/[email protected] specify init <PROJECT_NAME>
-
-# Or install latest from main (may include unreleased changes)
-uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
+uv tool install specify-cli --from git+https://github.com/github/[email protected]
```
-> [!NOTE]
-> For a persistent installation, `pipx` works equally well:
-> ```bash
-> pipx install git+https://github.com/github/[email protected]
-> ```
-> The project uses a standard `hatchling` build backend and has no uv-specific dependencies.
-
-Or initialize in the current directory:
+Then initialize a project:
```bash
-uvx --from git+https://github.com/github/[email protected] specify init .
-# or use the --here flag
-uvx --from git+https://github.com/github/[email protected] specify init --here
+specify init <PROJECT_NAME> --integration copilot
```
+### One-time Usage
+
+Run directly without installing β€” see the [One-time usage (uvx)](install/one-time.md) guide.
+
+### Alternative Package Managers
+
+- **pipx** β€” see the [pipx installation guide](install/pipx.md)
+- **Enterprise / Air-Gapped** β€” see the [air-gapped installation guide](install/air-gapped.md)
+
### Specify Integration
Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass `--integration`.
@@ -49,11 +46,11 @@ Interactive terminals prompt you to choose a coding agent integration during ini
You can proactively specify your coding agent integration during initialization:
```bash
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration claude
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration gemini
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration copilot
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration codebuddy
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration pi
+specify init <project_name> --integration claude
+specify init <project_name> --integration gemini
+specify init <project_name> --integration copilot
+specify init <project_name> --integration codebuddy
+specify init <project_name> --integration pi
```
### Specify Script Type (Shell vs PowerShell)
@@ -69,8 +66,8 @@ Auto behavior:
Force a specific script type:
```bash
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --script sh
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --script ps
+specify init <project_name> --script sh
+specify init <project_name> --script ps
```
### Ignore Agent Tools Check
@@ -78,7 +75,7 @@ uvx --from git+https://github.com/github/[email protected] specify init <proje
If you prefer to get the templates without checking for the right tools:
```bash
-uvx --from git+https://github.com/github/[email protected] specify init <project_name> --integration claude --ignore-agent-tools
+specify init <project_name> --integration claude --ignore-agent-tools
```
## Verification
@@ -103,61 +100,8 @@ The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
### Enterprise / Air-Gapped Installation
-If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can create a portable wheel bundle on a connected machine and transfer it to the air-gapped target.
-
-**Step 1: Build the wheel on a connected machine (same OS and Python version as the target)**
-
-```bash
-# Clone the repository
-git clone https://github.com/github/spec-kit.git
-cd spec-kit
-
-# Build the wheel
-pip install build
-python -m build --wheel --outdir dist/
-
-# Download the wheel and all its runtime dependencies
-pip download -d dist/ dist/specify_cli-*.whl
-```
-
-> **Important:** `pip download` resolves platform-specific wheels (e.g., PyYAML includes native extensions). You must run this step on a machine with the **same OS and Python version** as the air-gapped target. If you need to support multiple platforms, repeat this step on each target OS (Linux, macOS, Windows) and Python version.
-
-**Step 2: Transfer the `dist/` directory to the air-gapped machine**
-
-Copy the entire `dist/` directory (which contains the `specify-cli` wheel and all dependency wheels) to the target machine via USB, network share, or other approved transfer method.
-
-**Step 3: Install on the air-gapped machine**
-
-```bash
-pip install --no-index --find-links=./dist specify-cli
-```
-
-**Step 4: Initialize a project (no network required)**
-
-```bash
-# Initialize a project β€” no GitHub access needed
-specify init my-project --integration claude
-```
-
-Bundled assets are used by default β€” no network access is required.
-
-> **Note:** Python 3.11+ is required.
-
-> **Windows note:** Offline scaffolding requires PowerShell 7+ (`pwsh`), not Windows PowerShell 5.x (`powershell.exe`). Install from https://aka.ms/powershell.
+If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](install/air-gapped.md) guide for step-by-step instructions on creating portable wheel bundles.
### Git Credential Manager on Linux
-If you're having issues with Git authentication on Linux, you can install Git Credential Manager:
-
-```bash
-#!/usr/bin/env bash
-set -e
-echo "Downloading Git Credential Manager v2.6.1..."
-wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
-echo "Installing Git Credential Manager..."
-sudo dpkg -i gcm-linux_amd64.2.6.1.deb
-echo "Configuring Git to use GCM..."
-git config --global credential.helper manager
-echo "Cleaning up..."
-rm gcm-linux_amd64.2.6.1.deb
-```
+If you're having issues with Git authentication on Linux, see the [Air-Gapped Installation guide](install/air-gapped.md#git-credential-manager-on-linux) for Git Credential Manager setup instructions.
diff --git a/docs/toc.yml b/docs/toc.yml
index d64d3b89d..ce91339a1 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -13,6 +13,12 @@
href: upgrade.md
- name: Install uv
href: install/uv.md
+ - name: Install with pipx
+ href: install/pipx.md
+ - name: One-time Usage (uvx)
+ href: install/one-time.md
+ - name: Enterprise / Air-Gapped
+ href: install/air-gapped.md
# Reference
- name: Reference
@@ -44,7 +50,10 @@
# Community
- name: Community
+ href: community/overview.md
items:
+ - name: Overview
+ href: community/overview.md
- name: Extensions
href: community/extensions.md
- name: Presets