# Compound Engineering Integration for Symph Agency

## Overview

This document describes how to integrate the **Compound Engineering** workflow (from EveryInc) with Symph Agency's build pipeline. The key addition is the **Ralph Wiggum** autonomous loop that enables fully autonomous builds.

## Prerequisites

### Installed Plugins (Done ✅)

```bash
# Already installed on this machine:
claude plugin marketplace add https://github.com/anthropics/claude-code
claude plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin
claude plugin install ralph-wiggum
claude plugin install compound-engineering
```

### Verify Installation

```bash
claude plugin list
# Should show:
# - compound-engineering@every-marketplace (v2.30.0) ✔ enabled
# - ralph-wiggum@claude-code-plugins (v1.0.0) ✔ enabled
```

---

## The Compound Engineering Workflow

### Philosophy

> "Each unit of engineering work should make subsequent units easier—not harder."

- **80% planning/review, 20% execution**
- Plan files capture decisions before coding
- Parallel reviewers catch issues early
- Learnings are documented for future use

### Core Commands

| Command | Purpose |
|---------|---------|
| `/workflows:plan` | Create detailed implementation plan |
| `/workflows:work` | Execute plan with task tracking |
| `/workflows:review` | Multi-agent code review |
| `/workflows:compound` | Document learnings |
| `/lfg` | Full autonomous workflow (combines all) |
| `/slfg` | Swarm mode (parallel execution) |

---

## Integration with Symph Agency Build Phase

### Current Build Flow (Before)

```
1. Human clicks "Start Build" in UI
2. Job created: [EXECUTE_BUILD_PLAN]
3. ARIA spawns Claude Code subagent
4. Claude Code builds app
5. QA Agent runs tests
6. Fix → QA → Fix loop until pass
7. Deploy
```

### New Build Flow (After — With Compound Engineering)

```
1. Human clicks "Start Build" in UI
2. Job created: [EXECUTE_BUILD_PLAN]
3. ARIA spawns Claude Code with compound-engineering plugin
4. Claude Code runs /lfg with the task:
   a. /ralph-loop starts autonomous mode
   b. /workflows:plan generates detailed plan from PRD
   c. /deepen-plan enhances with research
   d. /workflows:work executes (with git worktree)
   e. /workflows:review runs parallel reviewers
   f. /resolve_todo_parallel fixes all findings
   g. /test-browser validates in browser
   h. Outputs <promise>DONE</promise> when complete
5. Deploy
```

### Key Differences

| Aspect | Before | After |
|--------|--------|-------|
| Planning | Brief + PRD only | Full plan file with phases |
| Execution | Single-pass build | Iterative with task tracking |
| Review | QA Agent (single) | Parallel specialist reviewers |
| Autonomy | Needs monitoring | Fully autonomous with ralph-loop |
| Learning | Manual | Auto-captured via /workflows:compound |

---

## Implementation Guide

### Step 1: Update Build Job Handler

In `HEARTBEAT.md`, update the `[EXECUTE_BUILD_PLAN]` handler:

```markdown
For `[EXECUTE_BUILD_PLAN]` jobs:

1. Read the approved build plan from `build/build-plan.md`
2. Read discovery artifacts (brief.md, prd.md, user-stories.md)
3. Read design artifacts (brand-guidelines.md, screens)

4. **Spawn Claude Code with /lfg:**
   ```bash
   cd /home/aria/projects/{slug}
   claude --dangerously-skip-permissions -p "/lfg Build the app according to build-plan.md. 
   Use agency-app-starter patterns. Deploy to {slug}.dev.apps.symph.co when complete.
   Output <promise>DONE</promise> when deployed and tested." \
   --max-iterations 50
   ```

5. Monitor for completion (check for DONE promise)
6. Update build-details.yaml with results
7. Delete job file
```

### Step 2: Create Symph-Specific CLAUDE.md

Each project should have a `CLAUDE.md` that tells Claude Code about our conventions:

