Skip to content

CLAUDE.md

Latest commit

 

History

History
240 lines (170 loc) · 7.72 KB

CLAUDE.md

File metadata and controls

240 lines (170 loc) · 7.72 KB

Compound Engineering Plugin

This repository distributes the compound-engineering plugin from a portable source of truth, then generates platform-specific outputs for Claude Code and Copilot.

Repository Structure

compound-engineering-plugin/
├── portable/
│   └── compound-engineering/         # Canonical portable source
├── .claude-plugin/
│   └── marketplace.json          # Generated Claude marketplace catalog
├── .github/
│   ├── agents/                   # Generated Copilot agents
│   ├── skills/                   # Generated Copilot skills
│   └── copilot-mcp-config.json   # Generated Copilot MCP config
├── docs/                         # Documentation site (GitHub Pages)
│   ├── index.html                # Landing page
│   ├── css/                      # Stylesheets
│   ├── js/                       # JavaScript
│   └── pages/                    # Reference pages
└── plugins/
    └── compound-engineering/     # Generated Claude plugin
        ├── .claude-plugin/
        │   └── plugin.json        # Plugin metadata
        ├── agents/                # Specialized AI agents
        ├── commands/              # Slash commands
        ├── skills/                # Skills
        ├── mcp-servers/           # MCP servers (context7)
        ├── README.md              # Plugin documentation
        └── CHANGELOG.md           # Version history

Philosophy: Compounding Engineering

Each unit of engineering work should make subsequent units of work easier -- not harder.

When working on this repository, follow the compounding engineering process:

  1. Plan -- Understand the change needed and its impact
  2. Delegate -- Use AI tools to help with implementation
  3. Assess -- Verify changes work as expected
  4. Codify -- Update this CLAUDE.md with learnings

Docs Directory Convention

All workflows write output to {project_root}/docs/:

  • docs/ideation/ -- Ideation artifacts (generated by /workflows:ideate)
  • docs/plans/ -- Implementation plans (generated by /workflows:plan)
  • docs/brainstorms/ -- Brainstorm documents (generated by /workflows:brainstorm)
  • docs/solutions/ -- Compounded learnings (generated by /workflows:compound)
  • docs/execution-sessions/ -- Work session logs (generated by /workflows:work)

Workflows create the docs/ directory if it does not exist.

Gitignore convention: Projects should ignore ephemeral output but keep solutions:

docs/ideation/
docs/plans/
docs/brainstorms/
docs/execution-sessions/
# Do NOT ignore docs/solutions/ -- these are institutional knowledge

Working with the Plugin

Updating the Compounding Engineering Plugin

When agents, commands, or skills are added/removed, follow this checklist:

1. Count all components accurately

# Count agents
find portable/compound-engineering/agents -name '*.md' | wc -l

# Count commands
find portable/compound-engineering/commands -name '*.md' | wc -l

# Count skills
find portable/compound-engineering/skills -mindepth 1 -maxdepth 1 -type d | wc -l

2. Update ALL description strings with correct counts

The portable source is canonical. Generated descriptions still appear in multiple places and must match everywhere:

  • portable/compound-engineering/plugin.yaml -- base metadata
  • plugins/compound-engineering/.claude-plugin/plugin.json -- description field
  • .claude-plugin/marketplace.json -- plugin description field
  • plugins/compound-engineering/README.md -- intro paragraph

Format: "Includes X specialized agents, Y commands, and Z skill(s)."

3. Update version numbers

When adding new functionality, bump the version in:

  • portable/compound-engineering/plugin.yaml -- version
  • Rebuild outputs with bun run build:platforms

4. Rebuild generated platform outputs

bun run build:platforms

5. Update documentation

  • plugins/compound-engineering/README.md -- list all components
  • plugins/compound-engineering/CHANGELOG.md -- document changes
  • CLAUDE.md -- update structure diagram if needed

6. Rebuild documentation site

Run the release-docs command to update all documentation pages:

claude /release-docs

7. Validate JSON files

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

8. Verify before committing

# Ensure counts in descriptions match actual files
grep -o "Includes [0-9]* specialized agents" plugins/compound-engineering/.claude-plugin/plugin.json
find portable/compound-engineering/agents -name '*.md' | wc -l

Adding a New Agent

  1. Create portable/compound-engineering/agents/new-agent.md
  2. Rebuild outputs with bun run build:platforms
  3. Update README.md agent list
  4. Test with claude agent new-agent "test"

Adding a New Command

  1. Create portable/compound-engineering/commands/new-command.md
  2. Rebuild outputs with bun run build:platforms
  3. Update README.md command list
  4. Test with claude /new-command

Adding a New Skill

  1. Create skill directory: portable/compound-engineering/skills/skill-name/
  2. Add skill structure: 
    skills/skill-name/
├── SKILL.md           # Skill definition with frontmatter (name, description)
└── scripts/           # Supporting scripts (optional)
  3. Rebuild outputs with bun run build:platforms
  4. Update README.md with skill documentation
  5. Update CHANGELOG.md with the addition
  6. Test with claude skill skill-name

Skill file format (SKILL.md):

---
name: skill-name
description: Brief description of what the skill does
---

# Skill Title

Detailed documentation...

Testing Changes

Test Locally

  1. Install the marketplace locally:

    claude /plugin marketplace add https://github.com/The-Rabak/compound-engineering-plugin

  2. Install the plugin:

    claude /plugin install compound-engineering

  3. Test agents and commands:

    claude /workflows:review
claude agent rabak-laravel-reviewer "test message"

Validate JSON

Before committing, ensure JSON files are valid:

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

Commit Conventions

Follow these patterns for commit messages:

  • Add [agent/command name] -- Adding new functionality
  • Remove [agent/command name] -- Removing functionality
  • Update [file] to [what changed] -- Updating existing files
  • Fix [issue] -- Bug fixes
  • Simplify [component] to [improvement] -- Refactoring

Resources

Key Learnings

This section captures important learnings as we work on this repository.

Always count actual files before updating descriptions

The counts appear in multiple places (plugin.json, marketplace.json, README.md) and must all match. Use the verification commands in the checklist above.

Edit portable source first

portable/compound-engineering/ is now the canonical source. plugins/compound-engineering/ and .github/ are generated outputs and should be rebuilt with bun run build:platforms after portable changes.

Stick to the official Claude Code plugin spec

Custom fields in marketplace.json (downloads, stars, rating, categories, trending) may confuse users or break compatibility. Only include fields from the official spec.