feat(ci): add markdownlint-cli2 for consistent markdown formatting

Add automated markdown linting to ensure consistent formatting across
all markdown files in the repository.

Changes:
- Add .markdownlint-cli2.jsonc configuration
- Create .github/workflows/lint.yml for CI/CD integration
- Fix all 908 existing markdown errors across 27 files
- Enforce ATX-style headings and asterisk emphasis
- Set consistent 2-space list indentation

This prevents markdown errors after project initialization and
maintains high documentation quality standards.

docs/README.md

@@ -7,11 +7,13 @@ This folder contains the documentation source files for Spec Kit, built using [D
 To build the documentation locally:
 
 1. Install DocFX:
+
    ```bash
    dotnet tool install -g docfx
    ```
 
 2. Build the documentation:
+
    ```bash
    cd docs
    docfx docfx.json --serve
@@ -31,4 +33,3 @@ To build the documentation locally:
 ## Deployment
 
 Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`.
-

docs/index.md

@@ -18,7 +18,7 @@ Spec-Driven Development **flips the script** on traditional software development
 
 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
@@ -36,19 +36,23 @@ Spec-Driven Development is a structured process that emphasizes:
 Our research and experimentation focus on:
 
 ### Technology Independence
+
 - Create applications using diverse technology stacks
 - Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks
 
 ### Enterprise Constraints
+
 - Demonstrate mission-critical application development
 - Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
 - Support enterprise design systems and compliance requirements
 
 ### User-Centric Development
+
 - Build applications for different user cohorts and preferences
 - Support various development approaches (from vibe-coding to AI-native development)
 
 ### Creative & Iterative Processes
+
 - Validate the concept of parallel implementation exploration
 - Provide robust iterative feature development workflows
 - Extend processes to handle upgrades and modernization tasks
@@ -60,4 +64,3 @@ Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main
 ## Support
 
 For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub.
-

docs/installation.md

@@ -42,11 +42,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <project_name
 All automation scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants.
 
 Auto behavior:
+
 - Windows default: `ps`
 - Other OS default: `sh`
 - Interactive mode: you'll be prompted unless you pass `--script`
 
 Force a specific script type:
+
 ```bash
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script sh
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script ps
@@ -63,6 +65,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <project_name
 ## Verification
 
 After initialization, you should see the following commands available in your AI agent:
+
 - `/speckit.specify` - Create specifications
 - `/speckit.plan` - Generate implementation plans  
 - `/speckit.tasks` - Break down into actionable tasks
@@ -87,4 +90,3 @@ git config --global credential.helper manager
 echo "Cleaning up..."
 rm gcm-linux_amd64.2.6.1.deb
 ```
-

docs/local-development.md

@@ -73,12 +73,14 @@ uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --igno
 ```
 
 Set an environment variable for convenience:
+
 ```bash
 export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
 uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps
 ```
 
 (Optional) Define a shell function:
+
 ```bash
 specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
 # Then
@@ -93,11 +95,13 @@ After running an `init`, check that shell scripts are executable on POSIX system
 ls -l scripts | grep .sh
 # Expect owner execute bit (e.g. -rwxr-xr-x)
 ```
+
 On Windows you will instead use the `.ps1` scripts (no chmod needed).
 
 ## 6. Run Lint / Basic Checks (Add Your Own)
 
 Currently no enforced lint config is bundled, but you can quickly sanity check importability:
+
 ```bash
 python -c "import specify_cli; print('Import OK')"
 ```
@@ -110,6 +114,7 @@ Validate packaging before publishing:
 uv build
 ls dist/
 ```
+
 Install the built artifact into a fresh throwaway environment if needed.
 
 ## 8. Using a Temporary Workspace
@@ -120,6 +125,7 @@ When testing `init --here` in a dirty directory, create a temp workspace:
 mkdir /tmp/spec-test && cd /tmp/spec-test
 python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh  # if repo copied here
 ```
+
 Or copy only the modified CLI portion if you want a lighter sandbox.
 
 ## 9. Debug Network / TLS Skips
@@ -130,6 +136,7 @@ If you need to bypass TLS validation while experimenting:
 specify check --skip-tls
 specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps
 ```
+
 (Use only for local experimentation.)
 
 ## 10. Rapid Edit Loop Summary
@@ -146,6 +153,7 @@ specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps
 ## 11. Cleaning Up
 
 Remove build artifacts / virtual env quickly:
+
 ```bash
 rm -rf .venv dist build *.egg-info
 ```
@@ -165,5 +173,3 @@ rm -rf .venv dist build *.egg-info
 - Update docs and run through Quick Start using your modified CLI
 - Open a PR when satisfied
 - (Optional) Tag a release once changes land in `main`
-
-

docs/quickstart.md

@@ -15,6 +15,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME
 ```
 
 Pick script type explicitly (optional):
+
 ```bash
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script ps  # Force PowerShell
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh  # Force POSIX shell
@@ -120,4 +121,3 @@ implement specs/002-create-taskify/plan.md
 - Read the complete methodology for in-depth guidance
 - Check out more examples in the repository
 - Explore the source code on GitHub
-