compound-engineering: Instructions file for Claude Code

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.
• Linked versions (cli + compound-engineering): The linked-versions release-please plugin keeps cli and compound-engineering at the same version. This is intentional -- it simplifies version tracking across the CLI and the plugin it ships. A consequence is that a release with only plugin changes will still bump the CLI version (and vice versa). The CLI changelog may also include commits that exclude-paths would normally filter, because linked-versions overrides exclusion logic when forcing a synced bump. This is a known upstream release-please limitation, not a misconfiguration. Do not flag linked-version bumps as unnecessary.
• 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).
• Scratch Space: When authoring or editing skills and agents that need repo-local scratch space, instruct them to use .context/ for ephemeral collaboration artifacts. Namespace compound-engineering workflow state under .context/compound-engineering/<workflow-or-skill-name>/, add a per-run subdirectory when concurrent runs are plausible, and clean scratch artifacts up after successful completion unless the user asked to inspect them or another agent still needs them. Durable outputs like plans, specs, learnings, and docs do not belong in .context/.
• Character encoding:
  • Identifiers (file names, agent names, command names): ASCII only -- converters and regex patterns depend on it.
  • Markdown tables: Use pipe-delimited (| col | col |), never box-drawing characters.
  • Prose and skill content: Unicode is fine (emoji, punctuation, etc.). Prefer ASCII arrows (->, <-) over Unicode arrows in code blocks and terminal examples.