mbertamini/harnessing-mistica

.agents/skills/author-component/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: author-component
+description: >
+  Author or modify a component INSIDE the mistica-web library source (the @telefonica/mistica package
+  repository). Use when editing files under src/, adding a new component with its stories and Playroom
+  snippet, changing component props, or working with vanilla-extract .css.ts styles and skinVars tokens in
+  this repository. This is the develop-the-library hat. Do NOT use it when merely consuming the published
+  @telefonica/mistica package in a downstream app — that is the mistica-react skill's job.
+license: MIT
+metadata:
+  author: telefonica
+  version: '1.0.0'
+  internal: true
+---
+
+# Author a Mistica component
+
+Use this skill when you are working **on** the `mistica-web` source — the repository that builds and publishes
+`@telefonica/mistica`. If instead you are building a UI in a separate application that _depends on_ the
+published package, stop and use the `mistica-react` skill; nothing here applies to that case.
+
+## When to apply
+
+- Adding a new component under `src/`, or modifying an existing one.
+- Changing a component's props, and therefore its Storybook `args` / `argTypes`.
+- Editing styles in `.css.ts` files or wiring `skinVars` design tokens.
+- Any task that changes the library's published surface.
+
+## Read first
+
+Before writing code, read `doc-internal/architecture.md`. It defines the source layout, the styling model, and
+the authoring conventions this skill depends on. That file — and everything under `doc-internal/` — is
+contributor-only and is not part of the published package.
+
+## Non-negotiable rules
+
+- Never import `@vanilla-extract/css` or `**/sprinkles.css` from a `.tsx` file; styles live in `.css.ts`.
+- Namespace React hooks: `React.useState`, `React.useEffect`.
+- Prefer `type` over `interface`; export types with `export type`; mark client components with
+  `'use client';`.
+- A new component ships with a Playroom snippet and Storybook stories. When props change, update the stories
+  accordingly.
+
+## Tests
+
+A component change is not complete without tests. For the suites, Jest configuration, and the
+`ThemeContextProvider` + `makeTheme()` requirement, see the `write-acceptance-test` skill and
+`doc-internal/testing-internals.md`.

.agents/skills/write-acceptance-test/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: write-acceptance-test
+description: >
+  Write or repair tests for the mistica-web library source (the @telefonica/mistica package repository) — unit
+  tests, Puppeteer-driven acceptance tests against Storybook, screenshot tests, SSR tests, or type tests under
+  src/**/__tests__, __acceptance_tests__, __screenshot_tests__, and __type_tests__. This is the
+  develop-the-library hat. Do NOT use it for testing an application that merely consumes the published
+  @telefonica/mistica package; that downstream case is covered by the mistica-react skill and doc/testing.md.
+license: MIT
+metadata:
+  author: telefonica
+  version: '1.0.0'
+  internal: true
+---
+
+# Write tests for the library source
+
+Use this skill when authoring or fixing tests **inside** the `mistica-web` repository. If you are testing a
+separate app that consumes the published `@telefonica/mistica` package, this does not apply — use the
+`mistica-react` skill, whose documentation covers the consumer testing surface.
+
+## Read first
+
+Read `doc-internal/testing-internals.md` before writing tests. It is the contributor reference for the suites,
+the per-concern Jest configuration, and the run commands. It is not shipped to consumers.
+
+## When to apply
+
+- Adding or repairing unit tests (`__tests__/`, `yarn test`).
+- Adding or repairing acceptance tests (`__acceptance_tests__/`, `yarn test-acceptance` against a running
+  Storybook).
+- Updating screenshot tests (`__screenshot_tests__/`) when visual states change.
+- Adjusting type tests (`__type_tests__/`); run `yarn build` first so declarations exist.
+
+## Rules
+
+- Wrap every rendered tree in a `ThemeContextProvider` with a theme from `makeTheme()`.
+- Prefer semantic queries (`getByRole`, `getByLabelText`) over `getByTestId`.
+- Never use mocks outside test files.
+
+## Evaluating skill or package changes
+
+To measure a change to the consumer skill or to the package as it affects generated UIs, follow the A/B
+methodology in the root `TESTING-MISTICA-SKILL.md`. That is a contributor methodology and is not part of the
+published package.

plugin/.claude-plugin/plugin.json → .claude-plugin/plugin.json

@@ -10,5 +10,6 @@
     "repository": "https://github.com/Telefonica/mistica-web",
     "license": "MIT",
     "keywords": ["react", "design-system", "telefonica", "mistica", "ui", "components"],
