Skip to main content

ADR-0028: Selectable IDE adapter materialization (Cursor and Copilot)

  • Status: Accepted
  • Date: 2026-07-29
  • Deciders: Michel Gillet

Context​

A2C policy lives in host-neutral rules/, prompts/, and AGENTS.md. IDE hosts need thin wrappers:

  • Cursor loads .cursor/rules/*.mdc
  • GitHub Copilot loads .github/copilot-instructions.md and .github/instructions/*.instructions.md

Bootstrap already materializes Cursor adapters. Teams that standardize on Copilot (or use both) need the same policy delivered in Copilot’s shape, without forcing Cursor-only paths.

Decision​

  1. Selectable adapters — Operators choose cursor, copilot, or both via --ide-adapters on a2c bootstrap and a2c setup-dev.
  2. Default remains cursor — Preserves existing bootstrap behavior.
  3. Persistence — Selected adapters are stored in:
    • workflows.ide_adapters in tool-state config.yaml
    • ide_adapters on adoption.yaml
  4. Resolution order — Explicit CLI → config → adoption → default [cursor].
  5. Materialization — Only managed A2C filenames are overwritten; project overlays (e.g. .cursor/rules/30-*.mdc, .github/instructions/99-*.instructions.md) are left untouched.
  6. Delivery-aware paths — Submodule/clone mounts rewrite method paths to tools/ai-rules/ for both hosts.
  7. Doctor — Warns when a selected adapter’s managed files are missing or stale for mount delivery.

Consequences​

Positive​

  • Copilot-first shops can adopt A2C without Cursor-specific wrappers.
  • Dual-host repos can keep both trees in sync via setup-dev.
  • Default stays Cursor-compatible.

Negative​

  • Two adapter trees can drift if operators edit managed files by hand (mitigated by re-running setup-dev).
  • Additional method assets under copilot/ to maintain alongside cursor/rules/.

Alternatives considered​

  • Always materialize both — Rejected; pollutes .github/ for Cursor-only teams.
  • Symlink strategy — Rejected; Windows and Copilot file shapes differ.
  • Single AGENTS.md only — Insufficient; Cursor/Copilot do not load root AGENTS as always-on IDE rules by themselves in all modes.

References​

Supersedes​

  • (none)

Superseded by​

  • (none)

Amends​

  • (none)