Compound engineering workflow using Agent Teams with embedded Ralph Loops. Commands: /ct:setup (safe install into existing projects), /ct:plan (research + plan), /ct:build (Agent Team execution with Ralph loops), /ct:review (multi-lens code review team), /ct:quick (fast builds), /ct:compound (extract learnings). Skills: ralph-loop (persistent retry-until-green pattern), compound-learning (CLAUDE.md knowledge management).

version
1.0.0

Install

/plugin install compound-teams@compound-teams-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add tbdng/compound-teams-plugin.

Contents

Discovered from source

Skills 2

Compound Learning — Project Memory Management

The compound learning system turns each build/review cycle into accumulated project knowledge via CLAUDE.md.

How It Works

Every project has a CLAUDE.md that Claude reads at the start of each session. The /ct:compound command appends learnings after each cycle. Over time, Claude becomes increasingly effective at working in this specific codebase.

Entry Format

Every learning entry must be:

Dated

[2026-02-07] Always use server actions for mutations in Next.js App Router

Specific

[2026-02-07] The Stripe webhook handler at /app/api/webhooks/stripe/route.ts
needs `export const config = { api: { bodyParser: false } }` — without raw
body, constructEvent() throws "No signatures found"

Actionable

Future Claude should know what to DO, not just what happened:

✅ "Use prisma.$transaction() when updating both the user and subscription tables" ❌ "Had a bug with Prisma transactions"

Section Structure

CLAUDE.md should have these sections (created by /ct:setup):

What Works

Patterns, libraries, approaches that proved effective:

[2026-02-07] Zod schemas as single source of truth: define once in /lib/schemas/,
use for API validation, form validation, and TypeScript types via z.infer<>

What Failed

Approaches tried and abandoned, with reasons:

[2026-02-07] tRPC added too much boilerplate for our API surface (3 endpoints).
Switched to plain route handlers with Zod validation. Revisit if API grows past 15 endpoints.

Recurring Bugs

Errors that show up repeatedly — prevent them proactively:

[2026-02-08] Forgetting "use server" directive causes: "Error: Functions cannot be
passed directly to Client Components unless you explicitly expose it by marking it
with 'use server'." Always add to files in /app/actions/.

Maintenance

Deduplication

If a new learning overlaps with an existing one, UPDATE the existing entry rather than adding a duplicate. Add the new date.

Retirement

Remove entries about tech that's been removed from the project. Dead patterns create noise.

Size Management

If CLAUDE.md exceeds ~500 lines:

  1. Split into topic files: .claude/docs/auth-patterns.md, .claude/docs/api-conventions.md
  2. Reference them from CLAUDE.md: "See .claude/docs/auth-patterns.md for auth conventions"
  3. Keep CLAUDE.md as the index with the most critical patterns inline

Contradiction Resolution

If a new learning contradicts an old one, update the old entry:

[2026-02-07] ~~Use REST for all endpoints~~ [2026-02-15] Use REST for CRUD,
WebSockets for real-time features (chat, notifications). See /lib/ws/ for setup.

What Makes Good Compound Learnings

GoodBad
References specific files/functionsVague generalities
Includes error messages"Had an error"
Says what TO DOSays what happened
Includes WHYJust states facts
Has context for when it appliesUniversal claims

Ralph Loop — Iterate Until Green

The Ralph Loop is a persistent retry pattern for AI coding agents. Instead of writing code and hoping it works, the agent implements → tests → fixes → retests in a loop until everything passes.

The Pattern

implement → test → [FAIL?] → read error → fix → test again → [PASS?] → lint → [FAIL?] → fix → lint again → [PASS?] → typecheck → [FAIL?] → fix → typecheck again → [PASS?] → DONE

Rules

  1. Max 5 retries per unique error. If the same test fails 5 times with the same root cause, stop and escalate.

  2. Max 3 retries before escalating. If stuck on the same error after 3 attempts, message the team lead with:

    • The error message
    • What you've tried
    • Your hypothesis about why it's failing
  3. Run checks in order: tests → lint → typecheck. Don't skip ahead.

  4. Each retry should be different. Don't repeat the same fix. If approach A failed, try approach B. If both fail, try a fundamentally different strategy.

  5. Read the error message carefully. Most failures contain the answer. Parse stack traces, find the actual line, understand the assertion.

