AGENTS.md

1# AGENTS.md
2 
3Middle Earth AI instructions for Codex, Claude, and Cursor with equal capability parity.
4 
5## Equality rule
6 
7- Cursor, Claude, and Codex are treated as equals.
8- No platform is primary for instruction definition.
9- Canonical source: `.ai/`.
10 
11## Canonical workflow
12 
131. Edit canonical files in `.ai/`.
142. Run `pnpm ai:sync` to regenerate platform adapters.
153. Run `pnpm ai:check` to validate parity and links.
16 
17## Current capability counts
18 
19- Rules: 11
20- Skills: 8
21- Agents/Roles: 2
22 
23## Available skills
24 
25- `check` - Run Middle Earth quality gates (lint, test, build) without committing. Runs AI instruction checks when .ai/ files are affected.
26- `commit` - Commit Changes
27- `create-branch` - Create Branch
28- `create-pr` - Create Pull Request
29- `debug` - Structured debugging workflow for errors, test failures, build issues, and unexpected behavior in the Middle Earth monorepo.
30- `finish-work` - End-to-end workflow to ship code changes as a PR. Creates branch, runs quality gates, commits changes, and creates PR.
31- `review-pr` - Review pull requests for quality, correctness, and adherence to Middle Earth project standards.
32- `unit-test` - Run and write Jest unit tests following Middle Earth patterns.
33 
34## Rule mappings
35 
36- `rule-bmad` - BMAD tool/output split and per-app artifact convention for Middle Earth
37- `rule-branch-naming` - Git branch naming conventions aligned with Conventional Commits
38- `rule-code-comments` - Code comment guidelines for all languages
39- `rule-code-preservation` - Code preservation rules - never delete or revert code without explicit approval
40- `rule-code-style` - Middle Earth code style conventions (TypeScript/JavaScript)
41- `rule-commit` - Conventional Commit message standards with Middle Earth scopes
42- `rule-documentation` - Markdown documentation standards
43- `rule-pull-request` - Pull request workflow and quality standards
44- `rule-pull-request-description` - Pull request description format and content standards
45- `rule-testing` - Middle Earth testing baseline guidelines (unit tests with Jest)
46- `rule-typescript` - Middle Earth TypeScript baseline guidelines (compiler, modules, best practices)
47 
48## Agent roles
49 
50- `debugger` - Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when you hit failures that need root-cause analysis.
51- `verifier` - Validates completed work. Use after tasks are marked done to confirm implementations are functional and meet project standards.
52 
53## Canonical references
54 
55- `.ai/README.md`
56- `.ai/DEFINITIONS.md`
57- `.ai/STANDARDS.md`
58- `.ai/PARITY_MATRIX.md`
59- `.ai/PROJECT_CONTEXT.md`
60 
61## Runtime adapter paths
62 
63- Cursor: `.cursor/rules/`, `.cursor/skills/`, `.cursor/agents/`
64- Claude: `.claude/settings.json`, `.claude/skills/`, `.claude/agents/`
65- Codex: `.agents/skills/`, `AGENTS.md`
66 
67## Setup commands (workspace)
68 
69- Install deps: `pnpm install`
70- Run lint (affected): `pnpm lint:affected`
71- Run tests: `pnpm nx affected --target test`
72- Build: `pnpm nx affected --target build`
73- Validate AI instructions: `pnpm ai:check`
74 
75# Middle Earth Project Context
76 
77Project-specific knowledge for AI assistants working on Middle Earth. This content is appended to the generated CLAUDE.md adapter.
78 
79## Project Overview
80 
81Middle 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.
82 
83- **@carrot-foundation/eslint-config-carrot** — Shared ESLint configuration
84- **@carrot-foundation/web-logger** — Pino-based logger utility for web applications
85- **@carrot-foundation/web-ui** — React UI component library (MUI-based, atomic design)
86 
87## Technology Stack
88 
89- **Monorepo**: Nx 21.6.3 workspace with pnpm 10.2.0
90- **Node**: 22.20.0 (see `.nvmrc`)
91- **Language**: TypeScript 5.3.3 (strict mode, verbatimModuleSyntax)
92- **Frontend**: React 19, Next.js 15.5.4, MUI 7.x
93- **Logging**: Pino 10.x
94- **Build**: SWC (swc/cli, swc/core)
95- **Testing**: Jest 29.4.1 with @nx/jest
96- **Linting**: ESLint 8.56.0 (Airbnb, SonarJS, Unicorn, Security, Perfectionist, Prettier)
97- **Release**: Semantic Release 22.0.12 with independent versioning
98- **Git Hooks**: Husky 9.x with lint-staged
99- **Commit Linting**: Commitlint with cz-git
100 
101## Architecture
102 
103### Directory Structure
104 
105```
106libs/publishable/
107  eslint-config-carrot/     # @carrot-foundation/eslint-config-carrot
108  web/
109    logger/                 # @carrot-foundation/web-logger
110    ui/                     # @carrot-foundation/web-ui
111      src/lib/
112        atoms/              # Basic components (Button, Icons)
113        molecules/          # Composed components (Share)
114        theme/              # Theme configuration and providers
115```
116 
117### Path Aliases
118 
119Defined in `tsconfig.base.json`:
120 
121- `@middle-earth/libs/publishable/eslint-config-carrot`
122- `@middle-earth/libs/publishable/web/logger`
123- `@middle-earth/libs/publishable/web/ui`
124 
125### UI Library (web-ui)
126 
127- Follows **atomic design**: atoms, molecules, theme
128- Built on **MUI 7.x** with custom theme
129- Uses **React 19** features
130 
131### Key Constraints
132 
133- **Libraries only**: No application code — all libraries in `libs/publishable/`
134- **Publishable**: All libraries are published to npm under `@carrot-foundation/`
135- **Independent versioning**: Each library versioned separately via semantic-release
136- **Path aliases required**: Use `@middle-earth/libs/publishable/*`, NOT relative `../../..`
137 
138## Common Commands
139 
140### Development
141 
142```bash
143# Build a library
144pnpm nx build <project-name>
145 
146# Run tests
147pnpm nx test <project-name>
148 
149# Run linting
150pnpm nx lint <project-name>
151```
152 
153### Affected Commands
154 
155```bash
156# Lint affected projects
157pnpm lint:affected                     # nx affected --target lint --fix
158 
159# Test affected projects (not available — use nx directly)
160pnpm nx affected --target test
161 
162# Build affected projects (not available — use nx directly)
163pnpm nx affected --target build
164```
165 
166### Utilities
167 
168```bash
169# Commitizen (guided commit message)
170pnpm commit                            # czg
171 
172# Validate package.json files
173pnpm pkgJsonLint                       # npmPkgJsonLint .
174 
175# Spell check
176pnpm spellcheck                        # cspell (if configured)
177```
178 
179## Code Standards
180 
181**Baseline standards**: see `.ai/rules/` for all rules.
182 
183### TypeScript
184 
185- **Strict mode**: `strict: true`, `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`
186- **Imports**: Use path aliases (`@middle-earth/libs/publishable/*`), NOT relative `../../..`
187- **No `any`**: Favor precise types and narrowing
188- **Return types**: Explicit for exported functions and public APIs
189- **File organization**: `*.constants.ts`, `*.helpers.ts`, `*.types.ts`
190 
191### Testing
192 
193- **Jest** as test runner (NOT Vitest)
194- **Unit tests**: `*.spec.ts(x)` in `__tests__/` folders
195- **Mocking**: `jest.mock` for modules, `jest.spyOn` for side effects
196- **Table-driven tests**: `it.each` for input/output matrices
197- **Coverage**: Aim for 100% where feasible
198 
199## Commit Message Guidelines
200 
201### Quick Reference
202 
203- **Format**: `<type>(optional scope): <description>`
204- **Types**: `feat`, `fix`, `refactor`, `docs`, `test`, `style`, `perf`, `build`, `ci`, `chore`, `revert`
205- **Imperative mood**: "add", "fix", "update" (NOT "added", "fixed", "updated")
206- **Lowercase**: Description starts with lowercase letter
207- **No period**: Description does NOT end with a period
208 
209### Middle Earth Scopes
210 
211- **`config`**: Root-level configuration files (nx.json, tsconfig.base.json, ESLint, commitlint)
212- **`lib`**: Libraries in `libs/publishable/`
213- **`release`**: Versioning, releases, publishing
214- **`ai`**: AI instructions and rules
215 
216### Examples
217 
218```
219feat(lib): add Button component to UI library
220chore(config): update ESLint rules for TypeScript files
221chore(release): bump eslint-config-carrot to 0.9.0
222refactor(lib): simplify logger initialization
223```
224 
225## Nx Configuration
226 
227- **Plugins**: @nx/eslint/plugin, @nx/jest/plugin
228- **Default Base**: main branch
229- **Build**: `@nx/js:swc` compiler
230- **Targets per library**: build, lint, test, types, package, publish, release
231- **Project Tags**: `type:lib`
232 
233## Important Notes
234 
235- **Package Manager**: pnpm ONLY (enforced by `preinstall` script)
236- **Node Version**: 22.20.0 (check `.nvmrc`)
237- **Husky Hooks**: Git hooks for pre-commit linting via lint-staged
238- **Renovate**: Dependency updates automated with config in `renovate.json`
239- **No Docker**: Libraries only — no container builds
240- **No Infrastructure**: No Terraform, no AWS resources
241 
242## Troubleshooting
243 
244### Clear Caches
245 
246```bash
247pnpm nx reset
248```
249 
250### Dependency Issues
251 
252```bash
253rm -rf node_modules pnpm-lock.yaml
254pnpm install
255```
256