From 3176ea1e6d014322d100fa0b0aa0bb6e402d7007 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 14 Sep 2026 16:49:55 -0500 Subject: [PATCH 1/2] docs: simplify README around three processes Use one shared setup and independent SDD, bug-fixing, and idea-assessment quickstarts. Consolidate detailed content into the docs and contributor guide, add missing process guides, align Chinese documentation, and preserve navigation without widening the site header. Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 23 +- README.md | 530 ++++++--------------------- README.zh-CN.md | 403 ++++++-------------- docs/README.md | 6 +- docs/community/overview.md | 12 + docs/guides/assessment.md | 114 ++++++ docs/guides/bugfix.md | 81 ++++ docs/guides/customization.md | 105 ++++++ docs/guides/existing-projects.md | 8 +- docs/history.md | 13 + docs/index.md | 45 ++- docs/installation.md | 30 ++ docs/local-development.md | 4 + docs/quickstart.md | 120 ++++-- docs/reference/agentic-assessment.md | 102 ++++++ docs/reference/agentic-bugfix.md | 7 +- docs/reference/agentic-sdd.md | 54 ++- docs/reference/bundles.md | 12 + docs/reference/integrations.md | 18 + docs/reference/overview.md | 16 +- docs/toc.yml | 10 +- 21 files changed, 956 insertions(+), 757 deletions(-) create mode 100644 docs/guides/assessment.md create mode 100644 docs/guides/bugfix.md create mode 100644 docs/guides/customization.md create mode 100644 docs/reference/agentic-assessment.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96818dba35..4f0d0123e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ These are one time installations required to be able to test your changes locall 1. Install [Python 3.11+](https://www.python.org/downloads/) 1. Install [uv](https://docs.astral.sh/uv/) for package management 1. Install [Git](https://git-scm.com/downloads) -1. Have an [AI coding agent available](README.md#-supported-ai-coding-agent-integrations) +1. Have an [AI coding agent available](https://github.github.io/spec-kit/reference/integrations.html)
💡 Hint if you are using VSCode or GitHub Codespaces as your IDE @@ -151,6 +151,27 @@ Including the issue or PR number makes branches traceable — especially useful ## Development workflow +### Does Spec Kit use Spec Kit? + +Yes — we dogfood Spec Kit while developing Spec Kit, especially for substantial +features and changes to the development workflow. Contributors are asked to test +relevant changes through the Spec-Driven Development commands. The +[feature assessment workflow](https://github.com/github/spec-kit/blob/main/.github/workflows/feature-assess.md) +is currently the automated dogfooding path: its setup uses the CLI from the +current checkout to initialize Copilot and install the `assess` extension, after +which Copilot follows the generated assessment skills against feature requests. +The other agentic workflows currently operate independently of the Specify CLI. + +This does not mean every change goes through the full workflow. Small fixes can +use the normal issue, pull request, review, and test process. Dogfooding +scaffolding and artifacts under `.github/agents/`, `.github/prompts/`, +`.github/copilot-instructions.md`, `.grok/`, `.specify/`, and `specs/` are +intentionally gitignored. The automated assessment workflow is ephemeral and +neither commits nor pushes its generated Copilot skills, so its output does not +enter repository history. + +### Workflow expectations + When working on spec-kit: 1. Test changes with the `specify` CLI commands (`/speckit.specify`, `/speckit.plan`, `/speckit.tasks`) in your coding agent of choice diff --git a/README.md b/README.md index a4e7fdafb9..3ed5287a44 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,9 @@
Spec Kit Logo

🌱 Spec Kit

-

Define what to build before building it — with any AI coding agent.

+

Build with a spec, fix a bug, or assess an idea — with your coding agent.

-

- An open source toolkit for building high-quality software with any AI coding agent — a ready-to-use spec-driven process (or bring your own), endlessly extensible, community-driven, and built for your whole organization. -

-

Latest Release GitHub stars @@ -20,473 +16,177 @@ 简体中文

-> [!NOTE] -> **One year of Spec Kit — and 1.0.0** -> -> One year after the first commit, Spec Kit has reached [1.0.0](https://github.com/github/spec-kit/releases/tag/v1.0.0) — not because the work is finished or its shape is frozen, but because the project has grown into something coherent, useful, and shaped by far more people than those who started it. -> -> The lead maintainer's personal anniversary post, [*Spec Kit Turns One — and Ships 1.0.0*](https://www.manorrock.com/blog/2026/08/21/spec_kit_turns_one.html), defines what 1.0.0 actually means for the project: **it is now just a number**. As agents make adapting to change dramatically cheaper, the value moves from stability to adaptability. -> -> To everyone who has used Spec Kit, challenged its assumptions, reported a problem, contributed code or documentation, created an extension or preset, shared an idea, or helped someone else get started: **thank you**. This milestone belongs to the community that carried the project through its first year and continues to shape where it goes next. - ---- - -## Table of Contents - -- [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development) -- [🐞 Bug Fixing with Spec Kit](#-bug-fixing-with-spec-kit) -- [💡 Assessing Ideas with Spec Kit](#-assessing-ideas-with-spec-kit) -- [⚡ Get Started](#-get-started) -- [📽️ Video Overview](#️-video-overview) -- [🌍 Community](#-community) -- [🤖 Supported AI Coding Agent Integrations](#-supported-ai-coding-agent-integrations) -- [🔧 Specify CLI Reference](#-specify-cli-reference) -- [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets) -- [📦 Bundles: Role-Based Setups](#-bundles-role-based-setups) -- [📚 Core Philosophy](#-core-philosophy) -- [🪞 Does Spec Kit Use Spec Kit?](#-does-spec-kit-use-spec-kit) -- [🌟 Development Phases](#-development-phases) -- [🎯 Experimental Goals](#-experimental-goals) -- [🔧 Prerequisites](#-prerequisites) -- [📖 Learn More](#-learn-more) -- [💬 Support](#-support) -- [🙏 Acknowledgements](#-acknowledgements) -- [📄 License](#-license) - -## 🤔 What is Spec-Driven Development? - -Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them. - -### SDD Quickstart - -Replace `vX.Y.Z` with the [latest release tag](https://github.com/github/spec-kit/releases), keeping the leading `v`. - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z -specify init my-project --integration copilot -cd my-project -``` - -Launch your coding agent in the project directory, then: - -0. **Establish** your project principles once (`/speckit-constitution`). This is a one-time step per project. -1. **Specify** what you want to build (`/speckit-specify`). -2. **Plan** how you will build it (`/speckit-plan`). -3. **Break down** the plan into actionable tasks (`/speckit-tasks`). -4. **Implement** the tasks (`/speckit-implement`). -5. **Converge** the implementation against the spec, plan, and tasks (`/speckit-converge`). - -> [!NOTE] -> Repeat steps 4 and 5 until `/speckit-converge` reports **Converged**. - -## 🐞 Bug Fixing with Spec Kit - -Bug fixes are risky when an agent jumps straight from a report to a patch without validating the diagnosis or confirming that the fix resolves the original symptom. The bundled, opt-in bug extension provides a repeatable **assess → fix → test** workflow that keeps each fix scoped, evidence-based, and documented from root cause through verification. - -### Bug Fix Quickstart - -Replace `vX.Y.Z` with the [latest release tag](https://github.com/github/spec-kit/releases), keeping the leading `v`. - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z -specify init my-project --integration copilot -cd my-project -specify extension add bug -``` +Spec Kit is an open source toolkit that gives AI coding agents structured +processes, reusable templates, and documented outcomes. Start with one of the +three processes below, customize it, or bring your own. -Launch your coding agent in the project directory, then: +## Choose your process -1. **Assess** the bug (`/speckit-bug-assess "" slug=login-crash`). -2. **Fix** the assessed cause (`/speckit-bug-fix slug=login-crash`). -3. **Test** the fix (`/speckit-bug-test slug=login-crash`). +| What you need | Process | Outcome | +| --- | --- | --- | +| Build a feature or application | [Spec-Driven Development](#spec-driven-development) | A specification carried through planning, implementation, and convergence | +| Diagnose and repair broken behavior | [Bug fixing](#bug-fixing) | An assessed cause, scoped fix, and recorded verification | +| Decide whether an idea deserves investment | [Idea assessment](#idea-assessment) | An evidence-backed go, clarify, or stop decision | -## 💡 Assessing Ideas with Spec Kit +These are **independent entry points**, not three mandatory phases. SDD ships in +core; bug fixing and assessment are bundled extensions you install when needed. -Good ideas deserve evidence before commitment, whether or not they become software. The bundled, opt-in assess extension turns a raw idea into a documented **go / needs-clarification / kill** decision through an independent **intake → research → define → shape → decide** workflow. + + -### Idea Assessment Quickstart +## Get started -Replace `vX.Y.Z` with the [latest release tag](https://github.com/github/spec-kit/releases), keeping the leading `v`. - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z -specify init my-project --integration copilot -cd my-project -specify extension add assess -``` - -Launch your coding agent in the project directory, then: - -1. **Intake** the idea (`/speckit-assess-intake "" slug=offline-mode`). -2. **Research** supporting and opposing evidence (`/speckit-assess-research slug=offline-mode`). -3. **Define** the problem, goals, and success metrics (`/speckit-assess-define slug=offline-mode`). -4. **Shape** possible solutions and their trade-offs (`/speckit-assess-shape slug=offline-mode`). -5. **Decide** whether to proceed, clarify, or stop (`/speckit-assess-decide slug=offline-mode`). - -> [!NOTE] -> Idea assessment is standalone. If you choose to build an idea with a **go** decision, you can hand it off to `/speckit-specify`. - -## ⚡ Get Started - -### 1. Install Specify CLI - -Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md)). Replace `vX.Y.Z` with the latest release tag from [Releases](https://github.com/github/spec-kit/releases) — keep the leading `v` (for example, `v0.12.11`, not `0.12.11`): - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z -``` - -Prefer installing from PyPI? The `specify-cli` package is also published there: +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. +Run this in your **terminal** to install the CLI from PyPI and create a project: ```bash uv tool install specify-cli -``` - -See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting. - -### 2. Initialize a project - -```bash specify init my-project --integration copilot cd my-project ``` -For CI or AI agent harnesses (no keyboard, or a PTY that cannot send arrow keys), pass `--non-interactive` so init never hangs on a picker. Combine with `--force` when initializing into a non-empty directory: - -```bash -specify init my-project --non-interactive --ignore-agent-tools -specify init --here --force --non-interactive --integration claude -``` - -To check for updates or upgrade the installed CLI, use the self-management commands. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options. + -```bash -# Check whether a newer release is available (read-only — does not modify anything) -specify self check +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. -# Preview what would run, without actually upgrading -specify self upgrade --dry-run +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). -# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install) -specify self upgrade +Now **launch your coding agent in the project directory** and choose a process +below. Run each `/speckit-*` command separately **in the agent**, not in your +terminal, and review the result before continuing. Other agents and modes may +use [different command syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). -# Or pin a specific release tag (replace vX.Y.Z[suffix] with your desired release tag) -specify self upgrade --tag vX.Y.Z[suffix] -``` + + -Bare `specify self upgrade` executes immediately, matching the no-prompt behavior of commands like `pip install -U` and `npm update`. For `uv tool` installs, it runs `uv tool install specify-cli --force --from ` under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. `uvx` (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed). +## Spec-Driven Development -### 3. Establish project principles +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. -Launch your coding agent in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI and Command Code in skills mode use `$speckit-*` instead; GitHub Copilot CLI uses `/agents` to select the agent or address it directly in a prompt. +**Constitution once per project; specify → plan → tasks → implement → converge per feature.** -Use the **`/speckit.constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development. - -```bash -/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements +```text +/speckit-constitution Create principles focused on code quality, testing, and maintainability. +/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album. +/speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite. +/speckit-tasks +/speckit-implement +/speckit-converge ``` -### 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. - -```bash -/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. -``` +Repeat **implement → converge** until convergence reports **Converged**. +Add clarification, checklists, and consistency analysis when you need extra +quality gates. -### 5. Create a technical implementation plan +[SDD walkthrough](https://github.github.io/spec-kit/quickstart.html) · +[Command reference](https://github.github.io/spec-kit/reference/agentic-sdd.html) -Use the **`/speckit.plan`** command to provide your tech stack and architecture choices. + + -```bash -/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. -``` +## Bug fixing -### 6. Break down into tasks +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. -Use **`/speckit.tasks`** to create an actionable task list from your implementation plan. +Install the opt-in extension **in your terminal**, from the project directory: ```bash -/speckit.tasks +specify extension add bug ``` -### 7. Execute implementation - -Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan. +Then run **assess → fix → test** in your coding agent: -```bash -/speckit.implement +```text +/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash +/speckit-bug-fix slug=login-crash +/speckit-bug-test slug=login-crash ``` -For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md). - -## 📽️ Video Overview - -Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)! - -[![Spec Kit video header](https://raw.githubusercontent.com/github/spec-kit/main/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) - -## 🌍 Community +The reports live in `.specify/bugs/login-crash/`. Review the final verdict: +`verified`, `partial`, or `failed`. Missing verification is not a successful fix. -Explore community-contributed resources on the [Spec Kit docs site](https://github.github.io/spec-kit/): +[Bug-fixing walkthrough](https://github.github.io/spec-kit/guides/bugfix.html) · +[Command reference](https://github.github.io/spec-kit/reference/agentic-bugfix.html) -- [Extensions](https://github.github.io/spec-kit/community/extensions.html) — commands, hooks, and capabilities -- [Presets](https://github.github.io/spec-kit/community/presets.html) — template and terminology overrides -- [Bundles](https://github.github.io/spec-kit/community/bundles.html) — role and team stacks composed from existing components -- [Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) — end-to-end SDD scenarios -- [Friends](https://github.github.io/spec-kit/community/friends.html) — projects that extend or build on Spec Kit + + -> [!NOTE] -> Community contributions are independently created and maintained by their respective authors. Review source code before installation and use at your own discretion. +## Idea assessment -Want to contribute? See the [Extension Publishing Guide](extensions/EXTENSION-PUBLISHING-GUIDE.md), the [Presets Publishing Guide](presets/PUBLISHING.md), or the [Community Bundles guide](docs/community/bundles.md). +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. -## 🤖 Supported AI Coding Agent Integrations - -Spec Kit works with 30+ AI coding agents — both CLI tools and IDE-based assistants. See the full list with notes and usage details in the [Supported AI Coding Agent Integrations](https://github.github.io/spec-kit/reference/integrations.html) guide. - -Run `specify integration list` to see all available integrations in your installed version. - -## Available Slash Commands - -After running `specify init`, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing `--integration --integration-options="--skills"` installs agent skills instead of slash-command prompt files. - -### Core Commands - -Essential commands for the Spec-Driven Development workflow: - -| Command | Agent Skill | Description | -| ------------------------ | ---------------------- | -------------------------------------------------------------------------- | -| `/speckit.constitution` | `speckit-constitution` | Create or update project governing principles and development guidelines | -| `/speckit.specify` | `speckit-specify` | Define what you want to build (requirements and user stories) | -| `/speckit.plan` | `speckit-plan` | Create technical implementation plans with your chosen tech stack | -| `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation | -| `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution | -| `/speckit.implement` | `speckit-implement` | Execute all tasks to build the feature according to the plan | -| `/speckit.converge` | `speckit-converge` | Assess the codebase against spec/plan/tasks and append remaining work as new tasks | - -### Optional Commands - -Additional commands for enhanced quality and validation: - -| Command | Agent Skill | Description | -| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `/speckit.clarify` | `speckit-clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | -| `/speckit.analyze` | `speckit-analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | -| `/speckit.checklist` | `speckit-checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | - -## 🔧 Specify CLI Reference - -For full command details, options, and examples, see the [CLI Reference](https://github.github.io/spec-kit/reference/overview.html). - -## 🧩 Making Spec Kit Your Own: Extensions & Presets - -Spec Kit can be tailored to your needs through two complementary systems — **extensions** and **presets** — plus project-local overrides for one-off adjustments: - -| Priority | Component Type | Location | -| -------: | ------------------------------------------------- | -------------------------------- | -| ⬆ 1 | Project-Local Overrides | `.specify/templates/overrides/` | -| 2 | Presets — Customize core & extensions | `.specify/presets/templates/` | -| 3 | Extensions — Add new capabilities | `.specify/extensions/templates/` | -| ⬇ 4 | Spec Kit Core — Built-in SDD commands & templates | `.specify/templates/` | - -- **Templates** are resolved at **runtime** — Spec Kit walks the stack top-down and uses the first match. -- Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset. -- **Extension/preset commands** are applied at **install time** — when you run `specify extension add` or `specify preset add`, command files are written into agent directories (e.g., `.claude/commands/`). -- If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically. -- If no overrides or customizations exist, Spec Kit uses its core defaults. - -### Extensions — Add New Capabilities - -Use **extensions** when you need functionality that goes beyond Spec Kit's core. Extensions introduce new commands and templates — for example, adding domain-specific workflows that are not covered by the built-in SDD commands, integrating with external tools, or adding entirely new development phases. They expand *what Spec Kit can do*. - -```bash -# Search available extensions -specify extension search - -# Install an extension -specify extension add -``` - -For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics. - -See the [Extensions reference](https://github.github.io/spec-kit/reference/extensions.html) for the full command guide. Browse the [community extensions](https://github.github.io/spec-kit/community/extensions.html) for what's available. - -### Presets — Customize Existing Workflows - -Use **presets** when you want to change *how* Spec Kit works without adding new capabilities. Presets override the templates and commands that ship with the core *and* with installed extensions — for example, enforcing a compliance-oriented spec format, using domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions that Spec Kit and its extensions produce. - -```bash -# Search available presets -specify preset search - -# Install a preset -specify preset add -``` - -For example, presets could restructure spec templates to require regulatory traceability, adapt the workflow to fit the methodology you use (e.g., Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven design), add mandatory security review gates to plans, enforce test-first task ordering, or localize the entire workflow to a different language. The [pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) shows just how deep the customization can go. Multiple presets can be stacked with priority ordering. - -See the [Presets reference](https://github.github.io/spec-kit/reference/presets.html) for the full command guide, including resolution order and priority stacking. - -## 📦 Bundles: Role-Based Setups - -Extensions and presets are individual building blocks. A **bundle** packages a -curated set of them — extensions, presets, steps, and workflows — into a single, -versioned, role-oriented setup so a whole team persona (product manager, business -analyst, security researcher, developer, …) can be provisioned with one command. - -A bundle is described by a hand-written `bundle.yml` manifest. It pins each -component to a version and, optionally, targets a specific integration; a bundle -with no `integration` is **agnostic** and inherits whatever integration the -project already uses. +Install the opt-in extension **in your terminal**, from the project directory: ```bash -# Discover bundles in the active catalog stack -specify bundle search [] - -# Inspect the exact component set a bundle will add (equals what install does) -specify bundle info - -# Install a bundle's full component set in one operation -specify bundle install - -# See what's installed, then update or remove non-destructively -specify bundle list -specify bundle update # or --all -specify bundle remove # removes only this bundle's components +specify extension add assess ``` -Bundles resolve from a **priority-ordered catalog stack** (project > user > -built-in). Each source carries an install policy: `install-allowed` sources can -be installed from, while `discovery-only` sources are visible in `search`/`info` -but refuse installation. Manage the stack with `specify bundle catalog list|add|remove`. +Then run **intake → research → define → shape → decide** in your coding agent: -Authors validate and package bundles locally. Distribution is hosting the built -artifact and adding a catalog source; community bundle submissions use the -[Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) -issue template so required component catalogs and install evidence can be reviewed: - -```bash -specify bundle validate --path ./my-bundle # structural + reference checks -specify bundle build --path ./my-bundle # produce a versioned .zip artifact +```text +/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode +/speckit-assess-research slug=offline-mode +/speckit-assess-define slug=offline-mode +/speckit-assess-shape slug=offline-mode +/speckit-assess-decide slug=offline-mode ``` -Four ready-to-read example bundle manifests live under -[`examples/bundles/`](examples/bundles/) (product manager, business analyst, -security researcher, developer). These are bundle packaging examples, not -filled generated feature specs; for end-to-end community examples, see the -[community walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html). - -Key guarantees: `info` shows exactly what `install` adds (transparency); -installs are idempotent and confined to the project root; `remove` never touches -components another installed bundle still needs; and all consume/author commands -work **offline** against local or pinned sources. - -### When to Use Which - -| Goal | Use | -| --- | --- | -| Add a brand-new command or workflow | Extension | -| Customize the format of specs, plans, or tasks | Preset | -| Integrate an external tool or service | Extension | -| Enforce organizational or regulatory standards | Preset | -| Ship reusable domain-specific templates | Either — presets for template overrides, extensions for templates bundled with new commands | -| Provision a complete role-based setup in one command | Bundle | - -## 📚 Core Philosophy - -Spec-Driven Development is a structured process that emphasizes: - -- **Intent-driven development** where specifications define the "*what*" before the "*how*" -- **Rich specification creation** using guardrails and organizational principles -- **Multi-step refinement** rather than one-shot code generation from prompts -- **Heavy reliance** on advanced AI model capabilities for specification interpretation - -## 🪞 Does Spec Kit Use Spec Kit? - -Yes — we dogfood Spec Kit while developing Spec Kit, especially for substantial -features and changes to the development workflow. Contributors are asked to test -relevant changes through the Spec-Driven Development commands. The -[feature assessment workflow](./.github/workflows/feature-assess.md) is currently -the automated dogfooding path: its setup uses the CLI from the current checkout -to initialize Copilot and install the `assess` extension, after which Copilot -follows the generated assessment skills against feature requests. The other -agentic workflows currently operate independently of the Specify CLI. - -This does not mean every change goes through the full workflow. Small fixes can -use the normal issue, pull request, review, and test process. Dogfooding -scaffolding and artifacts under `.github/agents/`, `.github/prompts/`, -`.github/copilot-instructions.md`, `.grok/`, `.specify/`, and `specs/` are -intentionally gitignored. The automated assessment workflow is ephemeral and -neither commits nor pushes its generated Copilot skills, so its output does not -enter repository history. See the [contributor development -workflow](./CONTRIBUTING.md#development-workflow) for the validation expectations. - -## 🌟 Development Phases - -| Phase | Focus | Key Activities | -| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **0-to-1 Development** ("Greenfield") | Generate from scratch |
  • Start with high-level requirements
  • Generate specifications
  • Plan implementation steps
  • Build production-ready applications
| -| **Creative Exploration** | Parallel implementations |
  • Explore diverse solutions
  • Support multiple technology stacks & architectures
  • Experiment with UX patterns
| -| **Iterative Enhancement** ("Brownfield") | Brownfield modernization |
  • Add features iteratively
  • Modernize legacy systems
  • Adapt processes
| - -For existing projects, keep Spec Kit tooling updates separate from feature -artifact evolution: refresh managed project files when upgrading, and update -`specs/` artifacts when intended behavior changes. The -[Evolving Specs guide](./docs/guides/evolving-specs.md) describes the -recommended brownfield loop. - -## 🎯 Experimental Goals - -Our research and experimentation focus on: - -### Technology independence - -- Create applications using diverse technology stacks -- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks - -### Enterprise constraints - -- Demonstrate mission-critical application development -- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) -- Support enterprise design systems and compliance requirements - -### User-centric development - -- Build applications for different user cohorts and preferences -- Support various development approaches (from vibe-coding to AI-native development) - -### Creative & iterative processes +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. -- Validate the concept of parallel implementation exploration -- Provide robust iterative feature development workflows -- Extend processes to handle upgrades and modernization tasks +[Assessment walkthrough](https://github.github.io/spec-kit/guides/assessment.html) · +[Command reference](https://github.github.io/spec-kit/reference/agentic-assessment.html) -## 🔧 Prerequisites + + + -- **Linux/macOS/Windows** -- [Supported](#-supported-ai-coding-agent-integrations) AI coding agent. -- [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation -- [Python 3.11+](https://www.python.org/downloads/) -- [Git](https://git-scm.com/downloads) +## Customize or bring your own process -If you encounter issues with an agent, please open an issue so we can refine the integration. +**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. -## 📖 Learn More +[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) -- **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process -- **[Quick Start Guide](https://github.github.io/spec-kit/quickstart.html)** - Step-by-step implementation walkthrough + + + + + + + + ---- +## Documentation -## 💬 Support +- [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) +- [How Spec Kit uses Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit) -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. + -## 🙏 Acknowledgements +## Support and contributing -This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam). +[Report a bug or request a feature](https://github.com/github/spec-kit/issues/new) · +[Contributing guide](./CONTRIBUTING.md) · [Code of conduct](./CODE_OF_CONDUCT.md) -## 📄 License + -This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. +Spec Kit is [MIT licensed](./LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index b90809eee7..aa1519eda7 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,18 +1,14 @@
- Spec Kit Logo + Spec Kit 标志

🌱 Spec Kit

-

在动手编码之前，先定义要构建什么 —— 适配任意 AI 编码助手。

+

与你的编码助手一起，依据规范开发、修复缺陷，或评估想法。

- 一个开源工具套件，帮助你借助任意 AI 编码助手构建高质量软件 —— 内置开箱即用的规范驱动流程（也可自带流程），可无限扩展、由社区驱动，并为整个组织的协作而设计。 -

- -

- Latest Release + 最新版本 GitHub stars - License - Documentation + 许可证 + 文档

@@ -20,342 +16,173 @@ 简体中文

---- +Spec Kit 是一个开源工具套件，为 AI 编码助手提供结构化流程、可复用模板和有据可查的成果。 +你可以从以下三种流程中任选一种开始，按需定制，也可以引入自己的流程。 -## 目录 +## 选择你的流程 -- [🤔 什么是规范驱动开发？](#-什么是规范驱动开发) -- [⚡ 快速开始](#-快速开始) -- [📽️ 视频概览](#️-视频概览) -- [🌍 社区](#-社区) -- [🤖 支持的 AI 编码助手集成](#-支持的-ai-编码助手集成) -- [🔧 Specify CLI 参考](#-specify-cli-参考) -- [🧩 打造你自己的 Spec Kit：扩展与预设](#-打造你自己的-spec-kit扩展与预设) -- [📦 捆绑包：面向角色的一键配置](#-捆绑包面向角色的一键配置) -- [📚 核心理念](#-核心理念) -- [🌟 开发阶段](#-开发阶段) -- [🎯 实验目标](#-实验目标) -- [🔧 环境要求](#-环境要求) -- [📖 深入了解](#-深入了解) -- [💬 支持](#-支持) -- [🙏 致谢](#-致谢) -- [📄 许可证](#-许可证) +| 你的需求 | 流程 | 产出 | +| --- | --- | --- | +| 构建功能或应用 | [规范驱动开发](#规范驱动开发) | 从规范出发，完成规划、实现与收敛 | +| 排查并修复异常行为 | [缺陷修复](#缺陷修复) | 经评估的原因、范围明确的修复与验证记录 | +| 判断一个想法是否值得投入 | [想法评估](#想法评估) | 基于证据决定推进、澄清或停止 | -## 🤔 什么是规范驱动开发？ +这三种流程是**彼此独立的入口**，不是必须依次完成的三个阶段。 +SDD 内置于核心；缺陷修复和想法评估由随工具提供的扩展实现，需要时再安装。 -规范驱动开发（Spec-Driven Development）**颠覆了**传统软件开发的思路。几十年来，代码一直是核心 —— 规范只是编码这项"正事"开始前搭起、随后就被丢弃的脚手架。规范驱动开发改变了这一点：**规范本身变得可执行**，它不再只是引导实现，而是直接生成可运行的实现。 + + + + -## ⚡ 快速开始 +## 快速开始 -### 1. 安装 Specify CLI - -需要 **[uv](https://docs.astral.sh/uv/)**（[安装 uv](./docs/install/uv.md)）。将 `vX.Y.Z` 替换为 [Releases](https://github.com/github/spec-kit/releases) 中最新的发布标签 —— 记得保留开头的 `v`（例如 `v0.12.11`，而不是 `0.12.11`）： - -```bash -uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z -``` - -更倾向从 PyPI 安装？`specify-cli` 包同样发布在那里： +你需要 **Python 3.11+**、**[uv](https://github.github.io/spec-kit/install/uv.html)** +以及受支持的 AI 编码助手，可在 Linux、macOS 或 Windows 上使用。 +在**终端**中从 PyPI 安装 CLI 并创建项目： ```bash uv tool install specify-cli -``` - -其他安装方式、安装校验、升级以及故障排查，请参阅[安装指南](./docs/installation.md)。 - -### 2. 初始化项目 - -```bash specify init my-project --integration copilot cd my-project ``` -要检查更新或升级已安装的 CLI，可使用自管理命令。更详细的场景和自定义选项请参阅[升级指南](./docs/upgrade.md)。 +CLI 只需安装一次，项目只需初始化一次；以下三种流程共用这套准备步骤。 -```bash -# 检查是否有更新版本可用（只读操作 —— 不会修改任何内容） -specify self check + -# 预览升级将执行的操作，但不实际升级 -specify self upgrade --dry-run +示例采用 **GitHub Copilot 默认的技能（skills）模式**。 +如需使用其他助手，将 `copilot` 替换为对应的 +[集成标识](https://github.github.io/spec-kit/reference/integrations.html)。 -# 就地升级到最新稳定版（自动识别 uv tool 与 pipx 安装方式） -specify self upgrade +已有代码？请参阅[现有项目指南](https://github.github.io/spec-kit/guides/existing-projects.html)。 +锁定版本、其他安装方式、CI 与故障排查见[安装指南](https://github.github.io/spec-kit/installation.html)； +更新已安装的 CLI 和项目文件见[升级指南](https://github.github.io/spec-kit/upgrade.html)。 -# 或锁定到指定的发布标签（将 vX.Y.Z[suffix] 替换为你想要的标签） -specify self upgrade --tag vX.Y.Z[suffix] -``` +现在，在**项目目录中启动编码助手**，选择以下一种流程。 +每条 `/speckit-*` 命令都应在**助手中逐条运行，而不是在终端中运行**，检查结果后再继续。 +其他助手或模式可能采用[不同的命令语法](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)。 -直接运行 `specify self upgrade` 会立即执行，与 `pip install -U`、`npm update` 等命令一样无需额外确认。对于 `uv tool` 安装的情况，它在底层会执行 `uv tool install specify-cli --force --from `，因此锁定的发布标签同样有效，包括 dev、alpha/beta/rc 或带构建元数据的后缀。`uvx`（临时运行）和源码检出会被自动识别，此时会给出针对具体路径的操作建议，而不会执行安装程序。可通过设置 `SPECIFY_UPGRADE_TIMEOUT_SECS` 来限制安装子进程的最长运行时间（默认无超时限制 —— 必要时用 `Ctrl+C` 中断）。 + + + + + + -### 3. 确立项目准则 +## 规范驱动开发 -在项目目录下启动你的编码助手。大多数助手将 spec-kit 暴露为 `/speckit.*` 斜杠命令；处于技能（skills）模式的 Codex CLI 则使用 `$speckit-*`；GitHub Copilot CLI 使用 `/agents` 来选择助手，或直接在提示词中指定它。 +先明确**做什么、为什么做**，再决定**怎么实现**。 +规范驱动开发（SDD）将需求转化为规范、技术方案和可执行任务，再依据这些制品指导实现。 -使用 **`/speckit.constitution`** 命令来创建项目的治理准则和开发指南，它们将指导后续所有开发工作。 +**每个项目先确立一次准则；每个功能依次完成：规范 → 方案 → 任务 → 实现 → 收敛。** -```bash -/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements +```text +/speckit-constitution Create principles focused on code quality, testing, and maintainability. +/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album. +/speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite. +/speckit-tasks +/speckit-implement +/speckit-converge ``` -### 4. 编写规范 +反复执行 **implement → converge**，直到收敛报告给出 **Converged**。 +需要额外的质量把关时，可加入需求澄清、检查清单和一致性分析。 -使用 **`/speckit.specify`** 命令描述你想构建什么。聚焦于**做什么**和**为什么做**，而不是技术栈。 +[SDD 实战指南](https://github.github.io/spec-kit/quickstart.html) · +[命令参考](https://github.github.io/spec-kit/reference/agentic-sdd.html) -```bash -/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. -``` - -### 5. 制定技术实现方案 - -使用 **`/speckit.plan`** 命令提供你的技术栈和架构选择。 - -```bash -/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. -``` +## 缺陷修复 -### 6. 拆解为任务 +将诊断、修复和验证分开，让助手针对评估出的原因修复，并检查最初出现的症状。 +无需先走一遍 SDD 功能开发流程。 -使用 **`/speckit.tasks`** 从实现方案生成一份可执行的任务清单。 +在项目目录下的**终端**中安装这个可选扩展： ```bash -/speckit.tasks +specify extension add bug ``` -### 7. 执行实现 - -使用 **`/speckit.implement`** 执行所有任务，按方案构建你的功能。 +然后在编码助手中依次运行 **assess → fix → test**（评估 → 修复 → 测试）： -```bash -/speckit.implement +```text +/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash +/speckit-bug-fix slug=login-crash +/speckit-bug-test slug=login-crash ``` -详细的分步说明，请参阅我们的[完整指南](./spec-driven.md)。 - -## 📽️ 视频概览 - -想看看 Spec Kit 的实际效果？观看我们的[视频概览](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)！ - -[![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) - -## 🌍 社区 - -在 [Spec Kit 文档站点](https://github.github.io/spec-kit/)上探索由社区贡献的资源： - -- [扩展（Extensions）](https://github.github.io/spec-kit/community/extensions.html) —— 命令、钩子与各类能力 -- [预设（Presets）](https://github.github.io/spec-kit/community/presets.html) —— 模板与术语覆盖 -- [捆绑包（Bundles）](https://github.github.io/spec-kit/community/bundles.html) —— 由现有组件组合而成的角色与团队技术栈 -- [实战演练（Walkthroughs）](https://github.github.io/spec-kit/community/walkthroughs.html) —— 端到端的 SDD 场景 -- [伙伴项目（Friends）](https://github.github.io/spec-kit/community/friends.html) —— 扩展 Spec Kit 或基于它构建的项目 - -> [!NOTE] -> 社区贡献由各自的作者独立创建和维护。请在安装前审阅源代码，并自行斟酌使用。 - -想要参与贡献？请参阅[扩展发布指南](extensions/EXTENSION-PUBLISHING-GUIDE.md)、[预设发布指南](presets/PUBLISHING.md)或[社区捆绑包指南](docs/community/bundles.md)。 - -## 🤖 支持的 AI 编码助手集成 - -Spec Kit 可与 30 多个 AI 编码助手协作 —— 既包括 CLI 工具，也包括基于 IDE 的助手。完整列表以及相关说明和使用细节，请参阅[支持的 AI 编码助手集成](https://github.github.io/spec-kit/reference/integrations.html)指南。 - -运行 `specify integration list` 可查看当前安装版本中所有可用的集成。 - -## 可用的斜杠命令 - -运行 `specify init` 后，你的 AI 编码助手就能使用这些斜杠命令来进行结构化开发。对于支持技能模式的集成，传入 `--integration --integration-options="--skills"` 会安装助手技能，而不是斜杠命令的提示词文件。 - -### 核心命令 - -规范驱动开发工作流中必不可少的命令： - -| 命令 | 助手技能 | 说明 | -| ------------------------ | ---------------------- | ---------------------------------------------------------- | -| `/speckit.constitution` | `speckit-constitution` | 创建或更新项目的治理准则和开发指南 | -| `/speckit.specify` | `speckit-specify` | 定义你想构建什么（需求与用户故事） | -| `/speckit.plan` | `speckit-plan` | 结合所选技术栈制定技术实现方案 | -| `/speckit.tasks` | `speckit-tasks` | 生成可执行的实现任务清单 | -| `/speckit.taskstoissues` | `speckit-taskstoissues`| 将生成的任务清单转换为 GitHub issue，便于跟踪与执行 | -| `/speckit.implement` | `speckit-implement` | 执行所有任务，按方案构建功能 | -| `/speckit.converge` | `speckit-converge` | 对照规范/方案/任务评估代码库，并将剩余工作追加为新任务 | - -### 可选命令 - -用于提升质量与做校验的额外命令： - -| 命令 | 助手技能 | 说明 | -| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- | -| `/speckit.clarify` | `speckit-clarify` | 澄清描述不充分的部分（建议在 `/speckit.plan` 之前使用；旧称 `/quizme`） | -| `/speckit.analyze` | `speckit-analyze` | 跨制品的一致性与覆盖度分析（在 `/speckit.tasks` 之后、`/speckit.implement` 之前运行） | -| `/speckit.checklist` | `speckit-checklist` | 生成自定义质量清单，校验需求的完整性、清晰度与一致性（好比"为自然语言写单元测试"） | +报告保存在 `.specify/bugs/login-crash/`。请检查最终结论： +`verified`（已验证）、`partial`（部分验证）或 `failed`（失败）。缺少验证不算修复成功。 -## 🔧 Specify CLI 参考 +[缺陷修复指南](https://github.github.io/spec-kit/guides/bugfix.html) · +[命令参考](https://github.github.io/spec-kit/reference/agentic-bugfix.html) -完整的命令详情、选项与示例，请参阅 [CLI 参考文档](https://github.github.io/spec-kit/reference/overview.html)。 +## 想法评估 -## 🧩 打造你自己的 Spec Kit：扩展与预设 +在投入之前先收集证据，无论这个想法最终是否会成为软件。 +这是一个独立流程，也适用于非软件类想法，即使项目中没有源代码也能使用。 -Spec Kit 可通过两套互补的机制进行深度定制 —— **扩展（extensions）** 和 **预设（presets）** —— 以及面向单个项目的本地覆盖，用于临时性调整： - -| 优先级 | 组件类型 | 位置 | -| -----: | ---------------------------------- | -------------------------------- | -| ⬆ 1 | 项目本地覆盖 | `.specify/templates/overrides/` | -| 2 | 预设 —— 定制核心与扩展 | `.specify/presets/templates/` | -| 3 | 扩展 —— 新增能力 | `.specify/extensions/templates/` | -| ⬇ 4 | Spec Kit 核心 —— 内置 SDD 命令与模板 | `.specify/templates/` | - -- **模板**在**运行时**解析 —— Spec Kit 从高到低遍历优先级栈，使用第一个匹配项。 -- 项目本地覆盖（`.specify/templates/overrides/`）允许对单个项目做一次性调整，无需创建完整的预设。 -- **扩展/预设命令**在**安装时**生效 —— 当你运行 `specify extension add` 或 `specify preset add` 时，命令文件会被写入助手目录（如 `.claude/commands/`）。 -- 若多个预设或扩展提供了同一命令，优先级最高的版本生效。移除时，次优先级的版本会自动恢复。 -- 若不存在任何覆盖或自定义，Spec Kit 使用核心默认配置。 - -### 扩展 —— 新增能力 - -当你需要 Spec Kit 核心之外的功能时，使用**扩展**。扩展可引入新命令和模板 —— 例如添加核心 SDD 命令未覆盖的领域特定工作流、集成外部工具，或新增全新的开发阶段。它们扩展了 *Spec Kit 能做什么*。 - -```bash -# 搜索可用扩展 -specify extension search - -# 安装扩展 -specify extension add -``` - -举例来说，扩展可以添加 Jira 集成、实现后代码审查、V 模型测试追溯性，或项目健康诊断等功能。 - -完整命令指南请参阅[扩展参考文档](https://github.github.io/spec-kit/reference/extensions.html)。浏览[社区扩展](https://github.github.io/spec-kit/community/extensions.html)了解现有资源。 - -### 预设 —— 定制现有工作流 - -当你想改变 Spec Kit 的*工作方式*而不是新增能力时，使用**预设**。预设会覆盖核心及已安装扩展中附带的模板和命令 —— 例如强制使用面向合规的规范格式、采用领域特定术语，或对方案和任务应用组织规范。预设定制的是 Spec Kit 及其扩展生成的制品与指令。 +在项目目录下的**终端**中安装这个可选扩展： ```bash -# 搜索可用预设 -specify preset search - -# 安装预设 -specify preset add +specify extension add assess ``` -举例来说，预设可以重构规范模板以要求监管追溯性，将工作流适配为你所用的方法论（如敏捷、看板、瀑布、用户任务驱动或领域驱动设计），在方案中添加强制安全审查关卡，强制要求测试优先的任务排序，或将整个工作流本地化为其他语言。[海盗语演示](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo)充分展示了定制的深度。多个预设可按优先级叠加使用。 - -完整命令指南以及解析顺序和优先级叠加说明，请参阅[预设参考文档](https://github.github.io/spec-kit/reference/presets.html)。 - -## 📦 捆绑包：面向角色的一键配置 - -扩展和预设是独立的构建模块。而**捆绑包（bundle）**将一组精选的扩展、预设、步骤和工作流打包成一个带版本、面向角色的配置，从而可以用一条命令为整个团队角色（产品经理、业务分析师、安全研究员、开发者……）完成配置。 - -捆绑包由一份手写的 `bundle.yml` 清单描述。它将每个组件锁定到具体版本，并可选择性地面向特定集成；未指定 `integration` 的捆绑包是**中立的**，会沿用项目当前已使用的集成。 +然后在编码助手中依次运行 **intake → research → define → shape → decide** +（收集想法 → 调研 → 定义问题 → 形成方案 → 决策）： -```bash -# 在当前激活的目录栈中发现捆绑包 -specify bundle search [] - -# 查看捆绑包将添加的确切组件集合（与实际安装的内容一致） -specify bundle info - -# 一步安装捆绑包的完整组件集合 -specify bundle install - -# 查看已安装内容，然后以非破坏性方式更新或移除 -specify bundle list -specify bundle update # 或 --all -specify bundle remove # 仅移除此捆绑包的组件 +```text +/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode +/speckit-assess-research slug=offline-mode +/speckit-assess-define slug=offline-mode +/speckit-assess-shape slug=offline-mode +/speckit-assess-decide slug=offline-mode ``` -捆绑包从一个**按优先级排序的目录栈**（项目 > 用户 > 内置）中解析。每个来源都带有安装策略：`install-allowed` 来源可用于安装，而 `discovery-only` 来源在 `search`/`info` 中可见但拒绝安装。可通过 `specify bundle catalog list|add|remove` 管理目录栈。 - -作者在本地校验并打包捆绑包。分发方式是托管构建产物并添加一个目录来源；社区捆绑包投稿请使用 [Bundle Submission](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue 模板，以便对所需的组件目录和安装证据进行审阅： - -```bash -specify bundle validate --path ./my-bundle # 结构与引用检查 -specify bundle build --path ./my-bundle # 生成带版本的 .zip 产物 -``` - -[`examples/bundles/`](examples/bundles/) 目录下有四份可直接阅读的示例清单（产品经理、业务分析师、安全研究员、开发者）。 - -关键保证：`info` 展示的内容与 `install` 添加的内容完全一致（透明性）；安装是幂等的，且限定在项目根目录内；`remove` 绝不会触碰其他已安装捆绑包仍需要的组件；所有消费/创作命令都能针对本地或锁定的来源**离线**工作。 - -### 何时用哪个 - -| 目标 | 使用 | -| --- | --- | -| 添加全新的命令或工作流 | 扩展 | -| 定制规范、方案或任务的格式 | 预设 | -| 集成外部工具或服务 | 扩展 | -| 强制执行组织或监管规范 | 预设 | -| 交付可复用的领域特定模板 | 均可 —— 预设用于模板覆盖，扩展用于随新命令一起打包的模板 | -| 用一条命令完成完整的角色配置 | 捆绑包 | - -## 📚 核心理念 - -规范驱动开发是一套结构化流程，它强调： - -- **意图驱动开发** —— 让规范先定义"*做什么*"，再谈"*怎么做*" -- **丰富的规范撰写** —— 借助护栏与组织准则来编写规范 -- **多步精炼** —— 而非从提示词一次性生成代码 -- **充分依赖**先进 AI 模型对规范的解读能力 - -## 🌟 开发阶段 - -| 阶段 | 侧重点 | 关键活动 | -| ----------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| **从 0 到 1 开发**（"绿地/Greenfield"） | 从零生成 |
  • 从高层需求出发
  • 生成规范
  • 规划实现步骤
  • 构建生产就绪的应用
| -| **创意探索** | 并行实现 |
  • 探索多样化的解决方案
  • 支持多种技术栈与架构
  • 试验不同的用户体验模式
| -| **迭代增强**（"棕地/Brownfield"） | 存量系统现代化 |
  • 迭代式添加功能
  • 现代化改造遗留系统
  • 调整流程
| - -对于已有项目，请将 Spec Kit 工具本身的更新与功能制品的演进分开处理：升级时刷新受管理的项目文件，而在预期行为发生变化时更新 `specs/` 制品。[规范演进指南](./docs/guides/evolving-specs.md)介绍了推荐的棕地迭代循环。 - -## 🎯 实验目标 - -我们的研究与实验聚焦于： - -### 技术无关性 - -- 使用多样化的技术栈构建应用 -- 验证这一假设：规范驱动开发是一套流程，不与特定技术、编程语言或框架绑定 - -### 企业级约束 - -- 展示关键业务应用的开发 -- 纳入组织层面的约束（云服务商、技术栈、工程实践） -- 支持企业设计系统与合规要求 - -### 以用户为中心的开发 - -- 为不同的用户群体和偏好构建应用 -- 支持多种开发方式（从"氛围编码"到 AI 原生开发） +制品保存在 `.specify/assessments/offline-mode/`，最终给出 +**go / needs-clarification / kill**（推进 / 需要澄清 / 停止）的决策。 +遇到待澄清问题时，直接完善已有的 Markdown 制品，或请助手协助修改，而不是重新生成整个阶段。 +如果决定开发，可将 `go` 的评估结果交给 `/speckit-specify`；记录理由后停止，同样是有价值的结果。 -### 创意与迭代流程 +[想法评估指南](https://github.github.io/spec-kit/guides/assessment.html) · +[命令参考](https://github.github.io/spec-kit/reference/agentic-assessment.html) -- 验证并行实现探索的理念 -- 提供稳健的迭代式功能开发工作流 -- 将流程扩展到升级与现代化改造任务 + + + -## 🔧 环境要求 +## 定制或引入自己的流程 -- **Linux/macOS/Windows** -- [受支持的](#-支持的-ai-编码助手集成) AI 编码助手。 -- [uv](https://docs.astral.sh/uv/) 用于包管理（推荐），或 [pipx](https://pipx.pypa.io/) 用于持久化安装 -- [Python 3.11+](https://www.python.org/downloads/) -- [Git](https://git-scm.com/downloads) +**扩展**新增能力，**预设**调整现有行为，**工作流**自动执行步骤，**捆绑包**打包面向角色的配置。 +单个项目的一次性模板调整可使用项目本地覆盖；流程或术语的本地化可使用预设。 -如果你在使用某个助手时遇到问题，欢迎提交 issue，以便我们完善相应集成。 +[定制指南](https://github.github.io/spec-kit/guides/customization.html) · +[社区扩展、预设、捆绑包与实战演练](https://github.github.io/spec-kit/community/overview.html) -## 📖 深入了解 + + + + + + + -- **[完整的规范驱动开发方法论](./spec-driven.md)** —— 深入了解整个流程 -- **[快速上手指南](https://github.github.io/spec-kit/quickstart.html)** —— 分步实现演练 +## 文档 ---- +以下链接指向英文指南。工具升级与功能规范演进是两件事：升级时更新工具文件，需求变化时更新 `specs/` 制品。 -## 💬 支持 +- [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) +- [Spec Kit 如何使用 Spec Kit](./CONTRIBUTING.md#does-spec-kit-use-spec-kit) -如需帮助，请提交 [GitHub issue](https://github.com/github/spec-kit/issues/new)。我们欢迎缺陷报告、功能建议，以及关于使用规范驱动开发的各类问题。 + -## 🙏 致谢 +## 支持与贡献 -本项目深受 [John Lam](https://github.com/jflam) 的工作与研究的影响，并在其基础上构建。 +[报告缺陷或提出功能建议](https://github.com/github/spec-kit/issues/new) · +[贡献指南](./CONTRIBUTING.md) · [行为准则](./CODE_OF_CONDUCT.md) -## 📄 许可证 + -本项目基于 MIT 开源许可证的条款授权。完整条款请参阅 [LICENSE](./LICENSE) 文件。 +Spec Kit 采用 [MIT 许可证](./LICENSE)。 diff --git a/docs/README.md b/docs/README.md index a9edc81dc9..d787a4b6fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -27,7 +27,11 @@ To build the documentation locally: - `index.md` - Main documentation homepage - `toc.yml` - Table of contents configuration - `installation.md` - Installation guide -- `quickstart.md` - Quick start guide +- `quickstart.md` - Spec-Driven Development walkthrough +- `guides/bugfix.md` - Bug-fixing walkthrough +- `guides/assessment.md` - Idea assessment walkthrough +- `guides/customization.md` - Choosing and combining customization building blocks +- `reference/agentic-*.md` - Detailed process command references - `_site/` - Generated documentation output (ignored by git) ## Deployment diff --git a/docs/community/overview.md b/docs/community/overview.md index d8fedcf1a3..48b0d42d7b 100644 --- a/docs/community/overview.md +++ b/docs/community/overview.md @@ -2,6 +2,10 @@ The Spec Kit community builds extensions, presets, bundles, 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. +> [!NOTE] +> Review community source code before installation and use it at your own +> discretion. A catalog listing is not an audit or endorsement. + ## Extensions Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. Over 130 community extensions are available from 70+ authors, covering everything from accessibility governance to multi-agent orchestration. @@ -31,3 +35,11 @@ Step-by-step guides that show Spec-Driven Development in action across different Community projects that extend, visualize, or build on Spec Kit — including VS Code extensions, Claude Code plugins, and more. [Browse friend projects →](friends.md) + +## Contribute a component + +To publish your own work, follow the +[Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md), +the [Presets Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md), +or the [Community Bundles guide](bundles.md). For help choosing a component type, +see [Customize Spec Kit](../guides/customization.md). diff --git a/docs/guides/assessment.md b/docs/guides/assessment.md new file mode 100644 index 0000000000..2b13b00a6d --- /dev/null +++ b/docs/guides/assessment.md @@ -0,0 +1,114 @@ +# Idea Assessment Quickstart + +Use this process to decide whether an idea deserves investment before committing +to a solution. It works for software ideas and non-software decisions alike. +No existing source code is required. + +The bundled, opt-in **assess** extension provides five stages: +**intake → research → define → shape → decide**. The result is an evidence-backed +`go`, `needs-clarification`, or `kill` decision, not an implementation. + +## Set up + +[Install Spec Kit and initialize a project](../installation.md). An empty project +is enough, or you can use an +[existing repository](existing-projects.md) when the idea relates to its code. +In a terminal at the initialized project root, install the extension: + +```bash +specify extension add assess +``` + +Then launch your coding agent in that directory. The examples below use +GitHub Copilot's default skills mode (`--integration copilot`). Other agents +use their own +[command invocation syntax](../reference/integrations.md#command-invocation). +Run each command separately in the agent, not in your terminal, reviewing the +artifact before moving on. + +## 1. Capture the idea + +```text +/speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode +``` + +You can also supply a URL, ticket, or codebase pointer. The agent captures the +input in `.specify/assessments/offline-mode/intake.md`. +The slug is the shared handle for all five stages. + +## 2. Research the evidence + +```text +/speckit-assess-research slug=offline-mode +``` + +The agent gathers supporting and opposing evidence in `research.md`. Review +sources and confidence levels: uncited assumptions are not established facts. +This stage should challenge the idea, not just build a case for it. + +## 3. Define the problem + +```text +/speckit-assess-define slug=offline-mode +``` + +The agent writes `problem.md`, describing the affected users, problem, goals, +non-goals, success metrics, and cost of doing nothing. + +## 4. Shape possible solutions + +```text +/speckit-assess-shape slug=offline-mode +``` + +The agent compares concept-level options, constraints, appetite, and trade-offs +in `concept.md`. Detailed architecture, implementation tasks, and source changes +are deliberately outside this process. + +## 5. Make the decision + +```text +/speckit-assess-decide slug=offline-mode +``` + +The agent records the scorecard, rationale, and verdict in `decision.md`. + +| Verdict | What it means | What to do | +| --- | --- | --- | +| `go` | The problem and evidence are adequate and a concept is recommended | Decide whether to act; optionally hand a software idea to SDD | +| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts with the missing information | +| `kill` | The idea is not worth pursuing now | Keep the recorded rationale; stopping is a successful outcome | + +All five artifacts live under `.specify/assessments/offline-mode/`. None of the +assessment commands modify source code. + +## Resolve unknowns by refining the artifacts + +The usual flow runs each command once. When an artifact contains +`[NEEDS CLARIFICATION: ...]`, edit that Markdown file directly or ask the agent +in free-form chat to incorporate the missing information: + +```text +Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: . Update any dependent wording and revise decision.md if this resolves the blocker. Preserve source and confidence tags. +``` + +Do not automatically regenerate the entire stage. Ask the agent to review +whether the new facts clear the blocker and revise the downstream scorecard, +verdict, or handoff accordingly. Rerunning a command is an exception, such as +replacing a discarded draft, and existing artifacts must not be overwritten +without confirmation. + +## Optional handoff to SDD + +Assessment is standalone: it does not automatically invoke SDD or insert itself +into the specification process. If you choose to build a software idea with a +`go` verdict, establish your project constitution if needed, then pass the +decision's handoff summary to the specification command: + +```text +/speckit-specify Use the handoff summary in .specify/assessments/offline-mode/decision.md to specify the approved offline-mode concept. +``` + +Continue with the [SDD quickstart](../quickstart.md). For stage prerequisites, +slug rules, and evidence requirements, see the +[idea assessment command reference](../reference/agentic-assessment.md). diff --git a/docs/guides/bugfix.md b/docs/guides/bugfix.md new file mode 100644 index 0000000000..ebe54b003c --- /dev/null +++ b/docs/guides/bugfix.md @@ -0,0 +1,81 @@ +# Bug Fixing Quickstart + +Use this process when existing behavior is broken and you need an evidence-based +diagnosis, a scoped repair, and verification against the original report. You do +not need to run the SDD feature workflow first. + +The bundled, opt-in **bug** extension separates the work into +**assess → fix → test**. Each bug gets a directory under +`.specify/bugs//` containing the diagnosis, change record, and test results. + +## Set up + +First [install Spec Kit](../installation.md) and initialize the repository that +contains the bug. If it already contains code, follow +[Adopting Spec Kit in an Existing Project](existing-projects.md). + +In a terminal at the initialized project root, install the extension: + +```bash +specify extension add bug +``` + +Then launch your coding agent in that directory. The examples below use +GitHub Copilot's default skills mode (`--integration copilot`). Other agents +expose the same steps using their own +[command invocation syntax](../reference/integrations.md#command-invocation). +Run each command separately in the agent, not in your terminal, and review its +output before continuing. + +## 1. Assess the bug + +Provide the symptom, reproduction steps, and expected behavior. A GitHub issue +URL or stack trace also works. Choose a short, reusable name for the bug: + +```text +/speckit-bug-assess "Submitting the login form with an empty password crashes the app instead of showing a validation error." slug=login-crash +``` + +The agent investigates the code and writes +`.specify/bugs/login-crash/assessment.md`. It does not change source code. +Review the diagnosis and proposed remediation before asking for a fix; do not +proceed with an unsupported diagnosis or a report that is not a bug. + +## 2. Fix the assessed cause + +Use the same slug: + +```text +/speckit-bug-fix slug=login-crash +``` + +The agent applies the assessed remediation and records the changes in +`.specify/bugs/login-crash/fix.md`. This is the only stage that edits source +code. If new evidence requires work outside the assessed scope, the agent must +record that deviation rather than silently expanding the repair. + +## 3. Test the fix + +```text +/speckit-bug-test slug=login-crash +``` + +The agent re-runs the reproduction and relevant tests, then writes +`.specify/bugs/login-crash/test.md`. This stage records evidence; it does not +edit source code to make a failing test pass. + +| Verdict | Meaning | What to do | +| --- | --- | --- | +| `verified` | The verification requirements were exercised successfully | Review the patch and evidence before merging | +| `partial` | Some verification could not be completed | Supply the missing environment or reproduction evidence and test again | +| `failed` | Verification found a remaining problem | Revisit the diagnosis or fix using that evidence, then test again | + +A passing test suite alone is not enough if the original reproduction was never +exercised. Keep the assessment, fix record, and test report together so a reviewer +can trace the repair from symptom to evidence. + +## Learn more + +- [Bug command reference](../reference/agentic-bugfix.md): arguments, slug handling, and output contracts. +- [SDD quickstart](../quickstart.md): use this when the work is a new feature rather than a repair. +- [Idea assessment quickstart](assessment.md): investigate whether a proposed change is worth pursuing. diff --git a/docs/guides/customization.md b/docs/guides/customization.md new file mode 100644 index 0000000000..2edf6971bb --- /dev/null +++ b/docs/guides/customization.md @@ -0,0 +1,105 @@ +# Customize Spec Kit + +The three first-party processes are starting points, not limits. Keep the +built-in SDD process, add bug fixing or assessment, adapt a process to your +organization, or bring a different process entirely. + +## Choose the right building block + +| Goal | Use | +| --- | --- | +| 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 | +| Enforce organizational or regulatory standards in existing templates | Preset | +| 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 | +| Provision a complete role-based setup in one operation | Bundle | + +## Extensions: add capabilities + +Extensions expand **what Spec Kit can do** through commands, templates, scripts, +and hooks. They can add domain-specific processes, external integrations, or +development phases beyond the core. + +```bash +specify extension search +specify extension add +``` + +Examples include Jira integration, post-implementation code review, V-Model test +traceability, and project health diagnostics. The bundled +[bug](bugfix.md) and [assess](assessment.md) extensions are first-party examples. +Browse [community extensions](../community/extensions.md), or use the +[extension reference](../reference/extensions.md) for management and configuration. + +## Presets: change how a process works + +Presets override templates and commands supplied by the core **and by installed +extensions**. They customize the artifacts and instructions produced without +requiring new tooling. + +```bash +specify preset search +specify preset add +``` + +Use a preset to require regulatory traceability, enforce test-first task ordering, +add security review gates to plans, or localize a workflow. Presets can also adapt +the methodology to Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven +design. The +[pirate-speak demo](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) +illustrates how extensively the terminology can change. + +Multiple presets can be stacked with priorities. See +[community presets](../community/presets.md) for examples and the +[preset reference](../reference/presets.md) for installation, composition +strategies, and precedence. + +## Project-local overrides and resolution + +For a one-off project customization, place a template override in +`.specify/templates/overrides/` rather than creating a reusable preset. +The default replacement order is: + +1. Project-local overrides. +2. Installed presets, in priority order. +3. Installed extensions, in priority order. +4. Spec Kit core templates in `.specify/templates/`. + +Templates are resolved when needed, using the first match by default. +Commands are different: installing extensions or presets materializes command +files into the active integration's directory. Agents do not re-resolve that +stack every time they invoke a command. Removing an overriding component +restores the surviving command layer through reconciliation. + +With no customizations, the core defaults apply. The +[file resolution reference](../reference/presets.md#file-resolution) is the +authoritative guide to paths, priorities, and prepend/append/wrap composition. + +## Bundles: role-based setups + +A bundle packages a curated set of extensions, presets, workflows, and workflow +steps as one versioned setup for a role or team. Its `bundle.yml` manifest pins +components and may target an integration; an integration-agnostic bundle inherits +the project's active integration. + +```bash +specify bundle search +specify bundle info +specify bundle install +``` + +Inspect `info` before installing to see the resolved component set. See the +[bundle reference](../reference/bundles.md) for updates, removal, catalog policies, +offline limitations, validation, and publishing, and the +[example manifests](https://github.com/github/spec-kit/tree/main/examples/bundles) +for product manager, business analyst, security researcher, and developer setups. + +## Share your customizations + +Community components are independently maintained. Review source code before +installation and use it at your own discretion. Visit the +[community guide](../community/overview.md) to discover components or publish your +own, and the [workflow reference](../reference/workflows.md) to automate a process. diff --git a/docs/guides/existing-projects.md b/docs/guides/existing-projects.md index 479715546e..9736557316 100644 --- a/docs/guides/existing-projects.md +++ b/docs/guides/existing-projects.md @@ -33,6 +33,12 @@ specifications for existing behavior. ## 2. Capture Project Guardrails +The remaining steps illustrate adopting **SDD** for a bounded feature. If your +first task is a repair, you can instead follow the +[bug-fixing quickstart](bugfix.md) after initialization; to evaluate a proposal, +use the [idea assessment quickstart](assessment.md). Neither process requires +completing the SDD steps below first. + Run `/speckit.constitution` with principles that are already true for the repository or that the team has explicitly agreed to adopt: @@ -49,7 +55,7 @@ so unrealistic rules create noise instead of useful constraints. ## 3. Choose a Bounded First Change -Start with a feature, bug fix, or modernization slice that can be reviewed +Start with a feature or modernization slice that can be reviewed independently. Do not make "document the entire existing system" your first feature unless that inventory is itself the intended deliverable. diff --git a/docs/history.md b/docs/history.md index b3aee62909..134fa1ca65 100644 --- a/docs/history.md +++ b/docs/history.md @@ -149,6 +149,19 @@ integrations, 157 community extensions, 33 presets, and 270+ contributors. Spec Kit continues to favor adaptability: processes, integrations, and conventions can evolve while agents help projects apply those changes. +The [1.0.0 release](https://github.com/github/spec-kit/releases/tag/v1.0.0) +marked a year of work rather than a promise that the project was finished or its +shape frozen. In the lead maintainer's personal anniversary post, +[*Spec Kit Turns One — and Ships 1.0.0*](https://www.manorrock.com/blog/2026/08/21/spec_kit_turns_one.html), +1.0.0 is **now just a number**: as agents make adapting to change less expensive, +the value moves from stability to adaptability. + +The anniversary also recognized everyone who used Spec Kit, challenged its +assumptions, reported problems, contributed code or documentation, created +extensions or presets, shared ideas, or helped someone get started. The milestone +belongs to the community that carried the project through its first year and +continues to shape it. + ## Enduring themes Several themes connect the project's stewardship periods and technical diff --git a/docs/index.md b/docs/index.md index 082c22ac7d..d7f4ca97ee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,24 +4,41 @@ # GitHub Spec Kit -**Spec-Driven Development or your own process — step by step or as an automated workflow.** +**Build with a spec, fix a bug, or assess an idea — with your coding agent.** -Spec Kit is an extensible, intent-driven harness that pushes any coding agent beyond code, guiding it across your SDLC or any business process. Use it for [Spec-Driven Development](concepts/sdd.md) (SDD), where you describe _what_ to build and refine it through structured phases. Run it step by step, automate it end to end, or shape a process of your own, keeping intent at the center. +Spec Kit gives your coding agent structured processes that keep intent and evidence ahead of implementation. Start with Spec-Driven Development (SDD), bug fixing, or idea assessment. Run a process step by step, automate it, or [shape one of your own](guides/customization.md) — including processes beyond software development. Install Spec Kit  -Quick Start +Choose your process --- +## Choose your process + +| What you need | Start here | What you get | +| --- | --- | --- | +| Build a feature or application | [Spec-Driven Development](quickstart.md) | A specification carried through planning, implementation, and convergence | +| Diagnose and repair broken behavior | [Bug fixing](guides/bugfix.md) | An assessed cause, scoped fix, and recorded verification | +| Decide whether an idea deserves investment | [Idea assessment](guides/assessment.md) | An evidence-backed go, clarify, or stop decision | + +These are independent entry points, not mandatory phases. SDD ships in core. +Bug fixing and assessment are bundled, opt-in extensions. Assessment can stand +alone; a decision to proceed does not automatically start implementation. + +Adding Spec Kit to an established codebase? Start with the +[existing-project guide](guides/existing-projects.md). + +--- +
### Spec-driven by default -The core SDD process ships ready to use: **Spec → Plan → Tasks → Implement**. +The core SDD process ships ready to use: **Specify → Plan → Tasks → Implement → Converge**. Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts. @@ -123,8 +140,20 @@ Community extensions like CI Guard and Architecture Guard add compliance gates a
- Getting Started - Install, configure, and run your first SDD workflow + Spec-Driven Development + Define, plan, implement, and converge on a feature + + + Bug Fixing + Assess the cause, apply a scoped fix, and verify the result + + + Idea Assessment + Research an idea and decide whether it deserves investment + + + Customize Spec Kit + Adapt a process, add capabilities, or package a role-based setup Existing Projects @@ -165,8 +194,8 @@ uv tool install specify-cli specify init my-project --integration copilot ``` -Ready to start? Follow the [Quick Start Guide](quickstart.md). +Ready to start? [Choose your process](#choose-your-process).
-

Last updated: August 21, 2026

+

Last updated: September 14, 2026

diff --git a/docs/installation.md b/docs/installation.md index 67b69505e6..a8a68fc992 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -95,6 +95,27 @@ specify init --script ps specify init --script py ``` +### CI and AI Agent Harnesses + +For environments without a keyboard, or a PTY that cannot send arrow keys, pass +`--non-interactive` so initialization never waits on a picker: + +```bash +specify init my-project --non-interactive --ignore-agent-tools +``` + +`--ignore-agent-tools` skips the agent executable check when the agent will run +elsewhere; omit it when you want that check. Non-interactive initialization +defaults to Copilot unless you select another integration explicitly. + +For a non-empty directory, `--force` acknowledges the merge warning. Review the +[existing-project guide](guides/existing-projects.md) and commit or back up local +changes before initializing: + +```bash +specify init --here --force --non-interactive --integration claude +``` + ### Ignore Agent Tools Check If you prefer to get the templates without checking for the right tools: @@ -134,6 +155,15 @@ Scripts are installed into a variant subdirectory matching the chosen script typ - `.specify/scripts/powershell/` — contains `.ps1` scripts (default on Windows) - `.specify/scripts/python/` — contains `.py` scripts (chosen with `--script py`; also installs the platform shell fallback) +## Choose a Process + +After initialization, launch your coding agent in the project directory and +follow the [SDD quickstart](quickstart.md), +[bug-fixing quickstart](guides/bugfix.md), or +[idea assessment quickstart](guides/assessment.md). These are independent entry +points. SDD is available immediately; the other guides show how to install their +bundled, opt-in extensions. + ## Troubleshooting ### Enterprise / Air-Gapped Installation diff --git a/docs/local-development.md b/docs/local-development.md index 34070451fc..243771614c 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -4,6 +4,10 @@ This guide shows how to iterate on the `specify` CLI locally without publishing > Scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs (no TTY, or `--non-interactive`) default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly. +For how the project uses its own SDD and assessment processes, see +[Does Spec Kit use Spec Kit?](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#does-spec-kit-use-spec-kit) +in the contributor guide. + ## 1. Clone and Switch Branches ```bash diff --git a/docs/quickstart.md b/docs/quickstart.md index fb2ecc2f74..d4304dcf2e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,11 +1,22 @@ -# Quick Start Guide + + +# Spec-Driven Development Quickstart This guide will help you get started with Spec-Driven Development using Spec Kit. Throughout, we illustrate each step with a running example: **Taskify**, a small team productivity platform. +Use SDD to build a feature or application from a specification. For a repair, +follow the [bug-fixing quickstart](guides/bugfix.md); to decide whether an idea +deserves investment, follow the [idea assessment quickstart](guides/assessment.md). +These are independent processes, not prerequisites for this guide. + > [!NOTE] > Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs (no TTY, or `--non-interactive`) default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly. -Commands are shown here in `/speckit.*` form, but the exact invocation depends on your agent. Some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Use whichever form your agent exposes — the steps are otherwise identical. +Commands here use GitHub Copilot's default skills mode (`/speckit-*`). +For other agents or modes, see +[Command invocation](reference/integrations.md#command-invocation). +Run each process command separately inside the coding agent, not in your terminal, +and review the result before moving to the next step. ## Recommended Process @@ -14,25 +25,28 @@ Commands are shown here in `/speckit.*` form, but the exact invocation depends o After installing Spec Kit, each command below is a step in the process. Two paths are common: +Establish a constitution once per project with `/speckit-constitution` before +starting either path. + **Shorter path** — for smaller features: -1. `/speckit.specify` -2. `/speckit.plan` -3. `/speckit.tasks` -4. `/speckit.implement` -5. `/speckit.converge` +1. `/speckit-specify` +2. `/speckit-plan` +3. `/speckit-tasks` +4. `/speckit-implement` +5. `/speckit-converge` -**Full path** — for production features, adding `/speckit.clarify`, `/speckit.checklist`, and `/speckit.analyze` as quality gates: +**Full path** — for production features, adding `/speckit-clarify`, `/speckit-checklist`, and `/speckit-analyze` as quality gates: -1. `/speckit.constitution` -2. `/speckit.specify` -3. `/speckit.clarify` -4. `/speckit.plan` -5. `/speckit.checklist` -6. `/speckit.tasks` -7. `/speckit.analyze` -8. `/speckit.implement` -9. `/speckit.converge` +1. `/speckit-constitution` (once per project) +2. `/speckit-specify` +3. `/speckit-clarify` +4. `/speckit-plan` +5. `/speckit-checklist` +6. `/speckit-tasks` +7. `/speckit-analyze` +8. `/speckit-implement` +9. `/speckit-converge` ### Install Specify @@ -40,7 +54,8 @@ After installing Spec Kit, each command below is a step in the process. Two path ```bash uv tool install specify-cli -specify init taskify # or: specify init . to use the current directory +specify init taskify --integration copilot +cd taskify ``` `init` lets you pick your coding agent interactively, or pass it explicitly with `--integration` (e.g. `--integration copilot`). For CI and AI agent harnesses, add `--non-interactive` so unspecified choices use documented defaults instead of hanging on an arrow-key picker. @@ -51,76 +66,96 @@ specify init taskify # or: specify init . to use the current directory > [Adopting Spec Kit in an Existing Project](guides/existing-projects.md) before > starting the workflow below. -### Step 1: `/speckit.constitution` — set the ground rules +Launch your coding agent in the project directory before continuing. + + + +### Step 1: `/speckit-constitution` — set the ground rules Establishes the project's guiding principles, which every later step is evaluated against. Run it once up front, passing your principles as arguments. ```text -/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented. +/speckit-constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented. ``` -### Step 2: `/speckit.specify` — describe what to build + + +### Step 2: `/speckit-specify` — describe what to build Creates the feature specification from a natural-language description. Focus on the **what** and **why**, not the tech stack. ```text -/speckit.specify Develop Taskify, a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users (one product manager, four engineers), three sample projects, no login for this first phase. +/speckit-specify Develop Taskify, a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users (one product manager, four engineers), three sample projects, no login for this first phase. ``` -### Step 3: `/speckit.clarify` — resolve ambiguities + + +### Step 3: `/speckit-clarify` — resolve ambiguities Asks targeted questions about anything underspecified and folds your answers back into the spec, so you're not planning on top of ambiguity. Run it before planning, optionally with a focus area. ```text -/speckit.clarify Focus on task card behavior — status changes, comment permissions, and user assignment. +/speckit-clarify Focus on task card behavior — status changes, comment permissions, and user assignment. ``` -### Step 4: `/speckit.plan` — choose the tech stack + + +### Step 4: `/speckit-plan` — choose the tech stack Generates the design artifacts from the spec. This is where implementation detail belongs — provide your tech stack and architecture. ```text -/speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications. +/speckit-plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications. ``` -### Step 5: `/speckit.checklist` — validate the spec + + +### Step 5: `/speckit-checklist` — validate the spec Generates a custom quality checklist — "unit tests for your requirements" — to confirm the spec is complete, clear, and consistent before you break the work down. These custom checklists are reviewer-owned requirements-quality review artifacts: mark an item `[x]` only when the reviewer determines that requirement-quality criterion is satisfied. Checked custom items do not mean implementation work is complete. ```text -/speckit.checklist +/speckit-checklist ``` -### Step 6: `/speckit.tasks` — break the work down + + +### Step 6: `/speckit-tasks` — break the work down Generates an actionable, dependency-ordered `tasks.md` from the design artifacts. ```text -/speckit.tasks +/speckit-tasks ``` -### Step 7: `/speckit.analyze` — check consistency + + +### Step 7: `/speckit-analyze` — check consistency Reports conflicts, gaps, and ambiguities across `spec.md`, `plan.md`, and `tasks.md`. It's read-only — if it flags issues, fix them at the source and re-run before implementing. ```text -/speckit.analyze +/speckit-analyze ``` -### Step 8: `/speckit.implement` — build it + + +### Step 8: `/speckit-implement` — build it -Executes the tasks in `tasks.md` in dependency order. Before implementation, it reads checklist checkbox state as a gate and asks before proceeding if any checklist items are unchecked; it does not change any checklist files or markers. The built-in `checklists/requirements.md` checklist is maintained by `/speckit.specify` and `/speckit.clarify`, while custom checklists remain reviewer-owned. Run it once to build everything, or scope it to one phase at a time for large features. +Executes the tasks in `tasks.md` in dependency order. Before implementation, it reads checklist checkbox state as a gate and asks before proceeding if any checklist items are unchecked; it does not change any checklist files or markers. The built-in `checklists/requirements.md` checklist is maintained by `/speckit-specify` and `/speckit-clarify`, while custom checklists remain reviewer-owned. Run it once to build everything, or scope it to one phase at a time for large features. ```text -/speckit.implement +/speckit-implement ``` -### Step 9: `/speckit.converge` — verify completeness + -Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appends new tasks to `tasks.md`; run `/speckit.implement` and converge again until it reports converged. Otherwise you're done — proceed to review or open a PR. +### Step 9: `/speckit-converge` — verify completeness + +Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appends new tasks to `tasks.md`; run `/speckit-implement` and converge again until it reports **Converged**. Otherwise you're done — proceed to review or open a PR. ```text -/speckit.converge +/speckit-converge ``` > [!TIP] @@ -137,7 +172,16 @@ Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appe ## Next Steps - See the [Agentic SDD](reference/agentic-sdd.md) reference for full detail on every command +- Learn how to [customize the process](guides/customization.md) with extensions, presets, workflows, and bundles - Read the [complete methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md) for in-depth guidance - 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/reference/agentic-assessment.md b/docs/reference/agentic-assessment.md new file mode 100644 index 0000000000..d5d48515c5 --- /dev/null +++ b/docs/reference/agentic-assessment.md @@ -0,0 +1,102 @@ +# Agentic Idea Assessment + +The bundled, opt-in **assess** extension evaluates an idea through +**intake → research → define → shape → decide**. It is a standalone process: +it can run in an initialized project with no source code, produces only +assessment artifacts, and does not automatically start SDD. For a guided example, +see the [Idea Assessment Quickstart](../guides/assessment.md). + +Install it from an initialized project's root: + +```bash +specify extension add assess +``` + +Commands below use `/speckit.assess.*` notation. GitHub Copilot's default skills +mode uses `/speckit-assess-*`; other integrations may use a different prefix. +See [Command invocation](integrations.md#command-invocation). + +## Commands and artifacts + +Every artifact is written under `.specify/assessments//`. + +| Command | Purpose | Output | +| --- | --- | --- | +| `/speckit.assess.intake` | Capture an idea from text, a URL, a ticket, or a codebase pointer | `intake.md` | +| `/speckit.assess.research` | Gather evidence for and against the idea, with sources and confidence | `research.md` | +| `/speckit.assess.define` | Define users, the problem, goals, non-goals, metrics, and cost of inaction | `problem.md` | +| `/speckit.assess.shape` | Compare concept-level options, appetite, and trade-offs | `concept.md` | +| `/speckit.assess.decide` | Record a scorecard, verdict, rationale, and optional SDD handoff | `decision.md` | + +Pass the initial idea and a slug to intake, then reuse the slug: + +```text +/speckit.assess.intake "Let users work offline and sync when they reconnect." slug=offline-mode +/speckit.assess.research slug=offline-mode +/speckit.assess.define slug=offline-mode +/speckit.assess.shape slug=offline-mode +/speckit.assess.decide slug=offline-mode +``` + +## Prerequisites and scope + +The five-stage sequence is the normal path, but not every stage is mandatory: + +- `define` can work directly from user input; intake and research are optional + for producing a problem definition. +- `shape` requires `problem.md` and stays at concept level. Architecture, + data models, APIs, tasks, and implementation belong to delivery, not assessment. +- `decide` requires `problem.md` and reads every available assessment artifact. + A `go` verdict additionally requires a shaped concept and adequate evidence; + skipping research does not waive the evidence requirement. + +## Slugs and existing artifacts + +The slug identifies one idea's directory. User-provided slugs are normalized to +lowercase kebab-case and retained without appended timestamps or numbers. +If no slug is supplied, intake asks for one interactively; automated runs +generate a unique slug. Later stages can reuse the slug from context when its +directory exists. + +Existing artifacts are not overwritten without confirmation. In automated mode, +commands refuse to overwrite them. For routine clarification, refine the existing +artifact rather than rerunning the command. + +## Decisions and evidence + +The decision scorecard rates criteria as `strong`, `adequate`, `weak`, or +`unknown`, with justifications drawn from the artifacts. + +| Verdict | Requirement or meaning | +| --- | --- | +| `go` | Problem validity and evidence strength are at least `adequate`, and a concept option is recommended | +| `needs-clarification` | Named unknowns block the decision; weak or unknown evidence, or a missing concept, cannot justify `go` | +| `kill` | The idea is not worth pursuing now; the decisive reason is recorded explicitly | + +Research must include evidence against the idea. Unsourced claims remain marked +as `ASSUMPTION`; do not invent citations or present uncertain evidence as fact. +A documented decision to stop is a useful result. + +## Refining an assessment + +Run each stage once in the usual flow. To resolve clarification markers or a +`needs-clarification` verdict, edit the affected Markdown directly or ask the +agent in free-form chat to incorporate the missing facts. Preserve sources and +confidence tags, then review dependent artifacts and revise `decision.md` as +needed. This is artifact refinement, not repeated command execution. + +Rerunning an earlier command is reserved for exceptions such as a wrong slug or +discarded draft. See the +[guided clarification example](../guides/assessment.md#resolve-unknowns-by-refining-the-artifacts). + +## Handoff and guardrails + +A `go` decision includes a handoff summary you can choose to pass to +`/speckit.specify`. No lifecycle hooks install assessment as a prerequisite of +SDD, and non-software ideas need not enter SDD at all. + +Assessment commands write only within `.specify/assessments//`; they do not +edit source code. The extension checks slugs and paths, treats fetched content +as untrusted data, and applies its URL trust policy. Consult the +[extension documentation](https://github.com/github/spec-kit/blob/main/extensions/assess/README.md) +for the complete guardrails and relationships to other extensions. diff --git a/docs/reference/agentic-bugfix.md b/docs/reference/agentic-bugfix.md index e43ac09491..0fad24388b 100644 --- a/docs/reference/agentic-bugfix.md +++ b/docs/reference/agentic-bugfix.md @@ -2,8 +2,13 @@ The **bug** extension adds a three-step bug triage process — assess, fix, and validate — that your coding agent runs alongside the core [Agentic SDD](agentic-sdd.md) process. Each bug lives in its own directory under `.specify/bugs//`, with one Markdown report per stage. +For a guided example, follow the [Bug Fixing Quickstart](../guides/bugfix.md). +Bug fixing does not require the SDD feature process first. For evaluating an idea +rather than repairing broken behavior, see +[Idea Assessment](agentic-assessment.md). + > [!NOTE] -> Commands are written in `/speckit.bug.*` form throughout this page. The exact invocation depends on your agent — some skills-based agents use `$speckit-bug-*` (e.g. Codex, ZCode) or `/skill:speckit-bug-*` (e.g. Kimi). Substitute the form your agent exposes. +> Commands are written in `/speckit.bug.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-bug-*`; some other agents use `$speckit-bug-*` (e.g. Codex, ZCode) or `/skill:speckit-bug-*` (e.g. Kimi). See [Command invocation](integrations.md#command-invocation). The bug extension is a bundled, opt-in extension. Install it before using these commands: diff --git a/docs/reference/agentic-sdd.md b/docs/reference/agentic-sdd.md index dc38e76a5a..7c8de58ff0 100644 --- a/docs/reference/agentic-sdd.md +++ b/docs/reference/agentic-sdd.md @@ -4,13 +4,37 @@ The `/speckit.*` slash commands drive the core Spec-Driven Development (SDD) pro The commands are designed to run in order, but only `/speckit.specify` is strictly required before `/speckit.plan`. The clarify, checklist, and analyze commands are quality gates you add for anything with meaningful ambiguity. +For evaluating an idea before committing to a specification, see +[Agentic Idea Assessment](agentic-assessment.md). Assessment is optional and +independent of the SDD process. + > [!NOTE] -> Commands are written in `/speckit.*` form throughout this page. The exact invocation depends on your agent — some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Substitute the form your agent exposes. +> Commands are written in `/speckit.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-*`; some other agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). See [Command invocation](integrations.md#command-invocation). ```text /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge ``` +## Command overview + +After `specify init`, these commands are available in the selected integration. +Integrations that support optional skills mode can select it with +`--integration-options="--skills"`; some integrations, including Copilot, use +skills by default. + +| Command | Agent skill | Purpose | +| --- | --- | --- | +| `/speckit.constitution` | `speckit-constitution` | Establish or update project principles | +| `/speckit.specify` | `speckit-specify` | Define requirements and user stories | +| `/speckit.plan` | `speckit-plan` | Create the technical implementation plan | +| `/speckit.tasks` | `speckit-tasks` | Break the plan into actionable tasks | +| `/speckit.implement` | `speckit-implement` | Execute the tasks | +| `/speckit.converge` | `speckit-converge` | Assess implementation against the artifacts and append remaining work | +| `/speckit.taskstoissues` | `speckit-taskstoissues` | Optionally convert tasks into GitHub issues | +| `/speckit.clarify` | `speckit-clarify` | Resolve ambiguity before planning (optional quality gate; formerly `/quizme`) | +| `/speckit.analyze` | `speckit-analyze` | Check artifact consistency after tasks and before implementation (optional quality gate) | +| `/speckit.checklist` | `speckit-checklist` | Generate requirements-quality checklists (optional quality gate) | + ## `/speckit.constitution` Creates or updates the project **constitution** — the guiding principles that every later phase is evaluated against — and keeps dependent templates in sync. Run it once up front and update it whenever your principles change. Pass the principles as arguments. @@ -19,6 +43,12 @@ Creates or updates the project **constitution** — the guiding principles that /speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns. ``` +For a more general starting point: + +```text +/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. +``` + ## `/speckit.specify` Creates or updates the feature **specification** from a natural-language description. Focus on the **what** and **why** — the user-facing behavior and goals — not the tech stack, which belongs in `/speckit.plan`. @@ -26,7 +56,7 @@ Creates or updates the feature **specification** from a natural-language descrip This workflow may also maintain `checklists/requirements.md`, the built-in spec-quality checklist that `/speckit.specify` creates and `/speckit.clarify` re-evaluates. That lifecycle is separate from custom checklists generated by `/speckit.checklist`. ```text -/speckit.specify Build an application that helps me organize photos into albums grouped by date, re-orderable by drag-and-drop on the main page, with a tile preview inside each album. +/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. ``` ## `/speckit.clarify` @@ -49,6 +79,12 @@ Runs the planning process to generate design artifacts from the spec. This is wh /speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications. ``` +For the photo-album example above: + +```text +/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. +``` + ## `/speckit.checklist` Generates a quality checklist for the feature — think of it as **"unit tests for your requirements."** Rather than testing code, it checks whether the spec itself is complete, clear, unambiguous, and consistent (for example: "Are the drag-and-drop rules defined for every column?", "Is behavior specified for a deleted assigned user?"). @@ -121,3 +157,17 @@ It first prints a severity-graded findings summary, then resolves to one of two - **Converged** — no gaps found. `tasks.md` is left byte-for-byte unchanged and you'll see a clean result like `✅ Converged — the implementation satisfies the spec, plan, and tasks.` You're done; proceed to review or open a PR. - **Tasks appended** — gaps found. Converge appends them as new tasks under a Convergence section in `tasks.md` and tells you how many. Run `/speckit.implement` again to complete them, then `/speckit.converge` once more. Each pass finds fewer items; repeat until it reports converged. + +## `/speckit.taskstoissues` + +Optionally converts an existing `tasks.md` into actionable GitHub issues. Run it +after generating tasks when you want to track execution in GitHub: + +```text +/speckit.taskstoissues +``` + +This command requires a GitHub `origin` remote and access to the GitHub MCP tools +for listing and creating issues. It creates issues only in the repository +identified by that remote and checks existing task IDs to avoid duplicates. +It is not required to implement tasks or converge on a feature. diff --git a/docs/reference/bundles.md b/docs/reference/bundles.md index 6035725c47..bb2a6aa7c7 100644 --- a/docs/reference/bundles.md +++ b/docs/reference/bundles.md @@ -4,6 +4,13 @@ Bundles compose existing Spec Kit components — extensions, presets, workflows, A bundle is described by a `bundle.yml` manifest and is discovered through the same catalog stack as other components. Installing a bundle resolves its declared components against pinned versions, checks for the single cross-bundle conflict point (the active integration), and applies each component idempotently with full provenance tracking so it can be cleanly removed or refreshed later. +For a concrete starting point, see the +[example bundle manifests](https://github.com/github/spec-kit/tree/main/examples/bundles) +for product managers, business analysts, security researchers, and developers. +These demonstrate packaging a role-based setup, not filled generated feature +specs; for end-to-end usage examples, see +[community walkthroughs](../community/walkthroughs.md). + ## Search Available Bundles ```bash @@ -141,6 +148,11 @@ If your bundle references components from non-default catalogs, document those c Bundles are discovered through a priority-ordered stack of catalog sources (project, user, and built-in scopes). +Each source has an install policy. `install-allowed` sources can be installed +from; `discovery-only` sources appear in `search` and `info` but refuse +installation. Inspect the active stack before installing a bundle from a +non-default source. + ### List the Catalog Stack ```bash diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 551f73c97e..5d95201980 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -48,6 +48,24 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify | [Zed](https://zed.dev/) | `zed` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `/speckit-` | | Generic | `generic` | Bring your own agent — use `--integration generic --integration-options="--commands-dir "` for AI coding agents not listed above | +## Command Invocation + +Run Spec Kit's process commands inside your coding agent, not in the terminal. +The steps are the same across integrations, but their spelling depends on the +agent and its installed mode: + +| Integration or mode | SDD example | Extension example | +| --- | --- | --- | +| GitHub Copilot, default skills mode | `/speckit-specify` | `/speckit-bug-assess` | +| Dotted slash-command notation used in the references | `/speckit.specify` | `/speckit.bug.assess` | +| Codex, Command Code, ZCode skills | `$speckit-specify` | `$speckit-bug-assess` | +| Kimi skills | `/skill:speckit-specify` | `/skill:speckit-bug-assess` | + +Use the form exposed by your agent. Copilot's default skills are installed under +`.github/skills/`; its opt-in commands layout is selected with +`--integration-options="--commands"`. In that layout, Copilot CLI can select an +agent through `/agents` or address it directly in a prompt. + ## List Available Integrations ```bash diff --git a/docs/reference/overview.md b/docs/reference/overview.md index 077eeb1d31..cbfd1c48a8 100644 --- a/docs/reference/overview.md +++ b/docs/reference/overview.md @@ -46,7 +46,12 @@ Bundles compose existing extensions, presets, workflows, and steps into a single ## Agentic Commands -The sections above cover primitives managed by the `specify` CLI. The following are the `/speckit.*` slash commands your coding agent runs step by step inside the editor — the agentic processes built on top of that foundation. +The sections above cover primitives managed by the `specify` CLI. The following +are independent processes your coding agent runs, not terminal commands. The +references use `/speckit.*` notation; see +[Command invocation](integrations.md#command-invocation) for your agent's syntax. +For guided examples, start with [SDD](../quickstart.md), +[bug fixing](../guides/bugfix.md), or [idea assessment](../guides/assessment.md). ### Agentic SDD @@ -59,3 +64,12 @@ The `/speckit.*` slash commands that drive the core Spec-Driven Development proc The bundled **bug** extension adds a three-step bug triage process — assess, fix, and validate — with each bug tracked in its own directory under `.specify/bugs/`. Install it with `specify extension add bug`. [Agentic Bug Fix reference →](agentic-bugfix.md) + +### Agentic Idea Assessment + +The bundled, opt-in **assess** extension evaluates an idea through intake, +research, definition, shaping, and a go / needs-clarification / kill decision. +It works without source code and does not require or automatically start SDD. +Install it with `specify extension add assess`. + +[Agentic Idea Assessment reference →](agentic-assessment.md) diff --git a/docs/toc.yml b/docs/toc.yml index c0a4264547..5a4e65ac5e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -11,10 +11,16 @@ items: - name: Installation href: installation.md - - name: Quick Start + - name: Spec-Driven Development href: quickstart.md + - name: Bug Fixing + href: guides/bugfix.md + - name: Idea Assessment + href: guides/assessment.md - name: Existing Projects href: guides/existing-projects.md + - name: Customize or Bring Your Own + href: guides/customization.md - name: Upgrade href: upgrade.md - name: Install uv @@ -51,6 +57,8 @@ href: reference/agentic-sdd.md - name: Agentic Bug Fix href: reference/agentic-bugfix.md + - name: Agentic Idea Assessment + href: reference/agentic-assessment.md - name: Authentication href: reference/authentication.md From 417a4d18c16a988c925e4e2bb869c47bda1c3ec2 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Mon, 14 Sep 2026 16:56:20 -0500 Subject: [PATCH 2/2] docs: distinguish agent skills from terminal setup Explicitly describe workflow steps as skills invoked in the agent chat, while reserving terminal instructions for CLI installation and project or extension setup. Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 19 +++++++++++-------- README.zh-CN.md | 18 ++++++++++-------- docs/guides/assessment.md | 5 +++-- docs/guides/bugfix.md | 5 +++-- docs/quickstart.md | 12 +++++++----- docs/reference/integrations.md | 4 +++- 6 files changed, 37 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 3ed5287a44..2cd0045f4c 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ core; bug fixing and assessment are bundled extensions you install when needed. 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. -Run this in your **terminal** to install the CLI from PyPI and create a project: +For **CLI setup only**, run this in your terminal to install Spec Kit and create a project: ```bash uv tool install specify-cli @@ -59,9 +59,10 @@ For pinned releases, other installers, CI, or troubleshooting, see To update an existing installation, see [Upgrade](https://github.github.io/spec-kit/upgrade.html). Now **launch your coding agent in the project directory** and choose a process -below. Run each `/speckit-*` command separately **in the agent**, not in your -terminal, and review the result before continuing. Other agents and modes may -use [different command syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +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). @@ -74,6 +75,8 @@ then guides implementation against those artifacts. **Constitution once per project; specify → plan → tasks → implement → converge per feature.** +Invoke these skills in your agent's chat: + ```text /speckit-constitution Create principles focused on code quality, testing, and maintainability. /speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album. @@ -98,13 +101,13 @@ quality gates. 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. -Install the opt-in extension **in your terminal**, from the project directory: +**CLI setup (terminal):** install the opt-in extension from the project directory: ```bash specify extension add bug ``` -Then run **assess → fix → test** in your coding agent: +Then invoke the **assess → fix → test** skills in your agent's chat: ```text /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash @@ -126,13 +129,13 @@ The reports live in `.specify/bugs/login-crash/`. Review the final verdict: 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. -Install the opt-in extension **in your terminal**, from the project directory: +**CLI setup (terminal):** install the opt-in extension from the project directory: ```bash specify extension add assess ``` -Then run **intake → research → define → shape → decide** in your coding agent: +Then invoke the **intake → research → define → shape → decide** skills in your agent's chat: ```text /speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode diff --git a/README.zh-CN.md b/README.zh-CN.md index aa1519eda7..3d7c069554 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -39,7 +39,7 @@ SDD 内置于核心；缺陷修复和想法评估由随工具提供的扩展实 你需要 **Python 3.11+**、**[uv](https://github.github.io/spec-kit/install/uv.html)** 以及受支持的 AI 编码助手，可在 Linux、macOS 或 Windows 上使用。 -在**终端**中从 PyPI 安装 CLI 并创建项目： +**仅 CLI 配置步骤在终端中执行**：从 PyPI 安装 Spec Kit 并创建项目： ```bash uv tool install specify-cli @@ -60,8 +60,8 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用 更新已安装的 CLI 和项目文件见[升级指南](https://github.github.io/spec-kit/upgrade.html)。 现在，在**项目目录中启动编码助手**，选择以下一种流程。 -每条 `/speckit-*` 命令都应在**助手中逐条运行，而不是在终端中运行**，检查结果后再继续。 -其他助手或模式可能采用[不同的命令语法](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)。 +在**助手的聊天界面中逐个调用 `/speckit-*` 技能**，检查结果后再继续。 +这些是助手技能，不是终端命令。其他助手或模式可能采用[不同的调用语法](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)。 @@ -77,6 +77,8 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用 **每个项目先确立一次准则；每个功能依次完成：规范 → 方案 → 任务 → 实现 → 收敛。** +在助手的聊天界面中调用以下技能： + ```text /speckit-constitution Create principles focused on code quality, testing, and maintainability. /speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album. @@ -97,13 +99,13 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用 将诊断、修复和验证分开，让助手针对评估出的原因修复，并检查最初出现的症状。 无需先走一遍 SDD 功能开发流程。 -在项目目录下的**终端**中安装这个可选扩展： +**CLI 配置（终端）**：在项目目录下安装这个可选扩展： ```bash specify extension add bug ``` -然后在编码助手中依次运行 **assess → fix → test**（评估 → 修复 → 测试）： +然后在助手的聊天界面中依次调用 **assess → fix → test**（评估 → 修复 → 测试）技能： ```text /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash @@ -122,14 +124,14 @@ specify extension add bug 在投入之前先收集证据，无论这个想法最终是否会成为软件。 这是一个独立流程，也适用于非软件类想法，即使项目中没有源代码也能使用。 -在项目目录下的**终端**中安装这个可选扩展： +**CLI 配置（终端）**：在项目目录下安装这个可选扩展： ```bash specify extension add assess ``` -然后在编码助手中依次运行 **intake → research → define → shape → decide** -（收集想法 → 调研 → 定义问题 → 形成方案 → 决策）： +然后在助手的聊天界面中依次调用 **intake → research → define → shape → decide** +（收集想法 → 调研 → 定义问题 → 形成方案 → 决策）技能： ```text /speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode diff --git a/docs/guides/assessment.md b/docs/guides/assessment.md index 2b13b00a6d..171de767e7 100644 --- a/docs/guides/assessment.md +++ b/docs/guides/assessment.md @@ -23,8 +23,9 @@ Then launch your coding agent in that directory. The examples below use GitHub Copilot's default skills mode (`--integration copilot`). Other agents use their own [command invocation syntax](../reference/integrations.md#command-invocation). -Run each command separately in the agent, not in your terminal, reviewing the -artifact before moving on. +Invoke each `/speckit-assess-*` skill separately in your agent's chat, reviewing +the artifact before moving on. These are agent skills, not terminal commands; +the terminal command above only installs the extension. ## 1. Capture the idea diff --git a/docs/guides/bugfix.md b/docs/guides/bugfix.md index ebe54b003c..b1f0effff3 100644 --- a/docs/guides/bugfix.md +++ b/docs/guides/bugfix.md @@ -24,8 +24,9 @@ Then launch your coding agent in that directory. The examples below use GitHub Copilot's default skills mode (`--integration copilot`). Other agents expose the same steps using their own [command invocation syntax](../reference/integrations.md#command-invocation). -Run each command separately in the agent, not in your terminal, and review its -output before continuing. +Invoke each `/speckit-bug-*` skill separately in your agent's chat and review its +output before continuing. These are agent skills, not terminal commands; the +terminal command above only installs the extension. ## 1. Assess the bug diff --git a/docs/quickstart.md b/docs/quickstart.md index d4304dcf2e..692d725a55 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -12,18 +12,19 @@ These are independent processes, not prerequisites for this guide. > [!NOTE] > Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs (no TTY, or `--non-interactive`) default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly. -Commands here use GitHub Copilot's default skills mode (`/speckit-*`). +The process steps here use GitHub Copilot's default skills mode (`/speckit-*`). For other agents or modes, see [Command invocation](reference/integrations.md#command-invocation). -Run each process command separately inside the coding agent, not in your terminal, -and review the result before moving to the next step. +Invoke each `/speckit-*` skill separately in your agent's chat and review the +result before moving to the next step. These are agent skills, not terminal +commands; only CLI installation and project setup use the terminal. ## Recommended Process > [!TIP] > **Context Awareness**: Spec Kit tracks the active feature by the feature directory recorded in `.specify/feature.json` (overridable with the `SPECIFY_FEATURE_DIRECTORY` environment variable). Commands resolve the feature from that state, **not** from the checked-out Git branch — no Git required. The opt-in **git** extension adds numbered feature branches (e.g. `001-feature-name`) for organizing work in version control, but the active feature is still whichever directory that state points to; `git checkout` alone does not change it. To point commands at a different feature, update `.specify/feature.json` (or set `SPECIFY_FEATURE_DIRECTORY`). -After installing Spec Kit, each command below is a step in the process. Two paths are common: +After installing Spec Kit, each skill below is a step in the process. Two paths are common: Establish a constitution once per project with `/speckit-constitution` before starting either path. @@ -66,7 +67,8 @@ cd taskify > [Adopting Spec Kit in an Existing Project](guides/existing-projects.md) before > starting the workflow below. -Launch your coding agent in the project directory before continuing. +Launch your coding agent in the project directory. Invoke the following skills +in its chat, one at a time. diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 5d95201980..35aef8f253 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -50,7 +50,9 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify ## Command Invocation -Run Spec Kit's process commands inside your coding agent, not in the terminal. +Invoke Spec Kit's process steps inside your coding agent, not in the terminal. +In GitHub Copilot's default mode, these are skills you invoke in the agent's +chat. CLI installation and setup commands are separate terminal operations. The steps are the same across integrations, but their spelling depends on the agent and its installed mode: