@mpfrontend/ai-skills 0.0.0-stage → 0.1.0

package/skills/mpfrontend-sync-design-tokens/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: mpfrontend-sync-design-tokens
+description: Plan and apply reviewed light/dark/system token updates from an MP Frontend normalized candidate while preserving authored styles and withholding baseline acceptance until evidence passes.
+---
+
+# Synchronize declared consumer tokens
+
+Requires the reviewed CLI 0.1.0 cohort, an attached design source and a supplied/imported candidate. Read consumer instructions,
+installed CLI `DESIGN-SYNC.md`, source provenance and the current accepted binding. The installed
+import procedure describes acquisition; no Figma write or automatic watcher is part of this workflow.
+Run `design status` first and stop on pending, disabled or drifted source state; do not bypass source
+binding verification by invoking lifecycle commands against an unrelated binding.
+
+Validate the exact candidate and inspect semantic diff by stable IDs. Names are not new identities.
+Check all declared light/dark values, alias resolution/types, explicit consumer CSS mappings, brand
+scope and system mode. Unsupported/unmapped tokens, aliases, missing modes or license issues are
+prerequisites, not permission to guess or silently strip declarations. Review removals/renames for
+authored usage and compatibility; never delete a custom product extension automatically.
+
+Run `mpfrontend design plan --binding <file> --candidate <hash> --dry-run --json`, then persist a plan
+only within implementation scope. Review its output hashes, tasks, diagnostics and required checks.
+Apply the reviewed exact path first with dry-run, then through `design apply --plan <path> --json`.
+If binding/source/CLI/output hashes changed, re-plan and re-review; there is no force bypass. A busy
+or interrupted writer requires inspecting its owner/state before recovery, never age-based deletion.
+
+Wire only the owned generated CSS into consumer composition and keep fonts/icons/structural overrides
+authored. Run actual typecheck/unit and light/dark/system, right to left, keyboard/focus and contrast
+checks on affected screens. Do not change source palette/Figma to hide a contrast conflict; record
+the source token and reviewed consumer mapping. Preserve identity/preferences/drafts during switching.
+
+Supply genuine reviewed artifacts in the documented evidence schema. CLI verifies identities/digests
+but does not execute the reported commands or judge visual quality. Component/asset/migration tasks
+remain open until authored code/tests and review satisfy them. Applying tokens is not full-DLS
+acceptance. Only a request authorizing promotion allows `design accept`; afterwards run design check.
+Report declared scope/results/gaps, and keep publication and owner visual approval separate.

