Skip to content

Readme clarity #2013

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pchemguy wants to merge 19 commits into
base: main
Choose a base branch
from
Open

Readme clarity #2013

Changes from 15 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
5ab58a9
Specify CLI Reference formatting
pchemguy Mar 28, 2026
b5a613f
Available Slash Commands clarity
pchemguy Mar 28, 2026
0a425e7
Add extension/preset commands to cli reference
pchemguy Mar 28, 2026
f758eb7
Extensions & Presets section clarity
pchemguy Mar 28, 2026
dc8aca6
Removes `$` from Agent Skill
pchemguy Mar 30, 2026
c5ff2f3
Reverts Supported AI Agents Table
pchemguy Mar 30, 2026
285bfdd
Added missing Agent Skill column
pchemguy Mar 30, 2026
c43a938
Trailing whitespaces
pchemguy Mar 30, 2026
92c058e
Adds missing code block language
pchemguy Mar 30, 2026
03e90fd
Revised wording
pchemguy Mar 30, 2026
0b70160
Revised specify synopsis
pchemguy Mar 30, 2026
2c3b0bc
Merge branch 'readme-formatting' of https://github.com/pchemguy/spec-…
pchemguy Mar 30, 2026
f122b45
Update specify command reference table
pchemguy Mar 30, 2026
2a8e430
Removes extra (duplicate) slashes
pchemguy Mar 30, 2026
780d125
Merge branch 'readme-formatting' of https://github.com/pchemguy/spec-…
pchemguy Mar 30, 2026
1c16967
Merge remote-tracking branch 'origin/main' into readme-formatting
pchemguy Apr 9, 2026
625aabf
Update README.md
pchemguy Apr 9, 2026
843f428
Removed old section
pchemguy Apr 9, 2026
1f5554d
missing /speckit.taskstoissues
pchemguy Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 59 additions & 52 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,6 @@ Community projects that extend, visualize, or build on Spec Kit:
- **[Spec Kit Assistant](https://marketplace.visualstudio.com/items?itemName=rfsales.speckit-assistant)** — A VS Code extension that provides a visual orchestrator for the full SDD workflow (constitution → specification → planning → tasks → implementation) with phase status visualization, an interactive task checklist, DAG visualization, and support for Claude, Gemini, GitHub Copilot, and OpenAI backends. Requires the `specify` CLI in your PATH.

## 🤖 Supported AI Agents

| Agent | Support | Notes |
| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Qoder CLI](https://qoder.com/cli) | ✅ | |
Expand Down Expand Up @@ -284,22 +283,61 @@ 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-skills`, Spec Kit 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-plan` | Define what you want to build (requirements and user stories) |
| `/speckit.plan` | `speckit-tasks` | Create technical implementation plans with your chosen tech stack |
| `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation |
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new “Available Slash Commands” section duplicates the later command list in the README (there’s another “Core Commands / Optional Commands” block further down around the “Environment Variables” section). Having two separate lists increases the risk they drift (e.g., skills vs slash commands nuance). Consider consolidating to a single canonical list and linking to it from here, or removing the later block if this is meant to replace it.

Suggested change
After running `specify init`, your AI coding agent will have access to these slash commands for structured development. If you pass `--ai-skills`, Spec Kit 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-plan` | Define what you want to build (requirements and user stories) |
| `/speckit.plan` | `speckit-tasks` | Create technical implementation plans with your chosen tech stack |
| `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation |
After running `specify init`, your AI coding agent will have access to Spec Kit slash commands for structured development. If you pass `--ai-skills`, Spec Kit installs agent skills instead of slash-command prompt files.
For the canonical list of available commands and their agent-skill equivalents, see the **Core Commands / Optional Commands** section later in this README.

Copilot uses AI. Check for mistakes.
| `/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") |
Comment on lines +341 to +345
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Available Slash Commands” tables don’t include /speckit.taskstoissues / speckit-taskstoissues, even though templates/commands/taskstoissues.md ships with the core and is referenced elsewhere in the README (Pi agent note about taskstoissues). If this section is intended to enumerate what specify init installs, consider adding taskstoissues under Optional Commands (or explicitly calling out that it’s omitted/conditional).

Suggested change
| 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") |
| 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") |
| `/speckit.taskstoissues` | `speckit-taskstoissues` | Convert generated task lists into GitHub issues for tracking and execution |

Copilot uses AI. Check for mistakes.

## 🔧 Specify CLI Reference

The `specify` command supports the following options:
The `specify` tool is invoked as

```bash
specify <COMMAND> <OPTIONAL_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`, 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`, etc.). This command does not have any additional options. |
| `version` | Show the currently installed Spec Kit version. |
| `extension` | Manage extensions |
| `preset` | Manage presets |
Comment on lines +359 to +365
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CLI command table appears incomplete: the specify CLI also has an integration top-level command group (e.g., specify integration list/install/uninstall/switch). Since the text says “supports the following commands”, please add integration to this list (or clarify that the table is a partial subset).

Suggested change
| 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 |
| 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 |
| `integration` | Manage integrations |
| `preset` | Manage presets |

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor Author

@pchemguy pchemguy Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not shown in specify.exe --help


### `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`, 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) |
Expand All @@ -311,7 +349,7 @@ The `specify` command supports the following options:
| `--debug` | Flag | Enable detailed debug output for troubleshooting |
| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) |
| `--ai-skills` | Flag | Install Prompt.MD templates as agent skills in agent-specific `skills/` directory (requires `--ai`). Extension commands are also auto-registered as skills when extensions are added later. |
| `--branch-numbering` | Option | Branch numbering strategy: `sequential` (default — `001`, `002`, `003`) or `timestamp` (`YYYYMMDD-HHMMSS`). Timestamp mode is useful for distributed teams to avoid numbering conflicts |
| `--branch-numbering` | Option | Branch numbering strategy: `sequential` (default — `001`, `002`, `003`) or `timestamp` (`YYYYMMDD-HHMMSS`). Timestamp mode is useful for distributed teams to avoid numbering conflicts |

### Examples

Expand Down Expand Up @@ -393,34 +431,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 slash commands for structured development.

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 |
Expand All @@ -431,21 +441,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/` |
Comment on lines +482 to +487
Copy link

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template resolution paths for presets and extensions in this priority table don’t match the actual on-disk layout described elsewhere in the repo. Preset and extension templates live under .specify/presets/<preset-id>/templates/ and .specify/extensions/<ext-id>/templates/ (not .specify/presets/templates/ / .specify/extensions/templates/). Using the current paths will send readers to non-existent locations.

Suggested change
| 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/` |
| Priority | Component Type | Location |
| -------: | ------------------------------------------------- | ----------------------------------------- |
| ⬆ 1 | Project-Local Overrides | `.specify/templates/overrides/` |
| 2 | Presets — Customize core & extensions | `.specify/presets/<preset-id>/templates/` |
| 3 | Extensions — Add new capabilities | `.specify/extensions/<ext-id>/templates/` |
| ⬇ 4 | Spec Kit Core — Built-in SDD commands & templates | `.specify/templates/` |

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Contributor Author

@pchemguy pchemguy Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I copied the paths from the Mermaid diagram. I have not used extensions/presets yet, so I cannot judge on the correctness of this suggestion. Refusing it in this pull request.


- **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

Expand Down
Loading