Adapter Guide

How to create, maintain, and contribute adapters for AI coding tools.

What is an Adapter?

An adapter translates the root AGENTS.md source of truth into a tool's native configuration format. It does not contain original instructions — it references the root files.

Adapter Structure

adapters/{tool-name}/
├── {tool-native-file}     # e.g., CLAUDE.md, .cursorrules
├── setup.md               # Human-readable setup guide
└── {config-files}         # Optional tool-native config

Creating a New Adapter

Step 1: Research the Tool

• What file(s) does the tool auto-detect? (e.g., CLAUDE.md, .cursorrules)
• Where does it expect config files? (e.g., .vscode/, .gemini/)
• What format does it use? (markdown, JSON, YAML, plain text)

Step 2: Create the Adapter Directory

mkdir -p adapters/your-tool/

Step 3: Create the Native File

Start with this template:

<!-- AUTO-GENERATED REFERENCE — Source of truth: /AGENTS.md -->
<!-- Do not edit this file directly. Edit /AGENTS.md and re-sync. -->

# {Tool Name} Agent Instructions

This project uses multimodel-dev-os.
Full instructions: /AGENTS.md

## Tool-Specific Notes
{What's unique about this tool's behavior}

## References
- /AGENTS.md
- /MEMORY.md

Step 4: Create setup.md

Include:

• Overview (1 paragraph)
• Setup steps (numbered list)
• How it works (brief explanation)
• Tips (3-5 bullets)
• Troubleshooting table

Step 5: Submit a PR

See CONTRIBUTING.md.

Maintaining Adapters

• When a tool changes its config format, update the adapter
• Test adapter files with the actual tool before submitting
• Keep adapter files under 50 lines — they're references, not full configs
• Version adapter changes in CHANGELOG.md

Adapter Best Practices

1. Never duplicate instructions from AGENTS.md
2. Always reference root files with absolute paths (/AGENTS.md)
3. Include only tool-specific overrides or behavior notes
4. Test with the actual tool — don't guess at file detection behavior
5. Document quirks — if a tool has unusual behavior, note it in setup.md

Synchronizing Adapters

Use the adapter command to automatically synchronize native rule and settings files from the bundled adapter registry templates into your workspace root:

# Check status of installed rule files
npx multimodel-dev-os adapter status

# Preview diffs between template and local rule files
npx multimodel-dev-os adapter diff cursor

# Write rule files to target (forces backup if files exist and --force is passed)
npx multimodel-dev-os adapter sync cursor --approved --force
npx multimodel-dev-os adapter sync all --approved