The contract layer
Specs as
CI-enforced contracts.
Markdown *.spec.md files are the
contract. spec-sync checks that the code matches the spec, in
both directions, and fails CI when
they drift. 33 languages, one format, a single Rust binary.
$ cargo install specsync
# Verify
$ specsync --version
specsync 6.2.0
# Validate specs against code
$ specsync check
✓ greeter (v1, draft): 7/7 sections
1 spec checked, 0 errors, 0 warnings
The idea
A README rots the day it is written. spec-sync treats every
*.spec.md as a contract and
diffs it against the source, both ways. Code with no spec entry is a warning;
a spec entry with no code is an error. Neither side can quietly fall behind,
because the diff runs in CI on every pull request.
Auto-detected from file extensions. The same markdown contract covers Rust, TypeScript, Go, Python, Swift, and 28 more. Twelve are profiled in detail below.
Code that drifts from the spec, and a spec that drifts from the code. Severity is calibrated so each gets the right signal.
Purpose through Change Log. A spec missing any of them is an error, so contracts stay complete by construction.
Three powers
From discovery to enforcement. Each power is a focused subcommand you wire into any CI. Drift is the gap between what your specs say and what your code actually does.
Step 1
Detect drift
Find the gap between what your specs say and what your code does: undocumented exports, stale entries, broken cross-references. 33 languages, auto-detected from file extensions.
Step 2
Plan and prove
When you opt into SDD: a deterministic interview, one scope approval, bind verification with change check --commit, then review and ship. Check itself does not require an active change.
Step 3
Prevent drift
Make drift impossible to merge: a strict gate on every PR via the GitHub Action. Drift becomes a build failure, not a review nag.
The spec format
A spec is markdown with YAML frontmatter. The frontmatter declares the module, its source files, and any dependencies; the body has seven required sections. spec-sync extracts the first backtick-quoted name in each Public API row and matches it to a code export.
auth.spec.md
module: auth
version: 3
status: stable
files:
- src/auth/service.ts
- src/auth/middleware.ts
db_tables:
- users
- sessions
depends_on:
- specs/database/database.spec.md
- corvid-labs/algochat@messaging
---
## Public API
| Function | Returns |
| `authenticate` | `User | null` |
Seven required sections
- Purpose. What the module does, in one paragraph.
- Public API. Every exported function, type, and class. Each row's backticked name is matched to a code export.
- Invariants. Properties that must always hold.
- Behavioral Examples. Inputs paired with their expected outputs.
- Error Cases. What can go wrong and how it surfaces.
- Dependencies. Other modules and external services.
- Change Log. Append-only history, one entry per version.
Key concepts
The vocabulary; everything else composes from these.
- spec
- A
*.spec.mdmarkdown file with YAML frontmatter. It is the contract for one module. - module
- A named unit declared by
module:in frontmatter, covering one or more sourcefiles:. - drift
- The gap between what a spec documents and what the code actually exports.
- coverage
- The share of source files claimed by a spec.
require-coverage: '100'gates on it. - cross-project ref
owner/repo@moduleindepends_on:, resolved withspecsync resolve --remote.- change
- An optional slug-id workspace with scope, approvals, semantic deltas, tasks, and verification evidence. Check is the product; SDD is opt-in.
Twelve profiled languages
Same contract, every stack. The extractor covers 33 languages; these twelve are the profiled set. spec-sync detects the language from the file extension and parses exactly the symbols that count as public, skipping test files automatically. The language reference has the per-language detail.
| Language | Exports detected |
|---|---|
| TypeScript / JS | export function / class / type / const / enum, re-exports, export * wildcard resolution |
| Rust | pub fn / struct / enum / trait / type / const / static / mod |
| Go | Uppercase func / type / var / const, methods |
| Python | __all__, or top-level def / class with no _ prefix |
| Swift | public / open func / class / struct / enum / protocol / actor |
| Kotlin | Top-level declarations, excludes private / internal |
| Java | public class / interface / enum / record / methods |
| C# | public class / struct / interface / enum / record / delegate |
| Dart | Top-level with no _ prefix: class / mixin / enum / typedef |
| PHP | class / interface / trait / enum, public function / const |
| Ruby | class / module, public methods, attr_accessor / reader / writer, constants |
| YAML | Top-level mapping keys, anchors and aliases supported |
Calibrated severities
What counts as drift. Errors fail CI; warnings annotate. The split is deliberate: a spec that promises code that does not exist is a broken contract (error), while code that has outrun its docs is a nudge (warning). Schema-aware validation tracks DB tables and columns across migrations the same way.
| 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 |
Make drift unmergeable
A gate in CI. The CorvidLabs/[email protected]
Action auto-detects OS and arch, downloads the binary, and runs the check on
every push and PR. When drift is real, deterministic scaffolding and native agent skills guide the repair.
.github/workflows/spec.yml
jobs:
specsync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: CorvidLabs/[email protected]
with:
version: '6.2.0'
strict: 'true'
require-coverage: '100'
comment: 'true'
Action inputs
| Input | Default |
|---|---|
version | 6.2.0 Release version of the binary to download. Pin it; do not omit. |
strict | false Treat warnings as errors, so undocumented exports also fail CI. |
require-coverage | 0 Minimum file coverage percent the run must meet. |
root | . Project root directory to validate. |
comment | false Post the drift summary as a PR comment (needs a pull_request event). |
args | '' Extra whitespace-separated CLI arguments; shell quoting is not supported. |
The VS Code extension (source only)
- Inline diagnostics. Errors and warnings map to the spec file, on save, with a 500ms debounce.
- CodeLens scores. A 0 to 100 quality score is shown inline above each spec file.
- Coverage webview. A rich panel with per-file and per-line coverage.
- Status bar. A persistent pass, fail, or error indicator for the workspace.
The extension lives in the repository's vscode-extension/ ↗ folder. It is not published on the VS Code Marketplace yet.
Agent-native, deterministic core
$ specsync generate
# Install native agent workflows
$ specsync agents install
# Start a verified delivery change
$ specsync change new "Add passkeys"
SpecSync never accepts model credentials, sends source to a provider, or executes an AI command. Claude, Cursor, Codex, and Gemini integrations enrich the deterministic artifacts inside each agent's own permission boundary.
Where it ships
- Language
- Rust, single static binary
- Crate
- specsync on crates.io
- Action
- CorvidLabs/[email protected] (GitHub Marketplace)
- Editor
- VS Code extension, as source in the repository (not on the Marketplace)
- Platforms
- macOS and Linux; Windows through WSL 2 (no Windows binary from 6.0)
- SDD lifecycle
- draft → approved → implementing → verifying → review → ship (opt-in)
- Latest
- v6.2.0
- License
- MIT
- Languages
- 33 auto-detected, 12 profiled
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 23 specs across proto, crypto, server, federation, invites, admin, interactions, and merlin-bridge
- → Merlin spec-sync is the agent contract; drift equals a failed task
- → fledge ↗ the spec-check lane runs specsync check
v6.2.0 is live
v6.2.0 shipped Nov 5, 2026.
The 5-minute quickstart
is a real walkthrough: a fresh crate to a green check in five copy-paste steps.