@usesketchbook/cli 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/.agents/skills/component-builder/SKILL.md +16 -0
  2. package/.agents/skills/contract-author/SKILL.md +16 -0
  3. package/.claude/commands/add.md +1 -5
  4. package/.claude/skills/component-builder/SKILL.md +15 -101
  5. package/.claude/skills/contract-author/SKILL.md +14 -132
  6. package/README.md +14 -30
  7. package/docs/agent-compatibility.md +43 -9
  8. package/docs/cli.md +31 -31
  9. package/harness/catalog/kits/dashboard/files/{63cde4f28d1c141c401d → 09d34e607ea6836480d1} +1 -1
  10. package/harness/catalog/kits/dashboard/files/{11a5797c4c9189b59fbe → 2239c4e4f1d873b03305} +1 -1
  11. package/harness/catalog/kits/dashboard/files/{864acc7ce20f541cf67c → 567a658f80560e3945c6} +1 -1
  12. package/harness/catalog/kits/dashboard/manifest.json +4 -4
  13. package/harness/catalog/kits/data-table/files/{b5d5d7f18347734138e0 → 35c832acd45c642705b1} +1 -1
  14. package/harness/catalog/kits/data-table/files/{36bac8f8e53119768b2e → aaf2d576ed0b53013ac3} +1 -1
  15. package/harness/catalog/kits/data-table/files/{1786ba4d3e0dba1d6a1f → ac8792b3aa3a43002c5e} +1 -1
  16. package/harness/catalog/kits/data-table/manifest.json +4 -4
  17. package/harness/catalog/kits/docs-article/files/{dbc2840f315f672e1d74 → 3c554edf05e9c8bb52c7} +1 -1
  18. package/harness/catalog/kits/docs-article/files/{7f36cb5f0d4f5e103bde → 9d0bb5a1be919431e8ce} +1 -1
  19. package/harness/catalog/kits/docs-article/files/{c2018b502a8094818d8f → e80ea70679e0065026d0} +1 -1
  20. package/harness/catalog/kits/docs-article/manifest.json +4 -4
  21. package/harness/catalog/kits/form-states/files/{b52fb2fc480f0c6352bd → 55a0558891d66e11c216} +1 -1
  22. package/harness/catalog/kits/form-states/files/{88252259f19ed675a0dc → 64566f1a9cb16592d296} +1 -1
  23. package/harness/catalog/kits/form-states/files/{b0b51ebf587b21fd89a1 → f086df13cb85411108a1} +1 -1
  24. package/harness/catalog/kits/form-states/manifest.json +4 -4
  25. package/harness/catalog/kits/onboarding/files/{e669d75a65f4d15d8289 → 738531c9cf4c8bfb9e28} +1 -1
  26. package/harness/catalog/kits/onboarding/files/{ce466020247ecf1ff5fe → b72445926f9763db6c4f} +1 -1
  27. package/harness/catalog/kits/onboarding/files/{322cf4dfc2ee0a035d85 → c969943667ca18e8b0d3} +1 -1
  28. package/harness/catalog/kits/onboarding/manifest.json +4 -4
  29. package/harness/catalog/kits/profile/files/{4aeca453e4792abf29de → 38a6ccd576aca5c96612} +1 -1
  30. package/harness/catalog/kits/profile/files/{0fdd3c14afbdadcf1969 → adccaa2829c56d7fa215} +1 -1
  31. package/harness/catalog/kits/profile/files/{5b58bb5f93ecf12d69ff → de99237cdcfb4ddef8dd} +1 -1
  32. package/harness/catalog/kits/profile/manifest.json +4 -4
  33. package/harness/catalog/kits/settings/files/{d2ebbd6e94570b2c6434 → 08c4411e3c8dbc9e614f} +1 -1
  34. package/harness/catalog/kits/settings/files/{b4a7a4ccdc59465b8de5 → d1cd9cf4acd3416e3f63} +1 -1
  35. package/harness/catalog/kits/settings/files/{1a5d639c6803e7d03acc → f325b6c93ce84d356228} +1 -1
  36. package/harness/catalog/kits/settings/manifest.json +4 -4
  37. package/harness/catalog/kits/sign-in/files/{ca224349b746c530f922 → 0ac413f342ed59e8f3d9} +1 -1
  38. package/harness/catalog/kits/sign-in/files/{552bdad5ce7559849e81 → 796309acee1d478d2692} +1 -1
  39. package/harness/catalog/kits/sign-in/files/{361745a3ed43c753c615 → a106d6104e40b13d7e82} +1 -1
  40. package/harness/catalog/kits/sign-in/manifest.json +4 -4
  41. package/harness/checks/run.mjs +1 -2
  42. package/harness/cli/commands/add.mjs +5 -3
  43. package/harness/cli/commands/api.d.mts +4 -4
  44. package/harness/cli/commands/api.mjs +1 -1
  45. package/harness/cli/commands/audit-css.mjs +1 -1
  46. package/harness/cli/commands/audit-decisions.mjs +1 -1
  47. package/harness/cli/commands/audit-page.mjs +1 -1
  48. package/harness/cli/commands/brand.mjs +1 -1
  49. package/harness/cli/commands/check.d.mts +1 -1
  50. package/harness/cli/commands/check.mjs +1 -1
  51. package/harness/cli/commands/docs.mjs +2 -2
  52. package/harness/cli/commands/doctor.d.mts +2 -2
  53. package/harness/cli/commands/doctor.mjs +7 -5
  54. package/harness/cli/commands/explain.mjs +1 -1
  55. package/harness/cli/commands/generate.mjs +1 -1
  56. package/harness/cli/commands/help.mjs +5 -5
  57. package/harness/cli/commands/icons.mjs +1 -1
  58. package/harness/cli/commands/init.d.mts +1 -1
  59. package/harness/cli/commands/init.mjs +4 -4
  60. package/harness/cli/commands/kits.mjs +3 -1
  61. package/harness/cli/commands/list.mjs +1 -1
  62. package/harness/cli/commands/prefix.mjs +1 -1
  63. package/harness/cli/commands/presets.mjs +1 -1
  64. package/harness/cli/commands/propagate.mjs +1 -1
  65. package/harness/cli/commands/remove.mjs +4 -2
  66. package/harness/cli/commands/selftest.mjs +1 -1
  67. package/harness/cli/commands/status.mjs +6 -4
  68. package/harness/cli/commands/swap.mjs +1 -1
  69. package/harness/cli/commands/sync.mjs +3 -3
  70. package/harness/cli/commands/tokens.mjs +9 -8
  71. package/harness/cli/commands/upgrade.mjs +7 -3
  72. package/harness/cli/docs.mjs +2 -2
  73. package/harness/cli/interactive.mjs +10 -10
  74. package/harness/cli/known-commands.json +26 -26
  75. package/harness/cli/presentation.d.mts +1 -1
  76. package/harness/cli/presentation.mjs +1 -1
  77. package/harness/cli/run.d.mts +3 -3
  78. package/harness/cli/run.mjs +5 -5
  79. package/harness/cli.mjs +0 -0
  80. package/harness/commands/add.mjs +1 -1
  81. package/harness/commands/bootstrap.mjs +4 -3
  82. package/harness/kits/index.json +8 -8
  83. package/harness/lib/agent-config.d.mts +1 -0
  84. package/harness/lib/agent-config.mjs +7 -6
  85. package/harness/lib/design/docs.mjs +2 -2
  86. package/harness/lib/design/sync.d.mts +1 -1
  87. package/harness/lib/installed.mjs +3 -1
  88. package/harness/lib/propagation.mjs +2 -2
  89. package/harness/manifest.json +3 -1
  90. package/harness/starters/blank.json +1 -1
  91. package/harness/starters/foundations.json +1 -1
  92. package/harness/starters/from-codebase.json +1 -1
  93. package/harness/starters/import.json +1 -1
  94. package/harness/starters/library+kits.json +1 -1
  95. package/harness/starters/library.json +1 -1
  96. package/harness/starters/pick.json +1 -1
  97. package/harness/templates/CLAUDE.md +1 -1
  98. package/harness/templates/project/.agents/skills/sketchbook/SKILL.md +1 -1
  99. package/harness/templates/project/AGENT-WORKFLOWS.md +2 -2
  100. package/harness/templates/project/docs/getting-started.md +17 -20
  101. package/harness/templates/project/package-lock.json +2 -2
  102. package/harness/templates/project/src/stories/contract.ts +4 -1
  103. package/harness/templates/project/src/stories/foundations/BorderWidth.stories.ts +1 -1
  104. package/harness/templates/project/src/stories/foundations/Color.stories.ts +1 -1
  105. package/harness/templates/project/src/stories/foundations/Density.stories.ts +1 -1
  106. package/harness/templates/project/src/stories/foundations/Elevation.stories.ts +1 -1
  107. package/harness/templates/project/src/stories/foundations/IconSizes.stories.ts +1 -1
  108. package/harness/templates/project/src/stories/foundations/LayoutGrid.stories.ts +2 -2
  109. package/harness/templates/project/src/stories/foundations/Motion.stories.ts +1 -2
  110. package/harness/templates/project/src/stories/foundations/Opacity.stories.ts +1 -1
  111. package/harness/templates/project/src/stories/foundations/Radius.stories.ts +1 -1
  112. package/harness/templates/project/src/stories/foundations/Spacing.stories.ts +1 -1
  113. package/harness/templates/project/src/stories/foundations/Typography.stories.ts +1 -1
  114. package/harness/templates/project/src/stories/foundations/ZIndex.stories.ts +1 -1
  115. package/harness/test/agent-config.test.mjs +21 -1
  116. package/harness/test/agent-guidance.test.mjs +16 -0
  117. package/harness/test/bootstrap.test.mjs +84 -15
  118. package/harness/test/checks.test.mjs +4 -1
  119. package/harness/test/claude-live.test.mjs +8 -3
  120. package/harness/test/cli.test.mjs +25 -5
  121. package/harness/test/copilot-live.test.mjs +12 -13
  122. package/harness/test/docs-reference.test.mjs +17 -0
  123. package/harness/test/opencode-live.test.mjs +25 -10
  124. package/harness/test/package.test.mjs +1 -0
  125. package/package.json +3 -1
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: component-builder
3
+ description: Implement a Sketchbook Web Component from its approved contract. Use after contract authoring to follow the project's planning, test-first, token, accessibility, and parity requirements.
4
+ ---
5
+
6
+ # Build a Sketchbook component
7
+
8
+ 1. **Validate the inputs.** Read `harness.config.json`, the component's contract pair and `plan.md`, the API vocabulary and relevant decisions. If the contract is missing or has blocking questions, use `contract-author` and stop. If `features.planningGate` is enabled, verify the approval before writing tests, stories or implementation. Do not infer approval. Use existing components, helpers and tests as examples; ask before expanding scope into shared infrastructure or adding dependencies.
9
+ 2. **Write the story and behavior spec from the contract.** When `features.testFirst` is enabled, run them before implementing and confirm failure for the intended behavior, not a broken fixture. Cover relevant props, variants, states, events, keyboard behavior, focus, accessible names and form behavior. Use the project's Playwright helpers and axe checks; check the screen-reader view for composite keyboard interactions. Don't rewrite passing criteria simply to match implementation.
10
+ 3. **Implement the approved contract.** Follow the configured Web Component conventions: use native controls and the existing form mixins or focus controllers where applicable. Use one custom element per TypeScript file, declare compound parts in the contract, and use component tokens in SCSS. Alias component tokens to semantic tokens; add approved missing semantic tokens at the proper layer and declare applicable contrast pairs. Rebuild generated styles and exports with `npm run generate`; never edit generated outputs. Log any accessibility-driven deviation in the contract instead of silently changing the API or behavior.
11
+ 4. **Verify.** Run `npm run check`, typechecking, lint and the relevant browser specs. Run broader harness and component gates when the change or release calls for them. Report blocked or skipped checks. If the contract itself is wrong, fix it first and get approval for any material scope change; do not make the tests fit the code.
12
+ 5. **Review before beta.** Compare implementation to the contract: files, tags, props, events, parts, slots, states, tokens, keyboard/accessibility behavior and spec coverage. Use a separate reviewer when available and authorized, otherwise report the parity review as pending and identify any self-checks performed. Record evidence and drift under web realizations; promote only after required checks and parity review pass. Keep contract and registry lifecycle status in sync. Stable requires the separate accessibility audit. In the Sketchbook source checkout, verify the catalog, public demos and configured design outputs using the maintainer workflow; installed projects follow their own documentation and design configuration.
13
+
14
+ For form controls, use `src/mixins/form-associated.ts` and `src/mixins/native-control.ts` with an existing input as a reference. Verify implicit submission, reset and validity; an error prop must set `customError` validity, and ARIA ID references do not cross shadow roots. For roving keyboard focus, start with `src/controllers/roving-focus.ts`. For stories, use the contract helpers in `src/stories/contract.ts` where applicable. Check `spec/decisions/DECISIONS.md` for the rationale and project-specific exceptions.
15
+
16
+ Report the checks actually run, any observed test-first failure, drift, token changes, review status and remaining work. Do not commit or publish unless asked.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: contract-author
3
+ description: Draft, resync, or validate a Sketchbook component contract. Use when a component has no contract or when its reference, anatomy, variant matrix, accessibility, or API has changed.
4
+ ---
5
+
6
+ # Author a Sketchbook component contract
7
+
8
+ Produce `spec/components/<name>/contract.json` and `contract.md`. This skill drafts or updates a contract; it does not implement the component.
9
+
10
+ 1. **Find the scope.** Read `harness.config.json`, the component registry entry, the contract schema in `spec/schemas/contract.schema.json`, and relevant decisions in `spec/decisions/DECISIONS.md`. Use an installed contract as a format example. For a new component, register it as `planned` if needed, preview `npx sketchbook add "<name>" --blank --dry-run`, then scaffold it. For a prose-only correction, edit the existing contract and validate it without rerunning research.
11
+ 2. **Extract evidence.** Use the project's configured design reference, existing code or supplied requirements as appropriate. For the default shadcn/ui reference, consult its docs and registry for anatomy, visual behavior and variants; do not import its implementation. Use the WAI-ARIA Authoring Practices Guide for applicable keyboard and ARIA patterns. A synced design file is an output, not the contract source. Distinguish observed behavior from assumptions.
12
+ 3. **Draft both files.** Specify the API, anatomy, variants, content, states, events, interaction, accessibility, usage and realizations at the level the component needs. Use `spec/api.json` to choose canonical names; register a justified alias or extension if needed. Component tokens alias existing semantic tokens, not foundation tokens or literal values. Mark unsupported claims as proposals in prose and with `proposal: true` where the schema supports it. Record missing evidence, tokens or decisions as open questions rather than inventing values.
13
+ 4. **Validate.** Check that the JSON and Markdown agree and run `npm run check`. Review the result against the sources. Where the client supports authorized delegation, extraction, drafting and validation can use separate briefs; otherwise do the phases in order and describe validation as a self-check.
14
+ 5. **Respect the gate.** For a new or redesigned component, if `features.planningGate` is enabled, complete `plan.md` with scope, file order, test plan, accessibility deviations and open questions with recommendations. Ask for explicit approval before any tests or implementation. Do not mark a plan approved without evidence.
15
+
16
+ Report the changed contract files, sources, unresolved proposals and check results. If an approval is needed, end with that request.
@@ -8,8 +8,4 @@ Add the component "$ARGUMENTS" to the design system, following the harness rules
8
8
  **From the catalog** (the reference components): if it is in the catalog and the person wants it as shipped, run `sketchbook add "$ARGUMENTS" --dry-run`, show what it installs (contract, code, stories, tests and any components it depends on), then run it without `--dry-run`; it ends with the checks. Report the result and the Storybook page. Run `sketchbook help add` to confirm options.
