Inspiration
What it does
How we built it
Challenges we ran into
Accomplishments that we're proud of
What we learned
What's next for SpecGuard Crew
Inspiration
AI agents write code that looks right and still breaks on edge cases. "All tests passed" only means the examples we happened to think of passed. SpecGuard Crew is our answer: a skeleton where correctness is a mathematical property, not a hope.
What it does
SpecGuard Crew is a reusable foundation — not an app. Its core is a pure functional state machine wrapped in an invariant engine: every transition is checked against registered predicates before the state is committed, so a violating mutation is rejected and the previous state is preserved. A property-based testing bridge (fast-check) then fuzzes those same invariants with generated inputs, 1,000 runs at a time, and reports the exact counterexample when one fails.
To prove the skeleton is genuinely reusable, it powers two applications in unrelated domains:
- Necromancer Vault — Shamir (k, n) threshold secret sharing over Galois Field GF(256). Any k of n horcrux shares reconstruct the secret byte-for-byte; any k-1 shares leak nothing. The engine blocks sub-threshold reconstruction, and the PBT suite verifies the round trip across randomized secrets and thresholds.
- Potions Exchange — a price-time priority limit order book for Halloween ingredients. Matching conserves total gold and inventory, and the book can never stay crossed. Randomized order floods are verified against both invariants with zero leaks.
Both run in one dashboard with a live Invariant Radar HUD streaming check results, latency, and PBT stress passes.
How we built it
TypeScript on Bun, fast-check for generative testing, dependency-free Web Components for the UI, GitHub Actions for static deployment to GitHub Pages. The repository is Kiro-native: .kiro/steering encodes architecture rules (product, tech, structure) with inclusion: always; .kiro/specs holds three EARS specification sets in requirements/design/tasks form; .kiro/hooks binds save triggers for type-checking and PBT regression; .kiro/agents defines an InvariantAuditor reviewer; .kiro/settings/mcp.json exposes the fuzzing engine over MCP.
Challenges we ran into
Implementing GF(256) with polynomial 0x11b silently produces an element of multiplicative order 51 instead of 255, which corrupts Lagrange interpolation while still "looking" correct. An early property test caught the counterexample; the spec's stated invariant rejected the choice, and the implementation moved to primitive polynomial 0x11d with a regression test guarding it.
Accomplishments we're proud of
Two orthogonal applications sharing one invariant kernel, with sub-millisecond invariant checks and 1,000-check PBT passes completing in about 6 ms in the browser.
What we learned
Specifications are only useful when they are executable. Encoding invariants first, then letting tests attack them, found a class of bugs unit tests never would.
What's next
Packaging the kernel as a standalone npm package, adding SMT-based requirement contradiction checks, and extending the MCP surface so other agents can request verification mid-reasoning.
Built With
- bun
- fast-check
- invariant-testing
- kiro
- property-based-testing
- typescript
- web-components
