diff --git a/AGENTS.md b/AGENTS.md index 12745f7f..d7360487 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 202f0634..2b42e8fd 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 b258f87c..76149512 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 035706eb..676e5131 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 3f0ddb78..3c952d68 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 fb6acc17..d6aa3bbf 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