# 7. Multi-tool adapter framework + token-preserving uninstall

**Status:** Superseded · 2026-07-02 (v10.7.0 removed all non-native adapters - the pipeline targets Claude Code + Copilot CLI only; Codex CLI was later added as a third NATIVE target in v13.0.0, not through this adapter framework). Original acceptance: 2026-04-27 (v7.7.0 / v7.9.0). Kept as the historical record of why the adapter framework existed; install flags documented below no longer exist.

## Context

Through v7.6, the pipeline shipped to two CLIs only: Claude Code and Copilot CLI. Both expose **subagent dispatch** - the ability for the orchestrator to fan out work to parallel sub-agents with their own model, prompt, and context. This is a hard prerequisite for the 8-phase pipeline (Phase 1 parallel exploration, Phase 4 multi-reviewer review, Phase 7 multi-channel reporting).

Users started asking: "can it work with Cursor / Windsurf / Cline / Copilot Chat / Continue / Zed?" The honest answer is mixed:

- **Subagent dispatch:** none of those tools expose it. So the orchestration layer cannot run there; only single-shot rules / instructions are loaded into a chat context.
- **Knowledge layer:** the pipeline's value is split roughly 30/70 between orchestration and content. The 193 SKILL.md catalog + 12 rules describe how to write good Swift / Compose / TypeScript / etc. - that part is genuinely portable and would benefit users on tools where the orchestration can't run.

Three forces shaped this decision:

1. We didn't want to fork the project per tool.
2. We didn't want to silently drop support claims (e.g. saying "works with Cursor" when only the rules were loaded but the user expected `:dev` and `:review` to run).
3. We needed a clean opposite for every install path. Once `npx ... install --cursor` writes 174 files into a user's repo, there must be a documented, **token-preserving** way to remove them all in one step.

## Decision

We introduce a tiered support model and a uninstaller that's contractually forbidden from touching credential storage.

### Tier 1 - Full pipeline (orchestration + knowledge)

Tools with subagent dispatch get the full 8-phase pipeline.

- **Claude Code** (default, `--claude`)
- **Copilot CLI** (`--copilot`)

Both install slash commands / skills, agent personas, scripts, rules, and the full skills tree to `$HOME/.claude/` or `$HOME/.copilot/`.

### Tier 2 - Knowledge layer only (v7.7.0)

Tools without subagent dispatch but with a documented rules / instructions format. Pipeline orchestration commands are filtered out (they have no callable surface here); rules + skills catalog port natively to each tool's format.

- **Cursor** (`--cursor`) - `.cursor/rules/multi-agent-*.mdc` + `.cursorrules` legacy fallback
- **Windsurf** (`--windsurf`) - `.windsurfrules` (single file, marker-wrapped)
- **Cline** (`--cline`) - `.clinerules/multi-agent-*.md` per-skill files

### Tier 3 - Knowledge layer (v7.9.0)

Three more tools with the same contract.

- **GitHub Copilot Chat** (`--copilot-chat`) - `.github/copilot-instructions.md` marker-wrapped + `.github/instructions/multi-agent-*.instructions.md` per-skill
- **Continue.dev** (`--continue`) - `.continue/rules/multi-agent-*.md` per-skill
- **Zed AI** (`--zed`) - `.rules` single file, marker-wrapped

### Tier 4 - Manual port

Closed/proprietary tools (JetBrains AI, Codeium, Tabnine, Amazon Q Developer) get no automated installer. Skill content can be copy-pasted; PRs welcome.

### Adapter framework

All non-Tier-1 adapters share `pipeline/adapters/_base.mjs`:

- **`parseFrontmatter`** / **`walkSkills`** - read SKILL.md, return name + frontmatter + body
- **`inferGlobs`** - map skill name → glob pattern (`**/*.swift`, `**/*.{kt,kts}`, etc.) for tools that scope rules by file pattern
- **`replaceManagedBlock`** / **`removeManagedBlock`** - read/write/strip the `<!-- multi-agent-pipeline:begin / end -->` marker pair inside a user-owned file. Lets us share rules files (`.windsurfrules`, `.rules`, `copilot-instructions.md`) with content the user already authored.
- **`withoutOrchestrationSkills`** - filter `multi-agent-*` core skills (the orchestration namespace) from the export. They have no callable surface in Tier 2 / Tier 3 tools.
- **`concatSkills`** - single-document concatenation for adapters that emit one rules file (Windsurf, Zed) instead of per-skill files.

