# 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

```bash
mkdir -p adapters/your-tool/
```

### Step 3: Create the Native File

Start with this template:

```markdown
<!-- 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](../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`
