Skip to content
Back to search

compound-product

A self-improving product system that reads reports, identifies priorities, and autonomously implements fixes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/snarktank--compound-product/badge.svg)](/listings/snarktank--compound-product)

HTML

<a href="/listings/snarktank--compound-product"><img src="/api/listings/snarktank--compound-product/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [Amp CLI](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - [agent-browser](https://github.com/vercel-labs/agent-browser) for browser-based testing (`npm install -g agent-browser`) - `jq` installed (`brew install jq` on macOS) - `gh` CLI installed and authenticated (`brew install gh`) - One of these LLM providers configured: - **Anthropic:** `export ANTHROPIC_API_KEY=sk-ant-...` - **OpenRouter:** `export OPENROUTER_API_KEY=sk-or-...` - **AI Gateway:** `export AI_GATEWAY_URL=https://... AI_GATEWAY_API_KEY=...`

Installation

Compound Product installs into your existing project repository. It adds scripts and configuration that work alongside your codebase.

# Clone compound-product somewhere temporary
git clone https://github.com/snarktank/compound-product.git
cd compound-product

# Install into your project
./install.sh /path/to/your/project

Or tell your AI agent (from within your project):

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 (you provide these)

Configuration

Copy and customize the config:

cp config.example.json config.json

Edit `config.json`:

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

Running

# Dry run - see what it would do
./scripts/compound/auto-compound.sh --dry-run

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

