Skip to content

add comet-crud Agent skills#5323

Open
manuelblum wants to merge 12 commits intomainfrom
com-2900/add-crud-skills
Open

add comet-crud Agent skills#5323
manuelblum wants to merge 12 commits intomainfrom
com-2900/add-crud-skills

Conversation

@manuelblum
Copy link
Collaborator

@manuelblum manuelblum commented Mar 16, 2026

Adds a set of agent skills that teach AI coding agents how to generate full-stack CRUD features for Comet DXP projects.

More info about skills are documented in deploy preview: https://deploy-preview-5323.docs.comet-dxp.com/docs/agent-skills/

Skills Overview

  • comet-crud — Orchestrator that composes all other skills to generate a complete CRUD feature end-to-end (API → Enums → DataGrid + Form → Pages → MasterMenu)
  • comet-api-graphql — Generates NestJS/GraphQL CRUD API (service, resolver, DTOs, filters, sort, args)
  • comet-admin-translatable-enum — Creates translatable enum components (chips, form fields, editable chips)
  • comet-admin-datagrid — Generates server-side MUI DataGrid components with Apollo Client
  • comet-admin-form — Generates Final Form components with create/edit/add modes
  • comet-admin-pages — Generates admin page navigation (Stack, StackSwitch, RouterTabs, toolbars)

Features

  • comet-crud (orchestrator)
    • Phases: API → Translatable Enums → DataGrid + Form (parallel) → Admin Pages → MasterMenu
    • Lint/tsc validation after each phase
    • Git commit per phase

when comet-crud triggers the user gets a prompt displayed, the plan can be further tweaked if needed.

Screenshot 2026-03-16 at 11 50 52
  • comet-api-graphql

    • Generated files
      • Service (all business logic)
      • Resolver (thin GraphQL layer)
      • Input DTO, Filter, Sort, Args, Paginated Response, Nested Input
    • Field types
      • Scalars (String, Int, Float, Boolean, Date, DateTime)
      • Enums (with registerEnumType)
      • Relations (ManyToOne, ManyToMany, OneToMany, OneToOne) with decision rules R1–R7
      • Blocks (with @ResolveField)
      • JSON / Embedded types
    • Features
      • Position ordering
      • Validation (class-validator decorators, custom validators)
      • Dedicated resolver arg (for parent-scoped entities)
      • Slug query (unique slug lookup)
      • Scoped entity (content scope filtering)
  • comet-admin-translatable-enum

    • Component types
      • Translatable (base mapping)
      • Chip (colored status chips with configurable colors)
      • Editable Chip (inline edit with Apollo mutation)
      • SelectField
      • AutocompleteField
      • RadioGroupField
      • CheckboxListField
  • comet-admin-datagrid

    • Grid variants
      • Standard paginated (default)
      • Non-paginated
      • Row reordering (drag & drop)
      • Sub-entity (parent-scoped)
      • Select / Checkbox picker
      • Excel export
      • Responsive columns
      • Initial sort/filter
      • External filter prop
      • Content scope
    • Column types
      • String, Boolean, Number, DateTime
      • Enum (chips with filterable select)
      • ManyToOne, ManyToMany, OneToMany
      • Array of Scalars, Nested Objects
      • FileUpload, ID, Relation Filter
    • Toolbar variants
      • Standard
      • Excel Export
      • Row Reordering
      • Select/Picker
  • comet-admin-form

    • Modes: create, edit, add-only
    • Field types
      • String, Text, Number, Boolean, DateTime
      • Enum (Select/Autocomplete/Radio/Checkbox)
      • ManyToOne (AsyncAutocompleteField), ManyToMany
      • Nested Objects, FileUpload, Block, Switch, AsyncSelectField
    • Layout & patterns
      • FieldSet grouping
      • Conditional fields (show/hide based on other field values)
      • Cross-field filtering
      • Input adornments
      • Validation with validators.js
  • comet-admin-pages

    • Page patterns
      • Single page (grid or form only)
      • Grid with EditDialog
      • Grid with edit page (StackSwitch)
      • Edit page with RouterTabs
      • Deeply nested pages
      • useStackSwitch (programmatic navigation)
      • ManyToMany selection tab
    • Toolbar patterns
      • Simple FormToolbar
      • Entity Toolbar (with own query, loading/error states, title display)

