Suggest roster-aware agent names

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Suggest roster-aware unused identity names during join onboarding (#178)
+
 ## [1.1.1] - 2026-06-25
 
 ### Added

SKILL.md

@@ -35,11 +35,13 @@ After this runs once, `~/.agents/skills/agmsg/` is populated and you can skip St
 ```bash
 ~/.agents/skills/agmsg/scripts/whoami.sh "$(pwd)" <type>
 # type: claude-code, codex, gemini, antigravity, copilot
-# Returns: agent=... / multiple=true ... / suggest=true ... / not_joined=true ...
+# Returns: agent=... / multiple=true ... / suggest=true ... / not_joined=true ...; join-needed paths may include suggested=<n1,n2,...>
 ```
 
 ### Step 2a: If not in a team — join one
 
+If whoami output includes `suggested=`, show those unused roster-aware identity names as options for the agent name. They are advisory; the user may still type a different name.
+
 Ask the user for a team name and agent name, then run:
 
 ```bash

scripts/data/name-pool.txt

@@ -0,0 +1,99 @@
+# Bundled identity-name pool for roster-aware onboarding suggestions.
+# Keep entries lowercase ASCII [a-z0-9-]. These are agent identities, not tool
+# types: prefer names like noether/lovelace over cc/codex.
+ada
+agnesi
+albert
+amalie
+anaximander
+archimedes
+arete
+artin
+astrid
+aurora
+babbage
+banach
+bell
+bernoulli
+boole
+brahe
+cannon
+cantor
+carson
+cartan
+cassini
+ceres
+chandrasekhar
+clarke
+copernicus
+curie
+darwin
+dedekind
+dirac
+easley
+edison
+emmy
+erdos
+euler
+faraday
+fibonacci
+fleming
+franklin
+galileo
+galois
+gauss
+germain
+gosling
+grace
+halley
+hamilton
+hardy
+hawking
+heisenberg
+hilbert
+hopper
+hypatia
+ibn-sina
+joule
+katherine
+kepler
+khayyam
+knuth
+kovalevskaya
+laplace
+leavitt
+leibniz
+lovelace
+margulis
+maxwell
+mendel
+minkowski
+mirzakhani
+newton
+noether
+norton
+ohm
+pasteur
+planck
+poisson
+ramanujan
+riemann
+rosalind
+rubin
+sagan
+shannon
+sonya
+sophie
+tao
+tesla
+thales
+turing
+tycho
+vonneumann
+wiles
+wright
+wu
+yang
+yukawa
+zermelo
+zhukovsky

scripts/drivers/types/antigravity/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> antigravity "$(pwd)"`
   4. Show the result and explain:
 
@@ -63,10 +63,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=antigravity project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=antigravity project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> antigravity "$(pwd)"`

scripts/drivers/types/claude-code/template.md

@@ -21,7 +21,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -30,7 +30,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> claude-code "$(pwd)"`
   4. Show the result and explain:
 
@@ -74,10 +74,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=claude-code project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=claude-code project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> claude-code "$(pwd)"`

scripts/drivers/types/codex/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> codex "$(pwd)"`
   4. Show the result and explain:
 
@@ -68,10 +68,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=codex project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=codex project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> codex "$(pwd)"`

scripts/drivers/types/copilot/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> copilot "$(pwd)"`
   4. Show the result and explain:
 
@@ -63,10 +63,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=copilot project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=copilot project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> copilot "$(pwd)"`

scripts/drivers/types/cursor/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> cursor "$(pwd)"`
   4. Show the result and explain:
 
@@ -63,10 +63,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=cursor project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=cursor project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> cursor "$(pwd)"`

scripts/drivers/types/gemini/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> gemini "$(pwd)"`
   4. Show the result and explain:
 
@@ -63,10 +63,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=gemini project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=gemini project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> gemini "$(pwd)"`

scripts/drivers/types/grok-build/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> grok-build "$(pwd)"`
   4. Show the result and explain:
 
@@ -69,10 +69,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=grok-build project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=grok-build project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> grok-build "$(pwd)"`

scripts/drivers/types/hermes/template.md

@@ -22,7 +22,7 @@ Four possible outputs:
 → Ask the user which agent name to use for this session, then go to **Execute**.
 
 **C) Not in a team:**
-`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`)
+`not_joined=true available_teams=<t1,t2,...>` (or `available_teams=none`), optionally `suggested=<n1,n2,...>`
 → Show the user the available teams from the output, then:
 
   > **First-time setup required.**
@@ -31,7 +31,7 @@ Four possible outputs:
   > - **Agent name**: this agent's identity within the team
 
   1. Ask: "Enter a team name (joins existing or creates new)"
-  2. Ask: "Enter a name for this agent"
+  2. If the output includes `suggested=`, show those unused roster-aware identity names as options. Ask: "Enter a name for this agent"; empty input may use the first suggested name.
   3. **You MUST use join.sh** — run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> hermes "$(pwd)"`
   4. Show the result and explain:
 
@@ -47,10 +47,10 @@ Four possible outputs:
   6. Then check inbox for the newly joined team.
 
 **D) Suggestions for reuse:**
-`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=hermes project=<path> available_teams=<t1,t2,...>`
+`suggest=true agents=<n1,n2,...> teams=<t1,t2,...> type=hermes project=<path> available_teams=<t1,t2,...>`, optionally `suggested=<n1,n2,...>`
 → No exact registration exists for this project, but there are same-type agent names registered elsewhere.
 
-  1. Show the suggested agent names to the user.
+  1. Show the reuse candidates from `agents=` and the unused roster-aware names from `suggested=` (if present).
   2. Ask whether to reuse one of those names or choose a new one.
   3. Ask for the team name to join (existing or new).
   4. Run: `~/.agents/skills/__SKILL_NAME__/scripts/join.sh <team> <agent_name> hermes "$(pwd)"`