diff --git a/CLAUDE.md b/CLAUDE.md index bccb956..2a2481a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,6 +35,7 @@ Hvert plugin er selvstendig med egen CLAUDE.md, README, hooks, agents og command 1. Plugin `README.md` — detaljert dokumentasjon av endringen 2. Plugin `CLAUDE.md` — arkitektur/oversikt 3. Rot-`README.md` — marketplace-landingssiden (`git.fromaitochitta.com/open/ktg-plugin-marketplace`) +- **Playground-oppdatering:** Ved endring av plugin playground HTML eller delt design-system, følg prosedyren i `shared/PLAYGROUND-MAINTENANCE.md` (4 spor: HTML-endring, DS-endring, screenshots, release). ## Sesjonsfiler (lokale, gitignored) diff --git a/shared/PLAYGROUND-MAINTENANCE.md b/shared/PLAYGROUND-MAINTENANCE.md new file mode 100644 index 0000000..6dcedd3 --- /dev/null +++ b/shared/PLAYGROUND-MAINTENANCE.md @@ -0,0 +1,146 @@ +# Playground Maintenance + +Procedure for updating plugin playground HTML files (single-file decision-builders + report viewers shipped under `plugins//playground/`) when a plugin is extended or upgraded. + +Five plugins currently consume the shared design system: `ms-ai-architect`, `okr`, `llm-security`, `ultraplan-local`, `config-audit`. The procedure is identical for all of them — substitute the plugin name where indicated. + +## Architecture in 30 seconds + +``` +marketplace-rot/ +├── shared/ +│ ├── playground-design-system/ ← Canonical source (where DS work happens) +│ │ ├── tokens.css, base.css, components*.css, fonts/ +│ │ ├── CHANGELOG.md +│ │ └── README.md +│ └── playground-examples/ ← Reference scenarios + showcase landing +│ +└── plugins// + └── playground/ + ├── -playground.html ← Loads CSS from `vendor/...` + └── vendor/playground-design-system/ ← Vendored snapshot (synced from shared/) + └── MANIFEST.json ← SHA-256 per file + source_commit + sync_date +``` + +**Standalone guarantee:** plugin HTML loads `vendor/...`, never `shared/...`. After sync, `vendor/` is self-sufficient — forkers who clip out `plugins//` get everything. + +## Four update tracks + +Pick the track(s) that match what you are changing. Multiple tracks can apply in one release. + +### Track A — Plugin HTML change (parser, renderer, surface, action) + +When: you are adding/modifying parsers, renderers, surfaces, action handlers, or fixtures inside the plugin's playground HTML. No DS change. + +1. Edit `plugins//playground/-playground.html` directly. +2. If fixture format changes, update `plugins//playground/test-fixtures/.md` and re-run parser tests. +3. Run plugin's playground test suite: + ```bash + cd plugins/ + bash tests/run-e2e.sh --playground + bash tests/test-playground-migrations.sh # if migrations exist + ``` +4. If demo state references fixtures, regenerate the inline JSON block: + ```bash + node scripts/build-demo-state.mjs # idempotent — replaces existing block + ``` + +No DS sync is needed for Track A. + +### Track B — Shared design-system change + +When: you are adding new tokens, components, or modifying generic CSS that all consuming playgrounds should benefit from. + +1. Edit `shared/playground-design-system/.css` at marketplace root. +2. Bump version in `shared/playground-design-system/CHANGELOG.md` (Keep a Changelog format). +3. Sync vendored copy in each consuming plugin: + ```bash + node scripts/sync-design-system.mjs [--force] + ``` + - **Drift detection:** the script refuses overwrite if `vendor/` files have been modified locally (SHA-256 mismatch). `--force` overrides. + - `MANIFEST.json` is updated with new `source_commit` + `sync_date` per file. + - Repeat for every consuming plugin (current consumers listed in repo-root `CLAUDE.md`). +4. Verify each plugin's playground tests still pass (Track A step 3). +5. Each consuming plugin must adopt the new selectors in its HTML to actually use them — DS bumps are additive, never breaking. + +**Adoption is optional.** Plugins not yet using a DS feature stay green without re-syncing. New DS hoists never break existing consumers as long as the bump is purely additive. + +### Track C — Visual verification (always before release) + +When: any visual-affecting change has landed (Track A, B, or both). + +1. Regenerate screenshots: + ```bash + cd plugins//tests/screenshot + npm install # one-time, gitignored node_modules + npx playwright install chromium # one-time, ~150MB + node run.mjs + ``` + - Output: `plugins//playground/screenshots//` + - Bump `OUT_DIR` in `tests/screenshot/run.mjs` when the plugin version changes (e.g. v1.10.0 → v1.11.0). + - Decide whether to keep older screenshot folders as historical reference, or delete them — they live under git history regardless. +2. Manual visual QA in Chrome: + - Open the plugin playground HTML from `file://`. + - Compare against `shared/playground-examples/scenarios/.html` (e.g. `ros-lier-kommune.html` is the showcase anchor for ms-ai-architect renderers). + - Check: eyebrow labels visible, severity-coded borders rendering, app-header breadcrumb correct, AI Act pyramid not clipping text, light/dark theme toggle working. + +### Track D — Release (version bump + docs) + +When: shipping a new version, regardless of which other tracks ran. + +Mandatory files to update in the release commit (or immediately after): + +1. `plugins//.claude-plugin/plugin.json` — bump `"version"`. +2. `plugins//README.md` — version badge, Version History entry, new detailed section under Playground describing the change. +3. `plugins//CLAUDE.md` — Playground heading version, architecture notes, status of any deferred work. +4. `plugins//CHANGELOG.md` — new `[X.Y.Z]` entry at the top (Keep a Changelog format) with Added/Changed/Notes subsections. +5. Marketplace-root `README.md` — bump version reference in the plugin's block. + +Conventional commit: +``` +feat(): release vX.Y.Z — +``` + +Do not use `[skip-docs]` on release commits — release commits are exactly when docs ship. Intermediate session commits within a multi-session release may use `[skip-docs]` if docs are bundled with the final commit. + +Push to Forgejo `main` is pre-authorized (see global `~/.claude/CLAUDE.md`). + +## Three-doc rule (from marketplace-root CLAUDE.md) + +> Enhver feature-endring som pusher til Forgejo MÅ oppdatere alle tre doc-nivåer i SAMME commit eller umiddelbart etter: +> 1. Plugin `README.md` — detailed change documentation +> 2. Plugin `CLAUDE.md` — architecture/overview +> 3. Marketplace-root `README.md` — marketplace landing page + +This rule applies to every release that consumers see. Internal refactors that do not change the user-visible contract may use `[skip-docs]`, but the next release commit must catch up the docs. + +## Common pitfalls + +- **Editing `vendor/` directly.** Never. Edit `shared/` and re-sync. Direct vendor edits trigger drift detection on next sync (which is the safety mechanism, but you have lost authorial intent). +- **`replace_all` in Edit tool with a string that appears in multiple contexts.** When migrating CSS class names, verify scope after each `replace_all` — e.g. `
` may appear in both project-sub-card and catalog-card with different surrounding markup. +- **Sync without testing.** Running `sync-design-system.mjs` then committing without running the plugin's test suite is how silent breakage ships. Always Track A step 3 after Track B step 3. +- **Forgetting to regenerate demo state.** If you change fixture formats but skip `build-demo-state.mjs`, the inline JSON block becomes stale and the "Last inn demo-data" button loads obsolete data. +- **Screenshot folder version mismatch.** Bumping `plugin.json` version without updating `OUT_DIR` in `tests/screenshot/run.mjs` produces screenshots in the wrong folder. Bump both. +- **Background orchestrators.** The harness does not expose Agent tool to sub-agents launched in background. Default to foreground for any orchestration involving sub-agents. + +## When to consider hoisting + +Inline CSS in a plugin's playground HTML is a candidate for hoisting to `shared/playground-design-system/components-tier3-supplement.css` when: + +- The selector represents a generic visual pattern (not domain-specific semantics). +- At least two playgrounds would benefit (or one playground plus the showcase under `playground-examples/`). +- The pattern is structurally identical, not just visually similar (different ARIA semantics or DOM shapes are usually a sign to keep it plugin-local). + +Components that should stay plugin-local include: +- Domain-specific verdict semantics (e.g. ms-ai-architect's `.verdict-pill` for go/block contrasts with DS `.verdict-pill-lg` for severity bands). +- Status modifiers that don't generalize (e.g. `.scenario-card[data-status="met/partial/missing"]` vs DS `data-status="winner"`). +- Components with structurally different ARIA patterns (e.g. native `
` vs JS-toggled `aria-expanded`). +- Surface-specific layouts (`.onboarding-*`, `.home-*`, `.project-*`, `.modal*`, `.command-form*`). + +## References + +- Marketplace-root `CLAUDE.md` — conventions and three-doc rule +- `shared/playground-design-system/CHANGELOG.md` — DS version history +- `shared/playground-design-system/README.md` — DS API surface and token reference +- `shared/playground-examples/` — reference scenarios serving as visual anchors +- Each plugin's `CLAUDE.md` Playground section — plugin-specific architecture and validation counts