feat(plugin): add Koobiq Claude Code plugin for product teams (DS-5683)

.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "koobiq-react",
+  "description": "Claude Code plugins for products built with Koobiq React (@koobiq/react-components).",
+  "owner": {
+    "name": "Koobiq",
+    "url": "https://github.com/koobiq"
+  },
+  "plugins": [
+    {
+      "name": "koobiq",
+      "source": "./plugins/koobiq",
+      "description": "Review product UI code against the Koobiq design system, migrate off deprecated APIs, upgrade the library and lint Koobiq usage.",
+      "category": "development",
+      "tags": ["design-system", "react", "code-review", "a11y", "koobiq"]
+    }
+  ]
+}

.github/workflows/plugin.yml

@@ -0,0 +1,42 @@
+name: Claude Code plugin
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read # clone the repository (actions/checkout)
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-node
+      - name: Plugin tests
+        run: pnpm run test:plugin
+      - name: Plugin version
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch --no-tags --depth=1 origin "+refs/heads/$BASE_REF:refs/remotes/origin/$BASE_REF"
+          node scripts/check-plugin-version.mjs "origin/$BASE_REF"
+        env:
+          BASE_REF: ${{ github.base_ref }}
+
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-node
+      - name: Build packages
+        run: pnpm run build
+      - name: Check the plugin against the build
+        run: node --test plugins/koobiq/scripts/tests/real.test.mjs
+        env:
+          KOOBIQ_DS_DIR: packages/components

.gitignore

@@ -26,3 +26,6 @@ test-results
 
 # api-extractor temp
 tools/public_api_guard/temp
+
+# Claude Code plugin eval results
+plugins/*/evals/results/

.nano-staged.mjs

@@ -3,7 +3,7 @@ export default {
     'eslint --fix',
     'vitest related --run',
   ],
-  '**/*.{css}': ['stylelint --fix'],
+  '**/*.{css}': ['stylelint --fix --allow-empty-input'],
   '**/*': () => 'pnpm type-check',
   '*': ['prettier --write --ignore-unknown'],
 };

.prettierignore

@@ -3,3 +3,5 @@ CHANGELOG.md
 tools/public_api_guard/
 .husky/_/
 next-env.d.ts
+plugins/koobiq/scripts/tests/fixtures/
+plugins/koobiq/evals/

.stylelintignore

@@ -9,3 +9,5 @@ playwright-report/
 test-results/
 templates/nextjs/template
 templates/vite/template
+plugins/koobiq/scripts/tests/fixtures/
+plugins/koobiq/evals/

AGENTS.md

@@ -45,6 +45,8 @@ Selected paths. The root also holds the lint, format, commit, and deploy configs
 │           └── code-block.ts          # `@koobiq/react-components/code-block` entry
 ├── docs/                              # Guide MDX pages rendered in Storybook (numeric prefix sets the order)
 ├── .storybook/                        # Storybook config, MDX doc blocks (Meta, Story, Props, Status, Alert), decorators
+├── .claude-plugin/                    # Claude Code plugin marketplace `koobiq-react` (for product teams)
+├── plugins/koobiq/                    # The `koobiq` Claude Code plugin: reviewer agent, skills, checker, lint preset
 ├── tools/
 │   ├── api-extractor/                 # Public API guard runner + config.json (guarded components/packages)
 │   ├── e2e/                           # Docker image, Compose files and runner of the Playwright e2e suite
@@ -121,9 +123,11 @@ pnpm approve-api react-core # refresh one package (react-primitives | react-core
 pnpm e2e:docker                  # Playwright screenshot tests in Docker, where the baselines belong
 pnpm e2e:docker -g Button        # filter by test title; arguments go to `pnpm e2e:components`
 pnpm e2e:docker:update-snapshots # rewrite changed and missing baselines
+
+pnpm test:plugin # node --test for the Claude Code plugin in plugins/koobiq
 ```
 
-CI (`.github/workflows`) runs `type-check`, `format:check`, `lint:css --max-warnings=0`, `lint:js --max-warnings=0`, `vitest --run`, `build && check-api`, and the e2e screenshot tests in Docker on an arm64 runner. Because of `--max-warnings=0`, Stylelint/ESLint **warnings fail CI**.
+CI (`.github/workflows`) runs `type-check`, `format:check`, `lint:css --max-warnings=0`, `lint:js --max-warnings=0`, `vitest --run`, `build && check-api`, the e2e screenshot tests in Docker on an arm64 runner, and, in `plugin.yml`, the Claude Code plugin checks (`test:plugin`, the version check on pull requests, the contract test against a build). Because of `--max-warnings=0`, Stylelint/ESLint **warnings fail CI**.
 
 ## Component Architecture
 
@@ -216,16 +220,18 @@ Public `--kbq-<component>-*` variables are override points.
 - Props with a fixed set of allowed values are exported as `as const` arrays plus a derived union type:
 
   ```ts
