64 lines
3.7 KiB
Markdown
64 lines
3.7 KiB
Markdown
# 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 test` after changes that affect parsing, conversion, or output.
|
||
- **Release versioning:** The root CLI package (`package.json`, root `CHANGELOG.md`, and repo `v*` tags) uses one shared release line managed by semantic-release on `main`. Do not start or maintain a separate root CLI version stream. Use conventional commits and let release automation write the next root package version. Keep the root changelog header block in sync with `.releaserc.json` `changelogTitle` so generated release entries stay under the header. Embedded marketplace plugin metadata (`plugins/compound-engineering/.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`) is a separate version surface and may differ, but contributors should not guess or hand-bump release versions for it in normal PRs. The automated release process decides the next plugin/marketplace releases and changelog entries after deciding which merged changes ship together.
|
||
- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, command go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
|
||
- **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:
|
||
|
||
1. **Define the target entry**
|
||
- Add a new handler in `src/targets/index.ts` with `implemented: false` until complete.
|
||
- Use a dedicated writer module (e.g., `src/targets/codex.ts`).
|
||
|
||
2. **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.
|
||
|
||
3. **Wire the CLI**
|
||
- Ensure `convert` and `install` support `--to <provider>` and `--also`.
|
||
- Keep behavior consistent with OpenCode (write to a clean provider root).
|
||
|
||
4. **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`).
|
||
|
||
5. **Docs**
|
||
- Update README with the new `--to` option and output locations.
|
||
|
||
## 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.
|
||
|
||
## Agent References in Skills
|
||
|
||
When referencing agents from within skill SKILL.md files (e.g., via the `Agent` or `Task` tool), always use the **fully-qualified namespace**: `compound-engineering:<category>:<agent-name>`. Never use the short agent name alone.
|
||
|
||
Example:
|
||
- `compound-engineering:research:learnings-researcher` (correct)
|
||
- `learnings-researcher` (wrong - will fail to resolve at runtime)
|
||
|
||
This prevents resolution failures when the plugin is installed alongside other plugins that may define agents with the same short name.
|
||
|
||
## Repository Docs Convention
|
||
|
||
- **Plans** live in `docs/plans/` and track implementation progress.
|