
compound-teams
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-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add tbdng/compound-teams-plugin.
Contents
Discovered from sourceSkills 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:
- Split into topic files:
.claude/docs/auth-patterns.md,.claude/docs/api-conventions.md - Reference them from CLAUDE.md: "See
.claude/docs/auth-patterns.mdfor auth conventions" - 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
| Good | Bad |
|---|---|
| References specific files/functions | Vague generalities |
| Includes error messages | "Had an error" |
| Says what TO DO | Says what happened |
| Includes WHY | Just states facts |
| Has context for when it applies | Universal 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
-
Max 5 retries per unique error. If the same test fails 5 times with the same root cause, stop and escalate.
-
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
-
Run checks in order: tests → lint → typecheck. Don't skip ahead.
-
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.
-
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:
| Stack | Tests | Lint | Typecheck |
|---|---|---|---|
| Next.js/React | npm test or npx vitest | npm run lint | npx tsc --noEmit |
| Python | pytest | ruff check . | mypy . |
| Node.js | npm test | npx eslint . | npx tsc --noEmit |
| Go | go 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
- Look for a plan in
.claude/plans/. If none exists, tell the user to run/ct:planfirst. - Read the plan thoroughly.
- Read CLAUDE.md — especially Build Commands, conventions, and learned patterns.
- 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:
- Request shutdown for each teammate:
Teammate({ operation: "requestShutdown", target_agent_id: "{name}" }) - Wait for acknowledgments
- Clean up:
Teammate({ operation: "cleanup" }) - Run the full test suite yourself one final time
- Report results to user
- Suggest: "Run
/ct:compoundto capture learnings from this build"
Emergency: Cost Control
If a teammate loops without progress (same error 5+ consecutive times):
- Message them to stop
- Request shutdown
- Report the blocker to the user — may need human intervention
- 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
- Read CLAUDE.md for conventions
- 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
- 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