Compound Engineering Plugin Development

Guide for working with the `compound-engineering` Claude Code plugin in the 8b-is-mp repository. This plugin follows the philosophy: **each unit of work makes subsequent work easier.**

Repository Structure

```

8b-is-mp/

├── .claude-plugin/

│ └── marketplace.json # Marketplace registry

├── plugins/compound-engineering/

│ ├── .claude-plugin/

│ │ └── plugin.json # Plugin metadata

│ ├── agents/ # Agent definitions by category

│ │ ├── review/

│ │ ├── research/

│ │ ├── design/

│ │ ├── workflow/

│ │ └── docs/

│ ├── commands/ # Command definitions

│ │ └── workflows/ # Workflow commands (prefixed workflows:)

│ ├── skills/ # Skill directories

│ │ └── skill-name/

│ │ ├── SKILL.md # Required: YAML frontmatter + instructions

│ │ ├── references/ # Optional: reference docs

│ │ └── scripts/ # Optional: helper scripts

│ ├── README.md # Component table and docs

│ └── CHANGELOG.md

└── docs/ # GitHub Pages static site

```

Verification Commands

Before updating any counts or descriptions, run these commands:

```bash

Count agents (in subdirectories)

find plugins/compound-engineering/agents -name "*.md" | wc -l

Count commands (includes nested workflow commands)

ls plugins/compound-engineering/commands/*.md plugins/compound-engineering/commands/*/*.md 2>/dev/null | wc -l

Count skills (directory-based)

ls -d plugins/compound-engineering/skills/*/ 2>/dev/null | wc -l

Validate JSON files

cat .claude-plugin/marketplace.json | jq .

cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .

```

Adding Components

Adding an Agent

1. Determine the appropriate category: `review/`, `research/`, `design/`, `workflow/`, or `docs/`

2. Create the agent file:

```bash

# Example: Add a new review agent

touch plugins/compound-engineering/agents/review/agent-name.md

```

3. Write agent definition in Markdown

4. Run verification commands to get new count

5. Update descriptions in all three locations (see "Updating Metadata" below)

Adding a Command

**Standard command:**

```bash

touch plugins/compound-engineering/commands/command-name.md

```

**Workflow command:**

```bash

Use workflows/ subdirectory and prefix name with workflows:

touch plugins/compound-engineering/commands/workflows/feature-name.md

Command invocation: /workflows:feature-name

```

Adding a Skill

1. Create skill directory structure:

```bash

mkdir -p plugins/compound-engineering/skills/skill-name/{references,scripts}

touch plugins/compound-engineering/skills/skill-name/SKILL.md

```

2. Write `SKILL.md` with required YAML frontmatter:

```markdown

---

name: skill-name

description: This skill should be used when... (third person, specific trigger conditions)

---

# Skill Name

[Detailed instructions for Claude Code...]

```

3. Add optional reference docs to `references/` and helper scripts to `scripts/`

Updating Metadata

When adding/removing components, update descriptions in **all three locations** (counts must match):

1. **`plugins/compound-engineering/.claude-plugin/plugin.json`**

- Update `description` field with new counts

- Bump `version` (semver: major.minor.patch)

2. **`.claude-plugin/marketplace.json`**

- Update plugin `description` field (must match plugin.json)

- Bump `version` (must match plugin.json)

3. **`plugins/compound-engineering/README.md`**

- Update component table with accurate counts

4. **`plugins/compound-engineering/CHANGELOG.md`**

- Add entry for the new version

5. **Rebuild documentation site:**

```bash

claude /release-docs

```

Version Bumping (Semantic Versioning)

Testing Workflow

```bash

1. Install marketplace locally

claude /plugin marketplace add /path/to/8b-is-mp

2. Install plugin

claude /plugin install 8b-compound-engineering

3. Test commands

claude /workflows:review

4. Test agents

claude agent kieran-rails-reviewer "test input"

```

Commit Message Format

Use this pattern for consistency:

```

[Action] [component] - brief description

Examples:

Add security-sentinel agent

Fix skill count mismatch in marketplace.json

Update version to 1.2.0 after adding 3 new commands

```

Documentation Site

Key Constraints

Count Synchronization

Component counts appear in three files. They **must** always match:

Always run verification commands before updating descriptions.

Stick to Claude Code Spec

Do not add custom fields to `marketplace.json` or `plugin.json`. Only use fields documented in the official [Claude Code Plugins Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference).

Agent Categories

Agents must be organized in subdirectories: `review/`, `research/`, `design/`, `workflow/`, `docs/`. Do not place agents directly in the `agents/` root.

Workflow Command Naming

Commands in `commands/workflows/` must be prefixed with `workflows:` in their filename/invocation (e.g., `workflows:review.md` → invoked as `/workflows:review`).

SKILL.md Frontmatter

Skills require YAML frontmatter with `name` and `description` fields. Description should be written in third person and specify when the skill should be used.

Common Tasks

**Add a new review agent:**

1. Create `plugins/compound-engineering/agents/review/agent-name.md`

2. Run `find plugins/compound-engineering/agents -name "*.md" | wc -l`

3. Update descriptions in plugin.json, marketplace.json, README.md

4. Bump versions in both JSON files

5. Update CHANGELOG.md

6. Run `claude /release-docs`

**Fix count mismatch:**

1. Run all verification commands

2. Update descriptions to match actual counts

3. Commit with message: `Fix component count mismatch`

**Prepare release:**

1. Ensure all tests pass

2. Update CHANGELOG.md with release notes

3. Bump version consistently across plugin.json and marketplace.json

4. Run `claude /release-docs`

5. Commit and tag release