```markdown
# CLAUDE.md - {Product Name}

## Project Context
- **Product:** {name}
- **Brief:** See `discovery/brief.md`
- **PRD:** See `discovery/prd.md`
- **Design:** See `design/brand-guidelines.md`

## Tech Stack
- Next.js 15 + Tailwind v4 + shadcn/ui
- Firebase (Firestore + Auth)
- Namespace isolation: dev_*, staging_*, prod_*

## Conventions
- Use `agency-app-starter` patterns
- Firestore rules must use namespace prefixes
- Enable Firebase Auth via enable_email_auth.py script
- All lists/dashboards query real Firestore (no mock data)

## Build Workflow
1. Run `/lfg` with the build plan
2. Use `/workflows:review` before any PR
3. Test all routes with `/test-browser`
4. Document learnings with `/workflows:compound`

## Deployment
- DEV: Caddy reverse proxy ({slug}.dev.apps.symph.co)
- PROD: Firebase App Hosting (via GitHub release)
```

### Step 3: Adapt Plan File Location

Compound Engineering uses `docs/plans/` but we use `build/build-plan.md`.

Option A: Symlink
```bash
mkdir -p docs/plans
ln -s ../../build/build-plan.md docs/plans/current-plan.md
```

Option B: Update `/workflows:work` to read from our location (pass path as argument)

### Step 4: Integrate Review Findings

Compound Engineering creates todo files in `todos/`. Map these to our system:

```bash
# After /workflows:review completes, findings are in:
ls todos/*.md

# Convert to our format or just use their format
# Their todos have: status, priority, issue_id, description
```

---

## Usage Examples

### Example 1: Full Autonomous Build

```bash
# From project directory
claude --dangerously-skip-permissions

# Then in Claude Code:
/lfg "Build the AI Teacher Assistant app. Follow build-plan.md. 
Deploy to ai-teacher-assistant.dev.apps.symph.co.
Output <promise>DONE</promise> when complete."
```

### Example 2: Just the Planning Phase

```bash
/workflows:plan "Add user authentication with Google OAuth"
# Creates: docs/plans/2026-02-06-feat-user-authentication-plan.md

/deepen-plan
# Enhances plan with parallel research
```

### Example 3: Code Review Before PR

```bash
/workflows:review
# Runs 12+ parallel reviewers
# Creates todos for findings
# Then:
/resolve_todo_parallel
# Fixes all findings in parallel
```

### Example 4: Swarm Mode for Large Features

```bash
/slfg "Implement complete user management system"
# Same as /lfg but steps 5+6 run as parallel agents
```

---

## Configuration

### Environment Variables

```bash
# For Context7 MCP (library docs)
export CONTEXT7_API_KEY="ctx7sk-..."

# For Gemini image generation (optional)
export GEMINI_API_KEY="..."
```

### MCP Servers (Auto-Configured by Plugin)

The compound-engineering plugin auto-registers:
- `context7` — Framework documentation lookup

---

## Learnings Capture

After each build, compound-engineering captures learnings:

```bash
/workflows:compound
# Creates: docs/solutions/YYYY-MM-DD-topic.md
```

Map to our system:
```bash
# Copy learnings to our location
cp docs/solutions/*.md agency/Learnings/
```

---

## Troubleshooting

### Ralph Loop Won't Exit

```bash
/cancel-ralph
```

### Plugin Not Found

```bash
claude plugin list
# If missing:
claude plugin install compound-engineering
claude plugin install ralph-wiggum
```

### Commands Conflict with Built-ins

Compound Engineering uses `workflows:` prefix to avoid conflicts:
- `/workflows:plan` (not `/plan`)
- `/workflows:review` (not `/review`)

---

## Next Steps

1. **Test on a real build** — Run `/lfg` on the next product in pipeline
2. **Capture learnings** — Document what works and what doesn't
3. **Tune prompts** — Adjust completion criteria based on results
4. **Create Symph-specific agents** — Add our own reviewer agents if needed

---

## References

- [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin)
- [Ralph Wiggum Technique](https://ghuntley.com/ralph/)
- [Every's Blog: How We Code with Agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents)
