@devo-bmad-custom/agent-orchestration 1.0.9 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devo-bmad-custom/agent-orchestration",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "BMAD Method — AI-native agile workflow system for Claude Code and compatible AI assistants",
   "keywords": [
     "bmad",

package/src/.agents/skills/tmux-commands/SKILL.md

@@ -7,7 +7,7 @@ Verified, tested tmux command templates for agent orchestration. Every command i
 2. Always append `Enter` to every `tmux send-keys` call
 3. **Use `-l` (literal) flag for all free-form message content** — prevents `|`, `:`, and other chars being interpreted as tmux key sequences. Send `Enter` as a separate call after. Do NOT use `-l` for slash commands (`/color`, `/rename`, `/exit`) — those must be interpreted.
 4. Verify pane exists before any operation targeting it
-5. Use `/rename` and `/color` Claude Code commands (not OSC 2 or `select-pane -T`) for agent identity
+5. **`/color` and `/rename` are sent by the spawner** via separate `tmux send-keys` calls after the agent starts — never rely on the agent's prompt to self-invoke them. Each command is its own `send-keys` call with `Enter`, with `sleep 10` between.
 
 ---
 
@@ -56,31 +56,38 @@ ROLE="dev"
 ROLE_COLOR=$(get_role_color "$ROLE")
 SPAWNER_PANE=$(tmux display-message -p "#{pane_id}")
 
-# 1. Split the pane
+# 1. Split the pane — wait 15s for WSL bash + Claude to initialize before sending commands
 sleep 10
 tmux split-window -h -c "$PROJECT_ROOT" \
   "claude --dangerously-skip-permissions 'You are the $ROLE agent. \
-FIRST: run /color $ROLE_COLOR then /rename $ROLE-agent. \
-Spawner pane: $SPAWNER_PANE. Session file: $SESSION_FILE. \
+Your spawner pane is $SPAWNER_PANE. Session file: $SESSION_FILE. \
+Always use -l flag for message content in tmux send-keys. \
 Always sleep 10 before and after every tmux command. \
 Always append Enter to every tmux send-keys call. \
 Always verify pane exists before targeting it. \
 $TASK_CONTEXT'"
-sleep 10
+sleep 15
 
 # 2. Capture new pane ID
 NEW_PANE_ID=$(tmux list-panes -F "#{pane_id}" | tail -1)
+
+# 3. Set agent identity — spawner sends /color and /rename as separate commands.
+#    Do NOT combine into one send-keys call; each must be submitted individually.
+sleep 10
+tmux send-keys -t "$NEW_PANE_ID" "/color $ROLE_COLOR" Enter
+sleep 10
+tmux send-keys -t "$NEW_PANE_ID" "/rename ${ROLE}-agent" Enter
 sleep 10
 
-# 3. Disable OSC 2 auto-rename (we use /rename instead)
+# 4. Disable OSC 2 auto-rename (we use /rename instead)
 tmux set-option -t "$NEW_PANE_ID" -p allow-rename off
 sleep 10
 
-# 4. Set pane border title (visible in tmux, separate from /rename)
+# 5. Set pane border title (visible in tmux, separate from /rename)
 tmux select-pane -t "$NEW_PANE_ID" -T "${ROLE}-${NEW_PANE_ID}"
 sleep 10
 
-# 5. Rebalance layout with master awareness
+# 6. Rebalance layout with master awareness
 tmux select-pane -t "$MASTER_PANE"
 sleep 10
 tmux select-layout main-vertical
@@ -126,18 +133,25 @@ fi
 
 ### 3. `tmux_kill_agent` — Gracefully close an agent pane
 
+**Trigger:** Coordinator sees a pane with status `ready-to-close` in the session file Pane Lifecycle table.
+
+**Pre-conditions (verify all before killing):**
+- [ ] Agent's report-back received (STEP COMPLETE message seen in this pane or session file updated)
+- [ ] Task marked `done` in session file Tasks section
+- [ ] Claude session ID saved to session file
+
 ```bash
-# Inputs: TARGET_PANE_ID, MASTER_PANE, SESSION_NAME, WINDOW_ID
+# Inputs: TARGET_PANE_ID, MASTER_PANE, SESSION_FILE
 TARGET_PANE_ID="%31"
 MASTER_PANE="%0"
 
-# 1. Verify pane exists in expected context
+# 1. Verify pane exists
 sleep 10
-VERIFIED=$(tmux list-panes -a -F "#{pane_id} #{session_name} #{window_id}" \
-  | grep "^$TARGET_PANE_ID ")
+VERIFIED=$(tmux list-panes -a -F "#{pane_id}" | grep -Fx "$TARGET_PANE_ID")
 if [ -z "$VERIFIED" ]; then
-  echo "ERROR: pane $TARGET_PANE_ID not found — aborting kill"
-  exit 1
+  echo "WARN: pane $TARGET_PANE_ID already gone — marking closed in session file"
+  # Update session file status to closed and exit
+  exit 0
 fi
 
 # 2. Send /exit (lets Claude flush writes and exit cleanly)
@@ -145,17 +159,24 @@ sleep 10
 tmux send-keys -t "$TARGET_PANE_ID" "/exit" Enter
 sleep 10
 
-# 3. Kill the pane
-tmux kill-pane -t "$TARGET_PANE_ID"
-sleep 10
+# 3. Verify pane closed on its own (Claude exits after /exit)
+STILL_ALIVE=$(tmux list-panes -a -F "#{pane_id}" | grep -Fx "$TARGET_PANE_ID")
+if [ -n "$STILL_ALIVE" ]; then
+  # Force kill if still up after /exit
+  tmux kill-pane -t "$TARGET_PANE_ID"
+  sleep 10
+fi
 
-# 4. Rebalance remaining panes
+# 4. Update session file — mark pane as closed
+# Edit Pane Lifecycle row: change status to `closed`, check off remaining boxes
+
+# 5. Rebalance remaining panes
 tmux select-pane -t "$MASTER_PANE"
 sleep 10
 tmux select-layout main-vertical
 sleep 10
 
-echo "Killed pane $TARGET_PANE_ID and rebalanced"
+echo "Closed pane $TARGET_PANE_ID — session file updated, layout rebalanced"
 ```
 
 ### 4. `tmux_rebalance` — Equalize pane sizes with master awareness
@@ -204,9 +225,11 @@ else
 fi
 ```
 
-### 6. `tmux_register_agent` — Agent startup: find session, register, set identity
+### 6. `tmux_register_agent` — Agent startup: find session, register
+
+Spawned agents do NOT self-invoke `/color` or `/rename` — the spawner sends those via `tmux send-keys` before handing off the task. This template handles session registration only.
 
-Every agent — including the master/coordinator conversation — runs this on startup BEFORE doing any work. The master conversation always runs `/color blue` + `/rename master-agent` first.
+The master/coordinator conversation is the exception: it runs `/color blue` and `/rename master-agent` manually as its first two actions since there is no spawner above it.
 
 ```bash
 # Inputs: ROLE, SESSION_FILE (passed in spawn context)
@@ -217,11 +240,6 @@ SESSION_NAME=$(tmux display-message -p "#{session_name}")
 WINDOW_ID=$(tmux display-message -p "#{window_id}")
 PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")
 
-# 2. Set own identity via Claude Code commands
-# (These are sent as slash commands in the Claude conversation, not bash)
-# /color <role_color>
-# /rename <role>-agent
-
 # 3. Find session file
 if [ -n "$BMAD_SESSION_ID" ]; then
   SESSION_FILE="$PROJECT_ROOT/_bmad-output/sessions/$BMAD_SESSION_ID/agent-sessions.md"
@@ -261,8 +279,13 @@ tmux send-keys -t "$SPAWNER_PANE" Enter
 sleep 10
 
 # 4. Check for more pending tasks for this role
-# 5. If found: claim next task
-# 6. If none: set status to idle in Active Agents table
+# 5. If found: claim next task and continue
+# 6. If none:
+#    a. Set status to `ready-to-close` in Pane Lifecycle table (NOT Active Agents)
+#    b. Check all close-down boxes in Pane Lifecycle row:
+#       ☑ report-back sent · ☑ session ID saved · ☑ task marked done · ☑ ready-to-close set
+#    c. The COORDINATOR is responsible for executing /exit + kill-pane.
+#       Do NOT self-exit unless you are the coordinator or explicitly told to.
 ```
 
 ---
@@ -349,12 +372,100 @@ sleep 10
 
 ---
 
+## Verification & Retry Protocol
+
+Every tmux operation must be verified after execution. Never assume a command worked.
+
+### Verifying `/color` and `/rename` applied
+
+After the spawner sends identity commands, verify the pane is alive and responsive:
+
+```bash
+# After sending /color and /rename, verify pane is still active (not crashed)
+sleep 10
+PANE_ALIVE=$(tmux list-panes -a -F "#{pane_id}" | grep -Fx "$NEW_PANE_ID")
+if [ -z "$PANE_ALIVE" ]; then
+  echo "ERROR: agent pane $NEW_PANE_ID died after identity commands"
+  exit 1
+fi
+# Note: /color and /rename visual effects are immediate in Claude Code.
+# If the pane is alive, the commands were received.
+```
+
+### Verifying message delivery
+
+Always capture the pane buffer after sending a message and grep for the key token:
+
+```bash
+tmux_verify_delivery() {
+  local PANE="$1"
+  local TOKEN="$2"   # unique substring from the message
+  local RETRIES=3
+
+  for i in $(seq 1 $RETRIES); do
+    sleep 10
+    FOUND=$(tmux capture-pane -t "$PANE" -p -S - | grep -F "$TOKEN")
+    if [ -n "$FOUND" ]; then
+      echo "OK: message confirmed in pane $PANE (attempt $i)"
+      return 0
+    fi
+    if [ $i -lt $RETRIES ]; then
+      echo "WARN: '$TOKEN' not found in pane $PANE, retrying ($i/$RETRIES)..."
+    fi
+  done
+
+  echo "ERROR: message '$TOKEN' never confirmed in pane $PANE after $RETRIES attempts"
+  return 1
+}
+
+# Usage after sending a message:
+tmux send-keys -t "$TARGET_PANE" -l "$MESSAGE"
+tmux send-keys -t "$TARGET_PANE" Enter
+tmux_verify_delivery "$TARGET_PANE" "TASK-001"  # use a unique token from the message
+```
+
+### Verifying agent spawned and initialized
+
+After splitting, confirm the pane exists and Claude has started (prompt visible):
+
+```bash
+# Wait for Claude prompt to appear in new pane (up to 30s)
+READY=0
+for i in 1 2 3; do
+  sleep 10
+  PROMPT=$(tmux capture-pane -t "$NEW_PANE_ID" -p -S - | grep -c "❯\|>\|Claude\|Human")
+  if [ "$PROMPT" -gt 0 ]; then
+    READY=1
+    break
+  fi
+  echo "Waiting for agent to initialize (attempt $i)..."
+done
+if [ "$READY" -eq 0 ]; then
+  echo "ERROR: agent pane $NEW_PANE_ID did not show prompt after 30s"
+  exit 1
+fi
+```
+
+### Retry rules
+
+| Operation | Verify by | Max retries | On failure |
+|---|---|---|---|
+| Message send | grep token in pane buffer | 3 | Log error, write to session file |
+| `/color` / `/rename` | pane still alive | 1 | Re-send both commands |
+| Pane spawn | pane ID in list + prompt visible | 3 | Kill and re-spawn |
+| Layout rebalance | `tmux list-panes` shows expected count | 1 | Re-run `select-layout` |
+
+---
+
 ## Common Mistakes (Avoid These)
 
 1. **No `Enter` on send-keys** — message typed but never submitted
 2. **No sleep between tmux commands** — race conditions, stale pane lists
-3. **Using OSC 2 / `select-pane -T` for naming** — Claude Code overwrites these
-4. **Killing pane without `/exit` first** — leaves partial writes, git locks
-5. **Using `tiled` layout instead of `main-vertical`/`main-horizontal`** — breaks master position
-6. **Reading pane titles for routing** — unreliable; use session file pane IDs
-7. **Spawning without `--dangerously-skip-permissions`** — agent halts on every tool use
+3. **Combining `/color` and `/rename` in one send-keys call** — only the first command runs; send each as a separate call with `sleep 10` between
+4. **Using OSC 2 / `select-pane -T` for naming** — Claude Code overwrites these
+5. **Killing pane without `/exit` first** — leaves partial writes, git locks
+6. **Using `tiled` layout instead of `main-vertical`/`main-horizontal`** — breaks master position
+7. **Reading pane titles for routing** — unreliable; use session file pane IDs
+8. **Spawning without `--dangerously-skip-permissions`** — agent halts on every tool use
+9. **No `-l` flag on message content** — `|` and `:` get interpreted as key sequences, message is garbled
+10. **Agent self-invoking `/color`+`/rename`** — unreliable; spawner sends these via `tmux send-keys` after the agent starts