comet-block

name: comet-block description: Creates and edits Comet blocks (API, Admin, Site) from natural-language prompts, including block fixture services. Use when the user asks to create a new block, edit an existing block, add/remove/change fields or child blocks, scaffold block files, or create block fixtures in a Comet project.

Comet Block Skill

Table of Contents

1. When to use
2. Workflow routing
3. Step 1 — Parse the prompt
4. Step 2 — Discover the project
5. Editing workflow ← follow this for edits
6. Step 3 — Create the API block ← creation only
7. Step 4 — Create the Admin block ← creation only
8. Step 5 — Create the Site block ← creation only
9. Step 6 — Register the block
10. Step 7 — Create block fixtures
11. Naming conventions
12. Code generation
13. Cross-references

When to use

• Creating a new Comet block from a natural-language description.
• Scaffolding block files across API, Admin, and Site layers.
• Adding, removing, or changing fields or child blocks in an existing block.
• Changing enum values, field types, or property names in an existing block.
• Creating block fixture services for seeding development databases.

Workflow routing

User request
    │
    ├─ Creating a new block?   → Steps 1 → 2 → 3 → 4 → 5 → 6 → 7
    │
    └─ Editing an existing block? → Steps 1 → 2 → Editing workflow → 7

Step 1 — Parse the prompt

Extract from the user's request:

1. Block name — derive PascalCase for Admin/Site (TeaserItemBlock) and kebab-case for API (teaser-item.block.ts). See Naming conventions.
2. Properties — for each property determine its type. Common types:
   • String — plain text (title, label).
   • Number — numeric with min/max (overlay).
   • Boolean — toggle/switch (showOverlay).
   • Numeric select — fixed numeric options. Use @IsInt() + @BlockField() in the API (not type: "enum"); use createCompositeBlockSelectField with number options in Admin. See select.md.
   • Enum/select — fixed string values (variant, alignment). See select.md.
   • RichText — formatted text. Choose shared RichTextBlock or a scoped inline one. See rich-text.md.
   • Image — choose DamImageBlock, PixelImageBlock, SvgImageBlock, or a project-specific MediaBlock. See image.md.
   • Child block — any other existing block used as a property.
   • List — multiple instances of a child block; requires a list block + item block pair. See block-types.md.
3. Registration target — where the block is added. Default: PageContentBlock (and ContentGroupBlock if it exists). Ask if unclear.
4. Ambiguities — if "image" is mentioned without specifics, or a referenced block may not exist, ask before proceeding.

For block type decision guidance, see block-types.md.

Step 2 — Discover the project

Before generating any code:

1. Locate the api and admin directories.
2. Locate the site package or packages by their dependencies, not the folder name. site is only the conventional name — a project may name the package differently or have several. A package.json (outside node_modules) that depends on @comet/site-nextjs or @comet/site-react is certainly a site package, since site blocks render through these (withPreview, PropsWithData):

   grep -rl --include='package.json' --exclude-dir=node_modules -E '"@comet/site-(nextjs|react)"' . | xargs -n1 dirname
   

   A frontend package can also exist without those dependencies — for example one that renders blocks for email with @comet/mail-react. Skip the site steps only if you find neither a site package nor another frontend package.
3. Find existing blocks directories — typically src/documents/pages/blocks/. Some shared blocks live in common/blocks/ or similar. Check both.
4. Verify referenced blocks exist — search for any blocks named in the prompt (e.g., HeadingBlock, LinkBlock) in all layers and note their import paths.
5. Find registration targets — search for createBlocksBlock usages to locate PageContentBlock, ContentGroupBlock, or other targets. Note file paths in all layers.

In the later steps and the reference files, example paths written as site/… mean the site package's root and @src/… means its src/ directory. They show the conventional layout — substitute the actual package folder found here.

Editing workflow

Use this instead of Steps 3–5 when modifying an existing block.

Classify each change

A single request may involve multiple change types — classify each independently.

Determine if a migration is needed

Ask the user before creating a migration if they haven't mentioned it. Explain the old vs new data shape and confirm.

Migration IS needed:

• Adding a required field (existing data lacks it).
• Changing a field's type (old data has the old shape).
• Removing a field (recommended to keep data clean).
• Renaming a field (old data uses the old name).

Migration is NOT needed:

• Adding an optional/nullable field (@IsUndefinable() + @BlockField({ nullable: true })).
• Adding a new supported block to a BlocksBlock or OneOfBlock.
• Adding new enum values (existing data unaffected).