package/skills/mpfrontend-table-from-api/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mpfrontend-table-from-api
+description: Render a validated MP Frontend read model with ResourceTable and consumer-owned labels, formatting and detail navigation, with paging, sorting and filtering declared from the contract. Does not infer mutations, backend parameters or field permissions.
+---
+
+# Render a selected read model
+
+Read the consumer instructions, approved operation and pinned public exports. Use the installed
+`mpfrontend-integrate-openapi` procedure if no generated read exists. Inspect the selected
+operation, responseStatus and responsePath: metadata selects columns, but `parseRead` validates the
+whole response. Do not cast an unvalidated payload into table rows or convert response fields into
+form inputs. Missing success schemas require API/projection review, not fabricated examples.
+
+Place generated parsing before state/rendering while preserving the consumer's authority and abort
+fences. Extract rows from the validated model in an authored adapter. Use `ResourceTable` from
+`@mpfrontend/ui`, a caption, localized labels, a value formatter and stable domain row keys when
+available. When the page has an access snapshot, pass `access={useAccess()}` from `@mpfrontend/access-react`: a
+column whose field the person may not view is removed with its header. Field access comes from the server's
+snapshot; do not derive permissions from fields or role names. Keep authorized detail navigation consumer-owned
+and render a detail link with `AccessLink`, which renders nothing when denied. Untrusted text stays React text, not
+injected HTML. Do not reveal sensitive columns merely because the API describes them.
+
+Paging, sorting and filtering follow the documented conventions. Declare how the operation encodes them as a
+`ListProtocol` of `@mpfrontend/ftg-core` in the entity of the resource (parameter names and encodings, where the
+answer holds the rows and the total) and keep its test, `checkListProtocol` against the captured contract, green:
+send only parameters the operation declares, never an invented one. Define the URL state with `listUrlState` of
+`@mpfrontend/data-react/shared`; the server screen reads it for the first render and the client binds it with
+`useTableUrlState`. Read pages with `useScopedQuery` through the app's own route, which reads the same URL state and
+calls the server boundary with `listSearchParams`. Give `ResourceTable` a declared `mode`: `server` when the backend
+pages, sorts or filters (it never does so itself), `client` only when the whole data set is in hand; never mix
+them. Its control texts come from the feature's catalog. Never put the scope, a token, a secret or a personal value
+in the URL. Implement loading, error and empty states; do not pretend the table is a virtualized grid. Keep
+horizontal overflow inside the table, not the viewport, and use logical alignment for right to left. Refresh must
+not overwrite an unrelated editing draft.
+
+Test the actual response adapter with malformed data, status mismatch, nullable/optional values,
+empty results, meaningful row-key/detail behavior and, with an access snapshot, a column the person may not view.
+Test the protocol against the contract, a link and a refresh that restore the list, back and forward, an invalid URL
+value that falls back to its default, and a change of access scope while a page is loading. Prove the parser runs before protected data
+is published and that an isolated parser-removal control fails a real assertion. Check labels,
+number/date formatting, loading/retry and keyboard detail access left to right and right to left, light/dark and
+mobile widths. Run the actual generated-check and Nx gates uncached.
+
+Report the selected contract, the list protocol, rows actually observed and unresolved grid/access features.
+No API exposure, business write, deployment or publication is authorized by this procedure.

package/skills/mpfrontend-upgrade-project/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: mpfrontend-upgrade-project
+description: Upgrade an existing MP Frontend consumer as one reviewed package/CLI/skills cohort with dry-run, regeneration and rollback evidence. Use for an authorized bounded upgrade, never for automatic major migrations.
+---
+
+# Upgrade a consumer cohort
+
+Read repository instructions and inventory exact installed package, lockfile, CLI, skills-lock and
+accepted design-candidate versions. Review the target changelog/compatibility notes and define one
+bounded compatible cohort. Do not mix independently convenient package versions or rebuild a published
+version with different contents.
+
+Every `@mpfrontend` package carries one cohort version; pin all of them, and the CLI, the Nx plugin and the
+workspace configuration, at that exact version, never a range. Keep the scope bound to the public registry in
+`.npmrc` (`@mpfrontend:registry=https://registry.npmjs.org/`), so that no other registry can serve it. After the
+install, compare the lockfile's integrity of each package with the release record (`docs/releases/<version>.md`)
+and run `npm audit signatures` for the registry signatures and provenance. Read the release notes first: while the
+major version is 0 a minor version may break, and its notes say how to move; a patch never breaks. Offline, install
+the release's archives through pnpm overrides and lock the SHA-256 of the release record.
+
+Before mutation, record the current working-tree diff and runnable gates. Use `mpfrontend skills update
+--dry-run --json`, FTG/design dry-runs and package-manager resolution output to expose planned changes.
+An authored skill, generated-output or design collision is a stop condition; never force it away. Git
+history is useful rollback evidence but this skill does not authorize commits, resets or checkout.
+
+Update manifests and lockfile together. Regenerate only outputs whose approved source/configuration or
+generator version requires it, then prove authored overrides remain intact. Run offline/frozen install
+when the distribution supports it, affected Nx `lint`, `typecheck`, `test`, `build`,
+`generated-check`/`design-verify`, skills check and a clean packed-consumer check appropriate to the
+change. Compare artifact identities and browser-critical behavior before and after.
+
+The quality profile is part of the cohort: `@mpfrontend/workspace-config` moves with the other
+packages, and its rules change only by upgrading it. A workspace created before the profile adopts it as
+a bounded upgrade: create a scratch workspace and app with the upgraded CLI outside the repository, copy
+the root `eslint.config.mjs`, `prettier.config.mjs`, `.prettierignore`, `check` script,
+`tools/ci/check.sh` and the pinned devDependencies, then give each project the `format`, `format:check`,
+`lint` and `test` targets and an `eslint.config.mjs` that spreads the root profile. Run `pnpm format` as
+its own formatting-only change, then fix every lint finding; do not widen allowed paths or switch a rule
+off to pass.
+
+A consumer of the previous cohort that used its built-in `ar` locale keeps it by adding it in its own
+repository, since MP Frontend now ships English only: register `ar: { direction: 'rtl' }` in the app's
+locale registry; keep or add `messages/ar.ts` in every catalog set, listed in each set's `translations`,
+with text for every key the set uses (the core messages no longer hold it), and run `catalog-check`; in
+the Security BFF set `apiLocales: { supported: ['en', 'ar'], defaultLocale: 'en' }` and add `ar` to
+`supportedUiLocales` and `preferenceCookie.locales`. A BFF without `apiLocales` now sends the default
+locale upstream. Pass the app's registry to `formatNumber` and `formatValue`. Follow the upgrade note of
+the nx-plugin README; never put the product's text into MP Frontend.
+
+If a gate fails, preserve diagnostics and restore only files owned by this upgrade when the user's
+authorized rollback is unambiguous; never overwrite unrelated local work. Report old/new cohort,
+changed files, exact evidence and known migration gaps.
+
+No major upgrade, auth replacement, accepted design-baseline change, Git publication, package
+publication or deployment is implied. Those require explicit decisions and authority.

