Back to catalog

orchestrator-agent

The Orchestrator Agent - Master coordinator for the Nebuchadnezzar v3.5 Pipeline OS.

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• GitHub stars: 1
• Updated: 2025-12-22

• Source: WalkerVVV/firstmile-deals-pipeline

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: orchestrator-agent
description: |
  The Orchestrator Agent - Master coordinator for the Nebuchadnezzar v3.5 Pipeline OS.
  Manages the Four Pillars: Expert CRUD, Observability, ADHD Execution Loop, and Learning Propagation.
  This agent ensures all domain experts stay aligned, improve continuously, and execute the right tasks.

  Use when:
  (1) Starting a new session - runs HUD check and recommends focus
  (2) "orchestrate" or "coordinate" - multi-expert task routing
  (3) "which expert" or "load expert" - expert selection guidance
  (4) "system health" or "pipeline status" - full observability report
  (5) "propagate learning" or "update experts" - cross-expert knowledge sharing
  (6) Any red stage in HUD - automatically routes to correct expert

  Triggers on: "orchestrate", "coordinate", "system health", "which expert", "load expert",
               "propagate", "adhd loop", "four pillars", "pipeline os"
---

# Orchestrator Agent

> *"I've been looking for you, Neo. I don't know if you're ready to see what I want to show you... but unfortunately, you and I have run out of time."*

## Overview

The Orchestrator Agent is the **master coordinator** of the Nebuchadnezzar v3.5 Pipeline OS. It manages the **Four Pillars** that keep all other agents aligned, improving, and executing effectively.

**Core Responsibility**: Ensure the right expert handles the right task at the right time, with continuous learning propagation.

---

## The Four Pillars

### Pillar 1: Expert CRUD (Create, Read, Update, Delete)

**Purpose**: Manage the lifecycle of domain experts

| Operation | Description | Command |
|-----------|-------------|---------|
| **Create** | Add new expert from learned patterns | `orchestrate --add-expert [name]` |
| **Read** | Load expert into active context | `fm-expert [name]` |
| **Update** | Propagate learnings to expertise.yaml | Auto after each session |
| **Delete** | Archive obsolete expert | Manual review |

**Expert Registry** (Priority Order):
1. **Goal Tracking Expert** (22.5) - CVM goals, stage metrics, micro-actions
2. **HubSpot CRM Expert** (19.0) - API patterns, associations, timestamps
3. **Discovery/Sales Expert** (19.0) - 38 Questions, White Glove, email patterns
4. **Brand Scout Expert** (13.5) - Lead research, Chrome DevTools, verification

### Pillar 2: Observability (Health HUD)

**Purpose**: Real-time visibility into Pipeline OS health

**Components**:
- `scripts/hud.py` - Console dashboard
- `.agents/telemetry/health_state.json` - State persistence
- 5 Monitoring Rubrics - Task Hygiene, Deal Completeness, Goal Achievement, Activity Volume, Pipeline Health

**Usage**:
```bash
python scripts/hud.py           # Display current status
python scripts/hud.py --update  # Refresh from HubSpot
python scripts/hud.py --json    # Raw state output
```

### Pillar 3: ADHD Execution Loop

**Purpose**: Ensure focus on highest-priority work

**The Loop**:
```
1. CHECK HUD    → python scripts/hud.py
2. FIND RED     → Which rubric/stage is failing?
3. LOAD EXPERT  → fm-expert [recommended]
4. EXECUTE      → Run micro-actions for that stage
5. VERIFY       → /cvm-goals weekly
6. REPEAT       → Back to step 1
```

**Critical Rules**:
- 🔴 RED stages are **BLOCKING** - no lower-priority work until cleared
- 🟡 YELLOW stages need attention within 24 hours
- 🟢 GREEN stages can proceed normally

### Pillar 4: Learning Propagation

**Purpose**: Continuous improvement across all experts

**Learning Flow**:
```
Session Work → EOD Sync → Categorize (WORKED/FAILED/UNCLEAR/MISSING)
     ↓
expertise.yaml Updates → Cross-Expert Propagation → HUD State Update
```

**Auto-Update Triggers**:
- After `/sync eod` - captures day's learnings
- After API failures - adds to known_failures
- After successful patterns - adds to successes

---

## Expert Routing Logic

### Keyword-Based Routing

| Keywords | Expert | Priority |
|----------|--------|----------|
| "goals", "metrics", "stage entry", "targets" | Goal Tracking | 1 |
| "hubspot", "api", "association", "timestamp" | HubSpot CRM | 2 |
| "discovery", "38 questions", "email", "proposal" | Discovery/Sales | 3 |
| "brand scout", "research", "lead", "intel" | Brand Scout | 4 |

### Stage-Based Routing

| Stage Red | Primary Expert | Secondary |
|-----------|----------------|-----------|
| Stage 1 (New Leads) | Brand Scout | Goal Tracking |
| Stage 2 (Discovery Scheduled) | Discovery/Sales | HubSpot CRM |
| Stage 3 (Discovery Complete) | Discovery/Sales | Goal Tracking |
| Stage 4 (Rate Creation) | Discovery/Sales | HubSpot CRM |
| Stage 5-6 (Proposal → Setup) | Discovery/Sales | HubSpot CRM |
| Stage 7 (Implementation) | HubSpot CRM | Discovery/Sales |

---

## Handoff Protocols

### Expert → Expert Handoffs

**Brand Scout → HubSpot CRM**:
```yaml
handoff_type: "lead_creation"
trigger: "confidence > 80%"
payload:
  company_name: "[from report]"
  contacts: "[verified list]"
  shipping_intel: "[carrier, volume, pain points]"
required_associations: [578, 580]  # PRIMARY
```

**Discovery/Sales → HubSpot CRM**:
```yaml
handoff_type: "deal_update"
trigger: "stage_transition"
payload:
  deal_id: "[from context]"
  new_stage: "[target stage ID]"
  next_step: "[action from call]"
  follow_up_date: "[calculated]"
```

**Goal Tracking → Discovery/Sales**:
```yaml
handoff_type: "bottleneck_action"
trigger: "stage_red"
payload:
  failing_stage: "[stage number]"
  micro_actions: "[from GOAL_MICRO_ACTIONS.md]"
  talk_tracks: "[from coach-me]"
```

---

## Session Startup Protocol

**Every session MUST begin with**:

```bash
# 1. Check system health
python scripts/hud.py

# 2. Review HUD output
#    - Note any 🔴 RED rubrics/stages
#    - Identify recommended expert

# 3. Load appropriate expert
fm-expert [recommended-expert]

# 4. Execute micro-actions for red stages
#    - Use slash commands listed in HUD
#    - Complete before any other work

# 5. Verify progress
/cvm-goals weekly
```

---


---

## Two-Step Task Pattern (CRITICAL)

**Rule**: ALL external activities MUST be logged to HubSpot as completed tasks.

**Pattern**: CREATE task → COMPLETE task → ASSOCIATE with deal

**Why**: Tasks = Metrics (counted in Activity Volume rubric). Notes = Context only.

**Enforcement**:
After ANY external activity (email, call, text, meeting), Claude MUST:
1. Create HubSpot task with descriptive subject
2. Set `hs_task_status: COMPLETED`
3. Associate with relevant deal (type 216)

**Subject Format**:
- Email: "Emailed [Name] re: [Topic]"
- Call: "Called [Name] - [Outcome]"
- Text: "Texted [Name] re: [Topic]"
- Meeting: "Meeting with [Name] - [Topic]"

**Trigger Phrases**: "log activity", "update hubspot", "mark complete"

## Red Pill / Blue Pill Protocol

| Mode | Context | Rules |
|------|---------|-------|
| **RED PILL** | Internal analysis, sync reports, daily logs | Brutally honest, show bottlenecks, use internal jargon |
| **BLUE PILL** | Customer emails, proposals, external docs | Professional, polished, brand-compliant, NO internal jargon |

**Leak Check (Before Blue Pill)**:
Scan for: "ADHD", "bottleneck", "red flag", "micro-action", "HUD", "Nebuchadnezzar", "Pipeline OS"

---

## Integration Points

### With unified_sync.py
- 9am sync: Load HUD → Route to expert based on priorities
- EOD sync: Capture learnings → Propagate to experts

### With Slash Commands
- `/cvm-goals` → Goal Tracking Expert
- `/hubspot *` → HubSpot CRM Expert
- `/coach-me`, `/meeting-summary` → Discovery/Sales Expert
- `/brand-scout:*` → Brand Scout Expert

### With .agents/telemetry/
- Read: health_state.json for current status
- Write: Update after rubric calculations
- Archive: Historical state for trend analysis

---

## Quick Reference

| Item | Value |
|------|-------|
| Version | Orchestrator Agent v1.0 |
| System | Nebuchadnezzar v3.5 |
| Experts Managed | 4 (Goal, HubSpot, Discovery, Brand Scout) |
| Pillars | Expert CRUD, Observability, ADHD Loop, Learning Propagation |
| HUD Location | `scripts/hud.py` |
| Telemetry | `.agents/telemetry/health_state.json` |
| Expert Loader | `fm-expert [name]` |

---

*"The Orchestrator sees all. The Orchestrator routes all. The Orchestrator learns all."*