From c5fd5eb84f8b7cc79bdc9e5c485c1cce8685002e Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:30:13 -0500 Subject: [PATCH 1/2] docs: streamline README onboarding and process guides Focus Get started on initial setup, preserve installation and upgrade details in their guides, and clarify each process example. Connect customization guidance to the capability inventory and replace the old video overview with Open Source Friday coverage. Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.ja.md | 2 +- README.ko.md | 3 +- README.md | 114 ++++++++++++++++++++--------------- README.zh-CN.md | 2 +- docs/guides/customization.md | 13 ++++ docs/install/pypi.md | 6 ++ docs/installation.md | 6 ++ docs/quickstart.md | 8 --- docs/upgrade.md | 4 ++ 9 files changed, 96 insertions(+), 62 deletions(-) diff --git a/README.ja.md b/README.ja.md index c9b16a5617..dcefab4d04 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 65f32c8fdf..c83658e705 100644 --- a/README.ko.md +++ b/README.ko.md @@ -170,14 +170,13 @@ 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.md b/README.md index 68267b5b55..3f50156526 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`. - -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. ## 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) @@ -212,16 +222,20 @@ Use project-local overrides for one-off template changes. - ## 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

diff --git a/README.zh-CN.md b/README.zh-CN.md index 79809f2ae7..35bdc34194 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) diff --git a/docs/guides/customization.md b/docs/guides/customization.md index 2edf6971bb..297143731f 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 6f36df0a54..57cf036bbe 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -20,6 +20,12 @@ pipx install specify-cli pip install specify-cli ``` +If Spec Kit is already installed, `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, run `uv tool install --force specify-cli` before `specify init`. +See [Upgrade](#upgrade) below for the commands for each package manager. + ### 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 ba61ab9452..3abd5919a0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -79,6 +79,12 @@ specify init --integration pi specify init --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 692d725a55..b477655c0d 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 4ceaa30d07..45e664c0a4 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: From 1d17b197b484adb2013caa8688ba5e8873e5ff52 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:52:14 -0500 Subject: [PATCH 2/2] docs: preserve original installer in PyPI upgrade guidance Scope repeated-install behavior to uv and direct uv, pipx, and pip users to upgrade through their original tool to avoid duplicate specify installations. Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/install/pypi.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/install/pypi.md b/docs/install/pypi.md index 57cf036bbe..e829b34156 100644 --- a/docs/install/pypi.md +++ b/docs/install/pypi.md @@ -20,11 +20,13 @@ pipx install specify-cli pip install specify-cli ``` -If Spec Kit is already installed, `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, run `uv tool install --force specify-cli` before `specify init`. -See [Upgrade](#upgrade) below for the commands for each package manager. +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