ConceptScaffoldGen

Scaffold a concept spec for $ARGUMENTS with annotations, state declarations (groups, enums, records), typed action signatures, capabilities, and a register() action.

When to use: Use when creating a new concept specification from scratch. Generates a .concept file with annotations (@version, @category, @visibility, @gate), purpose, state (with groups, enum types, record types), actions with typed variants, invariants, capabilities block, and a register() action following Jackson's methodology.

Design Principles

• Singularity: Each concept serves exactly one purpose — if the purpose has 'and', it's two concepts.

• Independence: A concept never references another concept's types or calls another concept's actions. Use type parameters and syncs.

• Sufficiency & Necessity: Every state field is needed by at least one action. Every action serves the concept's purpose. No dead state.

• Invariant Completeness: Key properties are captured as formal invariants documenting what must be true after each action.

• Description Quality: Every variant description must explain the outcome in domain terms — never echo the variant name ('Created.') or use vague text ('Failed.'). Error variants explain what went wrong; ok variants explain what is now true.

Step-by-Step Process

Step 1: Register Generator

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

Examples: Register the concept scaffold generator

const result = await conceptScaffoldGenHandler.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 typeParam (string), $2 purpose (string), $3 stateFields (statefield[]), $4 actions (actiondef[]), $5 version (int?), $6 gate (bool?), $7 capabilities (string[])

Step 3: Generate Concept Spec

Generate a well formed . concept file with state declarations , typed action signatures , variant returns , and a register ( ) action for PluginRegistry discovery .

Arguments: $0 name (string), $1 typeParam (string), $2 purpose (string), $3 stateFields (statefield[]), $4 actions (actiondef[]), $5 version (int?), $6 gate (bool?), $7 capabilities (string[])

Checklist:

• Concept name is PascalCase?

• Type parameter is a single capital letter?

• Purpose block describes why, not what?

• State fields use correct relation types (set, ->, option, list)?

• Every action has at least one variant?

• register() action is included for PluginRegistry?

• Annotations (@category, @visibility) are present?

• @version annotation included if this is a versioned spec?

• State fields use enum types for fixed value sets?

• State groups organize related fields?

• Capabilities block present for generator/plugin concepts?

• Variant descriptions explain outcomes, not just echo variant names?

• All files written through Emitter (not directly to disk)?

• Source provenance attached to each file?

• Generation step recorded in GenerationPlan?

Examples: Generate a basic concept

clef scaffold concept --name User --actions create,update,delete

Generate with custom state

clef scaffold concept --name Article --param A --category domain

Generate with version and gate

clef scaffold concept --name Approval --version 2 --gate --capabilities search,export

Step 4: Edit the Concept Spec

Refine the generated .concept file: 1. Add annotations: @version(N) for versioning, @gate for async gates, @category("domain") for grouping, @visibility("public"|"internal"). 2. Write a purpose block explaining why the concept exists (not how it works). 3. Design state fields: sets (set T), mappings (T -> Type), option/list wrappers, enum types ({Active | Inactive | Pending}), record types ({key: String, value: String}), state groups for related fields. 4. Define actions with typed params and variant returns. All primitives: String, Int, Float, Bool, Bytes, DateTime, ID. 5. Write invariants with after/then/and chains. 6. Add capabilities block if the concept is a generator or plugin.

References

• Concept specification writing guide

Supporting Materials

• Concept spec scaffolding walkthrough

Quick Reference

Input Type Purpose

name String PascalCase concept name

typeParam String Type parameter letter (default: T)

purpose String Purpose description

category String Annotation category (domain, devtools, etc.)

version Int @version annotation number

gate Bool @gate annotation for async gates

stateFields list StateField State declarations (with group, enum, record support)

actions list ActionDef Action signatures with variants

capabilities list String Capabilities block entries

invariants list String Invariant steps

Anti-Patterns

Purpose describes implementation

Purpose block says how the concept works instead of why it exists.

Bad:

purpose { Store users in a Map<string, User> and provide CRUD operations via async handler methods. }

Good:

purpose { Manage user identity and profile information. }

Missing variants

Action only has ok variant — no error handling path.

Bad:

action create(name: String) { -> ok(user: U) { Created. } }

Good:

action create(name: String) { -> ok(user: U) { New user registered and ready for profile setup. } -> duplicate(name: String) { A user with this name already exists. } -> error(message: String) { Creation failed due to a storage or validation error. } }

Terse or echo descriptions

Variant descriptions that echo the variant name or use a single generic word — they tell the reader nothing about the actual outcome.

Bad:

action create(name: String) { -> ok(user: U) { Created. } -> error(message: String) { Failed. } }

Good:

action create(name: String) { -> ok(user: U) { New user registered and ready for authentication setup. } -> error(message: String) { Creation failed due to a storage or validation error. } }

Validation

Generate a concept scaffold:

npx tsx cli/src/index.ts scaffold concept --name User --actions create,update,delete

Validate generated concept:

npx tsx cli/src/index.ts check specs/app/user.concept

Run scaffold generator tests:

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

Related Skills

Skill When to Use

/concept-designer

Design concepts using Jackson's methodology before generating

/create-handler

Generate handler implementations for the concept

/create-sync

Generate sync rules connecting the concept