ros/spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-01-30 04:32:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1288 from github/localden/updates

Browse Source 
Small QOL updates
This commit is contained in:
Den Delimarsky
2025-12-04 11:58:04 -08:00
committed by GitHub
parent baeb829ed4 0049b1cdc2
commit 9111699cd2
8 changed files with 118 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
AGENTS.md
View File

@@ -29,25 +29,25 @@ Specify supports multiple AI agents by generating agent-specific command files a
### Current Supported Agents ### Current Supported Agents
| Agent | Directory | Format | CLI Tool | Description | | Agent | Directory | Format | CLI Tool | Description |
|-------|-----------|---------|----------|-------------| | -------------------------- | ---------------------- | -------- | --------------- | --------------------------- |
| **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI | | **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI |
| **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI | | **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI |
| **GitHub Copilot** | `.github/agents/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code | | **GitHub Copilot** | `.github/agents/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |
| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI | | **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI |
| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI | | **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI |
| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI | | **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI |
| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI | | **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI |
| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows | | **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows |
| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE | | **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE |
| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI | | **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI |
| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE | | **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE |
| **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI | | **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI |
| **Qoder CLI** | `.qoder/commands/` | Markdown | `qoder` | Qoder CLI | | **Qoder CLI** | `.qoder/commands/` | Markdown | `qoder` | Qoder CLI |
| **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI | | **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI |
| **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI | | **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI |
| **SHAI** | `.shai/commands/` | Markdown | `shai` | SHAI CLI | | **SHAI** | `.shai/commands/` | Markdown | `shai` | SHAI CLI |
| **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE | | **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE |
### Step-by-Step Integration Guide ### Step-by-Step Integration Guide
@@ -153,7 +153,7 @@ Add to case statement:
case "$AGENT_TYPE" in case "$AGENT_TYPE" in
# ... existing cases ... # ... existing cases ...
windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;; windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;
"") "")
# ... existing checks ... # ... existing checks ...
[ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf"; [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf";
# Update default creation condition # Update default creation condition
@@ -307,7 +307,7 @@ echo "✅ Done"
Require a command-line tool to be installed: Require a command-line tool to be installed:
- **Claude Code**: `claude` CLI - **Claude Code**: `claude` CLI
- **Gemini CLI**: `gemini` CLI - **Gemini CLI**: `gemini` CLI
- **Cursor**: `cursor-agent` CLI - **Cursor**: `cursor-agent` CLI
- **Qwen Code**: `qwen` CLI - **Qwen Code**: `qwen` CLI
- **opencode**: `opencode` CLI - **opencode**: `opencode` CLI

2
CODE_OF_CONDUCT.md
View File

@@ -23,7 +23,7 @@ include:
Examples of unacceptable behavior by participants include: Examples of unacceptable behavior by participants include:
- The use of sexualized language or imagery and unwelcome sexual attention or - The use of sexualized language or imagery and unwelcome sexual attention or
advances advances
- Trolling, insulting/derogatory comments, and personal or political attacks - Trolling, insulting/derogatory comments, and personal or political attacks
- Public or private harassment - Public or private harassment
- Publishing others' private information, such as a physical or electronic - Publishing others' private information, such as a physical or electronic

10
CONTRIBUTING.md
View File

@@ -32,8 +32,8 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler
## Submitting a pull request ## Submitting a pull request
>[!NOTE] > [!NOTE]
>If your pull request introduces a large change that materially impacts the work of the CLI or the rest of the repository (e.g., you're introducing new templates, arguments, or otherwise major changes), make sure that it was **discussed and agreed upon** by the project maintainers. Pull requests with large changes that did not have a prior conversation and agreement will be closed. > If your pull request introduces a large change that materially impacts the work of the CLI or the rest of the repository (e.g., you're introducing new templates, arguments, or otherwise major changes), make sure that it was **discussed and agreed upon** by the project maintainers. Pull requests with large changes that did not have a prior conversation and agreement will be closed.
1. Fork and clone the repository 1. Fork and clone the repository
1. Configure and install the dependencies: `uv sync` 1. Configure and install the dependencies: `uv sync`
@@ -71,13 +71,13 @@ To test your templates, commands, and other changes locally, follow these steps:
Run the following command to generate the local packages: Run the following command to generate the local packages:
``` ```bash
./.github/workflows/scripts/create-release-packages.sh v1.0.0 ./.github/workflows/scripts/create-release-packages.sh v1.0.0
``` ```
2. **Copy the relevant package to your test project** 2. **Copy the relevant package to your test project**
``` ```bash
cp -r .genreleases/sdd-copilot-package-sh/. <path-to-test-project>/ cp -r .genreleases/sdd-copilot-package-sh/. <path-to-test-project>/
``` ```
@@ -122,7 +122,7 @@ When submitting AI-assisted contributions, please ensure they include:
- **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution - **Clear disclosure of AI use** - You are transparent about AI use and degree to which you're using it for the contribution
- **Human understanding and testing** - You've personally tested the changes and understand what they do - **Human understanding and testing** - You've personally tested the changes and understand what they do
- **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals - **Clear rationale** - You can explain why the change is needed and how it fits within Spec Kit's goals
- **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement - **Concrete evidence** - Include test cases, scenarios, or examples that demonstrate the improvement
- **Your own analysis** - Share your thoughts on the end-to-end developer experience - **Your own analysis** - Share your thoughts on the end-to-end developer experience

124
README.md
View File

@@ -142,26 +142,26 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
## 🤖 Supported AI Agents ## 🤖 Supported AI Agents
| Agent | Support | Notes | | Agent | Support | Notes |
|-----------------------------------------------------------|---------|---------------------------------------------------| | ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [Qoder CLI](https://qoder.com/cli) | ✅ | | | [Qoder CLI](https://qoder.com/cli) | ✅ | |
| [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. | | [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. |
| [Amp](https://ampcode.com/) | ✅ | | | [Amp](https://ampcode.com/) | ✅ | |
| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | | | [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | |
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | | [Claude Code](https://www.anthropic.com/claude-code) | ✅ | |
| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | | | [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | |
| [Codex CLI](https://github.com/openai/codex) | ✅ | | | [Codex CLI](https://github.com/openai/codex) | ✅ | |
| [Cursor](https://cursor.sh/) | ✅ | | | [Cursor](https://cursor.sh/) | ✅ | |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | |
| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | | | [GitHub Copilot](https://code.visualstudio.com/) | ✅ | |
| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support | | [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support |
| [Jules](https://jules.google.com/) | ✅ | | | [Jules](https://jules.google.com/) | ✅ | |
| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | | | [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | |
| [opencode](https://opencode.ai/) | ✅ | | | [opencode](https://opencode.ai/) | ✅ | |
| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | | | [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | |
| [Roo Code](https://roocode.com/) | ✅ | | | [Roo Code](https://roocode.com/) | ✅ | |
| [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | | | [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | |
| [Windsurf](https://windsurf.com/) | ✅ | | | [Windsurf](https://windsurf.com/) | ✅ | |
## 🔧 Specify CLI Reference ## 🔧 Specify CLI Reference
@@ -169,25 +169,25 @@ The `specify` command supports the following options:
### Commands ### Commands
| Command | Description | | Command | Description |
|-------------|----------------------------------------------------------------| | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init` | Initialize a new Specify project from the latest template | | `init` | Initialize a new Specify project from the latest template |
| `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qoder`) | | `check` | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`, `shai`, `qoder`) |
### `specify init` Arguments & Options ### `specify init` Arguments & Options
| Argument/Option | Type | Description | | Argument/Option | Type | Description |
|------------------------|----------|------------------------------------------------------------------------------| | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) | | `<project-name>` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
| `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `bob`, or `qoder` | | `--ai` | Option | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, `amp`, `shai`, `q`, `bob`, or `qoder` |
| `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) | | `--script` | Option | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell) |
| `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code | | `--ignore-agent-tools` | Flag | Skip checks for AI agent tools like Claude Code |
| `--no-git` | Flag | Skip git repository initialization | | `--no-git` | Flag | Skip git repository initialization |
| `--here` | Flag | Initialize project in the current directory instead of creating a new one | | `--here` | Flag | Initialize project in the current directory instead of creating a new one |
| `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) | | `--force` | Flag | Force merge/overwrite when initializing in current directory (skip confirmation) |
| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | | `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) |
| `--debug` | Flag | Enable detailed debug output for troubleshooting | | `--debug` | Flag | Enable detailed debug output for troubleshooting |
| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | | `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) |
### Examples ### Examples
@@ -250,29 +250,29 @@ After running `specify init`, your AI coding agent will have access to these sla
Essential commands for the Spec-Driven Development workflow: Essential commands for the Spec-Driven Development workflow:
| Command | Description | | Command | Description |
|--------------------------|-----------------------------------------------------------------------| | ----------------------- | ------------------------------------------------------------------------ |
| `/speckit.constitution` | Create or update project governing principles and development guidelines | | `/speckit.constitution` | Create or update project governing principles and development guidelines |
| `/speckit.specify` | Define what you want to build (requirements and user stories) | | `/speckit.specify` | Define what you want to build (requirements and user stories) |
| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | | `/speckit.plan` | Create technical implementation plans with your chosen tech stack |
| `/speckit.tasks` | Generate actionable task lists for implementation | | `/speckit.tasks` | Generate actionable task lists for implementation |
| `/speckit.implement` | Execute all tasks to build the feature according to the plan | | `/speckit.implement` | Execute all tasks to build the feature according to the plan |
#### Optional Commands #### Optional Commands
Additional commands for enhanced quality and validation: Additional commands for enhanced quality and validation:
| Command | Description | | Command | Description |
|----------------------|-----------------------------------------------------------------------| | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | | `/speckit.clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) |
| `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | | `/speckit.analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) |
| `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | | `/speckit.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
### Environment Variables ### Environment Variables
| Variable | Description | | Variable | Description |
|------------------|------------------------------------------------------------------------------------------------| | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>**Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |
## 📚 Core Philosophy ## 📚 Core Philosophy
@@ -285,11 +285,11 @@ Spec-Driven Development is a structured process that emphasizes:
## 🌟 Development Phases ## 🌟 Development Phases
| Phase | Focus | Key Activities | | Phase | Focus | Key Activities |
|-------|-------|----------------| | ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> | | **0-to-1 Development** ("Greenfield") | Generate from scratch | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> | | **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> | | **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
## 🎯 Experimental Goals ## 🎯 Experimental Goals
@@ -407,8 +407,8 @@ This step creates or updates the `.specify/memory/constitution.md` file with you
With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop. With your project principles established, you can now create the functional specifications. Use the `/speckit.specify` command and then provide the concrete requirements for the project you want to develop.
>[!IMPORTANT] > [!IMPORTANT]
>Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**. > Be as explicit as possible about *what* you are trying to build and *why*. **Do not focus on the tech stack at this point**.
An example prompt: An example prompt:
@@ -551,8 +551,8 @@ researching .NET Aspire in general and I don't think that's gonna do much for us
That's way too untargeted research. The research needs to help you solve a specific targeted question. That's way too untargeted research. The research needs to help you solve a specific targeted question.
``` ```
>[!NOTE] > [!NOTE]
>Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change. > Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change.
### **STEP 5:** Have Claude Code validate the plan ### **STEP 5:** Have Claude Code validate the plan
@@ -570,8 +570,8 @@ This helps refine the implementation plan and helps you avoid potential blind sp
You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked. You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.com/en/github-cli/github-cli) installed) to go ahead and create a pull request from your current branch to `main` with a detailed description, to make sure that the effort is properly tracked.
>[!NOTE] > [!NOTE]
>Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan. > Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.
### **STEP 6:** Generate task breakdown with /speckit.tasks ### **STEP 6:** Generate task breakdown with /speckit.tasks
@@ -608,8 +608,8 @@ The `/speckit.implement` command will:
- Follow the TDD approach defined in your task plan - Follow the TDD approach defined in your task plan
- Provide progress updates and handle errors appropriately - Provide progress updates and handle errors appropriately
>[!IMPORTANT] > [!IMPORTANT]
>The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine. > The AI agent will execute local CLI commands (such as `dotnet`, `npm`, etc.) - make sure you have the required tools installed on your machine.
Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution. Once the implementation is complete, test the application and resolve any runtime errors that may not be visible in CLI logs (e.g., browser console errors). You can copy and paste such errors back to your AI agent for resolution.

12
docs/upgrade.md
View File

@@ -86,7 +86,7 @@ specify init --here --force --ai copilot
Without `--force`, the CLI warns you and asks for confirmation: Without `--force`, the CLI warns you and asks for confirmation:
``` ```text
Warning: Current directory is not empty (25 items) Warning: Current directory is not empty (25 items)
Template files will be merged with existing content and may overwrite existing files Template files will be merged with existing content and may overwrite existing files
Proceed? [y/N] Proceed? [y/N]
@@ -286,11 +286,13 @@ This tells Spec Kit which feature directory to use when creating specs, plans, a
1. **Restart your IDE/editor** completely (not just reload window) 1. **Restart your IDE/editor** completely (not just reload window)
2. **For CLI-based agents**, verify files exist: 2. **For CLI-based agents**, verify files exist:
```bash ```bash
ls -la .claude/commands/ # Claude Code ls -la .claude/commands/ # Claude Code
ls -la .gemini/commands/ # Gemini ls -la .gemini/commands/ # Gemini
ls -la .cursor/commands/ # Cursor ls -la .cursor/commands/ # Cursor
``` ```
3. **Check agent-specific setup:** 3. **Check agent-specific setup:**
- Codex requires `CODEX_HOME` environment variable - Codex requires `CODEX_HOME` environment variable
- Some agents need workspace restart or cache clearing - Some agents need workspace restart or cache clearing
@@ -312,7 +314,8 @@ cp /tmp/constitution-backup.md .specify/memory/constitution.md
### "Warning: Current directory is not empty" ### "Warning: Current directory is not empty"
**Full warning message:** **Full warning message:**
```
```text
Warning: Current directory is not empty (25 items) Warning: Current directory is not empty (25 items)
Template files will be merged with existing content and may overwrite existing files Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N] Do you want to continue? [y/N]
@@ -329,6 +332,7 @@ This warning appears when you run `specify init --here` (or `specify init .`) in
**What gets overwritten:** **What gets overwritten:**
Only Spec Kit infrastructure files: Only Spec Kit infrastructure files:
- Agent command files (`.claude/commands/`, `.github/prompts/`, etc.) - Agent command files (`.claude/commands/`, `.github/prompts/`, etc.)
- Scripts in `.specify/scripts/` - Scripts in `.specify/scripts/`
- Templates in `.specify/templates/` - Templates in `.specify/templates/`
@@ -346,6 +350,7 @@ Only Spec Kit infrastructure files:
- **Type `y` and press Enter** - Proceed with the merge (recommended if upgrading) - **Type `y` and press Enter** - Proceed with the merge (recommended if upgrading)
- **Type `n` and press Enter** - Cancel the operation - **Type `n` and press Enter** - Cancel the operation
- **Use `--force` flag** - Skip this confirmation entirely: - **Use `--force` flag** - Skip this confirmation entirely:
```bash ```bash
specify init --here --force --ai copilot specify init --here --force --ai copilot
``` ```
@@ -388,6 +393,7 @@ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
**Explanation:** **Explanation:**
The `specify` CLI tool is used for: The `specify` CLI tool is used for:
- **Initial setup:** `specify init` to bootstrap Spec Kit in your project - **Initial setup:** `specify init` to bootstrap Spec Kit in your project
- **Upgrades:** `specify init --here --force` to update templates and commands - **Upgrades:** `specify init --here --force` to update templates and commands
- **Diagnostics:** `specify check` to verify tool installation - **Diagnostics:** `specify check` to verify tool installation
@@ -397,6 +403,7 @@ Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/s
**If your agent isn't recognizing slash commands:** **If your agent isn't recognizing slash commands:**
1. **Verify command files exist:** 1. **Verify command files exist:**
```bash ```bash
# For GitHub Copilot # For GitHub Copilot
ls -la .github/prompts/ ls -la .github/prompts/
@@ -412,6 +419,7 @@ Once you've run `specify init`, the slash commands (like `/speckit.specify`, `/s
4. **For some agents**, you may need to reload the workspace or clear cache 4. **For some agents**, you may need to reload the workspace or clear cache
**Related issue:** If Copilot can't open local files or uses PowerShell commands unexpectedly, this is typically an IDE context issue, not related to `specify`. Try: **Related issue:** If Copilot can't open local files or uses PowerShell commands unexpectedly, this is typically an IDE context issue, not related to `specify`. Try:
- Restarting VS Code - Restarting VS Code
- Checking file permissions - Checking file permissions
- Ensuring the workspace folder is properly opened - Ensuring the workspace folder is properly opened

9
spec-driven.md
View File

@@ -195,6 +195,7 @@ The templates include comprehensive checklists that act as "unit tests" for the
```markdown ```markdown
### Requirement Completeness ### Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain - [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous - [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable - [ ] Success criteria are measurable
@@ -208,10 +209,14 @@ The implementation plan template enforces architectural principles through phase
```markdown ```markdown
### Phase -1: Pre-Implementation Gates ### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII) #### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects? - [ ] Using ≤3 projects?
- [ ] No future-proofing? - [ ] No future-proofing?
#### Anti-Abstraction Gate (Article VIII) #### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly? - [ ] Using framework directly?
- [ ] Single model representation? - [ ] Single model representation?
``` ```
@@ -347,15 +352,19 @@ The implementation plan template operationalizes these articles through concrete
```markdown ```markdown
### Phase -1: Pre-Implementation Gates ### Phase -1: Pre-Implementation Gates
#### Simplicity Gate (Article VII) #### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects? - [ ] Using ≤3 projects?
- [ ] No future-proofing? - [ ] No future-proofing?
#### Anti-Abstraction Gate (Article VIII) #### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly? - [ ] Using framework directly?
- [ ] Single model representation? - [ ] Single model representation?
#### Integration-First Gate (Article IX) #### Integration-First Gate (Article IX)
- [ ] Contracts defined? - [ ] Contracts defined?
- [ ] Contract tests written? - [ ] Contract tests written?
``` ```

11
templates/commands/specify.md
View File

@@ -40,27 +40,28 @@ Given that feature description, do this:
- "Fix payment processing timeout bug" → "fix-payment-timeout" - "Fix payment processing timeout bug" → "fix-payment-timeout"
2. **Check for existing branches before creating new one**: 2. **Check for existing branches before creating new one**:
a. First, fetch all remote branches to ensure we have the latest information: a. First, fetch all remote branches to ensure we have the latest information:
```bash ```bash
git fetch --all --prune git fetch --all --prune
``` ```
b. Find the highest feature number across all sources for the short-name: b. Find the highest feature number across all sources for the short-name:
- Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'` - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
- Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'` - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
- Specs directories: Check for directories matching `specs/[0-9]+-<short-name>` - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
c. Determine the next available number: c. Determine the next available number:
- Extract all numbers from all three sources - Extract all numbers from all three sources
- Find the highest number N - Find the highest number N
- Use N+1 for the new branch number - Use N+1 for the new branch number
d. Run the script `{SCRIPT}` with the calculated number and short-name: d. Run the script `{SCRIPT}` with the calculated number and short-name:
- Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
- Bash example: `{SCRIPT} --json --number 5 --short-name "user-auth" "Add user authentication"` - Bash example: `{SCRIPT} --json --number 5 --short-name "user-auth" "Add user authentication"`
- PowerShell example: `{SCRIPT} -Json -Number 5 -ShortName "user-auth" "Add user authentication"` - PowerShell example: `{SCRIPT} -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
**IMPORTANT**: **IMPORTANT**:
- Check all three sources (remote branches, local branches, specs directories) to find the highest number - Check all three sources (remote branches, local branches, specs directories) to find the highest number
- Only match branches/directories with the exact short-name pattern - Only match branches/directories with the exact short-name pattern

6
templates/commands/taskstoissues.md
View File

@@ -24,8 +24,10 @@ You **MUST** consider the user input before proceeding (if not empty).
git config --get remote.origin.url git config --get remote.origin.url
``` ```
**ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL** > [!CAUTION]
> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote. 1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
**UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL** > [!CAUTION]
> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL