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.
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
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! |
There was a problem hiding this comment.
Pull request overview
This PR updates the DocFX documentation to clarify where to run Spec Kit commands (terminal vs AI assistant slash commands), addressing confusion reported in issue #140 when users typed /specify in Copilot Chat and it was treated as plain text.
Changes:
- Add a new “VS Code Usage” doc page explaining command locations and Copilot Chat setup.
- Update
quickstart.mdwith a CLI vs slash-command reference table, updated examples using/speckit.*, and troubleshooting tips. - Update docs navigation/indexing to include the new VS Code page.
Show a summary per file
| File | Description |
|---|---|
| docs/vscode-usage.md | New guide explaining VS Code terminal vs Copilot Chat usage and setup. |
| docs/quickstart.md | Adds a command-type table, clarifies CLI vs slash commands, updates examples, and adds troubleshooting. |
| docs/toc.yml | Adds “VS Code Usage” to the Getting Started TOC. |
| docs/README.md | Lists the new vscode-usage.md file in the docs structure. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 5
|
|
||
| ### Common Issues and Solutions | ||
|
|
||
| - **Command not found**: Ensure `uvx` is installed (`pip install uvx`) |
There was a problem hiding this comment.
The troubleshooting tip suggests installing uvx via pip install uvx, but this repo’s docs list uv as the prerequisite and uvx ships with uv. Suggest updating the instruction to install uv (or link to the uv install docs) rather than a non-standard uvx package name.
| - **Command not found**: Ensure `uvx` is installed (`pip install uvx`) | |
| - **Command not found**: Ensure `uv` is installed; `uvx` is included with `uv` |
| ### 3. Create a Technical Implementation Plan | ||
|
|
||
| Use the `/speckit.plan` command to provide your tech stack and architecture choices. | ||
| Use the plan command to provide your tech stack and architecture choices. |
There was a problem hiding this comment.
This section is meant to clarify command types, but it says “Use the plan command…” without naming the slash command explicitly. Suggest referring to /speckit.plan here (and noting it runs in the AI assistant), to stay consistent with the surrounding CLI vs slash command distinction.
| Use the plan command to provide your tech stack and architecture choices. | |
| Use the `/speckit.plan` slash command (in an AI assistant or editor that supports slash commands) to provide your tech stack and architecture choices. |
|
|
||
| ```text | ||
| implement specs/002-create-taskify/plan.md | ||
| /speckit.implement specs/002-create-taskify/plan.md |
There was a problem hiding this comment.
The example passes a plan file path to /speckit.implement, but the speckit.implement prompt file doesn’t appear to consume arguments (it always reads plan.md/tasks.md from the feature context). Suggest either removing the argument from the docs or updating the prompt/command behavior so the argument is actually used.
| /speckit.implement specs/002-create-taskify/plan.md | |
| /speckit.implement |
| ```powershell | ||
| # create a venv (first time) | ||
| python -m venv .venv | ||
|
|
||
| # allow script execution for the current session if required (temporary) | ||
| Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process | ||
|
|
||
| # activate the venv | ||
| .\.venv\Scripts\Activate.ps1 | ||
|
|
||
| # install the project in editable mode (if the project exposes a CLI entrypoint) | ||
| pip install -e . | ||
|
|
||
| # run the CLI (example) | ||
| specify --help | ||
| ``` |
There was a problem hiding this comment.
These steps recommend pip install -e . to get the specify CLI, but elsewhere in the repo the documented installation paths are uv tool install specify-cli ... (persistent) or uvx --from ... specify ... (one-time). Suggest aligning this VS Code guide with the project’s supported install flows to avoid sending new users down a local-dev-only setup path.
| ```powershell | ||
| python -m specify_cli --help | ||
| ``` | ||
|
|
||
| Replace `specify_cli` above with the actual module name or entrypoint if different. |
There was a problem hiding this comment.
This suggests python -m specify_cli --help and then says to “replace specify_cli … if different”, but for this repo/module structure the direct module entrypoint differs depending on whether it’s installed (editable) vs run from source (e.g., python -m src.specify_cli). Suggest making the guidance explicit for this repo rather than leaving it as a placeholder.
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
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