chore(ai): added the central Claude instructions and a generalized coding skill by ArtBlue · Pull Request #511 · eBay/evo-web

ArtBlue · 2026-02-11T22:38:36Z

Description

`CLAUDE.md`

This file was generated after an /init in the repo. Claude Code took almost 11 minutes to read the entire repo and create the central instructions file. I did not make any changes, though noticed some things could be improved.

`SKILL: evo-safe-coding`

This is a high-level problem solving skill. The process to create it was involved. It was based on deep research in Notebook LM that was then condensed in ChatGPT into the skill. Its aim is to provide high-level guardrails for agents solving coding challenges.

…safe coding skill

changeset-bot · 2026-02-11T22:38:48Z

⚠️ No Changeset found

Latest commit: 7aaef67

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

Copilot

Pull request overview

Adds repository-level Claude Code guidance and introduces an org-wide “safe coding” skill to standardize agent-driven coding workflows.

Changes:

Added CLAUDE.md with repo architecture, commands, standards (BEM/WCAG), and PR checklist highlights.
Added .claude/skills/evo-safe-coding/SKILL.md defining a risk-gated workflow and “do not” rules for agent changes.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
`CLAUDE.md`	Central documentation for repo architecture, package layout, dev commands, and standards.
`.claude/skills/evo-safe-coding/SKILL.md`	Adds a reusable skill outlining safe-change workflow and guardrails for coding tasks.

CLAUDE.md

Copilot · 2026-02-11T22:39:32Z

CLAUDE.md

+**Key differences:**
+
+- `ebayui-core-react`: Uses forwardRef, CommonJS build, external MakeupJS
+- `evo-react`: React 19 native (no forwardRef), ESM-only, bundled MakeupJS


React still supports forwardRef; documenting evo-react as "no forwardRef" reads like a framework limitation rather than a codebase convention. Suggest rephrasing to clarify this is a project choice (e.g., "components typically avoid forwardRef" or "doesn’t rely on forwardRef in this package") to prevent incorrect assumptions by contributors.

Suggested change

- `evo-react`: React 19 native (no forwardRef), ESM-only, bundled MakeupJS

- `evo-react`: React 19 native (typically avoids forwardRef), ESM-only, bundled MakeupJS

agliga

Overall LGTM. Im fine approving this as is, but I did add some minor suggestions.

I went through and added some suggestions just to make things way more specific. When I saw some of these it was a bit ambiguous in certain cases and knowing AI, it could do the wrong thing

CLAUDE.md

agliga · 2026-02-12T17:07:47Z

CLAUDE.md

+cd packages/skin && npm run storybook
+cd packages/ebayui-core && npm run storybook
+cd packages/ebayui-core-react && npm run storybook


npm start should also launch storybook on these

npm start should also launch storybook on these

@agliga , npm start currently just runs the Evo Web site. Are you suggesting a change to that?

In the root, npm start runs the evo site (currently though it will also start react and marko storybook on different ports)
However in each of the packages have their own npm start. This will trigger starting storybook.

I see. So, how are you suggesting we modify this?

Change this: cd packages/ebayui-core && npm run storybook
To this?: cd packages/ebayui-core && npm start

Yes!
OR we can do

npm start -w packages/ebayui-core

From the root.

Either way is fine.

CLAUDE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

CLAUDE.md

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

HenriqueLimas

I think we should use what is going to be the standard for these files (at least for now), like AGENTS.md and the .agents/skills/ folder. Eventually claude and others will start following the standard and we can have a CLAUDE.md locally that reference the AGENTS.md like below:

CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@AGENTS.md

Since this is open source we shouldn't dictate what agents the contributor will use.

CLAUDE.md

HenriqueLimas · 2026-02-12T23:34:23Z

CLAUDE.md

+**Key differences:**
+
+- `ebayui-core-react`: Uses forwardRef, CommonJS build, external MakeupJS
+- `evo-react`: React 19 native (no forwardRef), ESM-only, bundled MakeupJS


