Trevin Chow
4.8 KiB
title, date, last_updated, category, module, problem_type, component, symptoms, root_cause, resolution_type, severity, tags
| title | date | last_updated | category | module | problem_type | component | symptoms | root_cause | resolution_type | severity | tags | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Native plugin install strategy for supported harnesses | 2026-06-19 | 2026-09-02 | integrations | installer | integration_decision | installer |
|
evolving_platform_install_surfaces | install_strategy | medium |
|
Native Plugin Install Strategy
Per-harness install commands live in README.md ("Install" and "More Install Options") and are not repeated here. This doc holds the decision and the two rules that fall out of it.
Decision
Compound Engineering is a self-contained skills package: specialist behavior lives in skill-local prompt assets under references/agents/ or references/personas/, and there are no formal standalone CE agents. So every supported harness installs through its own native plugin/package mechanism (Claude, Codex, Cursor, Copilot, Droid, Qwen, Kimi, OpenCode, Pi, Antigravity, Cline, Grok Build, Devin, omp). The Bun converter stays repo tooling for development, compatibility fixtures, and legacy cleanup; it is not the user-facing installer. The root package is not a public npm installer: release automation must not publish @every-env/compound-plugin, and README install instructions must not rely on bunx. Kiro was dropped as a documented install target; converter and cleanup code for it remains only for regression coverage and old-artifact handling.
A native manifest beats a converter target
Adding "support for platform X" looks like a normal new target provider (--to x, converter, writer, output tree). When the platform already has a plugin manifest and marketplace contract, that is the wrong first move: native plugin support is a distribution contract, not a format-conversion problem. A converter target would add a generated install path to document, test, version, and clean up, while users would still need the manifest for the platform's normal install flow. This is how Kimi landed: PR #997 proposed a converter target; PR #998 shipped .kimi-plugin/plugin.json plus .kimi-plugin/marketplace.json instead (docs/specs/kimi.md lists which Kimi fields are used and which runtime fields are intentionally absent).
Wire a native surface as a first-class release surface: the release-owned manifest goes in .github/release-please-config.json as an extra file of the root component; static catalog files with no version stay out of release ownership and are validated instead; bun run release:validate rejects a missing manifest, version drift against the root plugin version, declared asset paths that do not exist, marketplace schema drift, plugin-ID drift against the Claude catalog, and root-local marketplace sources such as "." or "./" (local-development placeholders only).
Warning signs that a proposed target belongs in native metadata instead:
- the platform docs describe a
plugin.json-style manifest in the source repo - the platform supports a custom marketplace or catalog pointing at repository sources
- the target would mostly copy existing skills without meaningful tool, permission, hook, or model conversion
- install docs would tell users to run this repo's converter instead of the platform's documented install path
Default --to codex suppresses skills on purpose
Codex reads .codex-plugin/plugin.json (skills: "./skills/") natively, so the converter's default --to codex mode is deliberately not a second skill installer: it suppresses skills, prompts, command-skills, and MCP so the native install is the sole source for those artifact types, and only converts formal Claude agents (empty for the current package). The non-obvious invariant is externallyManagedSkillNames (src/converters/claude-to-codex.ts -> src/targets/codex.ts): default mode passes the native skill names to the writer so cleanup does not mistake natively installed skills for stale converter-owned artifacts. Drop it and re-running install --to codex sweeps active native skills into backup.
codexIncludeSkills (legacy full mode, kept for fixtures and cleanup tests) can still emit copied skills and generated prompts; there, keep unknown slash references unchanged so transformContentForCodex() cannot corrupt URLs or app routes, treat ce:* and workflows:* names as legacy cleanup-only artifacts, and keep native skill names hyphenated. Do not reintroduce prompt wrappers for current native skills.