---
title: "Executor Orchestrator Pattern"
aliases:
  - "Executor Orchestrator"
  - "Spawned Worker Pattern"
  - "executor-orchestrator-redesign"
created: '2026-05-14'
updated: '2026-05-31'
tags:
  - personal-os
  - executor
  - planning
  - architecture
related:
  - "[[personal/projects/personal-os/executor-v2-redesign]]"
  - "[[personal/projects/personal-os/executor-spawning-research]]"
---
# Plan: Executor as Spawned Worker — Orchestrator Pattern

**Date**: 2026-05-14
**Status**: Planning
**Parent**: [[executor-v2-redesign]]

## Problem

Currently Eagle (орёл) handles executor tasks inline in the conversation:
- Takes on the task directly in the discussion thread
- Asks Alex for permissions mid-task, blocking the flow
- Creates tight coupling between conversational layer and execution layer

## Desired Architecture

```
Alex  →  Eagle (orchestrator, in Zulip topic)
               ↓  spawn
          Executor (worker process, separate Hermes session)
               ↓  writes to Zulip #executor topic
          Eagle monitors #executor
               ↓  reads recent output (not full thread)
               ↓  auto-approve obvious decisions
               ↓  escalate ambiguous → @mention Alex
```

## Roles

### Eagle (Orchestrator)
- Receives task request in any Zulip topic
- Queues task to `executor_queue` DB table
- Spawns Executor worker via `hermes cron run` or similar
- Monitors `#executor` topic for Executor messages
- Reads only recent N messages (sliding window, not full thread)
- Auto-approval logic:
  - "create worktree" → approve
  - "run tests" → approve
  - "open draft PR" → approve
  - "push to branch" → approve
  - "modify unrelated file" → DENY + escalate
  - "post Asana comment" → escalate to Alex
  - Any scope expansion → escalate to Alex
- @mention Alex only when ambiguous or high-risk

### Executor (Worker)
- Separate Hermes session/process
- Bot identity: "Executor" or "Исполнитель" (not Eagle)
- Communicates via `#executor` Zulip topic
- Posts structured messages: `[REQUEST: <action>]`, `[STATUS: <phase>]`, `[DONE: <result>]`
- Does NOT ask Alex directly — all escalations go to Eagle
- On permission denied → explain why, ask what to do differently

## Message Protocol (Executor → Eagle)

```
[STATUS: investigation] Analysing bug GID 123456...
[REQUEST: create_worktree] Branch: fix/tab-preview-stuck
[REQUEST: run_tests] Scheme: macOS UI Tests CI
[STATUS: pr_open] Draft PR: https://github.com/...
[DONE: pr_ready] PR #1234 opened, CI green, ready for review
[ESCALATE: scope_expansion] Found unrelated issue in TabBar.swift — should I fix it?
```

## Auto-approval Rules (Eagle)

| Message type | Auto action |
|---|---|
| `[REQUEST: create_worktree]` | ✅ approve silently |
| `[REQUEST: run_build]` | ✅ approve silently |
| `[REQUEST: run_tests]` | ✅ approve silently |
| `[REQUEST: open_draft_pr]` | ✅ approve silently |
| `[REQUEST: push_branch]` | ✅ approve silently |
| `[REQUEST: post_asana_comment]` | ⚠️ show Alex, wait |
| `[REQUEST: merge_pr]` | ❌ always escalate |
| `[ESCALATE: *]` | ⚠️ always escalate |
| `[ESCALATE: scope_expansion]` | ❌ deny by default + notify Alex |

## Eagle Monitoring Loop

Eagle does NOT run a continuous monitoring process. Instead:
- Option A: Hermes cron (every 2 min) → check `#executor` for unprocessed `[REQUEST]` or `[ESCALATE]` messages → process them
- Option B: Webhook trigger on Zulip `#executor` stream → Eagle session wakes up

**Recommendation: Option A** (simpler, uses existing cron infra)

## Context Window Management

Eagle reads Executor's thread with sliding window:
- Last 20 messages from `#executor` for the current `executor_run_id`
- Filter by `run_id` tag in messages to handle concurrent runs
- Structured messages allow O(1) parsing without LLM

## Relation to Executor v2

This is a UI/coordination layer ON TOP of executor-v2 bash daemons:
- executor-runner.sh still does the heavy lifting
- Eagle becomes the gatekeeper/orchestrator that monitors and approves
- Executor worker sends structured messages via Zulip API (or hermes platform API)

## Implementation Steps

1. Define message protocol (structured tags)
2. Add Zulip message sender to executor worker prompts
3. Create Eagle monitoring cron (2 min interval, `#executor` stream)
4. Implement auto-approval logic in Eagle monitoring prompt
5. Add escalation → `@mention Alex` in monitoring prompt
6. Test with a real executor run in dry-run mode

## Нужен GTD-подобный фреймворк оркестрации

> Заметка от 2026-05-18: нужен фреймворк оркестрации задач наподобие GTD — inbox → clarify → organize → execute. Eagle как orchestrator должен не только спавнить воркеров, но и управлять очередью задач по GTD-принципам: capture all inputs, один trusted system, обработка inbox по расписанию, контексты выполнения. Это высвободит ручную координацию (~2-4ч/день) которую Alex сейчас делает руками.

## External Insights (from ZeBrains / Habr research, 2026-06-02)

### AGENTS.md как жёсткий триггер правил
Практика ZeBrains: правила в system prompt ИИ склонен игнорировать без явного файла-триггера. Стоит добавить `AGENTS.md` (или `EXECUTOR.md`) в каждый рабочий worktree — воркер читает его первым делом перед началом работы. Это не дублирование промпта, а explicit "включение режима". Реализация — 3rd party паттерн, не 1st priority.

### Проверка на лишний код в pr-review
ИИ систематически генерирует ~40% избыточного кода (лишние поля, ненужные связи, переусложнённая логика). Стоит добавить в `executor-worker-pr-review.md` явный чеклист: нет ли файлов/методов/полей которые не нужны для этой конкретной задачи. Реализация — 3rd party паттерн, не 1st priority.

### Короткие промпты с явными actionable items (из proagents research)
Промпты воркеров должны быть краткими, но содержать конкретные actionable steps — не narrative prose. Каждый шаг = одно действие с явным expected outcome. Это важнее полноты описания.

## Open Questions

- How does Executor "spawn" as a separate bot persona? 
  - Option A: Same Hermes instance, different SOUL/persona config
  - Option B: Separate Hermes gateway with "Executor" identity
  - Option C: `hermes run -p executor-worker.md` as subprocess (non-interactive)
- Concurrent runs: Eagle needs to track run_id per conversation thread

---

## Связанные заметки
- [[personal/projects/personal-os/executor-v2-redesign|Executor v2 Redesign]]
- [[personal/projects/personal-os/executor-spawning-research|Executor Spawning Research]]