Agent Orchestration Specification — WO System Multi-Agent Architecture

Status: Accepted | Version: 2.0 | Date: 2026-02-13

Pattern: Orchestrator-Workers with Human Checkpoints

---

1. Agent Node Registry

1.1 Node Topology

                            ┌─────────────────────────────┐
                            │   WO Orchestrator Agent      │
                            │   (Central Coordinator)      │
                            └─────────┬───────────────────┘
                   ┌──────────┬───────┼───────┬──────────┬──────────┐
                   ▼          ▼       ▼       ▼          ▼          ▼
            ┌──────────┐ ┌────────┐ ┌────┐ ┌──────┐ ┌────────┐ ┌─────┐
            │Asset Mgmt│ │Schedule│ │Exp │ │Vendor│ │  Doc   │ │ QA  │
            │  Agent   │ │ Agent  │ │Match│ │Coord │ │ Agent  │ │Agent│
            └──────────┘ └────────┘ └────┘ └──────┘ └────────┘ └──┬──┘
                                                                   │
                                                            ┌──────▼──────┐
                                                            │   HUMAN     │
                                                            │ CHECKPOINT  │
                                                            │ (Approvals) │
                                                            └─────────────┘

1.2 Node Specifications

Node	CODITECT Pattern	Model Tier	Max Tokens	Circuit Breaker
WO Orchestrator	Orchestrator-Workers	Sonnet	50,000	N/A (coordinator)
Asset Management	Routing	Haiku	5,000	3 failures / 60s
Scheduling	Parallelization	Sonnet	15,000	3 failures / 120s
Experience Matching	Routing	Haiku	5,000	5 failures / 60s
Vendor Coordinator	Prompt Chaining	Sonnet	15,000	2 failures / 300s
Documentation	Prompt Chaining	Haiku	10,000	3 failures / 60s
QA Review	Evaluator-Optimizer	Opus	30,000	1 failure / 600s

---

2. Message Contract Definitions

2.1 Core Message Types

// ─── Base ────────────────────────────────────────────────
interface AgentMessage {
  id: string;                      // UUID
  correlation_id: string;          // Traces full workflow
  source_agent: AgentId;
  target_agent: AgentId;
  timestamp: string;               // ISO 8601
  tenant_id: string;
  acting_as: string;               // Person ID (human principal)
  
  // CODITECT compliance
  audit_ref?: string;              // Links to AuditTrail entry
  regulatory_flag: boolean;
}

type AgentId = 
  | 'wo_orchestrator'
  | 'asset_mgmt'
  | 'scheduling'
  | 'experience_matching'
  | 'qa_review'
  | 'vendor_coord'
  | 'documentation'
  | 'human_checkpoint';

// ─── WO Orchestrator Messages ────────────────────────────
interface WorkOrderIntent extends AgentMessage {
  type: 'CREATE_MASTER' | 'CREATE_CHILD' | 'TRANSITION' | 'DECOMPOSE';
  payload: {
    master_wo_id?: string;
    template_id?: string;          // Job plan template for decomposition
    item_id: string;
    summary: string;
    detail: string;
    source_type: 'AUTOMATION' | 'EXTERNAL_VENDOR' | 'MANUAL';
    regulatory_flag: boolean;
  };
}

interface WorkOrderStateChange extends AgentMessage {
  type: 'STATE_CHANGE';
  payload: {
    work_order_id: string;
    previous_status: WorkOrderStatus;
    new_status: WorkOrderStatus;
    guards_evaluated: GuardResult[];
    signature_id?: string;
  };
}

interface SubWorkOrderIntent extends AgentMessage {
  type: 'SUB_WO_INTENT';
  payload: {
    master_wo_id: string;
    sequence: number;              // Execution order
    dependencies: string[];        // WO IDs that must complete first
    task_type: 'TICKETING' | 'IT_BUILD' | 'VENDOR_INSTALL' | 'CONFIG_VALIDATE' | 'USER_SETUP' | 'DECOMMISSION';
    item_id: string;
    summary: string;
    detail: string;
    job_plan_template_id?: string;
  };
}

interface GuardViolation extends AgentMessage {
  type: 'GUARD_VIOLATION';
  payload: {
    work_order_id: string;
    target_status: WorkOrderStatus;
    violations: Array<{
      guard: string;
      reason: string;
      part11_ref?: string;
    }>;
  };
}

// ─── Asset Management Messages ───────────────────────────
interface AssetChangeRequest extends AgentMessage {
  type: 'ASSET_CHANGE';
  payload: {
    asset_id: string;
    action: 'REMOVE_FROM_PRODUCTION' | 'DECOMMISSION' | 'UPDATE_STATUS' | 'REGISTER_NEW';
    work_order_id: string;
    target_status: string;
    external_ticket_ref?: string;  // ITSM/CMMS reference
  };
}

interface AssetChangeResult extends AgentMessage {
  type: 'ASSET_CHANGE_RESULT';
  payload: {
    asset_id: string;
    previous_status: string;
    new_status: string;
    work_order_id: string;
    external_ticket_ref?: string;
    success: boolean;
    error?: string;
  };
}

// ─── Scheduling Messages ─────────────────────────────────
interface SchedulingRequest extends AgentMessage {
  type: 'SCHEDULING_REQUEST';
  payload: {
    work_order_id: string;
    job_plan_id: string;
    priority: number;
    dependencies: string[];        // WO IDs — schedule after these
    required_tools: ToolRequirement[];
    required_experience: ExperienceRequirement[];
    preferred_window?: {
      earliest_start: string;
      latest_end: string;
    };
  };
}

interface ScheduleProposal extends AgentMessage {
  type: 'SCHEDULE_PROPOSAL';
  payload: {
    work_order_id: string;
    proposed_start: string;
    proposed_end: string;
    estimated_hours: number;
    assigned_persons: Array<{
      person_id: string;
      role: string;
      fit_score: number;           // 0.0 – 1.0
    }>;
    confidence: number;            // 0.0 – 1.0
    conflicts?: string[];          // Competing WO IDs
  };
}

interface SchedulingFailure extends AgentMessage {
  type: 'SCHEDULING_FAILURE';
  payload: {
    work_order_id: string;
    reason: 'NO_QUALIFIED_PERSONS' | 'NO_TOOLS_AVAILABLE' | 'WINDOW_CONFLICT' | 'DEPENDENCY_DEADLOCK';
    detail: string;
    suggestions?: string[];
  };
}

// ─── Experience Matching Messages ────────────────────────
interface StaffingRequest extends AgentMessage {
  type: 'STAFFING_REQUEST';
  payload: {
    work_order_id: string;
    requirements: Array<{
      experience_id: string;
      min_rating: number;
      headcount: number;
    }>;
    exclude_persons?: string[];    // Avoid conflicts of interest
  };
}

interface StaffingProposal extends AgentMessage {
  type: 'STAFFING_PROPOSAL';
  payload: {
    work_order_id: string;
    candidates: Array<{
      person_id: string;
      person_name: string;
      experience_matches: Array<{
        experience_id: string;
        rating: number;
        required: number;
        surplus: number;
      }>;
      availability: 'AVAILABLE' | 'PARTIAL' | 'UNAVAILABLE';
      composite_score: number;     // Weighted fit score
    }>;
  };
}

interface StaffingGap extends AgentMessage {
  type: 'STAFFING_GAP';
  payload: {
    work_order_id: string;
    unmet_requirements: Array<{
      experience_id: string;
      experience_name: string;
      min_rating: number;
      best_available_rating: number;
      gap: number;
    }>;
    recommendation: 'VENDOR_REQUIRED' | 'TRAINING_NEEDED' | 'LOWER_REQUIREMENT';
  };
}

// ─── QA Review Messages ──────────────────────────────────
interface QAReviewRequest extends AgentMessage {
  type: 'QA_REVIEW_REQUEST';
  payload: {
    work_order_id: string;
    regulatory_flag: boolean;
    required_artifacts: Array<{
      type: 'IQ_REPORT' | 'OQ_REPORT' | 'PQ_REPORT' | 'GOLDEN_IMAGE' | 'WI_UPDATE' | 'RISK_ASSESSMENT';
      document_id?: string;
      status: 'ATTACHED' | 'MISSING' | 'DRAFT';
    }>;
    child_wo_summary: Array<{
      wo_id: string;
      status: WorkOrderStatus;
      has_approval: boolean;
    }>;
  };
}

interface QAPrecheckResult extends AgentMessage {
  type: 'QA_PRECHECK_RESULT';
  payload: {
    work_order_id: string;
    ready_for_review: boolean;
    missing_artifacts: string[];
    warnings: string[];
    // Does NOT contain approval decision — that's human-only
  };
}

// ─── Vendor Coordinator Messages ─────────────────────────
interface VendorTaskRequest extends AgentMessage {
  type: 'VENDOR_TASK_REQUEST';
  payload: {
    work_order_id: string;
    vendor_id: string;
    task_description: string;
    deliverables: Array<{
      type: 'IQ_REPORT' | 'OQ_REPORT' | 'SOFTWARE_INSTALL' | 'CALIBRATION' | 'TRAINING';
      required: boolean;
    }>;
    deadline?: string;
    contract_ref?: string;
  };
}

