| name | monorepo-agent-setup |
| description | 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.
|
| disable-model-invocation | true |
Monorepo agent setup
Canonical layout and sync policy for Cursor and Claude Code in this repo.
Memory layout
- 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) 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.
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, review-*) live once under .agents/skills/.
- Review skills: edit
.agents/skills/review*/SKILL.md (self-contained; Claude via symlink).
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", and the
security-reviewer template in docs/agent-templates/ preloads it rather than copying it.
- MCP: keep
.mcp.json and .cursor/mcp.json server lists aligned (type: "http" on HTTP servers).
- Nested guides: update ; keep as + 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: 18 mirrored basenames (only
core/guardrails always-on).
- Subagents:
verifier, bundle-analyzer, docs-researcher.
- 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.