The usage of forwardRef is an internal decision where we will use React 19 ref property instead of the current forwardRef. It should be React 19, ESM` (we don't need to have MakeupJS reference). I think we can update this one later but we also will have automatically import of .css files.

@HenriqueLimas , ok, should we just ignore the Copilot suggestion, then?

HenriqueLimas · 2026-02-12T23:35:23Z

CLAUDE.md

ui-core-react components assumes @ebay/skin is loaded, that will change on evo-web/react

CLAUDE.md

HenriqueLimas · 2026-02-12T23:39:46Z

CLAUDE.md

+**Changesets workflow:**
+
+1. Make changes to packages
+2. Run `npm run change` to create a changeset


This one tends not to work for me since they cannot iterate with changeset prompts, they usually create a manual file instead

@HenriqueLimas , when you say, "they," who are you referring to?

HenriqueLimas · 2026-02-12T23:50:00Z

CLAUDE.md

+### Migration Paths
+
+**Marko 5 → 6:**
+
+- From: `@ebay/ebayui-core`
+- To: `@evo-web/marko`
+- Status: In progress - See this PR for reference and details: https://github.com/eBay/evo-web/issues/499
+
+**React CJS → ESM:**
+
+- From: `@ebay/ui-core-react`
+- To: `@evo-web/react`
+- Status: Pre-release
+
+Legacy packages maintained for backwards compatibility.


I am wondering if this is relevant for the Agent, is more an info to the application owner that uses our packages, not for developing

@HenriqueLimas , I think it could be relevant for dev as well.

HenriqueLimas · 2026-02-12T23:51:52Z

CLAUDE.md

+## PR Checklist Highlights
+
+**All PRs:**
+
+- Build must be green
+- Changes within scope of linked issue
+- Reference issue with "Fixes #[number]"
+- Include changeset (unless docs-only)
+
+**Markup changes:**
+
+- BEM naming conventions
+- Semantic HTML5 elements
+- WCAG 2.2 AA compliance
+
+**CSS/SCSS changes:**
+
+- Regenerate `dist/` folder using `npm run build`
+- Test in all supported browsers
+- Percy visual regression approved
+- Verify dark mode and RTL support
+- Check responsive breakpoints (320px, 512px, 768px, 1024px, 1280px, 1440px, 1680px, 1920px)
+
+**Breaking changes:**
+
+- Only allowed in major version releases
+- Must be clearly documented in changeset


Not sure how relevant this is for the agent to work in the repo. This is more a guideline for a user that creates PR and something that happen after the PR. The only information that might be necessary is the Regenreate dist/folder usingnpm run build`

@HenriqueLimas , I think when tasks are handed to an agent to complete, this would probably be needed for direction. Assuming agents on Github (Claude and Codex will soon be available) are assigned an end-to-end task at some point, this will be relevant IMO.

LuLaValva · 2026-02-17T20:28:34Z

CLAUDE.md

I really don't want to be pedantic or pick a fight, but I am a little bit offended that this was the result of our last thread. It has multiple typos, and doesn't really include the details that I suggested.

Agree with this.
Note to AI: never spell Marko with a c otherwise you will get the Marko team upset

@LuLaValva , my bad for the typos. Context switching is not just bad for agents. 😉

I don't see it as pedantic or "picking a fight." Apologies, I should have relayed this earlier. I wasn't intentionally trying to ignore your suggestion. They're good adjustments.

ebayui-core uses Marko 5 and the Class API, while evo-web uses Marko 6 and the Tags API

The issue here is that it's too vague and adds references to concepts that Claude and other agents have little to no knowledge about, so this would actually be counterproductive to be included in the main agent instructions by itself. To include it we would need to add a section about each and explain their differences in some detail, preferably with direct examples or references to those details and examples.

We can work together offline to come up with that content or if you'd prefer, you can simply use the "suggest change" feature to suggest exactly what we should capture.

agliga

Did another pass. I added a lot of suggestions and some questions.
IMO its looking much better now.

agliga · 2026-02-18T17:23:37Z

CLAUDE.md

+├── index.marko              # Template with TypeScript interfaces
+├── component.ts             # Lifecycle and behavior (optional)
+├── component-browser.ts             # Client side only lifecycle and behavior  (optional)
+├── marko-tag.json          # Attribute validation


This isn't needed anymore since we moved off of marko 4

Suggested change

├── marko-tag.json # Attribute validation

agliga · 2026-02-18T17:24:58Z

CLAUDE.md

+├── component-browser.ts             # Client side only lifecycle and behavior  (optional)
+├── marko-tag.json          # Attribute validation
+├── style.ts                # Imports Skin CSS
+├── browser.json            # Build remapping


Suggested change

├── browser.json # Build remapping

├── browser.json # Lasso configuration

Also Im thinking this might not be needed. This was used in certain cases where people did not want to have our imports.
Next major version these should be removed

agliga · 2026-02-18T17:26:26Z

CLAUDE.md

+**Style Conventions**
+See `./packages/skin/STYLEGUIDE.md` for detailed style conventions.
+
+**PostCSS pipeline:** Sass → PostCSS → Autoprefixer → cssnano → `dist/`


Suggested change

**PostCSS pipeline:** Sass → PostCSS → Autoprefixer → cssnano → `dist/`

**CSS build pipeline:** Sass → PostCSS → Autoprefixer → cssnano → `dist/`

agliga · 2026-02-18T17:27:19Z

CLAUDE.md

+- Ensure keyboard operability for all interactive elements
+- Maintain focus states and sufficient color contrast
+- Test in both light and dark modes
+- Support RTL (right-to-left) layouts


Should we add a section here about font text size and supporting that? Like font zoom

agliga · 2026-02-18T17:28:16Z

CLAUDE.md

+**Required for all components:**
+
+- Adequate test coverage for new/modified code
+- Browser tests (Marko) or jsdom tests (React)


Suggested change

- Browser tests (Marko) or jsdom tests (React)

- Server snapshot tests (Marko/React)

- Browser tests (Marko) or jsdom tests (React)

agliga · 2026-02-18T17:37:48Z

