Introduction
Subak checks the code your AI tools generate against what you meant to build, then hands you a signed record of what holds. AI writes the code; Subak tells you, in plain terms, whether it does what you asked, catches the bugs and broken logic AI tends to leave behind, and shows you what's ready before you ship.
Under the hood, Subak is a spec-driven development framework. You capture a project's intent as a graph of small, schema-validated documents called artifacts, and subak validate then mechanically and semantically proves that those artifacts are mutually coherent and that the code conforms to them. Instead of one giant prompt and a wall of generated code you have to trust on vibes, you get a dependency graph of deliverables where every node has a contract and every edge has a validator.
A declarative, provider-agnostic, schema-driven framework for defining, validating, executing, and redelivering project deliverables in a workflow DAG.
The problem it solves
AI coding tools are great at getting you started and fall short before they follow through. The first 80% (scaffolding, a working demo, a plausible-looking feature) is easy. The hard part, the part LLMs reliably drop, is keeping the whole project coherent as it evolves. Unstructured output accrues architectural debt and turns into vibe-coded spaghetti that doesn't scale, and re-prompting the entire codebase on every change burns tokens rebuilding the world.
Subak attacks this from a different angle. Because intent lives in a structured graph rather than in prose and generated source, Subak always knows the blast radius of a change: edit one artifact, and it can tell you exactly which downstream artifacts and which slices of code are now in question, and re-validate only those.
Subak is additive, not substitutive. You keep your existing setup — Cursor, Claude Code, Copilot — and add Subak on top. It doesn't proxy your LLM or host your IDE; it gives the tools you already use a checkable definition of "correct." See Integrations.
The core pieces at a glance
Artifacts
Artifacts are the structured documents that capture every project deliverable — a persona, a requirement, a bounded context, a feature, a flow. They're pure data validated against a JSON Schema: no logic, just the contract for each kind of deliverable. They start from a single human-authored idea seed and fan out from there. Read Artifacts & the DAG for the full type catalog.
The workflow DAG (metagraph)
The artifact types, the dependency edges between them, and the validation rules over those edges are declared together in a metagraph — a declarative graph embedded in the CLI. The dependency edges encode generation order (you author intent top-down, each level a function of the levels above it), and the validation rules are coherence constraints that guard each edge. One workflow describes one domain; the software workflow currently defines dozens of artifact types across five sections — Discovery, Requirements, Architecture, Interface, and Features. See The Workflow.
subak validate and the proof certificate
Running subak validate checks that every artifact passes schema validation, that every cross-reference resolves, and that the artifact set is coherent per the embedded rules. Crucially, it doesn't just return a pass/fail — it emits a proof certificate (subak.proof.json) that records why the verdict holds: which inputs were examined, which rules applied, and what kind of evidence each conclusion rests on. That certificate is the thing that makes a verdict trustworthy rather than opaque. See Validation.
Who it's for
Subak is for people building real things with AI — founders shipping a vibe-coded app, freelancers delivering client work, and teams putting a quality gate on every project. If you can describe what you want but can't read every line the AI wrote, Subak is the check that tells you whether it's safe to ship. It's especially valuable if you run AI agents for long stretches: the proof certificate gives an agent an external, machine-checkable answer key to anchor against, so it can run longer and more confidently without a human watching every step. That argument is the subject of Why Subak.
Next steps
- Why Subak — the motivation: why epistemic validation unlocks longer, more confident unsupervised agentic coding.
- Getting Started — install Subak, sign in, authenticate the CLI, and create your first project.
- Concepts — the mechanism in depth: artifacts and the DAG, validation, and the workflow.