@se-studio/project-build 1.0.131 → 1.0.133

package/skills/contentful-cms/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/contentful-cms/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.