6 · Cursor & other IDEs

TL;DR

Objective — make every AI tool (Cursor, Gemini, Codex) boot from the same AGENTS.md constitution, and register the project’s MCP servers — chiefly Laravel Boost — in .mcp.json at the repo root (C6 commit).

User part + done-when

👤 User part — almost nothing here needs a person beyond a choice: which extra IDEs (Cursor, Gemini, Codex) you actually use. If you only run one AI tool, you can skip the mirrors. Everything else is terminal-runnable or file edits.

Done when .mcp.json is valid, C6 is committed on develop, Cursor boots from the constitution, and any mirror is a one-line pointer.  ·  ⏱ ~10 min  ·  🤖 mostly the agent.

Background

The constitution (AGENTS.md) is tool-agnostic by design — one canonical file, every other tool file is a one-line redirect. This step makes the other agents — Cursor, Gemini, Codex — boot from that same AGENTS.md, and registers the project’s MCP servers so any tool can reach them.

The rule across all of them: one canonical file (AGENTS.md), every other tool file is a one-line redirect. That’s what keeps the constitution from drifting across five tools.

Steps

1. Register the project MCP servers (.mcp.json)

Project-scoped MCP servers live in .mcp.json at the repo root (committed at C6) so every teammate and every tool gets them. The key one for Laravel is Laravel Boost — it adds search-docs (version-specific docs), tinker, database-query, browser-logs, and more.

Who does this

🤖 Agent installs Boost (in local development) and writes .mcp.json. 👤 User decides whether to add other project MCPs.

1. Do not enable Boost until local development installs it.

   This phase happens before the extracted Laravel app is fully running, so a live .mcp.json entry that calls php artisan boost:mcp will throw connection errors for two phases. Keep the Boost snippet disabled or parked in .mcp.json.example until local development installs the package.

   composer require laravel/boost --dev
   php artisan boost:install
   # Expected: Boost installs; `boost:install` scaffolds config and guidelines

   • ✅ composer show laravel/boost lists the package as installed.

2. Write .mcp.json only after Boost exists.

   {
     "mcpServers": {
       "laravel-boost": {
         "command": "php",
         "args": ["artisan", "boost:mcp"],
         "disabled": true
       }
     }
   }

   If your MCP client ignores disabled, keep this exact object in .mcp.json.example and do not commit it as live .mcp.json until composer show laravel/boost passes. After Phase 3 installs Boost, remove "disabled": true, validate JSON, and smoke-test search-docs.

   python3 -m json.tool .mcp.json >/dev/null && git add -n .mcp.json
   # Expected: valid JSON; dry-run lists file only after Boost exists or the entry is disabled

   • ✅ .mcp.json is valid JSON on disk and cannot call a missing Boost package.

Tip

Boost’s system prompt instructs agents to “use search-docs before any other approach for Laravel questions” — version-accurate answers beat general-knowledge guesses. Drop .blade.php/.md files into .ai/guidelines/ to add custom rules alongside Boost’s built-in Laravel guidelines.

2. Boot Cursor from the constitution