package/skills/mpfrontend-use-ui/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mpfrontend-use-ui
+description: Compose the existing neutral MP Frontend components (Button, Field, Select, Card, ResourceTable, ResourceForm, Dialog, OneTimeCodeField, ConfirmWithCode, Tree) with consumer-owned DLS styling. Not a complete Figma component library or design-sync workflow.
+---
+
+# Use the neutral component boundary
+
+Read the consumer instructions and installed `@mpfrontend/ui` types before implementation. The
+current public kit has Button, Field, Select, Card, ResourceTable, ResourceForm, Dialog,
+OneTimeCodeField, ConfirmWithCode and Tree.
+Use those exports rather than private package internals or copying core into the product. Read and
+request forms have different metadata; route to the installed table/form procedures when applicable.
+
+The kit owns semantic markup and supported interaction states; the consumer owns product names,
+assets, fonts, icons, CSS/token values and composed screens. Existing mp-* classes and variable-based
+Tailwind hooks are styling interfaces, not evidence of a complete unstyled/headless widget system.
+Do not add a product's brand/token registry to neutral core. Verify local font/asset rights before
+public redistribution; missing proprietary fonts may use a licensed consumer fallback.
+
+Use accessible labels and native semantics. Preserve Button loading/restricted/disabled states;
+Field helper/error associations; Select's logical icon placement; and table captions/column scopes.
+Set product-specific loading/error copy explicitly. Inspect actual types before assuming unsupported
+slots, variants, modal behavior, widget registration or controlled-null semantics.
+
+Verify real keyboard interaction, focus visibility, disabled submissions, error announcements,
+long text and mobile overflow. Exercise left to right and right to left with logical spacing and light/dark tokens.
+For API controls prove the consumer adapters and request/read guards, not only static rendering.
+Run relevant UI and consumer lint/typecheck/test/build targets; save native browser evidence when
+visual acceptance is required. A screenshot alone does not prove interaction or accessibility.
+
+Frame every app with `@mpfrontend/app-layout`: `AppFrame` (skip link and focusable `main`), `AppHeader`
+(brand, navigation slot, actions slot), `Navigation` and `PageFrame` (a section labelled by its title,
+with an actions slot). Pass only the navigation items that the server allows; the shell decides nothing
+about access, and every text is a prop. Import `@mpfrontend/ui/tailwind.css` and
+`@mpfrontend/app-layout/tailwind.css` from the app's global stylesheet so that Tailwind v4 compiles the
+structural classes, and verify a built rule such as `p-6` of Card. Take spacing and layout from the
+components and utility classes; never add a layout stylesheet, a class rule to the global entry or a raw
+colour, which the shared lint rules refuse.
+
+For a sensitive action confirmed by a code sent to the person, use `ConfirmWithCode` (built on `Dialog` and
+`OneTimeCodeField`): its `onConfirm` posts the code through the BFF with the CSRF token and an idempotency
+key, and the server alone checks it. Never check a code in the browser, keep it in storage or put it in a
+URL. Pass every label from the catalog; verify Tab, Shift+Tab, Escape and focus return in both directions.
+
+For a hierarchy (menus and the elements under them, for example), use the controlled `Tree`, with
+`columns` for a tree table. Keep `expanded` and the node states in the feature's state; write the state
+rule (including any change over the current children) in the feature model and call it from
+`onActivate`. The tree decides no access; the server's projection decides which nodes and states exist.
+
+If a missing reusable component is requested, record its neutral behavioral contract and test it
+before extending core; do not label an invented component as a verified Figma implementation.
+Never alter Figma, publish a package or perform a live business mutation without that authority.

