@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.github/copilot-instructions.md

@@ -183,3 +183,61 @@ import handleEvent from '../../helpers/event-utils';
 - Remove the `...sdkComponents` spread from `component-map.ts`.
 - Use `any` without justification — prefer `unknown` and narrow.
 - Add `@ts-ignore` — use `@ts-expect-error` with explanation if truly needed.
+
+---
+
+## 9. Component Generation Workflow — Single Component
+
+When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
+read the full contents of `.github/prompts/add-component.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> For generating **multiple field components** at once, see Section 10.
+
+---
+
+## 10. Batch Field Component Generation
+
+When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
+read the full contents of `.github/prompts/generate-field-components.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 11. Batch Template Component Generation
+
+When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
+read the full contents of `.github/prompts/generate-template-components.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 12. Batch Widget Component Generation
+
+When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
+read the full contents of `.github/prompts/generate-widget-components.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 13. Batch Design System Extension Component Generation
+
+When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
+read the full contents of `.github/prompts/generate-dse-components.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+---
+
+## 14. Generate All Components (Multi-Type)
+
+When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
+read the full contents of `.github/prompts/generate-all-components.prompt.md` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> Use this section when the request spans more than one component type. For a single type, use Sections 10–13.

package/templates/react-sdk-reference/.github/prompts/add-component.prompt.md

@@ -3,19 +3,147 @@ agent: agent
 description: Add a new component type to the registry
 ---
 
-Add a new component called `{{componentName}}` of type **{{componentType}}** (field | template | widget | designSystemExtension).
-
-## Steps:
-
-1. Create the component directory: `src/components/{{componentType}}/{{componentName}}/`
-2. Create `{{componentName}}.tsx` with the appropriate pattern:
-   - **field**: Extend `PConnFieldProps`, use `handleEvent`, handle `displayMode`
-   - **template**: Extend `PConnProps`, render children via grid/layout
-   - **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
-   - **designSystemExtension**: Pure display props or extend `PConnProps`
-3. Create `index.tsx` with: `export { default } from './{{componentName}}';`
-4. Register in `src/components/component-map.ts`:
-   - Add import at top
-   - Add entry in the appropriate section of `getSampleComponentMap()`
-
-Ensure the build passes after adding the component.
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component name** — the exact name (e.g. `AutoComplete`, `DatePicker`)
+- **Component type** — one of: `field` | `template` | `widget` | `designSystemExtension`
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output path** — the exact or relative path where the component should be generated (e.g. `src/components/field/AutoComplete`)
+
+If any of the four are missing or ambiguous, ask the user all unresolved items in **one numbered list** and wait for their answers before continuing. Do not guess or proceed with assumptions.
+
+Example questions to ask (only ask the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is the exact component name?
+3. What type of component is this? (field / template / widget / designSystemExtension)
+4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
+
+### Case-insensitive component name matching
+
+The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `.github/skills/field-skills/`, `.github/skills/template-skills/`, `.github/skills/widget-skills/`, and `.github/skills/design-system-extension-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+
+Once all four are known, continue to Step 1.
+
+---
+
+## Step 1 — Check for existing component (overwrite check)
+
+Before generating, check if a component already exists at the resolved output path:
+
+1. Check if `<outputPath>/<ComponentName>.tsx` (or the directory) already exists.
+2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - If the user says **yes**, proceed to overwrite.
+   - If the user says **no**, stop and skip generation.
+3. If it **does not exist**, continue to Step 2.
+
+---
+
+## Step 2 — Check for skill files
+
+Always read the **general type skill** for the component type:
+
+| Component Type | General Skill File |
+|---|---|
+| `field` | `.github/skills/field-components.md` |
+| `template` | `.github/skills/template-components.md` |
+| `widget` | `.github/skills/widget-components.md` |
+| `designSystemExtension` | `.github/skills/design-system-extension.md` |
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type | Specific Skill Location |
+|---|---|
+| `field` | `.github/skills/field-skills/<ComponentName>.md` |
+| `template` | `.github/skills/template-skills/<ComponentName>.md` |
+| `widget` | `.github/skills/widget-skills/<ComponentName>.md` |
+| `designSystemExtension` | `.github/skills/design-system-extension-skills/<ComponentName>.md` |
+
+If the component-specific skill file exists, read it fully. Pay special attention to:
+- **Behavioral Contract** — state management, event handling, option loading, edge cases
+- **Design System Mapping** table — the recommended component for the chosen design system
+
+You must read **both** the general type skill and the component-specific skill (if it exists) before proceeding.
+
+Examples:
+- `AutoComplete` (field) → read `field-components.md` + `field-skills/AutoComplete.md`
+- `AdvancedSearch` (template) → read `template-components.md` + `template-skills/AdvancedSearch.md`
+- `AppAnnouncement` (widget) → read `widget-components.md` + `widget-skills/AppAnnouncement.md`
+- `AlertBanner` (designSystemExtension) → read `design-system-extension.md` + `design-system-extension-skills/AlertBanner.md`
+
+If no component-specific skill file exists, continue using the general pattern from the type skill.
+
+---
+
+## Step 3 — Check and install dependencies
+
+Run:
+```
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+```
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+---
+
+## Step 4 — Discover the design system's API
+
+Before writing any code, inspect the installed package:
+
+1. `cat node_modules/<designSystem>/README.md` — note the correct import path and usage patterns for the installed version.
+2. `grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"` — lists every component actually exported by the installed version.
+3. For every component you plan to use, read its TypeScript prop interface from the installed `.d.ts`:
+   `find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3`, then `grep -A 40 "interface.*Props"` on the result.
+4. Only use component names and prop names confirmed in those files. Do not rely on training knowledge of the API.
+
+Also check:
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+---
+
+## Step 5 — Generate the component
+
+Create the component directory at the resolved output path (from Step 0).
+
+Create `<ComponentName>.tsx` using the pattern for the component type:
+
+- **field**: Extend `PConnFieldProps` from `@pega/sdk-react`. Extract `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`. Call `handleEvent(actions, 'changeNblur', propName, value)` on blur. Handle `displayMode === 'DISPLAY_ONLY'` and `'STACKED_LARGE_VAL'` using `getComponentFromRegistry('FieldValueList')`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+- **template**: Extend `PConnProps`, render children via the design system's grid/layout primitives
+- **widget**: Extend `PConnProps`, fetch data via `PCore.getDataPageUtils()`
+- **designSystemExtension**: Pure display props or extend `PConnProps`
+
+Create `index.tsx`:
+```typescript
+export { default } from './<ComponentName>';
+```
+
+---
+
+## Step 6 — Register in component-map.ts
+
+Edit `src/components/component-map.ts`:
+
+1. Add the import at the top of the file, in the correct section (Fields / Templates / Widgets / Design System Extension)
+2. Add an entry in `getSampleComponentMap()` under the matching category comment
+
+Do not restructure or reorder any existing entries.
+
+---
+
+## Step 7 — Verify the build
+
+Run:
+```
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report what files were created and what was added to `component-map.ts`.

package/templates/react-sdk-reference/.github/prompts/generate-all-components.prompt.md

@@ -0,0 +1,154 @@
+---
+agent: agent
+description: Generate components across multiple types (field, template, widget, designSystemExtension) using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Base components folder** — the root folder that contains (or will contain) the component type subfolders (e.g. `src/components/`)
+- **Component types in scope** — which types to generate (default: all four if not specified)
+
+Both **design system** and **base components folder** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the base folder — the client's folder structure may differ.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, and `designSystemExtension/` will be used under it.
+
+### Component type scope
+
+Extract which types the user wants from the message:
+
+| User says | Types in scope |
+|---|---|
+| "generate all components" | field + template + widget + designSystemExtension |
+| "generate field and widget components" | field + widget |
+| "generate widget, template components" | widget + template |
+| "generate all components except templates" | field + widget + designSystemExtension |
+| "replace everything" | field + template + widget + designSystemExtension |
+
+Default to **all four types** if the message does not restrict the scope.
+
+### Derived output paths
+
+Once the base folder is known, derive the output path for each type in scope:
+
+| Type | Derived path |
+|---|---|
+| field | `<base>/field/` |
+| template | `<base>/template/` |
+| widget | `<base>/widget/` |
+| designSystemExtension | `<base>/designSystemExtension/` |
+
+Once design system, base folder, and type scope are resolved, continue to Step 1.
+
+---
+
+## Step 1 — Read general skill files (once, for each type in scope)
+
+Read the general skill file for every type in scope. Do this upfront — do not re-read per component.
+
+| Type | Skill file to read |
+|---|---|
+| field | `.github/skills/field-components.md` |
+| template | `.github/skills/template-components.md` |
+| widget | `.github/skills/widget-components.md` |
+| designSystemExtension | `.github/skills/design-system-extension.md` |
+
+Keep all loaded skill files active throughout the entire session.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Read the DS README from `node_modules`
+- Discover all exported components from `dist/index.d.ts`
+- Read prop interfaces for primitives needed across **all types in scope**:
+  - **field**: form input controls (Input, Select, Checkbox, DatePicker, etc.)
+  - **template**: grid/layout primitives (Grid, Flex, Columns, SimpleGrid, etc.)
+  - **widget**: card/list/table/button/badge primitives
+  - **designSystemExtension**: alert/notification/avatar primitives
+- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+
+Build a unified **DS API reference map** covering all types in scope. Reuse it throughout — do not repeat discovery commands per component.
+
+---
+
+## Step 3 — Overwrite check (all types, all at once)
+
+For every type in scope, check whether each component's `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+Collect all existing components across all types and report them in one consolidated list:
+
+> "The following N components already exist across [types]: [list grouped by type]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate field components (skip if field not in scope)
+
+If `field` is in scope, execute **Step 4** from `.github/prompts/generate-field-components.prompt.md` in full:
+- Use the derived field output path: `<base>/field/`
+- The general skill (`field-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS API reference map is already built from Step 2 — do not repeat discovery commands
+- For each of the 27 field components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 5 — Generate template components (skip if template not in scope)
+
+If `template` is in scope, execute **Step 4** from `.github/prompts/generate-template-components.prompt.md` in full:
+- Use the derived template output path: `<base>/template/`
+- The general skill (`template-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS layout API is already discovered from Step 2 — do not repeat discovery commands
+- For each of the 32 template components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 6 — Generate widget components (skip if widget not in scope)
+
+If `widget` is in scope, execute **Step 4** from `.github/prompts/generate-widget-components.prompt.md` in full:
+- Use the derived widget output path: `<base>/widget/`
+- The general skill (`widget-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS UI primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 9 widget components: read skill file → generate → register in `component-map.ts`
+- If no skill file exists for a component (e.g., `SummaryList`), use the general pattern from `widget-components.md`
+- Report progress after each component
+
+---
+
+## Step 7 — Generate design system extension components (skip if DSE not in scope)
+
+If `designSystemExtension` is in scope, execute **Step 4** from `.github/prompts/generate-dse-components.prompt.md` in full:
+- Use the derived DSE output path: `<base>/designSystemExtension/`
+- The general skill (`design-system-extension.md`) is already loaded from Step 1 — do not re-read it
+- The DS display primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 11 DSE components: read skill file → generate → register in `component-map.ts`
+- Apply the Pattern B/A/C branching as specified in the skill file and `design-system-extension.md`
+- Report progress after each component
+
+---
+
+## Step 8 — Verify the build
+
+Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a final summary:
+  - Total components generated, grouped by type
+  - All entries added to `component-map.ts`
+  - Any components skipped (if "skip existing" was chosen in Step 3)

package/templates/react-sdk-reference/.github/prompts/generate-dse-components.prompt.md

@@ -0,0 +1,131 @@
+---
+agent: agent
+description: Generate all (or a subset of) design system extension components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where DSE components should be generated (e.g. `src/components/designSystemExtension/`)
+- **Component list** — which components to generate (default: all 11 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the DSE components be generated? (e.g. `src/components/designSystemExtension/`)
+
+If the user specified a subset (e.g., "just AlertBanner and FieldValueList"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 11 DSE components)
+
+| Component | Pattern | DS needed? |
+|---|---|---|
+| AlertBanner | B — Pure display | Yes |
+| Banner | B — Pure display | Yes |
+| CaseSummaryFields | A — PConnect display | Minimal |
+| DetailsFields | A — PConnect display | Minimal |
+| FieldGroup | C — Complex display | No |
+| FieldGroupList | C — Complex display | No |
+| FieldValueList | A — PConnect display | No (CSS only) |
+| Operator | B — Pure display | Yes |
+| Pulse | C — Complex display | No |
+| RichTextEditor | C — Complex display | No |
+| WssQuickCreate | B — Pure display | Yes |
+
+---
+
+## Step 1 — Read `design-system-extension.md` (once, for the entire session)
+
+Read the full contents of `.github/skills/design-system-extension.md`.
+
+This gives you:
+- All three implementation patterns (Pure display, Field value display, Complex display with PConnect)
+- The `// [DS RENDER]` placeholder approach for Pattern B components
+- The Design System Adaptation section — pattern categorisation, variant mapping table, DS discovery guidance
+- Styling patterns — when to use CSS files vs DS style props
+- Registration conventions
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Read the DS README from `node_modules`
+- Discover exported components from `dist/index.d.ts`
+- Focus on display primitives used by Pattern B components: Alert, Card, Avatar, Badge, Tag, Notification
+- Read prop interfaces for these components from `.d.ts` files
+
+> Pattern A/C components (FieldValueList, FieldGroup, Pulse, etc.) use PConnect bridge or plain CSS — they do not use the DS API. Only Pattern B components consume DS primitives.
+
+Build a **DS display primitive reference map** from this discovery. Reuse it for every Pattern B component — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+> "The following N components already exist: [list]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
+- Read `.github/skills/design-system-extension-skills/<ComponentName>.md` fully
+- Identify the component's pattern (B / A / C) from the skill file
+- Pay attention to:
+  - **Behavioral Contract** — prop handling, variant mapping, rendering logic, edge cases
+  - **Design System Mapping** table — the recommended DS primitive for Pattern B components
+
+### 4b — Generate the component files
+Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - **Pattern B** (Pure display — AlertBanner, Banner, Operator, WssQuickCreate): use DS alert/card/avatar primitive from Step 2 API map in the `// [DS RENDER]` section; apply variant mapping from the skill file
+  - **Pattern A** (PConnect display — CaseSummaryFields, DetailsFields, FieldValueList): use CSS classes or DS typography props; no DS component primitives
+  - **Pattern C** (Complex display — FieldGroup, FieldGroupList, Pulse, RichTextEditor): use PConnect bridge (`createElement(createPConnectComponent(), ...)`); no DS primitives
+- Create `index.tsx` if required by the skill file:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+- Create any CSS file required by the skill file
+
+### 4c — Register the component
+Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
+- Add the import to `src/components/component-map.ts` in the Design System Extension section
+- Add the entry to `getSampleComponentMap()` under the DSE comment
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`

package/templates/react-sdk-reference/.github/prompts/generate-field-components.prompt.md

@@ -0,0 +1,144 @@
+---
+agent: agent
+description: Generate all (or a subset of) field components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where field components should be generated (e.g. `src/components/field/`, `app/ui/fields/`)
+- **Component list** — which components to generate (default: all 27 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the field components be generated? (e.g. `src/components/field/`)
+
+If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default)
+
+| Component | Pega Name |
+|---|---|
+| AutoComplete | AutoComplete |
+| CancelAlert | CancelAlert |
+| Checkbox | Checkbox |
+| Currency | Currency |
+| Date | Date |
+| DateTime | DateTime |
+| Decimal | Decimal |
+| Dropdown | Dropdown |
+| Email | Email |
+| Group | Group |
+| Integer | Integer |
+| Location | Location |
+| Multiselect | Multiselect |
+| ObjectReference | ObjectReference |
+| Percentage | Percentage |
+| Phone | Phone |
+| RadioButtons | RadioButtons |
+| RichText | RichText |
+| ScalarList | ScalarList |
+| SelectableCard | SelectableCard |
+| SemanticLink | SemanticLink |
+| TextArea | TextArea |
+| TextContent | TextContent |
+| TextInput | TextInput |
+| Time | Time |
+| URL | URL |
+| UserReference | UserReference |
+
+---
+
+## Step 1 — Read `field-components.md` (once, for the entire session)
+
+Read the full contents of `.github/skills/field-components.md`.
+
+This gives you:
+- The behavioral skeleton every field component must follow (state, effects, event handling, display modes)
+- The Design System Adaptation guide (prop mapping conventions, form layout wrappers)
+- The abstract template to use as a base for all components
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Read the DS README from `node_modules`
+- Discover all exported components from `dist/index.d.ts`
+- Read prop interfaces for the control types needed across the component list
+- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+
+Build a **DS API reference map** from this discovery. You will reuse it for every component — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+> "The following N components already exist: [list]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
+- Read `.github/skills/field-skills/<ComponentName>.md` fully
+- Pay attention to:
+  - **Behavioral Contract** — state management, option loading, edge cases specific to this component
+  - **Design System Mapping** table — the recommended DS component for the chosen design system
+  - **UI control type** — use this to select the closest DS primitive if the chosen DS is not in the mapping table
+
+### 4b — Generate the component files
+Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - The abstract behavioral skeleton from `field-components.md` (read in Step 1)
+  - The Behavioral Contract from the component skill file
+  - The DS API confirmed in Step 2 (from the DS API reference map — no new terminal commands needed)
+  - Display mode guards (`DISPLAY_ONLY`, `STACKED_LARGE_VAL`) via `getComponentFromRegistry('FieldValueList')`
+  - `data-test-id={testId}` on the underlying interactive element
+- Create `index.tsx`:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+
+### 4c — Register the component
+Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
+- Add the import to `src/components/component-map.ts` in the Fields section
+- Add the entry to `getSampleComponentMap()` under the fields comment
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`