/setup

/superteam:setup

You are running the /superteam:setup command. Walk the user through an interactive setup for the superteam plugin. The goal is to (1) confirm which multiplexer they'll use, (2) let them assign a model per agent type, and (3) apply their choices by rewriting the four superteam-*.md files' model: frontmatter fields at the plugin's active install path (or ~/.claude/agents/ as a fallback for manual installs).

Do not skip steps. Each step uses the AskUserQuestion tool. After the user answers all questions, apply the changes in a single batch, then print the tailored launch instructions.

Step 0 — Resolve the install path

Before asking any questions, find which superteam install is active. Two cases:

1. Plugin install (preferred): the user ran claude /plugin install superteam. Files live at ~/.claude/plugins/cache/superteam/superteam/<version>/agents/. There may be multiple versions cached; pick the most recently modified.
2. Manual install: the user copied the .md files directly into ~/.claude/agents/.

Resolve via Bash:

# Try plugin install first (latest version directory by mtime).
PLUGIN_BASE=$(ls -1dt ~/.claude/plugins/cache/superteam/superteam/*/agents 2>/dev/null | head -1)
USER_BASE="$HOME/.claude/agents"

if [ -n "$PLUGIN_BASE" ] && [ -f "$PLUGIN_BASE/superteam-planner.md" ]; then
  BASE="$PLUGIN_BASE"
  INSTALL_KIND="plugin"
elif [ -f "$USER_BASE/superteam-planner.md" ]; then
  BASE="$USER_BASE"
  INSTALL_KIND="user-scope"
else
  echo "ERROR: superteam is not installed. Run 'claude /plugin install superteam' (preferred) or copy agents/superteam-*.md into ~/.claude/agents/ first."
  exit 1
fi
echo "$BASE"

Save the resolved path as BASE and the install kind as INSTALL_KIND. All subsequent file edits target $BASE/superteam-<role>.md.

If INSTALL_KIND == "plugin" and ~/.claude/agents/superteam-planner.md also exists, the user has both a plugin install AND legacy manual copies in user scope — these will collide and shadow each other unreliably. Before continuing, ask whether to delete the user-scope leftovers:

• Question: "You have superteam agent files at both ~/.claude/agents/ (legacy) and the plugin cache. They will collide. Delete the legacy user-scope copies?"
• Header: "Cleanup"
• Options:
  • Yes — delete legacy copies (Recommended) — "Removes ~/.claude/agents/superteam-*.md. The plugin's copies become the single source of truth."
  • No — keep both — "Leaves both in place. Agent discovery may be inconsistent; not recommended."

If the user picks Yes, rm -f ~/.claude/agents/superteam-*.md.

Step 1 — Multiplexer choice

Ask the user which terminal multiplexer they use. The four agents work under any of them — the only difference is the launch command + the visual layout of the teammates.

Use AskUserQuestion with:

• Question: "Which terminal multiplexer will you launch superteam under?"
• Header: "Multiplexer"
• Options:
  • cmux (recommended) — "Each teammate appears as a native cmux split with sidebar metadata + notifications. Uses cmux claude-teams --dangerously-skip-permissions which auto-translates to cmux splits via a tmux shim."
  • tmux — "Each teammate gets a tmux pane via Agent Teams' native tmux split-pane mode. Launch with tmux new && claude --agent superteam-planner."
  • iTerm2 — "Each teammate gets an iTerm2 pane via Agent Teams' native iTerm2 support. Launch with claude --agent superteam-planner inside iTerm2."
  • None / in-process — "All teammates run inside the lead's terminal; cycle with Shift+Down. Works in VS Code's terminal, Windows Terminal, Ghostty, or anywhere else."

Save the answer as MULTIPLEXER.

Step 2 — Layout mode

Ask the user which team layout they prefer. This is saved to config.json and used by the planner when spawning teammates and by /superteam:layout to arrange panes.

Use AskUserQuestion with:

• Question: "Which pane layout should the team use?"
• Header: "Team layout"
• Options:
  • flat (default) — "One tab/pane per teammate. Simple, easy to debug individual agents."
  • by-worktree — "All teammates working on the same ticket grouped into one split per ticket. Best for multiple tickets in flight."

Save the answer as LAYOUT. Default to flat if not otherwise specified.

Steps 3–6 — Per-agent model choice

For each of the four agents below, ask the user which Claude model to assign. Use AskUserQuestion for each (you can batch up to four in a single call).

Use the same option set per question:

• claude-opus-4-7 — "Highest quality. Recommended for complex reasoning + design. Slower + more expensive."
• claude-sonnet-4-6 — "Balanced. Strong on mechanical TDD + reviewer work. Fast, cost-effective."
• claude-haiku-4-5-20251001 — "Fastest + cheapest. Use only for trivial tasks. Limited reasoning."
• Keep current setting — "Don't change this agent's model from what's already on disk."

Ask in this order, with these question + header pairs:

1. Question: "Which model should superteam-planner use?" Header: "Planner model" Recommendation hint to include in your message: opus, since the planner does deeper reasoning about decomposition + dependencies.

2. Question: "Which model should superteam-implementer use?" Header: "Implementer model" Hint: sonnet — strong on mechanical TDD.

3. Question: "Which model should superteam-spec-reviewer use?" Header: "Spec reviewer model" Hint: sonnet — fast, accurate for spec compliance.

4. Question: "Which model should superteam-code-reviewer use?" Header: "Code reviewer model" Hint: sonnet — fast, accurate for quality + security reviews.

Save each answer as MODEL_PLANNER, MODEL_IMPLEMENTER, MODEL_SPEC_REVIEWER, MODEL_CODE_REVIEWER. If the user picks "Keep current setting" for any, skip that file in Step 6.

Step 5b — Layout preference

Ask the user which team layout they prefer. This is saved to ~/.claude/superteam/config.json as layout and read by the planner every time it spawns a team.

Use AskUserQuestion with:

• Question: "Preferred team layout when multiple tickets are in flight?"
• Header: "Team layout"
• Options:
  • flat (default) — "One tab/pane per teammate. Easiest for single-ticket runs or when you prefer to manage panes yourself."
  • by-worktree — "Group impl + spec-reviewer + code-reviewer of the same ticket into one split/tab per ticket. Best for parallel multi-ticket work."

Save the answer as LAYOUT_MODE.

After collecting all answers, write the config to ~/.claude/superteam/config.json:

mkdir -p "$HOME/.claude/superteam"
CONFIG="$HOME/.claude/superteam/config.json"

# Merge with any existing config (preserve model overrides from previous runs)
EXISTING="{}"
if [[ -f "$CONFIG" ]]; then
  EXISTING=$(cat "$CONFIG")
fi

echo "$EXISTING" | jq \
  --arg mux "$MULTIPLEXER" \
  --arg layout "$LAYOUT_MODE" \
  '. + {"multiplexer": $mux, "layout": $layout}' \
  > "$CONFIG"

echo "Config written to $CONFIG"

Step 6 — Apply the model choices via apply-overrides.sh

The model choices are persisted in config.json (Step 7). After writing config.json, apply them immediately by running the override hook:

bash "${CLAUDE_PLUGIN_DIR:-$(dirname "$0")/..}/hooks/apply-overrides.sh"

Or if running from within Claude Code where the repo path is known:

SUPERTEAM_AGENT_BASE="$BASE" bash hooks/apply-overrides.sh

apply-overrides.sh reads ~/.claude/superteam/config.json and rewrites the model: frontmatter line in each agent file found at $BASE. It is idempotent — running it multiple times produces the same result.

Model overrides survive plugin updates. Because choices are stored in config.json (not only in the plugin cache files), running claude /plugin update superteam will reset the cache files to shipped defaults, but apply-overrides.sh automatically re-applies your saved choices on the next session start. You do not need to re-run /superteam:setup after a plugin update.

Step 7 — Persist choices to ~/.claude/superteam/config.json (F6)

After applying model edits, write the user's choices to ~/.claude/superteam/config.json so that downstream commands (teardown, layout, retry, etc.) can read the persisted multiplexer and per-agent model overrides without re-prompting.

Run via Bash:

mkdir -p ~/.claude/superteam
cat > ~/.claude/superteam/config.json <<EOF
{
  "version": "1",
  "multiplexer": "$MULTIPLEXER",
  "layout": "$LAYOUT",
  "models": {
    "superteam-planner": "$MODEL_PLANNER",
    "superteam-implementer": "$MODEL_IMPLEMENTER",
    "superteam-spec-reviewer": "$MODEL_SPEC_REVIEWER",
    "superteam-code-reviewer": "$MODEL_CODE_REVIEWER"
  },
  "installKind": "$INSTALL_KIND",
  "installBase": "$BASE"
}
EOF
echo "Config written to ~/.claude/superteam/config.json"

If any model was "Keep current setting", substitute the literal string "keep" for that field — downstream commands that read this file must treat "keep" as "do not override".

Confirm the file was written: cat ~/.claude/superteam/config.json.

Step 9 — Reload + print tailored launch instructions

After all edits land, instruct the user to run /reload-plugins so Claude Code picks up the model changes (only required when INSTALL_KIND == "plugin"; manual installs are re-scanned on next session).

Then print one of the following based on MULTIPLEXER. Format as a code block they can copy.

• cmux:

  Setup complete. To launch your team:
  
      cd <your-repo>
      cmux claude-teams --dangerously-skip-permissions
  
  Inside the session, tell the lead:
  
      "Spawn superteam-implementer, superteam-spec-reviewer,
       and superteam-code-reviewer as my team. Then process ticket
       <YOUR-TICKET>: <spec>."
  

• tmux:

  Setup complete. To launch your team:
  
      cd <your-repo>
      tmux new -s superteam
      claude --agent superteam-planner
  
  Inside the session, tell the lead:
  
      "Spawn superteam-implementer, superteam-spec-reviewer,
       and superteam-code-reviewer as my team. Then process ticket
       <YOUR-TICKET>: <spec>."
  

• iTerm2:

  Setup complete. To launch your team:
  
      cd <your-repo>
      claude --agent superteam-planner
  
  iTerm2 split-pane mode kicks in automatically when the lead spawns
  teammates. Inside the session, tell the lead:
  
      "Spawn superteam-implementer, superteam-spec-reviewer,
       and superteam-code-reviewer as my team. Then process ticket
       <YOUR-TICKET>: <spec>."
  

• None / in-process:

  Setup complete. To launch your team:
  
      cd <your-repo>
      claude --agent superteam-planner
  
  Teammates will run inside this terminal. Cycle through them with
  Shift+Down. Inside the session, tell the lead:
  
      "Spawn superteam-implementer, superteam-spec-reviewer,
       and superteam-code-reviewer as my team. Then process ticket
       <YOUR-TICKET>: <spec>."
  

Step 10 — Final summary

Print a one-line summary: which models are assigned to which agents, which multiplexer was selected, and which install path was used ($BASE).

If INSTALL_KIND == "plugin", add this caveat:

⚠ The model overrides are written to the plugin cache ($BASE). Running claude plugin update superteam will reset them to the plugin's shipped defaults. Re-run /superteam:setup after any plugin update to re-apply your choices.

Then stop. Do not auto-launch anything.