From 59dcfe7b87cec078328abedc625354884064fbe5 Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Mon, 27 Oct 2025 20:08:19 +0500 Subject: [PATCH 1/9] docs: add quickstart and VS Code usage guides for AI beginners * 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 #140 --- docs/quickstart.md | 21 +++++++---- docs/vscode-usage.md | 86 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 6 deletions(-) create mode 100644 docs/vscode-usage.md diff --git a/docs/quickstart.md b/docs/quickstart.md index a97c9fe193..3dc1d203a9 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,6 +2,8 @@ This guide will help you get started with Spec-Driven Development using Spec Kit. +> **Important**: Commands like `/specify` should be run in your terminal, not in the Copilot Chat window. See [VS Code Usage Guide](vscode-usage.md) for detailed instructions on where to run commands. + > NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. ## The 4-Step Process @@ -23,29 +25,36 @@ uvx --from git+https://github.com/github/spec-kit.git specify init **Note**: All commands should be run in your terminal, not in the Copilot Chat window. See our [VS Code Usage Guide](vscode-usage.md) for: +> - Where to run CLI commands +> - How to set up GitHub Copilot Chat +> - Troubleshooting common issues ## Detailed Example: Building Taskify Here's a complete example of building a team productivity platform: -### Step 1: Define Requirements with `/speckit.specify` +### Step 1: Define Requirements with the specify command ```text Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md new file mode 100644 index 0000000000..8dc574d42b --- /dev/null +++ b/docs/vscode-usage.md @@ -0,0 +1,86 @@ +## Using Spec Kit commands in Visual Studio Code + +This page explains where to run Spec Kit commands when you're working inside VS Code and how to install and enable the GitHub Copilot Chat extension. + +### Quick answer + +- Run CLI commands (like `specify`) in the VS Code integrated terminal, not in the Copilot Chat input. The chat is for conversational prompts and will not execute shell commands. +- To use GitHub Copilot Chat, install the `GitHub Copilot Chat` extension and sign in to GitHub. Instructions below. + +### Install & enable GitHub Copilot Chat (GUI) + +1. Open VS Code. +2. Open the Extensions view (Ctrl+Shift+X). +3. Search for "Copilot Chat" and install "GitHub Copilot Chat" (published by GitHub). +4. After installation, the extension may prompt you to sign in. Follow the sign-in flow to authenticate with your GitHub account. +5. Open the Copilot Chat panel from the sidebar or use the Command Palette (Ctrl+Shift+P) and run: `Copilot Chat: Open Chat`. + +### Install & enable GitHub Copilot Chat (command line) + +If you prefer the command line, you can install the extension with the VS Code CLI. Open PowerShell and run: + +```powershell +# Install the Copilot Chat extension +code --install-extension GitHub.copilot-chat + +# Open VS Code (if not already open) +code . +``` + +After launching VS Code you may still need to follow the sign-in flow the first time the extension runs. + +### Where to run `specify` and other CLI commands + +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+`). +2. Make sure you're in the project folder (the same folder that contains the repository files). +3. Activate your Python environment and install the project if needed (example using a virtual environment): + +```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 +``` + +If the project exposes a console script named `specify`, the last command will run it. If not, you can often run a module directly: + +```powershell +python -m specify_cli --help +``` + +Replace `specify_cli` above with the actual module name or entrypoint if different. + +### Why commands typed into Copilot Chat don't run + +The chat is a text/AI interface. Typing `/specify` there is treated as part of your message to the assistant, not as a shell invocation. To run the command you must execute it in a terminal, or build a VS Code task/extension that runs it for you. + +### Helpful tips for newcomers + +- If you're new to Python projects, create and activate a virtual environment before installing. +- Use the integrated terminal for all CLI work — you can split terminals, run tasks, and see output inside VS Code. +- To run common workflows with one click, consider adding a VS Code Task or an npm/powershell script that runs the command you need. + +### Troubleshooting common issues + +1. **PowerShell execution policy blocks activation** + - Solution: Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process` to temporarily allow script execution + +2. **Command not found after installation** + - Make sure you're in your virtual environment (you should see `(.venv)` in your terminal prompt) + - Try reinstalling with `pip install -e .` from the project root + +3. **Copilot Chat not showing up** + - Verify you're signed in to GitHub in VS Code + - Try reloading VS Code (Command Palette > Developer: Reload Window) \ No newline at end of file From ff9a7b5f3f1351536d5dbfcf809923087d195f0c Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Sun, 12 Apr 2026 21:54:02 +0500 Subject: [PATCH 2/9] docs: clarify where to run /specify commands - fixes issue #140 --- docs/README.md | 2 + docs/quickstart.md | 136 +++++++++++++++++++++++++++++++------------ docs/toc.yml | 2 + docs/vscode-usage.md | 5 +- 4 files changed, 106 insertions(+), 39 deletions(-) diff --git a/docs/README.md b/docs/README.md index a9edc81dc9..f719f5f161 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,6 +28,8 @@ To build the documentation locally: - `toc.yml` - Table of contents configuration - `installation.md` - Installation guide - `quickstart.md` - Quick start guide +- `vscode-usage.md` - VS Code usage guide (where to run commands) +- `local-development.md` - Local development guide - `_site/` - Generated documentation output (ignored by git) ## Deployment diff --git a/docs/quickstart.md b/docs/quickstart.md index 3dc1d203a9..be647b4acf 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,7 +2,19 @@ This guide will help you get started with Spec-Driven Development using Spec Kit. -> **Important**: Commands like `/specify` should be run in your terminal, not in the Copilot Chat window. See [VS Code Usage Guide](vscode-usage.md) for detailed instructions on where to run commands. +> **Important**: There are two ways to interact with Specify; pick the right one for your workflow: +> +> - 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. +> +> See the [VS Code Usage Guide](vscode-usage.md) for details on where to run each type of command. + +| Command Type | Where to Run | Example | Notes | +|-------------|--------------|---------|--------| +| CLI Commands | Terminal (Bash, PowerShell) | `specify init ` | No leading slash | +| Slash Commands | AI Assistant (e.g., GitHub Copilot Chat) | `/speckit.specify ...` | Requires leading slash | > NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`. @@ -10,7 +22,7 @@ This guide will help you get started with Spec-Driven Development using Spec Kit ### 1. Install Specify -Initialize your project depending on the coding agent you're using: +Initialize your project using the CLI: ```bash uvx --from git+https://github.com/github/spec-kit.git specify init @@ -25,54 +37,102 @@ uvx --from git+https://github.com/github/spec-kit.git specify init **Note**: Always run CLI commands in your terminal and slash commands in your AI assistant. See our [VS Code Usage Guide](vscode-usage.md) for setup instructions. -> **Note**: All commands should be run in your terminal, not in the Copilot Chat window. See our [VS Code Usage Guide](vscode-usage.md) for: -> - Where to run CLI commands -> - How to set up GitHub Copilot Chat -> - Troubleshooting common issues +### Common Issues and Solutions + +- **Command not found**: Ensure `uvx` is installed (`pip install uvx`) +- **Wrong script type**: Use `--script ps` (PowerShell) or `--script sh` (Bash) to override auto-selection +- **Slash commands not working**: Verify your AI assistant supports slash commands and the `/speckit` prefix is included +- **Environment errors**: Check Python/Node.js installation and PATH settings +- **Git access issues**: Verify your Git credentials and repository access ## Detailed Example: Building Taskify Here's a complete example of building a team productivity platform: -### Step 1: Define Requirements with the specify command +### Step 1: Define Requirements with `/speckit.specify` + +```text +/speckit.specify Develop Taskify, a team productivity platform. Predefine 5 users: 1 product manager, 4 engineers. Create 3 sample projects with Kanban columns: To Do, In Progress, In Review, Done. No login. Drag-and-drop tasks. Highlight user-assigned tasks. Allow editing/deleting own comments only. + +Note: Do NOT implement — only return the spec. +``` + +For more detailed requirements: ```text -Develop Taskify, a team productivity platform. It should allow users to create projects, add team members, -assign tasks, comment and move tasks between boards in Kanban style. In this initial phase for this feature, -let's call it "Create Taskify," let's have multiple users but the users will be declared ahead of time, predefined. -I want five users in two different categories, one product manager and four engineers. Let's create three -different sample projects. Let's have the standard Kanban columns for the status of each task, such as "To Do," -"In Progress," "In Review," and "Done." There will be no login for this application as this is just the very -first testing thing to ensure that our basic features are set up. For each task in the UI for a task card, -you should be able to change the current status of the task between the different columns in the Kanban work board. -You should be able to leave an unlimited number of comments for a particular card. You should be able to, from that task -card, assign one of the valid users. When you first launch Taskify, it's going to give you a list of the five users to pick -from. There will be no password required. When you click on a user, you go into the main view, which displays the list of -projects. When you click on a project, you open the Kanban board for that project. You're going to see the columns. -You'll be able to drag and drop cards back and forth between different columns. You will see any cards that are -assigned to you, the currently logged in user, in a different color from all the other ones, so you can quickly -see yours. You can edit any comments that you make, but you can't edit comments that other people made. You can -delete any comments that you made, but you can't delete comments anybody else made. +/speckit.specify Build a team productivity platform with these core features: + +1. Users and Authentication: + - 5 predefined users (1 PM, 4 engineers) + - No login system (simplified first version) + - User selection from list on startup + +2. Project Structure: + - 3 sample projects + - Kanban board per project + - Columns: To Do, In Progress, In Review, Done + - 5-15 tasks per project + - At least one task per column + +3. Task Management: + - Drag-and-drop between columns + - Assign users to tasks + - Highlight tasks assigned to current user + - Unlimited comments per task + - Users can edit/delete their own comments only + +Note: Do NOT implement — only return the spec. ``` ### Step 2: Refine the Specification @@ -96,9 +156,11 @@ Read the review and acceptance checklist, and check off each item in the checkli Be specific about your tech stack and technical requirements: ```text -We are going to generate this using .NET Aspire, using Postgres as the database. The frontend should use -Blazor server with drag-and-drop task boards, real-time updates. There should be a REST API created with a projects API, -tasks API, and a notifications API. +/speckit.plan Generate a plan using: +- Backend: .NET Aspire with Postgres database +- Frontend: Blazor server with drag-and-drop task boards +- APIs: REST endpoints for projects, tasks, and notifications +- Features: Real-time updates, drag-and-drop UI ``` ### Step 4: Validate and Implement @@ -111,10 +173,10 @@ Read through it with an eye on determining whether or not there is a sequence of to be doing that are obvious from reading this. Because I don't know if there's enough here. ``` -Finally, implement the solution: +Generate the implementation: ```text -implement specs/002-create-taskify/plan.md +/speckit.implement specs/002-create-taskify/plan.md ``` ## Key Principles @@ -127,6 +189,6 @@ implement specs/002-create-taskify/plan.md ## Next Steps -- Read the complete methodology for in-depth guidance -- Check out more examples in the repository -- Explore the source code on GitHub +- Read the [complete methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md) for in-depth guidance +- Check out [more examples](https://github.com/github/spec-kit/tree/main/templates) in the repository +- Explore the [source code on GitHub](https://github.com/github/spec-kit) diff --git a/docs/toc.yml b/docs/toc.yml index 082bb8c868..b15a2cc491 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -9,6 +9,8 @@ href: installation.md - name: Quick Start href: quickstart.md + - name: VS Code Usage + href: vscode-usage.md # Development workflows - name: Development diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index 8dc574d42b..e666a4edc3 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -62,9 +62,10 @@ python -m specify_cli --help Replace `specify_cli` above with the actual module name or entrypoint if different. -### Why commands typed into Copilot Chat don't run +### Where to run commands: Terminal vs AI Assistant -The chat is a text/AI interface. Typing `/specify` there is treated as part of your message to the assistant, not as a shell invocation. To run the command you must execute it in a terminal, or build a VS Code task/extension that runs it for you. +- **CLI commands** (e.g., `specify init`, `specify check`): Run in the VS Code integrated terminal. These are shell commands that execute on your machine. +- **Slash commands** (e.g., `/speckit.specify`, `/speckit.plan`): Run inside an AI assistant chat window (like GitHub Copilot Chat). These are consumed by the AI assistant, not executed as shell commands. ### Helpful tips for newcomers From 3867450aaf9d5a05e260e1de1e2c574d6c4589bd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 13 Apr 2026 12:50:03 +0000 Subject: [PATCH 3/9] docs: address Copilot review comments on quickstart and vscode-usage 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> --- docs/quickstart.md | 8 +------- docs/vscode-usage.md | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index be647b4acf..920ae63405 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -7,7 +7,7 @@ This guide will help you get started with Spec-Driven Development using Spec Kit > - 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. +> **Note**: Spec Kit slash commands use the `/speckit.` prefix (for example, `/speckit.specify` and `/speckit.plan`). Use the `/speckit.` prefix for all slash commands. > > See the [VS Code Usage Guide](vscode-usage.md) for details on where to run each type of command. @@ -55,12 +55,6 @@ Example (slash command used in the assistant/chat): Note: Do NOT change or implement this spec; only return the spec text focusing on requirements and acceptance criteria. ``` -If you prefer the terminal, you can still run the CLI version (no leading slash): - -```bash -specify init my-project -``` - ### 3. Create a Technical Implementation Plan Use the plan command to provide your tech stack and architecture choices. diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index e666a4edc3..ca3e78023d 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -33,7 +33,7 @@ After launching VS Code you may still need to follow the sign-in flow the first 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+`). +1. Open the integrated terminal (View > Terminal or Ctrl+\`). 2. Make sure you're in the project folder (the same folder that contains the repository files). 3. Activate your Python environment and install the project if needed (example using a virtual environment): From dc423536f997c64e2caf7ab0ba011b56dde7c41c Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 00:34:56 +0500 Subject: [PATCH 4/9] docs: address code review feedback - fix 5 issues from PR #2190 --- docs/quickstart.md | 4 ++-- docs/vscode-usage.md | 29 +++++++++++++---------------- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 920ae63405..d03db1289e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -57,7 +57,7 @@ Note: Do NOT change or implement this spec; only return the spec text focusing o ### 3. Create a Technical Implementation Plan -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 /speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database. @@ -170,7 +170,7 @@ to be doing that are obvious from reading this. Because I don't know if there's Generate the implementation: ```text -/speckit.implement specs/002-create-taskify/plan.md +/speckit.implement ``` ## Key Principles diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index ca3e78023d..f6cb4cfb3e 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -35,32 +35,29 @@ The Copilot Chat input is a conversational interface only — it does not run sh 1. Open the integrated terminal (View > Terminal or Ctrl+\`). 2. Make sure you're in the project folder (the same folder that contains the repository files). -3. Activate your Python environment and install the project if needed (example using a virtual environment): +3. Install and run the CLI (examples using uvx - the recommended way, or use uv for persistent installation): ```powershell -# create a venv (first time) -python -m venv .venv +# Run once with uvx (no installation needed) +uvx --from git+https://github.com/github/spec-kit.git specify --help -# 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) +# Or install persistently with uv (recommended) +uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify --help ``` -If the project exposes a console script named `specify`, the last command will run it. If not, you can often run a module directly: +To run the CLI from the source repository without installation: ```powershell -python -m specify_cli --help +cd /path/to/spec-kit +uvx --from . specify --help ``` -Replace `specify_cli` above with the actual module name or entrypoint if different. +Or directly via the module: + +```powershell +python -m src.specify_cli --help +``` ### Where to run commands: Terminal vs AI Assistant From 34686c69f34dfdf1b2a7d4482778671f7be522b9 Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 14:16:54 +0500 Subject: [PATCH 5/9] fix: replace pip install uvx with correct uv install instruction --- docs/quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index d03db1289e..9a1a63030f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -84,7 +84,7 @@ Let the AI generate tasks, write code, run tests, and fix bugs — all from your ### Common Issues and Solutions -- **Command not found**: Ensure `uvx` is installed (`pip install uvx`) +- **Command not found**: Ensure `uv` is installed (see [uv install docs](https://docs.astral.sh/uv/getting-started/installation/)); `uvx` is included with `uv` - **Wrong script type**: Use `--script ps` (PowerShell) or `--script sh` (Bash) to override auto-selection - **Slash commands not working**: Verify your AI assistant supports slash commands and the `/speckit` prefix is included - **Environment errors**: Check Python/Node.js installation and PATH settings From ff755ae250f6d4116bd0fa43ac60b4dd35f79d9e Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 14:30:53 +0500 Subject: [PATCH 6/9] docs: fix cross-platform code examples in vscode-usage.md - Use 'sh' code block instead of 'powershell' for cross-platform commands - Add OS-specific path examples for cd command - Wording fix: 'Open PowerShell' -> 'Open a terminal' --- docs/vscode-usage.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index f6cb4cfb3e..8a174742f9 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -17,9 +17,9 @@ This page explains where to run Spec Kit commands when you're working inside VS ### Install & enable GitHub Copilot Chat (command line) -If you prefer the command line, you can install the extension with the VS Code CLI. Open PowerShell and run: +If you prefer the command line, you can install the extension with the VS Code CLI. Open a terminal (for example, the VS Code integrated terminal) and run: -```powershell +```sh # Install the Copilot Chat extension code --install-extension GitHub.copilot-chat @@ -48,7 +48,9 @@ specify --help To run the CLI from the source repository without installation: -```powershell +```sh +# On Windows: cd C:\path\to\spec-kit +# On macOS/Linux: cd /path/to/spec-kit cd /path/to/spec-kit uvx --from . specify --help ``` From db5884ca8c48fc99504c428bbb460981a556631f Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 18:28:00 +0500 Subject: [PATCH 7/9] docs: fix PowerShell capitalization and update installation troubleshooting --- docs/vscode-usage.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index 8a174742f9..797a626bd5 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -70,7 +70,7 @@ python -m src.specify_cli --help - If you're new to Python projects, create and activate a virtual environment before installing. - Use the integrated terminal for all CLI work — you can split terminals, run tasks, and see output inside VS Code. -- To run common workflows with one click, consider adding a VS Code Task or an npm/powershell script that runs the command you need. +- To run common workflows with one click, consider adding a VS Code Task or an npm/PowerShell script that runs the command you need. ### Troubleshooting common issues @@ -78,8 +78,10 @@ python -m src.specify_cli --help - Solution: Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process` to temporarily allow script execution 2. **Command not found after installation** - - Make sure you're in your virtual environment (you should see `(.venv)` in your terminal prompt) - - Try reinstalling with `pip install -e .` from the project root + - If you installed with `uv tool install`, ensure the uv tools bin directory is on your `PATH`, then verify the tool is installed with `uv tool list` + - If needed, reinstall with `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git` + - If you're running from the source repository in a virtual environment, make sure the environment is activated (you should see `(.venv)` in your terminal prompt) + - For that source/venv workflow, try reinstalling with `pip install -e .` from the project root 3. **Copilot Chat not showing up** - Verify you're signed in to GitHub in VS Code From 934b1b88f31b16f4f58def6bf4e41571244392d5 Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 19:02:00 +0500 Subject: [PATCH 8/9] docs: address PR review feedback - fix recommendation wording and remove broken python -m invocation --- docs/vscode-usage.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index 797a626bd5..663a8ebf43 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -35,13 +35,13 @@ The Copilot Chat input is a conversational interface only — it does not run sh 1. Open the integrated terminal (View > Terminal or Ctrl+\`). 2. Make sure you're in the project folder (the same folder that contains the repository files). -3. Install and run the CLI (examples using uvx - the recommended way, or use uv for persistent installation): +3. Run the CLI with `uvx` for one-off usage, or install it with `uv tool install` if you expect to use it regularly: ```powershell # Run once with uvx (no installation needed) uvx --from git+https://github.com/github/spec-kit.git specify --help -# Or install persistently with uv (recommended) +# Or install persistently with uv for regular usage uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify --help ``` @@ -55,12 +55,6 @@ cd /path/to/spec-kit uvx --from . specify --help ``` -Or directly via the module: - -```powershell -python -m src.specify_cli --help -``` - ### Where to run commands: Terminal vs AI Assistant - **CLI commands** (e.g., `specify init`, `specify check`): Run in the VS Code integrated terminal. These are shell commands that execute on your machine. From ebbf32f018ab408975d30a98300bb6955d8c5d1a Mon Sep 17 00:00:00 2001 From: Tayyaba Akbar Date: Tue, 14 Apr 2026 19:39:34 +0500 Subject: [PATCH 9/9] docs: address PR review feedback - add slash command explanation, troubleshooting, and fix minor formatting issues --- docs/quickstart.md | 7 ++++++- docs/vscode-usage.md | 25 +++++++++++++++++++------ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index 9a1a63030f..ddd3178a78 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -9,6 +9,8 @@ This guide will help you get started with Spec-Driven Development using Spec Kit > > **Note**: Spec Kit slash commands use the `/speckit.` prefix (for example, `/speckit.specify` and `/speckit.plan`). Use the `/speckit.` prefix for all slash commands. > +> **Important for slash commands to work**: When you run `specify init`, you must select your AI assistant (e.g., `--ai copilot` for GitHub Copilot). This generates the prompt/command files (e.g., `.github/prompts/` for Copilot) that make slash commands available. Without this step, `/speckit.*` commands will be treated as plain text. +> > See the [VS Code Usage Guide](vscode-usage.md) for details on where to run each type of command. | Command Type | Where to Run | Example | Notes | @@ -39,6 +41,8 @@ uvx --from git+https://github.com/github/spec-kit.git specify init **How slash commands work**: When you ran `specify init` with `--ai copilot` (or selected Copilot during init), Spec Kit generated prompt files into the `.github/prompts/` folder in your project. These files are what make `/speckit.*` commands appear in Copilot Chat. The commands are project-specific and only show up when VS Code is opened on the project folder containing `.github/prompts/`. For other agents, commands are stored in their respective locations (e.g., `.claude/commands/`, `.gemini/commands/`). + If you use a coding agent, some agents may try to rewrite or "improve" your prompt. Make the difference from step 1 explicit in your slash prompt. For example, include an explicit instruction such as: ``` @@ -86,7 +90,8 @@ Let the AI generate tasks, write code, run tests, and fix bugs — all from your - **Command not found**: Ensure `uv` is installed (see [uv install docs](https://docs.astral.sh/uv/getting-started/installation/)); `uvx` is included with `uv` - **Wrong script type**: Use `--script ps` (PowerShell) or `--script sh` (Bash) to override auto-selection -- **Slash commands not working**: Verify your AI assistant supports slash commands and the `/speckit` prefix is included +- **Slash commands not working**: Verify your AI assistant supports slash commands and the `/speckit` prefix is included. Make sure you ran `specify init` with `--ai copilot` (or selected Copilot) so the `.github/prompts/` folder was created +- **`/speckit.*` treated as plain text**: This usually means the prompt files weren't generated. Run `specify init` again with `--ai copilot` and confirm `.github/prompts/` exists in your project - **Environment errors**: Check Python/Node.js installation and PATH settings - **Git access issues**: Verify your Git credentials and repository access diff --git a/docs/vscode-usage.md b/docs/vscode-usage.md index 663a8ebf43..2f00bfc0e4 100644 --- a/docs/vscode-usage.md +++ b/docs/vscode-usage.md @@ -33,7 +33,7 @@ After launching VS Code you may still need to follow the sign-in flow the first 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+\`). +1. Open the integrated terminal (View > Terminal or Ctrl+\`). 2. Make sure you're in the project folder (the same folder that contains the repository files). 3. Run the CLI with `uvx` for one-off usage, or install it with `uv tool install` if you expect to use it regularly: @@ -49,8 +49,6 @@ specify --help To run the CLI from the source repository without installation: ```sh -# On Windows: cd C:\path\to\spec-kit -# On macOS/Linux: cd /path/to/spec-kit cd /path/to/spec-kit uvx --from . specify --help ``` @@ -60,6 +58,15 @@ uvx --from . specify --help - **CLI commands** (e.g., `specify init`, `specify check`): Run in the VS Code integrated terminal. These are shell commands that execute on your machine. - **Slash commands** (e.g., `/speckit.specify`, `/speckit.plan`): Run inside an AI assistant chat window (like GitHub Copilot Chat). These are consumed by the AI assistant, not executed as shell commands. +### How Slash Commands Work in Copilot Chat + +When you run `specify init` and select **GitHub Copilot** as your AI assistant (or use `--ai copilot`), Spec Kit generates command files into the `.github/prompts/` folder in your project. These prompt files are what make the `/speckit.*` slash commands appear and work in Copilot Chat. + +Key points: +- The slash commands are **project-specific** — they only show up when VS Code is opened on the project folder that contains the `.github/prompts/` directory +- If you don't see `/speckit.*` commands, verify that `specify init` was run with `--ai copilot` and that the `.github/prompts/` folder exists +- Other AI agents (Claude, Gemini, etc.) store their commands in different locations (e.g., `.claude/commands/`, `.gemini/commands/`) + ### Helpful tips for newcomers - If you're new to Python projects, create and activate a virtual environment before installing. @@ -70,13 +77,19 @@ uvx --from . specify --help 1. **PowerShell execution policy blocks activation** - Solution: Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process` to temporarily allow script execution - + 2. **Command not found after installation** - If you installed with `uv tool install`, ensure the uv tools bin directory is on your `PATH`, then verify the tool is installed with `uv tool list` - If needed, reinstall with `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git` - If you're running from the source repository in a virtual environment, make sure the environment is activated (you should see `(.venv)` in your terminal prompt) - For that source/venv workflow, try reinstalling with `pip install -e .` from the project root - + 3. **Copilot Chat not showing up** - Verify you're signed in to GitHub in VS Code - - Try reloading VS Code (Command Palette > Developer: Reload Window) \ No newline at end of file + - Try reloading VS Code (Command Palette > Developer: Reload Window) + +4. **`/speckit.*` commands are treated as plain text instead of slash commands** + - Verify you ran `specify init` with `--ai copilot` (or selected Copilot during init) so the `.github/prompts/` folder was created + - Confirm the `.github/prompts/` directory exists in your project root + - Make sure VS Code is opened on the **project folder** (not a parent directory), since Copilot discovers commands relative to the open workspace + - If the folder exists but commands still don't appear, reload VS Code (Command Palette > Developer: Reload Window) \ No newline at end of file