Skip to content

💫 Toolkit to help you get started with SDD or any other process!

Update Markdown formatting

den (work)0049b1cdc2f9
diff --git a/AGENTS.md b/AGENTS.md
index 12745f7fd..d7360487b 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 202f06346..2b42e8fd6 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/. <path-to-test-project>/
```
diff --git a/README.md b/README.md
index b258f87c8..76149512f 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 035706eb8..676e5131f 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 3f0ddb78b..3c952d683 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]+-<short-name>$'`
- Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
- Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
-
+
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 fb6acc179..d6aa3bbf5 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