Builder

MolnOS Builder is the native spec-driven development workflow for MolnOS. It combines structured artifacts, tracked iterations, and deployable outputs so teams can move quickly without losing control.

Features

Versioned Artifacts

Builder keeps four artifacts as first-class inputs:

intent - the intended outcome
guardrails - boundaries and constraints
requirements - functional and technical requirements
checks - evaluation criteria

Each artifact supports revision history and explicit activation, making runs reproducible.

Structured Delivery Lifecycle

Builder runs through a clear lifecycle:

Plan to resolve artifact selection and create an execution plan
Generate for new implementations
Evolve for incremental updates from a baseline generation
Evaluate against checks
Apply to deploy a selected generation

Context-Native Iteration

All operations are scoped under /contexts/{contextName}/builder/*. This keeps spec, generation history, and deployment state aligned to one context boundary.

Traceable Runs and Outputs

Builder stores generations and runs with timestamps, model/provider metadata, and input/output summaries. This makes it easy to audit what changed and why.

Why Builder

Builder is designed to give immediate value with very low process overhead:

Cloud-integrated full lifecycle: Spec artifacts, generation, evaluation, and deployment run inside the same context boundary
Integrated instead of disaggregated: No split between chat tool, separate IDE plugin state, and separate deployment handoff
Editable outputs: You can update generated code directly and apply those changes without leaving Builder
Stateful iteration: evolve uses a persistent context thread and baseline generation instead of stateless prompt retries
Lean by default: Four artifact types plus a small run lifecycle keeps the workflow focused, without heavyweight process frameworks
Minimal learning curve: The flow maps to everyday development behavior (plan -> generate/evolve -> evaluate -> apply)

Common Use Cases

Build a new service from specs, then apply the result
Iteratively refactor generated code with evolve while preserving context resources
Evaluate candidate changes against checks before deployment
Import runtime state into Builder before starting a new iteration

How It Works

Console

Use MolnOS Console Builder to edit artifacts, run plan/generate/evolve/evaluate, inspect generation outputs, and apply deployments in one workflow.

CLI

The CLI maps directly to Builder endpoints:

# Create and activate artifact revisions
molnos builder revision-create my-context intent @intent.md --activate
molnos builder revision-create my-context requirements @requirements.md --activate
molnos builder revision-create my-context checks @checks.md --activate

# Run the lifecycle
molnos builder plan my-context
molnos builder generate my-context
molnos builder evolve my-context "tighten error handling and simplify flow"
molnos builder evaluate my-context

# Inspect outputs
molnos builder generations my-context
molnos builder runs my-context

# Apply a generation
molnos builder apply my-context <generationId>

API

Builder endpoints are available under /contexts/{contextName}/builder/*.

Create or revise artifacts

Create a new immutable revision for one artifact type:

POST /contexts/{contextName}/builder/artifacts/{artifactType}/revisions

{
  "contentMarkdown": "# Problem\nOn-call engineers spend too long scanning logs.",
  "activate": true,
  "createdBy": "docs-example"
}

Use artifactType as one of intent, guardrails, requirements, checks.

Build a plan from active or selected revisions

Use active revisions:

POST /contexts/{contextName}/builder/plan

Pin explicit revisions:

{
  "selection": {
    "intent": { "revisionId": "rev-intent-1" },
    "guardrails": { "revisionId": "rev-guardrails-1" },
    "requirements": { "revisionId": "rev-requirements-2" },
    "checks": { "revisionId": "rev-checks-3" }
  }
}

Generate initial code and IaC

POST /contexts/{contextName}/builder/generate

{
  "selection": {
    "intent": { "revisionId": "rev-intent-1" },
    "requirements": { "revisionId": "rev-requirements-2" },
    "checks": { "revisionId": "rev-checks-3" }
  },
  "resourceTypes": ["functions", "sites"],
  "iterationFeedback": "Prefer clear helper functions and explicit error handling."
}

Evolve from a baseline generation

POST /contexts/{contextName}/builder/evolve

{
  "prompt": "Refactor for readability and keep behavior unchanged.",
  "generationId": "gen-baseline-123"
}

evolve writes to a single context thread so you can keep iterating without losing prior state.

Apply with optional inline file overrides

Apply a stored generation directly:

{
  "generationId": "gen-456"
}

Apply and override files in the same request (for hand-edited code):

{
  "generationId": "gen-456",
  "files": [
    {
      "path": "functions/dailyDigest.js",
      "content": "export async function handler(req, context) { return { ok: true }; }"
    }
  ]
}

This allows cloud-native iteration while still supporting precise manual edits.

Evaluate and inspect history

Evaluate a specific generation:

POST /contexts/{contextName}/builder/evaluate

{
  "generationId": "gen-456"
}

Inspect outputs and run history:

GET /contexts/{contextName}/builder/generations
GET /contexts/{contextName}/builder/generations/{generationId}
GET /contexts/{contextName}/builder/runs
GET /contexts/{contextName}/builder/runs/{runId}

See full request and response schemas in OpenAPI schema.

Artifact Types

{artifactType} accepts:

intent
guardrails
requirements
checks

Permissions

Builder operations require builder-scoped permissions:

builder.artifact.read, builder.artifact.list, builder.artifact.update
builder.revision.create, builder.revision.read, builder.revision.list, builder.revision.activate
builder.run.plan, builder.run.import, builder.run.generate, builder.run.evolve, builder.run.evaluate, builder.run.apply, builder.run.read, builder.run.list