diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 00000000..fa20c809
--- /dev/null
+++ b/.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'
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
new file mode 100644
index 00000000..a96fd3e6
--- /dev/null
+++ b/.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"
+ }
+ }
+}
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8259e8f1..ea672914 100644
--- a/CHANGELOG.md
+++ b/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
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 6dc4b121..73a27ec9 100644
--- a/CODE_OF_CONDUCT.md
+++ b/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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index da41f476..3e6e24aa 100644
--- a/CONTRIBUTING.md
+++ b/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).
diff --git a/README.md b/README.md
index 27fce788..fed79325 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
🌱 Spec Kit
Build high-quality software faster.
@@ -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:
diff --git a/SECURITY.md b/SECURITY.md
index 6424c8b2..4c1e92da 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,6 +1,6 @@
-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).
@@ -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.
diff --git a/templates/agent-file-template.md b/templates/agent-file-template.md
index 27961a8b..4cc7fd66 100644
--- a/templates/agent-file-template.md
+++ b/templates/agent-file-template.md
@@ -8,7 +8,7 @@ Auto-generated from all feature plans. Last updated: [DATE]
## Project Structure
-```
+```text
[ACTUAL STRUCTURE FROM PLANS]
```
diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md
index d43a7948..4de842aa 100644
--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -93,11 +93,11 @@ Execution steps:
- Each question must be answerable with EITHER:
- A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
- A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
- - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
- - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
- - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
- - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
- - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+ - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+ - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+ - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+ - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+ - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
4. Sequential questioning loop (interactive):
- Present EXACTLY ONE question at a time.
@@ -115,8 +115,8 @@ Execution steps:
|--------|-------------|
| A |
+