Skip to content

Cursor agent setup — three-repo map

Canonical guide for Cursor, Antigravity, Gemini CLI, and Claude Code when working on Rafael's repos. For Graphify mechanics see Local AI context. For MCP server details see MCP overview.

Three-repo map

Repo Path Role Deploy
infra-devops infra/devops on Forgejo Platform VPS stack, scripts, MCP server, docs site Push main → Woodpecker self-deploy
portfolio rafael.gonzalez.albes/portfolio Personal site + writing automation + engineering showcase Push main → SFTP IONOS
aifeatures-site rafael.gonzalez.albes/aifeatures-site aifeatures.ai programmatic SEO / affiliate SPA Push main → SFTP IONOS

Cross-cutting profile: C:\Users\anik0z\Documents\agent router\cursor.md (preferences, project table, privacy notes).

MCP servers per repo

Server infra-devops portfolio aifeatures-site
plane yes yes optional
forgejo yes yes (via gen script) yes (via gen script)
woodpecker yes yes (via gen script) yes (via gen script)
infra-ops yes no no
smart-router no yes yes

Generate per-project .cursor/mcp.json

From infra-devops (tokens in local/.env, never commit output if it contains secrets):

bash local/gen-portfolio-mcp-json.sh
bash local/gen-aifeatures-mcp-json.sh

infra-devops: copy templates/cursor-mcp.json.example → .cursor/mcp.json and fill tokens. Build infra-ops MCP: npm run mcp:build --prefix mcp-server.

Reload Cursor after MCP changes: Ctrl+Shift+P → Developer: Reload Window.

Per-IDE file matrix

IDE infra-devops portfolio aifeatures-site
Cursor rules .cursor/rules/*.mdc .cursor/rules/*.mdc .cursor/rules/*.mdc
Cursor hooks .cursor/hooks.json → sessionStart sessionStart + writing nudge sessionStart → ai:check
Cursor MCP .cursor/mcp.json (local) .cursor/mcp.json (local) .cursor/mcp.json (local)
Antigravity .agents/rules/, workflows/, skills/ same .gemini-rules.md only (bootstrap .agents/ via npm run ai:setup when added)
Gemini CLI GEMINI.md, .gemini/skills/ same GEMINI.md, .gemini-rules.md
Claude Code .claude/instructions.md + per-machine SessionStart .claude/settings.json hooks (aifeatures) graphify hook-guards in .claude/settings.json
Standing doc AGENTS.md, CLAUDE.md AGENTS.md, .gemini-rules.md AGENTS.md, CLAUDE.md
AI context doc docs/AI_CONTEXT.md docs/AI_CONTEXT.md docs/AI_CONTEXT.md

Cursor rules inventory

infra-devops (.cursor/rules/)

File alwaysApply Purpose
graphify.mdc yes graphify query/path/explain before broad Read/Grep/Glob
ai-context-auto.mdc yes Agents run ai:context:if-stale, ai:repair, graphify update
infra-mcp-routing.mdc yes plane / forgejo / woodpecker / infra-ops routing
ci-red-pipeline.mdc yes Red CI protocol for infra/devops
no-cursor-commit-attribution.mdc yes No Co-authored-by: Cursor trailers

Hook: .cursor/hooks.json → sessionStart → scripts/ai-context-on-session.mjs (staleness check, detached rebuild, doctor/repair).

portfolio (.cursor/rules/)

File alwaysApply Purpose
graphify.mdc yes Graphify query-first
ai-context.mdc yes Doctor/repair + secret safety
ci-red-pipeline.mdc yes Red CI for rafael.gonzalez.albes/portfolio
plane-workflow.mdc yes PORT-N tickets, branch/PR conventions
smart-router.mdc yes Route questions via smart-router MCP ask
user-profile.mdc yes Read agent router/cursor.md
writing-daily-workflow.mdc scoped scripts/writing-* backfill and topic refill

Hooks: ai-context-on-session.mjs + writing-on-session.mjs (backfill/topic plan nudges).

Automations: .cursor/automations/*.prefill.json — see portfolio WRITING_AUTOMATION.

aifeatures-site (.cursor/rules/)

File alwaysApply Purpose
graphify.mdc yes Graphify query-first
no-cursor-commit-attribution.mdc yes No Cursor co-author trailers
ci-red-pipeline.mdc yes Red CI for rafael.gonzalez.albes/aifeatures-site
smart-router.mdc yes Local LLM routing for routine questions
user-profile.mdc yes Read agent router/cursor.md

Hooks: sessionStart → .cursor/hooks/ai-context-on-session.mjs (doctor → repair → if-stale); same ai:doctor / ai:repair / ai:context:if-stale parity as portfolio.

Session hooks (shared behavior)

scripts/ai-context-on-session.mjs in infra-devops (portfolio has its own copy):

  1. Cheap staleness check in foreground (~mtime walk)
  2. If stale: detached worker rebuild (doctor → repair → generate-ai-context.mjs)
  3. Lock: graphify-out/.rebuild.lock, log: graphify-out/.rebuild.log
  4. Always exits 0 — never blocks session open

Stale definition (infra-devops, Aug 2026): whole repo minus .graphifyignore — not a hand-maintained allow-list.

Also triggered by .githooks/post-merge and post-checkout (branch checkouts only, $3 = 1).

Multitask vs other modes

Mode Use when
Cursor Multitask Large bounded feature with milestones; parallel Explorer/Worker/Reviewer gates
Single Cursor Agent Small fixes, doc updates, one-file changes
Ship worker Plane ticket → PR → CI on VPS
Portfolio Writing Automations Scheduled /writing content with human finalize gate

Playbook: cursor-multitask-playbook.md. Template pack: templates/multitask/.

Do not commit ephemeral .agents/teamwork_* runtime dirs — distill outcomes into docs/ and source code.

New machine checklist

  1. Clone repo(s) from Forgejo
  2. npm install (sets git hooks via postinstall where configured)
  3. npm run ai:setup (Graphify CLI + IDE skills)
  4. Copy/generate .cursor/mcp.json (see above)
  5. npm run ai:doctor — fix with npm run ai:repair
  6. Reload Cursor window
  7. For infra-devops: bash scripts/setup-local-ssh.sh + fill local/.env

App repo bootstrap

New Vite/static apps: copy from templates/cursor-app/ during onboard-project. See also agent router/new-project.ps1 for greenfield projects.