Skip to main content

Cursor integration

How Cursor consumes shared workflow policy from this repository and how consuming superbuild repos materialize active rules.

Design stance​

Cursor is one consumer of this repository, not the owner of policy. Canonical content lives in AGENTS.md and docs/. Files under cursor/rules/ are adapter rule sources — short, composable instructions that tell Cursor to read canonical docs before acting.

Two Cursor rule locations​

PathScope
cursor/rules/ in this repoShared adapter sources shipped to all consumers
.cursor/rules/ in this repoSelf-governance for maintainers editing superbuild-workflow
.cursor/rules/ in consuming reposMaterialized shared adapters + local overlays

Cursor discovers rules from the workspace root .cursor/rules/. Consuming repos therefore materialize shared adapters locally; they do not rely on Cursor reading through the submodule path unless explicitly configured.

Typical consumer setup​

  1. Submodule mounted at tools/ai-rules/
  2. Setup script (see templates/setup-dev.template.sh) copies or symlinks:
    • tools/ai-rules/cursor/rules/*.mdc → .cursor/rules/
  3. Local overlay files remain in .cursor/rules/ with distinct names (e.g. 90-local-overlay.mdc)
  4. Consumer root AGENTS.md points agents to tools/ai-rules/AGENTS.md
MethodProsCons
SymlinkAuto-tracks submodule contentWindows permission/developer mode quirks
CopySimple, universalMust re-run script after submodule bump

Teams pick one approach and document it in consumer AGENTS.md.

Shared adapter files​

FileRole
00-common-superbuild.mdcEntry: read AGENTS.md and docs before workflow/build changes
01-cmake-conan-policy.mdcCMake authority, Conan role, presets, cross-platform
02-repo-layout.mdcsrc/, libs/, tools/ai-rules/, local overlays

Adapters should:

  • Use frontmatter (description, globs, alwaysApply as appropriate)
  • Stay concise; link paths to tools/ai-rules/docs/
  • Not duplicate full governance text

Self-governance in this repo​

When editing superbuild-workflow in this repository, Cursor loads .cursor/rules/:

  • 00-governance.mdc
  • 10-doc-sync.mdc
  • 20-change-scope.mdc

These do not ship to consumers as mandatory copies; they govern maintainers of the canonical repo.

Agent behavior expectations​

In a consuming repo, Cursor agents should:

  1. Respect materialized shared rules in .cursor/rules/
  2. Read tools/ai-rules/AGENTS.md for shared policy depth
  3. Read consumer root AGENTS.md for local exceptions
  4. Not edit files under tools/ai-rules/ for shared policy fixes unless tasked to update the submodule upstream

Updating after submodule bump​

When tools/ai-rules/cursor/rules/ changes:

  1. Bump submodule commit in consumer
  2. Re-run materialization step
  3. Preserve local overlay files (script should not delete 9*-local-*.mdc or similar convention)
  4. Smoke-test that Cursor lists expected rules