From 3e883fa32ca768629abeb5065d51c5926b525cc9 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Thu, 4 Dec 2025 11:50:36 -0800 Subject: [PATCH 1/2] Update Markdown formatting --- AGENTS.md | 44 ++++++++-------- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 6 +-- README.md | 126 ++++++++++++++++++++++----------------------- spec-driven.md | 9 ++++ 5 files changed, 98 insertions(+), 89 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b72dd74d3e..12745f7fd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,25 +29,25 @@ Specify supports multiple AI agents by generating agent-specific command files a ### Current Supported Agents -| Agent | Directory | Format | CLI Tool | Description | -|-------|-----------|---------|----------|-------------| -| **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code 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 | -| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI | -| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI | -| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI | -| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI | -| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows | -| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE | -| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI | -| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE | -| **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI | -| **Qoder CLI** | `.qoder/commands/` | Markdown | `qoder` | Qoder CLI | -| **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI | -| **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI | -| **SHAI** | `.shai/commands/` | Markdown | `shai` | SHAI CLI | -| **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE | +| Agent | Directory | Format | CLI Tool | Description | +| -------------------------- | ---------------------- | -------- | --------------- | --------------------------- | +| **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code 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 | +| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI | +| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI | +| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI | +| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI | +| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows | +| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE | +| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI | +| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE | +| **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI | +| **Qoder CLI** | `.qoder/commands/` | Markdown | `qoder` | Qoder CLI | +| **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI | +| **Amp** | `.agents/commands/` | Markdown | `amp` | Amp CLI | +| **SHAI** | `.shai/commands/` | Markdown | `shai` | SHAI CLI | +| **IBM Bob** | `.bob/commands/` | Markdown | N/A (IDE-based) | IBM Bob IDE | ### Step-by-Step Integration Guide @@ -153,7 +153,7 @@ Add to case statement: case "$AGENT_TYPE" in # ... existing cases ... windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;; - "") + "") # ... existing checks ... [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf"; # Update default creation condition @@ -307,7 +307,7 @@ echo "✅ Done" Require a command-line tool to be installed: - **Claude Code**: `claude` CLI -- **Gemini CLI**: `gemini` CLI +- **Gemini CLI**: `gemini` CLI - **Cursor**: `cursor-agent` CLI - **Qwen Code**: `qwen` CLI - **opencode**: `opencode` CLI @@ -410,4 +410,4 @@ When adding new agents: --- -*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* +_This documentation should be updated whenever new agents are added to maintain accuracy and completeness._ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 73a27ec93d..a08311e675 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -23,7 +23,7 @@ include: Examples of unacceptable behavior by participants include: - The use of sexualized language or imagery and unwelcome sexual attention or -advances + advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information, such as a physical or electronic diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c413dd0184..202f06346d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,8 +32,8 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler ## Submitting a pull request ->[!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. +> [!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. 1. Fork and clone the repository 1. Configure and install the dependencies: `uv sync` @@ -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 - **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 - **Your own analysis** - Share your thoughts on the end-to-end developer experience diff --git a/README.md b/README.md index 27ab8372f6..b258f87c88 100644 --- a/README.md +++ b/README.md @@ -142,26 +142,26 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c ## 🤖 Supported AI Agents -| Agent | Support | Notes | -|-----------------------------------------------------------|---------|---------------------------------------------------| -| [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. | -| [Amp](https://ampcode.com/) | ✅ | | -| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | | -| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | -| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | | -| [Codex CLI](https://github.com/openai/codex) | ✅ | | -| [Cursor](https://cursor.sh/) | ✅ | | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | -| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | | -| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support | -| [Jules](https://jules.google.com/) | ✅ | | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | | -| [opencode](https://opencode.ai/) | ✅ | | -| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | | -| [Roo Code](https://roocode.com/) | ✅ | | -| [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | | -| [Windsurf](https://windsurf.com/) | ✅ | | +| Agent | Support | Notes | +| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| [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. | +| [Amp](https://ampcode.com/) | ✅ | | +| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | ✅ | | +| [Claude Code](https://www.anthropic.com/claude-code) | ✅ | | +| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | ✅ | | +| [Codex CLI](https://github.com/openai/codex) | ✅ | | +| [Cursor](https://cursor.sh/) | ✅ | | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ | | +| [GitHub Copilot](https://code.visualstudio.com/) | ✅ | | +| [IBM Bob](https://www.ibm.com/products/bob) | ✅ | IDE-based agent with slash command support | +| [Jules](https://jules.google.com/) | ✅ | | +| [Kilo Code](https://github.com/Kilo-Org/kilocode) | ✅ | | +| [opencode](https://opencode.ai/) | ✅ | | +| [Qwen Code](https://github.com/QwenLM/qwen-code) | ✅ | | +| [Roo Code](https://roocode.com/) | ✅ | | +| [SHAI (OVHcloud)](https://github.com/ovh/shai) | ✅ | | +| [Windsurf](https://windsurf.com/) | ✅ | | ## 🔧 Specify CLI Reference @@ -169,25 +169,25 @@ The `specify` command supports the following options: ### Commands -| Command | Description | -|-------------|----------------------------------------------------------------| -| `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`) | +| Command | Description | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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`) | ### `specify init` Arguments & Options -| Argument/Option | Type | Description | -|------------------------|----------|------------------------------------------------------------------------------| -| `` | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) | +| Argument/Option | Type | Description | +| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `` | 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` | -| `--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 | -| `--no-git` | Flag | Skip git repository initialization | -| `--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) | -| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | -| `--debug` | Flag | Enable detailed debug output for troubleshooting | -| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | +| `--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 | +| `--no-git` | Flag | Skip git repository initialization | +| `--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) | +| `--skip-tls` | Flag | Skip SSL/TLS verification (not recommended) | +| `--debug` | Flag | Enable detailed debug output for troubleshooting | +| `--github-token` | Option | GitHub token for API requests (or set GH_TOKEN/GITHUB_TOKEN env variable) | ### Examples @@ -250,46 +250,46 @@ After running `specify init`, your AI coding agent will have access to these sla Essential commands for the Spec-Driven Development workflow: -| Command | Description | -|--------------------------|-----------------------------------------------------------------------| -| `/speckit.constitution` | Create or update project governing principles and development guidelines | -| `/speckit.specify` | Define what you want to build (requirements and user stories) | -| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | -| `/speckit.tasks` | Generate actionable task lists for implementation | -| `/speckit.implement` | Execute all tasks to build the feature according to the plan | +| Command | Description | +| ----------------------- | ------------------------------------------------------------------------ | +| `/speckit.constitution` | Create or update project governing principles and development guidelines | +| `/speckit.specify` | Define what you want to build (requirements and user stories) | +| `/speckit.plan` | Create technical implementation plans with your chosen tech stack | +| `/speckit.tasks` | Generate actionable task lists for implementation | +| `/speckit.implement` | Execute all tasks to build the feature according to the plan | #### Optional Commands Additional commands for enhanced quality and validation: -| Command | Description | -|----------------------|-----------------------------------------------------------------------| -| `/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`) | +| Command | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `/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.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | ### Environment Variables -| 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.
**Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | +| 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.
\*\*Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. | ## 📚 Core Philosophy Spec-Driven Development is a structured process that emphasizes: -- **Intent-driven development** where specifications define the "*what*" before the "*how*" +- **Intent-driven development** where specifications define the "_what_" before the "_how_" - **Rich specification creation** using guardrails and organizational principles - **Multi-step refinement** rather than one-shot code generation from prompts - **Heavy reliance** on advanced AI model capabilities for specification interpretation ## 🌟 Development Phases -| Phase | Focus | Key Activities | -|-------|-------|----------------| -| **0-to-1 Development** ("Greenfield") | Generate from scratch | | -| **Creative Exploration** | Parallel implementations | | -| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | +| Phase | Focus | Key Activities | +| ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **0-to-1 Development** ("Greenfield") | Generate from scratch | | +| **Creative Exploration** | Parallel implementations | | +| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | ## 🎯 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. ->[!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**. +> [!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**. 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. ``` ->[!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. +> [!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. ### **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. ->[!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. +> [!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. ### **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 - Provide progress updates and handle errors appropriately ->[!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. +> [!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. 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. diff --git a/spec-driven.md b/spec-driven.md index 0e546ff3c4..70b9789708 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -195,6 +195,7 @@ The templates include comprehensive checklists that act as "unit tests" for the ```markdown ### Requirement Completeness + - [ ] No [NEEDS CLARIFICATION] markers remain - [ ] Requirements are testable and unambiguous - [ ] Success criteria are measurable @@ -208,10 +209,14 @@ The implementation plan template enforces architectural principles through phase ```markdown ### Phase -1: Pre-Implementation Gates + #### Simplicity Gate (Article VII) + - [ ] Using ≤3 projects? - [ ] No future-proofing? + #### Anti-Abstraction Gate (Article VIII) + - [ ] Using framework directly? - [ ] Single model representation? ``` @@ -347,15 +352,19 @@ The implementation plan template operationalizes these articles through concrete ```markdown ### Phase -1: Pre-Implementation Gates + #### Simplicity Gate (Article VII) + - [ ] Using ≤3 projects? - [ ] No future-proofing? #### Anti-Abstraction Gate (Article VIII) + - [ ] Using framework directly? - [ ] Single model representation? #### Integration-First Gate (Article IX) + - [ ] Contracts defined? - [ ] Contract tests written? ``` From 0049b1cdc2f9ba12def39a042872b0b1b6a09704 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Thu, 4 Dec 2025 11:55:56 -0800 Subject: [PATCH 2/2] Update Markdown formatting --- AGENTS.md | 2 +- CONTRIBUTING.md | 4 ++-- README.md | 4 ++-- docs/upgrade.md | 12 ++++++++++-- templates/commands/specify.md | 11 ++++++----- templates/commands/taskstoissues.md | 6 ++++-- 6 files changed, 25 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 12745f7fd9..d7360487b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -410,4 +410,4 @@ When adding new agents: --- -_This documentation should be updated whenever new agents are added to maintain accuracy and completeness._ +*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 202f06346d..2b42e8fd61 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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: - ``` + ```bash ./.github/workflows/scripts/create-release-packages.sh v1.0.0 ``` 2. **Copy the relevant package to your test project** - ``` + ```bash cp -r .genreleases/sdd-copilot-package-sh/. / ``` diff --git a/README.md b/README.md index b258f87c88..76149512f6 100644 --- a/README.md +++ b/README.md @@ -278,7 +278,7 @@ Additional commands for enhanced quality and validation: Spec-Driven Development is a structured process that emphasizes: -- **Intent-driven development** where specifications define the "_what_" before the "_how_" +- **Intent-driven development** where specifications define the "*what*" before the "*how*" - **Rich specification creation** using guardrails and organizational principles - **Multi-step refinement** rather than one-shot code generation from prompts - **Heavy reliance** on advanced AI model capabilities for specification interpretation @@ -408,7 +408,7 @@ 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. > [!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: diff --git a/docs/upgrade.md b/docs/upgrade.md index 035706eb88..676e5131f0 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -86,7 +86,7 @@ specify init --here --force --ai copilot Without `--force`, the CLI warns you and asks for confirmation: -``` +```text Warning: Current directory is not empty (25 items) Template files will be merged with existing content and may overwrite existing files 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) 2. **For CLI-based agents**, verify files exist: + ```bash ls -la .claude/commands/ # Claude Code ls -la .gemini/commands/ # Gemini ls -la .cursor/commands/ # Cursor ``` + 3. **Check agent-specific setup:** - Codex requires `CODEX_HOME` environment variable - 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" **Full warning message:** -``` + +```text Warning: Current directory is not empty (25 items) Template files will be merged with existing content and may overwrite existing files 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:** Only Spec Kit infrastructure files: + - Agent command files (`.claude/commands/`, `.github/prompts/`, etc.) - Scripts in `.specify/scripts/` - 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 `n` and press Enter** - Cancel the operation - **Use `--force` flag** - Skip this confirmation entirely: + ```bash 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:** The `specify` CLI tool is used for: + - **Initial setup:** `specify init` to bootstrap Spec Kit in your project - **Upgrades:** `specify init --here --force` to update templates and commands - **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:** 1. **Verify command files exist:** + ```bash # For GitHub Copilot 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 **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 - Checking file permissions - Ensuring the workspace folder is properly opened diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 3f0ddb78b1..3c952d683e 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -40,27 +40,28 @@ Given that feature description, do this: - "Fix payment processing timeout bug" → "fix-payment-timeout" 2. **Check for existing branches before creating new one**: - + a. First, fetch all remote branches to ensure we have the latest information: + ```bash git fetch --all --prune ``` - + 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]+-$'` - Local branches: `git branch | grep -E '^[* ]*[0-9]+-$'` - Specs directories: Check for directories matching `specs/[0-9]+-` - + c. Determine the next available number: - Extract all numbers from all three sources - Find the highest number N - Use N+1 for the new branch number - + 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 - 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"` - + **IMPORTANT**: - 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 diff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.md index fb6acc1791..d6aa3bbf55 100644 --- a/templates/commands/taskstoissues.md +++ b/templates/commands/taskstoissues.md @@ -24,8 +24,10 @@ You **MUST** consider the user input before proceeding (if not empty). 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. -**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