📐 The contract layer
Specs as
CI-enforced contracts.
Markdown *.spec.md files
are the contract. spec-sync validates the code matches the spec. In both
directions. And fails CI when they drift. 12 languages, one format,
single Rust binary.
Install
- uses: CorvidLabs/spec-sync@v4
with:
strict: 'true'
require-coverage: '100'
# Or as a CLI
$ cargo install specsync
$ specsync check
What's in it
Bidirectional validation
Catches drift both ways. Code exports not in the spec, and spec entries missing from code. Severity is calibrated: phantom entries are errors; undocumented additions are warnings.
12 languages, one format
TypeScript, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, Ruby, YAML. Auto-detected from file extensions. Same *.spec.md markdown contract everywhere.
Cross-project references
Specs can reference specs in sibling repos via specsync.toml. A breaking change in repo A shows up as a CI failure in repo B that depended on it.
CI-enforced
GitHub Action does the diff on every PR. Drift becomes a build failure, not a code-review nag. Bidirectional means neither the spec nor the code can quietly fall behind.
Schema-aware
Tracks DB tables + columns across migrations. Phantom tables, missing columns, and type drift all surface as errors. SQL, MySQL, Postgres dialects supported.
VS Code extension
Inline diagnostics in the editor. Drift shows up as red squiggles before you commit. CLI behavior mirrored exactly so dev + CI agree.
Spec format
Every *.spec.md has seven required sections.
Pair each public API with the code symbol it documents; spec-sync does the matching.
- Purpose
- What the module does in one paragraph
- Public API
- Every exported function / type / class. Paired with code
- Invariants
- Properties that must always hold
- Behavioral Examples
- Inputs + expected outputs
- Error Cases
- What can go wrong + how it surfaces
- Dependencies
- Other modules / external services
- Change Log
- Append-only history per version
What counts as drift
Calibrated severities. Errors fail CI; warnings annotate.
| Drift | Severity |
|---|---|
| Code exports something not in the spec | warning |
| Spec documents something missing from code | error |
| Source file in spec was deleted | error |
| DB table in spec missing from schema | error |
| Column in spec missing from migrations | error |
| Column in schema not documented in spec | warning |
| Column type mismatch (spec vs schema) | warning |
| Required markdown section missing | error |
Where it ships
- Language
- Rust
- Crate
- specsync (on crates.io)
- Action
- CorvidLabs/spec-sync@v4 (GitHub Marketplace)
- Editor
- VS Code extension
- Latest
- v4.3.3 (May 2026)
- License
- MIT
Where it's used
Every CorvidLabs repo with a spec runs specsync check as a CI gate, typically inside fledge's verify lane.
- → corvid-chat 21 specs across proto / crypto / server / federation / invites / admin / interactions / merlin-bridge
- → corvid-agent module specs are the source of truth; agents validate before completing tasks
- → Merlin spec-sync IS the agent contract; drift = failed task
- → fledge spec-check lane plugin
5-minute quickstart
The README has a real walkthrough. Clone the examples crate, run specsync check, watch it pass.