Run a smux-native manager/worker workflow over tmux panes with task envelopes, sanitized context mirrors, and optional thin helper scripts.
Use this skill when one pane should act as a manager agent and coordinate one or more worker agent panes through tmux-bridge, without first building a separate orchestration runtime.
This version also supports a ProblemMap drift guard: the manager can diagnose suspicious worker behavior from the shared context mirror before blindly retrying, widening scope, or rewriting prompts.
Manager is just another pane
tmux-bridge directly.Pane transport is for control signals
Workers should read a context mirror, not scrape the manager pane
context.jsonl / context.md / live.log.context_seq.Manager is the only task authority
TASK_ASSIGNTASK_ACCEPT, STATUS, RESULT, FAILTASK_ASSIGNtmux-bridge using protocol verbstail -f runtime/context/live.logInitialize a runtime directory:
smux-manager-skill/scripts/init-runtime.sh /tmp/smux-manager-demo
Label panes early:
tmux-bridge name "$(tmux-bridge id)" manager
tmux-bridge name %1 codex
Append sanitized context entries as the manager clarifies or narrows work:
smux-manager-skill/scripts/append-context.sh \
/tmp/smux-manager-demo 110 manager codex CONTEXT task-123 \
"Investigate failing auth tests under tests/ and src/auth.ts"
Dispatch a task:
smux-manager-skill/scripts/send-task.sh \
codex task-123 codex 45 110 lease-task-123 \
"Investigate failing auth tests" "tests/ src/auth.ts" \
"/tmp/smux-manager-demo/artifacts"
Track short replies in the manager pane and mirror meaningful ones back into context.jsonl / context.md / live.log.
When a worker starts to drift, diagnose before you re-prompt. For example:
python3 smux-manager-skill/scripts/problemmap-guard.py \
/tmp/smux-manager-demo task-123 codex \
--expected "Investigate failing auth tests under tests/ and src/auth.ts"
This writes a ProblemMap case, diagnosis, and gated event artifact under:
/tmp/smux-manager-demo/artifacts/problemmap/task-123/codex/
Use the diagnosis to decide whether to re-ground the task, restore continuity, tighten boundaries, or reassign the worker.
Let workers send protocol replies with the helper when PATH or read-guard friction appears:
TMUX_BRIDGE_BIN="$HOME/.smux/bin/tmux-bridge" \
smux-manager-skill/scripts/send-reply.sh \
manager TASK_ACCEPT task-123 codex 46 110 lease-task-123 \
"Accepted and starting inspection"
Required verbs:
HELLOTASK_ASSIGNTASK_ACCEPTHEARTBEATSTATUSASKRESULTFAILRequired fields on every task-bound message:
taskworkerseqlease_tokencontext_seqSee references/PROTOCOL.md for the wire format and examples.
context_seq so workers can read snapshot + delta instead of scraping manager scrollbackSee references/CONTEXT_MIRROR.md for file layout and update rules.
Use the ProblemMap guard when a worker shows signs such as:
ASK messages on the same taskSTATUS updates with little forward motionFAIL that suggests confusion, loss of continuity, or runtime closure issuesRESULT that does not line up with the manager's stated goalThe guard reads runtime/context/context.jsonl, builds a compact failure-bearing case, routes it through the sibling problemmap skill, and emits:
case.jsondiagnosis.jsonevent.jsonThe diagnosis is manager-facing. It helps the manager choose the next control move instead of improvising generic prompt changes.
See references/PROBLEMMAP_GUARD.md for trigger patterns and intervention guidance.
scripts/init-runtime.sh — create runtime folders and mirror filesscripts/append-context.sh — append a sanitized context event to JSONL / Markdown / live logscripts/send-task.sh — send a TASK_ASSIGN envelope using the required read-act-read cyclescripts/send-reply.sh — send worker replies with tmux-bridge path fallback and read-act-read handlingscripts/problemmap-guard.py — build a ProblemMap case from context events and emit a route-first drift diagnosisThe smux-native MVP worked, but the first live validations exposed two real sources of friction:
Pane-local PATH drift
tmux-bridge on PATH.TMUX_BRIDGE_BIN or fall back to ~/.smux/bin/tmux-bridge.Read guard recovery
type a reply and then forget the extra read required before keys Enter.Worker drift is often continuity or boundary failure, not just a bad prompt
ASK, stalled STATUS, and off-target RESULT messages can mean F2/F3/F4/F6-class problems.At that point, keep the same protocol and context mirror, then add a thin helper layer or a real runtime on top.