💫 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.mdindex 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.mdindex 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.mdindex 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, andthe 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.```bashuv tool install specify-cli@@ -80,41 +82,32 @@ specify init my-project --integration copilotcd 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:```bashspecify 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:```bashspecify 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.mdindex 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.mdindex 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 capabilitiesExtensions expand **what Spec Kit can do** through commands, templates, scripts,diff --git a/docs/install/pypi.md b/docs/install/pypi.mdindex 6f36df0a5..e829b3415 100644--- a/docs/install/pypi.md+++ b/docs/install/pypi.md@@ -20,6 +20,14 @@ pipx install specify-clipip 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 releasePin 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.mdindex ba61ab945..3abd5919a 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -79,6 +79,12 @@ specify init <project_name> --integration pispecify 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.mdindex 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.--[](https://www.youtube.com/watch?v=a9eR1xsfvHg)diff --git a/docs/upgrade.md b/docs/upgrade.mdindex 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: