docs: Progress Tracker sidecar specification and beads tasks

[agent-relay]

Progress Tracker Sidecar Agent

Detailed specification for Progress Tracker external sidecar agent that monitors relay workspace servers and provides deep visibility into agent work.

What's Included

1. Comprehensive Specification (docs/PROGRESS_TRACKER_SIDECAR_SPEC.md)

• Architecture: External sidecar agent using Claude/Codex SDK
• Components: 6 core components with detailed design
  • Relay API client (query daemon state)
  • Log tailer (stream agent stdout/stderr)
  • Pattern analyzer (LLM-powered stuck detection)
  • Reminder system (context-aware reminders)
  • Lifecycle manager (start/stop/restart agents)
  • Escalation engine (alert lead with context)

2. Key Features

• Real-time monitoring of multiple relay servers simultaneously
• Deep work visibility via log tailing (not just relay messages)
• Intelligent stuck detection using LLM analysis
• Context-aware reminders using agent's trail/continuity
• Agent lifecycle control (start/stop/restart)
• Smart escalation with full context to lead
• Automatic recovery for error loops and timeouts

3. Implementation Plan (docs/PROGRESS_TRACKER_BEADS_TASKS.md)

• 6 feature tasks organized by implementation phase
• 54 hours total estimated effort
• 2-3 week timeline with 2 developers
• Clear requirements and acceptance criteria per task

Problem Solved

Current relay monitoring gaps:

• ❌ Time-based prompts create noise without insight
• ❌ No visibility beyond relay messages
• ❌ Stuck agents undetected until manual intervention
• ❌ No intelligent recovery mechanisms
• ❌ Continuity context underutilized

Solution Benefits

✅ Event-based monitoring (no time-based prompts)
✅ Deep work visibility (logs + relay messages)
✅ Automatic stuck detection (<2min latency)
✅ Intelligent reminders using context
✅ Auto-recovery for common failure modes
✅ Lead gets real, actionable alerts
✅ Scales to monitor n relay servers

Implementation Phases

1. Core Framework (8h) - Polling loop, config, logging
2. Relay API (6h) - Query daemon, get agent state
3. Log Tailing (12h) - Stream logs, detect patterns
4. Reminders (10h) - Context-aware messages, response tracking
5. Lifecycle (8h) - Start/stop/restart, auto-recovery
6. Alerting (10h) - Slack/webhook, history, escalation

Next Steps

1. Review specification and design
2. Discuss implementation approach
3. Create individual PRs for each phase
4. Deploy Phase 1 (core framework) first
5. Iterate based on feedback

Discussion Points

• Should sidecar be Claude or Codex (language model)?
• Relay daemon API endpoints - any gaps vs spec?
• Alert delivery (Slack, webhook, both)?
• Configuration format and defaults?
• Multi-server monitoring priorities?

---

RFC (Request for Comment) - looking for feedback on architecture and approach before implementation begins.

🤖 Generated with Claude Code

Co-Authored-By: khaliqgant khaliqgant@example.com

[khaliqgant]

Along with this we should remove the continuity scheduled injections as it causes confusion.

[my-senior-dev-pr-review]

🤖 My Senior Dev — Analysis Complete

👤 For @agent-relay[bot]

⚡ 3rd PR this month

View your contributor analytics →

---

📊 4 files reviewed • 3 need attention

⚠️ Needs Attention:

• docs/PROGRESS_TRACKER_BEADS_TASKS.md — Critical documentation providing guidance for task implementation lacks thorough detail on dependencies and clarity in task specifications.

---

🚀 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.