122 lines
6.0 KiB
Markdown
122 lines
6.0 KiB
Markdown
# Agent Instructions
|
|
|
|
This repository primarily houses the `compound-engineering` coding-agent plugin and the Claude Code marketplace/catalog metadata used to distribute it.
|
|
|
|
It also contains:
|
|
- the Bun/TypeScript CLI that converts Claude Code plugins into other agent platform formats
|
|
- additional plugins under `plugins/`, such as `coding-tutor`
|
|
- shared release and metadata infrastructure for the CLI, marketplace, and plugins
|
|
|
|
`AGENTS.md` is the canonical repo instruction file. Root `CLAUDE.md` exists only as a compatibility shim for tools and conversions that still look for it.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
bun install
|
|
bun test # full test suite
|
|
bun run release:validate # check plugin/marketplace consistency
|
|
```
|
|
|
|
## 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:** Releases are prepared by release automation, not normal feature PRs. The repo now has multiple release components (`cli`, `compound-engineering`, `coding-tutor`, `marketplace`) and one canonical root `CHANGELOG.md`. Use conventional titles such as `feat:` and `fix:` so release automation can classify change intent, but do not hand-bump release-owned versions or changelog entries in routine PRs.
|
|
- **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.
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
src/ CLI entry point, parsers, converters, target writers
|
|
plugins/ Plugin workspaces (compound-engineering, coding-tutor)
|
|
.claude-plugin/ Claude marketplace catalog metadata
|
|
tests/ Converter, writer, and CLI tests + fixtures
|
|
docs/ Requirements, plans, solutions, and target specs
|
|
```
|
|
|
|
## Repo Surfaces
|
|
|
|
Changes in this repo may affect one or more of these surfaces:
|
|
|
|
- `compound-engineering` under `plugins/compound-engineering/`
|
|
- the Claude marketplace catalog under `.claude-plugin/`
|
|
- the converter/install CLI in `src/` and `package.json`
|
|
- secondary plugins such as `plugins/coding-tutor/`
|
|
|
|
Do not assume a repo change is "just CLI" or "just plugin" without checking which surface owns the affected files.
|
|
|
|
## Plugin Maintenance
|
|
|
|
When changing `plugins/compound-engineering/` content:
|
|
|
|
- Update substantive docs like `plugins/compound-engineering/README.md` when the plugin behavior, inventory, or usage changes.
|
|
- Do not hand-bump release-owned versions in plugin or marketplace manifests.
|
|
- Do not hand-add canonical release entries to the root `CHANGELOG.md`.
|
|
- Run `bun run release:validate` if agents, commands, skills, MCP servers, or release-owned descriptions/counts may have changed.
|
|
|
|
Useful validation commands:
|
|
|
|
```bash
|
|
bun run release:validate
|
|
cat .claude-plugin/marketplace.json | jq .
|
|
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .
|
|
```
|
|
|
|
## Coding Conventions
|
|
|
|
- Prefer explicit mappings over implicit magic when converting between platforms.
|
|
- Keep target-specific behavior in dedicated converters/writers instead of scattering conditionals across unrelated files.
|
|
- Preserve stable output paths and merge semantics for installed targets; do not casually change generated file locations.
|
|
- When adding or changing a target, update fixtures/tests alongside implementation rather than treating docs or examples as sufficient proof.
|
|
|
|
## Commit Conventions
|
|
|
|
- Use conventional titles such as `feat: ...`, `fix: ...`, `docs: ...`, and `refactor: ...`.
|
|
- Component scope is optional. Example: `feat(coding-tutor): add quiz reset`.
|
|
- Breaking changes must be explicit with `!` or a breaking-change footer so release automation can classify them correctly.
|
|
|
|
## Adding a New Target Provider
|
|
|
|
Only add a provider when the target format is stable, documented, and has a clear mapping for tools/permissions/hooks. Use this checklist:
|
|
|
|
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.
|
|
|
|
## 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
|
|
|
|
- **Requirements** live in `docs/brainstorms/` — requirements exploration and ideation.
|
|
- **Plans** live in `docs/plans/` — implementation plans and progress tracking.
|
|
- **Solutions** live in `docs/solutions/` — documented decisions and patterns.
|
|
- **Specs** live in `docs/specs/` — target platform format specifications.
|