feat: migrate repo releases to manual release-please (#293)
This commit is contained in:
Trevin Chow
90
AGENTS.md
90
AGENTS.md
@@ -1,19 +1,85 @@
|
||||
# Agent Instructions
|
||||
|
||||
This repository contains a Bun/TypeScript CLI that converts Claude Code plugins into other agent platform formats.
|
||||
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:** 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.
|
||||
- **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.
|
||||
|
||||
## Adding a New Target Provider (e.g., Codex)
|
||||
## Directory Layout
|
||||
|
||||
Use this checklist when introducing a new target provider:
|
||||
```
|
||||
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.
|
||||
@@ -37,17 +103,6 @@ Use this checklist when introducing a new target provider:
|
||||
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.
|
||||
@@ -60,4 +115,7 @@ This prevents resolution failures when the plugin is installed alongside other p
|
||||
|
||||
## Repository Docs Convention
|
||||
|
||||
- **Plans** live in `docs/plans/` and track implementation progress.
|
||||
- **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.
|
||||
|
||||
Reference in New Issue
Block a user