orchestrator-agent

# 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:**

1. **Log workflow start**
```
   POST audit: action="workflow_start", resource="email_content_pipeline"
```

2. **Execute Email Agent**
```
   - Call: npm run email-agent
   - Wait for completion
   - Capture: processed count, errors, audit logs
```

3. **Evaluate Results**
```
   IF processed > 0:
     Continue to step 4
   ELSE:
     Notify user "No new emails to process"
     Exit workflow
```

4. **Update Contact Scores**
```
   FOR each processed email:
     - Get updated contact AI score
     - Filter: aiScore >= 70 (warm leads)
     - Store in memory for content generation
```

5. **Execute Content Agent**
```
   - Call: npm run content-agent
   - Wait for completion
   - Capture: generated count, content types
```

6. **Validate Output**
```
   Query generatedContent:
   - Count drafts created
   - Verify all have status="draft"
   - Check aiModel="sonnet"
```

7. **Generate Report**
```
   Output summary with:
   - Emails processed: X
   - Contacts updated: X
   - Content generated: X
   - High-priority leads identified: X
   - Recommended next actions
```

8. **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:**

1. **Fetch pending approvals**
```
   GET generatedContent:
   - status="draft"
   - Sort by contact.aiScore DESC
   - Limit: 5
```

2. **Validate contacts**
```
   FOR each content:
     - Get contact details
     - Verify status="prospect" (ready to receive)
     - Check lastInteraction < 30 days (recent)
```

3. **Approve content**
```
   FOR each draft:
     POST mutation: content.approve(userId=system)
```

4. **Update contact status**
```
   FOR each contact:
     - Mark nextFollowUp = NOW + 7 days
     - Update lastInteraction = NOW
```

5. **Log audit trail**
```
   FOR each action:
     POST audit event with full details
```

6. **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:**

1. **Check data integrity**
```
   Verify:
   - All organizations active
   - All users have valid roles
   - All contacts have valid status
   - All emails properly linked
```

2. **Audit recent activities**
```
   Query auditLogs (last 24h):
   - Total actions: X
   - Errors: X
   - Error rate: X%
   - Failed agents: [list]
```

3. **Database health**
```
   Check:
   - All indexes working
   - No orphaned records
   - Data consistency
   - Storage usage
```

4. **Agent performance**
```
   FOR each agent:
     - Last run: [timestamp]
     - Success rate: X%
     - Avg processing time: Xms
     - Last error: [if any]
```

5. **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