package/skills/mpfrontend-verify-frontend/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mpfrontend-verify-frontend
+description: Verify a bounded MP Frontend consumer change using existing Nx and FTG checks plus actual browser evidence. Report readiness gaps without treating a review as authority to fix, deploy or publish.
+---
+
+# Verify a bounded change
+
+Requires MP Frontend CLI `0.1.0`. Read the consumer's instructions, changed-file scope and
+acceptance criteria. A review/diagnosis is read-only apart from normal diagnostic build/test artifacts;
+fixes, restarts, business writes and release actions require the corresponding user request.
+
+Check `pnpm exec mpfrontend --version` and `pnpm exec mpfrontend skills check --json`.
+Find the actual Nx targets in `project.json`/workspace configuration; do not report success when Nx
+says no tasks ran. Run the affected `format:check`, `lint`, `typecheck`, `test`, `build` and
+`generated-check` targets uncached where defined, then `pnpm check --skip-nx-cache`. Lint carries the
+shared quality profile: module boundaries, no raw colour outside the theme files, no hand-written CSS
+outside the theme layer and logical properties instead of physical left and right. Report a rule switched off, an `eslint-disable` without a reason or a widened
+allowed path as a finding, not as a pass. Verify frozen dependencies, consumer-authored override preservation and
+the OpenAPI hash consumed by FTG/Swagger. Missing tests are a gap, not a passing test count.
+
+For UI/API changes, verify the actual deployed surface, response status and failure state. Use the
+available browser capability for the required locale/theme/viewport/keyboard states; unavailable
+browser evidence stays unverified. Never substitute mock data for a failing real API without labeling
+an explicitly approved demo mode. Use synthetic local identities only for authorized test journeys;
+do not collect real credentials or real payment/location data.
+
+For protected changes assess server authorization, CSRF/origin checks, stale authority, data projection,
+session/store outage and realtime recovery as relevant. UI visibility is not an authorization boundary.
+Record a failing control for the safety property being tested. Preserve unsaved drafts in recovery.
+
+Report exact commands/counts, observed browser/API evidence and remaining acceptance gates.
+Passing a build does not establish production HA, security, full journey acceptance or distribution
+rights. Preparation and review never authorize GitHub/npm publication.