e97f85bd53
* Add OpenCode converter coverage and specs * Add Codex target support and spec docs * Generate Codex command skills and refresh spec docs * Add global Codex install path * fix: harden plugin path loading and codex descriptions * feat: ensure codex agents block on convert/install * docs: clarify target branch usage for review * chore: prep npm package metadata and release notes * docs: mention opencode and codex in changelog * docs: update CLI usage and remove stale todos * feat: install from GitHub with global outputs
2.1 KiB
2.1 KiB
Agent Instructions
This repository contains a Bun/TypeScript CLI that converts Claude Code plugins into other agent platform formats.
Working Agreement
- Branching: Create a feature branch for any non-trivial change. If already on the correct branch for the task, keep using it; do not create additional branches or worktrees unless explicitly requested.
- Safety: Do not delete or overwrite user data. Avoid destructive commands.
- Testing: Run
bun testafter changes that affect parsing, conversion, or output. - Output Paths: Keep OpenCode output at
opencode.jsonand.opencode/{agents,skills,plugins}. - ASCII-first: Use ASCII unless the file already contains Unicode.
Adding a New Target Provider (e.g., Codex)
Use this checklist when introducing a new target provider:
-
Define the target entry
- Add a new handler in
src/targets/index.tswithimplemented: falseuntil complete. - Use a dedicated writer module (e.g.,
src/targets/codex.ts).
- Add a new handler in
-
Define types and mapping
- Add provider-specific types under
src/types/. - Implement conversion logic in
src/converters/(from Claude → provider). - Keep mappings explicit: tools, permissions, hooks/events, model naming.
- Add provider-specific types under
-
Wire the CLI
- Ensure
convertandinstallsupport--to <provider>and--also. - Keep behavior consistent with OpenCode (write to a clean provider root).
- Ensure
-
Tests (required)
- Extend fixtures in
tests/fixtures/sample-plugin. - Add spec coverage for mappings in
tests/converter.test.ts. - Add a writer test for the new provider output tree.
- Add a CLI test for the provider (similar to
tests/cli.test.ts).
- Extend fixtures in
-
Docs
- Update README with the new
--tooption and output locations.
- Update README with the new
When to Add a Provider
Add a new provider when at least one of these is true:
- A real user/workflow needs it now.
- The target format is stable and documented.
- There’s a clear mapping for tools/permissions/hooks.
- You can write fixtures + tests that validate the mapping.
Avoid adding a provider if the target spec is unstable or undocumented.