From 9ee9076d600f286abfc7e0834bc7cfcc982510a9 Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 21 Jun 2026 06:41:25 +0000 Subject: [PATCH] docs(delegate-job): add Subagent Orchestration Pattern section to SKILL.md Verified pattern from 2026-06-21 6-batch refactoring sprint: - Main worker (agy-new) + 2 reviewers (agy-existing, claude-existing) + Hermes orchestrator - Brief delivery via file path (not inline tmux send-keys) - Polling for short tasks, MQTT subscriber for long tasks - Complementary reviewer coverage (different models catch different bugs) - Hermes fallback fix for small well-defined issues - Batch grouping rules (no file overlap) --- .../SKILL.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/skills/tmux-agent-orchestrate-delegate-job/SKILL.md b/skills/tmux-agent-orchestrate-delegate-job/SKILL.md index b55ce69..336811b 100644 --- a/skills/tmux-agent-orchestrate-delegate-job/SKILL.md +++ b/skills/tmux-agent-orchestrate-delegate-job/SKILL.md @@ -317,6 +317,39 @@ business-logic validation — those are hooks you fill (`validate.sh` reads - **Secrets in `detail`/`data`** — keep payloads generalised; no paths, keys, or tokens (except the production `auth_token` in `data`). +## Subagent Orchestration Pattern + +When using this skill from a Hermes `delegate_task` subagent to dispatch work to +a coding-agent CLI (agy/claude) running in a tmux session, the following pattern +has been verified (2026-06-21, 6-batch refactoring sprint): + +### Roles +- **Main worker** (implementation): one agent session (e.g. `agy-new`) receives + brief files and executes code changes. +- **Reviewers** (spec compliance + code quality): two other agent sessions + (e.g. `agy-existing`, `claude-existing`) review the diff in parallel. +- **Hermes** (orchestrator): dispatches subagents, verifies diffs, commits, + and falls back to direct fixes when reviewers find issues. + +### Key lessons learned +1. **Brief delivery via file path** — don't paste long briefs inline via + `tmux send-keys`; the TUI may swallow them. Instead, send a short instruction + like "follow /tmp/batch1-brief.md" and let the agent read the file. +2. **Polling vs MQTT subscriber** — for short tasks (<5min), pane polling + (`capture-pane` + grep for completion markers) is simpler and more reliable + than registering a job via `registry.py` + `job_subscriber.py`. Use MQTT + subscriber only for long-running jobs (>5min) where push notification matters. +3. **Reviewers catch different bugs** — in practice, agy (Flash) caught + semantic issues (slash matching, export scope), while claude (Opus) caught + API signature mismatches (paho v2 5-arg vs 4-arg `on_disconnect`). Two + reviewers with different models provide complementary coverage. +4. **Hermes fallback fix** — when reviewers find a small, well-defined issue + (wrong argument count, missing slash), Hermes should fix it directly rather + than re-dispatching the implementer. This saves a full round-trip. +5. **Batch grouping** — group 2-3 FW items per batch when they touch different + files (no file overlap). This amortises the dispatch overhead. Items touching + the same file must be in separate batches to avoid conflicts. + ## Verification Checklist - [ ] `started` → `completed` over the public broker: subscriber prints the