[ruudandriessen]

Why

Claude Code and Cursor load the root CLAUDE.md into every session, whichever package you work in. It is about 490 lines, mostly about apollo-react, apollo-wind, Storybook and the overall architecture. A session in packages/apollo-vertex got all of that on top of its own AGENTS.md.

This PR keeps only the repo-wide rules at the root. Everything else moves next to the code it's about, using the AGENTS.md plus CLAUDE.md (@AGENTS.md) pattern already used by the vertex folders. No rule text changes.

Before	After
Root instructions: 487 lines	Root instructions: 66 lines
Session in packages/apollo-vertex: about 790 lines	Session in packages/apollo-vertex: about 370 lines

Where each section went

Section of the old root CLAUDE.md	New home
Verified docs, think critically, plan before acting, pause on unknowns, fixup/rebase git workflow	Root AGENTS.md, unchanged, plus a map of where package instructions live
Styling Standards (apollo-react)	packages/apollo-react/AGENTS.md, unchanged
No em dashes in Storybook copy	apps/storybook/AGENTS.md, with a one-line reminder in apollo-react and apollo-wind, where the stories live
Architecture overview (stack, structure, tokens, CI, release, migration path)	docs/architecture.md, not loaded into agent context
Pointer to DESIGN-CONTEXT.md	packages/apollo-vertex/AGENTS.md, since the file is about Apollo Vertex

Root CLAUDE.md is now @AGENTS.md, so Claude Code and tools that read AGENTS.md (Cursor, Codex) see the same content.

Review notes

• Em dash rule scope. It used to list apollo-core and apollo-ui-icons, but those packages have no .stories.tsx files. Stories exist only in apollo-react, apollo-wind and apps/storybook, so the rule now names those.
• Wording changes in docs/architecture.md. The text is otherwise moved unchanged, apart from the self-reference to CLAUDE.md in the structure tree and five uses of "development". The local secret scanner flagged those as matching a configured environment value, so they were reworded without changing meaning ("Contributor Workflow", "Watch mode", and so on).
• Stale content. The architecture overview was already partly out of date: the workflow file names, the "Changesets or semantic-release" choice, and missing apps such as apollo-vertex. It is moved as-is so this PR stays a move. Updating it can be a follow-up.
• New package files. packages/apollo-react/AGENTS.md, packages/apollo-wind/AGENTS.md and apps/storybook/AGENTS.md add a short "where things live" section and commands, taken from each package.json and the current folder layout.

If you want zero root instructions locally

Claude Code users can still drop the root file entirely with claudeMdExcludes in .claude/settings.local.json (docs).

  

[Copilot]

🟢 Approval recommended

The documentation-only reorganization preserves the intended guidance and has no identified blocking issues.

No open issues 🎉

What changed in this PR

This documentation-only PR reduces default agent context by keeping shared rules at the repository root and placing package-specific guidance beside the relevant code.

Changes:

• Consolidates root rules in AGENTS.md, with CLAUDE.md importing it.
• Adds local guidance and Claude imports for apollo-react, apollo-wind, and Storybook.
• Moves the architecture reference into docs/architecture.md and scopes the design-context pointer to Apollo Vertex.

File	Description
packages/​apollo-wind/​CLAUDE.md	Imports local agent guidance.
packages/​apollo-wind/​AGENTS.md	Adds package layout, commands, and Storybook copy guidance.
packages/​apollo-vertex/​AGENTS.md	Adds the root design-context reference.
packages/​apollo-react/​CLAUDE.md	Imports local agent guidance.
packages/​apollo-react/​AGENTS.md	Houses styling rules, package layout, and commands.
docs/​architecture.md	Holds the relocated architecture reference.
CLAUDE.md	Replaces the lengthy root content with an AGENTS.md import.
apps/​storybook/​CLAUDE.md	Imports local agent guidance.
apps/​storybook/​AGENTS.md	Documents app layout and Storybook copy rules.
AGENTS.md	Centralizes shared rules and maps package guidance.

_{Review effort: Balanced}

[github-actions]

Dependency License Review

• ✅ 1957 package(s) scanned
• ✅ No license issues found
• ⚠️ 2 package(s) excluded (see details below)

License distribution

License	Packages
MIT	1721
ISC	91
Apache-2.0	57
BSD-3-Clause	28
BSD-2-Clause	23
BlueOak-1.0.0	8
MPL-2.0	4
CC0-1.0	4
MIT-0	3
MIT OR Apache-2.0	2
(MIT OR Apache-2.0)	2
Unlicense	2
LGPL-3.0-or-later	1
Python-2.0	1
CC-BY-4.0	1
(MPL-2.0 OR Apache-2.0)	1
Unknown	1
Artistic-2.0	1
(WTFPL OR MIT)	1
(BSD-2-Clause OR MIT OR Apache-2.0)	1
CC-BY-3.0	1
0BSD	1
(MIT OR CC0-1.0)	1
MIT AND ISC	1

Excluded packages

Package	Version	License	Reason
@img/sharp-libvips-linux-x64	1.3.4	LGPL-3.0-or-later	LGPL pre-built binary, not linked
khroma	2.1.0	Unknown	MIT per GitHub repo, missing license field in package.json

[github-actions]

Storybook visual diff

⏭️ Skipped: the apollo-design preview deployment did not succeed, so no comparison ran. Logs

Updated (PT): Oct 26, 2026, 01:56:48 AM

[github-actions]

📊 Coverage + size by package

Per-package bundle size on this PR (no JS/TS source changes detected under packages/* or web-packages/*).

Package	Coverage	New-line coverage	Packed (gzip)	Unpacked	vs main
@uipath/apollo-core	—	—	42.02 MB	50.17 MB	±0
@uipath/apollo-react	58.4%	—	8.14 MB	32.18 MB	+336 B
@uipath/apollo-ui-icons	—	—	2.86 MB	6.97 MB	±0
@uipath/apollo-vertex	85.5%	—	336.8 KB	1.88 MB	±0
@uipath/apollo-wind	79.5%	—	814.7 KB	4.70 MB	−7 B
@uipath/ap-chat	85.8%	—	40.42 MB	45.72 MB	±0

_{"Coverage" is each package's own coverage.include scope (e.g. apollo-core instruments only scripts/). "Packed"/"Unpacked" come from npm pack --dry-run and only cover built packages — "—" means not measured this run (package not affected / not built). "vs main" is the packed (gzipped) delta against the last successful main build (the package-sizes artifact from the Release workflow); "—" there means no main baseline was available this run. The baseline is main's latest build, not this PR's exact merge-base, so it includes any drift since the branch diverged. Packages with no vitest config are omitted.}