A BuildSpec is the single source of truth for a Lucid project. It’s a Zod-validated JSON document describing every page, every section, every image slot, every entity, and every integration. The AI fills it during spec generation. The codegen engine reads it during build.
Why spec-first?
Three reasons, in order of importance. First, it’s free to iterate: you can re-generate a spec ten times before you ever spend a credit. Second, it makes the AI’s job tractable: filling a typed shape is what modern LLMs do well, so we get predictable output. Third, it makes diffs meaningful: “add a pricing section” re-generates exactly one file, not the whole site.
Shape
Top-level: meta, kind ("website" or "webapp"), kit, brand,content, pages, optional entities + auth for webapps, integrations, seo, nav, legal, images, build. The full shape is authored in packages/shared/src/schemas/build-spec.ts.