Executable specs from your source.

The problem

Specifications live out of sync with code. A feature launches, the spec sits unchanged in a wiki, and the gap grows. Testing follows manual scripts. When behavior changes, nobody updates the spec — it becomes noise.

Yet specifications are essential: they encode business rules, encode intent, and let agents reason about what a system should do. The friction is synchronization.

What SpecBook does

SpecBook takes any repository revision and makes it the source of truth for specifications. Upload a GitHub repo URL or a commit SHA. SpecBook indexes the codebase into an immutable snapshot: vector embeddings of every function and test, a GraphRAG knowledge graph connecting concepts, and an ontology of business entities and behaviors. Agents then reason over that snapshot to discover and document business behavior: what the code does, what it should do, and where gaps exist.

The engine compiles those discoveries into Gherkin feature files (human-readable scenarios in Given/When/Then form) and generates Playwright test bundles — validated, runnable, with assertions that match the spec. Every test is tied to the source revision, creating an audit trail of what behavior was correct at what point in time.

What makes it different

• Source-backed immutability. Specs aren't written by hand then left to drift. They're derived from code, pinned to a specific revision, and regenerated when the code changes. The spec is always current with reality or obviously out of sync.
• Behavior discovery via GraphRAG. Agents don't just read code; they build a knowledge graph of how entities relate, how data flows, and what invariants hold. From that graph, they discover implicit business rules the code enforces but the team hasn't formalized.
• Policy-bound agent execution. SpecBook uses a deny-by-default policy engine (inspired by Warden). Agents run sandboxed: they can read the codebase, write specs and tests, but cannot access production credentials or make external calls. Policies are versioned with the spec snapshot.
• Validated test generation. Generated Playwright tests are not guesses. They're traced against the snapshot's behavior to confirm they exercise the specified paths. Invalid tests are rejected before they ship.

Deploy

SpecBook runs entirely on Cloudflare. Clone and deploy to your own account:

git clone https://github.com/ruizrica/specbook
cd specbook
wrangler deploy

Configure your environment with a GitHub OAuth app (for repo access), your Claude API key, and optional Langfuse credentials for observability. Everything else — Workers, D1 database, Vectorize index, R2 storage for artifacts, and isolated container execution — lives in your Cloudflare account. No third-party SaaS. You control the data, you control the cost.

SpecBook is co-authored by Ricardo Ruiz and Peretz Hildeshaim.