claude-engineering-plugin/AGENTS.md

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

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). GitHub release PRs and GitHub Releases are the canonical release-notes surface for new releases; root CHANGELOG.md is only a pointer to that history. Use conventional titles such as feat: and fix: so release automation can classify change intent, but do not hand-bump release-owned versions or hand-author release notes 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 release entries to CHANGELOG.md or treat it as the canonical source for new releases.
• Run bun run release:validate if agents, commands, skills, MCP servers, or release-owned descriptions/counts may have changed.

Useful validation commands:

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.