Appendix B: Recommended Tool Stack

This appendix provides a comprehensive reference for tools that support Spec-Driven Development. Each layer includes tools with descriptions, when to use them in SDD, and one-line getting started commands.

Layer Overview

Layer	Category	Primary Tools	SDD Role
1	Specification Authoring	Markdown, Vale, Nunjucks	Create and validate specs
2	AI Coding Agents	Cursor, Claude, Windsurf, OpenAI API	Generate code from specs
3	Agent Configuration	SKILL.md, AGENTS.md, .cursor/rules, MCP	Guide AI behavior
4	Version Control	Git, GitHub, GitLab	Spec-first workflows
5	Testing	Vitest, Playwright, Pytest	Validate against specs
6	Contract Testing	Pact, Specmatic, Prism	API contract validation
7	CI/CD	GitHub Actions, GitLab CI	Spec validation pipelines
8	Observability	OpenTelemetry, Grafana	SDD-specific instrumentation
9	Security Scanning	Snyk, Semgrep, Trivy	AI-generated code review
10	Documentation	Docusaurus, MkDocs	Publish specifications

1. Specification Authoring

Tool	What It Does	When to Use in SDD	Getting Started
VS Code / Cursor	Markdown editing with preview, extensions	Primary editor for spec authoring; AI-assisted spec expansion	`code specs/` or open in Cursor
Typora	WYSIWYG Markdown editor	When non-technical stakeholders need to edit specs	Download from typora.io
Vale	Prose linter for style and consistency	Enforce spec writing standards; catch passive voice, jargon	`vale specs/`
markdownlint	Markdown structure and syntax linting	Ensure valid Markdown; consistent formatting	`npx markdownlint-cli specs/*/.md`
Nunjucks / Handlebars	Template engines for spec generation	Generate specs from templates with variables	`npm install nunjucks`
Mermaid	Diagram-as-code (flowcharts, sequences)	Embed architecture diagrams in specs	````mermaid graph TD` in Markdown
Structurizr	C4 model for architecture diagrams	Document system context in spec appendices	`structurizr export -workspace workspace.dsl`

Spec Linter Configuration (Vale)

# .vale.ini
StylesPath = styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Google, write-good

SDD-specific: Use Vale to enforce "Given/When/Then" in acceptance criteria, flag [NEEDS CLARIFICATION] resolution, and check for vague terms ("appropriate," "properly").

2. AI Coding Agents

Tool	What It Does	When to Use in SDD	Getting Started
Cursor	VS Code fork with integrated AI; rules, skills, agents	Primary SDD agent; spec-in-context, plan-driven tasks	`cursor .` (open project)
Claude Code (Anthropic)	Standalone AI coding assistant	When Cursor unavailable; spec-to-code generation	`claude` or API
Gemini CLI (Google)	Command-line AI for code generation	Multi-modal spec analysis; code generation	`gemini generate "implement spec"'`
Windsurf	AI-powered IDE (Codeium)	Alternative to Cursor; spec-aware coding	`ws .` (open project)
GitHub Copilot	Inline code completion and chat	Lightweight AI assist; less spec-centric	Enable in VS Code/Cursor
OpenAI API (Responses API)	Programmatic agentic code generation with tools	CI/CD automation, spec-to-plan assistants, eval-driven pipelines	`npm install openai`

AI Coding Agents Comparison

Feature	Cursor	Claude Code	Windsurf	Copilot
Spec-in-context	✅ Rules, skills	✅ Manual paste	✅ Rules	⚠️ Limited
Plan-driven tasks	✅ tasks.md	⚠️ Manual	✅ Tasks	❌
SKILL.md support	✅ Native	❌	⚠️ Custom	❌
.cursor/rules	✅	❌	✅	❌
Multi-file editing	✅	✅	✅	⚠️ Chat only
Cost model	Subscription	API/Pro	Freemium	Subscription
Best for SDD	Primary	Spec-heavy batches	Cursor alternative	Light assist

