mirror of
https://github.com/github/spec-kit.git
synced 2026-08-15 14:02:04 +02:00
docs: reframe SDD positioning, modernize install, and de-duplicate walkthroughs (#3565)
* docs: reframe SDD positioning, modernize install, and de-duplicate walkthroughs Reframe the landing page so Spec Kit reads as a toolkit for Spec-Driven Development *or your own process* with any AI coding agent, and correct stale claims: context files and git are now opt-in extensions, and the install path uses PyPI (specify-cli). Generalize the landing cards to cover bundles and catalog hosting across all primitives. Restructure the Quick Start into a lean, guided Taskify walkthrough with one command per step (install as a prerequisite, Steps 1-9 aligned with the Full path), and extract the deep per-command detail into two new reference pages: reference/agentic-sdd.md (the /speckit.* SDD process) and reference/agentic-bugfix.md (the bug extension). Retitle the reference overview to "Reference" and group these agentic processes in their own section, distinct from CLI-managed primitives. Remove the duplicated "Detailed Process" walkthrough from README.md (and its TOC entry), repointing readers to the docs-site Quick Start while keeping the concise "Get Started" section as the front door. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89 * docs: address review feedback on accuracy and scope - quickstart: correct the git/feature note — resolution reads .specify/feature.json / SPECIFY_FEATURE, not the checked-out branch, so switching branches alone does not switch the active feature. - quickstart + agentic-sdd: add an invocation-style note ($speckit-* for Codex/ZCode, /skill:speckit-* for Kimi) so the agent-neutral commands are executable everywhere. - agentic-sdd: fix the tasks phase structure to match the generator (Setup, Foundational, one phase per user story, final Polish; tests optional within user-story phases). - index: soften the catalog claim (catalogs curate discovery, not an install allow-list) and relabel the "CLI reference" link to "Reference" to match the retitled, broader page. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89 * docs: correct feature-resolution override and add bug-command invocation note - quickstart: the previous fix named the wrong override. The active feature *directory* resolves from SPECIFY_FEATURE_DIRECTORY then .specify/feature.json; SPECIFY_FEATURE only supplies the identifier after a directory is resolved. Rewrite the note to point users at .specify/feature.json / SPECIFY_FEATURE_DIRECTORY, and clarify the git extension's branches don't by themselves change the active feature. - agentic-bugfix: add the same invocation-style caveat as the SDD reference ($speckit-bug-* for Codex/ZCode, /skill:speckit-bug-* for Kimi). Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89 * docs: tighten bug-command contracts and drop numbered-phase examples - agentic-bugfix: don't overstate overwrite protection — an interactive run can overwrite an existing assessment after confirmation; only automated mode refuses and picks a new slug. Correct the verify verdict to the schema's verified/partial/failed (not-run is a per-check status); an unexercised reproduction downgrades the result to partial. - agentic-sdd: the implement examples labeled scoping "Phase 1/2", but the tasks contract reserves Phase 1 for Setup and Phase 2 for Foundational (user stories start at Phase 3). Scope by phase name and user-story content instead to avoid mis-scoping execution. Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89 --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Manfred Riem
co-authored by
Copilot App
Copilot App
parent
b08d665837
commit
396fc2c240
@@ -0,0 +1,52 @@
|
||||
# Agentic Bug Fix
|
||||
|
||||
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/<slug>/`, with one Markdown report per stage.
|
||||
|
||||
> [!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.
|
||||
|
||||
The bug extension is a bundled, opt-in extension. Install it before using these commands:
|
||||
|
||||
```bash
|
||||
specify extension add bug
|
||||
```
|
||||
|
||||
The three commands share a single handle — the **slug**, the per-bug directory name under `.specify/bugs/`. Supply it with `slug=<name>`; if omitted, `/speckit.bug.assess` asks for one (or generates a unique one in automated mode). Slugs are normalized to lowercase kebab-case. If an assessment already exists for a slug, an interactive run asks before overwriting it, while an automated run refuses and picks a new unique slug instead.
|
||||
|
||||
```text
|
||||
/speckit.bug.assess -> /speckit.bug.fix -> /speckit.bug.test
|
||||
```
|
||||
|
||||
## `/speckit.bug.assess`
|
||||
|
||||
Triages a bug report — pasted text (such as a stack trace) or a URL (such as a GitHub issue) — against the codebase: it judges whether the report is a real bug, locates the suspected code paths, and proposes a remediation. This command is **read-only**: it writes only `assessment.md` and never modifies source code.
|
||||
|
||||
```text
|
||||
/speckit.bug.assess "TypeError: cannot read properties of undefined (reading 'token') at /auth/callback"
|
||||
```
|
||||
|
||||
```text
|
||||
/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token
|
||||
```
|
||||
|
||||
Output: `.specify/bugs/<slug>/assessment.md`.
|
||||
|
||||
## `/speckit.bug.fix`
|
||||
|
||||
Applies the remediation described in the assessment and records exactly what changed. This is the **only** bug command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (logged under **Deviations from Assessment**).
|
||||
|
||||
```text
|
||||
/speckit.bug.fix slug=callback-token
|
||||
```
|
||||
|
||||
Output: `.specify/bugs/<slug>/fix.md`.
|
||||
|
||||
## `/speckit.bug.test`
|
||||
|
||||
Validates the fix by re-running the reproduction and any added tests, then records the verification result — one of `verified`, `partial`, or `failed`. Like `assess`, it is **read-only** with respect to source code. Verdicts are never over-claimed: if the assessment listed a reproduction that wasn't actually exercised, the overall result is downgraded to `partial` rather than reported as `verified`.
|
||||
|
||||
```text
|
||||
/speckit.bug.test slug=callback-token
|
||||
```
|
||||
|
||||
Output: `.specify/bugs/<slug>/test.md`.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Agentic SDD
|
||||
|
||||
The `/speckit.*` slash commands drive the core Spec-Driven Development (SDD) process — an **agentic process** your coding agent runs step by step. For a guided, end-to-end run see the [Quick Start Guide](../quickstart.md); this page is the detailed reference for each command — including arguments, output, and how they interact. For the philosophy behind the process, see [What is SDD?](../concepts/sdd.md). For bug triage, see [Agentic Bug Fix](agentic-bugfix.md).
|
||||
|
||||
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.
|
||||
|
||||
> [!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.
|
||||
|
||||
```text
|
||||
/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge
|
||||
```
|
||||
|
||||
## `/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.
|
||||
|
||||
```text
|
||||
/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.
|
||||
```
|
||||
|
||||
## `/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`.
|
||||
|
||||
```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.clarify`
|
||||
|
||||
Asks up to five targeted questions about underspecified areas of the current spec and encodes your answers back into `spec.md`. Run it as many times as needed before planning, each time tackling a different area. Optionally pass a focus area as an argument.
|
||||
|
||||
```text
|
||||
/speckit.clarify Focus on the task card behavior: status changes, comment limits, and who can be assigned.
|
||||
```
|
||||
|
||||
Clarifying before planning keeps you from designing on top of ambiguity. If `/speckit.analyze` later surfaces requirement gaps, come back and run `/speckit.clarify` (or `/speckit.specify`) again.
|
||||
|
||||
## `/speckit.plan`
|
||||
|
||||
Runs the planning process to generate design artifacts from the spec. This is where implementation detail belongs — provide your tech stack, architecture, and technical constraints as arguments.
|
||||
|
||||
```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.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?").
|
||||
|
||||
Run it with no arguments for a broad pass, or pass a focus area to target one aspect:
|
||||
|
||||
```text
|
||||
/speckit.checklist
|
||||
```
|
||||
|
||||
```text
|
||||
/speckit.checklist Focus on the Kanban board interactions and comment permissions.
|
||||
```
|
||||
|
||||
Review the generated checklist. If it surfaces gaps, loop back to `/speckit.clarify` or `/speckit.specify` to tighten the spec before breaking the work down.
|
||||
|
||||
## `/speckit.tasks`
|
||||
|
||||
Generates an actionable, dependency-ordered `tasks.md` from the design artifacts. Tasks are organized into phases: **Setup**, **Foundational** (blocking prerequisites), then **one phase per user story** in priority order, and a final **Polish** phase for cross-cutting concerns. Tests are generated within a user story's phase when requested rather than as a separate phase, and tasks are marked for parallel execution where possible.
|
||||
|
||||
```text
|
||||
/speckit.tasks
|
||||
```
|
||||
|
||||
## `/speckit.analyze`
|
||||
|
||||
Performs a **read-only** cross-artifact consistency and quality analysis across `spec.md`, `plan.md`, and `tasks.md`, reporting conflicts, gaps, and ambiguities (for example a task with no matching requirement, or a plan choice that contradicts the spec). It never edits files — it produces a report and can optionally suggest remediations for you to approve.
|
||||
|
||||
```text
|
||||
/speckit.analyze
|
||||
```
|
||||
|
||||
Run it before implementing, while the artifacts can still be adjusted cheaply. If it surfaces issues, **return to the earlier step that owns them** and fix them at the source — `/speckit.specify` or `/speckit.clarify` for requirement problems, `/speckit.plan` for design problems, `/speckit.tasks` to regenerate the task list — then re-run `/speckit.analyze` until it comes back clean. You can also run `/speckit.analyze` again after implementation as an extra review.
|
||||
|
||||
## `/speckit.implement`
|
||||
|
||||
Executes the tasks in `tasks.md`, running each phase in dependency order and respecting parallel markers.
|
||||
|
||||
For a small feature, run it once to build everything:
|
||||
|
||||
```text
|
||||
/speckit.implement
|
||||
```
|
||||
|
||||
For a large feature, work in stages to avoid overwhelming the agent's context — scope each run with an argument, validate the result, then continue:
|
||||
|
||||
```text
|
||||
/speckit.implement Implement only the Setup and Foundational phases: project scaffolding and the project/task data model with basic CRUD. Stop before the user-story features.
|
||||
```
|
||||
|
||||
```text
|
||||
/speckit.implement Now implement the Kanban board user story: drag-and-drop between columns.
|
||||
```
|
||||
|
||||
Verify each stage works before moving to the next.
|
||||
|
||||
## `/speckit.converge`
|
||||
|
||||
Assesses the codebase against the feature's spec, plan, and tasks to confirm nothing was missed. It is **append-only**: it never edits or deletes code, and its only possible write is adding tasks to `tasks.md`. Run it only after `/speckit.implement` has run on the current `tasks.md`.
|
||||
|
||||
```text
|
||||
/speckit.converge
|
||||
```
|
||||
|
||||
It first prints a severity-graded findings summary, then resolves to one of two outcomes:
|
||||
|
||||
- **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.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Supported AI Coding Agent Integrations
|
||||
|
||||
The Specify CLI supports a wide range of AI coding agents. When you run `specify init`, the CLI sets up the appropriate command files, context rules, and directory structures for your chosen AI coding agent — so you can start using Spec-Driven Development immediately, regardless of which tool you prefer.
|
||||
The Specify CLI supports a wide range of AI coding agents. When you run `specify init`, the CLI sets up the appropriate command files and directory structures for your chosen AI coding agent — so you can start using Spec-Driven Development immediately, regardless of which tool you prefer.
|
||||
|
||||
## Supported AI Coding Agents
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# CLI Reference
|
||||
# Reference
|
||||
|
||||
The Specify CLI (`specify`) manages the full lifecycle of Spec-Driven Development — from project initialization to workflow automation.
|
||||
The Specify CLI (`specify`) manages the full lifecycle of Spec-Driven Development — from project initialization to workflow automation. This section is the detailed reference for the CLI's commands and primitives, plus the agentic `/speckit.*` processes your coding agent runs.
|
||||
|
||||
## Core Commands
|
||||
|
||||
@@ -10,7 +10,7 @@ The foundational commands for creating and managing Spec Kit projects. Initializ
|
||||
|
||||
## Integrations
|
||||
|
||||
Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files, context rules, and directory structures for a specific agent. Only one integration is active per project at a time, and you can switch between them at any point.
|
||||
Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files and directory structures for a specific agent. Only one integration is active per project at a time, and you can switch between them at any point.
|
||||
|
||||
[Integrations reference →](integrations.md)
|
||||
|
||||
@@ -37,3 +37,19 @@ Workflows automate multi-step Spec-Driven Development processes into repeatable
|
||||
Bundles compose existing extensions, presets, workflows, and steps into a single, versioned, installable unit. Rather than adding new behavior, a bundle curates a stack of primitives — everything a team or role needs — and installs it in one step through each component's own machinery, with version pinning, conflict checks, and provenance tracking for clean updates and removal.
|
||||
|
||||
[Bundles reference →](bundles.md)
|
||||
|
||||
## 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.
|
||||
|
||||
### Agentic SDD
|
||||
|
||||
The `/speckit.*` slash commands that drive the core Spec-Driven Development process your coding agent runs step by step: constitution, specify, clarify, plan, checklist, tasks, analyze, implement, and converge. Run them in order, adding the clarify/checklist/analyze quality gates for anything with meaningful ambiguity.
|
||||
|
||||
[Agentic SDD reference →](agentic-sdd.md)
|
||||
|
||||
### Agentic Bug Fix
|
||||
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user