Sample Pull Request

Following Pull Request where done by AI via specification of a feature. The different Pull Request should showcase most of the features available and defined in the skill.

Starting from e.g. typically table/form, but also table/edit. different sub features

  • server side form validation
  • client side validation
  • positioning in datagrid
  • multiselect in datagrid
  • ...
Header Header
Product vivid-planet/comet-starter#1344
Product Categories vivid-planet/comet-starter#1345
Product Variant vivid-planet/comet-starter#1346
Product Review vivid-planet/comet-starter#1347
Product Collection vivid-planet/comet-starter#1348

Sometimes AI had some slight problems but resolved them on there own with manually prompting this:

Fix errors

use playwright mcp server to check current implemented feature. If any errors occur fix them.

Possible Improvements of the skills:

  • create fixtures
  • create API Service tests.
  • create storybook stories for components (blocked by: Storybook setup for admin)
  • At the end of implementing - Playwright MCP test and fix bugs which occur
  • create end 2 end tests for playwright to guarantee that nothing breaks in the future (blocked by: end 2 end test setup)

Further info

note: sometimes it is necessary (especially when new permission are generated, that the api needs to restart - not 100% sure why)

- Fix sort variable to use array in grid-02-row-reordering reference
- Change enum field defaults: SelectField (<=4), AutocompleteField (>4), RadioGroupField only on request
- Add useAutocompleteOptions helper reference for translatable enum skill
- Update enum-04-autocomplete-field to point to helper reference instead of "ask the user"
- Add GPG signing fallback hint to comet-crud error recovery
@manuelblum manuelblum marked this pull request as ready for review March 16, 2026 12:53
@auto-assign auto-assign bot requested a review from johnnyomair March 16, 2026 12:53
@johnnyomair johnnyomair requested a review from Copilot March 16, 2026 15:15
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new set of “agent skills” (prompt-based instruction bundles) aimed at teaching AI coding agents how to scaffold full-stack CRUD features for Comet DXP projects, plus corresponding documentation pages listing and describing these skills.

Changes:

  • Introduces a new comet-crud orchestrator skill with a phased workflow (API → enums → grid/form → pages → MasterMenu) and a commit/validation strategy.
  • Adds extensive reference templates for comet-api-graphql, comet-admin-translatable-enum, comet-admin-datagrid, comet-admin-form, and comet-admin-pages.
  • Documents the available skills under docs/docs/11-agent-skills/ and updates cspell ignore list.

Reviewed changes

