Skill: superteam:layout

Skill: superteam:layout

Arrange running superteam agent panes into a logical visual layout. Reads the persisted multiplexer and layout preference from ~/.claude/superteam/config.json (config.layout, config.multiplexer). Supports two modes: flat and by-worktree.

---

When to invoke this skill

Explicit triggers (user says any of these):

• "organize the layout"
• "group agents by ticket"
• "tidy panes"
• /superteam:layout <mode>
• "switch to flat layout"
• "switch to by-worktree"

Implicit triggers (planner-owned — NO opt-out):

• After team spawn: planner MUST invoke this skill once all initial teammates are live.
• After /superteam:ticket <id>: planner invokes again after the new ticket's 3 tasks are dropped and teammates spawned.
• After /superteam:retry <ticket>: planner ensures the rework teammate(s) land in the existing ticket group.
• After /superteam:gc: planner invokes to close empty groups left by removed worktrees.

---

Step 0 — Prerequisite: F8 + F14 pane-title discipline

Before this skill can group panes, each teammate must have renamed its terminal pane to the <ticket>:<role> string (F14 convention):

<ticket>:<role>

Teammate	Pane title format	Example
Implementer	<ticket>:impl	AUTH-1:impl
Spec-reviewer	<ticket>:spec	AUTH-1:spec
Code-reviewer	<ticket>:review	AUTH-1:review

Each teammate agent sets the pane title on first action via:

printf '\033]0;%s\007' "<ticket>:<role>"
# e.g.: printf '\033]0;AUTH-1:impl\007'

This FIRST RUN step is mandatory in all three teammate system prompts (implementer / spec-reviewer / code-reviewer). Without it, parse_ticket_groups cannot distinguish panes.

The by-worktree mode groups panes by the ticket prefix — everything before the : separator. For example, AUTH-1:impl, AUTH-1:spec, and AUTH-1:review all share the AUTH-1 prefix and are grouped together.

The layout skill discovers pane titles by querying the multiplexer:

• cmux: tmux list-panes -a -F '#{pane_title}' (cmux exposes a tmux shim; use the supported list-panes verb)
• tmux: tmux list-panes -a -F '#{pane_title}'
• iTerm2: osascript -e 'tell application "iTerm2" to tell current window to tell each tab to tell each session to name'

---

Step 1 — Read persisted config

CONFIG="$HOME/.claude/superteam/config.json"

if [[ -f "$CONFIG" ]]; then
  MUX=$(jq -r '.multiplexer // "cmux"' "$CONFIG")
  LAYOUT=$(jq -r '.["config.layout"] // "flat"' "$CONFIG")
else
  MUX="cmux"
  LAYOUT="flat"
fi

# Override from argument if provided
if [[ -n "${1:-}" ]]; then
  LAYOUT="$1"
fi

Valid values for config.layout: flat, by-worktree.

---

Step 2 — Validate mode

source "$(dirname "$0")/../../lib/layout-dispatch.sh"
validate_layout_mode "$LAYOUT" || exit 1

---

Step 3 — Collect live pane titles

Collect current pane titles from the multiplexer. Each line should be in the form agent-name · TICKET-N.

case "$MUX" in
  cmux)
    # cmux exposes a tmux shim; list-panes is the supported way to read titles.
    PANE_TITLES=$(tmux list-panes -a -F '#{pane_title}' 2>/dev/null || echo "")
    ;;
  tmux)
    PANE_TITLES=$(tmux list-panes -a -F '#{pane_title}' 2>/dev/null || echo "")
    ;;
  iterm2)
    # iTerm2: use osascript to enumerate session names
    PANE_TITLES=$(osascript -e \
      'tell application "iTerm2" to tell current window to get name of every session of every tab' \
      2>/dev/null | tr ',' '\n' | xargs || echo "")
    ;;
  none|*)
    echo "Multiplexer '$MUX' does not support pane manipulation — layout is a no-op."
    exit 0
    ;;
esac

---

Step 4 — Apply layout

The layout can be applied by invoking the script directly (preferred) or by calling layout_dispatch when already sourced:

# Preferred: invoke as a runnable script
bash ${CLAUDE_PLUGIN_ROOT}/lib/layout-dispatch.sh "$LAYOUT"

# Or, when lib is already sourced:
layout_dispatch "$LAYOUT" "$MUX" "$PANE_TITLES"

To preview planned moves without executing them, use --dry-run:

bash ${CLAUDE_PLUGIN_ROOT}/lib/layout-dispatch.sh by-worktree --dry-run

---

Mode reference

flat (default)

One tab/pane per teammate. No structural changes are applied. This is the no-op / pass-through mode.

Use case: simple debugging, single-ticket runs, or when the user prefers to manage panes manually.

by-worktree

All teammates working on the same ticket — impl(TICKET-N), spec-review(TICKET-N), code-review(TICKET-N) — are grouped into one parent pane / split per ticket.

Use case: multiple tickets in flight — watch a ticket's full pipeline at once.

cmux note: under cmux claude-teams, cmux groups teammate splits natively (and the tmux shim exposes no pane-move/join verb to script). by-worktree is therefore a no-op on cmux — it applies only to tmux and iTerm2.

---

Per-multiplexer dispatch

Multiplexer	Group/split primitive	Move primitive
cmux	native — cmux groups teammate splits automatically; nothing to script	native
tmux	tmux split-window (new window per ticket group)	tmux join-pane -s <src-pane-id> -t <dst-pane-id>
iTerm2	split horizontally with default profile via AppleScript	Move tab between split groups via osascript / iTerm2 Python API

cmux — no action needed

cmux renders each teammate (spawned via the native Agent tool) as a split and groups them automatically. The skill emits no commands for cmux:

# (native) TICKET-1 — cmux renders this group automatically

tmux example

# Join spec and code reviewer into the impl pane's window
tmux join-pane -s $SPEC_PANE_ID  -t $IMPL_PANE_ID
tmux join-pane -s $CODE_PANE_ID  -t $IMPL_PANE_ID

iTerm2 (AppleScript) example

tell application "iTerm2"
  tell current window
    create tab with default profile
    tell current tab
      split horizontally with default profile  -- spec-reviewer pane
      split horizontally with default profile  -- code-reviewer pane
    end tell
  end tell
end tell

---

Re-arrange on demand

Invoking superteam:layout <mode> against an already-running team moves existing panes without re-spawning.

Note: Running by-worktree mode twice may create duplicate groups if the multiplexer does not detect that a group already exists. If that happens, close the duplicate group manually and re-run. flat mode is always safe to invoke multiple times.

---

Config persistence

The layout preference is stored in ~/.claude/superteam/config.json:

{
  "multiplexer": "cmux",
  "config.layout": "by-worktree",
  "models": {
    "planner": "claude-opus-4-7",
    "implementer": "claude-sonnet-4-6",
    "spec-reviewer": "claude-sonnet-4-6",
    "code-reviewer": "claude-sonnet-4-6"
  }
}

The setup wizard (/superteam:setup) writes this file. The planner reads it at spawn time via jq -r '.["config.layout"] // "flat"' ~/.claude/superteam/config.json.