interface VendorTaskUpdate extends AgentMessage {
  type: 'VENDOR_TASK_UPDATE';
  payload: {
    work_order_id: string;
    vendor_id: string;
    status: 'ACKNOWLEDGED' | 'IN_PROGRESS' | 'DELIVERABLES_SUBMITTED' | 'COMPLETE';
    artifacts_attached: Array<{
      document_id: string;
      type: string;
      filename: string;
    }>;
  };
}

// ─── Documentation Messages ──────────────────────────────
interface DocumentationUpdateRequest extends AgentMessage {
  type: 'DOC_UPDATE_REQUEST';
  payload: {
    work_order_id: string;
    updates: Array<{
      action: 'CREATE_WI' | 'UPDATE_WI' | 'CAPTURE_GOLDEN_IMAGE' | 'LINK_EVIDENCE' | 'VERSION_DOCUMENT';
      document_id?: string;
      description: string;
    }>;
  };
}

interface DocumentationUpdateResult extends AgentMessage {
  type: 'DOC_UPDATE_RESULT';
  payload: {
    work_order_id: string;
    results: Array<{
      action: string;
      document_id: string;
      version: number;
      success: boolean;
      error?: string;
    }>;
  };
}

---

3. Orchestration Flows

3.1 Master WO Decomposition (Win10 → Win11 Upgrade)

Step 1: Client → WO Orchestrator
  Message: WorkOrderIntent { type: CREATE_MASTER }
  Action: Create Master WO (DRAFT), evaluate job plan template
  Output: Master WO created, 6 SubWorkOrderIntents generated

