DeployScaffoldGen

Scaffold a deploy.yaml manifest for application $ARGUMENTS with runtime configs, infrastructure, and concept assignments.

When to use: Use when creating a new deployment manifest for a CLEF application. Generates deploy.yaml with runtime configurations, infrastructure declarations, concept-to-runtime assignments, and build settings.

Design Principles

• Declarative Over Imperative: The deploy manifest declares intent (what runs where) — the framework resolves transport, storage, and engine assignments.
• Runtime Isolation: Each concept runs in exactly one runtime. Cross-runtime communication uses transport adapters configured in the infrastructure section.
• Infrastructure as Code: The IaC provider setting enables clef deploy to generate Terraform, CloudFormation, or Pulumi resources from the manifest.

Step-by-Step Process

Step 1: Register Generator

Self-register with PluginRegistry so KindSystem can track DeployConfig → DeployManifest transformations. Registration is also handled automatically by register-generator-kinds.sync.

Examples: Register the deploy scaffold generator

const result = await deployScaffoldGenHandler.register({}, storage);

Step 2: Preview Changes

Dry-run the generation using Emitter content-addressing to classify each output file as new, changed, or unchanged. No files are written.

Arguments: $0 appName (string), $1 runtimes (runtime[]), $2 concepts (conceptassignment[])

Step 3: Generate Deploy Manifest

Generate a deploy . yaml manifest with runtime configs , infrastructure declarations , and concept assignments .

Arguments: $0 appName (string), $1 runtimes (runtime[]), $2 concepts (conceptassignment[])

Checklist:

• App name is valid?
• Every runtime has a type and transport?
• Infrastructure storage backends match runtime storage refs?
• Every listed concept has a runtime assignment?
• IaC provider is set (terraform, cloudformation, pulumi, docker-compose)?
• Build section specifies compiler and test runner?
• All files written through Emitter (not directly to disk)?
• Source provenance attached to each file?
• Generation step recorded in GenerationPlan?

Examples: Generate a basic deploy manifest

clef scaffold deploy --app my-app

Generate with custom runtimes

clef scaffold deploy --app conduit --iac terraform

Generate programmatically

import { deployScaffoldGenHandler } from './deploy-scaffold-gen.impl';
const result = await deployScaffoldGenHandler.generate({
  appName: 'conduit',
  runtimes: [
    { name: 'api', type: 'node', transport: 'http', storage: 'postgresql' },
    { name: 'worker', type: 'node', transport: 'sqs', storage: 'redis' },
  ],
  concepts: [
    { name: 'User', runtime: 'api' },
    { name: 'Article', runtime: 'api' },
  ],
  iacProvider: 'terraform',
}, storage);

Step 4: Edit the Deployment Manifest

Refine the generated deploy.yaml: map concepts to runtimes, assign syncs to engines, configure transport adapters for cross-runtime communication, and declare runtime capabilities and resource limits.

References

• Deploy manifest (deploy.yaml) schema reference

Supporting Materials

• Deployment manifest scaffolding walkthrough

Quick Reference

Input	Type	Purpose
appName	String	Application name
version	String	Semver version
runtimes	list Runtime	Runtime configs (name, type, transport, storage)
concepts	list Assignment	Concept-to-runtime mappings
iacProvider	String	IaC provider (terraform, cloudformation, pulumi)

Anti-Patterns

Concept without runtime assignment

Concept listed in deploy manifest but not assigned to any runtime.

Bad:

concepts:
  User:
    spec: ./specs/user.concept
    # No implementations or runtime!

Good:

concepts:
  User:
    spec: ./specs/user.concept
    implementations:
      - language: typescript
        runtime: api
        storage: postgresql

Mismatched storage backends

Runtime references a storage backend not declared in infrastructure.

Bad:

runtimes:
  api: { storage: mongodb }  # Not in infrastructure!
infrastructure:
  storage:
    postgresql: { type: postgresql }

Good:

runtimes:
  api: { storage: postgresql }
infrastructure:
  storage:
    postgresql: { type: postgresql }

Validation

Generate a deploy scaffold:

npx tsx cli/src/index.ts scaffold deploy --app my-app

Validate deploy manifest:

npx tsx cli/src/index.ts deploy --validate

Run scaffold generator tests:

npx vitest run tests/scaffold-generators.test.ts

Related Skills

Skill	When to Use
/deployment-config	Validate and refine generated deploy manifests
/create-suite	Generate suites referenced by the deploy manifest
/build-orchestration	Build concepts for the declared runtimes