Add scheduled jobs feature proposal and specification

[khaliqgant]

Overview

This PR adds a comprehensive proposal and detailed specification for implementing scheduled and trigger-based jobs in agent-relay.

What's Included

Proposal Document ()

• Executive summary and problem statement
• Solution overview with architecture decisions
• Implementation plan with phased approach
• Risk mitigation strategies
• Success metrics

Detailed Specification ()

• Complete architecture design (daemon component)
• Implementation details with code sketches
• Database schema definitions (job_runs, job_configs)
• Completion detection strategy (DONE message + idle fallback)
• Error handling and timeout logic
• Testing strategy
• 7-phase migration path

Key Features

• Scheduled Jobs: Cron-based scheduling for recurring tasks
• Trigger-based Jobs: Event-driven spawning (webhooks, file watches)
• Automatic Lifecycle: Agents auto-release upon completion
• Multi-agent Support: Jobs can spawn multiple agents in parallel
• CLI Auto-detection: Automatically detect first available authenticated CLI
• Job History: Track job runs with status, timing, and logs

Design Decisions

1. Architecture: Daemon component (not separate service) for simpler deployment
2. Completion: DONE message primary, idle detection fallback
3. Storage: Database for job history, separate from agent logs
4. Overlap: Allow by default, configurable later if needed
5. CLI: Auto-detect first available authenticated CLI

Next Steps

This is a proposal/specification PR. Once approved, implementation can proceed following the phased approach outlined in the spec.

Related

• Trajectory: traj_n5zbaot3huoe
• Beads: 18 task beads created for implementation tracking

---

[my-senior-dev-pr-review]

🤖 My Senior Dev — Analysis Complete

👤 For @khaliqgant

📁 Expert in src (662 edits) • ⚡ 155th PR this month

View your contributor analytics →

---

📊 2 files reviewed • 4 need attention

⚠️ Needs Attention:

• docs/proposals/scheduled-jobs-proposal.md — Significant concerns regarding security, maintainability, and lack of testing need careful attention.

---

🚀 Open Interactive Review →

The full interface unlocks features not available in GitHub:

• 💬 AI Chat — Ask questions on any file, get context-aware answers
• 🔍 Smart Hovers — See symbol definitions and usage without leaving the diff
• 📚 Code Archeology — Understand how files evolved over time (/archeology)
• 🎯 Learning Insights — See how this PR compares to similar changes

---

💬 Chat here: @my-senior-dev explain this change — or try @chaos-monkey @security-auditor @optimizer @skeptic @junior-dev

📖 View all 12 personas & slash commands

You can interact with me by mentioning @my-senior-dev in any comment:

In PR comments or on any line of code:

• Ask questions about the code or PR
• Request explanations of specific changes
• Get suggestions for improvements

Slash commands:

• /help — Show all available commands
• /archeology — See the history and evolution of changed files
• /profile — Performance analysis and suggestions
• /expertise — Find who knows this code best
• /personas — List all available AI personas

AI Personas (mention to get their perspective):

Persona	Focus
@chaos-monkey 🐵	Edge cases & failure scenarios
@skeptic 🤨	Challenge assumptions
@optimizer ⚡	Performance & efficiency
@security-auditor 🔒	Security vulnerabilities
@accessibility-advocate ♿	Inclusive design
@junior-dev 🌱	Simple explanations
@tech-debt-collector 💳	Code quality & shortcuts
@ux-champion 🎨	User experience
@devops-engineer 🚀	Deployment & scaling
@documentation-nazi 📚	Documentation gaps
@legacy-whisperer 🏛️	Working with existing code
@test-driven-purist ✅	Testing & TDD

For the best experience, view this PR on myseniordev.com — includes AI chat, file annotations, and interactive reviews.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional flags.