# Just run the loop (if you already have prd.json)
./scripts/compound/loop.sh 10

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 379 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Compound Product
  2. A self-improving product system that reads daily reports, identifies the #1 actionable priority, and autonomously implements it.
  3. **The concept:** Your product generates reports about its performance. An AI agent analyzes those reports, picks the most impactful fix, creates a plan, and implements it—all while you sleep. You wake up to a PR ready for review.
  4. Built on [Kieran Klaassen's Compound Engineering](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents) methodology, [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/), and [Ryan Carson's implementation](https://x.com/ryancarson/status/2008548371712135632).
  5. ## How It Works
  6. ```mermaid
  7. flowchart TD
  8. subgraph "Phase 0: Your System"
  9. GEN[Generate Daily Report<br/>your code, cron, etc.]
  10. GEN --> R[📊 reports/*.md<br/>metrics, errors, feedback]
  11. end
  12. subgraph "Phase 1: Analysis"
  13. A[analyze-report.sh<br/>LLM API]
  14. R --> A
  15. A --> J[analysis.json<br/>priority + criteria]
  16. end
  17. subgraph "Phase 2: Planning"
  18. B[Create Branch<br/>compound/feature-name]
  19. J --> B
  20. B --> PRD[AI Agent<br/>Load prd skill]
  21. PRD --> MD[tasks/prd-feature.md]
  22. MD --> TASKS[AI Agent<br/>Load tasks skill]
  23. TASKS --> JSON[prd.json<br/>executable tasks]
  24. end
  25. subgraph "Phase 3: Execution Loop"
  26. LOOP[loop.sh<br/>max N iterations]
  27. JSON --> LOOP
  28. LOOP --> PICK[Pick next task<br/>where passes: false]
  29. PICK --> IMPL[AI Agent<br/>Implement task]
  30. IMPL --> CHECK{Quality<br/>Checks?}
  31. CHECK -->|Pass| COMMIT[Git Commit]
  32. CHECK -->|Fail| FIX[Fix & Retry]
  33. FIX --> CHECK
  34. COMMIT --> UPDATE[Update prd.json<br/>passes: true]
  35. UPDATE --> DONE{All tasks<br/>done?}
  36. DONE -->|No| PICK
  37. DONE -->|Yes| EXIT[Exit loop]
  38. end
  39. subgraph Output
  40. EXIT --> PUSH[Git Push]
  41. PUSH --> PR[🎉 Pull Request<br/>Ready for review]
  42. end
  43. click A "https://github.com/snarktank/compound-product/blob/main/scripts/analyze-report.sh" "View analyze-report.sh"
  44. click LOOP "https://github.com/snarktank/compound-product/blob/main/scripts/loop.sh" "View loop.sh"
  45. click PRD "https://github.com/snarktank/compound-product/blob/main/skills/prd/SKILL.md" "View PRD skill"
  46. click TASKS "https://github.com/snarktank/compound-product/blob/main/skills/tasks/SKILL.md" "View Tasks skill"
  47. ```
  48. ## Quick Start
  49. ### Prerequisites
  50. - [Amp CLI](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
  51. - [agent-browser](https://github.com/vercel-labs/agent-browser) for browser-based testing (`npm install -g agent-browser`)
  52. - `jq` installed (`brew install jq` on macOS)
  53. - `gh` CLI installed and authenticated (`brew install gh`)
  54. - One of these LLM providers configured:
  55. - **Anthropic:** `export ANTHROPIC_API_KEY=sk-ant-...`
  56. - **OpenRouter:** `export OPENROUTER_API_KEY=sk-or-...`
  57. - **AI Gateway:** `export AI_GATEWAY_URL=https://... AI_GATEWAY_API_KEY=...`
  58. ### Installation
  59. Compound Product installs into your existing project repository. It adds scripts and configuration that work alongside your codebase.
  60. ```bash
  61. # Clone compound-product somewhere temporary
  62. git clone https://github.com/snarktank/compound-product.git
  63. cd compound-product
  64. # Install into your project
  65. ./install.sh /path/to/your/project
  66. ```
  67. Or tell your AI agent (from within your project):
  68. ```
  69. Install compound-product from https://github.com/snarktank/compound-product into this repo
  70. ```
  71. This creates:
  72. - `scripts/compound/` - The automation scripts
  73. - `compound.config.json` - Configuration for your project
  74. - `reports/` - Directory for your daily reports (you provide these)
  75. ### Configuration
  76. Copy and customize the config:
  77. ```bash
  78. cp config.example.json config.json
  79. ```
  80. Edit `config.json`:
  81. ```json
  82. {
  83. "tool": "amp",
  84. "reportsDir": "./reports",
  85. "outputDir": "./compound",
  86. "qualityChecks": ["npm run typecheck", "npm test"],
  87. "maxIterations": 25,
  88. "branchPrefix": "compound/"
  89. }
  90. ```
  91. ### Running
  92. ```bash
  93. # Dry run - see what it would do
  94. ./scripts/compound/auto-compound.sh --dry-run
  95. # Full run
  96. ./scripts/compound/auto-compound.sh
  97. # Just run the loop (if you already have prd.json)
  98. ./scripts/compound/loop.sh 10
  99. ```
  100. ## Report Format
  101. Your report can be any markdown file. The AI will analyze it and pick the #1 actionable item.
  102. Example report structure:
  103. ```markdown
  104. # Daily Report - 2024-01-15
  105. ## Key Metrics
  106. - Signups: 45 (down 20% from yesterday)
  107. - Errors: 12 TypeErrors in checkout flow
  108. - User feedback: "Can't find the save button"
  109. ## Issues
  110. 1. Checkout flow has JavaScript errors
  111. 2. Save button is below the fold on mobile
  112. 3. Email validation is too strict
  113. ## Recommendations
  114. - Fix checkout JavaScript errors (blocking revenue)
  115. - Move save button above fold
  116. - Relax email validation
  117. ```
  118. ## The Loop
  119. Each iteration of the loop:
  120. 1. **Reads** `prd.json` to find the next task where `passes: false`
  121. 2. **Implements** the task
  122. 3. **Runs quality checks** (configurable in `config.json`)
  123. 4. **Commits** if checks pass
  124. 5. **Updates** `prd.json` to mark task as `passes: true`
  125. 6. **Appends** learnings to `progress.txt`
  126. 7. **Repeats** until all tasks complete or max iterations reached
  127. ### Memory Between Iterations
  128. Each iteration runs with fresh context. Memory persists via:
  129. - **Git history** - Previous commits show what was done
  130. - **progress.txt** - Learnings and patterns discovered
  131. - **prd.json** - Which tasks are complete
  132. - **AGENTS.md** - Long-term codebase knowledge (updated by agents)
  133. ## Skills
  134. Two skills are included for PRD creation and task generation:
  135. ### PRD Skill
  136. Creates a Product Requirements Document from a feature description.
  137. ```
  138. Load the prd skill. Create a PRD for [your feature]
  139. ```
  140. ### Tasks Skill
  141. Converts a PRD markdown file to `prd.json` with **granular, machine-verifiable tasks**.
  142. Key features:
  143. - Generates 8-15 small tasks (not 3-5 large ones)
  144. - Each acceptance criterion is boolean pass/fail
  145. - Browser tests use [agent-browser](https://github.com/vercel-labs/agent-browser) commands
  146. - Investigation and implementation are separate tasks
  147. ```
  148. Load the tasks skill. Convert tasks/prd-feature.md to prd.json
  149. ```
  150. ## Customization
  151. ### Custom Analysis Script
  152. By default, `analyze-report.sh` uses the Anthropic API directly. To use your own:
  153. ```json
  154. {
  155. "analyzeCommand": "npx tsx ./my-custom-analyze.ts"
  156. }
  157. ```
  158. Your script must output JSON to stdout:
  159. ```json
  160. {
  161. "priority_item": "Fix checkout errors",
  162. "description": "...",
  163. "rationale": "...",
  164. "acceptance_criteria": ["...", "..."],
  165. "branch_name": "compound/fix-checkout-errors"
  166. }
  167. ```
  168. ### Quality Checks
  169. Configure your project's quality checks:
  170. ```json
  171. {
  172. "qualityChecks": [
  173. "npm run typecheck",
  174. "npm run lint",
  175. "npm test"
  176. ]
  177. }
  178. ```
  179. ### Branch Prefix
  180. All branches are created with a prefix:
  181. ```json
  182. {
  183. "branchPrefix": "compound/"
  184. }
  185. ```
  186. ## ⚠️ Security Considerations
  187. **This tool runs AI agents with elevated permissions.** Understand the risks before using:
  188. ### What the agents can do
  189. - **Read and modify any file** in your repository
  190. - **Execute shell commands** (build, test, git operations)
  191. - **Make network requests** (API calls, git push)
  192. - **Create branches and PRs** in your repository
  193. ### Safeguards in place
  194. 1. **PRs, not direct merges** - All changes go through pull requests for human review
  195. 2. **Quality checks** - Configurable checks run before commits
  196. 3. **Max iterations** - The loop stops after N iterations to prevent runaway execution
  197. 4. **Dry run mode** - Test the analysis phase without making changes
  198. ### Recommendations
  199. - **Review PRs carefully** before merging
  200. - **Run in a separate environment** (VM, container) if concerned about file access
  201. - **Use API keys with limited scope** where possible
  202. - **Don't use on production branches** - always target a feature branch
  203. - **Monitor the first few runs** to understand behavior
  204. ### The `--dangerously-allow-all` flag
  205. The scripts use `--dangerously-allow-all` (Amp) and `--dangerously-skip-permissions` (Claude Code) to allow autonomous operation. This means the agent bypasses normal confirmation prompts. This is intentional for automation but means you're trusting the agent to make good decisions.
  206. ## Philosophy
  207. **Compound Product** is based on the idea that each improvement should make future improvements easier:
  208. 1. **Agents update AGENTS.md** - Discovered patterns are documented for future iterations
  209. 2. **Progress is logged** - Each task records what was learned
  210. 3. **Small tasks compound** - Many small, correct changes beat large, risky ones
  211. 4. **Human review remains** - The loop creates PRs, not direct merges
  212. ## Scheduling (macOS launchd)
  213. To run Compound Product automatically (e.g., every night), use macOS launchd:
  214. ```bash
  215. # Copy the example plist
  216. cp examples/com.compound.plist.example ~/Library/LaunchAgents/com.compound.myproject.plist
  217. # Edit it with your project path and username
  218. nano ~/Library/LaunchAgents/com.compound.myproject.plist
  219. # Load it
  220. launchctl load ~/Library/LaunchAgents/com.compound.myproject.plist
  221. # Check status (last column is exit code, 0 = success)
  222. launchctl list | grep compound
  223. ```
  224. **Important: PATH configuration**
  225. launchd runs with a minimal PATH. You must include the directories where your tools are installed:
  226. ```bash
  227. # Find where your CLI is installed
  228. which amp # e.g., /Users/you/.npm-global/bin/amp
  229. which claude # e.g., /opt/homebrew/bin/claude
  230. ```
  231. Update the `PATH` in your plist to include these directories. The example plist includes common locations.
  232. **Troubleshooting launchd:**
  233. ```bash
  234. # Check logs
  235. tail -f /path/to/your/project/logs/compound.log
  236. # Unload and reload
  237. launchctl unload ~/Library/LaunchAgents/com.compound.myproject.plist
  238. launchctl load ~/Library/LaunchAgents/com.compound.myproject.plist
  239. # Test manually (should produce same result as launchd)
  240. /bin/bash -c 'cd /path/to/project && ./scripts/compound/auto-compound.sh --dry-run'
  241. ```
  242. ## Troubleshooting
  243. ### Loop exits early
  244. Check `progress.txt` for errors. Common issues:
  245. - Quality checks failing (fix the code or adjust checks)
  246. - Task too large (split into smaller tasks)
  247. - Context overflow (task description needs to be more focused)
  248. ### Analysis fails
  249. Ensure one of these LLM providers is configured:
  250. ```bash
  251. # Option 1: Anthropic API
  252. export ANTHROPIC_API_KEY=sk-ant-...
  253. # Option 2: OpenRouter
  254. export OPENROUTER_API_KEY=sk-or-...
  255. # Option 3: AI Gateway (any OpenAI-compatible endpoint)
  256. export AI_GATEWAY_URL=https://your-gateway.com/v1
  257. export AI_GATEWAY_API_KEY=your-key
  258. export AI_GATEWAY_MODEL=claude-sonnet-4-20250514 # optional
  259. ```
  260. ### Agent can't find tools
  261. For Amp, ensure skills are installed:
  262. ```bash
  263. ls ~/.config/amp/skills/
  264. ```
  265. For Claude Code:
  266. ```bash
  267. ls ~/.claude/skills/
  268. ```
  269. ## Contributing
  270. PRs welcome! Please keep changes focused and include tests where applicable.
  271. ## License
  272. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.