Skip to main content

Alternative tool integration

This repository is intentionally tool-agnostic at its core. Cursor is supported via thin adapters; other AI-augmented IDEs and agents can consume the same canonical content without adopting .mdc format.

Canonical sources (use these first)​

AssetTypical use
AGENTS.mdPrimary agent entry point; purpose, boundaries, quick reference
docs/*.mdDeep policy, rationale, governance
templates/Bootstrapping consumer repos
README.mdHuman onboarding and index

Any tool that can include repository files in context should prioritize these paths.

Why portable Markdown​

  • Reviewability — architects diff policy in GitLab like code
  • Longevity — not tied to one vendor's rule file format
  • Composability — multiple tools read the same sentences without sync drift
  • Human parity — developers and agents share one truth

Tool-specific files should be thin adapters: summaries, guardrails, and pointers — not a second full policy corpus.

Integration patterns by tool class​

IDE agents with project rules (Cursor, similar)​

  • Materialize or symlink cursor/rules/*.mdc into workspace .cursor/rules/
  • Add local overlays for exceptions
  • See cursor-integration.md

CLI / cloud agents (custom scripts, CI bots)​

  • Pass AGENTS.md and selected docs/ paths in the system or project prompt
  • Pin submodule revision in CI for reproducible agent behavior
  • Example prompt header: "Follow tools/ai-rules/AGENTS.md and tools/ai-rules/docs/governance.md"

GitHub/GitLab Copilot-style instructions​

  • Map AGENTS.md content to vendor instruction files in the consumer if required
  • Keep generated/vendor files derived from submodule content, documented as downstream artifacts
  • Regenerate when submodule bumps; do not treat vendor file as authoritative

MCP / custom knowledge bases​

  • Index docs/ and AGENTS.md from tools/ai-rules/ at a fixed revision
  • Include repository-layout.md and cmake-conan-policy.md for build tasks

Adapter authoring guidelines​

When adding support for a new tool:

  1. Add a short doc section or docs/<tool>-integration.md if non-trivial
  2. Place adapter files in a clearly named directory (e.g. cursor/rules/, future copilot/ if needed)
  3. Each adapter file should reference canonical doc paths under tools/ai-rules/
  4. Avoid duplicating paragraphs from docs/ — link by path

What not to do​

  • Move policy exclusively into a tool-specific format
  • Require a proprietary sync pipeline for basic agent correctness
  • Fork AGENTS.md per tool with divergent semantics

Testing multi-tool consistency​

When changing policy here, ask:

  • Can an agent with only AGENTS.md + one doc follow the change?
  • Do Cursor adapters still point to the updated doc sections?
  • Do consumer templates need updates?