diff --git a/EOF b/EOF deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/README.md b/README.md index b0a474888b..6128ff8f24 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/spec-kit.git@vX.Y.Z - -# 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/spec-kit.git@vX.Y.Z -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 - -# 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/spec-kit.git@vX.Y.Z -# pipx users: pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z -``` +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/spec-kit.git@vX.Y.Z specify init - -# Or initialize in existing project -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --integration copilot -# or -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z 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 0000000000..99804be3c3 --- /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 dba3b2c55e..e44bebd246 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 -91 community extensions (50+ authors), 18 presets, and growing — including entirely different SDD processes: +91 community extensions (50+ authors), 18 presets, 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. - Browse community presets → @@ -124,9 +124,9 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a Reference Core commands, integrations, extensions, presets, and workflows - + Community - Presets, walkthroughs, and friend projects + Extensions, presets, walkthroughs, and friend projects Development diff --git a/docs/install/air-gapped.md b/docs/install/air-gapped.md new file mode 100644 index 0000000000..bf2a46380e --- /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 0000000000..134cb0b11d --- /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 + +# Or target a specific release (replace vX.Y.Z with a tag from Releases) +uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init + +# 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 0000000000..68c55bd9cf --- /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/spec-kit.git@vX.Y.Z + +# 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/spec-kit.git@vX.Y.Z +``` + +## 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 86ad35559f..06f5de471f 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/spec-kit.git@vX.Y.Z specify init - -# Or install latest from main (may include unreleased changes) -uvx --from git+https://github.com/github/spec-kit.git specify init +uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` -> [!NOTE] -> For a persistent installation, `pipx` works equally well: -> ```bash -> pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z -> ``` -> 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/spec-kit.git@vX.Y.Z specify init . -# or use the --here flag -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here +specify init --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/spec-kit.git@vX.Y.Z specify init --integration claude -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration gemini -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration copilot -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration codebuddy -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration pi +specify init --integration claude +specify init --integration gemini +specify init --integration copilot +specify init --integration codebuddy +specify init --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/spec-kit.git@vX.Y.Z specify init --script sh -uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --script ps +specify init --script sh +specify init --script ps ``` ### Ignore Agent Tools Check @@ -78,7 +75,7 @@ uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --integration claude --ignore-agent-tools +specify init --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 d64d3b89da..ce91339a1b 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