CLAUDE.md

+cd packages/skin && npm run storybook
+cd packages/ebayui-core && npm run storybook
+cd packages/ebayui-core-react && npm run storybook


Yes!
OR we can do

npm start -w packages/ebayui-core

From the root.

Either way is fine.

agliga · 2026-02-18T17:39:34Z

CLAUDE.md

+
+```bash
+# Marko browser test
+npx vitest run packages/ebayui-core/src/components/ebay-button/test/test.browser.js


This is incorrect. Running this locally fails.
Here's the correct command

Suggested change

npx vitest run packages/ebayui-core/src/components/ebay-button/test/test.browser.js

npm test -w packages/ebayui-core -- src/components/ebay-button/test/test.browser.js

agliga · 2026-02-18T17:40:11Z

CLAUDE.md

+npx vitest run packages/ebayui-core/src/components/ebay-button/test/test.browser.js
+
+# React test
+npx vitest run packages/ebayui-core-react/src/ebay-button/__tests__/index.spec.tsx


Same with this:

Suggested change

npx vitest run packages/ebayui-core-react/src/ebay-button/__tests__/index.spec.tsx

npm test -w packages/ebayui-core-react -- src/ebay-button/__tests__/index.spec.tsx

agliga · 2026-02-18T17:41:07Z

CLAUDE.md

Agree with this.
Note to AI: never spell Marko with a c otherwise you will get the Marko team upset

agliga · 2026-02-18T17:41:48Z

CLAUDE.md

+- Test in all supported browsers
+- Percy visual regression approved
+- Verify dark mode and RTL support
+- Check responsive breakpoints (320px, 512px, 768px, 1024px, 1280px, 1440px, 1680px, 1920px)


If we want to test the font zoom as well, add it here too

chore(ai): added the central Claude instructions and the generalized …

72e93c4

…safe coding skill

ArtBlue requested review from HenriqueLimas, LuLaValva, agliga, ianmcburnie and saiponnada February 11, 2026 22:38

ArtBlue self-assigned this Feb 11, 2026

Copilot AI review requested due to automatic review settings February 11, 2026 22:38

Copilot AI reviewed Feb 11, 2026

View reviewed changes

agliga reviewed Feb 12, 2026

View reviewed changes

Corrected React legacy package

402563a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

LuLaValva reviewed Feb 12, 2026

View reviewed changes

CLAUDE.md Outdated Show resolved Hide resolved

CLAUDE.md Outdated Show resolved Hide resolved

ArtBlue and others added 2 commits February 12, 2026 09:57

Fixed incorrect syntax usage.

0379d07

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

Make stories more explicit for Skin only.

71d78d6

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

agliga added the documentation label Feb 12, 2026

ArtBlue and others added 5 commits February 12, 2026 10:57

Added client side info

43e440e

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

Avoid Makeup since it's being phased out.

435ed12

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

Made comment more explicit.

309ec59

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

More explicit context

ebb549c

Co-authored-by: Andrew Gliga <agliga4@gmail.com>

fix(ai): updated instructions per PR feedback

fcdc699

HenriqueLimas reviewed Feb 12, 2026

View reviewed changes

ArtBlue added 2 commits February 17, 2026 08:21

chore(ai): removed code guidance in lieu of the reference to the source

19947a2

chore(ai): made PR feedback adjustments

e1ac62c

LuLaValva reviewed Feb 17, 2026

View reviewed changes

agliga mentioned this pull request Feb 18, 2026

docs: added ai context bank (experimental) #513

Open

agliga reviewed Feb 18, 2026

View reviewed changes

fix(au): fixed typos

7aaef67

	- `evo-react`: React 19 native (no forwardRef), ESM-only, bundled MakeupJS
	- `evo-react`: React 19 native (typically avoids forwardRef), ESM-only, bundled MakeupJS

	├── browser.json # Build remapping
	├── browser.json # Lasso configuration

	PostCSS pipeline: Sass → PostCSS → Autoprefixer → cssnano → `dist/`
	CSS build pipeline: Sass → PostCSS → Autoprefixer → cssnano → `dist/`

	- Browser tests (Marko) or jsdom tests (React)
	- Server snapshot tests (Marko/React)
	- Browser tests (Marko) or jsdom tests (React)

	npx vitest run packages/ebayui-core/src/components/ebay-button/test/test.browser.js
	npm test -w packages/ebayui-core -- src/components/ebay-button/test/test.browser.js

	npx vitest run packages/ebayui-core-react/src/ebay-button/__tests__/index.spec.tsx
	npm test -w packages/ebayui-core-react -- src/ebay-button/__tests__/index.spec.tsx

Conversation

ArtBlue commented Feb 11, 2026

Description

CLAUDE.md

SKILL: evo-safe-coding

Uh oh!

changeset-bot bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

agliga left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agliga Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HenriqueLimas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agliga left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

`CLAUDE.md`

`SKILL: evo-safe-coding`

changeset-bot bot commented Feb 11, 2026 •

edited

Loading

agliga Feb 12, 2026 •

edited

Loading