From c03f02da401031653145202714f8452f0469f6b1 Mon Sep 17 00:00:00 2001 From: amuzip Date: Thu, 5 Feb 2026 15:44:53 +0900 Subject: [PATCH] fix: resolve markdownlint errors across documentation - Add language specifiers to fenced code blocks (bash, text) - Fix whitespace issues around code fences - Disable MD036 (emphasis as heading) for intentional warning text - Disable MD060 (table column style) for existing table formats Co-Authored-By: Claude Opus 4.5 --- .markdownlint-cli2.jsonc | 4 +++- CONTRIBUTING.md | 4 ++-- docs/upgrade.md | 12 ++++++++++-- templates/commands/specify.md | 11 ++++++----- 4 files changed, 21 insertions(+), 10 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index d6db02777c..0108b9f234 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -19,7 +19,9 @@ }, "MD050": { "style": "asterisk" - } + }, + "MD036": false, + "MD060": false }, "ignores": [ ".genreleases/" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c413dd0184..f5e4593c95 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/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