9
9
 
10
10
  **New or redesigned** (not in the catalog, or `--blank`):
11
- 1. Run `sketchbook add "$ARGUMENTS" --blank` to scaffold `spec/components/<name>/` and set the registry status to draft. If the component is not in `spec/registry.json`, stop and say so.
12
- 2. Use the `contract-author` skill to fill `contract.json` and `contract.md` (harness format; UI, names and variants from the visual reference; keyboard and ARIA from the WAI-ARIA APG; component tokens alias semantic tokens only).
13
- 3. Run `sketchbook check` until it passes. If a semantic token is missing, propose it with `sketchbook tokens add <path> … --pair fg/bg` (rule `tokens-through-the-harness`); never alias foundation tokens from a component.
14
- 4. Fill `plan.md` (scope, files, test plan, accessibility deviations, open questions with a recommendation first).
15
- 5. Stop at the planning gate (`.claude/rules/planning-gate.md`): summarize the plan and ask for approval. Do not write tests or code yet.
11
+ Use the `contract-author` skill to preview the scaffold, draft and validate the contract, and request approval when the project's planning gate is enabled. If the component is not in `spec/registry.json`, stop and say so. This command ends at contract planning; it does not write tests or code.
@@ -1,124 +1,38 @@
1
1
  ---
2
2
  name: component-builder
