SpecGate

Deterministic spec-based verification for LLM-implemented code.

Engineers write specs. LLMs implement them. SpecGate closes the gap by providing a non-stochastic harness that validates implementations against specs using runtime traces.

Crates

Crate	Description
specgate	Umbrella crate — annotations + harness in one dependency
specgate-cli	CLI: specgate validate and specgate run
specgate-harness	Test harness: codegen, trace collection, matching
specgate-annotations	Annotation facade
specgate-annotations-macros	Proc macros
specgate-runtime	Runtime trace buffer
specgate-types	Spec/binding parsing

How It Works

Spec YAML  +  Annotated Source  →  Harness  →  Pass / Fail per case

1. Write a spec (.spec.yaml) declaring operations, types, and expected behavior
2. Annotate source with #[spec_operation], #[derive(SpecEvent)], spec_trace!
3. The harness generates a runner, compiles it, collects traces, and compares

See the specgate crate docs for usage, and the CLI docs for command-line usage.

Design Principles

1. Spec is the single source of truth
2. Conformance checking is deterministic — no LLM in the verification loop
3. Traces are the evidence — generated tests have zero domain knowledge
4. Zero-cost in production — annotations are no-ops without the trace feature

Documentation

• docs/knowledge/ — reference docs for spec format, annotations, bindings, etc.
• CHANGELOG.md — release history

Implementation Skill (for AI agents)

.github/skills/implement-spec.md is a structured workflow that AI coding agents follow when implementing from a spec. It defines:

• How to read a spec — what each field means, how types map to code
• The TDD workflow — annotate first, write harness bootstrap test, then implement
• Validation gates — specgate validate before implementing, specgate run after
• Trust boundary — agents must never read harness-generated artifacts as implementation input
• Checklist — what must be true before an implementation is considered done

Point any agent at this file when asking it to "implement a spec" or "build from spec". The knowledge base in docs/knowledge/ provides topic-specific reference (spec format, annotation syntax, binding files, Rust/C# conventions, etc.).

Contributing

See CONTRIBUTING.md.

License

MIT OR Apache-2.0