mirror of
https://github.com/EveryInc/compound-engineering-plugin.git
synced 2026-10-02 19:57:22 +02:00
55 lines
3.2 KiB
Markdown
55 lines
3.2 KiB
Markdown
---
|
|
title: "Cross-platform model field normalization for target converters"
|
|
date: 2026-03-29
|
|
category: integration-issues
|
|
module: src/converters
|
|
problem_type: integration_issue
|
|
component: tooling
|
|
symptoms:
|
|
- "Target platforms received raw Claude model aliases (e.g., 'sonnet') they could not resolve"
|
|
- "Duplicated CLAUDE_FAMILY_ALIASES and normalizeModel logic across converters with divergent alias values"
|
|
root_cause: config_error
|
|
resolution_type: code_fix
|
|
severity: medium
|
|
tags:
|
|
- model-normalization
|
|
- converters
|
|
- cross-platform
|
|
- opencode
|
|
- droid
|
|
- copilot
|
|
- codex
|
|
---
|
|
|
|
# Cross-platform model field normalization for target converters
|
|
|
|
Claude Code uses bare model aliases (`model: sonnet`) in agent and command frontmatter. A `model` field in a target's frontmatter does not mean the format is the same: each target wants something different, and the wrong guess is an invalid config rather than a visible error. `src/utils/model.ts` is the single alias map (`CLAUDE_FAMILY_ALIASES`) and normalization helpers; converters must use it rather than carrying a local copy (two divergent copies is how Qwen shipped `sonnet -> claude-sonnet` instead of the dated ID).
|
|
|
|
## Per-target behavior and why
|
|
|
|
| Target | Behavior | Why |
|
|
|--------|----------|-----|
|
|
| OpenCode | Resolve alias + add provider prefix (`anthropic/claude-sonnet-5-5`) | Multi-provider; routes on the `provider/model-id` prefix. Same rule for any future multi-provider target with that format (the removed Qwen and OpenClaw converters used it). |
|
|
| Droid (Factory) | Pass through as-is (`sonnet`) | Factory resolves Claude's bare aliases natively and also accepts dated IDs and `custom:<model>`; normalizing to a form it also accepts adds nothing. |
|
|
| Copilot | Drop | Copilot's `model` field takes Copilot display names ("Claude Opus 4.5"), not Claude model IDs or aliases, and has no documented resolution for them. Spec: "If unset, inherits the default model." |
|
|
| Codex | Drop | Skill frontmatter supports only `name` and `description` (Rust `SkillFrontmatter` struct). Model selection is global via `config.toml` or `/model`. |
|
|
|
|
Copilot and Droid converters remain as cleanup remnants, not install targets; the installable Bun targets are `opencode`, `codex`, `pi`, and `antigravity`.
|
|
|
|
## Rejected assumptions
|
|
|
|
- Pass everything through: right for Droid only.
|
|
- Every target wants the same format: false, see table.
|
|
- Codex skills accept a model override: they do not.
|
|
- Qwen should drop model because it is single-provider: wrong, it was multi-provider via `settings.json`; the removal was for native-install reasons, not model handling.
|
|
- Copilot has no model support: wrong; it has one, in a format we cannot produce from Claude values, which is a different reason to drop.
|
|
|
|
## Rule
|
|
|
|
**When in doubt, drop.** If you cannot confidently produce the target's expected format, omit the field rather than emit a possibly invalid value; targets fall back to a default when `model` is unset. Research a new target's model format before assuming pass-through or copying another converter, and add new alias generations only in `src/utils/model.ts`.
|
|
|
|
## Related
|
|
|
|
- `docs/solutions/adding-converter-target-providers.md`
|
|
- `docs/solutions/integrations/native-plugin-install-strategy.md` for why Qwen and OpenClaw converters were removed
|