Merge branch 'main' into update-user-guide-docs

Author: localden

.github/workflows/lint.yml

@@ -0,0 +1,18 @@
+name: Lint
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: '**/*.md'

.markdownlint-cli2.jsonc

@@ -0,0 +1,24 @@
+{
+  // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+  "config": {
+    "default": true,
+    "MD003": {
+      "style": "atx"
+    },
+    "MD007": {
+      "indent": 2
+    },
+    "MD013": false,
+    "MD024": {
+      "siblings_only": true
+    },
+    "MD033": false,
+    "MD041": false,
+    "MD049": {
+      "style": "asterisk"
+    },
+    "MD050": {
+      "style": "asterisk"
+    }
+  }
+}

AGENTS.md

@@ -68,12 +68,14 @@ AGENT_CONFIG = {
 ```
 
 **Key Design Principle**: The dictionary key should match the actual executable name that users install. For example:
+
 - ✅ Use `"cursor-agent"` because the CLI tool is literally called `cursor-agent`
 - ❌ Don't use `"cursor"` as a shortcut if the tool is `cursor-agent`
 
 This eliminates the need for special-case mappings throughout the codebase.
 
 **Field Explanations**:
+
 - `name`: Human-readable display name shown to users
 - `folder`: Directory where agent-specific files are stored (relative to project root)
 - `install_url`: Installation documentation URL (set to `None` for IDE-based agents)
@@ -102,12 +104,14 @@ Update the **Supported AI Agents** section in `README.md` to include the new age
 
 Modify `.github/workflows/scripts/create-release-packages.sh`:
 
-##### Add to ALL_AGENTS array:
+##### Add to ALL_AGENTS array
+
 ```bash
 ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q)
 ```
 
-##### Add case statement for directory structure:
+##### Add case statement for directory structure
+
 ```bash
 case $agent in
   # ... existing cases ...
@@ -131,14 +135,16 @@ gh release create "$VERSION" \
 
 #### 5. Update Agent Context Scripts
 
-##### Bash script (`scripts/bash/update-agent-context.sh`):
+##### Bash script (`scripts/bash/update-agent-context.sh`)
 
 Add file variable:
+
 ```bash
 WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
 ```
 
 Add to case statement:
+
 ```bash
 case "$AGENT_TYPE" in
   # ... existing cases ...
@@ -151,14 +157,16 @@ case "$AGENT_TYPE" in
 esac
 ```
 
-##### PowerShell script (`scripts/powershell/update-agent-context.ps1`):
+##### PowerShell script (`scripts/powershell/update-agent-context.ps1`)
 
 Add file variable:
+
 ```powershell
 $windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'
 ```
 
 Add to switch statement:
+
 ```powershell
 switch ($AgentType) {
     # ... existing cases ...
@@ -200,13 +208,15 @@ elif selected_ai == "windsurf":
 **CRITICAL**: When adding a new agent to AGENT_CONFIG, always use the **actual executable name** as the dictionary key, not a shortened or convenient version.
 
 **Why this matters:**
+
 - The `check_tool()` function uses `shutil.which(tool)` to find executables in the system PATH
 - If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
 - This creates unnecessary complexity and maintenance burden
 
 **Example - The Cursor Lesson:**
 
 ❌ **Wrong approach** (requires special-case mapping):
+
 ```python
 AGENT_CONFIG = {
     "cursor": {  # Shorthand that doesn't match the actual tool
@@ -222,6 +232,7 @@ if agent_key == "cursor":
 ```
 
 ✅ **Correct approach** (no mapping needed):
+
 ```python
 AGENT_CONFIG = {
     "cursor-agent": {  # Matches the actual executable name
@@ -234,6 +245,7 @@ AGENT_CONFIG = {
 ```
 
 **Benefits of this approach:**
+
 - Eliminates special-case logic scattered throughout the codebase
 - Makes the code more maintainable and easier to understand
 - Reduces the chance of bugs when adding new agents
@@ -289,6 +301,7 @@ echo "✅ Done"
 ### CLI-Based Agents
 
 Require a command-line tool to be installed:
+
 - **Claude Code**: `claude` CLI
 - **Gemini CLI**: `gemini` CLI  
 - **Cursor**: `cursor-agent` CLI
@@ -298,13 +311,16 @@ Require a command-line tool to be installed:
 - **CodeBuddy CLI**: `codebuddy` CLI
 
 ### IDE-Based Agents
+
 Work within integrated development environments:
+
 - **GitHub Copilot**: Built into VS Code/compatible editors
 - **Windsurf**: Built into Windsurf IDE
 
 ## Command File Formats
 
 ### Markdown Format
+
 Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer
 
 ```markdown
@@ -316,6 +332,7 @@ Command content with {SCRIPT} and $ARGUMENTS placeholders.
 ```
 
 ### TOML Format
+
 Used by: Gemini, Qwen
 
 ```toml
@@ -337,6 +354,7 @@ Command content with {SCRIPT} and {{args}} placeholders.
 ## Argument Patterns
 
 Different agents use different argument placeholders:
+
 - **Markdown/prompt-based**: `$ARGUMENTS`
 - **TOML-based**: `{{args}}`
 - **Script placeholders**: `{SCRIPT}` (replaced with actual script path)
@@ -372,4 +390,3 @@ When adding new agents:
 ---
 
 *This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*
-

CHANGELOG.md

@@ -63,7 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - New `/clarify` command template to surface up to 5 targeted clarification questions for an existing spec and persist answers into a Clarifications section in the spec.
 - New `/analyze` command template providing a non-destructive cross-artifact discrepancy and alignment report (spec, clarifications, plan, tasks, constitution) inserted after `/tasks` and before `/implement`.
-	- Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles.
+  - Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles.
 
 ## [0.0.16] - 2025-09-22
 
@@ -140,7 +140,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated command instructions in the CLI.
 - Cleaned up the code to not render agent-specific information when it's generic.
 
-
 ## [0.0.6] - 2025-09-17
 
 ### Added
@@ -166,4 +165,3 @@ N/A
 ### Changed
 
 N/A
-

CODE_OF_CONDUCT.md

@@ -14,21 +14,21 @@ orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 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
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
   address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing to Spec Kit
+# Contributing to Spec Kit
 
 Hi there! We're thrilled that you'd like to contribute to Spec Kit. Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE).
 

README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img src="./media/logo_small.webp"/>
+    <img src="./media/logo_small.webp" alt="Spec Kit Logo"/>
     <h1>🌱 Spec Kit</h1>
     <h3><em>Build high-quality software faster.</em></h3>
 </div>
@@ -253,7 +253,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
@@ -383,7 +383,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:
 
@@ -417,16 +417,16 @@ At this stage, your project folder contents should resemble the following:
 ```text
 └── .specify
     ├── memory
-    │	 └── constitution.md
+    │  └── constitution.md
     ├── scripts
-    │	 ├── check-prerequisites.sh
-    │	 ├── common.sh
-    │	 ├── create-new-feature.sh
-    │	 ├── setup-plan.sh
-    │	 └── update-claude-md.sh
+    │  ├── check-prerequisites.sh
+    │  ├── common.sh
+    │  ├── create-new-feature.sh
+    │  ├── setup-plan.sh
+    │  └── update-claude-md.sh
     ├── specs
-    │	 └── 001-create-taskify
-    │	     └── spec.md
+    │  └── 001-create-taskify
+    │      └── spec.md
     └── templates
         ├── plan-template.md
         ├── spec-template.md
@@ -440,6 +440,7 @@ With the baseline specification created, you can go ahead and clarify any of the
 You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream.
 
 Preferred order:
+
 1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section.
 2. Optionally follow up with ad-hoc free-form refinement if something still feels vague.
 
@@ -477,23 +478,23 @@ The output of this step will include a number of implementation detail documents
 .
 ├── CLAUDE.md
 ├── memory
-│	 └── constitution.md
+│  └── constitution.md
 ├── scripts
-│	 ├── check-prerequisites.sh
-│	 ├── common.sh
-│	 ├── create-new-feature.sh
-│	 ├── setup-plan.sh
-│	 └── update-claude-md.sh
+│  ├── check-prerequisites.sh
+│  ├── common.sh
+│  ├── create-new-feature.sh
+│  ├── setup-plan.sh
+│  └── update-claude-md.sh
 ├── specs
-│	 └── 001-create-taskify
-│	     ├── contracts
-│	     │	 ├── api-spec.json
-│	     │	 └── signalr-spec.md
-│	     ├── data-model.md
-│	     ├── plan.md
-│	     ├── quickstart.md
-│	     ├── research.md
-│	     └── spec.md
+│  └── 001-create-taskify
+│      ├── contracts
+│      │  ├── api-spec.json
+│      │  └── signalr-spec.md
+│      ├── data-model.md
+│      ├── plan.md
+│      ├── quickstart.md
+│      ├── research.md
+│      └── spec.md
 └── templates
     ├── CLAUDE-template.md
     ├── plan-template.md
@@ -575,6 +576,7 @@ Once ready, use the `/speckit.implement` command to execute your implementation
 ```
 
 The `/speckit.implement` command will:
+
 - Validate that all prerequisites are in place (constitution, spec, plan, and tasks)
 - Parse the task breakdown from `tasks.md`
 - Execute tasks in the correct order, respecting dependencies and parallel execution markers
@@ -625,4 +627,3 @@ This project is heavily influenced by and based on the work and research of [Joh
 ## 📄 License
 
 This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms.
-

SECURITY.md

@@ -1,10 +1,10 @@
-Thanks for helping make GitHub safe for everyone.
+# Security Policy
 
-# Security
+Thanks for helping make GitHub safe for everyone.
 
 GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub).
 
-Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. 
+Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation.
 
 ## Reporting Security Issues
 
@@ -16,13 +16,13 @@ Instead, please send an email to opensource-security[@]github.com.
 
 Please include as much of the information listed below as you can to help us better understand and resolve the issue:
 
-  * The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
-  * Full paths of source file(s) related to the manifestation of the issue
-  * The location of the affected source code (tag/branch/commit or direct URL)
-  * Any special configuration required to reproduce the issue
-  * Step-by-step instructions to reproduce the issue
-  * Proof-of-concept or exploit code (if possible)
-  * Impact of the issue, including how an attacker might exploit the issue
+- The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
 
 This information will help us triage your report more quickly.