szoloth/compound-product

Compound Product

A self-improving product system that reads daily reports, identifies the #1 actionable priority, and autonomously implements it. You wake up to a PR ready for review.

Based on Kieran Klaassen's Compound Engineering, Geoffrey Huntley's Ralph pattern, and Ryan Carson's implementation.

No API key needed! Uses Claude Code CLI with your Max subscription.

---

When to use this skill

• Structuring raw observations into reports - "Turn these notes into a compound report"
• Running the compound workflow - "Run compound on this report"
• Setting up compound in a new repository
• Daily capture - Dump friction, requests, questions throughout the day

Quick invocations

Structure this into a compound report: [paste messy notes]

Run compound product on reports/daily.md

Turn my daily capture into a compound report

---

The Compound Loop

┌─────────────────────────────────────────────────────────────────────┐
│                        COMPOUND PRODUCT FLOW                         │
└─────────────────────────────────────────────────────────────────────┘

  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │   REPORTS    │────▶│   ANALYZE    │────▶│  CREATE PRD  │
  │  reports/*.md │     │ Pick #1 item │     │ prd skill    │
  └──────────────┘     └──────────────┘     └──────────────┘
                                                   │
                                                   ▼
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │  CREATE PR   │◀────│ EXECUTE LOOP │◀────│ CREATE TASKS │
  │   gh pr      │     │ loop.sh      │     │ tasks skill  │
  └──────────────┘     └──────────────┘     └──────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Per Iteration:  │
                    │ 1. Pick next task│
                    │ 2. Implement     │
                    │ 3. Quality checks│
                    │ 4. Commit        │
                    │ 5. Update prd.json│
                    │ 6. Log progress  │
                    └──────────────────┘

---

Quick start

Install into a project

# Clone compound-product
git clone https://github.com/snarktank/compound-product.git /tmp/compound-product

# Install into your project
/tmp/compound-product/install.sh /path/to/your/project

Or tell the agent:

Install compound-product from https://github.com/snarktank/compound-product into this repo

This creates:

• scripts/compound/ - The automation scripts
• compound.config.json - Configuration for your project
• reports/ - Directory for your daily reports

Configuration

Edit compound.config.json:

{
  "reportsDir": "./reports",
  "outputDir": "./scripts/compound",
  "qualityChecks": ["npm run typecheck", "npm test"],
  "maxIterations": 25,
  "branchPrefix": "compound/",
  "analyzeCommand": ""
}

| Field | Description | |-------|-------------| | reportsDir | Where to find report markdown files | | outputDir | Where prd.json and progress.txt live | | qualityChecks | Commands to run after each task | | maxIterations | Max loop iterations before stopping | | branchPrefix | Prefix for created branches | | analyzeCommand | Custom analysis script (optional) |

---

Running the compound pipeline

Option 1: Interactive mode (same session) ⭐ Recommended

Run directly in your current Claude Code session - no subprocess spawning:

Run compound product on reports/daily-report.md

Or step by step:

1. Analyze reports/daily-report.md and pick the #1 priority
2. Create a PRD for that priority (use prd skill)
3. Convert the PRD to prd.json (use tasks skill)
4. Implement the tasks one by one, running quality checks between each
5. Create a PR when done

Advantages of interactive mode:

• Faster (no subprocess overhead)
• You can intervene/guide at any step
• Full context preserved throughout
• Can ask clarifying questions if needed

Option 2: Automated mode (shell scripts)

For overnight/scheduled runs without supervision:

# Full pipeline
./scripts/compound/auto-compound.sh

# Dry run first
./scripts/compound/auto-compound.sh --dry-run

# Just the loop (if you already have prd.json)
./scripts/compound/loop.sh [max_iterations]

Use automated mode when:

• Running overnight while you sleep
• Scheduling via launchd/cron
• CI/CD pipelines

---

Generating reports

From raw inputs → structured report

Don't have a formal report? Just dump your observations, notes, transcripts, or questions and I'll structure them:

Structure this into a compound report:

- noticed the search is slow when typing fast
- "can we add filtering by date?" - Charles in standup
- checkout page threw an error for Maria
- why does the sidebar collapse on refresh?
- [paste meeting transcript or slack thread]

I'll transform messy inputs into a structured report with:

• Prioritized issues (critical → low)
• User feedback with attribution
• Metrics if available
• Actionable recommendations

Daily capture template

For ongoing capture, use templates/daily-capture.md:

## What I noticed today
Search feels slow when typing fast

## Requests I heard  
"Can we add date filtering?" - Charles

## Questions that came up
Why does sidebar collapse on refresh?

## Raw notes
[paste anything relevant]

Then: "Turn my daily capture into a compound report"

---

Report structuring instructions

When transforming raw inputs into a compound report, I:

1. Categorize inputs

| Input type | Maps to | |------------|---------| | Friction, bugs, slowness | Issues (with severity) | | Stakeholder quotes | User Feedback (with attribution) | | Numbers, counts, timings | Metrics | | Ideas, "what if" | Opportunities | | Questions, confusion | Issues or Open Questions |

2. Prioritize issues

• Critical: Blocking users, losing data, breaking revenue
• High: Significant friction, mentioned by multiple people
• Medium: Annoyances, inefficiencies
• Low: Polish, nice-to-haves

3. Extract actionable items

Each item should be:

• Specific (not "make it faster" but "search results take 3+ seconds")
• Verifiable (can confirm when fixed)
• Scoped (completable in hours, not weeks)
• No database migrations required

4. Generate recommendations

Prioritized list of what to fix, considering:

• User impact
• Frequency mentioned
• Effort to fix
• Dependencies

---

Structured report format

The system analyzes markdown reports to pick the #1 actionable item. Reports should contain:

# Daily Report - 2024-01-15

## Key Metrics
- Signups: 45 (down 20% from yesterday)
- Errors: 12 TypeErrors in checkout flow
- User feedback: "Can't find the save button"

## Issues
1. Checkout flow has JavaScript errors
2. Save button is below the fold on mobile
3. Email validation is too strict

## Recommendations
- Fix checkout JavaScript errors (blocking revenue)
- Move save button above fold
- Relax email validation

Constraints the analyzer applies:

• Must NOT require database migrations
• Must be completable in a few hours
• Must be specific and verifiable
• Prefers fixes over new features
• Prefers high-impact, low-effort items

---

Interactive workflow (in-session)

When you invoke this skill, I'll run the compound loop directly in this session:

Step 1: Analyze report

I read the report and identify the #1 actionable priority:

• Must NOT require database migrations
• Completable in a few hours
• Specific and verifiable
• High-impact, low-effort

Step 2: Create PRD

Using the prd skill, I create a Product Requirements Document:

• Self-clarify (answer 5 key questions from context)
• Generate structured PRD with tasks
• Save to tasks/prd-[feature-name].md

Step 3: Convert to executable tasks

Using the tasks skill, I convert the PRD to prd.json:

• Explode into 8-15 granular tasks
• Each task has machine-verifiable acceptance criteria
• Order by dependencies

Step 4: Execute the loop

For each task where passes: false:

1. Implement the task
2. Run quality checks from config
3. Commit if checks pass
4. Update prd.json to mark passes: true
5. Log learnings to progress.txt
6. Repeat until all tasks complete

Step 5: Create PR

When all tasks pass, I create a pull request with:

• Summary of what was done
• Rationale from report analysis
• Progress log excerpt

---

Using the skills directly

Create a PRD

Load the prd skill. Create a PRD for [feature description]

Convert PRD to executable tasks

Load the tasks skill. Convert tasks/prd-feature.md to prd.json

---

prd.json format

{
  "project": "Project Name",
  "branchName": "compound/feature-name",
  "description": "One-line description",
  "tasks": [
    {
      "id": "T-001",
      "title": "Specific action verb + target",
      "description": "What to do and why",
      "acceptanceCriteria": [
        "Run `npm run typecheck` - exits with code 0",
        "File `src/auth.ts` contains `redirectUrl: '/dashboard'`",
        "agent-browser: open /signup - page loads without errors"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Machine-verifiable acceptance criteria

Every criterion must be a boolean check an agent can definitively pass or fail:

| Type | Pattern | Example | |------|---------|---------| | Command | Run [cmd] - exits with code 0 | Run npm test - exits with code 0 | | File check | File [path] contains [string] | File middleware.ts contains clerkMiddleware | | Browser nav | agent-browser: open [url] - [result] | agent-browser: open /login - renders SignIn | | Browser action | agent-browser: click [element] - [result] | agent-browser: click Submit - redirects | | Console check | agent-browser: console shows no errors | |

Bad (vague):

• "Works correctly"
• "Review the configuration"
• "Verify it looks good"

---

The execution loop

Each iteration:

1. Reads prd.json to find next task where passes: false
2. Implements the task
3. Runs quality checks from config
4. Commits if checks pass
5. Updates prd.json to mark task as passes: true
6. Appends learnings to progress.txt
7. Repeats until all tasks complete or max iterations reached

Memory between iterations

Each iteration runs with fresh context. Memory persists via:

• Git history - Previous commits show what was done
• progress.txt - Learnings and patterns discovered
• prd.json - Which tasks are complete
• AGENTS.md - Long-term codebase knowledge (updated by agents)

Progress log format

## Codebase Patterns
- Use `sql` template for aggregations
- Always use `IF NOT EXISTS` for migrations
- Export types from actions.ts for UI components
---

## 2024-01-15 10:30 - T-001
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
---

---

Agent instructions (for the loop)

When running in the loop, the agent should:

1. Read config at compound.config.json
2. Read PRD at [outputDir]/prd.json
3. Read progress log at [outputDir]/progress.txt (check Codebase Patterns first)
4. Ensure on correct branch from PRD branchName
5. Pick highest priority task where passes: false
6. Implement that single task
7. Run quality checks from config
8. Update AGENTS.md if patterns discovered
9. Commit with message: feat: [Task ID] - [Task Title]
10. Update PRD to set passes: true
11. Append progress to progress.txt

Stop condition: When ALL tasks have passes: true, respond with:

🎉 COMPLETE 🎉

---

Requirements

Primary: Claude Code CLI (Max subscription)

No API key needed! The compound system uses Claude Code CLI, which works with your Max subscription:

# Verify Claude Code is installed
claude --version

# If not installed
brew install claude-code
# or see: https://docs.anthropic.com/claude-code

Fallback: API keys (for headless/CI environments)

If Claude Code CLI isn't available, the system falls back to API providers:

# Option 1: Anthropic API (direct)
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2: OpenAI API
export OPENAI_API_KEY=sk-...

# Option 3: OpenRouter
export OPENROUTER_API_KEY=sk-or-...

# Option 4: AI Gateway (any OpenAI-compatible endpoint)
export AI_GATEWAY_URL=https://your-gateway.com/v1
export AI_GATEWAY_API_KEY=your-key

---

Scheduling (macOS launchd)

To run automatically (e.g., every night):

# Copy the example plist
cp examples/com.compound.plist.example ~/Library/LaunchAgents/com.compound.myproject.plist

# Edit with your project path
nano ~/Library/LaunchAgents/com.compound.myproject.plist

# Load it
launchctl load ~/Library/LaunchAgents/com.compound.myproject.plist

# Check status
launchctl list | grep compound

Important: launchd runs with minimal PATH. Include directories where your tools are installed in the plist.

---

Security considerations

This tool runs AI agents with elevated permissions:

What agents can do

• Read and modify any file in the repository
• Execute shell commands (build, test, git operations)
• Make network requests (API calls, git push)
• Create branches and PRs

Safeguards

• PRs, not direct merges - all changes go through human review
• Quality checks - configurable checks run before commits
• Max iterations - loop stops after N iterations
• Dry run mode - test without making changes

Recommendations

• Review PRs carefully before merging
• Run in a separate environment if concerned
• Use API keys with limited scope
• Don't use on production branches
• Monitor the first few runs

---

Troubleshooting

Loop exits early

Check progress.txt for errors. Common issues:

• Quality checks failing
• Task too large (split into smaller tasks)
• Context overflow (focus task description)

Analysis fails

Ensure Claude Code CLI is installed and authenticated:

claude --version
claude auth status

If using API fallback, ensure one provider is configured (see Requirements section).

Skills not found

Ensure the prd and tasks skills are installed:

ls ~/.claude/skills/prd/
ls ~/.claude/skills/tasks/

---

File structure after install

your-project/
├── compound.config.json      # Configuration
├── scripts/
│   └── compound/
│       ├── auto-compound.sh  # Full pipeline
│       ├── loop.sh           # Execution loop
│       ├── analyze-report.sh # Report analysis
│       ├── prompt.md         # Amp prompt template
│       └── CLAUDE.md         # Claude prompt template
├── reports/                  # Your reports go here
│   └── *.md
└── tasks/                    # Generated PRDs
    └── prd-*.md

---

Philosophy

Compound Product is based on the idea that each improvement makes future improvements easier:

1. Agents update AGENTS.md - Discovered patterns are documented for future iterations
2. Progress is logged - Each task records what was learned
3. Small tasks compound - Many small, correct changes beat large, risky ones
4. Human review remains - The loop creates PRs, not direct merges

---

Related skills

• prd - Create Product Requirements Documents
• tasks - Convert PRD to executable prd.json
• ralph-loop - Similar autonomous coding pattern
• agentic-review - Multi-agent code review for PRs