Conversation
Improves formatting of Specify CLI Reference
Improve "Available Slash Commands" clarity in README.md.
Improves Extensions & Presets section clarity in README.md
There was a problem hiding this comment.
Pull request overview
Improves README.md clarity by restructuring and expanding documentation around supported agents, available slash commands, and the Specify CLI reference.
Changes:
- Reformats the “Supported AI Agents” section into a cleaner markdown table.
- Moves/expands “Available Slash Commands” into its own section with core/optional command listings.
- Refactors the CLI reference and replaces the extensions/presets mermaid diagram with a priority table + bullets.
Comments suppressed due to low confidence (3)
README.md:321
- The CLI invocation signature shown as
specify <COMMAND> <SUBCOMMAND> <OPTIONS>is misleading because several top-level commands (e.g.,init,check,version) do not take a subcommand. Consider documenting this asspecify <COMMAND> [<SUBCOMMAND>] [OPTIONS]or showing separate usage lines for commands with/without subcommands.
The `specify` tool is invoked as
specify
and supports the following commands:
README.md:330
- The “Commands” table omits the
versiontop-level command even though it exists in the CLI (@app.command() def version()insrc/specify_cli/__init__.py). Since this section says “supports the following commands”, the list should includeversion(and any other top-level commands) to avoid documenting an incomplete CLI surface.
| 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. |
| `extension` | Manage extensions |
| `preset` | Manage presets |
README.md:449
- The template stack table has incorrect locations for presets and extensions:
.specify/presets//templates/and.specify/extensions//templates/contain a double slash and are missing the<preset-id>/<ext-id>directory segment (compare to the surrounding text that previously used.specify/presets/<preset-id>/templates/etc.). This should be corrected so the paths match the actual on-disk layout.
| 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/` |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why. Thank you for doing this!
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address more Copilot feedback. You are almost there!
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Can you please resolve conflicts?
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
I have completed conflict resolution process and Copilot review. |
There was a problem hiding this comment.
Pull request overview
This PR improves the project’s README documentation by reorganizing and clarifying how to use Spec Kit’s agent commands, CLI invocation, and customization layering (extensions/presets/overrides).
Changes:
- Adds an “Available Slash Commands” section with a core/optional command breakdown.
- Clarifies
specifyCLI invocation and expands the documented top-level command list. - Replaces the extensions/presets mermaid diagram with a priority table and bullet explanations.
Show a summary per file
| File | Description |
|---|---|
| README.md | Reorganizes and clarifies agent command usage, CLI reference formatting, and extensions/presets layering docs |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
README.md:341
#### Optional Commandsalso skips a heading level under## Available Slash Commands, which will trigger markdownlint MD001. Use a### Optional Commandsheading (or adjust surrounding headings so nesting increments by one).
#### Optional Commands
Additional commands for enhanced quality and validation:
- Files reviewed: 1/1 changed files
- Comments generated: 0 new
There was a problem hiding this comment.
Pull request overview
Updates README.md to improve onboarding clarity around agent commands and the specify CLI reference.
Changes:
- Adds a dedicated “Available Slash Commands” section with core vs optional commands and corresponding skill names.
- Clarifies CLI invocation and expands the documented top-level command list.
- Replaces the extensions/presets priority Mermaid diagram with a concise priority table and bullets.
Show a summary per file
| File | Description |
|---|---|
| README.md | Reorganizes and expands documentation for slash commands, CLI usage, and customization (templates/extensions/presets) resolution. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 4
| The `specify` command supports the following options: | ||
| The `specify` tool is invoked as | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
The fenced block is tagged as bash but uses angle-bracket placeholders (<COMMAND>, <OPTIONAL_SUBCOMMAND>, <OPTIONS>), which are not valid shell syntax (they’re interpreted as redirection if copy/pasted). Consider switching the fence to text (or adjust the synopsis to a copy/paste-safe form like specify COMMAND [SUBCOMMAND] [OPTIONS]).
| ```bash | |
| ```text |
|
|
||
| ## 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. |
There was a problem hiding this comment.
This section mentions --ai-skills without noting that the CLI requires --ai when using it (otherwise specify init exits with an error). To prevent confusion, update the sentence to explicitly show specify init ... --ai <agent> --ai-skills or mention the dependency on --ai.
| 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. | |
| 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`. |
| | 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 | |
There was a problem hiding this comment.
The command list is presented as complete (“supports the following commands”), but the CLI also defines an integration command group (specify integration ...) in the codebase. Either include integration in this table or reword the lead-in to clarify this is a partial subset.
| | 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 | | |
| | `preset` | Manage presets | | |
| | `integration` | Manage integrations | |
| | 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/` | |
There was a problem hiding this comment.
The preset/extension template locations in this priority table don’t match the actual on-disk layout used by the resolver and docs. Presets are under .specify/presets/<preset-id>/templates/ and extensions under .specify/extensions/<ext-id>/templates/; the current .specify/presets/templates/ and .specify/extensions/templates/ paths will point readers to non-existent directories.
| | 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/` | |
mnriem
left a comment
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
Description
Improves clarity of README.md
AI Disclosure