Platform Lightning Type Widget Coordinate

Building a Lightning Type With a Widget

Coordinate Lightning Type, Apex class, and HXL widget generation across the two paths below. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.

Scope

Apex-backed Lightning Types only — root lightning:type of the form @apexClassType/<namespace>__<ClassName> (outer class). The class itself carries the @AuraEnabled fields that define the payload shape; nested list-element types live as inner classes referenced by List<Inner> fields on the outer class. Object/JSON-based Lightning Types (root lightning__objectType with primitive properties) are out of scope; route those to platform-custom-lightning-type-generate and platform-widget-generate separately.

---

Phase Graph

Per-phase pattern:

---

Phase 1 — Path selection

Determine the path from the user prompt and pick the corresponding leaf-skill load order:

If the prompt names no Lightning Type at all (just a widget against prompt-provided fields or sample data), this orchestrator should not have been triggered — route the user to platform-widget-generate directly.

If the prompt is ambiguous between the two paths, ask one clarifying question max and pick. The new-lightning-type-with-widget path's platform-apex-generate step is engaged automatically — do not prompt the user to confirm Apex.

---

Phase 2 — Lightning Type discovery (existing-lightning-type-with-widget only)

Skipped for new-lightning-type-with-widget (the Lightning Type does not yet exist).

For existing-lightning-type-with-widget, FIRST Read references/lightning-type-discovery.md (REQUIRED — do NOT skip; do not run Phase 2 from this summary alone), then execute its find → verify → ensure-class procedure step by step. The bullets below are a reminder, not a substitute for the reference:

• Local project first: search force-app/**/lightningTypes/<TypeName>/schema.json.
• If not found, run sf project retrieve --metadata LightningTypeBundle:<TypeName> against the connected org.
• If multiple candidates surface, list them with FQNs and paths. Ask the user to pick.
• After locating the schema, verify it is in scope (root lightning:type starts with @apexClassType/). If the type is object/JSON-based, surface that and stop.
• Ensure the backing Apex class is in the local project. Parse <ClassName> from the @apexClassType/<ns>__<ClassName> root. If <pkgDir>/classes/<ClassName>.cls is absent, run sf project retrieve --metadata ApexClass:<ClassName>. This runs whether the Lightning Type was found locally or retrieved from the org — a locally-present Lightning Type can still reference an absent class. If the class exists nowhere, surface it and stop (the type is unrenderable). See the reference for the full procedure.
• If retrieval fails, surface the CLI error and offer: (a) ask the user to run retrieve manually and re-run, or (b) downgrade to new-lightning-type-with-widget if appropriate. Never silently downgrade.
• If retrieval finds nothing, prompt the user to confirm flipping to new-lightning-type-with-widget before continuing.

Capture the Lightning Type schema.json SHA-256 and the Apex class FQN (parsed from @apexClassType/...) at the end of this phase. The Phase 5 lightning-type-unchanged gate compares the SHA against the on-disk SHA at end of Phase 4 to enforce no silent schema edits.

Staleness: do NOT maintain a cross-session cache. Always read the local project fresh and always re-retrieve from the org per session.

---

Phase 3 — Build plan + approval gate

Print a build plan using the template in references/build-plan-format.md. The plan must list:

• A one-line developer-facing summary of what will be built (the PLAN: line in the template).
• Lightning Type name and source (existing in local project · retrieved from org · newly created), plus the Apex class FQN it references.
• Files about to be created or modified, with absolute paths.
• Sub-skills that will run after approval.
• Validations that will run after generation.

The plan is read by the developer. Keep it concrete: name the artifacts, files, sub-skills, and validations.

Print the plan in full, then proceed unless the user's next reply explicitly pushes back. Explicit pushback = no, stop, wait, change X, use Y instead, or an equivalent rejection / revision request. Explicit approval (yes, approve, go, looks good, ok) is welcome but NOT required — silence, an unrelated follow-up, or the natural continuation of a single-turn eval all count as implicit approval. The plan being visible in the transcript is the invariant; blocking on interactive approval is not. If pushback arrives, revise the plan and re-print before moving on.

---

Phase 4 — Generation

Execute the sub-skill load order from the chosen path's row in the Phase 1 table. For each sub-skill:

1. Load the skill.
2. Execute the leaf skill's authoring workflow against the spec from Phase 3. The leaf skill is authoritative for its own deliverables.
3. Verify the outputs match what the build plan promised.
4. Checkpoint before invoking the next sub-skill.

new-lightning-type-with-widget handoff contract:

• Apex authors a class whose @AuraEnabled fields define the desired Lightning Type shape. Inner classes are used only for nested list-element types. Capture the outer class FQN (<namespace>__<ClassName>).
• The Custom Lightning Type references the outer class via lightning:type: "@apexClassType/<namespace>__<ClassName>".
• Widget grounds on the outer class's @AuraEnabled fields and binds attributes via {!$attrs.X}.
• After the widget bundle is written, author the Lightning Type's renderer wiring per the renderer.json wiring step below.

existing-lightning-type-with-widget handoff contract:

• Hand the widget skill the Lightning Type schema.json path and the Apex class FQN captured in Phase 2. The widget skill derives its own schema.json from the Apex class's @AuraEnabled fields (see platform-widget-generate/references/schema-from-lightning-type.md).
• After the widget bundle is written, author the Lightning Type's renderer wiring per the renderer.json wiring step below. The Lightning Type schema.json is NOT modified (lightning-type-unchanged enforces this) — only renderer.json is written.

Renderer.json wiring step (BOTH flows — never optional):

First, Read platform-custom-lightning-type-generate/references/widget-rendition.md (REQUIRED — do NOT skip; do not author renderer.json from memory or by copying an existing project sample, which may use a deprecated shape).

After the widget bundle exists, author <pkgDir>/lightningTypes/<TypeName>/renderer.json using the widget-rendition pattern documented in platform-custom-lightning-type-generate/references/widget-rendition.md. The renderer file is a thin wrapper — its first child references the widget via "definition": "@widget/c/<widgetName>" and maps every widget schema property to the Lightning Type instance's matching attribute via {!$attrs.<schemaPropertyName>}. Do NOT duplicate the widget body inside renderer.json; the widget bundle is the single source of truth for the rendering tree.

Existing-renderer handling (existing-lightning-type-with-widget only): if renderer.json already exists at the target path, read it first.

• If it already references the same widget (same @widget/c/<widgetName>) with the same attribute mapping, leave it alone.
• If it references a different widget OR uses a custom-LWC root override (c/<componentName>), STOP and surface the conflict to the user before overwriting. Do not silently replace the user's existing rendition.
• If the file exists but is not a widget-rendition (e.g. property-level overrides only), surface that and ask whether to merge or replace.

Without this wiring the widget is unreachable from the Lightning Type — the widget bundle ships dead. renderer-wires-widget enforces existence and binding correctness.

---