Nightly Automation

Nightly automation that makes your AI agent learn and ship while you sleep.

Overview

Compound Engineering is a methodology where AI agents continuously improve by:

1. Learning - Extracting insights from each work session
2. Persisting - Storing learnings in steering documents
3. Compounding - Using accumulated knowledge to improve future work

This creates a self-improving loop where every unit of work makes future work easier.

Nightly Automation

Two jobs run every night in sequence:

The order matters: review runs first so fresh learnings inform the implementation job.

Compound Review (10:30 PM)

The agent:

1. Reviews all Claude Code sessions from the past 24 hours
2. Identifies sessions where learnings weren't explicitly captured
3. Extracts patterns, gotchas, architecture decisions, and debugging approaches
4. Updates relevant steering documents:
   • QUALITY.md - Code quality patterns
   • TDD.md - Testing insights
   • TECHNICAL.md - Architecture decisions
   • SECURITY.md - Security learnings
5. Commits and pushes to dev branch

Auto-Compound (11:00 PM)

The agent:

1. Pulls latest (including fresh learnings from compound review)
2. Queries FlowState for highest priority "To Do" task
3. Creates feature branch: compound/YYYYMMDD-task-slug
4. Implements the task following TDD and project standards
5. Updates task status in FlowState
6. Creates a draft PR for review
7. Switches back to dev branch (leaves repo in clean state for next run)

Setup

# Install and activate
./scripts/compound/setup.sh

# Verify agents are loaded
launchctl list | grep epicflowstate

Manual Testing

# Interactive test menu
./scripts/compound/test-compound.sh

# Trigger compound review immediately
launchctl start com.epicflowstate.daily-compound-review

# Trigger auto-compound immediately
launchctl start com.epicflowstate.auto-compound

Logs

# Compound review logs
tail -f logs/compound-review.log

# Auto-compound logs
tail -f logs/auto-compound.log

Task Prioritization

Auto-compound selects tasks using this priority:

1. Has milestoneId - Part of planned work (higher priority)
2. Oldest createdAt - FIFO within same priority level

Tasks without milestones are still processed but after milestone-linked tasks.

What Gets Learned

The compound review extracts and persists:

Caffeinate

A caffeinate agent keeps the Mac awake during the automation window:

• Starts: 5:00 PM
• Duration: 9 hours (until 2:00 AM)
• Ensures launchd jobs execute even if the Mac would normally sleep

Configuration

Changing Schedule

Edit plist files in scripts/compound/launchd/:

<key>StartCalendarInterval</key>
<dict>
    <key>Hour</key>
    <integer>22</integer>  <!-- 10 PM -->
    <key>Minute</key>
    <integer>30</integer>
</dict>

After editing, reload:

launchctl unload ~/Library/LaunchAgents/com.epicflowstate.*.plist
launchctl load ~/Library/LaunchAgents/com.epicflowstate.*.plist

Disabling Temporarily

# Unload agents (preserves files)
launchctl unload ~/Library/LaunchAgents/com.epicflowstate.daily-compound-review.plist
launchctl unload ~/Library/LaunchAgents/com.epicflowstate.auto-compound.plist

Uninstalling Completely

launchctl unload ~/Library/LaunchAgents/com.epicflowstate.*.plist
rm ~/Library/LaunchAgents/com.epicflowstate.*.plist

Best Practices

During Development Sessions

1. Be explicit about learnings - When you discover something important, mention it
2. Note gotchas - Edge cases and unexpected behaviors are valuable
3. Document decisions - Architecture choices and their rationale
4. Capture debugging steps - What worked when solving issues

For Compound Review

The nightly review is a safety net. It catches learnings from sessions where you:

• Forgot to explicitly compound at the end
• Were focused on shipping and didn't pause to reflect
• Discovered patterns through trial and error

For Auto-Compound

1. Keep tasks well-defined - Clear acceptance criteria help autonomous implementation
2. Link to milestones - Ensures important work gets prioritized
3. Review PRs daily - Check what shipped overnight, provide feedback
4. Update task descriptions - If a task was partially completed, update it

Troubleshooting

Jobs Not Running

1. Check Mac wasn't asleep during scheduled time
2. Verify agents are loaded: launchctl list | grep epicflowstate
3. Check logs for errors

Claude CLI Not Found

The plist files include the nvm node path. Update if your installation differs:

which claude  # Find your path
# Update PATH in scripts/compound/launchd/*.plist

FlowState MCP Not Accessible

Ensure Docker containers are running when jobs execute:

./scripts/local-env.sh status

The Compound Effect

Over time, this system creates:

1. Institutional Memory - Steering documents become a knowledge base
2. Consistent Quality - Learnings prevent repeated mistakes
3. Autonomous Progress - Work continues while you sleep
4. Reduced Context Switching - Wake up to PRs, not task lists

The agent gets smarter every day because it reads its own updated instructions before each implementation run.

References

• Ryan Carson's Compound Engineering - Original concept
• Compound Engineering Plugin - Claude Code skill
• Scripts: scripts/compound/