---
name: team-tile-demo
description: Long-form guided demo of the all-maw-verb team bootstrap pattern — walks step-by-step from blank tmux session → maw tile N → TeamCreate → maw run with team-flagged claude.exe → SendMessage missions → shutdown_request → TeamDelete → cleanup. Narrates each step with the 6-seam visibility model and the wire format. Use when user says "team-tile-demo", "show me the team-tile flow", "demo the team mesh", "walk me through it", "long demo", or wants the educational walkthrough.
argument-hint: [--quick | --narrate] [--mission "<mission text>"]
---

# /team-tile-demo — The Long Walkthrough

A guided, narrated execution of the all-maw-verb team bootstrap pattern. Each step shows what runs, what happens, and what seam from [[ψ/ralph/55-teammate-message-wire]] it touches.

**Validated live**: 2026-05-20, digger-buddy-team session, captured in [[ψ/lab/buddy-mom-demo/plan.md]].

## When to use

- User wants to UNDERSTAND the pattern, not just run it (`/team-tile-spawn` is the production verb)
- Teaching someone new to the fleet how teams work
- Reproducing the empirical seams during a teaching session
- User says "long demo", "walk me through", "teach me team-tile"

## When NOT to use

- Production team spawn → use [[~/.claude/skills/team-tile-spawn/]]
- Just need quick parallel agents → use built-in `/team-agents`
- Single subagent → use the `Agent` tool

## Modes

| Flag | Behavior |
|---|---|
| `--narrate` (default) | Pause and explain at each step; show seam references |
| `--quick` | Run end-to-end without pausing; print commands but skip explanations |
| `--mission "<txt>"` | Override the default 2-bullet mission with custom text |

## The 12-step walkthrough

### Pre-flight (step 0)

Check the prerequisites. Each line is a discoverable failure mode.

```bash
[ -n "$TMUX" ] || die "not in tmux"
[ -n "$CLAUDE_SESSION_ID" ] || die "no parent uuid"
which maw rtk bun tmux || die "missing tools"
ToolSearch select:TeamCreate,SendMessage,TeamDelete   # load if not in session
```

**Narrate**: "We need tmux (for panes), CLAUDE_SESSION_ID (for the --parent-session-id flag — proves we're a Claude session), and the team-coordination tools loaded."

### Step 1 — `TeamCreate` (lead-side, from Claude)

This is a Claude-tool call, not a shell command:

```
TeamCreate({
  team_name: "demo-team",
  description: "Demo of the team-tile pattern",
  agent_type: "researcher"
})
```

**What happens**: `~/.claude/teams/demo-team/config.json` is written with the lead (you) as the sole initial member.

**Narrate**: "TeamCreate registers the team in the runtime + on disk. **It does NOT spawn any teammates** — only registers the name. Teammates get added by the framework when `Agent({team_name})` is called, OR they're never added (seam #2 from [[55]]: orphans). For our demo, we spawn via `maw tile --cmd` (raw flag invocation), so teammates will be orphans by config — but reachable by name via SendMessage."

### Step 2 — `maw tile 1 --path <repo> --cmd <claude-cmd>` per member (NEW — post maw-js #1837)

For each member, ONE verb does spawn + cd + boot claude.exe:

```bash
CMD="env CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
  $CLAUDE_BIN \
  --agent-id <role>@<team> \
  --agent-name <role> \
  --team-name <team> \
  --agent-color <color> \
  --parent-session-id $CLAUDE_SESSION_ID \
  --model sonnet \
  --dangerously-skip-permissions"

rtk maw tile 1 --path <repo-path> --cmd "$CMD"
```

**Narrate**: "Seven claude.exe flags — the canonical TeamCreate spawn flag set. `--agent-id <role>@<team>` is the routing address (SendMessage sender resolves by this). `--agent-color` flows all the way through to the `<teammate-message color=...>` XML attr (seam: color flag → JSON inbox → XML wire — verified live). The `maw tile --path --cmd` ergonomic shipped in maw-js #1837 — before that we had to call `maw tile N` then `maw run <addr>` per pane."

**Old way** (pre-#1837, kept for archeology): `rtk maw tile N` then per pane `rtk maw run $SESSION:$WINDOW.$i "cd <cwd> && env ... claude.exe ..."`. Two verbs instead of one. The bash had to discover SESSION + WINDOW first and address each pane by `<session>:<window>.<idx>`. Now `--path --cmd` makes it a single verb.

### Step 3 — `tmux select-layout main-vertical` (optional but pretty)

```bash
tmux select-layout main-vertical
```

**Narrate**: "Puts the lead pane (where you're typing) on the left, all the tile panes stacked on the right. Useful when you want to watch the team work while continuing as lead. Apply AFTER all spawns so it tiles everyone evenly."

### Step 4 — Discover addresses for verification (optional)

```bash
SESSION=$(tmux display-message -p '#{session_name}')
WINDOW=$(tmux display-message -p '#{window_index}')
# tile panes are pane indices 1..N (pane 0 is lead)
```

**Narrate**: "The address `50-digger:2.1` reads as session `50-digger`, window `2`, pane `1`. This is the form `maw peek` (and `maw run`) understands. Raw `%97` doesn't work — try `maw run %97` and you'll get '%97 not in local sessions or agents map'."

### Step 5 — (collapsed into step 2 above)

### Step 6 — Wait for boots (8–12s)

```bash
sleep 10
```

**Narrate**: "Claude Code takes a few seconds to boot — env load, model handshake, status bar paint."

### Step 7 — Verify the teammate identity

```bash
rtk maw peek $SESSION:$WINDOW.1
# Status bar should show: @<role>  | cwd  | session-uuid → conversation-id
```

**Narrate**: "If you see `@mother-reader` at the top of the pane content (matching `--agent-name`), the teammate is fully booted. The session UUID is the FRESH session created by the spawn — not the parent."

### Step 8 — `SendMessage` each mission (from Claude)

```
SendMessage({
  to: "<role>",
  summary: "<5-10 word gist>",
  message: "<full mission text>"
})
```

**Narrate**: "The message lands in `~/.claude/teams/<team>/inboxes/<role>.json` as JSON. When the teammate's next turn fires, the Claude Code runtime reads that JSON file and wraps it as `<teammate-message teammate_id=... color=... summary=...>...body...</teammate-message>` injected into the teammate's conversation context. See [[ψ/ralph/55-teammate-message-wire]] for the schema regex extracted from `claude.exe` binary."

### Step 9 — Receive replies (XML wire)

Wait for the teammate to do its work + call `SendMessage` back. The reply arrives in YOUR (lead) context as `<teammate-message>` XML:

```xml
<teammate-message teammate_id="mother-reader" color="magenta" summary="3 patterns found">
1. <pattern>...
2. <pattern>...
3. <pattern>...
</teammate-message>
```

**Narrate**: "Five body shapes empirically observed: verbose markdown, short text ack, JSON `idle_notification`, JSON `shutdown_request`, JSON `shutdown_approved`. All fit the same XML wrapper."

### Step 10 — `SendMessage({type: "shutdown_request"})` to each

```
SendMessage({to: "<role>", message: {type: "shutdown_request"}})
```

**What happens**: Each teammate gets a `<teammate-message>` containing the JSON envelope; they respond with `{"type": "shutdown_approved", "requestId": "..."}`; the framework signals their process to exit cleanly.

**Narrate**: "**Seam #6** (discovered today): `shutdown_approved` reply doesn't always actually kill the process — only signals the framework can stop coordinating. Sometimes the claude.exe lingers as an idle pane. Follow up with `tmux kill-pane` if you want assurance."

### Step 11 — `TeamDelete()` (cleanup the team registry)

```
TeamDelete({})
```

**What happens**: `~/.claude/teams/<team>/` (config + inboxes + tasks) is removed.

**Narrate**: "Don't `rm -rf` directly — the user's safety hook blocks it. TeamDelete is the proper Claude-tool path. For files outside `~/.claude/teams/`, `mv` to `/tmp/<staging>` per fleet convention."

### Step 12 — Pane cleanup

```bash
tmux kill-pane -t $SESSION:$WINDOW.1
tmux kill-pane -t $SESSION:$WINDOW.2
# ... per teammate
```

**Narrate**: "Even after `shutdown_approved`, the panes may still hold idle claude.exe processes. Killing the panes ensures they're really gone."

## The 6-seam summary (from today's live experiment)

| # | Seam | Closed by |
|---|---|---|
| 1 | `/maw-workon` workers ↔ team substrate | proposed `/maw-team-workon` (open) |
| 2 | GitHub issues ↔ teams | proposed `maw team issues` verb (open) |
| 3 | XML render via `<teammate-message>` only flows for receivers with agent-id env | (architectural — by design) |
| 4 | Cross-session boundary is auth, not protocol | mother's `bridge-spawn.ts` (validated) |
| 5 | `maw ls` registry blind to raw-spawn panes | maw-js #1837 P1.8 (maw-ls-visible by default) |
| 6 | `shutdown_approved` ≠ process kill | `tmux kill-pane` follow-up (no proper fix yet) |

## The verb chain (one-liner)

```
maw tile N → tmux select-layout → TeamCreate → maw run × N → SendMessage × N → wait → SendMessage shutdown × N → TeamDelete → tmux kill-pane × N
```

## Reference paths

- [[ψ/lab/buddy-mom-demo/plan.md]] — the original validation experiment (today)
- [[ψ/ralph/49-buddy-team]] — buddy plugin context
- [[ψ/ralph/55-teammate-message-wire]] — wire format + 5-seam visibility
- [[ψ/ralph/56-mother-oracle-team-architect]] — mother's team-architecture authorship
- [[ψ/ralph/scripts/team-tile/team-tile.ts]] — the OLD (raw-tmux-split) script that hit seam #3
- [[~/.claude/skills/team-tile-spawn/]] — the production verb (this demo's prod sibling)
- [[~/.claude/skills/team-talk/SKILL.md]] (mother) — the conversational team wrapper
- maw-js issues #1837 + #1838 — when these land, the verb chain shortens significantly

## Mission templates for the demo

Default 2 missions when running this demo (override with `--mission`):

- `mother-reader` → "Read ψ/lab/boy-method/dna-full-list.md in mother-oracle's repo and reply with 2-3 surprising DNA patterns"
- `buddy-reader` → "Read plugins/buddy/lib.ts in maw-plugin-registry and reply with 2 bullets on buildBuddyPriming's design"

These are the SAME missions used in the original 2026-05-20 validation — so re-running the demo reproduces the original findings (Elza as pure synthesis, Yamada Hisao protecting Thai, buildBuddyPriming's 9 required + 6 optional fields).

## Bonus: what an empty pane looks like before you bootstrap it

```
$ rtk maw tile 3
  ● 50-digger-tile-1 → %102
  ● 50-digger-tile-2 → %103
  ● 50-digger-tile-3 → %104
✓ 3 panes tiled

$ rtk maw peek 50-digger:2.1
   /opt/Code/github.com/Soul-Brews-Studio/digger-oracle.wt-1-buddy-team
nat 💻 m5 agents/1-buddy-team
❯
```

Just a blank zsh prompt sitting in your worktree path. The `cd <repo> && claude.exe <flags>` from `maw run` is what transforms it into a teammate.

ARGUMENTS: $ARGUMENTS