Monorepo Agent Setup

USE WHEN: editing Cursor/Claude agent config, rules, hooks, skills, MCP, subagents, slash commands, or dual-tree sync; or when asking how Claude vs Cursor instructions are laid out in this monorepo. DO NOT USE WHEN: implementing app features, Workers, or frontend UI unless the task is specifically about agent tooling.

louisbrulenaudet Updated Sep 17, 2026

Install

Press C to copy

$ npx skillmds@latest add louisbrulenaudet/monorepo-agent-setup

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to collection

README badge

[![SkillMD](https://skillmd.com/badge/louisbrulenaudet/monorepo-agent-setup.svg)](https://skillmd.com/skills/louisbrulenaudet/monorepo-agent-setup)

Trust & safety

Audits pending

Not yet audited · commit b3efd80

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Monorepo agent setup

Canonical layout and sync policy for Cursor and Claude Code in this repo.

Memory layout

Layer	Claude Code	Cursor
Global instructions	CLAUDE.md (`@AGENTS.md`)	AGENTS.md
Path-scoped rules	`.claude/rules/` (`*.md`)	`.cursor/rules/` (`*.mdc`)
Hooks wiring	`.claude/settings.json`	`.cursor/hooks.json`
Hook scripts	`hooks/` (shared)	`hooks/` (shared)
Subagents	`.claude/agents/`	`.cursor/agents/`
Review workflows	Skills under `.agents/skills/review*` (symlink)	Same skills under `.agents/skills/review*`
Dependency-scoped reviews	`/review-<dep>` skills under `.agents/skills/review-<dep>/` (symlink) - one per dev dependency (claude-code, cursor, vite, oxc, typescript, turborepo, pnpm, wrangler, hono, tailwind, vitest, tanstack-router, tanstack-query, react, zod, knip, syncpack)	Same
Deep skills	Symlinks → `.agents/skills/`	`.agents/skills/` (source of truth)
Nested app guides	`CLAUDE.md` per app/package	`AGENTS.md` per app/package

Claude: nested CLAUDE.md loads on demand; debug with tail -f hooks/logs/instructions-loaded.log.
Cursor: nested AGENTS.md by directory; .mdc rules attach via globs / alwaysApply. Debug: Customize → Hooks.
Rule folders (core, frontend, backend, contracts, quality, tests, ops) organize only; scoping is frontmatter (paths vs globs/alwaysApply).
Vite config rule: .claude/rules/frontend/vite-config.md ↔ .cursor/rules/frontend/vite-config.mdc - apps/front-*/vite.config.ts only.
Tailwind rule: .claude/rules/frontend/tailwind.md ↔ .cursor/rules/frontend/tailwind.mdc - apps/front-*/src/**/*.{ts,tsx,css}, apps/front-*/index.html.
Ports rule: .claude/rules/backend/ports.md ↔ .cursor/rules/backend/ports.mdc - wrangler.jsonc, app package.json, front-*/vite.config.ts.
TSConfig rule: .claude/rules/quality/typescript-config.md ↔ .cursor/rules/quality/typescript-config.mdc - packages/typescript-config/**, **/tsconfig*.json.
Vitest shared-config rule: .claude/rules/quality/vitest-config.md ↔ .cursor/rules/quality/vitest-config.mdc - packages/vitest-config/**.
Turbo rule: .claude/rules/core/turborepo.md ↔ .cursor/rules/core/turborepo.mdc - **/turbo.json, .github/workflows/**.

See hooks/AGENTS.md for hook authoring. Full layout and sync policy: this skill.

Content taxonomy (what belongs where)

Put instructions in the layer that matches how often agents need them. Path-scoped rules save context; alwaysApply / rules without paths cost the same as root AGENTS.md.

Layer	Put here	Examples
Root `AGENTS.md`	Always-on project map for almost every task	Overview, architecture diagram, worker prefixes, where-to-put, essential pnpm scripts, architecture decision bullets, pointers
Path-scoped rules (mirrored `.cursor` / `.claude`)	Only when editing matching files	Ports / `inspector_port` / `strictPort`, wrangler secrets, contract workflow, oxlint style, TSConfig presets
Nested app/package `AGENTS.md`	Package-local workflows	`apps/front-app`, `worker-api`, `dtos-common`
Skills	Deep / on-demand procedures	`monorepo-agent-setup`, `turborepo`, `hono`, review skills
`README.md`	Human-facing docs	Full port registry, copy-from-existing scaffold checklist

Do not duplicate path-scoped or linter detail in root AGENTS.md. Prefer a one-line pointer to the owning rule, skill, or README.

Sync policy

When changing agent setup, keep both tools in sync:

Rules: edit both .cursor/rules/<cat>/<name>.mdc and .claude/rules/<cat>/<name>.md (remap frontmatter: Cursor description/globs/alwaysApply ↔ Claude paths).
Agents: edit both .cursor/agents/<name>.md and .claude/agents/<name>.md (keep product-native keys: model, tools, readonly, color).
Hooks: edit scripts only under hooks/; update both .cursor/hooks.json and .claude/settings.json when wiring changes.
Skills: install/update under .agents/skills/ + skills-lock.json (when present). Claude entries are symlinks into .agents/skills/ (except Cursor-only skills-update). Project-owned skills (pnpm, ui-ux-design-best-practices, monorepo-agent-setup, privileged-legal-data, front-vitest, review-*) live once under .agents/skills/.
Review skills: edit .agents/skills/review*/SKILL.md (self-contained; Claude via symlink). Two families: dimension reviews (review, review-architecture, review-ci, review-code-quality, review-configuration, review-performance, review-security, review-seo, review-ui) and dependency-scoped stack reviews (review-claude-code, review-cursor, review-vite, review-oxc, review-typescript, review-turborepo, review-pnpm, review-wrangler, review-hono, review-tailwind, review-vitest, review-tanstack-router, review-tanstack-query, review-react, review-zod, review-knip, review-syncpack). Both share the same output contract (Critical / Improvements / Optional plan) and disable-model-invocation: true - human-only. Dependency-scoped skills mandate ground-truth retrieval (Context7 MCP → Firecrawl restricted to official domains → official changelogs) before suggestions; no hard-coded doc URLs, cite sources per finding. review-* and pnpm set disable-model-invocation: true, so only a human can run them - they cannot be preloaded into a subagent's skills: field or invoked through the Skill tool. Keep it that way for the whole-repo review deep dives; do not add it to a skill an agent needs. privileged-legal-data is deliberately model-invocable for exactly that reason: it is the preloadable checklist behind guardrails.md → "Privileged client data". When adding a security review agent later, preload that skill rather than copying its contents into the agent description. front-vitest is also model-invocable: the thin tests/front-react rule points at it for DOM/RTL/Router harness depth.
MCP: keep .mcp.json and .cursor/mcp.json server lists aligned (type: "http" on HTTP servers).
Nested guides: update AGENTS.md; keep CLAUDE.md as @AGENTS.md + Claude-only bullets.

Agent guides (apps / packages)

Focus	Guide
pnpm workspaces	`.agents/skills/pnpm/SKILL.md`
React SPA	`apps/front-app/AGENTS.md`
HTTP gateway	`apps/worker-api/AGENTS.md`
Zod DTOs	`packages/dtos-common/AGENTS.md`
Shared value sets	`packages/enums-common/AGENTS.md`
TS presets	`packages/typescript-config/AGENTS.md`
Agent hooks	`hooks/AGENTS.md`

Inventory (quick)

Rules: 25 mirrored basenames (only core/guardrails always-on); tests/ holds vitest + hono-workers + front-react (DOM/RTL depth in skill front-vitest); ops/ holds ci + cd. No drizzle-orm rule until a DB-owning worker lands.
Subagents: verifier, bundle-analyzer, docs-researcher.
Skills: 25 mirrored basenames plus 17 dependency-scoped /review-<dep> stack reviews (see Review skills above); deep skills (turborepo, wrangler, TanStack family) consulted as context by their matching review skill.
Cursor hooks: beforeShellExecution (git guards, failClosed), afterFileEdit (format/lint), sessionStart.
Claude hooks: PreToolUse Bash (same git guards), PostToolUse Edit|Write (format/lint), InstructionsLoaded.
MCP: cloudflare-docs, context7 (project). Keep the Cursor Cloudflare plugin disabled unless you need account-scoped bindings/builds/observability MCP (those trigger OAuth login); do not double-register Context7 via plugin.

---name: monorepo-agent-setupdescription: USE WHEN: editing Cursor/Claude agent config, rules, hooks, skills, MCP, subagents, slash commands, or dual-tree sync; or when asking how Claude vs Cursor instructions are laid out in this monorepo. DO NOT USE WHEN: implementing app features, Workers, or frontend UI unless the task is specifically about agent tooling.---# Monorepo agent setupCanonical layout and sync policy for **Cursor** and **Claude Code** in this repo.## Memory layout| Layer | Claude Code | Cursor ||-------|-------------|--------|| Global instructions | [CLAUDE.md](../../../CLAUDE.md) (`@AGENTS.md`) | [AGENTS.md](../../../AGENTS.md) || Path-scoped rules | [`.claude/rules/`](../../../.claude/rules/) (`*.md`) | [`.cursor/rules/`](../../../.cursor/rules/) (`*.mdc`) || Hooks wiring | [`.claude/settings.json`](../../../.claude/settings.json) | [`.cursor/hooks.json`](../../../.cursor/hooks.json) || Hook scripts | [`hooks/`](../../../hooks/) (shared) | [`hooks/`](../../../hooks/) (shared) || Subagents | [`.claude/agents/`](../../../.claude/agents/) | [`.cursor/agents/`](../../../.cursor/agents/) || Review workflows | Skills under `.agents/skills/review*` (symlink) | Same skills under `.agents/skills/review*` || Dependency-scoped reviews | `/review-<dep>` skills under `.agents/skills/review-<dep>/` (symlink) - one per dev dependency (claude-code, cursor, vite, oxc, typescript, turborepo, pnpm, wrangler, hono, tailwind, vitest, tanstack-router, tanstack-query, react, zod, knip, syncpack) | Same || Deep skills | Symlinks → [`.agents/skills/`](../../) | [`.agents/skills/`](../../) (source of truth) || Nested app guides | `CLAUDE.md` per app/package | `AGENTS.md` per app/package |- Claude: nested `CLAUDE.md` loads on demand; debug with `tail -f hooks/logs/instructions-loaded.log`.- Cursor: nested `AGENTS.md` by directory; `.mdc` rules attach via `globs` / `alwaysApply`. Debug: **Customize → Hooks**.- Rule folders (`core`, `frontend`, `backend`, `contracts`, `quality`, `tests`, `ops`) organize only; scoping is frontmatter (`paths` vs `globs`/`alwaysApply`).- Vite config rule: `.claude/rules/frontend/vite-config.md` ↔ `.cursor/rules/frontend/vite-config.mdc` - `apps/front-*/vite.config.ts` only.- Tailwind rule: `.claude/rules/frontend/tailwind.md` ↔ `.cursor/rules/frontend/tailwind.mdc` - `apps/front-*/src/**/*.{ts,tsx,css}`, `apps/front-*/index.html`.- Ports rule: `.claude/rules/backend/ports.md` ↔ `.cursor/rules/backend/ports.mdc` - `wrangler.jsonc`, app `package.json`, `front-*/vite.config.ts`.- TSConfig rule: `.claude/rules/quality/typescript-config.md` ↔ `.cursor/rules/quality/typescript-config.mdc` - `packages/typescript-config/**`, `**/tsconfig*.json`.- Vitest shared-config rule: `.claude/rules/quality/vitest-config.md` ↔ `.cursor/rules/quality/vitest-config.mdc` - `packages/vitest-config/**`.- Turbo rule: `.claude/rules/core/turborepo.md` ↔ `.cursor/rules/core/turborepo.mdc` - `**/turbo.json`, `.github/workflows/**`.See [`hooks/AGENTS.md`](../../../hooks/AGENTS.md) for hook authoring. Full layout and sync policy: this skill.## Content taxonomy (what belongs where)Put instructions in the layer that matches how often agents need them. Path-scoped rules save context; `alwaysApply` / rules without `paths` cost the same as root `AGENTS.md`.| Layer | Put here | Examples ||-------|----------|----------|| Root [`AGENTS.md`](../../../AGENTS.md) | Always-on project map for almost every task | Overview, architecture diagram, worker prefixes, where-to-put, essential pnpm scripts, architecture decision bullets, pointers || Path-scoped rules (mirrored `.cursor` / `.claude`) | Only when editing matching files | Ports / `inspector_port` / `strictPort`, wrangler secrets, contract workflow, oxlint style, TSConfig presets || Nested app/package `AGENTS.md` | Package-local workflows | `apps/front-app`, `worker-api`, `dtos-common` || Skills | Deep / on-demand procedures | `monorepo-agent-setup`, `turborepo`, `hono`, review skills || [`README.md`](../../../README.md) | Human-facing docs | Full port registry, copy-from-existing scaffold checklist |Do **not** duplicate path-scoped or linter detail in root `AGENTS.md`. Prefer a one-line pointer to the owning rule, skill, or README.## Sync policyWhen changing agent setup, keep both tools in sync:1. **Rules:** edit both `.cursor/rules/<cat>/<name>.mdc` and `.claude/rules/<cat>/<name>.md` (remap frontmatter: Cursor `description`/`globs`/`alwaysApply` ↔ Claude `paths`).2. **Agents:** edit both `.cursor/agents/<name>.md` and `.claude/agents/<name>.md` (keep product-native keys: `model`, `tools`, `readonly`, `color`).3. **Hooks:** edit scripts only under `hooks/`; update both `.cursor/hooks.json` and `.claude/settings.json` when wiring changes.4. **Skills:** install/update under `.agents/skills/` + `skills-lock.json` (when present). Claude entries are symlinks into `.agents/skills/` (except Cursor-only `skills-update`). Project-owned skills (`pnpm`, `ui-ux-design-best-practices`, `monorepo-agent-setup`, `privileged-legal-data`, `front-vitest`, `review-*`) live once under `.agents/skills/`.5. **Review skills:** edit `.agents/skills/review*/SKILL.md` (self-contained; Claude via symlink). Two families: **dimension** reviews (`review`, `review-architecture`, `review-ci`, `review-code-quality`, `review-configuration`, `review-performance`, `review-security`, `review-seo`, `review-ui`) and **dependency-scoped stack reviews** (`review-claude-code`, `review-cursor`, `review-vite`, `review-oxc`, `review-typescript`, `review-turborepo`, `review-pnpm`, `review-wrangler`, `review-hono`, `review-tailwind`, `review-vitest`, `review-tanstack-router`, `review-tanstack-query`, `review-react`, `review-zod`, `review-knip`, `review-syncpack`). Both share the same output contract (Critical / Improvements / Optional plan) and `disable-model-invocation: true` - human-only. Dependency-scoped skills mandate ground-truth retrieval (Context7 MCP → Firecrawl restricted to official domains → official changelogs) before suggestions; no hard-coded doc URLs, cite sources per finding. `review-*` and `pnpm` set `disable-model-invocation: true`, so **only a human can run them** - they cannot be preloaded into a subagent's `skills:` field or invoked through the Skill tool. Keep it that way for the whole-repo review deep dives; do not add it to a skill an agent needs. `privileged-legal-data` is deliberately **model-invocable** for exactly that reason: it is the preloadable checklist behind `guardrails.md` → "Privileged client data". When adding a security review agent later, preload that skill rather than copying its contents into the agent description. `front-vitest` is also model-invocable: the thin `tests/front-react` rule points at it for DOM/RTL/Router harness depth.6. **MCP:** keep [`.mcp.json`](../../../.mcp.json) and [`.cursor/mcp.json`](../../../.cursor/mcp.json) server lists aligned (`type: "http"` on HTTP servers).7. **Nested guides:** update `AGENTS.md`; keep `CLAUDE.md` as `@AGENTS.md` + Claude-only bullets.## Agent guides (apps / packages)| Focus | Guide ||-------|-------|| pnpm workspaces | `.agents/skills/pnpm/SKILL.md` || React SPA | `apps/front-app/AGENTS.md` || HTTP gateway | `apps/worker-api/AGENTS.md` || Zod DTOs | `packages/dtos-common/AGENTS.md` || Shared value sets | `packages/enums-common/AGENTS.md` || TS presets | `packages/typescript-config/AGENTS.md` || Agent hooks | `hooks/AGENTS.md` |## Inventory (quick)- **Rules:** 25 mirrored basenames (only `core/guardrails` always-on); `tests/` holds vitest + hono-workers + front-react (DOM/RTL depth in skill `front-vitest`); `ops/` holds `ci` + `cd`. No `drizzle-orm` rule until a DB-owning worker lands.- **Subagents:** `verifier`, `bundle-analyzer`, `docs-researcher`.- **Skills:** 25 mirrored basenames plus 17 dependency-scoped `/review-<dep>` stack reviews (see Review skills above); deep skills (`turborepo`, `wrangler`, TanStack family) consulted as context by their matching review skill.- **Cursor hooks:** `beforeShellExecution` (git guards, `failClosed`), `afterFileEdit` (format/lint), `sessionStart`.- **Claude hooks:** PreToolUse Bash (same git guards), PostToolUse Edit\|Write (format/lint), InstructionsLoaded.- **MCP:** `cloudflare-docs`, `context7` (project). Keep the Cursor Cloudflare **plugin** disabled unless you need account-scoped bindings/builds/observability MCP (those trigger OAuth login); do not double-register Context7 via plugin.

louisbrulenaudet/monorepo-template/tree/main/.agents/skills/monorepo-agent-setup commit b3efd804ad

Frequently asked questions

npx skillmds@latest add louisbrulenaudet/monorepo-agent-setup