Verification Commands

Read these from CLAUDE.md "Build Commands" section. Common patterns:

StackTestsLintTypecheck
Next.js/Reactnpm test or npx vitestnpm run lintnpx tsc --noEmit
Pythonpytestruff check .mypy .
Node.jsnpm testnpx eslint .npx tsc --noEmit
Gogo test ./...golangci-lint run(built into compiler)

When to Break the Loop

Stop looping and escalate when:

  • Same error persists after 3 different fix attempts
  • The fix requires changes outside your assigned task scope
  • You need a dependency or config change that affects other teammates
  • The test itself appears to be wrong (explain why to the team lead)

Anti-Patterns

  • Don't suppress errors to make tests pass. Fix the root cause.
  • Don't delete failing tests. Fix the code or fix the test, but don't remove coverage.
  • Don't retry without changing anything. Each attempt must try something different.
  • Don't fix unrelated tests. If a pre-existing test fails, note it and move on — it's not your task.

Commands 6

Build — Execute Plan with Agent Team + Ralph Loops

You are the team lead. Execute a plan by spawning an Agent Team where every teammate iterates until their work passes all checks.

Before Starting

  1. Look for a plan in .claude/plans/. If none exists, tell the user to run /ct:plan first.
  2. Read the plan thoroughly.
  3. Read CLAUDE.md — especially Build Commands, conventions, and learned patterns.
  4. Switch to delegate mode (Shift+Tab). You coordinate. You do NOT write code.

Step 1: Create the Team

Teammate({ operation: "spawnTeam", team_name: "{feature-name}" })

Step 2: Create Tasks from the Plan

For each task in the plan:

TaskCreate({
  subject: "{task name from plan}",
  description: "{full description including files to touch, tests to write, and acceptance criteria}",
  activeForm: "{what in-progress looks like}",
  blockedBy: ["{task IDs this depends on}"]  // only if plan specifies dependencies
})

Step 3: Spawn Teammates

Scale the team to the plan:

  • 2-3 tasks: 1 builder + 1 qa
  • 4-6 tasks: 2 builders + 1 qa
  • 7+ tasks: 3 builders + 1 qa

Builder Prompt (include in every builder spawn):

You are a builder on team "{feature-name}".

WORKFLOW — RALPH LOOP:
1. Run TaskList() — find a pending, unblocked task with no owner
2. Claim it: TaskUpdate({ taskId, owner: "$CLAUDE_CODE_AGENT_NAME" })
3. Start it: TaskUpdate({ taskId, status: "in_progress" })
4. Read CLAUDE.md for conventions and patterns before coding
5. Implement the solution
6. Write tests for your changes
7. Run the test command from CLAUDE.md "Build Commands"
   - If tests FAIL: read the error, fix the code, run tests again
   - MAX 5 retries per unique error
   - If stuck after 3 retries on the SAME error: message team lead with the error and what you've tried
8. Run the lint command from CLAUDE.md "Build Commands"
   - Fix any issues, rerun until clean
9. Run the type check command from CLAUDE.md "Build Commands"
   - Fix any issues, rerun until clean
10. ALL GREEN → commit with a descriptive message
11. TaskUpdate({ taskId, status: "completed" })
12. Go back to step 1 for the next task
13. No tasks left → message team lead: "All my tasks are done"

RULES:
- NEVER mark a task complete if any check fails
- NEVER skip writing tests
- If you need to modify a file another teammate is working on, message them FIRST
- Each commit should be atomic — one task, one commit

QA Prompt (include in QA spawn):

You are QA on team "{feature-name}".

