CLAUDE.md

1# CLAUDE.md
2 
3Claude adapter for Middle Earth AI instructions. This file is generated from canonical `.ai/`.
4 
5## Equality rule
6 
7- Cursor, Claude, and Codex are configured as equals.
8- Capability parity is mandatory across all three.
9- Canonical source remains tool-agnostic in `.ai/`.
10 
11## Claude runtime
12 
13- Baseline settings: `.claude/settings.json`
14- Skills: `.claude/skills/*/SKILL.md`
15- Agents: `.claude/agents/*.md`
16 
17## Required workflow
18 
191. Update canonical docs under `.ai/`.
202. Run `pnpm ai:sync`.
213. Run `pnpm ai:check`.
22 
23## Canonical references
24 
25- `.ai/README.md`
26- `.ai/DEFINITIONS.md`
27- `.ai/STANDARDS.md`
28- `.ai/PARITY_MATRIX.md`
29- `.ai/PROJECT_CONTEXT.md`
30 
31## Capability counts
32 
33- Rules: 11
34- Skills: 8
35- Agents/Roles: 2
36 
37# Middle Earth Project Context
38 
39Project-specific knowledge for AI assistants working on Middle Earth. This content is appended to the generated CLAUDE.md adapter.
40 
41## Project Overview
42 
43Middle Earth is a monorepo for Carrot Foundation's publishable libraries. It contains shared packages consumed by other Carrot repos. There are no applications — only publishable libraries.
44 
45- **@carrot-foundation/eslint-config-carrot** — Shared ESLint configuration
46- **@carrot-foundation/web-logger** — Pino-based logger utility for web applications
47- **@carrot-foundation/web-ui** — React UI component library (MUI-based, atomic design)
48 
49## Technology Stack
50 
51- **Monorepo**: Nx 21.6.3 workspace with pnpm 10.2.0
52- **Node**: 22.20.0 (see `.nvmrc`)
53- **Language**: TypeScript 5.3.3 (strict mode, verbatimModuleSyntax)
54- **Frontend**: React 19, Next.js 15.5.4, MUI 7.x
55- **Logging**: Pino 10.x
56- **Build**: SWC (swc/cli, swc/core)
57- **Testing**: Jest 29.4.1 with @nx/jest
58- **Linting**: ESLint 8.56.0 (Airbnb, SonarJS, Unicorn, Security, Perfectionist, Prettier)
59- **Release**: Semantic Release 22.0.12 with independent versioning
60- **Git Hooks**: Husky 9.x with lint-staged
61- **Commit Linting**: Commitlint with cz-git
62 
63## Architecture
64 
65### Directory Structure
66 
67```
68libs/publishable/
69  eslint-config-carrot/     # @carrot-foundation/eslint-config-carrot
70  web/
71    logger/                 # @carrot-foundation/web-logger
72    ui/                     # @carrot-foundation/web-ui
73      src/lib/
74        atoms/              # Basic components (Button, Icons)
75        molecules/          # Composed components (Share)
76        theme/              # Theme configuration and providers
77```
78 
79### Path Aliases
80 
81Defined in `tsconfig.base.json`:
82 
83- `@middle-earth/libs/publishable/eslint-config-carrot`
84- `@middle-earth/libs/publishable/web/logger`
85- `@middle-earth/libs/publishable/web/ui`
86 
87### UI Library (web-ui)
88 
89- Follows **atomic design**: atoms, molecules, theme
90- Built on **MUI 7.x** with custom theme
91- Uses **React 19** features
92 
93### Key Constraints
94 
95- **Libraries only**: No application code — all libraries in `libs/publishable/`
96- **Publishable**: All libraries are published to npm under `@carrot-foundation/`
97- **Independent versioning**: Each library versioned separately via semantic-release
98- **Path aliases required**: Use `@middle-earth/libs/publishable/*`, NOT relative `../../..`
99 
100## Common Commands
101 
102### Development
103 
104```bash
105# Build a library
106pnpm nx build <project-name>
107 
108# Run tests
109pnpm nx test <project-name>
110 
111# Run linting
112pnpm nx lint <project-name>
113```
114 
115### Affected Commands
116 
117```bash
118# Lint affected projects
119pnpm lint:affected                     # nx affected --target lint --fix
120 
121# Test affected projects (not available — use nx directly)
122pnpm nx affected --target test
123 
124# Build affected projects (not available — use nx directly)
125pnpm nx affected --target build
126```
127 
128### Utilities
129 
130```bash
131# Commitizen (guided commit message)
132pnpm commit                            # czg
133 
134# Validate package.json files
135pnpm pkgJsonLint                       # npmPkgJsonLint .
136 
137# Spell check
138pnpm spellcheck                        # cspell (if configured)
139```
140 
141## Code Standards
142 
143**Baseline standards**: see `.ai/rules/` for all rules.
144 
145### TypeScript
146 
147- **Strict mode**: `strict: true`, `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`
148- **Imports**: Use path aliases (`@middle-earth/libs/publishable/*`), NOT relative `../../..`
149- **No `any`**: Favor precise types and narrowing
150- **Return types**: Explicit for exported functions and public APIs
151- **File organization**: `*.constants.ts`, `*.helpers.ts`, `*.types.ts`
152 
153### Testing
154 
155- **Jest** as test runner (NOT Vitest)
156- **Unit tests**: `*.spec.ts(x)` in `__tests__/` folders
157- **Mocking**: `jest.mock` for modules, `jest.spyOn` for side effects
158- **Table-driven tests**: `it.each` for input/output matrices
159- **Coverage**: Aim for 100% where feasible
160 
161## Commit Message Guidelines
162 
163### Quick Reference
164 
165- **Format**: `<type>(optional scope): <description>`
166- **Types**: `feat`, `fix`, `refactor`, `docs`, `test`, `style`, `perf`, `build`, `ci`, `chore`, `revert`
167- **Imperative mood**: "add", "fix", "update" (NOT "added", "fixed", "updated")
168- **Lowercase**: Description starts with lowercase letter
169- **No period**: Description does NOT end with a period
170 
171### Middle Earth Scopes
172 
173- **`config`**: Root-level configuration files (nx.json, tsconfig.base.json, ESLint, commitlint)
174- **`lib`**: Libraries in `libs/publishable/`
175- **`release`**: Versioning, releases, publishing
176- **`ai`**: AI instructions and rules
177 
178### Examples
179 
180```
181feat(lib): add Button component to UI library
182chore(config): update ESLint rules for TypeScript files
183chore(release): bump eslint-config-carrot to 0.9.0
184refactor(lib): simplify logger initialization
185```
186 
187## Nx Configuration
188 
189- **Plugins**: @nx/eslint/plugin, @nx/jest/plugin
190- **Default Base**: main branch
191- **Build**: `@nx/js:swc` compiler
192- **Targets per library**: build, lint, test, types, package, publish, release
193- **Project Tags**: `type:lib`
194 
195## Important Notes
196 
197- **Package Manager**: pnpm ONLY (enforced by `preinstall` script)
198- **Node Version**: 22.20.0 (check `.nvmrc`)
199- **Husky Hooks**: Git hooks for pre-commit linting via lint-staged
200- **Renovate**: Dependency updates automated with config in `renovate.json`
201- **No Docker**: Libraries only — no container builds
202- **No Infrastructure**: No Terraform, no AWS resources
203 
204## Troubleshooting
205 
206### Clear Caches
207 
208```bash
209pnpm nx reset
210```
211 
212### Dependency Issues
213 
214```bash
215rm -rf node_modules pnpm-lock.yaml
216pnpm install
217```
218