+    "skills": ["published-skills/mistica-react", "published-skills/mistica-figma"],
     "dependencies": [{"name": "figma", "marketplace": "claude-plugins-official"}]
 }

.claude/skills

@@ -0,0 +1 @@
+../.agents/skills

AGENTS.md

@@ -2,6 +2,23 @@
 
 React component library for Telefonica's Design System.
 
+## You are developing the library, not consuming it
+
+This repository is the **source** of the `@telefonica/mistica` package. When you work here you are authoring
+the library itself. Read the contributor documentation under `doc-internal/`:
+
+- [`doc-internal/architecture.md`](./doc-internal/architecture.md) — source layout, styling model, authoring
+  conventions.
+- [`doc-internal/testing-internals.md`](./doc-internal/testing-internals.md) — test suites, Jest
+  configuration, run commands.
+- [`doc-internal/release-process.md`](./doc-internal/release-process.md) — release flow and what ships in the
+  tarball.
+
+Do **NOT** follow the consumer guide `doc/llms/llms.md` for authoring tasks. The `doc/` tree and the
+`published-skills/mistica-react` skill describe how a downstream app _uses_ the published package; they are
+the consumer surface and do not apply when editing this source. The develop-the-library skills live under
+`.agents/skills/` and load automatically in this workspace.
+
 **Package manager**: `yarn`
 
 **Tooling**: yarn storybook (components live doc), yarn playroom (prototyping tool)
@@ -28,3 +45,43 @@ React component library for Telefonica's Design System.
 
 - Read [CONTRIBUTING](./CONTRIBUTING.md) before creating a PR or contributing to Mistica repo.
 - Always add the `AI` label to PRs where the code was written by an AI agent.
+
+# Documentation
+
+- **Do NOT read all docs upfront**
+- When working on a task, use this map to find and read only the docs relevant to your task.
+
+For library development (authoring this source), the internal docs are the primary reference:
+
+```
+doc-internal
+├── architecture.md           # source layout, styling model, authoring conventions
+├── release-process.md        # release flow and what ships in the tarball
+└── testing-internals.md      # test suites, Jest configuration, run commands
+```
+
+The `doc/` tree is the consumer surface (how a downstream app uses the published package):
+
+```
+doc
+├── analytics.md              # event tracking and analytics props
+├── components.md             # component catalog and usage (read .d.ts for props)
+├── design-tokens.md          # skinVars tokens, colors, skin/color-scheme rules
+├── fonts.md                  # font setup and loading
+├── forms.md                  # form example, form fields, validation
+├── images
+│   └── layout                # layout diagrams and SVG assets referenced by layout.md
+├── layout.md                 # Box, Stack, Inline, grid, responsive layout
+├── llms
+│   ├── agents
+│   │   └── figma-verifier.md # Figma verifier agent instructions
+│   ├── figma-mcp.md          # Figma MCP workflow
+│   └── llms.md               # main entry point, critical rules, doc index
+├── lottie.md                 # optimizing bundle size with Lottie animations
+├── migration-guide.md        # migration guide for the new Cards ecosystem (16.x)
+├── patterns.md               # page composition patterns and best practices
+├── sheet.md                  # Sheet modal component and predefined sheets
+├── testing.md                # unit/visual test setup and conventions
+├── texts.md                  # customizing default component texts via theme
+└── theme-config.md           # ThemeContextProvider and ThemeConfig options
+```

doc-internal/architecture.md

