@usesketchbook/cli 0.3.0 → 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.
- package/.agents/skills/component-builder/SKILL.md +16 -0
- package/.agents/skills/contract-author/SKILL.md +16 -0
- package/.claude/commands/add.md +1 -5
- package/.claude/skills/component-builder/SKILL.md +15 -101
- package/.claude/skills/contract-author/SKILL.md +14 -132
- package/README.md +1 -1
- package/docs/agent-compatibility.md +42 -8
- package/harness/cli/commands/add.mjs +1 -1
- package/harness/cli/commands/api.d.mts +4 -4
- package/harness/cli/commands/check.d.mts +1 -1
- package/harness/cli/commands/init.d.mts +1 -1
- package/harness/cli.mjs +0 -0
- package/harness/commands/add.mjs +1 -1
- package/harness/commands/bootstrap.mjs +4 -3
- package/harness/lib/agent-config.d.mts +1 -0
- package/harness/lib/agent-config.mjs +7 -6
- package/harness/lib/design/sync.d.mts +1 -1
- package/harness/lib/installed.mjs +2 -0
- package/harness/manifest.json +3 -1
- package/harness/templates/CLAUDE.md +1 -1
- package/harness/templates/project/.agents/skills/sketchbook/SKILL.md +1 -1
- package/harness/templates/project/AGENT-WORKFLOWS.md +2 -2
- package/harness/templates/project/docs/getting-started.md +2 -2
- package/harness/templates/project/package-lock.json +2 -2
- package/harness/test/agent-config.test.mjs +21 -1
- package/harness/test/agent-guidance.test.mjs +16 -0
- package/harness/test/bootstrap.test.mjs +84 -15
- package/harness/test/claude-live.test.mjs +8 -3
- package/harness/test/copilot-live.test.mjs +12 -13
- package/harness/test/docs-reference.test.mjs +17 -0
- package/harness/test/opencode-live.test.mjs +25 -10
- package/harness/test/package.test.mjs +1 -0
- 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.
|
package/.claude/commands/add.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
5
|
-
|
|
6
|
-
|
|
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.
|
|
12
|
-
changelog:
|
|
13
|
-
|
|
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
|
-
#
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
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
|
-
- [
|
|
120
|
-
-
|
|
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
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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.
|
|
12
|
-
changelog:
|
|
13
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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
|
-
- [
|
|
154
|
-
-
|
|
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
|
@@ -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`
|
|
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
|
|
|
@@ -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
|
|
12
|
-
| `codex` | Shared guidance, `.
|
|
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, `.
|
|
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
|
-
|
|
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/` |
|
|
27
|
-
| OpenCode | `AGENTS.md
|
|
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
|
|
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
|
|
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).
|
|
@@ -45,7 +45,7 @@ export default {
|
|
|
45
45
|
};
|
|
46
46
|
}
|
|
47
47
|
const r = await scaffold(root, display, { dryRun });
|
|
48
|
-
const next = 'Draft the contract
|
|
48
|
+
const next = 'Draft the contract from the design and accessibility references, then run npm run check. If the planning gate is enabled, fill plan.md and stop for approval before implementation.';
|
|
49
49
|
if (dryRun)
|
|
50
50
|
out(`Would scaffold spec/components/${r.name}/ (${r.tag}) and write:\n ${r.files.join('\n ')}`);
|
|
51
51
|
else
|
|
@@ -47,15 +47,15 @@ declare const _default: {
|
|
|
47
47
|
} | {
|
|
48
48
|
data: {
|
|
49
49
|
entry: {
|
|
50
|
-
|
|
51
|
-
values?: string | string[];
|
|
50
|
+
kind: "text" | "icon" | "slot";
|
|
52
51
|
meaning: string;
|
|
53
52
|
figma: null | import("../../../generated/types/api.js").Figma;
|
|
54
|
-
proposal?: boolean;
|
|
55
53
|
} | {
|
|
56
|
-
|
|
54
|
+
type: "variant" | "boolean" | "text" | "number";
|
|
55
|
+
values?: string | string[];
|
|
57
56
|
meaning: string;
|
|
58
57
|
figma: null | import("../../../generated/types/api.js").Figma;
|
|
58
|
+
proposal?: boolean;
|
|
59
59
|
} | null;
|
|
60
60
|
used: import("../../lib/api.mjs").PropRow[];
|
|
61
61
|
aspects?: undefined;
|
|
@@ -226,7 +226,7 @@ declare const _default: {
|
|
|
226
226
|
exitCode?: undefined;
|
|
227
227
|
} | {
|
|
228
228
|
changed: string[];
|
|
229
|
-
warnings: (
|
|
229
|
+
warnings: (import("../types.mjs").EnvelopeIssue | IssueLike)[];
|
|
230
230
|
errors: import("../types.mjs").EnvelopeIssue[];
|
|
231
231
|
exitCode: number;
|
|
232
232
|
next: string;
|
package/harness/cli.mjs
CHANGED
|
File without changes
|
package/harness/commands/add.mjs
CHANGED
|
@@ -52,7 +52,7 @@ export async function add(root, displayName, { dryRun = false } = {}) {
|
|
|
52
52
|
accessibility: { role: 'PROPOSAL', accessibleNameSource: 'PROPOSAL', keyboard: {}, aria: [], contrast: [] },
|
|
53
53
|
tokens: {},
|
|
54
54
|
realizations: { web: { status: 'not-started', files: [], spec: `playwright/tests/${name}/${name}.behavior.spec.ts`, coverage: [], drift: [] }, design: { status: 'not-started', coverage: [], drift: [] } },
|
|
55
|
-
openQuestions: [{ id: 'Q0', question: '
|
|
55
|
+
openQuestions: [{ id: 'Q0', question: 'Is the contract grounded in the design reference and applicable WAI-ARIA guidance?', status: 'open' }],
|
|
56
56
|
decisions: [],
|
|
57
57
|
};
|
|
58
58
|
const md = `---\ncomponent: ${component}\nstatus: draft\nversion: 0.1.0\nplatforms: [web, design]\ndependsOn: []\nlast_updated: ${today()}\nsource: shadcn/ui ${entry.name} (UI and API), harness process\n---\n\n# ${component}\n\n> PROPOSAL. Typed spec: [contract.json](./contract.json).\n\n## 1. Purpose\n\n## 2. Anatomy\n\n## 3. Props / API\n\n## 4. Variant matrix\n\n## 5. Roles and color\n\n## 6. States\n\n## 7. Dimensions and layout\n\n## 8. Typography\n\n## 9. Accessibility\n\n## 10. Usage\n### Behavior\n### Composition\n### Choosing the props\n### Do / Don't\n\n## Realizations\n### Figma\nNot started.\n### Web\nNot started.\n### Coverage\nNone yet.\n### Known drift\nNone.\n\n## Open questions\n\n## Spec for agents\nBuild from contract.json only. CSS uses only --${config.prefix}-${name}-* variables (check T4). Tests first (rule test-first).\n`;
|
|
@@ -14,7 +14,7 @@ import { runChecks } from '../checks/run.mjs';
|
|
|
14
14
|
import { installed, installedMarkdown } from '../lib/installed.mjs';
|
|
15
15
|
import { hookScript, readClaudeSettings } from '../lib/claude-layer.mjs';
|
|
16
16
|
import { emptyLog, inheritDecisions } from '../lib/decisions.mjs';
|
|
17
|
-
import { AGENT_ENGINE_FILES, agentFileState, claudeDestination, hasClaudeLayer, isAgentFile, profileFiles, renderAgentSetup, selectedAgentProfiles, STAGED } from '../lib/agent-config.mjs';
|
|
17
|
+
import { AGENT_ENGINE_FILES, agentFileState, claudeDestination, hasClaudeLayer, isAgentFile, profileFiles, renderAgentSetup, selectedAgentProfiles, STAGED, WORKFLOW_SKILLS } from '../lib/agent-config.mjs';
|
|
18
18
|
export { STAGED };
|
|
19
19
|
const TEMPLATE = join(HARNESS, 'templates/project');
|
|
20
20
|
const IGNORED = new Set(['.git', '.DS_Store']);
|
|
@@ -97,7 +97,8 @@ export function syncHarness(root, { all = false, dryRun = false, agentsOnly = fa
|
|
|
97
97
|
copy(join(ENGINE, file), file, { owned: true });
|
|
98
98
|
}
|
|
99
99
|
for (const file of profileFiles(profiles)) {
|
|
100
|
-
const source = file === 'CLAUDE.md' ? join(HARNESS, 'templates', file)
|
|
100
|
+
const source = file === 'CLAUDE.md' ? join(HARNESS, 'templates', file)
|
|
101
|
+
: join(WORKFLOW_SKILLS.includes(file) ? ENGINE : TEMPLATE, file);
|
|
101
102
|
copy(source, file, { agent: true });
|
|
102
103
|
}
|
|
103
104
|
if (profiles.includes('claude')) {
|
|
@@ -221,7 +222,7 @@ export const engineSpec = (given, cwd = process.cwd()) => {
|
|
|
221
222
|
function projectPackage(name, spec) {
|
|
222
223
|
const engine = enginePkg();
|
|
223
224
|
const omit = (o, keys) => Object.fromEntries(Object.entries(o ?? {}).filter(([k]) => !keys.includes(k)));
|
|
224
|
-
const files = (engine.files ?? []).filter((p) => !/^(harness|scripts|\.claude|\.githooks|docs|spec)(\/|$)/.test(p));
|
|
225
|
+
const files = (engine.files ?? []).filter((p) => !/^(harness|scripts|\.agents|\.claude|\.githooks|docs|spec)(\/|$)/.test(p));
|
|
225
226
|
// The engine's peers (lit) are what the project's components import: the project depends on them, at the engine's pins.
|
|
226
227
|
const peers = Object.keys(engine.peerDependencies ?? {});
|
|
227
228
|
const pinnedPeers = Object.fromEntries(peers.map((k) => [k, engine.devDependencies?.[k] ?? engine.peerDependencies?.[k]]));
|