3
3
  description: >
4
- Build a component from its approved contract, test-first: stories and
5
- behavior spec first (seen failing), then SCSS + Lit code using only
6
- component tokens, then all gates, review, and beta. Trigger: after the
7
- planning gate passes for a component (`/add` stops at the gate), or when
8
- asked to "build", "implement" or "code" a component that has a contract.
4
+ Build a component from its approved contract using the shared Sketchbook
5
+ workflow. Trigger: implementation after the planning gate; use the
6
+ project's test-first, token, accessibility, and parity requirements.
9
7
  metadata:
10
8
  author: sketchbook
11
- version: '1.2.0'
12
- changelog: >
13
- The parity-auditor brief declares its model and is launched with it
14
- (SB-0114); affects the beta review step.
15
- auto-invoke: Building, implementing or coding a component that has an approved contract
9
+ version: '1.3.0'
10
+ changelog: Use the shared Agent Skill as the workflow; keep the same build requirements across clients; retain the Claude review brief here.
11
+ auto-invoke: Building, implementing, or coding a component with an approved contract.
16
12
  allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, WebFetch, Agent]
17
13
  ---
18
14
 
19
- # component-builder
20
-
21
- Turns `spec/components/<name>/contract.json` into a working Web Component, following the harness loop. Visuals and names come from the visual reference (shadcn/ui); everything else (contract wording, tokens, accessibility, tests) is the harness's own.
22
-
23
- ---
15
+ # Component Builder
24
16
 
25
17
  ## When to use
26
18
 
27
- Use this skill when:
28
-
29
- - The planning gate has passed for a component (`/add` stops at the gate) and it is time to build it.
30
- - Asked to "build", "implement" or "code" a component that has a contract.
31
-
32
- Do not use this skill for:
33
-
34
- - A component with no contract yet (use `contract-author`; the `contract-first` rule applies).
35
- - Writing or running Playwright specs on their own (use `playwright-worker`).
36
-
37
- ---
19
+ Open the [shared component-builder skill](../../../.agents/skills/component-builder/SKILL.md) and follow it. It defines entry criteria, build order, validation and lifecycle requirements.
38
20
 
39
21
  ## Critical patterns
40
22
 
