Fix/issue 140 clarify commands location#2190
Fix/issue 140 clarify commands location#2190Tayyaba-Akbar956 wants to merge 4 commits intogithub:mainfrom
Conversation
* Add \docs/quickstart.md\: 4-step beginner flow with clear CLI vs AI command separation * Add \docs/vscode-usage.md\: step-by-step guide to install Copilot Chat, run \specify\ in terminal, and fix common errors * Update \README.md\ with links to both guides * Use newcomer-friendly tone with warnings, code blocks, and troubleshooting * Prevent users from typing \specify\ into Copilot Chat (common first-timer mistake) Closes github#140
There was a problem hiding this comment.
Pull request overview
Documentation update to address issue #140 by clarifying where Spec Kit CLI commands vs AI-assistant slash commands should be run (terminal vs chat), and by standardizing examples on the /speckit.* slash-command prefix.
Changes:
- Added a new VS Code usage guide explaining Copilot Chat setup and where to run CLI vs slash commands.
- Updated quickstart with a command-type reference table, troubleshooting, and revised examples using
/speckit.*. - Updated docs navigation to include the new VS Code guide.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide describing Copilot Chat setup and where to run CLI vs slash commands. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started TOC. |
| docs/README.md | Updates docs index to include the new VS Code usage page. |
| docs/quickstart.md | Adds command-type clarification/table, troubleshooting, and updates examples to /speckit.*. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/vscode-usage.md
Outdated
|
|
||
| The Copilot Chat input is a conversational interface only — it does not run shell/CLI commands on your machine. To actually run `specify` (or any other CLI command supplied by this repo), use the VS Code integrated terminal: | ||
|
|
||
| 1. Open the integrated terminal (View > Terminal or Ctrl+`). |
There was a problem hiding this comment.
Ctrl+`` contains a literal backtick that starts an inline code span and can break Markdown rendering for the rest of the page. Escape the backtick (e.g., Ctrl+``) or wrap the shortcut in a code span that safely includes a backtick (e.g., using double backticks).
| 1. Open the integrated terminal (View > Terminal or Ctrl+`). | |
| 1. Open the integrated terminal (View > Terminal or Ctrl+\`). |
docs/quickstart.md
Outdated
| > - CLI: run the `specify` command (no leading slash) in your terminal. | ||
| > - Slash commands (AI assistant): use `/speckit.specify`, `/speckit.plan`, etc., inside an AI assistant or editor that supports slash commands (for example, GitHub Copilot Chat). Do not remove the leading slash — these commands rely on the slash prefix to trigger the assistant correctly. | ||
| > | ||
| > **Note**: The original command was `/specify`, but it has been renamed to `/speckit.*` (e.g., `/speckit.specify`, `/speckit.plan`) to avoid conflicts with other tools. Use the `/speckit.` prefix for all slash commands. |
There was a problem hiding this comment.
The note claims the original slash command was /specify and was renamed to /speckit.*, but there’s no supporting reference in the repo (changelog/docs) indicating a rename from /specify. Consider removing the historical claim or replacing it with a verifiable statement (e.g., that Spec Kit commands use the /speckit.* prefix for discoverability).
| > **Note**: The original command was `/specify`, but it has been renamed to `/speckit.*` (e.g., `/speckit.specify`, `/speckit.plan`) to avoid conflicts with other tools. Use the `/speckit.` prefix for all slash commands. | |
| > **Note**: Spec Kit slash commands use the `/speckit.` prefix (for example, `/speckit.specify` and `/speckit.plan`). Use the `/speckit.` prefix for all slash commands. |
docs/quickstart.md
Outdated
| If you prefer the terminal, you can still run the CLI version (no leading slash): | ||
|
|
||
| ```bash | ||
| specify init my-project | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This suggests specify init my-project as the “CLI version” of /speckit.specify, but specify init is project initialization and not an alternative to generating a spec via /speckit.specify. This is likely to confuse users; consider removing this block or replacing it with a CLI action that’s actually equivalent (e.g., editing the generated spec.md manually, or using specify CLI commands that exist like specify check).
| If you prefer the terminal, you can still run the CLI version (no leading slash): | |
| ```bash | |
| specify init my-project | |
| ``` | |
| There is no direct CLI equivalent shown in this guide for generating a spec: use `/speckit.specify` in a supported AI assistant/editor for this step. The `specify init` command is only for project initialization in step 1, not for creating the spec itself. |
mnriem
left a comment
There was a problem hiding this comment.
Please address Copilot feedback. If not applicable, please explain why
Agent-Logs-Url: https://github.com/Tayyaba-Akbar956/spec-kit/sessions/6753ecd1-6750-44a1-9e1b-3645b52f9bd0 Co-authored-by: Tayyaba-Akbar956 <193090017+Tayyaba-Akbar956@users.noreply.github.com>
…fy-command-instructions docs: fix Copilot review comments on quickstart and vscode-usage guides
|
Hi @mnriem! I've addressed all three Copilot review comments. The fixes have been merged into this branch and are reflected in the latest commits. Here's a quick summary of what was fixed:
Please let me know if anything else needs to be changed. Thanks! |
Summary
Fixes issue #140 - Unclear instructions on where to run
/specifycommand.Problem
New users were confused about where to run spec-kit commands:
/specifyin Copilot Chat treated it as plain text, not a commandSolution
specify) vs slash commands (/speckit.specify)/speckit.prefixFiles Changed