InterfaceScaffoldGen

Scaffold an interface.yaml for $ARGUMENTS with target configs, SDK settings, and per-concept overrides.

When to use: Use when creating a new interface generation manifest. Generates interface.yaml with target configurations for REST, GraphQL, gRPC, CLI, MCP, and Claude Skills, plus SDK settings and spec outputs.

Design Principles

Target Independence: Each target (REST, GraphQL, CLI, etc.) generates independently — they share concept specs but produce separate output trees.
Layered Configuration: Configuration flows from global defaults → target defaults → per-concept overrides. Specific settings override general ones.
SDK Completeness: Each SDK target should generate a fully-functional client library — types, methods, error handling, and documentation.

Step-by-Step Process

Step 1: Register Generator

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

Examples: Register the interface scaffold generator

const result = await interfaceScaffoldGenHandler.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 name (string), $1 targets (string[]), $2 sdks (string[])

Step 3: Generate Interface Manifest

Generate an interface . yaml manifest with target specific defaults , SDK configurations , and concept overrides .

Arguments: $0 name (string), $1 targets (string[]), $2 sdks (string[])

Checklist:

Interface name is valid?
At least one target is specified?
Each target has sensible defaults?
SDK package names are unique per language?
Per-concept overrides reference valid concepts?
Grouping strategy is set?
All files written through Emitter (not directly to disk)?
Source provenance attached to each file?
Generation step recorded in GenerationPlan?

Examples: Generate a REST + GraphQL interface

clef scaffold interface --name my-api --targets rest,graphql --sdks typescript

Generate a full-stack interface

clef scaffold interface --name my-api --targets rest,graphql,grpc,cli,mcp,claude-skills --sdks typescript,python,go

Step 4: Edit the Interface Manifest

Refine the generated interface.yaml: configure targets (CLI, REST, MCP, Claude Skills, SDK), set per-concept overrides for routing and grouping, define workflows with steps and prose, and add annotations for generation control.

References

Interface manifest (interface.yaml) schema reference

Supporting Materials

Interface manifest scaffolding walkthrough

Quick Reference

Input	Type	Purpose
name	String	Interface name
targets	list String	Target types (rest, graphql, grpc, cli, mcp, claude-skills)
sdks	list String	SDK languages (typescript, python, go, rust, java, swift)
concepts	list String	Concepts with per-concept overrides
openapi	Boolean	Generate OpenAPI spec (default: true)
asyncapi	Boolean	Generate AsyncAPI spec (default: false)

Anti-Patterns

Targets without concept overrides

All concepts use the same REST base path — collision risk.

Bad:

targets:
  rest: { basePath: /api }
# No per-concept overrides — all concepts share /api

Good:

targets:
  rest: { basePath: /api }
concepts:
  User:
    rest: { basePath: /api/users }
  Article:
    rest: { basePath: /api/articles }

Validation

Generate an interface scaffold:

npx tsx cli/src/index.ts scaffold interface --name my-api --targets rest,graphql

Generate interfaces from manifest:

npx tsx cli/src/index.ts interface generate --manifest my-api.interface.yaml

Run scaffold generator tests:

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

Related Skills

Skill	When to Use
`/create-suite`	Generate suites whose concepts the interface exposes
`/create-concept`	Generate concept specs for interface concepts
`/deployment-config`	Deploy the service that hosts the generated interface

interface-scaffold-gen