Spec Sync

SpecSync

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

Install · Quick start · Verified change workflow · Live documentation · Examples · Comparisons

Install

The GitHub 6.1.1 release uses the immutable candidate qualified on Ubuntu and macOS. This separate Action wrapper update selects its published binary by default. Confirm availability at your chosen distribution before using the 6.1.1 installation pins below; GitHub asset publication does not itself establish crates.io or Homebrew publication. Confirm what you received with specsync --version, and pin all lifecycle writers and CI to the same 6.x version.

Cargo

cargo install specsync

Homebrew

brew install CorvidLabs/tap/spec-sync

GitHub Action

- uses: CorvidLabs/[email protected]
  with:
    version: '6.1.1'
    strict: 'true'
    require-coverage: '100'

Prefer the @v6.1.1 Action and binary pins shown above for release gates. @v6.0.0 still defaults the download to 6.0.0-rc.14, so pass version: '6.0.0' only when using that older tag. This main wrapper's omitted-input default is published 6.1.1, following supported-platform asset and Action checks. The immutable @v6.1.1 tag still embeds default 6.1.0: explicitly pass version: '6.1.1' with that tag for its new binary. Floating @v6 advances to this wrapper commit only after its actual consumer checks pass; the immutable @v6.1.1 ref is never moved here.

Minimal immutable configuration:

- uses: CorvidLabs/[email protected]
  with:
    version: '6.1.1'

Pre-built binaries

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.

A contract change in 60 seconds

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 errors

The 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.

Read the adversarial proof

What SpecSync catches

SpecSync validates Markdown module specs (*.spec.md) against source code in both directions.

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.

Verified change workflow

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 merge

The 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.

Quick start

# 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 install

For an existing 4.x project, use the guided migration and adoption flow described in the configuration and workflow guides.

Specs and companion files

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

Read the complete spec format, companion-file reference, and workflow conventions.

Architecture

One local binary does the work. Editors, the GitHub Action, MCP clients and agent skills all run the same CLI. check is the drift check. change is the opt-in lifecycle that leaves its evidence in Git.

flowchart LR
    users([Developers, coding agents,<br/>VS Code, MCP clients, CI]) --> cli[[specsync]]
    cli --> check[check<br/>spec vs code drift]
    cli --> change[change<br/>new, approve, check,<br/>review, finalize]
    check --> repo[(specs/ + source)]
    change -->|scoped sync| check
    change --> evidence[(.specsync/changes/<br/>then archive/)]

The high-level design covers the components, the change state machine, sequence diagrams for the key commands, the evidence files and digests, and CI, Trust and release.

Documentation

Executable examples

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

How it compares

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

Supported languages

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.

Contributing

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.

License

MIT — see LICENSE.