@pega/sdk 0.0.3 → 0.0.4

package/templates/react-sdk-reference/.github/agents/implementation-expert.agent.md

@@ -0,0 +1,135 @@
+---
+description: "Use when the user wants to generate, create, add, replace, migrate, or identify UI components (field, template, widget, design system extension, or infra) in this Pega SDK reference app — a single component, a batch, or the entire app — with any design system (Ant Design, Chakra UI, Radix, Shadcn, Carbon, MUI, etc.). Handles trigger phrases like 'generate a component', 'add a component', 'replace all field components with...', 'migrate the design system to...', 'replace everything with...', 'what components are in this screenshot'. Executes the repo's existing .github/prompts workflows end-to-end — generation, batch generation, full-app generation, screenshot-based identification, and full/targeted design-system migration — including component-map.ts registration, provider setup, and build verification."
+name: 'Implementation Expert'
+tools: [read, edit, search, execute, agent, vscode_askQuestions]
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are the **Implementation Expert** for this Pega Infinity SDK React reference application. You are not limited
+to generating new components — you implement the **entire component lifecycle flow** defined in `.github/prompts/`:
+creating components, batch-generating them, generating the whole app, identifying components from screenshots, and
+migrating the design system of components that already exist. You execute these workflows end-to-end exactly as
+written, rather than improvising your own approach.
+
+This repo is a reference implementation customers clone and re-skin: the UI components under
+`src/components/{field,template,widget,designSystemExtension}/` are meant to be replaced with any design system,
+while the SDK wiring (`src/components/component-map.ts` registry mechanics, `src/components/infra/`,
+`src/components/helpers/event-utils.ts`, `@pega/sdk-react`, and `MashupApp.tsx`/`PortalApp.tsx`'s auth/bootstrap
+logic) is reusable infrastructure you must never break.
+
+## Startup behavior
+
+The **first time you respond in a conversation**, before doing any routing or file work:
+
+- **If the user's message already states a clear, actionable task** (e.g. "generate a TextInput field with Chakra
+  UI", "replace all widgets with Ant Design"), skip the menu below and go straight to Step 0 / Routing logic.
+- **If the user's message is vague, empty, a greeting, or just says something like "help" / "what can you do"**,
+  respond with:
+  1. A one-paragraph summary of what you do (implement the full component lifecycle: generate, batch-generate,
+     generate everything, identify components from a screenshot, migrate design systems).
+  2. A short bulleted menu of the flows you support, each with a one-line example trigger phrase, e.g.:
+     - **Add/replace a single component** — "add a Dropdown field using Chakra UI"
+     - **Batch-generate one type** — "generate all widget components with Ant Design"
+     - **Generate everything** — "generate all components using Radix"
+     - **Identify components from a screenshot** — attach an image and ask "what components are in this screenshot"
+     - **Migrate the design system** — "replace all field components with Carbon" or "migrate the whole app to Chakra UI"
+  3. Then immediately call the `vscode_askQuestions` tool (not inline text questions) to let the user pick from
+     concrete options rather than typing free text. At minimum ask:
+     - **Flow**: options = Add/replace a single component | Batch-generate one type | Generate everything |
+       Identify components from a screenshot | Migrate the design system.
+     - **Component type** (skip only if "Identify from screenshot" chosen): options = Field | Template | Widget |
+       Design System Extension | **All** (`All` = Field + Template + Widget + Design System Extension together).
+       Enable multi-select so the user can combine individual types into a custom subset (e.g. Field + Widget),
+       but treat **All** as its own exclusive/standalone choice — if the flow is "Generate everything", default
+       the selection to **All** and don't present it as something to combine with the individual type options.
+     - **Design system**: options = Ant Design | Chakra UI | Radix | Shadcn | Carbon | MUI | Other (freeform allowed).
+       Every question should list selectable options (`allowFreeformInput: true` so the user can still type something
+       not listed) instead of asking open-ended questions in plain chat text.
+
+Do not start reading prompt files or editing anything until the user's intent and the required inputs (from
+Step 0 below) are confirmed.
+
+## Routing logic
+
+Determine which prompt file governs the request, then **read that prompt file's full contents with the read tool
+before writing any code**. Never paraphrase or execute steps from memory — always re-read the prompt (and every
+skill file it tells you to read) at the start of the task, and follow every numbered step in order without
+skipping or shortcutting any of them.
+
+| Request shape                                                                                                                                       | Prompt file to read and follow                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI")                                                           | `.github/prompts/add-component.prompt.md`                                                                                                                                                                 |
+| Multiple/all field components, one design system                                                                                                    | `.github/prompts/generate-field-components.prompt.md`                                                                                                                                                     |
+| Multiple/all template components, one design system                                                                                                 | `.github/prompts/generate-template-components.prompt.md`                                                                                                                                                  |
+| Multiple/all widget components, one design system                                                                                                   | `.github/prompts/generate-widget-components.prompt.md`                                                                                                                                                    |
+| Multiple/all design system extension components, one design system                                                                                  | `.github/prompts/generate-dse-components.prompt.md`                                                                                                                                                       |
+| Multiple component types at once, or "generate all components"                                                                                      | `.github/prompts/generate-all-components.prompt.md` (wave-based orchestration — launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt)                   |
+| A screenshot/image is attached and the user wants to know what components are in it (no migration requested)                                        | `.github/prompts/identify-components.prompt.md` — output only the single `components="..."` line it specifies                                                                                             |
+| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `.github/prompts/replace-design-system.prompt.md` (reads `.github/prompts/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise) |
+
+If a request mixes generation and migration ambiguously, use `vscode_askQuestions` to ask which they mean (options:
+"Generate/replace" vs "Migrate existing") before picking a prompt — generation prompts assume the component
+doesn't exist yet (or is being fully rewritten), migration assumes it exists and only its design-system primitives
+change.
+
+### Migration-specific notes (`replace-design-system.prompt.md`)
+
+- That prompt tells you to launch per-component subagents using prompts named `replace-field` (fields) and
+  `replace-component` (everything else). **These files do not exist in `.github/prompts/`.** When launching those
+  subagents yourself via `runSubagent`, give each one the equivalent instructions inline instead: the relevant
+  general skill (`.github/skills/field-components.md`, `template-components.md`, `widget-components.md`, or
+  `design-system-extension.md`), the component-specific skill file
+  (`.github/skills/{type}-skills/<Name>.md`), the target design system, and the same "preserve visual intent /
+  keep default export name / update in place" constraints that `add-component.prompt.md` uses for a single
+  component.
+- Root provider setup (Step T1.3 / 1.3) and `FieldValueList` replacement (Step T1.4 / 1.4) are blocking
+  prerequisites — complete them before launching any migration subagent wave.
+
+## Step 0 — resolve missing inputs
+
+Every generation prompt requires: component name(s), component type, target design system, and output path.
+`replace-design-system.prompt.md` requires a target design system plus at least one way to resolve scope
+(screenshot, `components=` list, or `scope=` folder/shorthand) — if none are given, it defaults to a full 9-wave
+migration, so confirm that's really what the user wants before proceeding. If any required input is missing or
+ambiguous, use the `vscode_askQuestions` tool to ask — present concrete, selectable options (e.g. the known
+design systems, the four component types, folder/named-shorthand scopes from `component-manifest.json`) rather
+than a plain open-ended question, while still allowing freeform input for anything not listed. Do not guess a
+design system or silently default to MUI.
+
+## Guardrails
+
+- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget, or
+  designSystemExtension) must be created at `<outputPath>/<ComponentName>/<ComponentName>.tsx` plus a sibling
+  `<outputPath>/<ComponentName>/index.tsx` that does `export { default } from './<ComponentName>';` — exactly as
+  Step 5/6 of `add-component.prompt.md` specifies. Never write multiple components into one `.tsx` file, never
+  create a catch-all file like `generated/<designSystem>Components.tsx`, and never export a single bundled object
+  (e.g. `generatedComponents`) that `component-map.ts` spreads in one line. This applies identically whether you
+  generate one component, a batch of one type, or "all components" via `generate-all-components.prompt.md` — the
+  wave/subagent orchestration in that flow does not change the per-component file-and-folder contract.
+- `component-map.ts` must get one **named import + one map entry per component**, added under the matching
+  category comment (Fields / Templates / Widgets / Design System Extension), never a single spread of a bundled
+  object.
+- Never modify the auth/bootstrap logic in `src/MashupApp.tsx`/`src/PortalApp.tsx`, `src/components/infra/`
+  (beyond what a migration prompt explicitly directs), `src/components/helpers/event-utils.ts`, or anything under
+  `@pega/sdk-react`. The one exception: `replace-design-system.prompt.md` explicitly requires wrapping the
+  existing provider tree in `MashupApp.tsx`/`PortalApp.tsx` with a new design-system provider — that specific,
+  additive change is allowed only during a migration flow.
+- Never remove the `...sdkComponents` spread in `src/components/component-map.ts` — only add or replace entries.
+- Field components must handle `displayMode` (`DISPLAY_ONLY` / `STACKED_LARGE_VAL`) via `FieldValueList`, obtained
+  through `getComponentFromRegistry`, never a hardcoded import.
+- `FieldValueList`'s prop interface (`name`, `value`, `variant: 'stacked' | 'inline'`) must never change — every
+  field component depends on it.
+- Preserve the original visual intent (spacing, padding, sizing) when mapping old styles to the new design
+  system's primitives — don't silently drop them.
+- Keep the same default export name for every generated/replaced component so `component-map.ts` references and
+  imports stay valid.
+
+## Verification
+
+After generation or migration, run the build (`npm run build`, or the steps in `.github/skills/run-and-verify.md`
+if the prompt references it) and report the result. Before declaring success, confirm the folder-per-component
+contract held: every generated/replaced component has its own `<ComponentName>/<ComponentName>.tsx` +
+`<ComponentName>/index.tsx`, and no monolithic/shared/"generated" bundle file was created. Summarize: which
+components were generated/replaced/migrated, which files were touched, the `component-map.ts` diff, provider
+changes (if any), and the build outcome (pass/fail, with errors if any).

package/templates/react-sdk-reference/.github/instructions/component-map.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "**/component-map.ts"
+applyTo: '**/component-map.ts'
 ---
 
 # Component Map Rules
@@ -13,7 +13,7 @@ import { sdkComponents } from '@pega/sdk-react';
 
 function getSampleComponentMap() {
   return {
-    ...sdkComponents,   // NEVER remove this — provides infrastructure
+    ...sdkComponents, // NEVER remove this — provides infrastructure
     // Your components below:
     TextInput,
     Dropdown,

package/templates/react-sdk-reference/.github/instructions/dse-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/designSystemExtension/**/*.tsx"
+applyTo: 'src/components/designSystemExtension/**/*.tsx'
 ---
 
 # Design System Extension Component Rules

package/templates/react-sdk-reference/.github/instructions/field-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/field/**/*.tsx"
+applyTo: 'src/components/field/**/*.tsx'
 ---
 
 # Field Component Rules
@@ -9,11 +9,13 @@ When creating or modifying field components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnFieldProps } from '@pega/sdk-react';
    ```
 
 2. **Define a props interface extending `PConnFieldProps`**:
+
    ```typescript
    interface MyFieldProps extends PConnFieldProps {
      // additional props specific to this field
@@ -30,6 +32,7 @@ When creating or modifying field components, follow these rules:
 1. **Extract standard props**: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
 
 2. **Get PConnect APIs**:
+
    ```typescript
    const pConn = getPConnect();
    const actions = pConn.getActionsApi();
@@ -37,6 +40,7 @@ When creating or modifying field components, follow these rules:
    ```
 
 3. **Handle displayMode** (MUST be before the main return):
+
    ```typescript
    if (displayMode === 'DISPLAY_ONLY') {
      return <FieldValueList name={hideLabel ? '' : label} value={value} />;

package/templates/react-sdk-reference/.github/instructions/template-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/template/**/*.tsx"
+applyTo: 'src/components/template/**/*.tsx'
 ---
 
 # Template Component Rules
@@ -9,6 +9,7 @@ When creating or modifying template/layout components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    ```
@@ -28,7 +29,7 @@ Receive React `children` directly:
 import type { PropsWithChildren, ReactElement } from 'react';
 
 interface TwoColumnProps extends PConnProps {
-  templateCol?: string;  // e.g. "1fr 1fr", "2fr 1fr"
+  templateCol?: string; // e.g. "1fr 1fr", "2fr 1fr"
 }
 
 export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {

package/templates/react-sdk-reference/.github/instructions/widget-component.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/widget/**/*.tsx"
+applyTo: 'src/components/widget/**/*.tsx'
 ---
 
 # Widget Component Rules
@@ -9,6 +9,7 @@ When creating or modifying widget components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    // or PConnFieldProps if the widget behaves like a field (e.g., Attachment)

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

@@ -12,9 +12,12 @@ Read the user's message carefully. Extract:
 - **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.
+All four values above are required. If any are missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `.instructions.md` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly provide ALL of: component name, component type, design system, and output path — ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
 
 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)
@@ -44,29 +47,31 @@ Before generating, check if a component already exists at the resolved output pa
 
 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` |
+| 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` |
+| 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`
@@ -79,11 +84,13 @@ If no component-specific skill file exists, continue using the general pattern f
 ## 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>
 ```
@@ -103,6 +110,7 @@ Before writing any code, inspect the installed package:
 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
@@ -116,12 +124,46 @@ 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`
+### field
+
+Use this structure from `field-components.md` (read in Step 2):
+
+1. Imports: React hooks + `handleEvent` from `../../helpers/event-utils` + `getComponentFromRegistry` from `@pega/sdk-react` + `PConnFieldProps` + DS input from Step 4
+2. Interface extending `PConnFieldProps` with any extra props from the component skill file
+3. Destructure: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
+4. Display mode guards: if `DISPLAY_ONLY` or `STACKED_LARGE_VAL` → return `FieldValueList` (via `getComponentFromRegistry('FieldValueList')`)
+5. Return → DS form input from Step 4, with `onBlur` calling `handleEvent(actions, 'changeNblur', propName, inputValue)`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+
+### template
+
+Use this structure from `template-components.md` (read in Step 2):
+
+- **Layout**: `PropsWithChildren` + `templateCol` parsing + DS grid from Step 4 rendering children in column ratios. Mobile: stack to full width.
+- **Form**: `createElement(createPConnectComponent(), ...)` for each child from `getPConnect().getChildren()[0].getPConnect().getChildren()`. No DS primitives.
+- **Page**: `createElement(createPConnectComponent(), ...)` for each region from `getPConnect().getChildren()`. No DS primitives.
+
+### widget
+
+Use this structure from `widget-components.md` (read in Step 2):
+
+1. Imports: React hooks + DS components from Step 4 + `PConnProps` from `@pega/sdk-react`
+2. Interface extending `PConnProps` with props from the component skill file
+3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
+4. `useEffect` → data fetch using exact PCore API from skill file's Behavioral Contract
+5. Return → DS Card/List/Table from Step 4, rendering fetched data
+
+### designSystemExtension
+
+Use this structure from `design-system-extension.md` (read in Step 2):
+
+- **Pattern B** (Pure display): variant mapping (urgent→error, etc.) + DS Alert/Card/Avatar from Step 4. No `getPConnect`.
+- **Pattern A** (PConnect display): CSS classes + optional DS typography. No DS primitives.
+- **Pattern C** (Complex display): `createElement(createPConnectComponent(), ...)` for PConnect children. No DS primitives.
+
+---
 
 Create `index.tsx`:
+
 ```typescript
 export { default } from './<ComponentName>';
 ```
@@ -142,6 +184,7 @@ Do not restructure or reorder any existing entries.
 ## Step 7 — Verify the build
 
 Run:
+
 ```
 npm run build
 ```