Fix/issue 140 clarify commands location

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

docs/quickstart.md

@@ -2,13 +2,29 @@
 
 This guide will help you get started with Spec-Driven Development using Spec Kit.
 
+> **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**: 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 |
+|-------------|--------------|---------|--------|
+| CLI Commands | Terminal (Bash, PowerShell) | `specify init <PROJECT_NAME>` | 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`.
 
 ## The 4-Step Process
 
 ### 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 <PROJECT_NAME>
@@ -23,23 +39,61 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 
 ### 2. Create the Spec
 
-Use the `/speckit.specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.
+Use the `/speckit.specify` slash command (in an AI assistant or editor that supports slash commands) to describe what you want to build. Focus on the **what** and **why**, not the tech stack. The slash command is intended to be consumed by an AI assistant and is different from the CLI `specify` command (no slash) which you run in a terminal.
 
-```bash
+> **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:
+
+```
+Do NOT change or implement this spec; only return the specification text focusing on requirements and acceptance criteria.
+```
+
+Keeping the `/speckit` prefix is important — removing it will break slash command behavior.
+
+Example (slash command used in the assistant/chat):
+
+```text
 /speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
+
+Note: Do NOT change or implement this spec; only return the spec text focusing on requirements and acceptance criteria.
 ```
 
 ### 3. Create a Technical Implementation Plan
 
-Use the `/speckit.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.
 
-```bash
+```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.
 ```
 
 ### 4. Break Down and Implement
 
-Use `/speckit.tasks` to create an actionable task list, then ask your agent to implement the feature.
+In **Copilot Chat**, run:
+
+```text
+/speckit.tasks
+```
+Then:
+
+```text
+/speckit.implement
+```
+
+Let the AI generate tasks, write code, run tests, and fix bugs — all from your specs!
+
+## Running Commands and Troubleshooting
+
+> **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.
+
+### Common Issues and Solutions
+
+- **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. 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
 
 ## Detailed Example: Building Taskify
 
@@ -48,22 +102,36 @@ Here's a complete example of building a team productivity platform:
 ### Step 1: Define Requirements with `/speckit.specify`
 
 ```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 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
+/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
@@ -87,9 +155,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
@@ -102,10 +172,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
 ```
 
 ## Key Principles
@@ -118,6 +188,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)

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

docs/vscode-usage.md

@@ -0,0 +1,95 @@
+## 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 a terminal (for example, the VS Code integrated terminal) and run:
+
+```sh
+# 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 <kbd>Ctrl</kbd>+<kbd>\`</kbd>).
+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:
+
+```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 for regular usage
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+specify --help
+```
+
+To run the CLI from the source repository without installation:
+
+```sh
+cd /path/to/spec-kit
+uvx --from . specify --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.
+- **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.
+- 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**
+   - 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)
+
+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)