SDD recommendation: Use Cursor as primary agent for its rules, skills, and spec-driven workflow. Claude Code for batch spec processing. Windsurf if team prefers Codeium models.

API currency note (2026): Prefer modern APIs such as OpenAI Responses API and equivalent current endpoints from other providers. Avoid legacy completion-style examples tied to retired models.

3. Agent Configuration

Tool/Standard	What It Does	When to Use in SDD	Getting Started
SKILL.md	Reusable skill definitions for AI agents	Package domain knowledge, workflows, constraints	Create `skills/[skill-name]/SKILL.md`
AGENTS.md	Agent role definitions and handoff protocols	Define spec→plan→task agent flow; subagent orchestration	Create `AGENTS.md` in project root
.cursor/rules/	Cursor-specific rules (MDC format)	Per-file, per-folder AI guidance; constitution enforcement	Create `.cursor/rules/constitution.mdc`
.cursorrules	Legacy single-file rules	Simple projects; single rule file	Create `.cursorrules` in project root
RULE.md	File-specific AI instructions	Override behavior for spec files, plan files	Create RULE.md in specs/
MCP (Model Context Protocol)	Standardized tool/context integration for agents	Connect agents to repositories, docs, ticketing, and internal systems	Configure MCP servers in your agent runtime
A2A (Agent2Agent)	Protocol for interoperability between specialized agents	Multi-agent workflows: planner agent, implementer agent, reviewer agent	Use an A2A-compatible gateway/runtime

Configuration Hierarchy

