Atomizer/hq/workspaces/shared/skills/orchestrate/README.md

Orchestration Engine — Atomizer HQ

Multi-instance synchronous delegation, workflow pipelines, and inter-agent coordination.

Overview

The Orchestration Engine enables structured communication between 8 independent OpenClaw agent instances running on Discord. It replaces fire-and-forget delegation with synchronous handoffs, chaining, validation, and reusable YAML workflows.

Architecture

┌─────────────────────────────────────────────────┐
│             LAYER 3: WORKFLOWS                  │
│       YAML multi-step pipelines                 │
│   (workflow.py — parallel, sequential, gates)   │
├─────────────────────────────────────────────────┤
│           LAYER 2: SMART ROUTING                │
│     Capability registry + channel context       │
│  (AGENTS_REGISTRY.json + fetch-channel-context) │
├─────────────────────────────────────────────────┤
│         LAYER 1: ORCHESTRATION CORE             │
│   Synchronous delegation + result return        │
│      (orchestrate.py — inotify + handoffs)      │
├─────────────────────────────────────────────────┤
│           EXISTING INFRASTRUCTURE               │
│  8 OpenClaw instances, hooks API, shared fs     │
└─────────────────────────────────────────────────┘

Files

File	Purpose
orchestrate.py	Core delegation engine — sends tasks, waits for handoff files via inotify
orchestrate.sh	Thin bash wrapper for orchestrate.py
workflow.py	YAML workflow engine — parses, resolves deps, executes pipelines
workflow.sh	Thin bash wrapper for workflow.py
fetch-channel-context.sh	Fetches Discord channel history as formatted context
metrics.py	Analyzes handoff files and workflow runs for stats
metrics.sh	Thin bash wrapper for metrics.py

Usage

Single delegation

# Synchronous — blocks until agent responds
python3 orchestrate.py webster "Find CTE of Zerodur" --caller manager --timeout 120

# With channel context
python3 orchestrate.py tech-lead "Review thermal margins" --caller manager --channel-context technical --channel-messages 20

# With validation
python3 orchestrate.py webster "Research ULE properties" --caller manager --validate --timeout 120

Workflow execution

# Dry-run (validate without executing)
python3 workflow.py quick-research --input query="CTE of ULE" --caller manager --dry-run

# Live run
python3 workflow.py quick-research --input query="CTE of ULE" --caller manager --non-interactive

# Material trade study (3-step pipeline)
python3 workflow.py material-trade-study \
  --input materials="Zerodur, Clearceram-Z HS, ULE" \
  --input requirements="CTE < 0.01 ppm/K" \
  --caller manager --non-interactive

Metrics

python3 metrics.py text    # Human-readable
python3 metrics.py json    # JSON output

Handoff Protocol

Agents write structured JSON to /home/papa/atomizer/handoffs/{runId}.json:

{
  "schemaVersion": "1.0",
  "runId": "orch-...",
  "agent": "webster",
  "status": "complete|partial|blocked|failed",
  "result": "...",
  "artifacts": [],
  "confidence": "high|medium|low",
  "notes": "...",
  "timestamp": "ISO-8601"
}

ACL Matrix

Caller	Can delegate to
manager	All agents
tech-lead	webster, nx-expert, study-builder, secretary
optimizer	webster, study-builder, secretary
Others	Cannot sub-delegate

Workflow Templates

• quick-research.yaml — 2 steps: Webster research → Tech-Lead validation
• material-trade-study.yaml — 3 steps: Webster research → Tech-Lead evaluation → Auditor review
• design-review.yaml — 3 steps: Tech-Lead + Optimizer (parallel) → Auditor consolidation

Result Storage

• Individual handoffs: /home/papa/atomizer/handoffs/orch-*.json
• Sub-delegations: /home/papa/atomizer/handoffs/sub/
• Workflow runs: /home/papa/atomizer/handoffs/workflows/{workflow-run-id}/
  • Per-step: {step-id}.json
  • Summary: summary.json