Skip to content

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

Readme clarity (#2013)

PChemGuy0a121b073cdc
diff --git a/README.md b/README.md
index 9301fbaf8..22518ca43 100644
--- a/README.md
+++ b/README.md
@@ -289,7 +289,6 @@ Community projects that extend, visualize, or build on Spec Kit:
- **[SpecKit Companion](https://marketplace.visualstudio.com/items?itemName=alfredoperez.speckit-companion)** β€” A VS Code extension that brings a visual GUI to Spec Kit. Browse specs in a rich markdown viewer with clickable file references, create specifications with image attachments, comment and refine each step inline (GitHub-style review), track your progress through the SDD workflow with a visual phase stepper, and manage steering documents like constitutions and templates.
## πŸ€– Supported AI Agents
-
| Agent | Support | Notes |
| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Qoder CLI](https://qoder.com/cli) | βœ… | |
@@ -321,22 +320,63 @@ Community projects that extend, visualize, or build on Spec Kit:
| [Trae](https://www.trae.ai/) | βœ… | |
| Generic | βœ… | Bring your own agent β€” use `--ai generic --ai-commands-dir <path>` for unsupported agents |
+## Available Slash Commands
+
+After running `specify init`, your AI coding agent will have access to these slash commands for structured development. If you pass `--ai <agent> --ai-skills`, Spec Kit installs agent skills instead of slash-command prompt files; `--ai-skills` requires `--ai`.
+
+#### 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 |
+
+#### 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
-The `specify` command supports the following options:
+The `specify` tool is invoked as
+
+```text
+specify <COMMAND> [SUBCOMMAND] [OPTIONS]
+```
+
+and supports the following commands:
### Commands
-| Command | Description |
-| ------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `init` | Initialize a new Specify project from the latest template |
-| `check` | Check for installed tools: `git` plus all CLI-based agents configured in `AGENT_CONFIG` (for example: `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `junie`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, etc.) |
+| Command | Description |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init` | Initialize a new Specify project from the latest template. |
+| `check` | Check for installed tools: `git` plus all CLI-based agents configured in `AGENT_CONFIG` (for example: `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `junie`, `qwen`, `opencode`, `codex`, `kiro-cli`, `shai`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, etc.) |
+| `version` | Show the currently installed Spec Kit version. |
+| `extension` | Manage extensions |
+| `preset` | Manage presets |
+| `integration` | Manage integrations |
### `specify init` Arguments & Options
+```bash
+specify init [PROJECT_NAME] <OPTIONS>
+```
+
| Argument/Option | Type | Description |
-| ---------------------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
+| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<PROJECT_NAME>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
| `--ai` | Option | AI assistant to use (see `AGENT_CONFIG` for the full, up-to-date list). Common options include: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `junie`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `kiro-cli` (`kiro` alias), `agy`, `bob`, `qodercli`, `vibe`, `kimi`, `iflow`, `pi`, `forge`, or `generic` (requires `--ai-commands-dir`) |
| `--ai-commands-dir` | Option | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`) |
| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) |
@@ -433,38 +473,6 @@ specify init my-project --ai claude --branch-numbering timestamp
specify check
```
-### Available Slash Commands
-
-After running `specify init`, your AI coding agent will have access to these structured development commands.
-
-Most agents expose the traditional dotted slash commands shown below, like `/speckit.plan`.
-
-Claude Code installs spec-kit as skills and invokes them as `/speckit-constitution`, `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, and `/speckit-implement`.
-
-For Codex CLI, `--ai-skills` installs spec-kit as agent skills instead of slash-command prompt files. In Codex skills mode, invoke spec-kit as `$speckit-constitution`, `$speckit-specify`, `$speckit-plan`, `$speckit-tasks`, and `$speckit-implement`.
-
-#### Core Commands
-
-Essential commands for the Spec-Driven Development workflow:
-
-| Command | Description |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `/speckit.constitution` | Create or update project governing principles and development guidelines |
-| `/speckit.specify` | Define what you want to build (requirements and user stories) |
-| `/speckit.plan` | Create technical implementation plans with your chosen tech stack |
-| `/speckit.tasks` | Generate actionable task lists for implementation |
-| `/speckit.implement` | Execute all tasks to build the feature according to the plan |
-
-#### Optional Commands
-
-Additional commands for enhanced quality and validation:
-
-| Command | Description |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) |
-| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) |
-| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
-
### Environment Variables
| Variable | Description |
@@ -475,21 +483,18 @@ Additional commands for enhanced quality and validation:
Spec Kit can be tailored to your needs through two complementary systems β€” **extensions** and **presets** β€” plus project-local overrides for one-off adjustments:
-```mermaid
-block-beta
- columns 1
- overrides["⬆ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"]
- presets["Presets β€” Customize core & extensions\n.specify/presets/<preset-id>/templates/"]
- extensions["Extensions β€” Add new capabilities\n.specify/extensions/<ext-id>/templates/"]
- core["Spec Kit Core β€” Built-in SDD commands & templates\n.specify/templates/\n⬇ Lowest priority"]
-
- style overrides fill:transparent,stroke:#999
- style presets fill:transparent,stroke:#4a9eda
- style extensions fill:transparent,stroke:#4a9e4a
- style core fill:transparent,stroke:#e6a817
-```
-
-**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. **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.
+| 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