π« 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/EOFdeleted file mode 100644index e69de29bb..000000000diff --git a/README.md b/README.mdindex 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 principlesLaunch 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 specUse 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 planUse 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 tasksUse **`/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 implementationUse **`/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+## SupportFor 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 IntegrationInteractive 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 iniYou 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 <projeIf 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.ymlindex d64d3b89d..ce91339a1 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -13,6 +13,12 @@href: upgrade.md- name: Install uvhref: 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.mditems:+ - name: Overview+ href: community/overview.md- name: Extensionshref: community/extensions.md- name: Presets