Turn requirements into module contracts that fail CI when code drifts—without losing the decisions and evidence around the fix.
Rust · single binary · 33 languages · no SpecSync API key required
Quick start · Verified change workflow · Live documentation · Examples · Comparisons
Start with product intent in specs/auth/requirements.md:
### REQ-auth-004
The system SHALL let a signed-in user revoke every active session.Refine it into the durable module contract in specs/auth/auth.spec.md:
| Name | Kind | Description |
|---|---|---|
| `revoke_all_sessions` | function | Revokes every session owned by the current user. |Now a developer adds a second public export without updating the contract:
pub fn revoke_all_sessions(user_id: UserId) -> Result<usize, SessionError> { /* ... */ }
pub fn revoke_session(session_id: SessionId) -> Result<(), SessionError> { /* new */ }The same check runs locally and in CI:
$ specsync check --strict
specs/auth/auth.spec.md
✓ Frontmatter valid
✓ All source files exist
✓ All required sections present
⚠ 1/2 exports documented
⚠ Undocumented export 'revoke_session' from src/auth.rs
✓ All dependency specs exist
1 specs checked: 1 passed, 2 warning(s), 0 failed
File coverage: 1/1 (100%)
LOC coverage: 2/2 (100%)
--strict mode: 2 warning(s) treated as errorsThe fix preserves more than a generated document:
requirements.md why the behavior exists and how success is judged
auth.spec.md the module/API contract checked against code
context.md decisions, constraints, and files the next agent needs
testing.md requirement-to-test evidence
<change-id>/ approved deltas, verification, and the delivery audit trail
Add the missing contract row—or make the export private—then rerun the check. CI turns green while the requirement, context, evidence, and exact contract change remain reviewable in Git.
SpecSync validates Markdown module specs (*.spec.md) against source code in both directions.
| Drift | Result |
|---|---|
| Code exports something absent from its spec | Warning; fails in strict mode |
| A spec documents an export missing from code | Error |
| A referenced source file was deleted | Error |
| A required spec section is missing | Error |
| A declared dependency does not exist | Error |
| A source import is undeclared | Strict dependency error |
| A documented database table or column is missing | Error |
| A schema column is undocumented or has a type mismatch | Warning |
It also provides a verified spec-driven development lifecycle, coverage gates, quality scoring, dependency analysis, cross-project references, Git hooks, editor integration, and agent-native workflows.
SpecSync's core is deterministic and local. It does not require a hosted SpecSync service, Corvid AI account, provider key, or embedded model. Claude, Cursor, Codex, Gemini, and other coding agents use the same CLI and lifecycle through their own permissions.
A successful structural check does not prove arbitrary natural-language behavior or execute product tests. Reviewers and product tests establish those behaviors; keep those checks in CI.
SpecSync 6.0 keeps one change package and one user-facing path from scope to merge:
specsync change new "Add passkeys" --spec auth --path src/auth.rs --json
specsync change answer add-passkeys acceptance_criteria \
"A registered passkey authenticates the user" --json
# answer the remaining interview questions and complete the selected artifacts/deltas
specsync change approve add-passkeys --actor "Ada"
# implement the approved contract and run product tests
specsync change check add-passkeys --commit
# push after local gates; wait for required CI and complete human implementation review
specsync change review add-passkeys --reviewer "Ada"
specsync change finalize add-passkeys
# no commit between review and finalize; commit/push the archive, wait for CI, then mergeThe scope approval binds human-approved content. The reviewer may be that same person.
Actor/reviewer labels and stored provider declarations are claims, not authenticated identity;
configure hosted checks and signed provenance policy separately when authentication is required.
change check materializes approved deltas and records scoped structural verification; it does
not execute project tests. finalize archives the package on the same PR. Merge only after
all active changes on the PR are archived. Use change status for eligible recovery, including
workflow-v2 reopen when accepted or archived evidence becomes stale.
Read the workflow guide or run the complete lifecycle example.
GitHub Releases, crates.io, and Homebrew (CorvidLabs/tap/spec-sync) all serve 6.0.0.
Confirm what you received with specsync --version, and pin all lifecycle writers and CI to
the same 6.x version.
cargo install specsyncbrew install CorvidLabs/tap/spec-sync- uses: CorvidLabs/spec-sync@v6.0.0
with:
version: '6.0.0'
strict: 'true'
require-coverage: '100'Prefer the immutable @v6.0.0 Action and binary pins shown above for release gates. Always
pass version: '6.0.0' with that tag: @v6.0.0 still defaults the download to 6.0.0-rc.14.
The floating @v6 tag is published; its omitted-input default is 6.0.0. YAML examples keep
the immutable pin.
Minimal immutable configuration:
- uses: CorvidLabs/spec-sync@v6.0.0
with:
version: '6.0.0'Download Linux or macOS binaries from GitHub Releases.
Windows is not a supported target as of 6.0 — no Windows binary is published. Run SpecSync
under WSL, or build it from source with cargo install specsync.
# Initialize configuration with the change workflow off
specsync init
# Write a source file first so the scaffold can bind it
mkdir -p src
cat > src/auth.ts <<'EOF'
export function login(): boolean {
return true;
}
EOF
# Scaffold a module contract and companion files
specsync add-spec auth
# Validate. A fresh scaffold still has stub sections, so this is a warning
# pass — fill Purpose, Invariants, examples, and errors before `--strict`.
specsync check
# Measure coverage and spec quality
specsync coverage
specsync score --all
# Install native coding-agent workflows and Git hooks
specsync agents install
specsync hooks installFor an existing 4.x project, use the guided migration and adoption flow described in the configuration and workflow guides.
Each module keeps one executable contract and focused context beside it:
specs/auth/
├── auth.spec.md validated module contract
├── requirements.md stable requirements and acceptance criteria
├── tasks.md active work, roadmap, and test debt
├── context.md architectural decisions and current state
└── testing.md automated, manual, and edge-case evidence
| Artifact | Durable responsibility |
|---|---|
*.spec.md |
Source files, public API, invariants, behavior, errors, dependencies, and change history |
requirements.md |
Stable REQ-* identities, normative SHALL statements, and acceptance criteria |
tasks.md |
Work still to do; requirements are not checkboxes |
context.md |
Decisions, constraints, key files, and handoff state |
testing.md |
Requirement traceability, automated coverage, manual QA, and adversarial cases |
.specsync/changes/<change-id>/ |
Proposed deltas, approvals, verification, and closing evidence |
Read the complete spec format, companion-file reference, and workflow conventions.
The examples create disposable projects and run the real CLI:
- Complete SDD lifecycle
- Five evolving product epics
- Ordered concurrent changes
- CI gate
- Polyglot project
- Rust workspace
SpecSync can stand alone or enforce the implementation layer beneath planning-oriented tools:
- SpecSync vs. Spec Kit
- SpecSync vs. OpenSpec
- Use SpecSync, Spec Kit, and OpenSpec together
- Adversarial detection and knowledge-preservation proof
SpecSync auto-detects source files and public exports across 33 languages:
TypeScript/JavaScript, Rust, Go, Python, Swift, Kotlin, Java, C#, Dart, PHP, Ruby, YAML, C, C++, Scala, Crystal, Nim, Erlang, Elixir, Perl, Common Lisp, Scheme, Emacs Lisp, Haskell, Lua, R, OCaml, Groovy, F#, Clojure, D, Objective-C, Bash, PowerShell, and Vala.
See the detailed language profiles for 12 representative stacks and the extractor source for exact support, export detection, and test exclusions across all 33 families.
Contributions are welcome. Read CONTRIBUTING.md, run the relevant tests, and keep specs synchronized with public behavior.
Security issues should follow SECURITY.md, not a public issue.
MIT — see LICENSE.