Getting Started with Compounding Engineering

Installation

Prerequisites

• Claude Code installed and configured
• A GitHub account (for marketplace access)
• Node.js 18+ (for MCP servers)

Step 1: Add the Marketplace

First, add the Every Marketplace to your Claude Code installation:

claude /plugin marketplace add https://github.com/EveryInc/every-marketplace

Step 2: Install the Plugin

Install the compounding-engineering plugin from the marketplace:

claude /plugin install compounding-engineering

Step 3: Verify Installation

Verify the plugin is installed correctly:

claude /plugin list

You should see compounding-engineering in the list of installed plugins.

Quick Start

Here are the most common ways to use the plugin:

Run a Code Review

The /workflows:review command runs a comprehensive code review using multiple agents in parallel:

# Review a PR by number
/workflows:review 123

# Review the current branch
/workflows:review

# Review a specific branch
/workflows:review feature/my-feature

Use a Specialized Agent

Invoke agents directly for specific tasks:

# Rails code review with Kieran's conventions
claude agent kieran-rails-reviewer "Review the UserController"

# Security audit
claude agent security-sentinel "Audit authentication flow"

# Research best practices
claude agent best-practices-researcher "Find pagination patterns for Rails"

Invoke a Skill

Skills provide domain expertise on demand:

# Generate images with Gemini
skill: gemini-imagegen

# Write Ruby in DHH's style
skill: dhh-ruby-style

# Create a new Claude Code skill
skill: create-agent-skills

Configuration

MCP Server Configuration

If MCP servers don't auto-load, add them manually to your .claude/settings.json:

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Environment Variables

Some skills require environment variables:

The Compounding Engineering Philosophy

Every unit of engineering work should make subsequent units of work easier—not harder.

This philosophy manifests in four key practices:

Using Agents

Agents are specialized personas that can be invoked to perform specific tasks. They're designed to bring deep expertise in their domain.

Invoking Agents

# Basic syntax
claude agent [agent-name] "[optional message]"

# Examples
claude agent kieran-rails-reviewer
claude agent security-sentinel "Audit the payment flow"
claude agent git-history-analyzer "Show changes to user model"

Agent Categories

View All Agents

Using Commands

Slash commands automate complex multi-step workflows. They orchestrate multiple agents, tools, and processes into a single command.

Running Commands

# Workflow commands (prefix: /workflows:)
/workflows:plan
/workflows:review 123
/workflows:work
/workflows:codify

# Utility commands
/changelog
/triage
/reproduce-bug

The Review Workflow

The /workflows:review command is the most comprehensive. It:

1. Detects the review target (PR, branch, or current changes)
2. Sets up a git worktree for isolated analysis
3. Runs 10+ review agents in parallel
4. Synthesizes findings by severity (P1/P2/P3)
5. Creates structured todo files for each finding
6. Generates a summary report

View All Commands

Using Skills

Skills provide domain expertise that Claude Code can invoke on-demand. Unlike agents (which are personas), skills are bodies of knowledge with templates, references, and workflows.

Invoking Skills

# In your prompt, reference the skill
skill: gemini-imagegen

# Or ask Claude to use it
"Use the dhh-ruby-style skill to refactor this code"

Skill Structure

Skills typically contain:

• SKILL.md - Main documentation and instructions
• references/ - Supporting documentation
• templates/ - Code templates and patterns
• workflows/ - Step-by-step procedures
• scripts/ - Executable scripts (if needed)

View All Skills

Code Review Workflow Guide

The code review workflow is the heart of Compounding Engineering. Here's how to get the most out of it.

Basic Review

# Review a PR
/workflows:review 123

# Review current branch
/workflows:review

Understanding Findings

Findings are categorized by severity:

• P1 Critical - Blocks merge. Security vulnerabilities, data corruption risks, breaking changes.
• P2 Important - Should fix. Performance issues, architectural concerns, reliability problems.
• P3 Nice-to-Have - Enhancements. Minor improvements, cleanup, documentation.

Working with Todo Files

Review findings are stored as todo files in the todos/ directory:

# List all pending todos
ls todos/*-pending-*.md

# Triage findings
/triage

# Resolve todos in parallel
/resolve_todo_parallel

Creating Custom Agents

You can create custom agents tailored to your team's needs. Agents are defined as markdown files with YAML frontmatter.

Agent File Structure

---
name: my-custom-agent
description: Brief description of what this agent does
---

# Agent Instructions

You are [role description].

## Your Responsibilities
1. First responsibility
2. Second responsibility

## Guidelines
- Guideline one
- Guideline two

Agent Location

Place custom agents in:

• .claude/agents/ - Project-specific agents
• ~/.claude/agents/ - User-wide agents

Creating Custom Skills

Skills are more complex than agents. They can include references, templates, workflows, and scripts.

Skill Directory Structure

my-skill/
  SKILL.md           # Main skill file (required)
  references/        # Supporting documentation
    concept-one.md
    concept-two.md
  templates/         # Code templates
    basic-template.md
  workflows/         # Step-by-step procedures
    workflow-one.md
  scripts/           # Executable scripts
    helper.py

SKILL.md Format

---
name: my-skill
description: Brief description shown when skill is invoked
---

# Skill Title

Detailed instructions for using this skill.

## Quick Start
...

## Reference Materials
The skill includes references in the `references/` directory.

## Templates
Use templates from the `templates/` directory.