Cursor Tooling Reference

This document is the recovery and reconstruction reference for the Cursor AI setup used in this project. It covers agents, rules, skills, MCP servers, and models. The canonical human-readable specs live in docs/ai-governance/**; live .cursor/** assets are operational mirrors used by Cursor at runtime.

---

Repository structure

ciq-mvp2-app/
  .cursor/
    agents/         ← Agent personality + instruction files (*.md)
    rules/          ← Always-applied workspace rules (*.mdc)
    skills/         ← Reusable agent skill workflows (*/SKILL.md)

~/.cursor/
  mcp.json          ← Global MCP server configuration
  skills-cursor/    ← Global Cursor-managed skills

Canonical vs mirror assets

Asset type	Canonical source	Operational mirror
Agent roles and authority	docs/ai-governance/*.md	.cursor/agents/*.md
Rules and always-applied behavior	docs/ai-governance/*.md + docs/standards/*.md	.cursor/rules/*.mdc
Skill intent and recovery	docs/ai-governance/*.md	.cursor/skills/*/SKILL.md
Product/runtime prompts	docs/prompts/**	implementation files or runtime config
Rebuild workflow	docs/rebuild/**	local setup steps / generated Cursor files

Reference: AI Asset Governance

---

Agents

Agent files live in .cursor/agents/*.md. Each file has a YAML frontmatter block that Cursor reads to configure the agent’s name, model, and description. The canonical role and authority definitions live in docs/ai-governance/*.md.

Frontmatter format

---
name: <agent-id>
model: <model-alias>
description: <one-line description shown in the agent picker>
---

Current agents

Agent ID	Role	Model	File
neo	Principal Architect & Technical Strategist	claude-4.6-opus-high-thinking	.cursor/agents/neo.md
father	Senior System Architect	claude-4.6-sonnet-medium	.cursor/agents/father.md
coder	Senior Polyglot Full-Stack Engineer	claude-4.6-sonnet-medium	.cursor/agents/coder.md
helper	Content, Data & AI Workflow Specialist	gpt-5.3-codex	.cursor/agents/helper.md
qa	QA Analyst	gpt-5.2	.cursor/agents/qa.md

Full agent descriptions, responsibilities, authority boundaries, and output formats are documented in docs/ai-governance/:

Doc	Agent
AI Agent: Neo	Neo
AI Agent: Father	Father
AI Agent: Coder	Coder
AI Agent: Helper	Helper
AI Agent: QA Analyst	QA

---

Rules

Rules live in .cursor/rules/*.mdc. They are Markdown files with YAML frontmatter. Rules with alwaysApply: true are injected into every Cursor session automatically. Their human-readable intent must remain documented in this repo.

Frontmatter format

---
description: <what this rule does>
alwaysApply: true   # or false for file-scoped rules
globs: **/*.ts      # only needed for file-scoped rules
---

Current rules (all alwaysApply: true)

default-delegation-helper.mdc

Purpose: When the user prompt does not explicitly name an agent role, default delegation uses helper.

Key behavior:

• Explicit role mentions (coder, neo, father, qa, explore, shell, browser-use) override the default.
• Verb cues (“can you code this?”) do not count as explicit role requests.

---

modern-ux-ui-ixd.mdc

Purpose: Treat modern UX, UI, and interaction design as first-class product constraints, not optional polish.

Key behavior:

• Prefer clear information hierarchy, scannability, and predictable navigation.
• Reduce friction in common workflows with strong defaults and progressive disclosure.
• Design states intentionally: default, empty, loading, error, success, and destructive flows.
• Use selection patterns that fit the decision.
• Favor consistency across similar routes, sections, buttons, filters, and setup flows.
• Consider operator efficiency, not just visual neatness.
• Keep accessibility in mind by default: keyboard flow, labels, focus states, WCAG.
• If there is a tradeoff between technical convenience and a clearly better UX, call it out explicitly.

---

read-docs-before-work.mdc

Purpose: Before implementing any feature, page, or component, read the relevant doc and inspect the current implementation.

Key behavior:

1. Read the relevant doc in ciq-mvp2-docs/docs/routes/ or ciq-mvp2-docs/docs/.
2. Inspect the current implementation as the primary UI reference when shipped code has moved beyond old design mocks.
3. Use Figma only when the user explicitly asks for it, or the task is clearly design-implementation work.
4. If docs, current implementation, and Figma conflict, call out the drift and confirm which source drives the change.

Source priority: Current implementation > Docs > Figma

Doc → route mapping:

Route / feature	Doc path
Get Started onboarding	Get Started (/get-started)
Account shell / layout	App Shell (Navigation, Search, Assistant Sidebar)
Channels page	Account – Channels
Dashboard	Account – Dashboard
Knowledge Bases	Account – Knowledge bases
Workspaces	Account – Workspaces
Workspace open (detail)	Account – Open workspace (workspace detail) + Workspace Open Page – Implementation Spec
Settings	Account – Settings
Profile	Account – My profile
Billing	Account – My profile: Billing (tab)
Comment Responder	Comment Responder (/comment-responder)
Chatti Live	Chatti Live

---

request-workflow-review-docs-implement.mdc

Purpose: Every user request follows a fixed workflow: review → docs → implement.

Key behavior:

1. Review the request — understand what is wanted and what is in scope.
2. Documentation — decide if the change requires doc updates. If yes, update docs first.
3. Implementation — if code changes are needed, delegate to Coder with a clear spec.
4. Unclear requests — if ambiguous, ask the user before proceeding.

---

Skills

Skills live in .cursor/skills/<skill-name>/SKILL.md. Each skill is a Markdown file with YAML frontmatter that Cursor reads to determine when to invoke the skill automatically. Their recovery contract must remain documented in this repo even if the live skill files are local-only.

Frontmatter format

---
name: <skill-id>
description: <trigger description — when the agent should invoke this skill>
metadata:
  mcp-server: <required MCP server, if any>
---

Current project skills (.cursor/skills/)

create-rule

When invoked: User wants to create a Cursor rule, add coding standards, set up project conventions, configure file-specific patterns, or asks about .cursor/rules/.

What it does: Guides the agent through gathering rule requirements (purpose, scope, file patterns) and creates a properly formatted .mdc file in .cursor/rules/.

File: .cursor/skills/create-rule/SKILL.md

---

create-skill

When invoked: User wants to create, write, or author a new Agent Skill, or asks about SKILL.md format or skill structure.

What it does: Guides the agent through creating a new skill with correct frontmatter, trigger description, and workflow content.

File: .cursor/skills/create-skill/SKILL.md

---

update-cursor-settings

When invoked: User wants to change editor settings, preferences, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.

What it does: Reads the current settings.json, applies the requested changes, and writes the updated file.

File: .cursor/skills/update-cursor-settings/SKILL.md

---

implement-design

When invoked: User mentions “implement design”, “generate code”, “implement component”, “build Figma design”, provides a Figma URL, or asks to build components matching Figma specs.

Requires: Figma MCP server connection.

What it does: Structured 7-step workflow:

1. Extract fileKey and nodeId from the Figma URL.
2. Fetch design context (get_design_context) — layout, typography, colors, spacing.
3. Capture visual reference (get_screenshot).
4. Download assets from Figma MCP localhost sources.
5. Translate to project conventions (design system, tokens, existing components).
6. Achieve 1:1 visual parity.
7. Validate layout, typography, colors, interactive states, accessibility.

File: .cursor/skills/implement-design/SKILL.md

---

code-connect-components

When invoked: User says “code connect”, “connect this component to code”, “connect Figma to code”, “map this component”, “link component to code”, “create code connect mapping”, or wants to establish mappings between Figma designs and code.

Requires: Figma MCP server connection.

What it does: Creates Code Connect mappings between Figma design components and codebase components.

File: .cursor/skills/code-connect-components/SKILL.md

---

create-design-system-rules

When invoked: User says “create design system rules”, “generate rules for my project”, “set up design rules”, “customize design system guidelines”, or wants to establish project-specific conventions for Figma-to-code workflows.

Requires: Figma MCP server connection.

What it does: Generates custom design system rules for the user’s codebase based on the Figma design system.

File: .cursor/skills/create-design-system-rules/SKILL.md

---

read-docs-before-work

When invoked: Agent is starting implementation work, user asks to build a feature, or working on routes/pages listed in the doc mapping.

What it does: Ensures the agent reads the relevant documentation and inspects the current implementation before any implementation work begins. Enforces the source priority: current implementation > docs > Figma.

File: .cursor/skills/read-docs-before-work/SKILL.md

---

Global Cursor-managed skills (~/.cursor/skills-cursor/)

These are skills managed by Cursor globally (not project-specific). They are available in all projects on this machine.

Skill	Purpose
create-rule	Create Cursor rules (global version)
create-skill	Create new Agent Skills (global version)
update-cursor-settings	Modify Cursor/VSCode settings.json (global version)
create-subagent	Create new Cursor subagent configurations
migrate-to-skills	Migrate existing agent instructions to the Skills format
shell	Shell command execution specialist

---

MCP Servers

MCP (Model Context Protocol) servers extend the agent with external tool capabilities. Configuration lives in ~/.cursor/mcp.json.

Current configuration (~/.cursor/mcp.json)

{
  "mcpServers": {
    "figma-local": {
      "url": "http://127.0.0.1:3845/mcp"
    },
    "Figma": {
      "url": "https://mcp.figma.com/mcp",
      "headers": {}
    }
  }
}

MCP server descriptions

figma-local (Figma Desktop MCP)

• URL: http://127.0.0.1:3845/mcp (local server started by the Figma desktop app)
• Purpose: Connects to the locally running Figma desktop application. Allows the agent to read the currently selected node in the open Figma file without needing a URL.
• Tools available: get_design_context, get_screenshot, get_metadata, get_figjam
• Requires: Figma desktop app running with MCP enabled.
• Used by skills: implement-design, code-connect-components, create-design-system-rules

Figma (Official Figma MCP)

• URL: https://mcp.figma.com/mcp
• Purpose: Official Figma cloud MCP server. Connects to Figma files via URL (fileKey + nodeId). Supports reading designs, creating FigJam diagrams, and managing Code Connect mappings.
• Tools available: get_design_context, get_screenshot, get_metadata, get_figjam, generate_diagram, Code Connect tools
• Requires: Figma account authentication.
• Used by skills: implement-design, code-connect-components, create-design-system-rules

Figma URL parsing

figma.com/design/:fileKey/:fileName?node-id=:nodeId

• fileKey — segment after /design/
• nodeId — value of node-id query param; convert - to : when passing to MCP tools (e.g. 4010-7241 → 4010:7241)

---

Models reference

Model alias	Used by	Characteristics
claude-4.6-opus-high-thinking	Neo	Highest reasoning capability; best for architecture, complex specs, and nuanced product decisions
claude-4.6-sonnet-medium	Father, Coder	Strong general-purpose model; good balance of speed and quality for implementation and high-level guidance
gpt-5.3-codex	Helper	Optimized for structured content generation, seed data, and copy tasks
gpt-5.2	QA	Suitable for validation, review, and issue reporting tasks

---

Rebuilding this setup from scratch

To recreate the full Cursor AI configuration on a new machine or in a new project:

1. Read the canonical docs first:

   • AI Governance: Agents Overview
   • AI Asset Governance
   • Rebuild Playbooks (Index)

2. Create agent files in .cursor/agents/ using the specs in docs/ai-governance/*.md. Each file needs the YAML frontmatter (name, model, description) followed by the agent’s system prompt.

3. Create rule files in .cursor/rules/ as .mdc files. Use the rule descriptions above. Set alwaysApply: true for all four current rules.

4. Create skill files in .cursor/skills/<skill-name>/SKILL.md. Each skill needs the YAML frontmatter (name, description, optional metadata.mcp-server) followed by the skill workflow content.

5. Configure MCP servers in ~/.cursor/mcp.json using the JSON block above. The figma-local server requires the Figma desktop app to be running. The Figma cloud server requires authentication via the mcp_auth tool on first use.

6. Verify by opening Cursor, checking that agents appear in the agent picker, rules are listed under workspace rules, and MCP servers show as connected.

7. Drift-check the live .cursor/** assets against the canonical docs and correct any mismatches before treating the setup as recovered.