AGENTS.md          → Agent roles, handoffs
.cursor/rules/     → Globs: specs/**, src/**
  constitution.mdc → Load constitution for all spec work
  sdd-workflow.mdc → Spec→Plan→Task flow
.cursorrules       → Fallback global rules
specs/RULE.md      → Spec-specific: "Focus on WHAT not HOW"

SKILL.md Template Snippet

# Skill: [Name]
## When to Use
Use when [condition].
## Instructions
1. [Step]
2. [Step]
## Output
[Expected format]

SDD-specific: Create skills for /speckit.specify, /speckit.plan, /speckit.tasks to standardize AI behavior across the pipeline.

4. Version Control

Tool	What It Does	When to Use in SDD	Getting Started
Git	Distributed version control	Core VCS for specs and code	`git init`
GitHub	Hosting, PRs, Actions	Spec-first PR workflow; branch per feature	`gh repo create`
GitLab	Hosting, CI/CD, MRs	Alternative to GitHub; built-in CI	`gitlab-create-project`
Git LFS	Large file storage	If specs include diagrams, assets	`git lfs install`

Git Workflow for Spec-Driven Development

Practice	Command/Pattern	Purpose
Branch per feature	`git checkout -b 004-real-time-chat`	Isolate spec + plan + code
Spec-first commits	Commit `spec.md` before `plan.md`	Traceability
Branch naming	`[number]-[kebab-case]` e.g. `004-real-time-chat`	Consistent, sortable
PR template	Include spec link, AC checklist	Enforce spec→code linkage

Branch Naming Convention

[FEATURE_NUMBER]-[short-description]

Examples:
003-password-reset
004-real-time-chat
005-csv-export

PR Template (GitHub)

## Spec
- [ ] spec.md reviewed and approved
- [ ] plan.md aligns with spec
- [ ] All [NEEDS CLARIFICATION] resolved

## Implementation
- [ ] Phase gates passed
- [ ] Contract tests pass
- [ ] Integration tests pass

5. Testing

Tool	What It Does	When to Use in SDD	Getting Started
Vitest	Fast unit/integration test runner (Vite)	JS/TS: contract tests, integration tests	`npm create vitest@latest`
Jest	Unit/integration testing	JS/TS: established projects	`npm install jest --save-dev`
Playwright	E2E browser testing	Validate user journeys from spec	`npm init playwright@latest`
Cypress	E2E testing with time-travel	Alternative to Playwright	`npm install cypress --save-dev`
Pytest	Python testing framework	Python: integration, property-based	`pip install pytest`
Cucumber	BDD with Gherkin	Acceptance criteria as executable specs	`npm install @cucumber/cucumber`
fast-check	Property-based testing (JS/TS)	Edge cases, invariants from spec	`npm install fast-check`
Hypothesis	Property-based testing (Python)	Python: property-based	`pip install hypothesis`

Test Tool Use Case Mapping

Use Case	Tool	SDD Mapping
Contract validation	Vitest + OpenAPI	plan.md contracts
Integration (real DB)	Vitest/Jest + Testcontainers	plan.md phases
E2E user flows	Playwright	spec.md user journeys
Acceptance criteria	Cucumber (Gherkin)	spec.md AC-*
Edge cases	fast-check, Hypothesis	spec.md edge cases
Performance NFRs	k6, Artillery	spec.md NFR-*

One-Line Commands

# Vitest
npx vitest run

# Playwright
npx playwright test

# Pytest
pytest tests/ -v

# fast-check (in test file)
import * as fc from 'fast-check';

6. Contract Testing

Tool	What It Does	When to Use in SDD	Getting Started
Pact	Consumer-driven contract testing	Microservices; consumer defines contract	`npm install @pact-foundation/pact`
Specmatic	Contract-first; OpenAPI as source of truth	REST APIs; spec→contract→test	`npx specmatic test`
Prism	OpenAPI mock server + validation	Mock API from contract; validate requests	`npx @stoplight/prism mock contract.yaml`
Dredd	HTTP contract testing from OpenAPI	Validate live API against OpenAPI	`npx dredd contract.yaml http://localhost:3000`
OpenAPI Validator	Validate requests/responses	Custom middleware; runtime validation	`npm install openapi-validator-middleware`

Contract Testing Comparison

Tool	Style	Best For	SDD Fit
Pact	Consumer-driven	Microservices, many consumers	When consumers own contract
Specmatic	Contract-first	REST, OpenAPI-centric	Strong — spec→contract→code
Prism	Mock + validate	Design phase, frontend dev	Mock before implementation
Dredd	Probe live API	Validate implementation	Post-implementation validation

SDD Contract Workflow

plan.md defines contracts/api.yaml (OpenAPI)
Prism mocks API for frontend/parallel work
Dredd or Specmatic validates implementation against contract
Contract tests run in CI before merge

# Prism mock
npx @stoplight/prism mock specs/004-chat/contracts/api.yaml

# Dredd validate
npx dredd specs/004-chat/contracts/api.yaml http://localhost:3000

API Specification Updates (2026)

OpenAPI 3.2: recommended baseline for REST contracts.
Arazzo: document and execute multi-step API workflows.
Overlay: apply environment/team-specific patches to base API specs.
AsyncAPI 3.1: keep event-driven contracts aligned with the same spec-first discipline.

7. CI/CD

Tool	What It Does	When to Use in SDD	Getting Started
GitHub Actions	Workflow automation	Spec validation, contract tests, deploy	Create `.github/workflows/sdd.yml`
GitLab CI	Pipeline automation	Alternative to GitHub Actions	Create `.gitlab-ci.yml`
Jenkins	Self-hosted pipelines	Enterprise; custom SDD stages	`jenkinsfile` with spec stage
CircleCI	Cloud CI/CD	Alternative to GitHub Actions	Create `.circleci/config.yml`

Spec Validation Pipeline (GitHub Actions)

# .github/workflows/sdd-validate.yml
name: SDD Validate
on: [push, pull_request]
jobs:
  spec-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check spec completeness
        run: |
          # Ensure no [NEEDS CLARIFICATION] in specs/
          ! grep -r "NEEDS CLARIFICATION" specs/ || exit 1
      - name: Vale lint specs
        run: |
          npm install -g vale
          vale specs/
  contract-test:
    runs-on: ubuntu-latest
    needs: spec-check
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run build
      - run: npm run test:contract

GitLab CI Spec Validation

# .gitlab-ci.yml
stages:
  - validate
  - test

validate:spec:
  stage: validate
  script:
    - ! grep -r "NEEDS CLARIFICATION" specs/ || exit 1
    - vale specs/

test:contract:
  stage: test
  script:
    - npm run test:contract

8. Observability

Tool	What It Does	When to Use in SDD	Getting Started
OpenTelemetry	Vendor-neutral tracing, metrics, logs	Instrument generated code; spec-driven metrics	`npm install @opentelemetry/api`
Grafana	Dashboards, alerting	Visualize spec-defined metrics	`docker run -d grafana/grafana`
Prometheus	Metrics collection, alerting	Scrape spec-defined metrics	`docker run -d prom/prometheus`
DataDog	APM, logs, metrics	Managed observability; SDD dashboards	`npm install dd-trace`
Jaeger	Distributed tracing	Trace spec-defined spans	`docker run -d jaegertracing/all-in-one`
Loki	Log aggregation	Query spec-defined log fields	`docker run -d grafana/loki`

SDD-Specific Observability Configuration

Spec Section	OTel Instrumentation	Grafana Panel
Observability Requirements	Metrics from telemetry.md	Dashboard from telemetry.md
Logs	Structured logger with trace_id	Log explorer
Alerts	Alertmanager rules	Alert thresholds
Metrics	Counter, Histogram, Gauge	Panels per metric

One-Line Commands

# OpenTelemetry Node
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

# Grafana (Docker)
docker run -d -p 3000:3000 grafana/grafana

# Prometheus
docker run -d -p 9090:9090 prom/prometheus

9. Security Scanning

Tool	What It Does	When to Use in SDD	Getting Started
Snyk	Dependency + code vulnerability scanning	Scan AI-generated dependencies; enforce SEC-*	`snyk test`
Semgrep	Static analysis with custom rules	Enforce security constraints; catch AI mistakes	`semgrep scan --config auto`
Trivy	Container + dependency scanning	Scan Docker images from generated Dockerfiles	`trivy image [image]`
SonarQube	Code quality, security, duplication	Broader quality gate for generated code	`sonar-scanner`
npm audit	Node dependency vulnerabilities	Quick check for JS projects	`npm audit`

AI-Generated Code Review Focus

Constraint	Tool	Rule/Check
No hardcoded secrets	Semgrep	Detect API keys, passwords
Parameterized queries	Semgrep	SQL injection patterns
Auth on endpoints	Semgrep	Route without auth middleware
Dependency vulns	Snyk, npm audit	CVE in deps
Container vulns	Trivy	Base image CVEs

One-Line Commands

# Snyk
npx snyk test

# Semgrep
pip install semgrep && semgrep scan --config auto .

# Trivy
docker run aquasec/trivy image [your-image]

10. Documentation

Tool	What It Does	When to Use in SDD	Getting Started
Docusaurus	React-based doc site	Publish specs as docs; versioned	`npx create-docusaurus@latest`
MkDocs	Python-based doc site	Lightweight; Markdown-native	`pip install mkdocs`
VitePress	Vite-powered static docs	Fast; Vue-based	`npm create vitepress@latest`
GitBook	Hosted documentation	Quick publish; collaboration	gitbook.com
Read the Docs	Hosted MkDocs	Free hosting for open source	readthedocs.org

Publishing Specifications

Approach	Tool	Use Case
Specs as docs	Docusaurus, MkDocs	Internal/external spec portal
Versioned specs	Docusaurus versioning	Spec history per release
Search	Algolia DocSearch	Find specs by keyword
API docs	OpenAPI → Redoc/Swagger	contracts/ as API docs

MkDocs for Specs

# mkdocs.yml
site_name: Project Specs
nav:
  - Home: index.md
  - Specs:
    - Feature 001: specs/001-password-reset/spec.md
    - Feature 002: specs/002-invitations/spec.md
  - Plans:
    - Feature 001: specs/001-password-reset/plan.md

pip install mkdocs mkdocs-material
mkdocs serve

Complete Tool Stack Summary Table

Layer	Category	Tools	Notes
1	Specification Authoring	VS Code/Cursor, Vale, markdownlint, Nunjucks, Mermaid	Vale for prose; Mermaid for diagrams
2	AI Coding Agents	Cursor, Claude Code, Windsurf, Copilot	Cursor primary for SDD
3	Agent Configuration	SKILL.md, AGENTS.md, .cursor/rules, .cursorrules	Hierarchy: AGENTS → rules → RULE
4	Version Control	Git, GitHub, GitLab	Branch per feature; spec-first PRs
5	Testing	Vitest, Playwright, Pytest, Cucumber, fast-check, Hypothesis	Map to spec: AC, edge cases, NFRs
6	Contract Testing	Pact, Specmatic, Prism, Dredd	Specmatic for contract-first SDD
7	CI/CD	GitHub Actions, GitLab CI	Spec validation + contract tests
8	Observability	OpenTelemetry, Grafana, Prometheus, DataDog	telemetry.md → instrumentation
9	Security Scanning	Snyk, Semgrep, Trivy	AI-generated code review
10	Documentation	Docusaurus, MkDocs, VitePress	Publish specs as living docs

Quick Reference: One-Line Commands by Layer

Layer	Command
1	`vale specs/`
2	`cursor .`
3	(Create files manually)
4	`git checkout -b 004-feature-name`
5	`npx vitest run` \| `npx playwright test` \| `pytest tests/`
6	`npx dredd contract.yaml http://localhost:3000`
7	`gh workflow run sdd-validate`
8	`docker run -d -p 3000:3000 grafana/grafana`
9	`npx snyk test` \| `semgrep scan --config auto .`
10	`mkdocs serve` \| `npm run docs:dev`

Tool Selection Decision Tree

Need to write specs?           → Cursor + Vale + Mermaid
Need AI to implement?           → Cursor (primary) or Claude Code
Need to constrain AI?           → SKILL.md + .cursor/rules + constitution
Need spec versioning?           → Git + branch per feature
Need to validate implementation? → Contract tests (Dredd/Specmatic) + Integration (Vitest)
Need to validate NFRs?          → k6/Artillery + Grafana
Need to scan AI code?           → Semgrep + Snyk
Need to publish specs?          → MkDocs or Docusaurus

SDD Pipeline Integration Examples

Example 1: Full SDD Pipeline with GitHub Actions

name: SDD Full Pipeline
on:
  push:
    branches: [main, '*-*']
  pull_request:
    branches: [main]
jobs:
  validate-specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for unresolved clarifications
        run: |
          if grep -r "NEEDS CLARIFICATION" specs/ 2>/dev/null; then
            echo "Unresolved [NEEDS CLARIFICATION] found"
            exit 1
          fi
      - name: Vale lint
        uses: errata-ai/vale-action@v2
        with:
          files: specs/
  contract-tests:
    runs-on: ubuntu-latest
    needs: validate-specs
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - run: npm run test:contract
  integration-tests:
    runs-on: ubuntu-latest
    needs: contract-tests
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run test:integration

Example 2: Spec-to-Deploy with Observability

For production SDD deployments, ensure telemetry from telemetry.md is instrumented:

Build: Compile with OpenTelemetry auto-instrumentation
Deploy: Container includes OTel collector config
Verify: Grafana dashboard from spec matches deployed metrics
Alert: Alertmanager rules from spec thresholds

Example 3: Multi-Agent SDD Workflow

Agent	Config	Responsibility
Spec Agent	`AGENTS.md` role	Expands user prompt → spec.md
Plan Agent	`.cursor/rules/plan.mdc`	spec.md → plan.md, contracts
Task Agent	`.cursor/rules/tasks.mdc`	plan.md → tasks.md
Impl Agent	`.cursor/rules/impl.mdc`	tasks.md → code

Each agent loads constitution + domain constraints. Handoff via files in specs/[branch]/.

Tool Version Compatibility (2026)

Tool / Standard	Recommended Version	Notes
Node.js	20 LTS or newer LTS	For Vitest, Playwright, and most JS tooling
Python	3.11+	For Pytest, Hypothesis, MkDocs
Vale	3.x	Prose linting
OpenTelemetry	1.x	Stable telemetry API
Playwright	1.40+	E2E testing
Docusaurus	3.x	Doc publishing
OpenAPI	3.2	REST contract baseline
AsyncAPI	3.1	Event-driven contracts
MCP	2025-06-18 spec line or newer	Tool/context interoperability for agents
SLSA	1.1	Supply-chain assurance guidance for CI/CD
SBOM	SPDX 3.0 or CycloneDX 1.6	Dependency and artifact traceability

Previous: Appendix A - Specification Templates | Next: Appendix C - 2026 Updates for Spec-Driven Development

Layer Overview​

1. Specification Authoring​

Spec Linter Configuration (Vale)​

2. AI Coding Agents​

AI Coding Agents Comparison​

3. Agent Configuration​

Configuration Hierarchy​

SKILL.md Template Snippet​

4. Version Control​

Git Workflow for Spec-Driven Development​

Branch Naming Convention​

PR Template (GitHub)​

5. Testing​

Test Tool Use Case Mapping​

One-Line Commands​

6. Contract Testing​

Contract Testing Comparison​

SDD Contract Workflow​

API Specification Updates (2026)​

7. CI/CD​

Spec Validation Pipeline (GitHub Actions)​

GitLab CI Spec Validation​

8. Observability​

SDD-Specific Observability Configuration​

One-Line Commands​

9. Security Scanning​

AI-Generated Code Review Focus​

One-Line Commands​

10. Documentation​

Publishing Specifications​

MkDocs for Specs​

Complete Tool Stack Summary Table​

Quick Reference: One-Line Commands by Layer​

Tool Selection Decision Tree​

SDD Pipeline Integration Examples​

Example 1: Full SDD Pipeline with GitHub Actions​

Example 2: Spec-to-Deploy with Observability​

Example 3: Multi-Agent SDD Workflow​

Tool Version Compatibility (2026)​

Layer Overview

1. Specification Authoring

Spec Linter Configuration (Vale)

2. AI Coding Agents

AI Coding Agents Comparison

3. Agent Configuration

Configuration Hierarchy

SKILL.md Template Snippet

4. Version Control

Git Workflow for Spec-Driven Development

Branch Naming Convention

PR Template (GitHub)

5. Testing

Test Tool Use Case Mapping

One-Line Commands

6. Contract Testing

Contract Testing Comparison

SDD Contract Workflow

API Specification Updates (2026)

7. CI/CD

Spec Validation Pipeline (GitHub Actions)

GitLab CI Spec Validation

8. Observability

SDD-Specific Observability Configuration

One-Line Commands

9. Security Scanning

AI-Generated Code Review Focus

One-Line Commands

10. Documentation

Publishing Specifications

MkDocs for Specs

Complete Tool Stack Summary Table

Quick Reference: One-Line Commands by Layer

Tool Selection Decision Tree

SDD Pipeline Integration Examples

Example 1: Full SDD Pipeline with GitHub Actions

Example 2: Spec-to-Deploy with Observability

Example 3: Multi-Agent SDD Workflow

Tool Version Compatibility (2026)