WORKFLOW:
1. Monitor TaskList() — wait for builder tasks to reach "completed"
2. For each completed task:
   a. Review the code changes (git diff for that task's commit)
   b. Run the FULL test suite — not just the new tests
   c. Check edge cases: null inputs, empty states, boundary values, error paths
   d. Verify acceptance criteria from the task description
   e. If issues found:
      - Create a new task: TaskCreate({ subject: "Fix: {issue}", description: "..." })
      - Message the relevant builder about the issue
   f. If clean: message team lead confirming this task passed QA
3. When ALL tasks pass QA:
   a. Run full integration/e2e tests if they exist
   b. Check for regressions
   c. Message team lead with final QA report

RULES:
- Be adversarial — try to break things
- Test error handling paths, not just happy paths
- Check for hardcoded values, missing validation, security issues
- Run the actual test/lint/typecheck commands from CLAUDE.md

Step 4: Monitor and Coordinate

While teammates work:

  • Check your inbox regularly for messages
  • If a teammate is blocked: suggest approaches (not code)
  • If two teammates need the same file: coordinate who goes first
  • If a teammate reports being stuck (3 retries same error): analyze and provide guidance
  • Track overall progress via TaskList()

Step 5: Wrap Up

When all tasks are complete AND QA confirms:

  1. Request shutdown for each teammate:
    Teammate({ operation: "requestShutdown", target_agent_id: "{name}" })
    
  2. Wait for acknowledgments
  3. Clean up: Teammate({ operation: "cleanup" })
  4. Run the full test suite yourself one final time
  5. Report results to user
  6. Suggest: "Run /ct:compound to capture learnings from this build"

Emergency: Cost Control

If a teammate loops without progress (same error 5+ consecutive times):

  1. Message them to stop
  2. Request shutdown
  3. Report the blocker to the user — may need human intervention
  4. This prevents runaway token costs

Compound — Extract and Document Learnings

Analyze what just happened and update CLAUDE.md so future sessions benefit.

Process

1. Gather Context

# Recent commits
git log --oneline -20

# Check for plans
ls .claude/plans/*.md 2>/dev/null

# Current CLAUDE.md
cat CLAUDE.md

2. Identify Learnings

Look for:

Patterns that worked:

  • Code patterns that solved problems well
  • Libraries or approaches that proved effective
  • Task decomposition that enabled good parallelism

Patterns that failed:

  • Approaches tried and abandoned
  • Libraries that didn't work as expected
  • Wrong assumptions

Recurring bugs:

  • Errors that appeared repeatedly during Ralph loops
  • Common mistakes teammates made
  • Things the linter/type checker caught repeatedly

Performance insights:

  • Optimizations that helped
  • Caching strategies
  • Query patterns to prefer or avoid

3. Update CLAUDE.md

Append entries to the "Learned Patterns" sections. Each entry MUST be:

  • Dated: [YYYY-MM-DD]
  • Specific: reference actual files, functions, or error messages
  • Actionable: future Claude should know what to DO differently

✅ Good: [2026-02-07] Stripe webhook routes need raw body — add export const config = { api: { bodyParser: false } } in Next.js App Router, or the signature check fails with "No signatures found matching the expected signature".

❌ Bad: [2026-02-07] Be careful with webhooks

4. Update Build Commands (if needed)

If the test/lint/typecheck commands changed or new ones were discovered, update the "Build Commands" section.

5. Update Architecture (if needed)

If the project structure changed (new directories, new major modules), update accordingly.

6. Archive Plan

# Move completed plan to archive
mv .claude/plans/{feature}.md .claude/plans/archive/{feature}.md 2>/dev/null

7. Report

Tell the user:

  • How many new learnings were added
  • Any patterns that contradict previous ones (update, don't duplicate)
  • Suggestions for what to build or fix next

Maintenance Rules

  • Don't duplicate entries — update if the learning evolved
  • Remove entries for tech that was removed
  • Keep entries concise — this file is read every session
  • If CLAUDE.md exceeds ~500 lines, suggest splitting into topic files that CLAUDE.md references

Plan — Research and Create Implementation Plan

You are the planning agent. Create a thorough plan BEFORE any code is written.

Input

The user provides a feature description via: /ct:plan $ARGUMENTS

Process

1. Understand the Request

Re-read $ARGUMENTS. If ambiguous, ask clarifying questions. Do NOT proceed until the goal is clear.

2. Research the Codebase

  • Read CLAUDE.md for project context, conventions, and learned patterns
  • Explore the directory structure and find related code
  • Check git log for recent changes in relevant areas
  • Identify utilities, patterns, and abstractions to reuse

3. Research Best Practices

  • Search the web for best practices related to this feature and stack
  • Look for common pitfalls
  • Check for established libraries that solve part of the problem

4. Write the Plan

Create .claude/plans/{feature-name}.md:

# Plan: {Feature Name}

## Goal
One sentence describing success.

## Context
What exists today. Reference specific files and modules.

## Approach
High-level strategy. Why this over alternatives.

## Tasks
Broken into independent, parallelizable units where possible.

### Task 1: {name}
- **What**: Clear deliverable
- **Files**: Specific paths to create/modify
- **Tests**: What tests to write
- **Blocked by**: Other task numbers (if any)
- **Done when**: Acceptance criteria

### Task 2: {name}
...

## Risks
What could go wrong and how to handle it.

## Patterns to Apply
Reference entries from CLAUDE.md "Learned Patterns" that are relevant.

5. Present for Approval

Show the plan. Wait for user to approve, modify, or reject.

Rules

  • Do NOT write code during planning
  • Do NOT spawn teammates during planning
  • Each task should be 10-30 minutes of work for one teammate
  • Prefer many small tasks over few large ones (better parallelism)
  • Tasks that can run in parallel should have no dependencies between them
  • Tasks that MUST be sequential should use "Blocked by" to declare order

Quick — Fast Build for Small Tasks

For tasks that don't warrant the full /ct:plan → /ct:build cycle.

When to Use

  • Bug fixes with clear repro steps
  • Small refactors (rename, extract, move)
  • Config or copy changes
  • Adding a single test

When NOT to Use (use /ct:plan + /ct:build)

  • New features touching multiple files
  • New API endpoints
  • Database schema changes
  • Anything needing multi-person review

Process

User provides the task via: /ct:quick $ARGUMENTS

  1. Read CLAUDE.md for conventions
  2. Spawn a small team:
Teammate({ operation: "spawnTeam", team_name: "quick-fix" })

Builder Prompt:

Implement this change: {$ARGUMENTS}

Read CLAUDE.md for conventions. Then:
1. Make the change
2. Write/update tests
3. Run tests — if fail: fix and retry (max 3 attempts)
4. Run lint + type check — fix if needed
5. Commit with descriptive message
6. Message team-lead when done

Verifier Prompt:

Wait for the builder to finish. Then:
1. Review the git diff
2. Run the FULL test suite (not just new tests)
3. Check for regressions
4. If issues: message builder with specifics
5. If clean: message team-lead confirming
  1. Once both confirm: shut down, clean up, report to user.

No need for /ct:compound unless something surprising was learned.

Review — Multi-Perspective Code Review Team

Spawn 3 specialized reviewers to examine code changes from different angles.

What to Review

If the user provides a branch/PR/commit range with $ARGUMENTS, use that. Otherwise, review changes from the most recent build: git diff main...HEAD

Step 1: Gather the Diff

git diff main...HEAD --stat
git log --oneline main..HEAD

Read the diff before spawning reviewers.

Step 2: Spawn Review Team

Teammate({ operation: "spawnTeam", team_name: "review-{feature}" })

Create 3 tasks, one per reviewer lens. Then spawn 3 teammates:

Security Reviewer Prompt:

Review the git diff (main...HEAD) for security issues.

CHECK: SQL injection, XSS, CSRF, hardcoded secrets/keys, missing input validation, insecure auth patterns, sensitive data in logs/errors, missing rate limiting, unsafe deserialization, path traversal.

Message team-lead with findings: file, line, severity (critical/high/medium/low), suggested fix.
If nothing found, confirm the changes look secure.

Architecture Reviewer Prompt:

Review the git diff (main...HEAD) for architectural quality. Read CLAUDE.md first for project conventions.

CHECK: Pattern consistency, separation of concerns, SOLID violations, DRY without over-abstraction, dependency direction, testability, performance at scale, error handling consistency.

Message team-lead with findings: file, concern, suggestion.
Also note things done WELL — we document good patterns too.

Correctness Reviewer Prompt:

Review the git diff (main...HEAD) for correctness. Also run the test suite.

CHECK: Test quality (not coverage theater), edge cases (null/empty/boundary), helpful error messages, type consistency across API boundaries, race conditions, resource cleanup (connections closed, listeners removed), acceptance criteria met.

Message team-lead with findings.

Step 3: Synthesize

Collect all findings. Present unified review:

## Code Review Summary

### Critical (must fix before merge)
- ...

### Improvements (should fix)
- ...

### Suggestions (nice to have)
- ...

### Good Patterns (add to CLAUDE.md via /ct:compound)
- ...

Step 4: Clean Up

Shut down all reviewers. Clean up the team.

If critical or "should fix" issues exist, suggest creating a fix plan: "Run /ct:plan Fix review findings to address these issues."

Setup — Install Compound Teams Workflow

You are the setup assistant. Install the compound-teams workflow (Plan → Build → Review → Compound) into this project safely.

Step 1: Audit Current State

Before changing anything, check what exists:

echo "=== CLAUDE.md ==="
ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"

echo "=== Settings ==="
cat .claude/settings.json 2>/dev/null || echo "No settings.json"

echo "=== Existing commands ==="
ls .claude/commands/ 2>/dev/null || echo "No commands directory"

echo "=== Existing agents ==="
ls .claude/agents/ 2>/dev/null || echo "No agents directory"

echo "=== Git status ==="
git status --short 2>/dev/null | head -5 || echo "Not a git repo"

Report findings to the user before proceeding.

Step 2: Enable Agent Teams

Check .claude/settings.json:

  • If it doesn't exist: create it with { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
  • If it exists but lacks the flag: add the flag, preserving all other settings
  • If it already has the flag: skip, tell user it's already enabled

Show the user the change before writing.

Step 3: Detect Project Stack

echo "=== Package manager ==="
ls package.json pnpm-lock.yaml yarn.lock bun.lock 2>/dev/null

echo "=== Framework ==="
cat package.json 2>/dev/null | grep -E '"(next|react|vue|svelte|astro|express|fastify|hono)"' | head -5
cat pyproject.toml 2>/dev/null | head -20
cat go.mod 2>/dev/null | head -5

echo "=== Test runner ==="
ls jest.config* vitest.config* playwright.config* cypress.config* pytest.ini 2>/dev/null
cat package.json 2>/dev/null | grep -E '"test"' | head -1

echo "=== Linter ==="
ls .eslintrc* eslint.config* biome.json .ruff.toml ruff.toml 2>/dev/null

echo "=== Type checker ==="
ls tsconfig.json mypy.ini 2>/dev/null

echo "=== CI ==="
ls .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | head -3

Report: "I detected [framework], [test runner], [linter], [type checker]. The Ralph Loop will use these for verification."

Step 4: Augment CLAUDE.md

NEVER overwrite existing CLAUDE.md. Check if compound-teams sections already exist.

If the file doesn't exist, create a minimal one. If it exists, append only the missing sections to the end:


---

## Compound Teams Workflow

This project uses: `/ct:plan` → `/ct:build` → `/ct:review` → `/ct:compound`

### Ralph Loop (All Teammates Follow This)
1. Implement the solution
2. Write or update tests
3. Run tests — if fail: read error, fix, retry (max 5 attempts per error)
4. Run linter/type checker — if fail: fix and retry
5. Only mark task complete when ALL checks pass
6. If stuck after 3 retries on same error, message team lead with blocker

### Build Commands
- Tests: `[DETECTED_TEST_COMMAND]`
- Lint: `[DETECTED_LINT_COMMAND]`
- Type check: `[DETECTED_TYPECHECK_COMMAND]`
- Dev server: `[DETECTED_DEV_COMMAND]`

### Learned Patterns
<!-- Grows via /ct:compound — each entry is dated and actionable -->

#### What Works

#### What Failed

#### Recurring Bugs

Replace the [DETECTED_*] placeholders with the actual commands from Step 3.

Show the user exactly what will be appended. Get confirmation before writing.

Step 5: Create Plans Directory

mkdir -p .claude/plans/archive

Step 6: Summary

✅ Compound Teams installed!

Commands available (via plugin):
  /ct:setup     — You just ran this
  /ct:plan      — Research and plan a feature
  /ct:build     — Execute with Agent Team + Ralph loops
  /ct:review    — Multi-perspective code review
  /ct:quick     — Fast builds for small tasks
  /ct:compound  — Extract learnings into CLAUDE.md

Agent Teams: enabled
Plans directory: .claude/plans/
Stack detected: [framework] + [test runner] + [linter]

Start with: /ct:plan <your next feature>

Safety Rules

  • NEVER overwrite existing files — only append or create new
  • ALWAYS show changes to user before writing
  • PRESERVE all existing CLAUDE.md content
  • If a conflict is found, present both versions and let user choose

Sponsors

Details

Marketplace
tbdng/compound-teams-plugin
Source
plugins/compound-teams
Author
tbdng
Category
Community