@se-studio/contentful-cms 1.0.43 → 1.0.44

package/skills/cms-guidelines/validation-prompt.md

@@ -1,170 +0,0 @@
-# Validation Prompt — Guideline vs Code
-
-**Step 5.3 — LLM validation of a guideline fragment against the component source.**
-
-Run as part of the generation pipeline (not CI). Heavy validation that checks completeness
-and consistency before committing. It is acceptable for this to take time — correctness is
-the priority.
-
----
-
-## When to run
-
-After Step 5.1 (generation) produces a guideline fragment, before committing. Feed the
-fragment and the component source to this prompt.
-
----
-
-## Prompt
-
-```
-You are validating a CMS component guideline fragment for accuracy and completeness.
-
-You will be given:
-1. The guideline fragment (markdown).
-2. The component source file (TypeScript/React).
-3. Supporting files: SizingInformation.ts, Section.tsx, mapping.md.
-
-Your task: systematically check whether the guideline is COMPLETE and CONSISTENT with
-the code. Produce a detailed report.
-
-Guideline fragment:
-<GUIDELINE_MARKDOWN>
-
-Component source:
-<COMPONENT_SOURCE>
-
-SizingInformation.ts:
-<SIZING_SOURCE>
-
-Section.tsx:
-<SECTION_SOURCE>
-
-mapping.md (CMS field → app prop mapping):
-<MAPPING_SOURCE>
-
----
-
-Check the following and report each as PASS, FAIL, or N/A:
-
-1. FIELDS COVERAGE
-   - Are all fields in USED_FIELDS mentioned in the "Used fields" table?
-   - Are any fields mentioned in the table that are NOT in USED_FIELDS?
-
-2. FIELD DESCRIPTIONS
-   - For each field in the table: is the "Effect when set" accurate?
-   - For each field in the table: is the "Effect when empty/removed" accurate?
-   - Are any effects described that do not match the code?
-
-3. TYPOGRAPHY
-   - Does the guideline state the correct typography class for each element?
-     (e.g. heading = h4, body = p3)
-   - Does it correctly describe which HTML element the heading renders as
-     based on index (h1 for first, h2 for later)?
-
-4. COLOUR BEHAVIOUR
-   - Does the guideline correctly describe how backgroundColour and textColour are applied
-     (section-wide, card-level, or neither)?
-   - Are the valid enum values for backgroundColour and textColour correct?
-
-5. POSITION/INDEX BEHAVIOUR
-   - If the component uses getSizingInformation(index), does the guideline describe:
-     (a) the heading level change (h1 vs h2)?
-     (b) the spacing/padding change?
-
-6. VARIANT DIFFERENCES
-   - If there are multiple registered variants (e.g. Hero and Hero Flipped), are they
-     all described, and are the differences accurately stated?
-
-7. IMPACT SECTION
-   - Does the "Impact of content changes" section describe what happens when:
-     (a) important optional fields are added?
-     (b) important optional fields are removed?
-   - Are there missing impact scenarios that would be confusing to a user?
-
-8. NO CODE REFERENCES
-   - Does the guideline contain any file path references (e.g. "Hero.tsx", "Section.tsx")?
-   - Does it contain any code beyond typography class names and colour names?
-
-9. COMPLETENESS
-   - Is there anything important in the code that the guideline does NOT mention and SHOULD?
-   - List any missing items.
-
----
-
-Output format:
-
-## Validation Report — <ComponentType>
-
-### Summary
-PASS / FAIL / PARTIAL — one sentence overall verdict.
-
-### Checks
-
-| Check | Result | Detail |
-|---|---|---|
-| Fields coverage | PASS | All 10 used fields are in the table. |
-| Field descriptions | FAIL | `visual` empty description says "copy-only" but should say "copy spans full width". |
-| Typography | PASS | Heading h4, body p3 — correct. |
-| Colour behaviour | PASS | Section-wide application described correctly. |
-| Position/index | PASS | h1/h2 and padding described. |
-| Variant differences | PASS | Hero Flipped column order described. |
-| Impact section | PARTIAL | Removing preHeading described; removing body not described. |
-| No code references | PASS | No file paths or raw code. |
-| Completeness | PARTIAL | Animation behaviour (animate-when-seen) not mentioned. |
-
-### Issues to fix
-
-List each FAIL and PARTIAL item with a specific fix instruction:
-- **Field: visual empty description** — change to: "Copy spans full section width on all breakpoints."
-- **Impact: removing body** — add row: "Remove body → body block disappears; links follow directly after heading/subtitle."
-- **Completeness: animation** — add to Behaviour section: "All text elements animate in when they scroll into view."
-
-### Verdict
-
-APPROVED — The guideline is complete and consistent. Minor fixes applied.
-OR
-NEEDS REVISION — Fix issues above before committing.
-```
-
----
-
-## Acceptance criteria
-
-**Approved if:**
-- Fields coverage = PASS
-- Typography = PASS
-- Colour behaviour = PASS
-- No code references = PASS
-- No more than 2 PARTIAL items (and they are minor)
-
-**Needs revision if:**
-- Any FAIL item
-- More than 2 PARTIAL items
-
-When revision is needed: apply the specific fixes from the "Issues to fix" list and re-run
-validation. Repeat until approved.
-
----
-
-## Cursor agent task prompt
-
-```
-Validate the CMS guideline fragment for <COMPONENT_TYPE>.
-
-Files to read:
-- docs/cms-guidelines/components/<type-slug>.md (the guideline to validate)
-- src/project/components/<TypeName>.tsx (source of truth)
-- src/lib/SizingInformation.ts
-- src/framework/Section.tsx
-- generated/cms-discovery/mapping.md
-
-Follow the validation prompt in validation-prompt.md.
-Produce a validation report.
-
-If APPROVED: proceed to merge.
-If NEEDS REVISION: apply the specific fixes to docs/cms-guidelines/components/<type-slug>.md,
-then re-validate (run this task again with the updated fragment).
-When approved, run: pnpm run cms-guidelines:merge
-Then commit both files.
-```

package/skills/cms-guidelines/variant-loop.md

@@ -1,189 +0,0 @@
-# Variant Loop — Orchestrator
-
-**Step 4.4 — Orchestration of: propose → screenshot → evaluate.**
-
-This document describes the full variant loop for one CMS type. Run it as a **Cursor agent task**,
-or manually follow the steps below.
-
----
-
-## Overview
-
-```
- ┌──────────────────────────────────────────────────┐
- │ INPUT: typeName, source file path, N             │
- └──────────────────────┬───────────────────────────┘
-                        │
-                        ▼
- ┌──────────────────────────────────────────────────┐
- │ Step 1: Propose N variants (LLM)                 │
- │ → variants.json (typeName, variants[])           │
- └──────────────────────┬───────────────────────────┘
-                        │
-                        ▼
- ┌──────────────────────────────────────────────────┐
- │ Step 2: Capture screenshots                      │
- │ → docs/cms-guidelines/screenshots/{mode}s/<n>.png│
- └──────────────────────┬───────────────────────────┘
-                        │
-                        ▼
- ┌──────────────────────────────────────────────────┐
- │ Step 3: Evaluate screenshot diversity (LLM)      │
- │ → suitablyDifferent, acceptedVariants, rejected  │
- └──────────────────────┬───────────────────────────┘
-                        │
-           ┌────────────┴─────────────┐
-           │ suitablyDifferent?       │
-           ▼ YES                      ▼ NO + attempts < 2×N
- ┌──────────────────┐      ┌──────────────────────────────┐
- │ Accept set;      │      │ Capture suggested new        │
- │ proceed to gen  │      │ variants; re-evaluate         │
- └──────────────────┘      └──────────────────────────────┘
-                                       │ attempts >= 2×N
-                                       ▼
-                            ┌──────────────────────────┐
-                            │ Accept best set so far   │
-                            └──────────────────────────┘
-```
-
----
-
-## Cursor agent task
-
-**Assign this task to a Cursor subagent.** Provide:
-- `apps/example-brightline/src/project/components/<TypeName>.tsx` (component source)
-- `generated/cms-discovery/field-list.json` (field metadata including enum values)
-- `generated/cms-discovery/theme-context.md` (palette + typography — authoritative colour names)
-- `scripts/guidelines/variant-proposal-prompt.md` (variant proposal instructions)
-- `scripts/guidelines/evaluation-prompt.md` (evaluation instructions)
-- `scripts/guidelines/capture-screenshots.mjs` (screenshot tool)
-- This file (orchestration rules)
-
-**Task prompt:**
-
-```
-Run the variant loop for <TypeName>:
-
-1. PROPOSE: Read the component source file, field list, and theme-context.md (for palette names).
-   Using the instructions in scripts/guidelines/variant-proposal-prompt.md, produce a variants.json
-   for <TypeName>. Use N = 5 (or fewer if the component is simple).
-   IMPORTANT: use only colour names from theme-context.md — do NOT invent colour names.
-
-2. CAPTURE: Run:
-     node scripts/guidelines/capture-screenshots.mjs --variants /tmp/variants.json
-   This saves screenshots to docs/cms-guidelines/screenshots/.
-
-3. EVALUATE: Using the instructions in scripts/guidelines/evaluation-prompt.md, look at
-   the captured screenshots and produce an evaluation JSON.
-   - If suitablyDifferent = true: proceed to Step 4.
-   - If suitablyDifferent = false AND total attempts < 2 × N:
-     Extend variants.json with 1–2 new variants from the suggestions, capture them,
-     re-evaluate. Repeat until suitablyDifferent = true or 2×N total attempts.
-   - If 2×N attempts reached: accept the best acceptedVariants set seen.
-
-4. WRITE ACCEPTED LIST: Save the final accepted variant list to:
-   generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
-   Use the `mode` field to pick the subdir: component → components/, collection → collections/, external → externals/.
-   Format: { "typeName": "<TypeName>", "mode": "<mode>", "variants": [...] }
-
-5. COMMIT: git add docs/cms-guidelines/screenshots/ generated/cms-discovery/
-           git commit -m "chore(bl): variant screenshots for <TypeName>"
-```
-
----
-
-## Manual steps
-
-If running manually:
-
-### 1 — Propose variants
-
-Feed the component source file to an LLM with the prompt in
-`scripts/guidelines/variant-proposal-prompt.md`.
-
-Save the output as `/tmp/<type-slug>-variants.json`.
-
-Example for Hero:
-```json
-{
-  "typeName": "Hero",
-  "mode": "component",
-  "variants": [
-    { "label": "default", "description": "All fields.", "showcaseParams": {} },
-    { "label": "no-visual", "description": "No visual.", "showcaseParams": { "showVisual": "false" } },
-    { "label": "navy", "description": "Navy bg.", "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" } },
-    { "label": "pine", "description": "Pine bg.", "showcaseParams": { "backgroundColour": "Pine", "textColour": "Off White" } },
-    { "label": "minimal", "description": "Heading only.", "showcaseParams": { "showVisual": "false", "showLinks": "false" } }
-  ]
-}
-```
-
-### 2 — Capture screenshots
-
-```bash
-# From apps/example-brightline
-node scripts/guidelines/capture-screenshots.mjs --variants /tmp/hero-variants.json
-```
-
-Saves to `docs/cms-guidelines/screenshots/components/hero-*.png` (or `collections/` for collection types).
-
-### 3 — Evaluate
-
-Feed the screenshots + evaluation prompt to an LLM. The LLM looks at the images and
-returns `suitablyDifferent`, `acceptedVariants`, `rejectedVariants`, and `suggestions`.
-
-If not suitably different: replace rejected screenshots with suggestions, re-capture, re-evaluate.
-
-### 4 — Save accepted list
-
-```bash
-# Use the appropriate subdir based on mode: components/, collections/, or externals/
-mkdir -p generated/cms-discovery/accepted-variants/components
-# Write manually or via script — e.g. for a component:
-# generated/cms-discovery/accepted-variants/components/hero.json
-```
-
-### 5 — Commit
-
-```bash
-git add docs/cms-guidelines/screenshots/ generated/cms-discovery/accepted-variants/
-git commit -m "chore(bl): variant screenshots for Hero"
-```
-
----
-
-## accepted-variants JSON format
-
-```json
-{
-  "typeName": "Hero",
-  "generatedAt": "2026-03-12",
-  "acceptedVariants": [
-    {
-      "label": "default",
-      "description": "All fields populated, no colour override.",
-    "screenshotPath": "docs/cms-guidelines/screenshots/components/hero-default.png",
-    "showcaseParams": {}
-    },
-    {
-      "label": "navy",
-      "description": "Navy background + Off White text.",
-      "screenshotPath": "docs/cms-guidelines/screenshots/components/hero-navy.png",
-      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
-    }
-  ]
-}
-```
-
-This file is read by the generation step (Phase 5) to know which screenshots to include
-in the guideline prompt.
-
----
-
-## Notes
-
-- Collections use `--collection <TypeName>` in cms-edit. The capture script handles this via `mode`.
-- If `agent-browser` is not installed, the capture script degrades to URL-only output; run
-  `agent-browser install` to enable actual screenshot capture.
-- The variant loop is the most expensive step. For simple components (1–2 visual states),
-  N = 3 is usually sufficient.

package/skills/cms-guidelines/variant-proposal-prompt.md

@@ -1,131 +0,0 @@
-# Variant Proposal Prompt
-
-**Step 4.1 — Input/output contract and prompt for proposing component variants.**
-
-The variant loop produces screenshots that cover the visual diversity of a component. A good
-set captures: default state, important absent-field states, colour variants, and any layout
-variants (like flipped). The screenshots are then used to write the "What it looks like" and
-"Colours" sections of the guideline.
-
----
-
-## Input
-
-- **Component source file:** full contents of `src/project/components/<Type>.tsx` (or
-  `src/project/collections/<Type>.tsx`).
-- **Used fields:** the `USED_FIELDS` or `FIELD_KEYS` from the source file.
-- **Palette:** colour names from `generated/cms-discovery/theme-context.md` (generated by
-  `cms-generate-collection-guidelines` from `tailwind.config.json`). This is the authoritative
-  source — use it in preference to `field-list.json` or `generated/colors.ts`.
-- **N:** number of variants to propose (typically 4–6 for a component, up to 8 for complex ones).
-
-The LLM should output **N variants** in JSON format (see below).
-
----
-
-## Prompt
-
-```
-You are preparing screenshots for CMS component guidelines.
-
-I will give you the source code of a Next.js component that renders a CMS entry.
-Your task: propose N variants that, together, best document how the component looks
-under different conditions. Choose variants that are VISUALLY DISTINCT — a reader
-should be able to tell them apart at a glance.
-
-Component source:
-<COMPONENT_SOURCE>
-
-Palette (from generated/cms-discovery/theme-context.md — use ONLY these names):
-Background colours (backgroundColour):
-<BACKGROUND_COLOURS>
-
-Text colours (textColour, i.e. foreground colours):
-<TEXT_COLOURS>
-
-Do NOT invent or paraphrase colour names. Use the exact names from theme-context.md.
-
-Rules:
-1. Always include a "default" variant with all optional fields populated and no colour override.
-2. Include at least one variant per important "missing field" state (e.g. no visual, no links).
-3. Include at least one colour variant if the component has backgroundColour (use a dark colour
-   like Navy or Deep Periwinkle).
-4. If the component has a flipped/alternate variant (e.g. Hero Flipped), include it.
-5. Avoid variants that will look identical or near-identical to another variant in the list.
-6. N = <N>; produce exactly N variants (or fewer if the component is simple).
-
-Output JSON only, no explanation. Format:
-{
-  "typeName": "<CMS componentType or collectionType>",
-  "variants": [
-    {
-      "label": "default",
-      "description": "All fields populated, no colour override.",
-      "showcaseParams": {}
-    },
-    {
-      "label": "no-visual",
-      "description": "visual field removed; copy spans full width.",
-      "showcaseParams": { "showVisual": "false" }
-    },
-    {
-      "label": "navy-background",
-      "description": "Navy background with Off White text.",
-      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
-    }
-  ]
-}
-
-showcaseParams keys must match the cms-edit screenshot --param format:
-  backgroundColour, textColour, showVisual, showLinks, showHeading, etc.
-For a flipped variant, use a separate typeName entry for "Hero Flipped".
-```
-
----
-
-## Output contract
-
-```json
-{
-  "typeName": "Hero",
-  "variants": [
-    {
-      "label": "default",
-      "description": "All optional fields populated, no colour override.",
-      "showcaseParams": {}
-    },
-    {
-      "label": "no-visual",
-      "description": "Visual removed; copy spans full width.",
-      "showcaseParams": { "showVisual": "false" }
-    },
-    {
-      "label": "navy",
-      "description": "Navy background + Off White text.",
-      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
-    },
-    {
-      "label": "minimal",
-      "description": "Heading only, no eyebrow/subtitle/body/links/visual.",
-      "showcaseParams": { "showVisual": "false", "showLinks": "false" }
-    }
-  ]
-}
-```
-
-- `label` — used to name the screenshot file: `<typeName-kebab>-<label>.png`
-- `description` — included in the screenshot log and used by the evaluation step
-- `showcaseParams` — key-value pairs passed as `--param key=value` to `cms-edit screenshot`
-
----
-
-## Notes on N and the cap
-
-The orchestrator (Step 4.4) uses N (the number of proposed variants) as a cap:
-
-- It will attempt up to **2×N** screenshots in total.
-- If the evaluation step (Step 4.3) concludes the variants are "suitably different" before
-  reaching 2×N attempts, it stops early.
-- If not, it requests a new proposal from the LLM for the remaining slots (up to 2×N total).
-
-For most components, N = 4–6 produces a good coverage set.