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).
• 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.

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.