Cursor reads .cursor/rules/*.mdc and supports the same skills · commands · agents · hooks layers as Claude Code — keep them in sync so every tool gets the same operating system.

Who does this

🤖 Agent writes the Cursor layer. 👤 User opens the project in Cursor to confirm the boot rule applies.

1. Add the always-apply boot rule as .cursor/rules/000-boot.mdc.

   ---
   description: Boot — read the constitution first
   alwaysApply: true
   ---
   
   # Boot
   
   Read `AGENTS.md` at the repo root FIRST — it is the cross-tool constitution
   (tech stack, conventions, safety rules, read-set). Then honor `.claude/rules/`
   (behavioral + reference rules) and `CLAUDE.local.md` if present.
   
   Key safety rules: never edit `vendor/`; wrap vendor edits in `ZAJ:BEGIN/END`;
   never run destructive migrations on shared data; always double-quote `.env` values.

   • ✅ File saved at .cursor/rules/000-boot.mdc with alwaysApply: true.

2. Mirror Claude’s agent layers under .cursor/ (same names, same contracts — the kit ships stubs/READMEs):

   mkdir -p .cursor/{skills,commands,agents}
   # Kit ships: .cursor/skills/README.md, commands/deploy-codecanyon.md, agents/README.md
   # Install full skills/agents into BOTH .claude/ and .cursor/ when ready.

   • ✅ .cursor/skills/, .cursor/commands/, and .cursor/agents/ exist and stay in sync with .claude/.

3. Wire Cursor hooks — .cursor/hooks.json calls the same block-destructive.sh guard Claude uses in yolo mode:

   {
     "version": 1,
     "hooks": {
       "beforeShellExecution": [
         {
           "command": ".claude/claude-mode/hooks/block-destructive.sh",
           "matcher": ".*"
         }
       ]
     }
   }

   • ✅ Destructive shell patterns (e.g. migrate:fresh, rm -rf /) are blocked in Cursor too.

4. Add the .cursorignore so Cursor never indexes secrets.

   .gitignore

   .env
   .env.*
   !.env.example
   !.env.tpl
   *.key
   *.pem
   auth.json
   **/secrets/**
   vendor/
   node_modules/
   storage/framework/
   bootstrap/cache/

   • ✅ Opening the project in Cursor → it acknowledges the constitution / safety rules without prompting; real secrets stay out of its index, while .env.example and .env.tpl remain visible as safe templates.

3. Mirror Gemini & Codex (optional thin pointers)

These tools also converge on AGENTS.md. Keep mirrors thin — a pointer, never a copy — so the constitution can’t fork across tools.

Who does this

🔀 User + Agent — the agent writes the mirrors; 👤 User chooses which of these tools to support.

1. Add the Gemini mirror — GEMINI.md at the repo root.

   GEMINI.md

   Read **AGENTS.md** first — it is the single source of truth for this project.

   • ✅ GEMINI.md is a one-line redirect, not a fork of the constitution.

2. Point Codex back at AGENTS.md. Codex reads AGENTS.md natively; if you keep a .codex/ note, point it back the same way.

   • ✅ Any .codex/ config is a pointer to AGENTS.md, not a copy.

4. Verify all tools converge

Confirm the MCP servers respond and every IDE boots from the one canonical constitution before advancing.

Who does this

🔀 User + Agent — the agent checks JSON validity + search-docs; 👤 User opens Cursor to confirm it boots from the constitution.

1. Confirm .mcp.json is valid on disk — functional search-docs smoke test waits until local development (Boost needs a running app).

   • ✅ .mcp.json validates with python3 -m json.tool; after local dev, search-docs returns version-specific Laravel docs.

2. Open the project in Cursor → it acknowledges the constitution / safety rules without prompting.

   • ✅ Cursor boots from AGENTS.md with no manual prompting.

3. Check every mirror is a pointer, not a fork (GEMINI.md, .codex/).

   • ✅ Each mirror is a one-line redirect back to AGENTS.md.

5. Commit MCP + Cursor mirrors (C6)

Who does this

🤖 Agent commits on develop. Includes .mcp.json and the .cursor/ layer (rules, hooks, ignore).

1. Stage and commit C6 from the project root.

   git branch --show-current    # must be develop
   git add .mcp.json .cursor
   # Optional thin mirrors — include if you created them:
   git add GEMINI.md .codex 2>/dev/null || true
   git commit -m "feat(ai): wire .mcp.json + Cursor/other-IDE mirrors"
   git log --oneline -6         # C6 atop C5…C1
   # Expected: C6 on develop; .mcp.json + .cursor/ tracked

   • ✅ git log shows C6; .mcp.json and .cursor/rules/000-boot.mdc are tracked.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 C6 committed on develop — .mcp.json valid with Laravel Boost disabled/parked until installed, or live only after Boost exists; .cursor/ mirrors tracked (git log shows C6).
• 🤖 Cursor boot rule in place — .cursor/rules/000-boot.mdc with alwaysApply: true points at AGENTS.md.
• 🤖 Cursor layers mirrored — .cursor/skills/, .cursor/commands/, .cursor/agents/, and .cursor/hooks.json stay in sync with .claude/.
• 🤖 .cursorignore in place — real secrets (.env, .env.*, *.key, *.pem, auth.json, **/secrets/**) excluded from Cursor’s index; safe templates (.env.example, .env.tpl) remain visible.
• 🔀 Mirrors are thin pointers — GEMINI.md (and any .codex/ note) redirect to AGENTS.md, never a copy.
• 🔀 Tools converge — opening Cursor acknowledges the constitution without prompting; search-docs returns version-specific Laravel docs after local dev.

→Next step

Verify & gate