Squad¶

Named specialists you keep around across repos and sessions, defined once as plain TOML instead of remembered by hand:

# ~/.config/vupai/squad.toml
[squad.sage]
role = "frontend specialist"
program = "claude"          # a key from config [programs]; omit for the default pane_command
brief = """
You are sage, the frontend specialist. Favor small, reviewable diffs and
flag anything that touches shared components.
"""

The global file at ~/.config/vupai/squad.toml is always read; a repo can add its own .vupai/squad.toml on top, and a member with the same name there replaces the global one whole (no field-level merging). Names are single words and can't collide with a reserved word, the broadcast word, a program key, or another member - a bad file is warned about and the offending member skipped, never a crash.

Starter roster¶

Don't want to write briefs from scratch? Grab the starter squad: six specialists covering a typical project.

Install it (only if you don't have a roster yet - this would overwrite yours):

mkdir -p ~/.config/vupai
curl -fo ~/.config/vupai/squad.toml \
  https://raw.githubusercontent.com/itsjrsa/vupai/master/examples/squad.toml

Then say "open archer" inside a session, and run vupai squad to see the roster. The briefs are starting points, not doctrine: edit them freely. No member pins a program, so each launches your default pane_command (whatever agent CLI you use).

• Summon one: say "open sage" (also "start sage") and vupai splits a pane named sage and launches it. The pane border carries the role next to the program (sage · claude · frontend specialist), so the border says who they are, not just what tool they run. Each member has one live incarnation at a time - saying it again while sage is already up answers "sage is already up" instead of duplicating the pane.
• Brief delivery depends on the tool: a claude member gets the brief as a real system prompt (--append-system-prompt) at launch; every other program is launched bare and has the brief pasted as its first message; a plain shell member (program = "shell") gets no brief at all - pasting one into a shell would execute it. If the paste fails, the pane is kept and vupai says "brief not delivered" so you can hand it over yourself.
• No confirm popup: summoning a member is a direct order, like "open claude" - it launches immediately.
• See who's who: vupai squad lists the effective roster (global + repo overlay) with each member's name, role, program, and whether a live pane currently carries their name.
• Watch it live: say "open squad" (also "show squad", <prefix>+v's s entry, or vupai squad --pane) to split a read-only pane, like the tasks pane, that repaints every couple of seconds with each member's name, role, program, and up/- status, plus the brief flattened to at most two lines (a longer brief trails off with "..."; the full text stays in squad.toml). One pane per session - reopening focuses the existing one.
• Squad names are never handed out as auto callsigns, so a specialist's pane is never confused with an ad-hoc agent that happened to get the same name.

Triage also knows about the roster: when one exists, it proposes an owner per task, shown as [p1, S, sage] and spoken as "for sage".