multi-agent-mux/.agents/skills/multi-agent-mux-delegate-job/SKILL.md

name, description, version, author, license, platforms

name	description	version	author	license	platforms
multi-agent-mux-delegate-job	Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, cline, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer.	1.1.0	Multi-Agent System	MIT	linux macos windows

multi-agent-mux-delegate-job — Async Job Delegation over MQTT

Delegate a unit of work to any autonomous agent, then observe it asynchronously instead of blocking. Every job gets a unique ID and a registry record. The worker agent publishes lifecycle events (started, permission_required, progress, completed, error) to a per-job MQTT topic, and the delegator/orchestrator subscribes to verify the final state.

This skill allows any agent (claude-code, hermes, agy, cline, etc.) to play any role: Orchestrator/Delegator, Worker/Implementer, or Reviewer.

---

Roles in Multi-Agent Mux

• Orchestrator (Delegator): Initiates the job, coordinates other agents, handles loops and reviews, and commits final changes.
• Worker (Implementer): Receives the brief file or task prompt, performs the implementation, and emits started/completed/error events.
• Reviewer: Evaluates git diffs or artifacts produced by the worker, and responds with a completed event containing "PASS" or feedback.

---

Core Commands (CLI)

The multi-agent-mux-delegate-job bash wrapper handles job registration, subscriber management, agent session targeting, and validation hooks:

# 1) Submit a new job to a targeted agent session (e.g. tmux session name 'demo')
multi-agent-mux-delegate-job submit \
  --agent <claude-code|hermes-agent|agy-agent|cline-agent|human> \
  --agent-session tmux:<session_name> \
  --prompt "Task description or instructions here" \
  --timeout 3600 --idle-timeout 120

# 2) Submit a job with a feedback loop (Worker-Reviewer Loop)
multi-agent-mux-delegate-job submit \
  --agent <worker_agent> --agent-session tmux:<worker_session> \
  --type loop --reviewer <reviewer_agent> --reviewer-session tmux:<reviewer_session> \
  --prompt "Task description"

# 3) Check job status and audit logs
multi-agent-mux-delegate-job status --job <JOB_ID>
multi-agent-mux-delegate-job logs   <JOB_ID>            # Chronological log of events
multi-agent-mux-delegate-job list                       # Summary of all registered jobs

# 4) Verify job artifacts with a validation script
multi-agent-mux-delegate-job verify --job <JOB_ID> --validate ./validate.sh

---

Task Delegation Types

Supported job types include:

• direct (default): Single agent execution (direct tasking).
• loop (Worker-Reviewer Loop): Alternates worker execution and reviewer evaluation until reviewer approves (PASS) or iterations run out.
• discuss (Research & Discussion): Collaboration between two agents to reach a consensus (e.g., agreeing on a design or plan).

For detailed state machine diagrams and configurations, see DELEGATION_TYPES.md.

---

The Event Protocol Contract

Every agent participating in the delegation contract must follow the same lifecycle publishing protocol using publish_event.py:

1. On Start: Publish started event. python3 .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py --job "$JOB_ID" --event started
2. On Tool/Permission Prompt: Publish permission_required event. python3 ... --job "$JOB_ID" --event permission_required --detail "<tool>:<reason>"
3. On Progress Update (Optional): Publish progress event. python3 ... --job "$JOB_ID" --event progress --detail "<status_update>"
4. On Success: Publish completed event. python3 ... --job "$JOB_ID" --event completed --detail "<summary>" (Reviewer should include "PASS" in the detail to approve).
5. On Failure/Feedback: Publish error event. python3 ... --job "$JOB_ID" --event error --detail "<reason_or_feedback>"

---

Audit Logs

Job lifecycle execution events are persistently mirrored to an append-only log under .mam/delegate_job_logs/<job_id>/ (containing meta.json, events.ndjson, and status.json). Use multi-agent-mux-delegate-job logs <job_id> to view the timeline.

---

Best Practices and Pitfalls

• Subscribe-Before-Publish: The subscriber must be running before the agent starts publishing. The submit command handles this automatically by launching the subscriber in the background first.
• Fresh job_id Propagation: Make sure the worker agent receives the correct JOB_ID generated for the current run, rather than reusing stale IDs from previous sessions.
• Brief delivery via file path: For long or complex prompts, write the instructions to a file (e.g. /tmp/task-brief.md) and pass a short prompt pointing to the file path to prevent terminal buffer overflows.
• Batch Grouping: Group non-overlapping tasks into batches to parallelize execution across multiple agent sessions, reducing overhead.