From Specs to Code: Why SysMARA Now Scaffolds Your Implementation

· SysMARA Team

If you ran sysmara build before v0.5.1, you got a curious result. The app/generated/ directory would fill up with route handler stubs, test scaffolds, and capability metadata. But every other directory in app/ — entities/, capabilities/, policies/, invariants/, services/ — stayed empty.

The framework told you what to build (via YAML specs) and generated the wiring (via the capability compiler), but left you staring at empty directories when it came time to write the actual implementation. For an AI-first framework, this was a significant gap. An AI agent reading the project had to figure out the right file structure, the correct import paths, the type names to use, and which policies and invariants to enforce — all from scratch.

The Gap Between Specification and Implementation

SysMARA's core philosophy is that architecture should be machine-readable. Your YAML specs contain everything an AI agent needs to understand the system: entity fields with types and constraints, capability bindings with policies and invariants, module boundaries with dependency rules. The capability compiler already proved that this information could be transformed into code.

But the compiler only generated generated-zone files — route stubs that get overwritten on every build. The editable-zone files where developers actually implement business logic were left as an exercise.

This is like giving someone a blueprint for a house and the plumbing fixtures, but not framing the walls.

What the Scaffold Generator Produces

Starting in v0.5.1, sysmara build includes a new step 5: scaffold generation. After compiling capabilities, the build pipeline reads your specs and generates starter TypeScript files for every entity, capability, policy, invariant, and module service.

Each generated file is specific to your system. This is not generic boilerplate — the scaffold reads your actual field definitions, policy conditions, and invariant rules:

  • Entity files contain typed interfaces matching the exact fields in your YAML spec, with optional markers and a runtime validation helper.
  • Capability handlers import the typed Input/Output interfaces from the generated route stubs and include TODO comments for each policy to enforce and invariant to validate.
  • Policy enforcers include the actor type, the effect (allow/deny), and comments for each condition from the spec.
  • Invariant validators import the entity type and embed the rule description as a TODO.
  • Module services get a class with one method stub per capability the module owns.

Why "Never Overwrite" Matters

The most important design decision in the scaffold generator is what it does not do: it never overwrites existing files. If you run sysmara scaffold and app/entities/user.ts already exists, it is skipped.

This means you can safely re-run the build pipeline after adding new entities, capabilities, or modules to your specs. Only the new stubs get generated. Your existing implementation code is untouched.

This is the right separation: generated-zone files (app/generated/) are always overwritten because they are deterministic outputs of the compiler. Editable-zone files (app/entities/, app/capabilities/, etc.) are scaffolded once and then owned by the developer.

What This Means for AI Agents

An AI agent working on a SysMARA project now has a complete starting point. After sysmara build:

  1. The YAML specs define the system architecture.
  2. The generated route stubs handle HTTP wiring.
  3. The scaffold files provide typed starting points for every piece of business logic.

The agent can read app/capabilities/create_user.ts and see exactly which policies to enforce, which entities to load, and which invariants to validate. The TODO comments are not generic — they reference the specific policy and invariant names from the spec. The import paths are correct. The types are wired.

The gap between "system defined" and "system implemented" just got much smaller.

Try It

npm install @sysmara/core
npx sysmara init
npx sysmara build

# Or standalone:
npx sysmara scaffold

See the Scaffold Generator documentation for full details on what gets generated and how to use the programmatic API.