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..e829b34156 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 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: