compound-engineering-core

Compound Engineering System

Reusable templates for bootstrapping projects with compound engineering practices: structured AI-assisted development, decision records, runbooks, and CI workflows.

This repository now also contains a private Claude plugin marketplace so shared workflow behavior can be updated in one place and reused across many repositories.

What's Included

Path	Purpose
templates/CLAUDE.md.base	Base Claude Code instructions (branch workflow, planning, memory, circuit breakers)
templates/.claude/settings.json	Default Claude Code permissions and deny rules
templates/.claude/settings.marketplace.example.json	Example project settings for marketplace/plugin enforcement
templates/.claude/agents/codex-gate-runner.md	Legacy compatibility shim for older repos; direct Codex invocation is now canonical
templates/.claude/agents/codex-pr-correctness-reviewer.md	Legacy compatibility shim for older repos; direct Codex invocation is now canonical
templates/.claude/agents/codex-pr-edgecase-reviewer.md	Legacy compatibility shim for older repos; direct Codex invocation is now canonical
templates/.claude/commands/workflows/brainstorm.md	Discovery command to clarify WHAT/why before planning
templates/.claude/commands/workflows/research.md	Deep research workflow with iterative PM feedback loops
templates/.claude/commands/workflows/deepen-plan.md	Plan hardening workflow with targeted research passes
templates/.claude/commands/workflows/plan-loop.md	PM + reviewer iterative planning loop command
templates/.claude/commands/workflows/debug.md	Structured repro/root-cause workflow with evidence capture
templates/.claude/commands/workflows/explain.md	Decision and behavior trace workflow for why/how questions
templates/.claude/commands/workflows/work.md	Execute approved plans with tracker + gate enforcement
templates/.claude/commands/workflows/pr-review.md	Mandatory PR review command
templates/.claude/commands/workflows/epic-delta-loop.md	Nested re-planning loop for mid-epic scope changes
templates/compound-engineering.local.example.md	Review-agent and external-gate configuration template
templates/docs/adr/	Architecture Decision Record template
templates/docs/runbooks/	Operational runbook template
templates/docs/runbooks/configure-codex-browser-mcp.md	Codex browser MCP setup for frontend validation
templates/docs/runbooks/configure-private-marketplace.md	Shared plugin rollout/update runbook
templates/docs/solutions/	Solution documentation structure
templates/docs/process/	Workflow definitions and sequence diagrams
templates/docs/plans/	Plan lifecycle + real-time execution tracker template
templates/docs/research/	Deep research artifact structure and conventions
templates/docs/knowledge/	Plan index and knowledge base lifecycle guidance
templates/docs/reviews/	Review evidence templates and logging conventions
templates/scripts/	Worktree creation/removal helpers
templates/.github/workflows/	CI workflow templates
.claude-plugin/marketplace.json	Private Claude plugin marketplace manifest
plugins/compound-engineering-core/	Shared plugin with core workflows and agents
scripts/validate-marketplace.sh	Validates marketplace and plugin manifests
scripts/release-plugin.sh	Bumps plugin version in both manifests

Usage

Option A: New project starter (recommended)

1. Click Use this template on this repository.
2. Clone your new repository locally.
3. Apply starter files into the repo root:

./bootstrap/apply-template.sh .

Template command files are still copied for backwards compatibility. Use plugin-prefixed commands in day-to-day work so shared updates come from the marketplace plugin.

4. Add marketplace once on your machine:

claude plugin marketplace add https://github.com/adam-badar/compound-engineering-system.git

5. Install shared plugin once (works across all repos on this machine):

claude plugin install compound-engineering-core@compound-engineering-marketplace --scope user

6. Rename CLAUDE.md.base to CLAUDE.md and customize project-specific sections.
7. Copy compound-engineering.local.example.md to compound-engineering.local.md and customize reviewers.
8. Run claude mcp add -s user codex-xhigh -- codex mcp-server -c 'model=\"gpt-5.3-codex\"' -c 'model_reasoning_effort=\"xhigh\"' once per machine.
9. Configure Codex browser MCP once per machine for frontend-validate (see templates/docs/runbooks/configure-codex-browser-mcp.md).
10. Verify plugin is installed:

claude plugin list
# should include: compound-engineering-core@compound-engineering-marketplace

11. If requirements are ambiguous, run discovery first (add freshness research controls for volatile domains):