-  export const buttonVariant = ['contrast-filled', 'fade-contrast-filled', ...] as const;
-  export type ButtonVariant = (typeof buttonVariant)[number];
+  export const buttonPropVariant = ['contrast-filled', 'fade-contrast-filled', ...] as const;
+  export type ButtonPropVariant = (typeof buttonPropVariant)[number];
   ```
 
 - All boolean props default to `false`. If `true` would be the natural default, invert the name (e.g. `hideArrow` instead of `showArrow={true}`).
 - Deprecated props warn via `deprecate()` (from `@koobiq/logger`) guarded by `process.env.NODE_ENV !== 'production'`:
 
   ```tsx
   if (process.env.NODE_ENV !== 'production' && 'disabled' in props) {
-    deprecate('Button: "disabled" is deprecated. Use "isDisabled" instead.');
+    deprecate(
+      'Button: the "disabled" prop is deprecated. Use "isDisabled" prop to replace it.'
+    );
   }
   ```
 
@@ -314,7 +320,7 @@ Any change to an existing component's exported types/signatures needs the same `
 
 All commits follow [Conventional Commits](https://www.conventionalcommits.org/) and are validated by commitlint — the `commit-msg` hook locally and the **PR title** in CI. `main` history is one squash commit per PR, so the PR title becomes the commit message. Only `feat` and `fix` appear in the changelog. Keep titles short (≤100 chars).
 
-Format in practice: `type(scope): subject (DS-NNNN)` — scope is the component name (`fix(Button): …`; several: `fix(Flag, Sidebar): …`) or `components` when adding a new component; `DS-NNNN` is the tracker ticket, when there is one.
+Format in practice: `type(scope): subject (DS-NNNN)` — scope is the component name (`fix(Button): …`; several: `fix(Flag, Sidebar): …`), `components` when adding a new component, or `plugin` for the Claude Code plugin; `DS-NNNN` is the tracker ticket, when there is one.
 
 | Type       | When to use                              |
 | ---------- | ---------------------------------------- |
@@ -339,6 +345,16 @@ chore(deps): bump `typescript` from 5.7.3 to 6.0.3
 
 `CHANGELOG.md` is generated at release time (`pnpm release`) — don't edit it by hand.
 
+## Claude Code Plugin
+
+`plugins/koobiq/` is a Claude Code plugin for **product teams**, published through `.claude-plugin/marketplace.json`. It reviews apps that use the library, not this repository. Maintainer notes are in `plugins/koobiq/README.md`.
+
+- The plugin parses the built package. Keep the `deprecate()` message format above, the `kbq-<file>-<class>-<hash>` class names, the `<component>Prop<Name>` value arrays and the entry points stable, or update the plugin in the same PR. After `pnpm build`, `KOOBIQ_DS_DIR=packages/components pnpm test:plugin` checks the contract.
+- When the setup steps in `docs/0-welcome.mdx` change, update `plugins/koobiq/skills/guidelines/references/setup.md` and `plugins/koobiq/skills/init/agents-block.md`.
+- The plugin has its own semver in `plugins/koobiq/.claude-plugin/plugin.json`, and users receive a change only when it changes. A PR that changes the plugin bumps it and adds a section to `plugins/koobiq/CHANGELOG.md` (CI runs `node scripts/check-plugin-version.mjs`). `feat(plugin)` / `fix(plugin)` commits are hidden from the design system's `CHANGELOG.md`, so don't mark them breaking with `!`.
+- After editing `marketplace.json` or `plugin.json`, run `claude plugin validate .`.
+- Plugin scripts are dependency-free ESM (`.mjs`, Node.js 18.17+) and are excluded from `tsconfig.json`; test them with `pnpm test:plugin`.
+
 ## Important Notes for Agents
 
 - When Storybook runs locally, an MCP server is available at `http://localhost:6006/mcp` (via `@storybook/addon-mcp`) — use it for component introspection.

CONTRIBUTING.md

@@ -131,3 +131,39 @@ pnpm approve-api             # refresh all
 pnpm approve-api Button      # refresh a single component
 pnpm approve-api react-icons # refresh a single package
 ```
+
+## 🤖 Claude Code plugin
+
+`plugins/koobiq/` is a Claude Code plugin for teams that build products with Koobiq React
+([user guide](https://react.koobiq.io/?path=/docs/ai-claude-code-plugin--docs)). It reads the built
+package, so some changes to the library reach it:
+
+- Write prop deprecations in the format from the
+  [Deprecation Strategy](https://react.koobiq.io/?path=/docs/deprecation-strategy--docs) page:
+  `pnpm test:plugin` checks every `deprecate()` call.
+- Keep the generated class names (`kbq-<file>-<class>-<hash>`), the `<component>Prop<Name>` value
+  arrays and the package entry points stable, or update the plugin in the same pull request. After
+  `pnpm build`, the contract test checks them:
+
+```bash
+KOOBIQ_DS_DIR=packages/components pnpm test:plugin
+```
+
+- When the setup steps on the Welcome page change, update
+  `plugins/koobiq/skills/guidelines/references/setup.md` and `plugins/koobiq/skills/init/agents-block.md`.
+
+When you change the plugin itself:
+
+- Bump `version` in `plugins/koobiq/.claude-plugin/plugin.json` (semver) and add a section to
+  `plugins/koobiq/CHANGELOG.md`: users receive a change only when the version changes. CI checks both:
+
+```bash
+node scripts/check-plugin-version.mjs origin/main
+```
+
+- Use the `plugin` commit scope, for example `fix(plugin): …`. These commits stay out of the
+  library's changelog.
+- Run `pnpm test:plugin` and `claude plugin validate .`, and try the plugin in a product with
+  `claude --plugin-dir /path/to/react-components/plugins/koobiq`.
+
+Maintainer notes: [plugins/koobiq/README.md](https://github.com/koobiq/react-components/blob/main/plugins/koobiq/README.md).

README.md

@@ -21,3 +21,8 @@ Here are a few helpful links for getting started with Koobiq React:
 - [@koobiq/react-icons](https://github.com/koobiq/icons) — a collection of React-icons (maintained in the [koobiq/icons](https://github.com/koobiq/icons) repository).
 - [@koobiq/react-core](https://github.com/koobiq/react-components/tree/main/packages/core) — common utilities and hooks used by Koobiq React packages.
 - [@koobiq/logger](https://github.com/koobiq/react-components/tree/main/packages/logger) — the utilities for displaying the log on the client side.
+
+## 🤖 AI tools
+
+- [Claude Code plugin](https://react.koobiq.io/?path=/docs/ai-claude-code-plugin--docs) — reviews product code against the design system, helps upgrade Koobiq React and installs a lint preset. Install it in Claude Code with `/plugin marketplace add koobiq/react-components`, then `/plugin install koobiq@koobiq-react`.
+- [LLMs.txt](https://react.koobiq.io/?path=/docs/ai-llms-txt--docs) — the documentation in a form AI tools can read.

docs/0-welcome.mdx

@@ -52,6 +52,17 @@ export default function App() {
 }
 ```
 
+**Working with Claude Code**
+
+The [Claude Code plugin](?path=/docs/ai-claude-code-plugin--docs) checks this setup in your app, keeps Claude on Koobiq components and tokens while it writes UI, and reviews your changes against the design system:
+
+```text
+/plugin marketplace add koobiq/react-components
+/plugin install koobiq@koobiq-react
+```
+
+Other AI tools can read the documentation through [LLMs.txt](?path=/docs/ai-llms-txt--docs).
+
 ## Browser Support
 
 [Check compatible browsers](https://browsersl.ist/#q=baseline+widely+available)

docs/12-llms.mdx

@@ -16,3 +16,7 @@ We support [LLMs.txt](https://llmstxt.org/) files to make Koobiq React documenta
 Use [`llms.txt`](https://react.koobiq.io/llms.txt) as the starting point.
 
 Support depends on the AI tool. Some tools can use these files directly, while others may require you to open or attach them manually.
+
+## Claude Code
+
+The [Claude Code plugin](?path=/docs/ai-claude-code-plugin--docs) goes further: it reviews product code against the design system, helps upgrade Koobiq React and installs a lint preset.