compound-engineering-plugin-mirror/plans/split-into-multiple-plugins.md

Split compound-engineering into Multiple Plugins

Issue: #20 Type: Enhancement / Refactor Date: 2025-12-15

Overview

Split the monolithic compound-engineering plugin (27 agents, 17 commands, 13 skills) into focused, composable plugins following Anthropic's plugin organization pattern.

Current State

compound-engineering/
├── agents/
│   ├── design/      (3 agents)
│   ├── docs/        (1 agent)
│   ├── research/    (4 agents)
│   ├── review/      (14 agents)
│   └── workflow/    (5 agents)
├── commands/        (17 commands)
├── skills/          (13 skills)
└── mcp-servers/     (2: playwright, context7)

Proposed Split

Core Plugin: compound-engineering-core

Philosophy: The foundational workflow that makes engineering compound. Includes all agents referenced by core commands.

Component	Items
Commands	workflows:plan, workflows:review, workflows:work, workflows:compound, resolve_pr_parallel, plan_review, generate_command, heal-skill, report-bug, release-docs, deploy-docs, resolve_parallel, resolve_todo_parallel, reproduce-bug, triage, changelog
Skills	compound-docs, file-todos, git-worktree, skill-creator, create-agent-skills, gemini-imagegen, agent-native-architecture, every-style-editor
Agents	repo-research-analyst, best-practices-researcher, framework-docs-researcher, spec-flow-analyzer, git-history-analyzer, code-simplicity-reviewer, pattern-recognition-specialist, architecture-strategist, performance-oracle, security-sentinel, data-integrity-guardian, data-migration-expert, deployment-verification-agent, agent-native-reviewer, bug-reproduction-validator, pr-comment-resolver, every-style-editor
MCP	context7

Rationale: Everything needed for the core workflow. /workflows:review references these review agents, so they must be in core. Plugin dev tools included for self-improvement.

---

Plugin: rails-dev

Focus: Ruby/Rails development with DHH/37signals style.

Component	Items
Skills	dhh-rails-style, dhh-ruby-style, andrew-kane-gem-writer, dspy-ruby
Agents	kieran-rails-reviewer, dhh-rails-reviewer, ankane-readme-writer, lint

Rationale: Everything Ruby/Rails in one place. Install this if you're a Rails dev.

---

Plugin: python-dev

Focus: Python development and review.

Component	Items
Agents	kieran-python-reviewer

Rationale: Python-specific tooling. Small now, can grow.

---

Plugin: typescript-dev

Focus: TypeScript/JavaScript development and review.

Component	Items
Agents	kieran-typescript-reviewer, julik-frontend-races-reviewer

Rationale: TypeScript/JS-specific tooling.

---

Plugin: frontend-design

Focus: Design implementation, iteration, and Figma sync.

Component	Items
Agents	figma-design-sync, design-iterator, design-implementation-reviewer
Skills	frontend-design
MCP	playwright

Rationale: Design-focused tooling that requires Playwright for screenshots.

---

Summary Table

Plugin	Agents	Commands	Skills	MCP	Framework
compound-engineering-core	17	14	8	1	Any
rails-dev	4	0	4	0	Ruby/Rails
python-dev	1	0	0	0	Python
typescript-dev	2	0	0	0	TS/JS
frontend-design	3	0	1	1	Any
compound-engineering (meta)	0	3	0	0	N/A
Total	27	17	13	2

Benefits

1. Composability - Users install only what they need
2. Clarity - Clear purpose for each plugin
3. Maintainability - Smaller, focused codebases
4. Discoverability - Easier to find relevant tools
5. Alignment - Matches Anthropic's official plugin structure

---

Migration Guide

For Existing Users

Before (single plugin):

claude /plugin install compound-engineering

After (choose what you need):

# Everyone needs core
claude /plugin install compound-engineering-core

# Add framework-specific plugins as needed
claude /plugin install rails-dev        # Ruby/Rails developers
claude /plugin install python-dev       # Python developers
claude /plugin install typescript-dev   # TypeScript/JS developers
claude /plugin install frontend-design  # Design-focused work

Install everything at once:

# One-liner to install all plugins
claude /plugin install compound-engineering-core rails-dev python-dev typescript-dev frontend-design

Or keep the original plugin as a meta-package:

# Install the meta-package (installs all 5 automatically)
claude /plugin install compound-engineering

Migration Scenarios

If you used...	Install these plugins
Just the workflow commands	compound-engineering-core
Rails code review	compound-engineering-core + rails-dev
Python code review	compound-engineering-core + python-dev
TypeScript code review	compound-engineering-core + typescript-dev
Design iteration/Figma	compound-engineering-core + frontend-design
Everything	All 5 plugins

What Moves Where

compound-engineering-core (install first, always)

Commands (14):

• workflows:plan, workflows:review, workflows:work, workflows:compound
• resolve_pr_parallel, plan_review
• generate_command, heal-skill, create-agent-skill
• resolve_parallel, resolve_todo_parallel, reproduce-bug, triage, changelog

Note: report-bug, release-docs, deploy-docs stay in the meta-package for project-level management.

Skills:

• compound-docs, file-todos, git-worktree
• skill-creator, create-agent-skills
• gemini-imagegen, agent-native-architecture
• every-style-editor

Agents:

• Research: repo-research-analyst, best-practices-researcher, framework-docs-researcher, spec-flow-analyzer, git-history-analyzer
• Review: code-simplicity-reviewer, pattern-recognition-specialist, architecture-strategist, performance-oracle, security-sentinel, data-integrity-guardian, data-migration-expert, deployment-verification-agent, agent-native-reviewer
• Workflow: bug-reproduction-validator, pr-comment-resolver, every-style-editor

MCP Servers: context7

---

rails-dev (Ruby/Rails developers)

Skills:

• dhh-rails-style - 37signals Rails conventions
• dhh-ruby-style - DHH Ruby style
• andrew-kane-gem-writer - Gem writing patterns
• dspy-ruby - DSPy for Ruby

Agents:

• kieran-rails-reviewer - Opinionated Rails review
• dhh-rails-reviewer - DHH-style Rails review
• ankane-readme-writer - Ankane-style READMEs
• lint - Ruby/Rails linting

---

python-dev (Python developers)

Agents:

• kieran-python-reviewer - Opinionated Python review

---

typescript-dev (TypeScript/JS developers)

Agents:

• kieran-typescript-reviewer - Opinionated TypeScript review
• julik-frontend-races-reviewer - Frontend race condition review

---

frontend-design (Design work)

Skills:

• frontend-design - Frontend design patterns

Agents:

• figma-design-sync - Sync with Figma designs
• design-iterator - Iterative design improvement
• design-implementation-reviewer - Design implementation review

MCP Servers: playwright (for screenshots)

---

Implementation Steps

Phase 1: Repository Structure

• Create new plugin directories in marketplace root:

  plugins/
  ├── compound-engineering-core/
  ├── rails-dev/
  ├── python-dev/
  ├── typescript-dev/
  └── frontend-design/
  

• Each plugin gets standard structure:

  plugin-name/
  ├── .claude-plugin/
  │   └── plugin.json
  ├── agents/
  ├── commands/
  ├── skills/
  ├── mcp-servers/  (if applicable)
  ├── CHANGELOG.md
  └── README.md
  

Phase 2: Move Components

• Copy agents to appropriate plugin directories
• Copy commands to appropriate plugin directories
• Copy skills to appropriate plugin directories
• Copy MCP server configs

Phase 3: Update Metadata

• Create plugin.json for each new plugin
• Update marketplace.json with all 5 plugins
• Write README.md for each plugin
• Create CHANGELOG.md for each plugin

Phase 4: Documentation

• Update docs site with new plugin structure
• Create migration guide page
• Update getting-started with new install instructions
• Add "which plugins do I need?" decision tree

Phase 5: Testing

• Test each plugin installs independently
• Test core plugin works standalone
• Test framework plugins work with core
• Verify no broken agent references

Phase 6: Release

• Deprecate old compound-engineering plugin (keep for 30 days)
• Release all 5 new plugins
• Announce migration path
• Update issue #20

---

Backward Compatibility

Recommendation: Keep compound-engineering as meta-package

The original compound-engineering plugin becomes a thin wrapper that installs all 5 plugins:

{
  "name": "compound-engineering",
  "version": "3.0.0",
  "description": "Meta-package: installs all compound-engineering plugins (core, rails-dev, python-dev, typescript-dev, frontend-design)",
  "dependencies": [
    "compound-engineering-core",
    "rails-dev",
    "python-dev",
    "typescript-dev",
    "frontend-design"
  ]
}

Benefits:

• Existing users run claude /plugin update compound-engineering and get the new structure
• New users can still install everything with one command
• No breaking change for current users
• Clear path to selective installation if desired

---

References

• Anthropic's plugin structure: https://github.com/anthropics/claude-code/tree/main/plugins
• Current plugin: /plugins/compound-engineering/
• Issue: #20