Skip to content

Commit 0a121b0

Browse files
pchemguyCopilot
pchemguy
and
Copilot
authored
Readme clarity (#2013)
* Specify CLI Reference formatting Improves formatting of Specify CLI Reference * Available Slash Commands clarity Improve "Available Slash Commands" clarity in README.md. * Add extension/preset commands to cli reference * Extensions & Presets section clarity Improves Extensions & Presets section clarity in README.md * Removes `$` from Agent Skill * Reverts Supported AI Agents Table * Added missing Agent Skill column * Trailing whitespaces Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Adds missing code block language Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Revised wording Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Revised specify synopsis * Update specify command reference table Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Removes extra (duplicate) slashes * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Removed old section * missing /speckit.taskstoissues * integration command Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 6af2e64 commit 0a121b0

File tree

1 file changed

+60
-55
lines changed

1 file changed

+60
-55
lines changed

‎README.md‎

Lines changed: 60 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,6 @@ Community projects that extend, visualize, or build on Spec Kit:
289289
- **[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.
290290

291291
## 🤖 Supported AI Agents
292-
293292
| Agent | Support | Notes |
294293
| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
295294
| [Qoder CLI](https://qoder.com/cli) | ✅ | |
@@ -321,22 +320,63 @@ Community projects that extend, visualize, or build on Spec Kit:
321320
| [Trae](https://www.trae.ai/) | ✅ | |
322321
| Generic | ✅ | Bring your own agent — use `--ai generic --ai-commands-dir <path>` for unsupported agents |
323322

323+
## Available Slash Commands
324+
325+
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`.
326+
327+
#### Core Commands
328+
329+
Essential commands for the Spec-Driven Development workflow:
330+
331+
| Command | Agent Skill | Description |
332+
| ------------------------ | ---------------------- | -------------------------------------------------------------------------- |
333+
| `/speckit.constitution` | `speckit-constitution` | Create or update project governing principles and development guidelines |
334+
| `/speckit.specify` | `speckit-specify` | Define what you want to build (requirements and user stories) |
335+
| `/speckit.plan` | `speckit-plan` | Create technical implementation plans with your chosen tech stack |
336+
| `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation |
337+
| `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution |
338+
| `/speckit.implement` | `speckit-implement` | Execute all tasks to build the feature according to the plan |
339+
340+
#### Optional Commands
341+
342+
Additional commands for enhanced quality and validation:
343+
344+
| Command | Agent Skill | Description |
345+
| -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
346+
| `/speckit.clarify` | `speckit-clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) |
347+
| `/speckit.analyze` | `speckit-analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) |
348+
| `/speckit.checklist` | `speckit-checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
349+
324350
## 🔧 Specify CLI Reference
325351

326-
The `specify` command supports the following options:
352+
The `specify` tool is invoked as
353+
354+
```text
355+
specify <COMMAND> [SUBCOMMAND] [OPTIONS]
356+
```
357+
358+
and supports the following commands:
327359

328360
### Commands
329361

330-
| Command | Description |
331-
| ------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
332-
| `init` | Initialize a new Specify project from the latest template |
333-
| `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.) |
362+
| Command | Description |
363+
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
364+
| `init` | Initialize a new Specify project from the latest template. |
365+
| `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.) |
366+
| `version` | Show the currently installed Spec Kit version. |
367+
| `extension` | Manage extensions |
368+
| `preset` | Manage presets |
369+
| `integration` | Manage integrations |
334370

335371
### `specify init` Arguments & Options
336372

373+
```bash
374+
specify init [PROJECT_NAME] <OPTIONS>
375+
```
376+
337377
| Argument/Option | Type | Description |
338-
| ---------------------- | -------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
339-
| `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
378+
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
379+
| `<PROJECT_NAME>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
340380
| `--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`) |
341381
| `--ai-commands-dir` | Option | Directory for agent command files (required with `--ai generic`, e.g. `.myagent/commands/`) |
342382
| `--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
433473
specify check
434474
```
435475

436-
### Available Slash Commands
437-
438-
After running `specify init`, your AI coding agent will have access to these structured development commands.
439-
440-
Most agents expose the traditional dotted slash commands shown below, like `/speckit.plan`.
441-
442-
Claude Code installs spec-kit as skills and invokes them as `/speckit-constitution`, `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, and `/speckit-implement`.
443-
444-
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`.
445-
446-
#### Core Commands
447-
448-
Essential commands for the Spec-Driven Development workflow:
449-
450-
| Command | Description |
451-
| ----------------------- | ------------------------------------------------------------------------ |
452-
| `/speckit.constitution` | Create or update project governing principles and development guidelines |
453-
| `/speckit.specify` | Define what you want to build (requirements and user stories) |
454-
| `/speckit.plan` | Create technical implementation plans with your chosen tech stack |
455-
| `/speckit.tasks` | Generate actionable task lists for implementation |
456-
| `/speckit.implement` | Execute all tasks to build the feature according to the plan |
457-
458-
#### Optional Commands
459-
460-
Additional commands for enhanced quality and validation:
461-
462-
| Command | Description |
463-
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
464-
| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) |
465-
| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) |
466-
| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
467-
468476
### Environment Variables
469477

470478
| Variable | Description |
@@ -475,21 +483,18 @@ Additional commands for enhanced quality and validation:
475483

476484
Spec Kit can be tailored to your needs through two complementary systems — **extensions** and **presets** — plus project-local overrides for one-off adjustments:
477485

478-
```mermaid
479-
block-beta
480-
columns 1
481-
overrides["⬆ Highest priority\nProject-Local Overrides\n.specify/templates/overrides/"]
482-
presets["Presets — Customize core & extensions\n.specify/presets/<preset-id>/templates/"]
483-
extensions["Extensions — Add new capabilities\n.specify/extensions/<ext-id>/templates/"]
484-
core["Spec Kit Core — Built-in SDD commands & templates\n.specify/templates/\n⬇ Lowest priority"]
485-
486-
style overrides fill:transparent,stroke:#999
487-
style presets fill:transparent,stroke:#4a9eda
488-
style extensions fill:transparent,stroke:#4a9e4a
489-
style core fill:transparent,stroke:#e6a817
490-
```
491-
492-
**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.
486+
| Priority | Component Type | Location |
487+
| -------: | ------------------------------------------------- | -------------------------------- |
488+
| ⬆ 1 | Project-Local Overrides | `.specify/templates/overrides/` |
489+
| 2 | Presets — Customize core & extensions | `.specify/presets/templates/` |
490+
| 3 | Extensions — Add new capabilities | `.specify/extensions/templates/` |
491+
| ⬇ 4 | Spec Kit Core — Built-in SDD commands & templates | `.specify/templates/` |
492+
493+
- **Templates** are resolved at **runtime** — Spec Kit walks the stack top-down and uses the first match.
494+
- Project-local overrides (`.specify/templates/overrides/`) let you make one-off adjustments for a single project without creating a full preset.
495+
- **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/`).
496+
- If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically.
497+
- If no overrides or customizations exist, Spec Kit uses its core defaults.
493498

494499
### Extensions — Add New Capabilities
495500

0 commit comments

Comments
 (0)