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 .

Checklist:

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

concept-scaffold-gen

ConceptScaffoldGen

Design Principles

Step-by-Step Process

Step 1: Register Generator

Step 2: Preview Changes

Step 3: Generate Concept Spec

Step 4: Edit the Concept Spec

References

Supporting Materials

Quick Reference

Anti-Patterns

Purpose describes implementation

Missing variants

Terse or echo descriptions

Validation

Related Skills