Copilot reviewed 98 out of 98 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
package-skills/comet-crud/SKILL.md New orchestrator skill instructions and workflow.
package-skills/comet-api-graphql/references/gen-07-service.md Service patterns and rules for generated CRUD services.
package-skills/comet-api-graphql/references/gen-06-nested-input.md Nested input DTO pattern for inline-managed OneToMany children.
package-skills/comet-api-graphql/references/gen-05-paginated.md Paginated response DTO pattern.
package-skills/comet-api-graphql/references/gen-04-args.md Args DTO pattern for list queries.
package-skills/comet-api-graphql/references/gen-03-sort.md Sort DTO/enum pattern and inclusion rules.
package-skills/comet-api-graphql/references/gen-02-filter.md Filter DTO pattern and mapping rules.
package-skills/comet-api-graphql/references/gen-01-input.md Input/UpdateInput DTO pattern and validation rules.
package-skills/comet-api-graphql/references/field-05-json-embedded.md JSON/Embedded field input guidance.
package-skills/comet-api-graphql/references/field-04-block.md Block field input/service/resolver patterns.
package-skills/comet-api-graphql/references/field-03-relation.md Relation field input/filter/sort/service patterns.
package-skills/comet-api-graphql/references/field-02-enum.md Enum input/filter/sort patterns.
package-skills/comet-api-graphql/references/field-01-scalar.md Scalar input/filter/sort patterns.
package-skills/comet-api-graphql/references/feature-04-slug.md Slug query + validation guidance.
package-skills/comet-api-graphql/references/feature-03-dedicated-arg.md Dedicated resolver arg pattern for parent-scoped entities.
package-skills/comet-api-graphql/references/feature-02-validation.md Server-side business validation payload pattern.
package-skills/comet-admin-translatable-enum/references/enum-helper-use-autocomplete-options.md Helper reference for enum autocomplete options hook.
package-skills/comet-admin-translatable-enum/references/enum-helper-record-to-options.md Helper reference for record-to-options conversion.
package-skills/comet-admin-translatable-enum/references/enum-helper-enum-chip.md Helper reference for generic enum chip wrapper.
package-skills/comet-admin-translatable-enum/references/enum-helper-create-translatable-enum.md Helper reference for translatable enum factory.
package-skills/comet-admin-translatable-enum/references/enum-helper-chip-icon.md Helper reference for chip icon component.
package-skills/comet-admin-translatable-enum/references/enum-06-checkbox-list-field.md CheckboxListField generation reference (multi-select enums).
package-skills/comet-admin-translatable-enum/references/enum-05-radio-group-field.md RadioGroupField generation reference.
package-skills/comet-admin-translatable-enum/references/enum-04-autocomplete-field.md AutocompleteField generation reference.
package-skills/comet-admin-translatable-enum/references/enum-03-select-field.md SelectField generation reference.
package-skills/comet-admin-translatable-enum/references/enum-02-editable-chip.md Editable enum chip (query + mutation) generation reference.
package-skills/comet-admin-translatable-enum/references/enum-01-chip.md Non-editable chip generation reference.
package-skills/comet-admin-translatable-enum/references/enum-00-translatable.md Base translatable enum component generation reference.
package-skills/comet-admin-translatable-enum/SKILL.md New skill entrypoint/overview for translatable enum generation.
package-skills/comet-admin-pages/references/toolbar-01-entity.md Entity toolbar pattern reference (with query).
package-skills/comet-admin-pages/references/toolbar-00-simple.md Simple form toolbar reference.
package-skills/comet-admin-pages/references/06-use-stack-switch.md useStackSwitch navigation pattern reference.
package-skills/comet-admin-pages/references/05-deeply-nested.md Deeply nested StackSwitch/RouterTabs pattern reference.
package-skills/comet-admin-pages/references/04-edit-page-with-tabs.md Edit page with RouterTabs pattern reference.
package-skills/comet-admin-pages/references/03-grid-with-edit-page.md Grid + add/edit pages (StackSwitch) pattern reference.
package-skills/comet-admin-pages/references/02-grid-with-dialog.md Grid with edit dialog pattern reference.
package-skills/comet-admin-pages/references/01-single-page.md Single page grid/form pattern reference.
package-skills/comet-admin-pages/SKILL.md New skill entrypoint/overview for admin pages/navigation patterns.
package-skills/comet-admin-form/references/form-pattern-03-validation.md Client-side validation guidance and examples.
package-skills/comet-admin-form/references/form-pattern-02-adornments.md Field adornments guidance and examples.
package-skills/comet-admin-form/references/form-pattern-01-conditional-fields.md Conditional fields / dependent selects guidance.
package-skills/comet-admin-form/references/form-layout-01-fieldset.md FieldSet layout guidance.
package-skills/comet-admin-form/references/form-field-13-async-select.md AsyncSelectField (dropdown relation) guidance.
package-skills/comet-admin-form/references/form-field-12-switch.md SwitchField guidance.
package-skills/comet-admin-form/references/form-field-11-block.md CMS block field integration guidance.
package-skills/comet-admin-form/references/form-field-10-file-upload.md File upload field guidance and fragment conventions.
package-skills/comet-admin-form/references/form-field-09-nested-object.md Nested scalar object (dot notation) guidance.
package-skills/comet-admin-form/references/form-field-08-many-to-many.md ManyToMany field guidance.
package-skills/comet-admin-form/references/form-field-07-many-to-one.md ManyToOne AsyncAutocompleteField reusable component guidance.
package-skills/comet-admin-form/references/form-field-06-enum.md Enum field guidance (reuse generated enum fields).
package-skills/comet-admin-form/references/form-field-05-datetime.md Date/DateTime field guidance and transformations.
package-skills/comet-admin-form/references/form-field-04-boolean.md CheckboxField guidance.
package-skills/comet-admin-form/references/form-field-03-number.md Number field guidance incl. currency adornments.
package-skills/comet-admin-form/references/form-field-02-text.md TextAreaField guidance.
package-skills/comet-admin-form/references/form-field-01-string.md TextField guidance.
package-skills/comet-admin-datagrid/references/grid-toolbar-03-select.md Toolbar reference for picker/select grids.
package-skills/comet-admin-datagrid/references/grid-toolbar-02-row-reordering.md Toolbar reference for row reordering grids.
package-skills/comet-admin-datagrid/references/grid-toolbar-01-excel-export.md Toolbar reference including Excel export action.
package-skills/comet-admin-datagrid/references/grid-toolbar-00-standard.md Standard toolbar reference (search/filter/add).
package-skills/comet-admin-datagrid/references/grid-col-def-13-relation-filter.md Relation filter operator/component reference.
package-skills/comet-admin-datagrid/references/grid-col-def-12-id.md ID column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-11-file-upload.md FileUpload + DAM image column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-10-nested-object.md Nested object column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-09-array-of-scalars.md Array-of-scalars column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-08-one-to-many.md OneToMany column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-07-many-to-many.md ManyToMany column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-06-many-to-one.md ManyToOne column reference (with relation filter operators).
package-skills/comet-admin-datagrid/references/grid-col-def-05-enum.md Enum column reference (chip + valueOptions).
package-skills/comet-admin-datagrid/references/grid-col-def-04-datetime.md Date/DateTime column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-03-number.md Number/currency column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-02-boolean.md Boolean column reference.
package-skills/comet-admin-datagrid/references/grid-col-def-01-string.md String column reference.
package-skills/comet-admin-datagrid/references/grid-09-content-scope.md Content scope grid feature reference.
package-skills/comet-admin-datagrid/references/grid-08-external-filter-prop.md External filter prop feature reference.
package-skills/comet-admin-datagrid/references/grid-07-initial-sort-filter.md Initial sort/filter feature reference.
package-skills/comet-admin-datagrid/references/grid-06-responsive-columns.md Responsive columns feature reference.
package-skills/comet-admin-datagrid/references/grid-05-excel-export.md Excel export feature reference.
package-skills/comet-admin-datagrid/references/grid-04-select.md Select/checkbox grid variant reference.
package-skills/comet-admin-datagrid/references/grid-03-sub-entity.md Sub-entity grid variant reference (parent ID required).
package-skills/comet-admin-datagrid/references/grid-02-row-reordering.md Row reordering grid variant reference.
package-skills/comet-admin-datagrid/references/grid-01-non-paginated.md Non-paginated grid variant reference.
package-skills/comet-admin-datagrid/SKILL.md New skill entrypoint/overview for DataGrid generation.
docs/docs/11-agent-skills/index.md Adds Agent Skills overview page and list of available skills.
docs/docs/11-agent-skills/2-comet-crud/index.md Adds detailed documentation page for comet-crud.
docs/docs/11-agent-skills/2-comet-crud/5-comet-admin-pages.md Adds documentation page for comet-admin-pages.
docs/docs/11-agent-skills/2-comet-crud/4-comet-admin-form.md Adds documentation page for comet-admin-form.
docs/docs/11-agent-skills/2-comet-crud/3-comet-admin-datagrid.md Adds documentation page for comet-admin-datagrid.
docs/docs/11-agent-skills/2-comet-crud/2-comet-admin-translatable-enum.md Adds documentation page for comet-admin-translatable-enum.
docs/docs/11-agent-skills/2-comet-crud/1-comet-api-graphql.md Adds documentation page for comet-api-graphql.
.cspellignore Adds datagrid to the spellchecker ignore list.

