SysMARA vs Internal Scaffolding Scripts

Scaffolding scripts generate code. The Capability Compiler understands your system.

The Scaffolding Script Pattern

Many engineering teams build internal scaffolding tools. These take various forms:

• Yeoman generators — Template-based project and component scaffolding
• Plop generators — Micro-generators for adding new files based on templates
• Custom CLI scripts — Team-specific scripts that generate boilerplate for new services, models, or endpoints
• Cookiecutter / copier — Template-based project generation with variable substitution
• Framework generators — rails generate, nest generate, artisan make

These tools are useful. They enforce naming conventions, reduce boilerplate, and ensure new components follow team patterns. But they share a fundamental limitation: they generate code without understanding the system.

What Scaffolding Scripts Know

A typical scaffolding script knows:

• The template to use (e.g., "create a new service with these files")
• The variables you provide (name, type, options)
• The directory structure to place files in
• Formatting and naming conventions

What Scaffolding Scripts Do Not Know

• What entities already exist in the system
• What invariants constrain the entity you are scaffolding for
• What policies should govern the new capability
• Whether the new component creates a dependency cycle
• Whether the new component conflicts with an existing module boundary
• What downstream impact the new component will have

Scaffolding scripts are context-free generators. They produce output based on a template and inputs, with no awareness of the system they are generating into.

What the Capability Compiler Knows

SysMARA's Capability Compiler operates on the system graph — the complete, compiled representation of your architecture. When it generates code, it knows:

Entity relationships

The compiler knows that the subscription entity in the billing module references workspaces.workspace. Generated handler code includes the correct type references and validation for cross-module relationships.

Invariant requirements

The compiler knows that downgrade_subscription is constrained by cannot_downgrade_with_unpaid_invoices. Generated handler scaffolding includes a placeholder for the invariant check with a comment referencing the invariant name and severity.

Policy bindings

The compiler knows which policies govern each capability. Generated handlers include the correct authorization checks based on declared policies, not guessed from templates.

Flow context

The compiler knows if a capability is part of a flow. Generated code includes flow-step markers that the runtime uses for flow tracking and step ordering validation.

Side-by-Side: Scaffolding a New Capability

With a Plop generator

# Run the generator
npx plop capability

# Prompts:
# ? Capability name: update_seat_count
# ? Module: billing
# ? Type: mutation

# Output: generates these files from templates
# src/billing/capabilities/update-seat-count.handler.ts
# src/billing/capabilities/update-seat-count.test.ts
# src/billing/capabilities/update-seat-count.schema.ts

The generated files follow naming conventions and include standard boilerplate, but the handler body is empty. The test file has placeholder tests. The schema file has a generic input/output type. Nothing knows about the seat_allocation entity's fields, the invariants that apply, or the policies that govern access.

With the SysMARA Capability Compiler

# Define the capability in specs
# specs/billing/capabilities/update-seat-count.yaml
name: update_seat_count
module: billing
entity: seat_allocation
type: mutation
invariants:
  - seat_count_minimum_one
policies:
  - billing_admin
  - admin_full_access

# Compile
npx sysmara compile

The compiler generates handler scaffolding that includes:

• Input type derived from the seat_allocation entity's declared fields
• A named invariant check placeholder for seat_count_minimum_one
• Authorization hooks for billing_admin and admin_full_access policies
• Route registration based on the capability type and module
• A manifest entry with a checksum for the generated file

Fire-and-Forget vs Regenerable

This is a critical distinction:

Scaffolding scripts are fire-and-forget

Once a scaffolding script generates code, the generated files are fully owned by the developer. The generator has no ongoing relationship with the output. If you change the template, existing generated files are unaffected. If you rename an entity, existing scaffolded code is unaware. The generated code immediately diverges from the template.

The Capability Compiler is regenerable

SysMARA's generated code is tracked with checksums in a manifest. The compiler knows which files it generated and whether they have been modified. This enables:

• Regeneration — If you change a spec (add a field, add an invariant), you can re-run the compiler. It regenerates the scaffolding while preserving your custom logic in safe edit zones.
• Drift detection — The compiler can detect when generated code has been modified outside of safe edit zones, flagging potential issues.
• Consistency guarantees — Every generated handler follows the same structure, with the same invariant check patterns, the same policy hooks, the same flow markers. This is not just convention — it is compiler output.

The Manifest

After compilation, SysMARA produces a manifest file that records:

{
  "version": "1.0.0",
  "generatedAt": "2025-01-15T10:30:00Z",
  "files": [
    {
      "path": "src/generated/billing/update-seat-count.handler.ts",
      "checksum": "sha256:a1b2c3d4...",
      "source": "specs/billing/capabilities/update-seat-count.yaml",
      "safeEditZones": [
        { "start": 15, "end": 45, "label": "business_logic" }
      ]
    }
  ]
}

Scaffolding scripts have no equivalent. Once they run, they forget.

Where Scaffolding Scripts Are Better

Where the Capability Compiler Is Better

When to Use Scaffolding Scripts

• Your project is small and does not have complex invariants or cross-module dependencies
• You need to generate non-backend artifacts (frontend components, infrastructure code, documentation)
• Your team has effective scaffolding already and the cost of switching is not justified
• You want framework-independent code generation

When to Use the Capability Compiler

• Your system has invariants and policies that generated code must respect
• You need regeneration — specs evolve and generated code should stay in sync
• AI agents are generating capabilities and need the compiler to ensure correctness
• You want a manifest that tracks generated code with checksums and safe edit zones