spec-linter

Validates specs have required frontmatter, links, and compliance. Use before commits or during code review.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The Spec Linter skill is a specialized quality assurance tool designed to automate the validation of technical specifications and documentation. It ensures that all project specs adhere to strict standards, including frontmatter completeness, test-to-spec traceability, and Architectural Decision Record (ADR) compliance. By integrating into pre-commit hooks and CI/CD pipelines, it helps engineering teams maintain high documentation standards and ensures that every code change is backed by proper requirements and testing links.

Use Cases

  • Pre-commit Compliance Checks: Automatically verify that all required frontmatter fields and PR template sections are completed before a developer commits code, reducing manual review overhead.
  • Architectural Change Validation: Enforce the creation of ADRs (Architectural Decision Records) whenever key components or frameworks are modified, ensuring long-term maintainability.
  • Test-to-Spec Traceability: Scan Swift test files to ensure every test method is mapped to a specific requirement ID (TC-XXX), facilitating easier auditing and coverage analysis.
  • CI/CD Quality Gate: Use as a blocking step in GitHub Workflows to prevent merging pull requests that do not meet the defined acceptance criteria or documentation standards.
name"Spec Linter"
description"Validates specs have required frontmatter, links, and compliance. Use before commits or during code review."

Spec Linter Skill

Purpose

Validate:

  • Frontmatter completeness
  • Test-to-spec traceability
  • ADR requirements for architectural changes
  • PR template compliance

Validation Rules

  1. Frontmatter required fields by type
  2. Test IDs (TC-XXX) present near Swift test methods
  3. ADR required when key components/frameworks change
  4. Acceptance criteria present for new features
  5. PR template sections completed

Usage

  • Pre-commit: python3 scripts/lint-specs.py
  • CI: see .github/workflows/spec-lint.yml