You can also share your feedback on Copilot code review. Take the survey.

Comment on lines +78 to +80
interface FormValues {
status: LocationStatusFormState;
}
Comment on lines +29 to +32
type {EnumName}AutocompleteFieldProps = Omit<
AutocompleteFieldProps<{EnumName}AutocompleteFieldOption, false, false, false>,
"options" | "getOptionLabel"
>;
Comment on lines +31 to +38
export const update{EntityName}{EnumName}Mutation = gql`
mutation Update{EntityName}{EnumName}($id: ID!, ${enumFieldName}: {EnumName}!) {
{updateMutation}(id: $id, input: { {enumFieldName}: ${enumFieldName} }) {
id
{enumFieldName}
}
}
`;
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Copy link
Contributor

Copilot AI commented Mar 16, 2026

@manuelblum I've opened a new pull request, #5324, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Contributor

Copilot AI commented Mar 16, 2026

@manuelblum I've opened a new pull request, #5325, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Contributor

Copilot AI commented Mar 16, 2026

@manuelblum I've opened a new pull request, #5326, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI and others added 2 commits March 16, 2026 18:27
…electFieldProps (#5326)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
…array form state (#5324)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
Copy link
Contributor

Copilot AI commented Mar 16, 2026

@manuelblum I've opened a new pull request, #5327, to work on those changes. Once the pull request is ready, I'll request review from you.

Copy link
Contributor

Copilot AI commented Mar 16, 2026

@manuelblum I've opened a new pull request, #5328, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot AI and others added 2 commits March 16, 2026 21:04
…ld skill reference (#5325)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: manuelblum <6098356+manuelblum@users.noreply.github.com>
@manuelblum manuelblum requested a review from thomasdax98 March 17, 2026 09:57
## What It Does

1. **API Entity & GraphQL** — generates the MikroORM entity, service, resolver, DTOs, and module registration (via `comet-api-graphql`)
2. **Translatable Enums** — generates translation components and form fields for any enums used by the entity (via `comet-admin-translatable-enum`)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This subskill seems too niche to me. Is this something that's commonly used/needed in projects?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code it produces seems a bit overkill to me as well (reviewed the common components in vivid-planet/comet-starter#1344).

sidebar_position: 1
---

The `comet-api-graphql` skill generates the NestJS/GraphQL API layer for a MikroORM entity. It follows the Comet convention of **thin resolvers** (GraphQL layer only) and **fat services** (all business logic).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is something we'll have to discuss, as it isn't the Comet convention (yet): https://docs.comet-dxp.com/docs/coding-guidelines/api-nestjs#service-best-practices.

- If lint fails: fix the issues automatically, re-run lint, then commit
- If tsc fails: read the errors, fix the source files, re-run tsc, then commit
- If a skill produces unexpected output: read the generated files, compare against the skill's reference docs, and fix
- If committing fails due to GPG signing issues: retry with `-c commit.gpgsign=false`
Copy link
Collaborator

@johnnyomair johnnyomair Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems specific to our setup with 1Password, should this be in the skill?

## Prerequisites

1. **Read the GraphQL schema** for the target entity to determine: list query signature (`filter`, `limit`, `offset`, `search`, `sort`), paginated return type, available fields, and whether a `deleteXxx` mutation exists.
2. **Check MUI DataGrid package** in `admin/package.json` — use `DataGridPro` unless `DataGridPremium` is already used or requested.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should use the version that's available, not enforce DataGridPro


1. **Read the entity file** (if it exists) to extract: class name, all properties with their MikroORM/GraphQL decorators, and relation types.
2. **Determine scope mode** — Most entities in this project are scoped. If the entity file exists, read it to determine the mode from its decorators. If working from a user description and scope is not mentioned, **ask the user** before proceeding — do not assume no scope.
- (a) `@ScopedEntity` with callback → **preferred** — entity has flat scope fields (`domain`, `language`) and `@ScopedEntity((row) => ({ domain: row.domain, language: row.language }))`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be discussed as well, for content-driven projects we usually have a scope field.

@johnnyomair
Copy link
Collaborator

Please move the skill to skills/ and use the dx-* convention.

@nsams nsams self-requested a review March 18, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants