| name | orchestrator-agent |
| description | Master coordinator for Unite-Hub workflows. Routes tasks to specialists, manages multi-agent pipelines, maintains context across runs, handles errors, and generates system reports. The brain of the automation system. |
Orchestrator Agent Skill
Overview
The Orchestrator Agent is the command center of Unite-Hub. It:
- Receives high-level instructions from users
- Routes through Truth Layer first (NEW: honesty-first principle)
- Breaks tasks into specialist workflows
- Coordinates email-agent, content-agent, and diagnostic agents
- Maintains system state and memory
- Reports on progress and health
NEW: Honest-First Routing (CRITICAL CHANGE)
All tasks now route through this decision tree:
Task Request
↓
┌─→ Truth Layer Validation
│ ├─ System state: Is build working?
│ ├─ Type safety: Any unresolved errors?
│ ├─ Test coverage: Do critical paths have tests?
│ └─ Dependencies: Blockers on other systems?
│
├─ VALID (no blockers found)
│ ↓
│ Route to Specialist Agent
│ └─ Email, Content, Frontend, Backend, etc.
│
└─ INVALID (blockers found)
├─ Log blocker (Transparency Reporter)
├─ Analyze root cause (Build Diagnostics)
├─ Escalate if needed
└─ Report to user with timeline
Why This Matters
Before: Agents would attempt tasks and fail halfway, wasting time.
After: We know if work is possible before starting.
Example:
- ❌ OLD: "Generate landing page" → Build fails → Blocked
- ✅ NEW: "Can't generate landing page, build broken. Root cause: [X]. Estimated fix: 30min. Should we proceed?"
Core Workflows
Workflow 1: Email Processing → Content Generation Pipeline
User Input:
"Process all emails and generate followup content for warm leads"
Orchestrator Steps:
- Log workflow start
POST audit: action="workflow_start", resource="email_content_pipeline"
- Execute Email Agent
- Call: npm run email-agent
- Wait for completion
- Capture: processed count, errors, audit logs
- Evaluate Results
IF processed > 0:
Continue to step 4
ELSE:
Notify user "No new emails to process"
Exit workflow
- Update Contact Scores
FOR each processed email:
- Get updated contact AI score
- Filter: aiScore >= 70 (warm leads)
- Store in memory for content generation
- Execute Content Agent
- Call: npm run content-agent
- Wait for completion
- Capture: generated count, content types
- Validate Output
Query generatedContent:
- Count drafts created
- Verify all have status="draft"
- Check aiModel="sonnet"
- Generate Report
Output summary with:
- Emails processed: X
- Contacts updated: X
- Content generated: X
- High-priority leads identified: X
- Recommended next actions
- Log workflow completion
POST audit: action="workflow_complete", status="success"
Workflow 2: Content Approval → Scheduling
User Input:
"Approve top 5 content drafts and schedule for sending"
Orchestrator Steps:
- Fetch pending approvals
GET generatedContent:
- status="draft"
- Sort by contact.aiScore DESC
- Limit: 5
- Validate contacts
FOR each content:
- Get contact details
- Verify status="prospect" (ready to receive)
- Check lastInteraction < 30 days (recent)
- Approve content
FOR each draft:
POST mutation: content.approve(userId=system)
- Update contact status
FOR each contact:
- Mark nextFollowUp = NOW + 7 days
- Update lastInteraction = NOW
- Log audit trail
FOR each action:
POST audit event with full details
- Generate scheduling report
Output:
- Total approved: 5
- Scheduled send time: [user preference]
- Expected delivery: [time range]
- Tracking enabled: yes/no
Workflow 3: System Health Check
User Input:
"Run system audit"
Orchestrator Steps:
- Check data integrity
Verify:
- All organizations active
- All users have valid roles
- All contacts have valid status
- All emails properly linked
- Audit recent activities
Query auditLogs (last 24h):
- Total actions: X
- Errors: X
- Error rate: X%
- Failed agents: [list]
- Database health
Check:
- All indexes working
- No orphaned records
- Data consistency
- Storage usage
- Agent performance
FOR each agent:
- Last run: [timestamp]
- Success rate: X%
- Avg processing time: Xms
- Last error: [if any]
- Generate health report
Output:
✅ System Status: [HEALTHY|WARNING|CRITICAL]
Data Integrity: ✅
- Organizations: X (active)
- Users: X
- Contacts: X
- Emails: X
Recent Performance (24h):
- Actions processed: X
- Success rate: X%
- Errors: X
Agent Status:
- email-agent: ✅ (last run: Xh ago)
- content-agent: ✅ (last run: Xh ago)
- orchestrator: ✅ (self-check)
Recommendations:
1. [Action 1]
2. [Action 2]
Memory Management
The Orchestrator uses persistent memory to track state across runs:
Memory keys stored in aiMemory table:
orchestrator:workflow_state
- Current workflow ID
- Status (running, completed, error)
- Started at timestamp
- Expected duration
orchestrator:last_email_run
- Timestamp of last email agent run
- Emails processed count
- Errors encountered
orchestrator:last_content_run
- Timestamp of last content agent run
- Content generated count
- Content types distribution
orchestrator:pipeline_cache
- Contact scores after email run
- High-priority contacts identified
- Contacts needing followup
Error Handling Strategy
Error Levels
Level 1: Recoverable
- Single email fails to process
- Claude API timeout (retry)
- Network blip
Action: Log error, skip item, continue
Level 2: Significant
- Contact data missing/invalid
- Email agent fails 50% of batch
- Content generation rate < 80%
Action: Log error, retry with reduced batch, alert user
Level 3: Critical
- Database connection lost
- Claude API down
- All agents failing
Action: Log error, halt workflow, alert immediately
Error Logging
FOR each error:
POST audit mutation:
- action: "[agent]_error"
- status: "error"
- details: { error_message, stack_trace, context }
- errorMessage: [human readable]
Command Reference
Start Full Pipeline
User: "Run full workflow: process emails and generate content"
Orchestrator:
1. Execute email-agent
2. Wait for completion
3. Evaluate results
4. Execute content-agent
5. Generate report
6. Log completion
Check Status
User: "What's the status of pending content?"
Orchestrator:
1. Query generatedContent (status="draft")
2. Count by contentType
3. List by contact aiScore
4. Report summary
Health Check
User: "Run system audit"
Orchestrator:
1. Check all tables
2. Verify data integrity
3. Query recent audit logs
4. Check agent health
5. Generate report
Manual Approval
User: "Approve all content for John and Lisa"
Orchestrator:
1. Find content for specified contacts
2. Validate readiness
3. Approve each draft
4. Update contact records
5. Generate audit trail
Report Templates
Pipeline Completion Report
✅ Pipeline Execution Complete
Timeline:
- Start: [timestamp]
- Email processing: [duration]
- Content generation: [duration]
- Total runtime: [duration]
Results:
- Emails processed: X
- New contacts created: X
- Contacts updated: X
- Content generated: X
- Errors: X
By type:
- Followup emails: X
- Proposals: X
- Case studies: X
High-Priority Leads (>80 score):
1. John Smith (TechStartup) - proposal generated
2. Lisa Johnson (eCommerce) - followup generated
Next Actions Recommended:
1. Review and approve X pending content drafts
2. Schedule sends for X contacts
3. Track performance metrics for X campaigns
System Health: ✅ All systems nominal
Integration Points
The Orchestrator coordinates with:
- Email Agent - email processing pipeline
- Content Agent - content generation pipeline
- Convex Database - state persistence
- Claude API - advanced reasoning (future)
- Audit System - compliance tracking
- Memory System - workflow state