When in doubt, create a migration — it is always the safer choice. See migration.md for the full decision matrix, class template, and annotated examples.

Apply changes in order

1. API block — update BlockData and BlockInput classes, decorators, validators.
2. Migration — create and register if needed. Update createBlock third argument to the options object. See migration.md.
3. Admin block — update the blocks object: add/remove entries, labels, options.
4. Site block (if exists) — update destructured fields and rendered output.
5. Block fixture (if exists) — update generateBlockInput() to match changes. See fixtures.md.
6. Verify consistency — confirm every property key name matches across all three layers.

Step 3 — Create the API block

File: {block-name}.block.ts (kebab-case). Place in the blocks directory found in Step 2.

Key patterns:

• BlockData uses @BlockField() for fields, @ChildBlock(X) for child blocks.
• BlockInput uses validators + @ChildBlockInput(X) for child blocks; implement transformToBlockData() with inputToData.
• Export with createBlock(BlockData, BlockInput, "BlockName").
• Enums require @BlockField({ type: "enum", enum: MyEnum }) — never use type: "enum" for numeric options.
• For list blocks: create the item block first, then createListBlock({ block: ItemBlock }, "MyList").

For field decorators, validator reference, savability rules, and complete examples, see api-patterns.md.

Step 4 — Create the Admin block

File: {BlockName}Block.tsx (PascalCase). Place in the blocks directory found in Step 2.

Key patterns:

• Use createCompositeBlock with a blocks object mapping property names to block configs.
• Helper functions: createCompositeBlockTextField, createCompositeBlockSelectField, createCompositeBlockSwitchField.
• fullWidth defaults to true in text and select helpers — omit it explicitly.
• All user-facing strings use FormattedMessage from react-intl. Follow ID convention: {blockName}Block.{field}.
• Set BlockCategory when the block is used inside a blocks block.
• Set previewContent in the override callback for meaningful block list previews.
• hiddenInSubroute rule: When the composite contains sub-route blocks (list, blocks-block, one-of), set hiddenInSubroute: true on every sibling entry that is not a sub-route block. Never set it on sub-route block entries themselves.
• label vs title: when the helper has a label, omit title on the block entry. When it has no label, provide title on the entry. They are mutually exclusive.
• For list blocks: use createListBlock from @comet/cms-admin with name, displayName, block, itemName, itemsName.

For the full helper API, BlockCategory enum, and complete examples, see admin-patterns.md.

Step 5 — Create the Site block (if site exists)

File: {BlockName}Block.tsx (PascalCase). Place in the blocks directory found in Step 2.

Key patterns:

• Wrap with withPreview(Component, { label: "BlockName" }).
• Type props as PropsWithData<{BlockName}BlockData> — import from @src/blocks.generated.
• Use hasRichTextBlockContent guard before rendering RichText. Never wrap RichTextBlock in a Typography component.
• DamImageBlock is not exported from @comet/site-nextjs — use the project-specific wrapper. See image.md.
• Always validate aspectRatio against allowedImageAspectRatios in the API config. See image.md.
• The supportedBlocks object (for BlocksBlock/PageContent site wrapper) must be defined at module level, not inside the component.

For withPreview, OneOfBlock/OptionalBlock, and complete site examples, see site-patterns.md.

Step 6 — Register the block

Add the new block to the registration target in all three layers using identical camelCase key names.

Default target: PageContentBlock. If ContentGroupBlock exists and mirrors PageContentBlock supported blocks, also register there.

// API & Admin: supportedBlocks object inside createBlocksBlock
myBlock: MyBlock,

// Site: supportedBlocks object
myBlock: (props) => <MyBlock data={props} />,

For the target hierarchy, multiple targets, and edge cases, see registration.md.

Step 7 — Create block fixtures

Create a fixture service that generates realistic seed data for the new block.

1. Create the fixture service matching the block type (composite, list, blocks-block, one-of).
2. Wire into the parent block's fixture. If the parent has no fixture, ask the user before creating one.
3. Register in fixtures.module.ts as a provider.
4. For nested list blocks: create the list item fixture service first, then the parent composite fixture which injects and calls it.

For faker guidelines, patterns by block type, and full examples, see fixtures.md.

Naming conventions

The name parameter in createBlock, createCompositeBlock, createListBlock, createBlocksBlock, and createOneOfBlock is PascalCase without a "Block" suffix and must be identical across all layers.

Cross-references