41
- ### Product rules (settled — do not reopen)
42
-
43
- - The visual reference (shadcn/ui) defines look and names only: look, component and prop names, variants, sizes, theme variable names. No Tailwind, React, Radix, or shadcn CLI. Get exact visuals from the shadcn docs page https://ui.shadcn.com/docs/components/<slug> and the registry JSON https://ui.shadcn.com/r/styles/new-york-v4/<slug>.json (Tailwind classes → our tokens). Keyboard/ARIA from the WAI-ARIA APG.
44
- - Built the contract-first standard: contract pair harness format, one custom element per .ts file, SCSS → generated .styles.ts, colocated stories, Playwright behavior specs, the reference implementation mixins/patterns.
45
- - Accessibility first (WCAG 2.2 AA). Deviations from shadcn or the reference implementation only where WCAG requires; each logged in the contract's realizations.web.drift.
46
- - Three token layers (D-011): component CSS uses ONLY its own `--sb-<component>-*` variables (declared in the contract's `tokens`, each aliasing a SEMANTIC token) plus private `--_*` properties. No literals (check T5) except with a `/* sketchbook-allow-literal: reason */` comment on the line before (warning). Never alias foundation tokens from a component; never edit spec/tokens/foundation.
47
- - If a needed semantic token is missing, add it to spec/tokens/semantic/base.tokens.json (mode-independent) or to BOTH light.tokens.json and dark.tokens.json (colors), aliasing foundation tokens, with contrast pairs in your contract. List every semantic token you add in your final report.
48
- - Native elements first (button, input, select, textarea, input type=range/checkbox/radio inside the shadow root). Compound families: each shadcn part is its own custom element named like shadcn (`sb-card-header`, `sb-tabs-trigger`), declared in the family contract's `elements` array (tag, summary, props, anatomy, content, events) — check C3 verifies each element against it. Share state between parts with `@lit/context` (installed) or parent/child queries. Roving focus: use `src/controllers/roving-focus.ts` (do not modify it; if it lacks something, work around locally and report). Form controls: use `src/mixins/form-associated.ts` + `src/mixins/native-control.ts` (Input is the model).
49
- - Shadow DOM facts learned (SB-0009): implicit submission must be handled by the component (Enter → form.requestSubmit()); a prop that shows an error must set customError validity; only aria-label can be forwarded from host to inner control (IDREFs don't cross shadow roots); set host ARIA before first render (willUpdate).
50
- - All docs and code comments in English. No new dependencies. The design file is synced separately with the `design-figma` skill.
51
-
52
- ### Boundaries
53
-
54
- - Edit only: your components' spec/components/<name>/, src/components/<name>/, playwright/tests/<name>/, their entries in spec/registry.json, and semantic token additions. Do NOT edit other components, src/mixins, src/controllers, src/styles, harness/, scripts/, .storybook/, playwright/helpers, package.json. If you need a shared change, describe it in your report and work around it locally.
55
- - Pass `SKETCHBOOK_PORT=<port>` to Playwright when several Storybooks run at once.
56
- - At the end run the whole suite once: `SKETCHBOOK_PORT=<port> npx playwright test -c playwright/playwright.config.ts` and all gates.
57
-
58
- ---
23
+ Use the local Claude rules and skills for task details when available, especially form-associated controls, browser testing, and Web Component conventions. For authorized independent parity review, launch the [parity-auditor](agents/parity-auditor.md) with the model and tools declared by the brief. Pass the component name and review the evidence in its report. Use the `a11y-checker` workflow for the separate audit before stable.
59
24
 
60
25
  ## Decision tree
61
26
 
62
- ```text
63
- Contract missing or `draft` with blocking open questions? -> contract-author first; stop
64
- Planning gate not passed (no approved plan.md)? -> stop and ask for approval
65
- Tests not yet written and seen failing? -> loop steps 4, before any component code
66
- Tests failing for a wrong reason (typo, broken story)? -> fix the test or story, not the component
67
- Contract wrong? -> fix the contract first, say so
68
- Need a shared change (mixins, controllers, helpers)? -> don't edit; work around locally and report
69
- Missing semantic token? -> add it (base, or light + dark), list it in the report
70
- All gates green and parity audit done? -> set status beta (loop step 7)
71
- Heading for stable? -> a11y audit first (a11y-checker's a11y-auditor brief)
72
- ```
73
-
74
- ---
75
-
76
- ## The loop, per component, in this order (no skipping)
77
-
78
- Read first: CLAUDE.md; .claude/rules/*.md (planning-gate, test-first, spec-is-source, contract-first, form-associated-controls, comment-minimalism); .claude/skills/contract-author/SKILL.md (+ agents/*.md as guidance — do the work yourself, don't spawn those agents); .claude/skills/playwright-worker/SKILL.md; .claude/skills/web-components-best-practices/SKILL.md; spec/decisions/DECISIONS.md (SB-0005..SB-0011); the models: spec/components/{spinner,button,input}/{contract.json,contract.md,plan.md}, src/components/{spinner,button,input}/*, playwright/tests/{spinner,button,input}/*, playwright/helpers/*, src/stories/contract.ts, src/styles/_a11y.scss, spec/schemas/contract.schema.json, harness/checks/*.mjs (what is enforced).
79
-
80
- 1. Contract: fill the scaffolded spec/components/<name>/contract.json and contract.md (the reference implementation headings, like Button's). Family parts go in `elements`. Contract `tag` is the root element; tokens prefix `<name>.` (kebab, e.g. `aspect-ratio.`, `radio-group.`).
81
- 2. `npm run check` passes.
82
- 3. plan.md: scope, files, test plan, a11y deviations, open questions answered with your recommendation. Status line: "Approved under SB-0011 (owner pre-approval, 2026-11-08)." Record the answers in contract.openQuestions (status answered).
83
- 4. Tests first: `src/components/<name>/<Name>.stories.ts` (title `Components/<Name>`, use argTypesFrom/argsFrom/matrixOf from src/stories/contract.ts) and `playwright/tests/<name>/<name>.behavior.spec.ts` (helpers in playwright/helpers; cover props, variants via tokens, keyboard, focus ring, ARIA/accessible name/description, events (bubbles/composed), forms where relevant, axe via axeViolations; a `screen-reader view` test with `expectScreenReaderView` when the contract binds keys beyond Tab and Enter; story views via `npm run test:component -- tests/screen-reader --update-snapshots`, reviewed). Run them and CONFIRM they fail for the right reason before writing the component. Say so in your report.
84
- 5. Implement: `<Name>.scss` (+ part SCSS in the same file; all elements of the folder import the one generated `<name>Styles` or each has its own `<Part>.scss`), `<Name>.ts` and one `.ts` per sub-element, `index.ts` exporting all; registration guard `if (!customElements.get(TAG)) customElements.define(TAG, Class)`; `declare global { interface HTMLElementTagNameMap … }`. Then `npm run generate`.
85
- 6. Green: `npm run check` (all 12 checks), `npx tsc --noEmit`, `npx eslint .`, `npm run test:harness`, and `SKETCHBOOK_PORT=<port> npx playwright test -c playwright/playwright.config.ts tests/<name>`. Don't weaken a test to pass; if the contract was wrong, fix the contract first and say so.
86
- 7. Review before beta, including the parity audit (below). Then update contract realizations.web (status complete, files incl. every element file + stories, parts, slots, spec, coverage list, drift), contract.md Realizations; set status `beta` in contract.json AND spec/registry.json (check R1 must pass).
87
- 7a. In the Sketchbook catalog source repository (`catalog.source` is true), document it in every output (check M1, `npm run check:maintainer`, must pass): docs site page (`npm run docs:components`) and a curated `apps/docs/content/_examples/<name>.html`; a batch in `spec/design-docs.json`; the design library (`sketchbook sync library <name>`, verify, `sync realize`) and its doc page stamped `checked` (`sync components <batch>`, compared with Storybook); `npm run catalog:build`; a new SB decision where one was made. In an installed project, follow its documentation and design-adapter configuration instead; those maintainer scripts and the Sketchbook docs site are not installed there.
88
- 8. Commit on your branch, one commit per component: `git commit -m "feat(<name>): ..."` with the repository's own git identity (never hard-code a person) and any co-author trailer your session requires. Commit generated files too (tokens.css, component.tokens.json, src/index.ts, *.styles.ts) after `npm run generate`.
89
-
90
- ## Parity audit and a11y audit
91
-
92
- The parity audit is part of the review in step 7, after the gates are green and before the status moves to `beta`. It checks the implementation against its contract, not code quality or accessibility. Its brief is [`agents/parity-auditor.md`](agents/parity-auditor.md). Launch it with the `Agent` tool as a general-purpose agent with the brief's `model`: the prompt is the brief's contents plus the component name (`<name>`); the agent stays within the brief's declared `tools` (Read, Bash, Grep, Glob) and never edits source. It writes its report to `docs/parity-audits/<name>-<YYYY-MM-DD>.md` (comparison table, differences and action plan, verdict). By default a mismatch is recorded as a `realizations.web.drift` entry; a human decides only the ambiguous cases where the contract may be the outdated side.
93
-
94
- The accessibility audit before a component moves to `stable` is not part of this loop: it is the `a11y-checker` skill's brief, `.claude/skills/a11y-checker/agents/a11y-auditor.md`.
95
-
96
- ## When done
97
-
98
- Per component: tests count (and that they failed first), notable decisions, a11y deviations/drift, semantic tokens added. Then: shared changes you needed, anything unfinished or failing (be explicit), final gate results, last commit hash.
99
-
100
- ---
27
+ - Missing contract, unresolved blocker or missing required approval: stop per the shared workflow.
28
+ - Testing or implementation: follow the shared workflow and use the client's Playwright or Web Component guidance as needed.
29
+ - Independent review unavailable: report what is pending; don't call a self-check an independent audit.
101
30
 
102
31
  ## Commands
103
32
 
104
- ```bash
105
- npm run check # all deterministic checks (contract, tokens, registry)
106
- npm run generate # rebuild *.styles.ts, tokens.css, component.tokens.json, src/index.ts
107
- npx tsc --noEmit # typecheck
108
- npx eslint . # lint
109
- npm run test:harness # proves each check can reject
110
- SKETCHBOOK_PORT=<port> npx playwright test -c playwright/playwright.config.ts tests/<name> # one component's behavior spec
111
- SKETCHBOOK_PORT=<port> npx playwright test -c playwright/playwright.config.ts # whole suite at the end
112
- git commit -m "feat(<name>): ..." # one commit per component
113
- ```
114
-
115
- ---
33
+ Use the build and verification commands in the shared workflow. Use `npm run test:component -- tests/<name>` to focus the behavior run on one component.
116
34
 
117
35
  ## Resources
118
36
 
119
- - [`agents/parity-auditor.md`](agents/parity-auditor.md): audits an implementation against its contract; launched in the review before beta; reports in `docs/parity-audits/`.
120
- - `.claude/skills/a11y-checker/agents/a11y-auditor.md`: the a11y audit before stable.
121
- - `.claude/skills/contract-author/SKILL.md`, `.claude/skills/playwright-worker/SKILL.md`, `.claude/skills/web-components-best-practices/SKILL.md`: read first.
122
- - `.claude/rules/`: planning-gate, test-first, spec-is-source, contract-first, form-associated-controls, comment-minimalism.
123
- - `spec/decisions/DECISIONS.md` (SB-0005..SB-0011), `spec/schemas/contract.schema.json`, `harness/checks/*.mts`.
124
- - Models: `spec/components/{spinner,button,input}/`, `src/components/{spinner,button,input}/`, `playwright/tests/{spinner,button,input}/`, `playwright/helpers/`, `src/stories/contract.ts`, `src/styles/_a11y.scss`.
37
+ - [Shared component-builder skill](../../../.agents/skills/component-builder/SKILL.md)
38
+ - [Claude parity-auditor brief](agents/parity-auditor.md)
@@ -1,156 +1,38 @@
1
1
  ---
2
2
  name: contract-author
3
3
  description: >
4
- Drafts or updates a component contract (contract.md + contract.json) from
5
- the shadcn/ui docs and registry, the WAI-ARIA APG, existing code or a
6
- description, through its extractor, drafter and validator briefs. Trigger:
7
- a component has no contract, or one needs a re-sync with its source or a
8
- structured field (anatomy, variantMatrix, aiHints) backfilled.
4
+ Draft, resync, or validate a component contract using the shared Sketchbook
5
+ workflow. Trigger: a missing contract or a changed reference, anatomy,
6
+ variant matrix, accessibility requirement, or API.
9
7
  metadata:
10
8
  author: sketchbook
11
- version: '1.2.0'
12
- changelog: >
13
- Shorter description; briefs declare a model and are launched with it
14
- (extractor on haiku) (SB-0114); affects the three-brief pipeline cost.
15
- auto-invoke: A component has no contract yet, or an existing one needs a re-sync with its source
9
+ version: '1.3.0'
10
+ changelog: Use the shared Agent Skill as the workflow; keep the same contract requirements across clients; retain Claude-specific role briefs here.
11
+ auto-invoke: A component has no contract or an existing contract needs to be updated or validated.
16
12
  allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, WebFetch, Agent]
17
13
  ---
18
14
 
19
15
  # Contract Author
20
16
 
21
- Produces a `spec/components/<name>/contract.md` (+ `contract.json`) that
22
- satisfies `spec/schemas/contract.schema.json`, by running three role briefs
23
- in sequence. Each is a file under [`agents/`](agents/), launched with the
24
- `Agent` tool as a general-purpose agent, with the brief's `model`, whose prompt is that brief's
25
- contents plus its inputs; the agent stays within the brief's declared
26
- `tools`.
27
-
28
- ---
29
-
30
17
  ## When to use
31
18
 
32
- Use this skill when:
33
-
34
- - A component has no `spec/components/<name>/` directory yet and one is
35
- needed before implementing it (see the `contract-first` rule).
36
- - An existing contract needs a re-sync with its source, a status change, or
37
- a structured field (`anatomy`, `variantMatrix`, `aiHints`) backfilled
38
- because the prose already covers it but `contract.json` doesn't yet.
39
-
40
- Do not use this skill for:
41
-
42
- - Partial edits that don't touch the contract's structured spec — a
43
- one-line prose typo fix doesn't need the full extractor → drafter →
44
- validator pipeline; just edit the file and re-run `npm run check`.
45
- - Auditing an _implementation_ against its contract — that's the
46
- `parity-auditor` brief at
47
- `.claude/skills/component-builder/agents/parity-auditor.md`, launched from
48
- the `component-builder` skill.
49
-
50
- ---
19
+ Open the [shared contract-author skill](../../../.agents/skills/contract-author/SKILL.md) and follow it. It defines the inputs, deliverables, checks and stopping point.
51
20
 
52
21
  ## Critical patterns
53
22
 
54
- ### 1. Source of truth for a new contract
55
-
56
- - **UI, API, visuals:** the shadcn/ui docs page for the component
57
- (`https://ui.shadcn.com/docs/components/<slug>`) and its registry JSON
58
- (`https://ui.shadcn.com/r/styles/new-york-v4/<slug>.json`). shadcn/ui is a
59
- reference only: nothing from Tailwind, React, Radix or the shadcn CLI is
60
- used in this repo.
61
- - **Keyboard and ARIA:** the WAI-ARIA Authoring Practices Guide (APG).
62
- - **Registry entry:** `spec/registry.json`.
63
- - **Tokens:** existing semantic tokens in `spec/tokens/semantic/*.tokens.json`.
64
- - Figma is **not** a source: design files are outputs of the contract.
65
- - Anything not confirmed by those sources is marked `"proposal": true` in
66
- JSON and `PROPOSAL` in prose.
67
-
68
- ### 2. Don't invent
69
-
70
- - Don't invent token values or hex codes — alias existing semantic tokens
71
- from `spec/tokens/semantic/*.tokens.json`. The component token layer
72
- (`tokens`) must alias SEMANTIC tokens only. If genuinely unknown, leave it
73
- as an open question rather than guessing.
74
- - Don't invent `aiHints.antiPatterns` either — ground each one in the
75
- shadcn/ui docs, the APG, or something the user explicitly said. If
76
- unconfirmed, leave it as an open question instead of guessing at a
77
- plausible-sounding anti-pattern.
78
-
79
- ### 2b. Names come from the API vocabulary
80
-
81
- Before naming a prop, a variant value, a state or an event, look in `spec/api.json` (`sketchbook api list`, `sketchbook api explain <name>`): use the canonical name. If the code has to spell it differently, register an alias; if it is truly specific to this component, register an extension with its reason. Check A1 fails on a name that is not registered (`docs/api-standard.md`).
82
-
83
- ### 3. One source of truth
84
-
85
- Don't duplicate the contract's content elsewhere — `contract.md` and
86
- `contract.json` are the only sources of truth; nothing else should hold a
87
- copy.
88
-
89
- ### 4. Narrow phases
90
-
91
- Each brief is scoped narrowly on purpose — extraction, drafting, and
92
- validation are different failure modes (a bad source read, a schema
93
- mismatch, a leftover validation error), and running them as separate
94
- delegated steps makes it obvious which phase produced a given problem.
95
-
96
- ---
23
+ For an authorized delegated run, use the `Agent` tool with the model and tools declared by each brief. Run the [extractor](agents/extractor.md), [drafter](agents/drafter.md), and [validator](agents/validator.md) in sequence, passing each phase's evidence and outputs to the next. Apply the project's configured gate from the shared workflow.
97
24
 
98
25
  ## Decision tree
99
26
 
100
- ```text
101
- No spec/components/<name>/ yet? -> full pipeline (workflow below)
102
- Existing contract out of sync with its source? -> full pipeline
103
- Structured field (anatomy/variantMatrix/aiHints)
104
- missing but the prose covers it? -> full pipeline (backfill)
105
- One-line prose typo or similar partial edit? -> edit the file, run npm run check
106
- Implementation vs contract audit? -> component-builder's parity-auditor brief
107
- ```
108
-
109
- ---
110
-
111
- ## Workflow
112
-
113
- ```text
114
- 1. Read spec/schemas/contract.schema.json — the contract.json produced
115
- must validate against it.
116
- 2. Read one existing contract as a template — spec/components/button/
117
- contract.md and contract.json are the reference example (frontmatter,
118
- props, anatomy, variant matrix, states, accessibility, usage,
119
- Realizations, open questions).
120
- 3. Launch agents/extractor.md
121
- -> gathers the component's real data from the sources above, marks every
122
- inferred/unconfirmed field PROPOSAL.
123
- 4. Launch agents/drafter.md
124
- -> writes contract.md (prose) + contract.json (structured spec) from the
125
- extractor's findings.
126
- 5. Launch agents/validator.md
127
- -> runs `npm run check` and fixes violations.
128
- 6. Planning gate: once `npm run check` passes, write
129
- spec/components/<name>/plan.md and STOP for approval (see the
130
- planning-gate rule). Tests come first (see the test-first rule).
131
- ```
132
-
133
- ## Status conventions
134
-
135
- `planned` (registered, no contract content yet), `draft` (contract written,
136
- open questions remain), `wip` (implementation in progress), `beta`
137
- (implemented, not fully audited), `stable` (verified end-to-end),
138
- `deprecated` (superseded), `code-only` (implementation with no design
139
- counterpart).
140
-
141
- ---
27
+ - Small prose correction: follow the shared skill's direct edit-and-check path.
28
+ - Full draft, re-sync or backfill: run the phases above if authorized; otherwise follow the shared workflow directly and disclose the self-check.
29
+ - Implementation parity review: use the component-builder skill instead.
142
30
 
143
31
  ## Commands
144
32
 
145
- ```bash
146
- npm run check # validate contract.json against the schema and the other deterministic checks
147
- ```
148
-
149
- ---
33
+ Use `npm run check` to validate the contract before requesting any required plan approval.
150
34
 
151
35
  ## Resources
152
36
 
153
- - [`spec/schemas/contract.schema.json`](../../../spec/schemas/contract.schema.json) — what `contract.json` must validate against.
154
- - `spec/components/button/contract.md` and `contract.json` — template contract.
155
- - [`agents/extractor.md`](agents/extractor.md), [`agents/drafter.md`](agents/drafter.md), [`agents/validator.md`](agents/validator.md) — the three role briefs launched in sequence.
156
- - `.claude/skills/component-builder/agents/parity-auditor.md` — the brief that audits an implementation against its contract.
37
+ - [Shared contract-author skill](../../../.agents/skills/contract-author/SKILL.md)
38
+ - [Claude role briefs](agents/)
package/README.md CHANGED
@@ -4,8 +4,8 @@
4
4
 
5
5
  # Sketchbook
6
6
 
7
- **The harness for building a design system with coding agents.**<br />
8
- Sources of truth, generators, deterministic checks, gates and agent guidance make design-system work repeatable. A component library is one of its outputs.
7
+ **Start with a working design system. Make it yours.**<br />
8
+ Choose a starter, change the sources your team owns, and use the Sketchbook CLI to rebuild and check your work.
9
9
 
10
10
  <br />
11
11
 
@@ -37,7 +37,7 @@ Sketchbook gives your team a workflow for building and maintaining a design syst
37
37
  | **Agent guidance** | Portable project instructions and task workflows, plus the existing Claude Code rules, skills, commands and hooks. |
38
38
  | **Outputs** | Tokens, a Web Components library, 8 page templates, Storybook, a Figma file and docs. The default library follows [shadcn/ui](https://ui.shadcn.com) and is a starting point you can edit or replace. |
39
39
 
40
- Bring nothing, your brand, your tokens or an existing product. The process is the same.
40
+ Bring your tokens or an existing app, or start with the library and change it as you go.
41
41
 
42
42
  ## Quick start
43
43
 
@@ -55,7 +55,7 @@ Run `npx sketchbook` in a terminal to explore the interactive menu. Choose a num
55
55
 
56
56
  `init` adds the CLI as a dev dependency of the design-system project. For an existing app, add `--adopt` to `init` and run it from the app directory. To bring your own tokens, use `--start import --from <tokens file>`. See the [Quickstart](https://sketchbook-docs.vercel.app/start/quickstart/) for all seven starters and the [upgrade guide](https://sketchbook-docs.vercel.app/guides/adopt-in-app/#upgrade) for updating the CLI and harness.
57
57
 
58
- Plain `init` creates a core-only project and writes its initial inventory to `docs/harness.md`. Add `--agent claude` to stage Claude Code, or `--agent codex,trae` to install both selected integrations. The same flag adds profiles to an existing project. Run `npx sketchbook doctor` to inspect your setup. [Agent compatibility guide](./docs/agent-compatibility.md)
58
+ Plain `init` creates a core-only project and writes its initial inventory to `docs/harness.md`. Add `--agent <profile>` to install the shared `contract-author` and `component-builder` skills and your client's setup. For example, `--agent claude` stages Claude Code, and `--agent codex,trae` selects both integrations. The same flag adds profiles to an existing project. Run `npx sketchbook doctor` to inspect your setup, then confirm what your client loaded. [Agent compatibility guide](./docs/agent-compatibility.md)
59
59
 
60
60
  ## Work on this repository
61
61
 
@@ -63,7 +63,7 @@ From the checkout root, run `npm ci` and then `npm run storybook` for the refere
63
63
 
64
64
  ## How it works
65
65
 
66
- Everything starts from a few files you own. The harness rebuilds every output from them, and checks stop anything that drifts.
66
+ Edit the source that owns the change, then rebuild. If a check finds drift, its result points you back to what needs attention.
67
67
 
68
68
  ```mermaid
69
69
  flowchart LR
@@ -73,7 +73,7 @@ flowchart LR
73
73
  K -- pass --> O["Outputs<br/>CSS · components · Storybook · Figma · docs"]
74
74
  ```
75
75
 
76
- **A component goes through the same path every time.**
76
+ Use this workflow to design a new component when the planning and test-first gates are enabled.
77
77
 
78
78
  1. **Contract.** `contract.json` and `contract.md` describe the API, tokens and accessibility. `npm run check` must pass.
79
79
  2. **Plan.** `plan.md` states scope, files, tokens, accessibility approach, test plan and open questions.
@@ -135,38 +135,22 @@ Dark mode follows `prefers-color-scheme`, or set `data-theme="dark"` on `<html>`
135
135
 
136
136
  | | |
137
137
  | --- | --- |
138
- | **A process, not a pile of files** | Contract, plan, approval, tests, checks and review, documented for contributors and agents. |
138
+ | **Agree on the component before building** | Contract, plan, approval, tests, checks and review, documented for contributors and agents. |
139
139
  | **Agent guidance** | Shared instructions describe the process; client-specific hooks and deterministic checks provide additional safeguards. |
140
- | **Checked without AI** | 26 deterministic checks cost no model spend and can each fail. |
141
- | **One source, every output** | Code, Storybook, CSS variables and Figma stay in step because they come from the same files. |
140
+ | **Run checks locally** | 26 deterministic checks cost no model spend and can each fail. |
141
+ | **Rebuild from shared sources** | Code, Storybook, CSS variables and Figma stay in step because they come from the same files. |
142
142
  | **Every foundation is yours** | 19 foundation families with 63 cited presets, or your own values, in one config. |
143
143
  | **Start where you are** | Seven starters, from blank to an existing codebase. |
144
- | **Accessible by default** | WCAG 2.2 AA, axe in every component test, screen-reader views of the accessibility tree. |
145
- | **Safe to upgrade** | Team-owned files are never overwritten. `sketchbook upgrade` only touches what the engine owns. |
144
+ | **Review accessibility as you build** | Contracts target WCAG 2.2 AA. Browser tests and accessibility audits cover different parts of that work. |
145
+ | **Review before you upgrade** | Preview how `sketchbook upgrade` will update harness-owned files. |
146
146
 
147
147
  ## Evidence
148
148
 
149
- Sketchbook was tested the way it is used: with a real AI agent, real projects and real installs.
149
+ In the November 2026 benchmark, 9 of 10 runs with project files alone produced a valid Switch contract, compared with 0 of 10 from an empty folder. The study used a small sample and Sketchbook’s own scoring scripts. [Benchmark results](./docs/research/value-benchmark/SUMMARY.md)
150
150
 
151
- **Does the harness make an agent follow your design system?** 252 headless Claude Code runs (Sonnet 5.5 and Opus 5.5) across five rounds, about $141 of API spend. The agent got the same tasks with and without the project's files, the CLI and the harness.
151
+ The November 11, 2026 installation retest covered a new project, an adopted app, and a checkout. It recorded 168 passing harness tests and 100 passing component behavior tests in an initialized project. One Claude setup step was simulated. [Installation retest](./docs/research/cli-distribution-retest-2/README.md)
152
152
 
153
- Round 3, before the lighter Claude layer (out of 10 runs):
154
-
155
- | Task | Empty folder | Project files | + CLI + harness |
156
- | --- | --- | --- | --- |
157
- | Writes a valid component spec | 0 | 9 | 10 |
158
- | Uses design-system components | 0 | 9 | 10 |
159
- | Uses tokens only, no literal colors | 0 | 10 | 10 |
160
- | Finds a real extra defect in a QA review | 0 | 9 | 10 |
161
-
162
- - The CLI makes authoring **21–32% cheaper** than files alone, and writes the same 8 files every run (round 3).
163
- - Round 5 (SB-0114) cut the harness's always-on context and reran the full setup. Evidence-backed findings per QA report rose from **4.0 to 5.6** (Sonnet) and **5.2 to 6.2** (Opus) over the CLI-only setup, with QA cost **−7% / +13%** against it. Every task now sits within +19% of that setup. Before the cut, the same harness added +66–68% to QA cost. Round 5 also recalibrated the scorer, so its numbers are not directly comparable with round 3's 3.8 → 5.0.
164
- - A bare model matched it on whether the page works, keyboard use and the planted defects, so the harness's value is conformance and evidence, not raw capability.
165
- - **What this does not show:** no comparison with other design systems, one component and one page, 10 runs per setup, and scorers written by the project. Read gaps as direction. Full report: [docs/research/value-benchmark/SUMMARY.md](./docs/research/value-benchmark/SUMMARY.md).
166
-
167
- **Does it install and upgrade safely?** From a packed tarball in an empty folder, `init`, `status`, `doctor`, `check`, `add`, `remove`, `upgrade` and repair all pass, with 100 of 100 behavior tests and 168 harness tests passing. Adopting into an existing app changes one line of its `package.json`. A team's own `.claude/` settings survive the install. In a hand-run Claude Code session, the installed rules made Claude decline an edit to a generated file and a rewrite of an accepted decision, and name the supported route instead. [Retest report](./docs/research/cli-distribution-retest-2/README.md).
168
-
169
- **Does the output match its reference?** Each of the 38 components (35 core and 3 more) has a parity audit: a read-only comparison of its code and behavior spec against its own contract, which was drafted from shadcn/ui. [docs/parity-audits/](./docs/parity-audits/).
153
+ Browse [Evidence](https://sketchbook-docs.vercel.app/reference/evidence/) for methods and limits. Use [Status](https://sketchbook-docs.vercel.app/reference/status/) for the current component and audit counts.
170
154
 
171
155
  ## What you can do with it
172
156
 
@@ -1,6 +1,6 @@
1
1
  # Agent compatibility map
2
2
 
3
- Sketchbook's CLI, configuration, contracts, generators, Git hooks and deterministic checks run without an AI provider. The model used by an agent is separate from the agent application's instruction and tool interfaces; changing model names alone cannot port integrations. This map records integration targets, not a claim of feature parity or an exhaustive list of models.
3
+ Use this map to check how your coding tool finds project guidance, which edit hooks it can run, and what has been verified. The CLI, contracts, generators, Git hooks, and checks run without an AI provider. Compatibility depends on the client’s tools and instruction interfaces as well as the model you choose.
4
4
 
5
5
  ## Install a profile
6
6
 
@@ -8,25 +8,27 @@ Plain `sketchbook init` creates a core-only project. Pass `--agent claude`, or a
8
8
 
9
9
  | `--agent` profile | Project files |
10
10
  | --- | --- |
11
- | `claude` | `CLAUDE.md` and the staged skills, commands, rules, hooks, and activation guide under `move-to-.claude/` |
12
- | `codex` | Shared guidance, `.agents/skills/sketchbook/SKILL.md`, `.codex/hooks.json`, and `.codex/sketchbook-guard.mjs` |
11
+ | `claude` | Shared component skills, `CLAUDE.md`, and the staged native wrappers, skills, commands, rules, hooks and activation guide under `move-to-.claude/` |
12
+ | `codex` | Shared guidance, `.codex/hooks.json`, and `.codex/sketchbook-guard.mjs` |
13
13
  | `gemini` | Shared guidance, `GEMINI.md`, `.gemini/settings.json`, and `.gemini/sketchbook-guard.mjs` |
14
- | `copilot` | Shared guidance, `.agents/skills/sketchbook/SKILL.md`, `.github/copilot-instructions.md`, `.github/hooks/sketchbook.json`, and `.github/hooks/sketchbook-guard.mjs` |
14
+ | `copilot` | Shared guidance, `.github/copilot-instructions.md`, `.github/hooks/sketchbook.json`, and `.github/hooks/sketchbook-guard.mjs` |
15
15
  | `trae` | Shared guidance and `.trae/rules/sketchbook.md` |
16
16
  | `jetbrains` | Shared guidance and `.aiassistant/rules/sketchbook.md` for AI Assistant chat |
17
17
  | `generic` | Shared guidance for clients that read `AGENTS.md`, such as Cursor, OpenCode, Windsurf, Kiro, and Antigravity |
18
18
 
19
- Shared guidance consists of `AGENTS.md` and `AGENT-WORKFLOWS.md`. Multiple profiles reuse those files.
19
+ Every selected profile installs the [standard Agent Skills](https://agentskills.io/specification) `contract-author` and `component-builder` under `.agents/skills/`. Profiles other than Claude also install `AGENTS.md`, `AGENT-WORKFLOWS.md`, and the `sketchbook` routing skill. These files are shared between profiles, not installed once per client. Clients without native skill loading can read the Markdown directly. Core-only init installs neither agent set.
20
+
21
+ For an existing setup, update the CLI and run `sketchbook init --dry-run` to preview missing files. Run `sketchbook init` to add them without overwriting shared team files. Use `sketchbook upgrade` to refresh harness-owned Claude wrappers. Where shared files differ, review and merge deliberately. For a legacy upgrade using `--from`, review the reported protected shared files and use the updated installed engine's `init` to add missing skills.
20
22
 
21
23
  ## Client and hook coverage
22
24
 
23
25
  | Agent / client | Instruction entry point | Current Sketchbook coverage and validation gap |
24
26
  | --- | --- | --- |
25
27
  | Antigravity IDE | `AGENTS.md` | Shared instructions and CLI; open the design-system folder as a workspace and verify discovery |
26
- | Claude Code | `CLAUDE.md`, `.claude/` | Existing staged skills, commands, rules and hooks; preserve the established integration |
27
- | OpenCode | `AGENTS.md` | Shared instructions and CLI; project configuration can be disabled; verify discovery |
28
+ | Claude Code | `CLAUDE.md`, `.claude/` | Native wrappers use the same shared component skills; commands, rules and hooks remain separate |
29
+ | OpenCode | `AGENTS.md`, `.agents/skills/` | Shared instructions and native skill activation tested in standalone and adopted scopes; project configuration can be disabled |
28
30
  | Cursor | `AGENTS.md` | Shared instructions and CLI; selected Claude-format hooks can be imported when enabled; verify version and behavior |
29
- | GitHub Copilot | `.github/copilot-instructions.md`; `AGENTS.md` in supported features | Repository instructions and a CLI/cloud create/edit guard adapter; verify client and hook activation |
31
+ | GitHub Copilot | `.github/copilot-instructions.md`, `.agents/skills/`; `AGENTS.md` in supported features | Create/edit guard tested in CLI; cloud discovery and enforcement not verified |
30
32
  | Gemini CLI | `GEMINI.md` | Shared instructions and BeforeTool adapter for supported edits; verify hook trust and activation |
31
33
  | Codex | `AGENTS.md`, `.agents/skills/` | Shared instructions, task-routing skill and native patch guard for generated files; verify skill and hook discovery |
32
34
  | Windsurf | `AGENTS.md` | Shared instructions and CLI; verify directory scope and discovery |
@@ -45,13 +47,31 @@ The same CLI, contracts, generators and checks run for every client, so test eac
45
47
  | Native hooks | The underlying generated-file and decision policies are shared where adapters use them. | Test each adapter's event format, registration, permissions and failure handling; Codex's patch guard covers a smaller scope. |
46
48
  | Agent and model behavior | CLI results and deterministic checks can be reused across clients and model families. | Test instruction-following and tool use only for representative combinations; record the exact versions and do not infer model compliance from a mock. |
47
49
 
50
+ ### Shared skill discovery by host
51
+
52
+ Model providers do not determine project discovery on their own. A model can use a skill when its host loads the instructions or when the model can read the file. Check the specific client, surface, version, workspace scope and policy.
53
+
54
+ | Host | Documented project convention | Sketchbook evidence for the shared component skills |
55
+ | --- | --- | --- |
56
+ | Anthropic Claude Code | [`.claude/skills/`](https://code.claude.com/docs/en/skills); remote surfaces have separate rules | CLI advertises the installed native wrappers; packaged tests verify both link to the same shared files. |
57
+ | OpenAI Codex | [`.agents/skills/`](https://developers.openai.com/codex/build-skills) for local project discovery | Files installed; prior client tests covered guidance and guards, not activation of the two new skills. |
58
+ | GitHub Copilot | [`.agents/skills/` and other project roots](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) depending on surface | CLI discovery tested separately from hooks; IDE and cloud discovery not verified here. |
59
+ | Google Gemini CLI | [`.agents/skills/` or `.gemini/skills/`](https://geminicli.com/docs/cli/skills/) | Files installed; prior client tests covered hooks, not activation of these skills. Check [Google's transition to Antigravity CLI](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli) separately. |
60
+ | OpenCode | [`.agents/skills/` and native or compatibility locations](https://opencode.ai/docs/skills/) | Discovery and activation exercised with a mock model in standalone and adopted projects. |
61
+ | Google Antigravity | [Workspace `.agents/` discovery](https://antigravity.google/docs/customization-discovery/) | Open the design-system workspace. Native loading not verified in the IDE or CLI. |
62
+ | Cursor | [`.agents/skills/` or `.cursor/skills/`](https://cursor.com/docs/skills) | Native loading not verified here. |
63
+ | Windsurf / Devin Desktop | [`.agents/skills/` and compatibility paths](https://docs.windsurf.com/windsurf/cascade/skills) | Native loading not verified here; check the installed client version. |
64
+ | TRAE | [`.trae/skills/` or enabled `.agents/skills/`](https://docs.trae.ai/ide/skills) | Native loading not verified; enable shared skill discovery if your edition requires it. |
65
+ | JetBrains AI Assistant | [Project `.agents/skills/` for supported agents](https://www.jetbrains.com/help/ai-assistant/agent-skills.html) | Native loading not verified here; AI Assistant chat rules are separate. |
66
+ | AWS Kiro | [Workspace `.kiro/skills/`](https://kiro.dev/docs/skills/) | The `generic` profile does not write native Kiro skill files. Use the shared files directly. |
67
+
48
68
  ## Focused checks for the remaining IDEs
49
69
 
50
70
  Use a disposable initialized project, or the design-system folder of an adopted test app. Record the client version, selected agent or chat mode, workspace folder and trust settings. Start a new session after changing rules. Inspect the client's rule or context display when available; an answer that merely mentions Sketchbook is not proof that instructions were automatically loaded. If the client cannot show that evidence, record discovery as unverified rather than repeating the full CLI suite.
51
71
 
52
72
  | Client | Distinct check |
53
73
  | --- | --- |
54
- | Antigravity | Add the nested design-system folder as a workspace and inspect Customizations for its instructions and skill. The app-root-only scope is documented separately below. |
74
+ | Antigravity | Add the nested design-system folder as a workspace and inspect Customizations for its instructions. Verify skill loading separately; use direct file reading if it isn't confirmed. |
55
75
  | Cursor | Check `AGENTS.md` in the project or nested scope being used; verify any optional Claude-hook import separately. |
56
76
  | Windsurf | Check whether the workspace-root or directory-scoped `AGENTS.md` applies to the file being edited. |
57
77
  | Kiro | Check `AGENTS.md` steering for the selected environment and agent; custom agents may have their own resource configuration. |
@@ -129,6 +149,20 @@ The harness does not call a model API or select a model. These are candidate fam
129
149
 
130
150
  The same deterministic CLI and project files are the contract for all families. Test representative component, token, accessibility and review tasks against that contract; evaluate tool use and instruction adherence separately from model availability. Do not hardcode version aliases or silently substitute one provider's models for another's.
131
151
 
152
+ ### Repeatable workflow comparison
153
+
154
+ Use the same disposable blank project, starting state and prompts for each client/model pair. Compare at least two models in the same client where possible. Keep a core-only run as the baseline. For an adopted app, repeat discovery from both the app root and the design-system folder. Keep hook coverage separate: a client that lacks a hook can still reach the same checked result by running the CLI explicitly.
155
+
156
+ | Task | Pass criteria |
157
+ | --- | --- |
158
+ | Install a catalog component | Previews with `sketchbook add button --dry-run`, verifies that the preview did not write files, installs the catalog component, and runs `sketchbook check`. |
159
+ | Change a foundation | Previews `sketchbook tokens set color.primary "#0F766E" --dry-run`, applies through the CLI without hand-editing generated files, and runs `sketchbook check`. |
160
+ | Propose a new component | Previews `sketchbook add badge --blank --dry-run`, drafts the contract from the supplied requirements and applicable accessibility references, runs `sketchbook check`, completes `plan.md`, and asks for approval without writing tests or implementation when the planning gate is enabled. |
161
+
162
+ Record the client and exact version, provider and model identifier, project scope, trust settings, loaded instructions, tested hooks, and task outcome. Score instruction discovery, hook behavior, and workflow outcome separately as **pass**, **fail**, or **not tested**. Note when success required repeating the prompt or supplying guidance manually. Only a run using the actual model can establish whether it followed the workflow; use a disposable project with no private content for hosted runs.
163
+
164
+ The core-only bootstrap test covers the CLI operations and scaffold boundary, not contract quality or an agent's decision to stop. On 2026-11-21, Claude Code 2.1.329 advertised both native wrappers, Copilot CLI 1.0.103 listed both shared skills from an adopted project, and OpenCode 2.3.2 loaded the contract-author workflow in a standalone project and component-builder in an adopted one. These checks used local test fixtures and, for session tests, mock model responses. Codex and Gemini adapter tests passed without rerunning their real-client suites. The real-model workflow comparison has not yet been run.
165
+
132
166
  ## JetBrains AI Assistant chat
133
167
 
134
168
  The generated chat rule declares `apply: always`. A static inspection of the official [AI Assistant plugin build 262.10968.63](https://plugins.jetbrains.com/plugin/download?updateId=1171905) found `.aiassistant/rules`, a leading metadata-block pattern, and the `apply` and `always` field values in its packaged classes and resources. This supports the chosen file format but does not verify rule activation. In AI Assistant, open **Settings → Tools → AI Assistant → Rules** and confirm that the Sketchbook rule is set to **Always**; inspect the response attachments to verify that it was included. For a previously initialized project, `init` and `upgrade` preserve the existing rule, so set its rule type in the IDE rather than expecting an automatic update. Project rules apply to AI Assistant chat; coding agents use their own instruction files. This configuration has not been validated in a live JetBrains session here. See [JetBrains project rules](https://www.jetbrains.com/help/ai-assistant/configure-project-rules.html).