Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: add workflow quickstarts (#4258)

Manfred Riem3f773571077a
diff --git a/README.md b/README.md
index de92639ce..c4418bf03 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,8 @@
## 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)
@@ -45,6 +47,75 @@
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/[email protected]
+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/[email protected]
+specify init my-project --integration copilot
+cd my-project
+specify extension add bug
+```
+
+Launch your coding agent in the project directory, then:
+
+1. **Assess** the bug (`/speckit-bug-assess "<bug report>" slug=login-crash`).
+2. **Fix** the assessed cause (`/speckit-bug-fix slug=login-crash`).
+3. **Test** the fix (`/speckit-bug-test slug=login-crash`).
+
+## πŸ’‘ Assessing Ideas with Spec Kit
+
+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
+
+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/[email protected]
+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 "<idea>" 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