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