@@ -0,0 +1,49 @@
+> **Internal contributor doc.** This file is for people authoring the `@telefonica/mistica` library source. It
+> is **NOT** shipped to consumers of the published package and must never be linked from a consumer-facing
+> skill or from `doc/`.
+
+# Library architecture
+
+This document describes how the `mistica-web` source is organised so that a contributor can place new code
+correctly. For how to _consume_ the published package, see `doc/llms/llms.md` instead — that is the consumer
+surface and is irrelevant to authoring tasks.
+
+## Source layout
+
+- `src/` — component sources, organised one folder or file per public component.
+- `src/generated/` — generated assets (icons, tokens). Never edit by hand; regenerate instead.
+- `src/**/__tests__/`, `__acceptance_tests__/`, `__screenshot_tests__/`, `__type_tests__/` — test suites
+  colocated with the code under test. See `doc-internal/testing-internals.md`.
+- `src/**/__stories__/`, `__private_stories__/` — Storybook stories that document each component.
+
+## Styling model
+
+Mistica styles are authored with [vanilla-extract](https://vanilla-extract.style/). Two rules are absolute and
+enforced in review:
+
+- **Never** import `@vanilla-extract/css` from a `.tsx` file. Style definitions live only in `.css.ts` files.
+- **Never** import `**/sprinkles.css` from a `.tsx` file.
+
+Runtime theming is exposed through `skinVars` design tokens. Components must read colours, spacing, and
+typography from tokens rather than hardcoding values, so that every brand skin renders correctly from a single
+implementation. Token semantics are documented for consumers in `doc/design-tokens.md`.
+
+## Component authoring conventions
+
+- Prefer `type` over `interface`; export public types with `export type`.
+- Client components start with the `'use client';` directive.
+- Always namespace React hooks: `React.useState`, `React.useEffect`.
+- Every new component ships with a Playroom snippet and Storybook stories. When props change, update the
+  stories `args` and `argTypes` accordingly.
+
+## Build outputs
+
+The published package is produced by `yarn build` into three trees, all listed in the `package.json` `files`
+allowlist:
+
+- `dist/` — CommonJS build (`main`).
+- `dist-es/` — ES module build (`module`).
+- `css/` — extracted static CSS.
+
+Consumer documentation in `doc/` is also shipped. Contributor material — `.agents/`, `published-skills/`, and
+this `doc-internal/` tree — is deliberately excluded from the tarball. See `doc-internal/release-process.md`.

doc-internal/release-process.md

@@ -0,0 +1,51 @@
+> **Internal contributor doc.** This file is for people authoring the `@telefonica/mistica` library source. It
+> is **NOT** shipped to consumers of the published package and must never be linked from a consumer-facing
+> skill or from `doc/`.
+
+# Release process and what ships
+
+This document records how the package is released and, critically, which paths reach consumers.
+
+## Conventional commits and contributing
+
+Read `CONTRIBUTING.md` before opening a pull request. Commits follow the Conventional Commits specification;
+the release is automated from commit history, so the commit type and scope drive the next version bump.
+Release commits are tagged `[skip ci]`.
+
+## The tarball allowlist
+
+`package.json` uses a `files` **allowlist**. Only the globs listed there are published; anything not listed is
+excluded by default. The shipped trees are:
+
+- `dist/**`, `dist-es/**`, `css/**` — the build outputs.
+- `doc/**` — consumer documentation, including `doc/llms/llms.md`.
+- `src/**` minus tests, stories, and generated sources.
+- `community.js`, `community.d.ts`.
+
+Because the mechanism is an allowlist, the contributor-only trees are excluded automatically and must stay
+that way:
+
+- `.agents/` — develop-the-library skills, active only in this workspace.
+- `published-skills/` — the consumer skill _sources_; consumers fetch these through
+  `npx skills add telefonica/mistica-web`, not through `node_modules`.
+- `doc-internal/` — this contributor documentation.
+- `.claude-plugin/`, `TESTING-MISTICA-SKILL.md` — tooling and methodology.
+
+After changing the `files` allowlist, verify the tarball contents:
+
+```
+npm pack --dry-run
+```
+
+Confirm that `doc/` is present and that `.agents/`, `published-skills/`, and `doc-internal/` are absent.
+
+## Two independent distribution channels
+
+The library reaches agents through two separate channels, and they resolve from different roots:
+
+- **`npx skills add telefonica/mistica-web`** (the `skills` CLI) discovers the consumer skill from
+  `published-skills/` via the root `.claude-plugin/plugin.json` `skills` array. The develop skills under
+  `.agents/skills/` carry `metadata.internal: true`, so this channel skips them.
+- **The Claude Code plugin marketplace** historically pinned the `plugin/` subdir at a fixed SHA. When
+  re-pinning to a commit that adopts this layout, point the marketplace source `path` at the repository root
+  so it reads the root `.claude-plugin/plugin.json` and `published-skills/`.

doc-internal/testing-internals.md

@@ -0,0 +1,40 @@
+> **Internal contributor doc.** This file is for people authoring the `@telefonica/mistica` library source. It
+> is **NOT** shipped to consumers of the published package and must never be linked from a consumer-facing
+> skill or from `doc/`.
+
+# Testing the library source
+
+This is the contributor view of testing the `mistica-web` source. It is distinct from the consumer-facing
+`doc/testing.md`, which explains how an application that _uses_ Mistica sets up its own tests. When authoring
+or repairing library tests, follow this document.
+
+## Test suites
+
+Tests are colocated with the code under test, grouped by suite directory:
+
+- `__tests__/` — unit tests, run with Jest (`yarn test`). Wrap every rendered tree in a `ThemeContextProvider`
+  with a theme built by `makeTheme()`; a component rendered without a theme will throw. Prefer semantic
+  queries (`getByRole`, `getByLabelText`) over `getByTestId`.
+- `__acceptance_tests__/` — end-to-end acceptance tests driven by Puppeteer against a running Storybook. Start
+  Storybook first, then run `yarn test-acceptance` (add `--ui` for the interactive runner).
+- `__screenshot_tests__/` — visual regression tests captured against Storybook stories.
+- `__type_tests__/` — static type assertions; these require generated declarations, so run `yarn build` before
+  `yarn ts-check`.
+
+## Jest configuration
+
+The repository splits Jest configuration per concern: `jest.unit.config.js`, `jest.acceptance.config.js`,
+`jest.ssr.config.js`, all composed from `jest.base.config.js`. The shared environment is set up in
+`setup-test-env.tsx`.
+
+## Conventions
+
+- Never use mocks outside test files.
+- A new component is not complete until it has unit coverage and, where it has meaningful visual states, a
+  screenshot story.
+
+## Evaluating changes to the consumer skill
+
+Changes to the `published-skills/mistica-react` skill — or to anything that influences how an agent generates
+Mistica UIs — are evaluated with the A/B methodology in the root `TESTING-MISTICA-SKILL.md`. That methodology
+is a contributor tool and is not shipped to consumers.

eval/doc-map/.gitignore

@@ -0,0 +1,3 @@
+results/
+runs.csv
+*.err

eval/doc-map/README.md

@@ -0,0 +1,64 @@
+# Doc-map experiment
+
+Measures whether the `# Documentation` map in `AGENTS.md` improves agentic
+performance, and whether the per-line descriptions earn their token cost.
+
+## Arms
+
+The arms differ only in the content of `AGENTS.md`:
+
+- `A-no-map` — no documentation map (the `master` baseline).
+- `B-bare-tree` — the `doc/` tree with filenames only, no descriptions.
+- `C-described` — the `doc/` tree with a one-line description per entry (current).
+
+Three arms separate two questions: does a map help at all (C and B versus A),
+and do the descriptions add value (C versus B).
+
+## What is measured
+
+Per `(arm, task)` cell, averaged over repetitions:
+
+- `inputTotal` — input tokens processed (raw + cache read + cache creation); the primary cost signal.
+- `output`, `cost$`, `turns` — output tokens, USD cost, conversation turns.
+- `tools` — number of tool calls.
+- `docsTouched` — distinct `doc/*.md` files the run opened.
+- `readExpected%` — share of runs that opened the task's expected doc (doc-dependent tasks only).
+- `wrongDocs` — doc files opened that were not the expected one.
+
+Tasks are split by tag. `doc-dependent` tasks require a specific doc; the map
+should help. `control` tasks need no doc; they expose the map's fixed overhead.
+
+## Running
+
+Requires the `claude` CLI and `jq` on `PATH`.
+
+```bash
+cd eval/doc-map
+REPS=3 MODEL=sonnet ./run.sh      # first pass
+node parse.mjs                    # tabulate; also writes runs.csv
+```
+
+Set `MODEL=opus` to measure your real working model. Set `REPS` higher to
+reduce noise from model nondeterminism. Restrict arms with `ARMS="A-no-map C-described"`.
+
+The runner swaps `AGENTS.md` per arm and always restores it on exit. It warns
+if a task writes files outside `AGENTS.md` and this directory.
+
+## Reading the result
+
+- On `doc-dependent` tasks, C (and B) should show lower `inputTotal` and
+  `tools`, higher `readExpected%`, and lower `wrongDocs` than A.
+- On `control` tasks, all arms should be close; a large gap means the map costs
+  tokens without benefit.
+- If C clearly beats B, the descriptions justify themselves; if not, the bare
+  tree is the better trade.
+
+## Caveats
+
+- **Quality is not auto-scored.** Token savings are meaningless if answers get
+  worse. Grade answer correctness separately (manual rubric or a blind
+  LLM-judge pass over `results/*.jsonl`) before drawing conclusions.
+- **Prompt caching** can mask token differences; keep `REPS` high and compare averages.
+- **Nondeterminism** requires repetition; a single run proves nothing.
+- For strict isolation against accidental writes, run the experiment inside a
+  throwaway `git worktree`.