Berkahkarya Orchestrator

---
name: berkahkarya-orchestrator
description: Use when orchestrate multi-skill workflows by routing tasks to the right
  agents and coordinating cross-platform operations.
domain: core
author: oyi77
license: Apache-2.0
subdomain: core-platform
tags:
- ai-agent
- berkahkarya
- infrastructure
- memory
- orchestrator
- self-improvement
- workflow
version: 1.0.0
category: core
---

# Berkahkarya Orchestrator

## When to Use
**Trigger phrases:**
- "berkahkarya orchestrator"
- "Orchestrate multi-skill workflows by routing tasks to the right agents and coordinating cross-platform operations"


- When the task falls within this skill's domain expertise
- When automated execution saves time over manual work
- When the skill's tools and integrations are available


## When NOT to Use

- When the task can be solved with existing standard libraries
- When the infrastructure is already in place and working
- When the added complexity does not provide measurable benefit


## Overview

The Berkahkarya Orchestrator is a foundational core infrastructure skill that provides system-wide coordination capabilities for the agent ecosystem. It operates as the central dispatch hub that receives incoming requests, decomposes them into executable subtasks, routes each subtask to the most capable skill agent, and reconciles the results into a coherent final response. Unlike simple linear pipelines, the orchestrator supports parallel execution branches, dependency-aware sequencing, and intelligent fallback strategies when primary agents fail.

The orchestrator maintains a dynamic skill registry that tracks every available agent's capabilities, current load, and historical performance. When a request arrives, the orchestrator queries this registry to match each subtask's domain requirements against registered agent capabilities, selecting the optimal primary candidate and a fallback chain. This routing intelligence improves over time through a feedback loop that captures success rates, latency, and dispatch accuracy for every executed workflow.

Cross-platform coordination is a core capability — the orchestrator manages operations across Telegram, WhatsApp, browser automation, REST APIs, file systems, and custom integrations. It handles platform-specific concerns such as credential lifecycle, rate limiting, message formatting, and connection state without exposing these details to downstream skill agents. Each agent receives a normalized context payload regardless of the originating platform.

The orchestrator's dependency graph engine enables complex multi-step workflows with branches, joins, and conditional paths. It detects circular dependencies before execution begins, enforces ordering constraints for dependent subtasks, and parallelizes independent branches automatically. This graph-based approach ensures that complex cross-platform operations execute in the correct sequence while maximizing throughput through concurrent execution of independent work.

## Architecture
- **Input layer** — Receives and validates incoming requests; normalizes multi-platform input (Telegram, webhook, API, file) into standard internal format
- **Skill registry** — Maintains index of available agents with capability tags, load metrics, and success-rate history; supports dynamic add/remove during runtime
- **Dependency graph engine** — Builds and validates directed acyclic graphs of subtasks; identifies critical path, parallel branches, and blocking dependencies
- **Dispatch router** — Matches subtasks to skill agents using capability matching and performance history; manages timeout, retry, and fallback chain policies
- **State management** — Maintains immutable execution context across workflow steps; snapshots state at each transition for recovery and audit
- **Result reconciliation** — Collects outputs from parallel agents; applies conflict-resolution rules; merges partial results into coherent response
- **Output layer** — Formats results per target platform; delivers via appropriate channel (response, webhook callback, file write, event emit)
- **Feedback pipeline** — Captures execution metrics (latency, success/failure, dispatch accuracy); persists to performance store; updates registry weights for future routing

## Configuration
- **Skill registry path** — Set the file or API endpoint for agent capability definitions
- **Routing strategy** — Configure dispatch algorithm (round-robin, least-loaded, capability-weighted, failover-priority)
- **Per-agent timeouts** — Define timeout and retry limits per agent category (e.g., 30s for fast inference, 300s for batch processing)
- **Dependency graph validation** — Enable/disable cycle detection, critical path analysis, and parallel branch optimization
- **Platform connectors** — Configure credentials, rate limits, and formatting rules for each target platform
- **Logging level** — Set verbosity (DEBUG, INFO, WARN, ERROR); enable structured JSON output for log aggregators
- **Resource limits** — Define maximum concurrent dispatches, memory per workflow, and total execution wall-clock time
- **State persistence** — Configure snapshot interval, storage backend (memory, file, database), and retention policy

## Integration

- Exposes standard interfaces for other skills to consume
- Supports event-driven and request-response patterns
- Compatible with the 1ai-skills hook system
- Logs metrics for the skill performance monitor

## Workflow

1. **Signal detection** — Monitor incoming triggers from configured platforms (Telegram, webhook, API, file watch); parse and validate request format; reject malformed or out-of-scope inputs before processing begins.
2. **Task decomposition** — Split complex requests into atomic subtasks; classify each subtask by domain, urgency, and required capability; assign priority and sequencing metadata.
3. **Agent discovery and selection** — Query the skill registry for agents matching each subtask's domain tag; filter by availability, current load, and historical success rate; select primary and fallback agents.
4. **Dependency graph construction** — Build a directed acyclic graph of all subtasks; compute critical path; identify parallelizable branches and serialize dependent chains; validate against deadlock and resource contention.
5. **Dispatch and execution** — Route each subtask to its selected agent with full context payload; apply per-agent timeout, retry count, and circuit-breaker policies; monitor execution progress via heartbeats; escalate stalled tasks to fallback agents.
6. **Result reconciliation** — Collect outputs from all agents as they complete; apply conflict-resolution rules for overlapping results; merge partial completions into a coherent final output; log per-agent execution metrics.
7. **Post-execution analysis** — Compute end-to-end latency, per-agent success rates, and dispatch accuracy; persist execution record to performance store; update routing weights for future requests based on observed outcomes.

## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I will add monitoring later" | Without monitoring, you cannot detect failures. Add it from day one. |
| "One model is enough" | Different tasks need different models. Route intelligently. |
| "Premature optimization" | Infrastructure decisions are hard to change later. Design for scale early. |
| "A single orchestrator config works for all tasks" | Different task types need different dispatch strategies, timeouts, and fallback chains. Profile per category. |
| "Manual routing is fine at this scale" | Manual routing doesn't scale beyond 3-4 agents. Automate dispatch before coordination overhead dominates. |
| "If one skill fails, retry the same skill" | Repeated retries without fallback waste time. Route to a different agent or degrade gracefully after first failure. |

## Code Examples

### Python — Model routing with failover

```python
# Example: Model routing
ROUTES = {
    "code": ["claude-sonnet-4-20250514", "gpt-4o"],
    "vision": ["gemini-2.5-pro", "gpt-4o"],
    "fast": ["gemini-2.5-flash", "gpt-4o-mini"],
}

def route_request(task: str, prompt: str):
    models = ROUTES.get(task, ROUTES["fast"])
    for model in models:
        try:
            return call_model(model, prompt)
        except Exception:
            continue
    raise RuntimeError("All models failed")
```

### Node.js — Skill dispatch and result aggregation

```javascript
const skillRegistry = {
  code: ["claude-sonnet-4", "gpt-4o"],
  vision: ["gemini-2.5-pro", "gpt-4o"],
  fast: ["gemini-2.5-flash", "gpt-4o-mini"],
};

async function dispatch(taskType, prompt) {
  const models = skillRegistry[taskType] ?? skillRegistry.fast;
  for (const model of models) {
    try {
      return await callModel(model, prompt);
    } catch (err) {
      console.warn(`Model ${model} failed:`, err.message);
    }
  }
  throw new Error(`All models failed for task=${taskType}`);
}
```


## Common Issues & Troubleshooting

| Problem | Solution |
|---|---|
| Agent dispatch times out or hangs | Set per-agent timeout in dispatch config; implement circuit-breaker that degrades to fallback agents after 2 consecutive failures |
| State corruption across workflow steps | Use immutable state snapshots with explicit checkpointing between steps; validate state schema at each transition |
| Dependency deadlock between parallel tasks | Run dependency graph cycle detection before dispatch; flag circular dependencies and escalate instead of attempting execution |
| Conflicting outputs from multiple skill agents | Register conflict-resolution precedence rules per task category; default to "first confirmed correct" with consensus threshold |
| Platform credential expiration mid-workflow | Implement credential refresh hooks per platform; cache tokens with expiry-aware lookup and proactive renewal before dispatch |
| Skill registry returns stale/unavailable agents | Add health-check probe before dispatch; cache registry responses with TTL and fallback to last-known-good on probe failure |

## Monetization

| Approach | Timeframe | Description |
|---|---|---|
| Workflow-as-a-Service consulting | 1-3 months | Offer custom multi-agent workflow design for enterprises; build orchestration blueprints that integrate their existing tools with AI agents |
| SaaS workflow orchestration platform | 6-12 months | Build a visual workflow builder around the orchestrator engine — drag-and-drop agent routing, state management, and performance dashboards for teams |
| Agent coordination audit | 1-2 months | Review existing agent deployments for routing inefficiencies, dependency bottlenecks, and failure-prone dispatch patterns; deliver optimization roadmap |
| Enterprise SLA monitoring add-on | 3-6 months | Wrap the orchestrator with SLA dashboards, incident alerts, and compliance audit trails; sell as premium tier to mid-market customers |
| Custom integration bundle | 2-4 weeks per integration | Build and maintain platform-specific connectors (Telegram, WhatsApp, Slack, Discord, email) as reusable orchestration plugins |

## Process
### Preparation
1. **Task intake** — Receive incoming request, parse intent, classify task type, and extract routing parameters
2. **Skill discovery** — Query skill registry to identify capable agents for each task segment; verify availability and capability
3. **Dependency mapping** — Build execution graph with prerequisite chains; identify parallelization opportunities and blocking constraints

### Execution
4. **Task dispatch** — Route each task segment to the appropriate skill agent with full context, constraints, and expected output schema
5. **Cross-platform coordination** — Synchronize operations across platforms (Telegram, WhatsApp, browser, API, file system); maintain shared state across distributed agents

### Stewardship
6. **Result aggregation** — Collect outputs from all dispatched agents, resolve conflicts using precedence rules, merge partial results into coherent response
7. **Feedback loop** — Log outcomes to performance monitor, update routing weights based on success/failure, adjust skill registry priorities for future invocations

## Verification
- [ ] All steps executed successfully
- [ ] Results validated against acceptance criteria
- [ ] Error handling tested with edge cases
- [ ] Cross-platform operations verified across all target platforms
- [ ] Skill routing configuration validated for all task types
- [ ] Workflow dependency graph checked for cycles and deadlocks
- [ ] State persistence verified across workflow restarts
- [ ] Fallback strategies tested for all registered skill agents
- [ ] Streaming and batch modes both tested
- [ ] Documentation updated with findings