5c32ef9233
Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Trevin Chow <tmchow@users.noreply.github.com>
2.2 KiB
title, category, tags, created, date, last_refreshed, module, severity, component, problem_type, root_cause
| title | category | tags | created | date | last_refreshed | module | severity | component | problem_type | root_cause | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Converter Target Provider Pitfalls | architecture |
|
2026-02-23 | 2026-02-23 | 2026-09-02 | converter-cli | medium | converter-cli | architecture_pattern | architectural_pattern |
Converter Target Provider Pitfalls
The step-by-step procedure for adding a target (types, converter, writer, CLI wiring, tests, docs) lives in docs/solutions/developer-experience/always-on-agents-md.md under "Adding a target provider"; the reference implementations are src/targets/opencode.ts + src/converters/claude-to-opencode.ts (most complete) and the Codex, Pi, and Antigravity pairs beside them. Before adding a converter target at all, check docs/solutions/integrations/native-plugin-install-strategy.md: a harness with a native plugin manifest gets a manifest, not a converter.
What that procedure does not tell you is where every past target went wrong. Each row below was hit at least once.
| Pitfall | Solution |
|---|---|
Double-nesting (.target/.target/) |
Check path.basename(outputRoot) before nesting |
| Inconsistent name normalization | Use a single normalizeName() function everywhere |
| Fragile content transformation | Test regex patterns against edge cases (file paths, URLs) |
| Heuristic section extraction fails | Use structural mapping (description -> Overview, body -> Procedure) instead |
| MCP config overwrites user edits | Always backup with timestamp before overwriting |
| Skill body not loaded | Verify ClaudeSkill has skillPath field for file reading |
| Missing deduplication | Build usedNames set before conversion, pass to each converter |
| Unsupported features cause silent loss | Always warn to stderr (hooks, incompatible MCP types, etc.) |
| Test isolation failures | Use unique temp directories per test, clean up afterward |
| Command namespace collisions after flattening | Use uniqueName() with deduplication, test multiple collisions |
Model field handling is its own trap per target; see docs/solutions/integrations/cross-platform-model-field-normalization.md and src/utils/model.ts.