Skip to content
Almathal Handbook

Spec

Accepted

A Spec (short for Archetype Spec) is the resolved configuration for one specific build of an Archetype. It combines:

  • The Archetype’s structure (Slots, Variation Points, Seams)
  • The user’s filled-in choices (which entities, which database, which auth provider)
  • The resolved Slot selections (which Adapters and Modules will be used)
  • The locked versions (exactly which version of each Adapter, Module, scaffolder)
  • The sanity check configuration (which checks run, blocking or advisory)

The Spec is the single source of truth for a generation. Every pipeline stage reads from it; every decision references it; the audit trail records it.

Spec Format

Specs are canonical JSON, validated against the Archetype Spec schema. YAML is acceptable as an edit-time format and converts losslessly to JSON.

Skeleton of a Spec (heavily abbreviated):

{
  "schema_version": "archetype-spec/v1",
  "spec_id": "build-7a3f8c2e",
  "archetype": {
    "id": "archetype:internal-crud-admin",
    "uuid": "f1e2d3c4-...",
    "version": "0.1.0"
  },
  "variation_points": {
    "database": "postgresql",
    "entities": [
      { "name": "User", "fields": [...] },
      { "name": "Product", "fields": [...] }
    ]
  },
  "adapter_slots": [
    {
      "slot_id": "slot:internal-crud-admin/persistence-primary",
      "selected": "adapter:java/spring-data-jpa@3.2.4",
      "uuid": "550e8400-..."
    }
  ],
  "module_slots": [
    {
      "slot_id": "slot:internal-crud-admin/auth",
      "selected": "module:auth/jwt-with-rbac@1.0.0",
      "uuid": "a1b2c3d4-..."
    }
  ],
  "scaffolders": [
    {
      "id": "scaffolder:jhipster",
      "version": "8.6.0",
      "config": { ... }
    }
  ],
  "seams": [ ... ],
  "sanity_checks": { ... },
  "fallback": { ... },
  "approval": {
    "approved_by": "user-12345",
    "approved_at": "2026-06-10T14:33:12Z",
    "summary_shown": "..."
  }
}

Spec Lifecycle

A Spec moves through these states during a generation:

  1. Drafting — Resolver is populating Variation Points and Slots
  2. Resolved — All fields populated, ready for Compatibility Validation
  3. Validated — Compatibility passed, ready for Build Approval
  4. Approved — User has signed off
  5. Building — Scaffolding and Stitching are in progress
  6. Verified — Build Verification passed; output ready for delivery
  7. Delivered — User has received the generated application
  8. Archived — The Spec is recorded as part of the build’s permanent audit record

Specs are immutable from the Approved state onward. Subsequent changes require a new Spec for a new build.

The Spec Is the Reproducibility Contract

Re-running a generation with the same Spec produces the same output, modulo the inherent non-determinism in the LLM Stitcher (which is bounded by Seam contracts and verification). Specifically:

  • Same Adapter versions selected
  • Same scaffolders run with same configuration
  • Same Modules composed
  • Same Variation Points filled

This is what makes generated apps regeneratable months later: the recorded Spec captures everything needed to reproduce the build, exactly as Cargo.lock or package-lock.json capture dependency state.

How Variation Points Resolve Into the Spec

Variation Points declared in the Archetype get resolved during Spec Resolution:

In Archetype declarationIn resolved Spec
{ "id": "database", "type": "enum", "options": ["postgresql", "mysql"], "default": "postgresql" }"database": "postgresql"
{ "id": "entities", "type": "user_defined_list", "min": 1 }"entities": [{...}, {...}]

The resolved Spec records the answers, not the schema. The schema (Archetype declaration) lives separately; the Spec is the instance.

How Slots Resolve Into the Spec

Slot declarations become Slot resolutions:

In Archetype declarationIn resolved Spec
{ "slot_id": "slot:.../persistence", "category": "persistence", "default": "adapter:java/spring-data-jpa", "alternatives": [...] }{ "slot_id": "slot:.../persistence", "selected": "adapter:java/spring-data-jpa@3.2.4", "uuid": "..." }

The resolved Spec records which Adapter or Module was chosen, locked to its exact version, with the UUID for audit purposes.

Saved Specs as Reusable Templates

An approved Spec can be saved as a reusable template — particularly useful for enterprises generating multiple similar apps. The saved template includes:

  • The Archetype reference (version-locked)
  • The Variation Point answers
  • The Slot selections

A new generation can start from a saved template, presenting the user with the prior selections pre-filled. The user can adjust as needed, but doesn’t start from scratch.

Saved templates are themselves versioned and stored in the customer’s space (not the global platform registry). They cannot reference Adapters or Modules that have been archived; if so, the template prompts the user to upgrade.

What’s Not in the Spec

The Spec contains configuration, not output. After a build runs, the generated application’s code, containers, tests, and audit trail are separate artifacts. The Spec is what produced them; they are not part of the Spec itself.

The Spec also does not contain the Adapter or Module Manifests themselves — only references (slug + UUID + version). The Manifests live in the central registry and are fetched as needed.