Each adapter exports a `{ name, install, uninstall }` contract. New adapters are mostly format-mapping over this base; adding a fourth would be ~150 LOC.

### Token-preserving uninstall

Every install path has a documented opposite via `npx @mmerterden/multi-agent-pipeline uninstall`. Slash command: `/multi-agent:uninstall` (renamed from `:delete` in v12.0.0) with a Copilot CLI peer `multi-agent-uninstall`. A `--all-data` flag extends it to also clear pipeline settings and the log root; tokens are never touched.

The uninstaller is **contractually forbidden** from touching:

1. Personal access tokens stored in macOS Keychain / Windows Credential Manager / Linux libsecret.
2. `~/.claude/CLAUDE.md` and `~/.claude/multi-agent-preferences.json` (user customizations).
3. User content outside the `<!-- multi-agent-pipeline:begin / end -->` markers in any shared rules file.

The contract is enforced statically by `smoke-delete-flow.sh` step 7:

```bash
grep -qE "credential-store|delete-generic-password|cmdkey /delete|secret-tool clear" uninstall.mjs
# fail varsa exit 1 - pattern eklenirse build kırılır
```

A future refactor that adds any credential-store deletion API to the uninstaller fails the build before it ships. Same posture for adapter modules: `smoke-adapters-tier3.sh` step 6 scans every Tier 3 adapter file.

## Consequences

Positive:

- One framework, six adapter targets. Tier 4 tools could be added incrementally without touching the orchestrator.
- Clear contract about what works where: Tier 1 = full pipeline, Tier 2/3 = knowledge layer only, Tier 4 = manual. No overpromising.
- Marker-wrapped blocks let us cohabit user-authored content cleanly. Users who ran `--zed` then later edited their `.rules` get their content back after `uninstall --zed`.
- Token-preserving uninstall is a reversible commitment. Removing the pipeline can never accidentally cost the user a re-auth round across Jira / GitHub / Bitbucket / Confluence / Vercel / Firebase / Telegram.
- Installer flag set is backward-compatible: zero-flag default still installs Claude Code exactly as v7.6 did.

Negative / costs:

- 6 adapters means 6 places where the format mapping can drift from upstream tool changes. Mitigation: round-trip smoke tests for each adapter exercise install + uninstall on every PR.
- `--all-tools` writes ~900 files (174 cursor + ~50 windsurf concat + 173 cline + 161 copilot-chat + 161 continue + 1 zed) into the user's repo. Acceptable: `.gitignore` patterns already cover most of these (`.cursor/`, `.continue/`, `.clinerules/`), and `:uninstall` cleans them all in one step.
- Per-tool format drift across tool versions (e.g. Cursor's `.mdc` format changes in 2027) requires per-adapter maintenance. Insulated from the orchestrator: bumping a Tier 2/3 tool format never touches Phase 1-7 logic.

## Alternatives Considered

**Refuse non-orchestration tools entirely:** simplest. Rejected because users on Cursor / Copilot Chat are a large slice of the pipeline's potential audience, and they get real value from the rules + skills catalog even without orchestration.

**Single "universal rules format" exported once, users hand-port:** simpler ship, but every user repeats the porting work, and no idempotent uninstall is possible without per-tool knowledge of where the rules ended up.

**Symlink mode (one rules dir, every tool reads from it):** elegant but no Tier 2/3 tool actually supports a single canonical location. Each tool insists on its own path (`.cursor/rules/`, `.windsurfrules`, `.clinerules/`, etc.).

**Generate adapters from a manifest at install time** instead of shipping per-adapter `.mjs` files: less code in the repo, but worse DX (debugging a generated adapter is painful) and harder to test per-tool round-trips. Per-adapter modules with shared `_base.mjs` won the readability tradeoff.

**Allow uninstall to clean credential entries:** rejected outright. Removing the tool should be a reversible decision; re-auth across Jira / GitHub / Bitbucket / Confluence / Vercel / Firebase / Telegram on every install + uninstall cycle is a poor user experience. The static check makes this guarantee permanent.