SuiteScaffoldGen

Scaffold a new CLEF suite named $ARGUMENTS with a suite.yaml manifest, concept spec stubs, and sync directory structure.

When to use: Use when creating a new CLEF suite from scratch. Generates a suite.yaml manifest with concept declarations, sync tier groupings, type parameter alignment, and directory structure stubs.

Design Principles

Convention Over Configuration: Generated suite.yaml follows the standard layout — concepts at top, syncs by tier, uses for external references. Tools work without extra configuration.
Type Parameter Alignment: Every concept's type parameter has an as tag that enables cross-concept type alignment. Concepts sharing the same as tag share the same entity type.
Sync Tier Discipline: Required syncs protect data integrity. Recommended syncs provide useful defaults. Integration syncs wire to external suites. Never promote a recommended sync to required without justification.

Step-by-Step Process

Step 1: Register Generator

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

Examples: Register the suite scaffold generator

const result = await kitScaffoldGenHandler.register({}, storage);
// { variant: 'ok', name: 'SuiteScaffoldGen', inputKind: 'KitConfig', ... }

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 description (string), $2 concepts (string[])

Step 3: Generate Suite Manifest

Generate a suite . yaml manifest and directory structure including stub concept specs and sync placeholders .

Arguments: $0 name (string), $1 description (string), $2 concepts (string[])

Checklist:

Suite name is kebab-case?
Version is valid semver?
All listed concepts have matching .concept stub files?
Syncs are grouped by tier (required/recommended/integration)?
Type parameter as tags are kebab-case with -ref suffix?
Dependencies use semver constraints?
All files written through Emitter (not directly to disk)?
Source provenance attached to each file?
Generation step recorded in GenerationPlan?

Examples: Generate a basic suite

clef scaffold suite --name auth --concepts User,Session,Password

Generate a domain suite with infrastructure

clef scaffold suite --name web3 --concepts Token,Wallet --domain

Generate programmatically

import { kitScaffoldGenHandler } from './suite-scaffold-gen.impl';
const result = await kitScaffoldGenHandler.generate({
  name: 'auth',
  description: 'Authentication and identity management.',
  concepts: ['User', 'Session', 'Password'],
  syncs: [
    { name: 'ValidateSession', tier: 'required' },
    { name: 'RefreshExpired', tier: 'recommended' },
  ],
}, storage);

Step 4: Edit the Suite Manifest

Refine the generated suite.yaml: add concept specs with type parameters and as tags, declare syncs grouped by tier (required, recommended, integration), set dependencies with semver constraints, and add infrastructure declarations for domain suites.

References

Supporting Materials

End-to-end suite scaffolding walkthrough

Quick Reference

Input	Type	Purpose
name	String	Suite name (kebab-case)
description	String	Suite purpose description
concepts	list String	PascalCase concept names
syncs	list {name, tier}	Sync declarations with tiers
dependencies	list String	External suite dependencies
isDomain	Boolean	Include infrastructure section

Anti-Patterns

Missing type parameter alignment

Concepts in the same suite lack as tags, preventing cross-concept type unification.

Bad:

concepts:
  User:
    spec: ./user.concept
    params:
      U: {}
  Session:
    spec: ./session.concept
    params:
      S: {}

Good:

concepts:
  User:
    spec: ./user.concept
    params:
      U: { as: user-ref }
  Session:
    spec: ./session.concept
    params:
      S: { as: session-ref }
      U: { as: user-ref }

Flat sync list without tiers

All syncs listed without tier annotation — impossible to know which are safe to override.

Bad:

syncs:
  - syncs/validate.sync
  - syncs/notify.sync
  - syncs/audit.sync

Good:

syncs:
  required:
    - path: ./syncs/validate.sync
  recommended:
    - path: ./syncs/notify.sync
      name: Notify

Validation

Generate a suite scaffold:

npx tsx cli/src/index.ts scaffold suite --name my-suite --concepts User,Session

Validate generated suite:

npx tsx cli/src/index.ts suite validate ./suites/my-suite

Run scaffold generator tests:

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

Related Skills

Skill	When to Use
`/suite-lifecycle`	Manage suite versions and dependencies after scaffolding
`/create-concept`	Generate concept specs for the suite's concepts
`/create-sync`	Generate sync rules for the suite's syncs