Skip to content

💫 Toolkit to help you get started with SDD or any other process!

docs: streamline README onboarding and process guides (#5029)

Manfred Riemf68ffcab37a2
diff --git a/README.ja.md b/README.ja.md
index c9b16a561..dcefab4d0 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -157,7 +157,7 @@ specify extension add assess
- [CLIリファレンス](https://github.github.io/spec-kit/reference/overview.html) と [プロセスコマンド](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
- [SDDの理念](https://github.github.io/spec-kit/concepts/sdd.html)、[完全な方法論](./spec-driven.md)、[既存の仕様の進化](https://github.github.io/spec-kit/guides/evolving-specs.html)
-- [紹介動画](https://github.github.io/spec-kit/quickstart.html#video-overview) と [プロジェクトの歴史](https://github.github.io/spec-kit/history.html)
+- [プロジェクトの歴史](https://github.github.io/spec-kit/history.html)
- [Spec KitはSpec Kit自身をどう使っているか](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
## スター数の推移
diff --git a/README.ko.md b/README.ko.md
index 65f32c8fd..c83658e70 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -170,14 +170,13 @@ specify extension add assess
<a id="-core-philosophy"></a>
<a id="-development-phases"></a>
<a id="-experimental-goals"></a>
-<a id="-video-overview"></a>
<a id="-does-spec-kit-use-spec-kit"></a>
## 문서
- [CLI 레퍼런스](https://github.github.io/spec-kit/reference/overview.html)와 [프로세스 명령어](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
- [SDD 철학](https://github.github.io/spec-kit/concepts/sdd.html), [전체 방법론](./spec-driven.md), [기존 스펙 발전시키기](https://github.github.io/spec-kit/guides/evolving-specs.html)
-- [소개 영상](https://github.github.io/spec-kit/quickstart.html#video-overview)과 [프로젝트 연혁](https://github.github.io/spec-kit/history.html)
+- [프로젝트 연혁](https://github.github.io/spec-kit/history.html)
- [Spec Kit이 Spec Kit을 쓰는 방법](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
## 스타 추이
diff --git a/README.md b/README.md
index 68267b5b5..3f5015652 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@ process, customize it, or bring your own.
| Decide whether an idea deserves investment | [Idea assessment](#idea-assessment) | An evidence-backed go, clarify, or stop decision |
| Adopt or create a different process | [Your own process](#capabilities) | A process adapted or assembled from reusable primitives |
-These are **independent entry points**, not mandatory phases. SDD ships in core;
+These are independent entry points, not mandatory phases. SDD ships in core;
bug fixing and assessment are bundled extensions you install when needed, and
the primitives below let you adopt or create other processes.
@@ -70,9 +70,11 @@ community source code before installing or running it.
## Get started
-You need **Python 3.11+**, **[uv](https://github.github.io/spec-kit/install/uv.html)**,
+You need Python 3.11+, [uv](https://github.github.io/spec-kit/install/uv.html),
and a supported AI coding agent on Linux, macOS, or Windows.
-For **CLI setup only**, run this in your terminal to install Spec Kit and create a project:
+
+Run these commands in your terminal to install Spec Kit and create a project.
+This example uses GitHub Copilot.
```bash
uv tool install specify-cli
@@ -80,41 +82,32 @@ specify init my-project --integration copilot
cd my-project
```
-If Spec Kit is already installed, `uv tool install specify-cli` keeps the installed
-version. Compare the version shown by `specify version` with the
-[latest version on PyPI](https://pypi.org/project/specify-cli/), and if it's older,
-run `uv tool install --force specify-cli` before `specify init`.
-
<a id="-supported-ai-coding-agent-integrations"></a>
-The examples use **GitHub Copilot's default skills mode**. Replace `copilot` with
-your [integration key](https://github.github.io/spec-kit/reference/integrations.html)
-to use another supported agent.
+After installing the Specify CLI and creating your project, launch your coding
+agent in the project directory, then choose a process below.
-Already have code? Follow the
-[existing-project guide](https://github.github.io/spec-kit/guides/existing-projects.html).
-For pinned releases, other installers, CI, or troubleshooting, see
-[Installation](https://github.github.io/spec-kit/installation.html).
-To update an existing installation, see [Upgrade](https://github.github.io/spec-kit/upgrade.html).
+For other setups:
-Now **launch your coding agent in the project directory** and choose a process
-below. Invoke each `/speckit-*` **skill in your agent's chat**, one at a time,
-and review the result before continuing. These are agent skills, not terminal
-commands. Other agents and modes may use
-[different invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation).
+- [Installation](https://github.github.io/spec-kit/installation.html) for pinned releases, other installers, CI, and troubleshooting.
+- [Existing projects](https://github.github.io/spec-kit/guides/existing-projects.html) to start with code you already have.
+- [Other agents](https://github.github.io/spec-kit/reference/integrations.html) for integration keys and [invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation).
+- [Upgrade](https://github.github.io/spec-kit/upgrade.html) to update an existing installation.
<a id="-what-is-spec-driven-development"></a>
<a id="sdd-quickstart"></a>
## Spec-Driven Development
-Define **what and why** before deciding **how** to build it. SDD turns your
-requirements into a specification, a technical plan, and actionable tasks,
-then guides implementation against those artifacts.
+Define what to build and why, then turn the specification into a plan, tasks,
+and working code.
-**Constitution once per project; specify → plan → tasks → implement → converge per feature.**
+The minimal flow is shown below. Create a constitution once per project and
+repeat the remaining steps for each feature. Run these skills in your agent's
+chat, not your terminal, one at a time, reviewing each result before continuing.
-Invoke these skills in your agent's chat:
+This example uses GitHub Copilot's default skills syntax. For another agent,
+use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation).
```text
/speckit-constitution Create principles focused on code quality, testing, and maintainability.
@@ -125,9 +118,8 @@ Invoke these skills in your agent's chat:
/speckit-converge
```
-Repeat **implement → converge** until convergence reports **Converged**.
-Add clarification, checklists, and consistency analysis when you need extra
-quality gates.
+Repeat implement and converge until convergence reports `Converged`.
+For clarification, checklists, and consistency analysis, see the SDD walkthrough.
[SDD walkthrough](https://github.github.io/spec-kit/quickstart.html) ·
[Command reference](https://github.github.io/spec-kit/reference/agentic-sdd.html)
@@ -137,16 +129,20 @@ quality gates.
## Bug fixing
-Keep diagnosis, repair, and verification separate so the agent fixes the assessed
-cause and checks the original symptom. No SDD feature workflow is required first.
+Assess the cause, fix the bug, and verify the original symptom is resolved.
+No SDD feature workflow is required first.
-**CLI setup (terminal):** install the opt-in extension from the project directory:
+Install the bug-fixing extension in your terminal, from the project directory:
```bash
specify extension add bug
```
-Then invoke the **assess → fix → test** skills in your agent's chat:
+Run these skills in your agent's chat, not your terminal, one at a time,
+reviewing each result before continuing.
+
+This example uses GitHub Copilot's default skills syntax. For another agent,
+use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation).
```text
/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash
@@ -154,8 +150,8 @@ Then invoke the **assess → fix → test** skills in your agent's chat:
/speckit-bug-test slug=login-crash
```
-The reports live in `.specify/bugs/login-crash/`. Review the final verdict:
-`verified`, `partial`, or `failed`. Missing verification is not a successful fix.
+Review the reports in `.specify/bugs/login-crash/`. The final verdict is
+`verified`, `partial`, or `failed`; only `verified` confirms a successful fix.
[Bug-fixing walkthrough](https://github.github.io/spec-kit/guides/bugfix.html) ·
[Command reference](https://github.github.io/spec-kit/reference/agentic-bugfix.html)
@@ -165,16 +161,20 @@ The reports live in `.specify/bugs/login-crash/`. Review the final verdict:
## Idea assessment
-Gather evidence before committing to an idea, whether or not it becomes software.
-This standalone process works even in a project with no source code.
+Gather evidence to decide whether an idea is worth pursuing.
+No source code or SDD feature workflow is required.
-**CLI setup (terminal):** install the opt-in extension from the project directory:
+Install the assessment extension in your terminal, from the project directory:
```bash
specify extension add assess
```
-Then invoke the **intake → research → define → shape → decide** skills in your agent's chat:
+Run these skills in your agent's chat, not your terminal, one at a time,
+reviewing each result before continuing.
+
+This example uses GitHub Copilot's default skills syntax. For another agent,
+use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation).
```text
/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode
@@ -184,11 +184,13 @@ Then invoke the **intake → research → define → shape → decide** skills i
/speckit-assess-decide slug=offline-mode
```
-The artifacts live in `.specify/assessments/offline-mode/`, ending in a
-**go / needs-clarification / kill** decision. Resolve unknowns by refining the
-existing Markdown artifacts directly or with the agent, rather than regenerating
-whole stages. A `go` decision can be handed to `/speckit-specify` if you choose
-to build it; stopping with a documented reason is also a useful result.
+Review the artifacts in `.specify/assessments/offline-mode/` and the final
+decision: `go`, `needs-clarification`, or `kill`. Resolve unknowns by editing the
+existing Markdown artifacts, directly or with your agent, rather than rerunning
+whole stages. If you choose to build a software idea with a `go` decision,
+establish a project constitution if needed, then pass the handoff summary from
+`decision.md` to `/speckit-specify`. Stopping with a documented reason is also a
+useful outcome.
[Assessment walkthrough](https://github.github.io/spec-kit/guides/assessment.html) ·
[Command reference](https://github.github.io/spec-kit/reference/agentic-assessment.html)
@@ -199,12 +201,20 @@ to build it; stopping with a documented reason is also a useful result.
## Customize or bring your own process
-**Extensions** add capabilities, **presets** adapt existing behavior,
-**workflows** automate steps, and **bundles** package a role-based setup.
-Use project-local overrides for one-off template changes.
+Customize Spec-Driven Development, bug fixing, or idea assessment to fit your
+team's standards. Or bring your own process without adopting any of them.
+Combine the [capabilities above](#capabilities) to match your goal:
+
+- Adapt an existing process with a preset, such as requiring regulatory traceability in plans. Use a project-local override for a one-off template change.
+- Bring your own process by adding its commands through an extension and exposing them to your coding agent through an integration.
+- Automate commands and checks in a workflow. Use overlays to adapt an installed workflow without forking it, or add custom workflow steps when the built-in types are not enough.
+- Share a reusable setup by packaging its extensions, presets, workflows, and workflow steps in a bundle.
+
+Start with the smallest change that meets your needs; you do not have to replace
+the whole process.
[Customization guide](https://github.github.io/spec-kit/guides/customization.html) ·
-[Community extensions, presets, bundles, and walkthroughs](https://github.github.io/spec-kit/community/overview.html)
+[Community components and walkthroughs](https://github.github.io/spec-kit/community/overview.html)
<a id="-specify-cli-reference"></a>
<a id="available-slash-commands"></a>
@@ -212,16 +222,20 @@ Use project-local overrides for one-off template changes.
<a id="-core-philosophy"></a>
<a id="-development-phases"></a>
<a id="-experimental-goals"></a>
-<a id="-video-overview"></a>
<a id="-does-spec-kit-use-spec-kit"></a>
## Documentation
- [CLI reference](https://github.github.io/spec-kit/reference/overview.html) and [process commands](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
- [SDD philosophy](https://github.github.io/spec-kit/concepts/sdd.html), [full methodology](./spec-driven.md), and [evolving existing specs](https://github.github.io/spec-kit/guides/evolving-specs.html)
-- [Video overview](https://github.github.io/spec-kit/quickstart.html#video-overview) and [project history](https://github.github.io/spec-kit/history.html)
+- [Project history](https://github.github.io/spec-kit/history.html)
- [How Spec Kit uses Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
+## In the news
+
+- [Open Source Friday: Spec Kit Part 2](https://www.youtube.com/watch?v=8hHCpNVLhmI) (October 16, 2026) — Manfred Riem and Nicole Haugen discuss Spec Kit 1.0 and the expanded toolkit.
+- [Open Source Friday with Spec Kit](https://www.youtube.com/watch?v=2IArMAhkJcE) (May 8, 2026) — An introduction and SDD demonstration with Manfred Riem.
+
## Star history
<p align="center">
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 79809f2ae..35bdc3419 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -177,7 +177,7 @@ specify extension add assess
- [CLI 参考](https://github.github.io/spec-kit/reference/overview.html)与[流程命令](https://github.github.io/spec-kit/reference/agentic-sdd.html#command-overview)
- [SDD 理念](https://github.github.io/spec-kit/concepts/sdd.html)、[完整方法论](./spec-driven.md)与[现有规范演进](https://github.github.io/spec-kit/guides/evolving-specs.html)
-- [视频概览](https://github.github.io/spec-kit/quickstart.html#video-overview)与[项目历史](https://github.github.io/spec-kit/history.html)
+- [项目历史](https://github.github.io/spec-kit/history.html)
- [Spec Kit 如何使用 Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit)
<a id="-支持"></a>
diff --git a/docs/guides/customization.md b/docs/guides/customization.md
index 2edf6971b..297143731 100644
--- a/docs/guides/customization.md
+++ b/docs/guides/customization.md
@@ -8,6 +8,7 @@ organization, or bring a different process entirely.
| Goal | Use |
| --- | --- |
+| Connect Spec Kit to a coding agent or adapt its command/skill delivery | Integration |
| Add a new command, capability, or process | Extension |
| Integrate an external tool or service | Extension |
| Change the format or terminology of specs, plans, or tasks | Preset |
@@ -15,8 +16,20 @@ organization, or bring a different process entirely.
| Ship reusable domain-specific templates | Presets for overrides; extensions for templates accompanying new commands |
| Make a one-off template adjustment in a single project | Project-local override |
| Automate a multi-step process | Workflow |
+| Add a custom executable step type for workflows | Workflow step package |
| Provision a complete role-based setup in one operation | Bundle |
+Integrations determine how commands and skills are delivered to your coding
+agent; they are distinct from extensions that connect to external tools or
+services. See the [integration reference](../reference/integrations.md) for
+supported agents, installation, and scaffolding a new adapter.
+
+Workflow step packages extend the step types available to workflows. See
+[custom step packages](../reference/workflows.md#custom-step-packages) for
+installation and execution, and
+[community workflow steps](../community/workflow-steps.md) for discovery and
+contribution guidance. Review executable packages before installing or using them.
+
## Extensions: add capabilities
Extensions expand **what Spec Kit can do** through commands, templates, scripts,
diff --git a/docs/install/pypi.md b/docs/install/pypi.md
index 6f36df0a5..e829b3415 100644
--- a/docs/install/pypi.md
+++ b/docs/install/pypi.md
@@ -20,6 +20,14 @@ pipx install specify-cli
pip install specify-cli
```
+If you installed Spec Kit with uv, repeating `uv tool install specify-cli`
+keeps the installed version; it does not upgrade it. Compare the version shown
+by `specify version` with the [latest version on PyPI](https://pypi.org/project/specify-cli/).
+If it is older, follow [Upgrade](#upgrade) below using the same tool you used for
+the original installation (uv, pipx, or pip) before running `specify init`.
+Do not switch installers just to upgrade: that can create a second installation
+while the old `specify` remains first on `PATH`.
+
### Install a specific release
Pin an exact version for reproducible installs (check [PyPI](https://pypi.org/project/specify-cli/#history) or [Releases](https://github.com/github/spec-kit/releases) for available versions):
diff --git a/docs/installation.md b/docs/installation.md
index ba61ab945..3abd5919a 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -79,6 +79,12 @@ specify init <project_name> --integration pi
specify init <project_name> --integration omp
```
+The README examples use GitHub Copilot's default skills mode. To use another
+supported agent, replace `copilot` with its
+[integration key](reference/integrations.md). See
+[Command Invocation](reference/integrations.md#command-invocation) for the
+syntax used by each agent and mode.
+
### Specify Script Type (Shell, PowerShell, or Python)
Automation scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 692d725a5..b477655c0 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -179,11 +179,3 @@ Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appe
- Compare the [core templates](https://github.com/github/spec-kit/tree/main/templates) with
[community walkthroughs](community/walkthroughs.md) to see how Spec-Driven Development is used in real projects
- Explore the [source code on GitHub](https://github.com/github/spec-kit)
-
-## Video Overview
-
-For a visual introduction, watch the
-[Spec Kit video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg).
-Use the commands in this guide for the current workflow and invocation syntax.
-
-[![Spec Kit video overview](https://raw.githubusercontent.com/github/spec-kit/main/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg)
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 4ceaa30d0..45e664c0a 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -21,6 +21,10 @@
The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
+If you installed from PyPI and want to keep that install route, follow the
+[PyPI upgrade instructions](install/pypi.md#upgrade). Repeating
+`uv tool install specify-cli` does not upgrade an existing installation.
+
### Recommended: `specify self upgrade`
The CLI ships with two self-management commands that handle the common case automatically: