Spec-driven, deterministic code generation for the AI era.
Website · npm · Docs · Changelog · Issues
YAML in. Production code out. Same spec → same code, every time.
npm install -g fixedcode
fixedcode generate my-domain.yaml -o build
fixedcode deploy build /path/to/your/projectNo LLM required. The core engine —
generate,build,verify,deploy,validate,registry— is fully deterministic and works offline with zero AI dependencies. The optionaldraft(spec-from-prose) andenrich(extension-point fill-in) commands use an LLM if you configure one, but you never have to. Hand-write your spec, hand-write your business logic, and the engine still works exactly the same.
LLMs are great at writing code from descriptions, but their output isn't reproducible — ask twice and you get two different answers. FixedCode flips this: the LLM writes the spec, the engine writes the code, and the LLM fills in extension points where the human-readable logic lives. The middle step is deterministic — the same YAML always produces the same output, byte for byte.
The result is what we call the AI sandwich:
- Top slice (AI) — turns natural language into a YAML spec.
- Middle (deterministic) — the FixedCode engine generates the project skeleton, controllers, tests, configs, migrations, etc.
- Bottom slice (AI) — fills in business logic in the extension points that were left blank.
You get the speed of "write me a service that does X" with the auditability of "I can read the spec and the templates." Regenerate at any time without losing your custom logic — extension points are user-owned.
The minimum viable workflow needs no LLM at all:
npm install -g fixedcode
# write your spec by hand (or copy an example), then:
fixedcode generate my-domain.yaml -o build
fixedcode verify my-domain.yaml build
fixedcode deploy build /path/to/your/projectIf you'd rather start from a full multi-spec project (domain + BFF + product app + marketing site, with the image-upload, admin-screen, users-management, pricing-page, and dashboard recipes pre-wired), run:
fixedcode init saas-vertical jobs
cd jobs
# edit .fixedcode.yaml so each bundle points at a local path or installed package
fixedcode build specs/ -o buildThe generated jobs/ directory ships with four ready-to-edit YAML specs and a README that walks through the next steps.
If you'd rather not write specs and extension-point logic by hand, FixedCode can use an LLM. This is opt-in — you only need it for the two AI-flavoured commands:
# draft a spec from a description (LLM required)
fixedcode draft spring-domain "order service with orders and line items" -o my-domain.yaml
# fill in extension-point business logic (LLM required)
fixedcode enrich build/To use these, drop an llm block in .fixedcode.yaml:
llm:
provider: openrouter # openrouter | openai | ollama
model: google/gemini-2.5-flash
apiKeyEnv: OPENROUTER_API_KEYAllowed endpoints: openrouter.ai, api.openai.com, api.anthropic.com, plus loopback for local model servers (Ollama). See docs/llm.md for the full trust model.
A FixedCode project ties together three things:
| Concept | What it is |
|---|---|
| Spec | A YAML file describing what to build, validated against a bundle's JSON Schema. |
| Bundle | A package of Handlebars templates + an enrich() function that turns a spec into a render context. Produces files. |
| Generator | A programmatic (non-template) producer of files. Generators take an adapter-mapped context and emit files. The OpenAPI generator is the worked example. |
The engine pipeline:
spec.yaml → parse → validate → enrich → render templates → run generators → write
Two regeneration rules keep your work safe:
- Generated files (
overwrite: true) — always rewritten when you regenerate. - Extension points (
overwrite: false) — generated once, then user-owned.
A .fixedcode-manifest.json in the output dir tracks every generated file with its overwrite flag and content hash.
| Package | Kind | What it generates |
|---|---|---|
spring-domain |
bundle | Spring Boot DDD domain code in Kotlin: aggregates, commands, queries, controllers, repositories, events. |
ts-service |
bundle | TypeScript + Express service skeleton with structured logging, config, tests. |
ts-agent |
bundle | TypeScript AI-agent service: tool registry, LLM loop, HTTP server. |
python-service |
bundle | Python + FastAPI service skeleton. |
python-agent |
bundle | Python AI-agent service. |
crud-api |
bundle | Minimal CRUD REST API (template-only). |
vite-react-app |
bundle | Vite + React 19 + TypeScript SPA: TanStack Router, Tailwind v4, optional Supabase auth, optional Docker. |
kotlin-spring-bff |
bundle | Kotlin + Spring Boot 3.3 Backend-For-Frontend: Resilience4j circuit breakers, typed WebClient per downstream service, optional Caffeine cache, JWT/OAuth2 security, JPA, Docker. |
next-marketing-site |
bundle | Static-export Next.js 14 marketing site: brand-driven Hero / Navbar / Footer, configurable extension-point pages, Tailwind v4, optional Plausible/Umami analytics, optional Docker → nginx. |
ddd-spike |
bundle | Original DDD reference bundle. |
openapi |
generator | OpenAPI 3.0.3 spec from a domain context (used by spring-domain). |
Discover and install community bundles via the registry:
fixedcode registry list
fixedcode registry search agent
fixedcode registry install spring-domainBundles declare which non-functional requirements they bake in (auth, logging, error handling, retry, soft-delete, etc.). The engine knows about a catalog of 28 CFRs across 7 categories and can verify or report on coverage:
fixedcode cfr catalog # list known CFRs
fixedcode cfr suggest order-domain.yaml # what's missing?
fixedcode cfr check order-domain.yaml build # is everything wired?
fixedcode cfr report order-domain.yaml build # markdown reportSee docs/cfrs.md for the full catalog.
docs/architecture.md— engine pipeline, contracts, typesdocs/bundles.md— writing your own bundledocs/generators.md— writing your own generatordocs/cfrs.md— Cross-Functional Requirementsdocs/registry.md— how the registry works, publishingdocs/llm.md— LLM configuration and security caveatsdocs/release.md— internal: cutting a releasedocs/new-vertical-workflow.md— spin up a new SaaS vertical in 30 minutesdocs/feature-bundle-roadmap.md— capability/feature recipe roadmap
Pre-1.0; expect API evolution. Tracked in issues:
- AST-validate LLM output before writing extension points (#8)
- Publish bundles + the OpenAPI generator to npm
- Interactive
enrichconfirmation (#5) - More language bundles
- Feature/capability bundles inside services (image upload, auth, search, etc.) — see
docs/feature-bundle-roadmap.md
PRs welcome. See CONTRIBUTING.md.
Apache License 2.0 — © 2026 contributors.