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

Merged
mnriem merged 25 commits into from
Apr 9, 2026
+60 −55
Merged

Readme clarity #2013

Changes from all commits
Commits
Show all changes
25 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
b1ea4aa
Merge branch 'main' into readme-formatting
pchemguy Apr 9, 2026
bf854de
integration command
pchemguy Apr 9, 2026
6e77e26
Update README.md
pchemguy Apr 9, 2026
313f8f8
Update README.md
pchemguy Apr 9, 2026
cb83191
Update README.md
pchemguy Apr 9, 2026
0be994d
Update README.md
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
115 changes: 60 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,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 @@ -319,22 +318,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) |
Expand Down Expand Up @@ -431,38 +471,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 |
Expand All @@ -473,21 +481,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

Expand Down
Loading