Step 2: WO Orchestrator → Asset Mgmt Agent (Child WO #1: Ticketing)
  Message: AssetChangeRequest { action: REMOVE_FROM_PRODUCTION }
  Dependency: None (first in chain)
  
Step 3: WO Orchestrator → Scheduling Agent (Child WO #2: IT Build)
  Message: SchedulingRequest { dependencies: [WO#1] }
  Sub-call: Scheduling → Experience Matching → StaffingProposal
  
Step 4: WO Orchestrator → Vendor Coordinator (Child WO #3: Vendor Install)
  Message: VendorTaskRequest { deliverables: [IQ_REPORT, OQ_REPORT, SOFTWARE_INSTALL] }
  Dependency: [WO#2]
  
Step 5: WO Orchestrator → Scheduling Agent (Child WO #4: Config/Validate)
  Message: SchedulingRequest { dependencies: [WO#3] }
  Sub-call: Documentation Agent → CAPTURE_GOLDEN_IMAGE, UPDATE_WI
  
Step 6: WO Orchestrator → Scheduling Agent (Child WO #5: User Accounts)
  Message: SchedulingRequest { dependencies: [WO#4] }
  
Step 7: WO Orchestrator → Asset Mgmt Agent (Child WO #6: Decommission)
  Message: AssetChangeRequest { action: DECOMMISSION }
  Dependency: [WO#5]
  
Step 8: WO Orchestrator → QA Review Agent (Master WO Review)
  Trigger: All children in PENDING_REVIEW | APPROVED | COMPLETED
  Message: QAReviewRequest { required_artifacts: [...] }
  
Step 9: QA Review Agent → Human Checkpoint
  Message: QAPrecheckResult → triggers UI notification
  Human: System Owner e-signs approval
  Human: QA e-signs approval (if regulatory)
  
Step 10: WO Orchestrator → COMPLETED
  Trigger: All approvals recorded, all post-approval tasks confirmed

3.2 Token Budget Projection (Master WO Decomposition)

Step	Agent	Model	Est. Tokens	Cost Tier
1	WO Orchestrator	Sonnet	8,000	Standard
2	Asset Mgmt	Haiku	2,000	Economy
3a	Scheduling	Sonnet	5,000	Standard
3b	Experience Matching	Haiku	2,000	Economy
4	Vendor Coordinator	Sonnet	6,000	Standard
5a	Scheduling	Sonnet	5,000	Standard
5b	Documentation	Haiku	4,000	Economy
6	Scheduling	Sonnet	3,000	Standard
7	Asset Mgmt	Haiku	2,000	Economy
8	QA Review	Opus	12,000	Premium
	Total		49,000	Mixed

Cost comparison: Single-model (all Opus) = ~$2.45 vs. Routed = ~$0.98 — 60% reduction.

---

4. CODITECT Agent Graph Definition

// CODITECT WO Agent Graph — LangGraph-compatible definition
import { Graph, StateGraph, END } from '@langchain/langgraph';

const woAgentGraph = new StateGraph({
  channels: {
    work_orders: { value: [] },
    messages: { value: [] },
    current_phase: { value: 'INIT' },
  }
})
  // Nodes
  .addNode('wo_orchestrator', WorkOrderOrchestratorNode)
  .addNode('asset_mgmt', AssetManagementNode)
  .addNode('scheduling', SchedulingNode)
  .addNode('experience_matching', ExperienceMatchingNode)
  .addNode('qa_review', QAReviewNode)
  .addNode('vendor_coord', VendorCoordinatorNode)
  .addNode('documentation', DocumentationNode)
  .addNode('human_checkpoint', HumanCheckpointNode)
  
  // Routing edges from orchestrator
  .addConditionalEdges('wo_orchestrator', routeByMessageType, {
    'ASSET_CHANGE': 'asset_mgmt',
    'SCHEDULING_REQUEST': 'scheduling',
    'STAFFING_REQUEST': 'experience_matching',
    'QA_REVIEW_REQUEST': 'qa_review',
    'VENDOR_TASK_REQUEST': 'vendor_coord',
    'DOC_UPDATE_REQUEST': 'documentation',
    'HUMAN_CHECKPOINT': 'human_checkpoint',
    'COMPLETE': END,
  })
  
  // Return edges to orchestrator
  .addEdge('asset_mgmt', 'wo_orchestrator')
  .addEdge('scheduling', 'wo_orchestrator')
  .addEdge('experience_matching', 'scheduling')  // Staffing feeds scheduling
  .addEdge('qa_review', 'wo_orchestrator')
  .addEdge('vendor_coord', 'wo_orchestrator')
  .addEdge('documentation', 'wo_orchestrator')
  .addEdge('human_checkpoint', 'wo_orchestrator')
  
  // Entry point
  .setEntryPoint('wo_orchestrator');

function routeByMessageType(state: GraphState): string {
  const lastMessage = state.messages[state.messages.length - 1];
  if (!lastMessage) return 'COMPLETE';
  
  const routeMap: Record<string, string> = {
    'ASSET_CHANGE': 'asset_mgmt',
    'SCHEDULING_REQUEST': 'scheduling',
    'STAFFING_REQUEST': 'experience_matching',
    'QA_REVIEW_REQUEST': 'qa_review',
    'VENDOR_TASK_REQUEST': 'vendor_coord',
    'DOC_UPDATE_REQUEST': 'documentation',
    'AWAIT_APPROVAL': 'human_checkpoint',
  };
  
  return routeMap[lastMessage.type] || 'COMPLETE';
}

---

5. Circuit Breaker Configuration

interface CircuitBreakerConfig {
  agent_id: AgentId;
  failure_threshold: number;       // Failures before opening
  recovery_timeout_ms: number;     // Time before half-open probe
  half_open_max_requests: number;  // Probes before closing
  
  // CODITECT-specific
  on_open: 'BLOCK' | 'FALLBACK' | 'ESCALATE';
  fallback_agent?: AgentId;
  escalation_target?: 'human_checkpoint';
}

const CIRCUIT_BREAKER_CONFIGS: Record<AgentId, CircuitBreakerConfig> = {
  asset_mgmt: {
    agent_id: 'asset_mgmt',
    failure_threshold: 3,
    recovery_timeout_ms: 60_000,
    half_open_max_requests: 1,
    on_open: 'ESCALATE',
    escalation_target: 'human_checkpoint',
  },
  scheduling: {
    agent_id: 'scheduling',
    failure_threshold: 3,
    recovery_timeout_ms: 120_000,
    half_open_max_requests: 2,
    on_open: 'FALLBACK',
    fallback_agent: 'wo_orchestrator', // Manual scheduling
  },
  qa_review: {
    agent_id: 'qa_review',
    failure_threshold: 1,           // QA is critical — fail fast
    recovery_timeout_ms: 600_000,
    half_open_max_requests: 1,
    on_open: 'ESCALATE',
    escalation_target: 'human_checkpoint',
  },
  vendor_coord: {
    agent_id: 'vendor_coord',
    failure_threshold: 2,
    recovery_timeout_ms: 300_000,
    half_open_max_requests: 1,
    on_open: 'BLOCK',              // Vendor failures block that WO only
  },
};