spec-linter
Validates specs have required frontmatter, links, and compliance. Use before commits or during code review.
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
- Frontmatter required fields by type
- Test IDs (TC-XXX) present near Swift test methods
- ADR required when key components/frameworks change
- Acceptance criteria present for new features
- PR template sections completed
Usage
- Pre-commit:
python3 scripts/lint-specs.py - CI: see
.github/workflows/spec-lint.yml