Summary
When new agents are added to `.squad/team.md\ (via \squad cast\ or manual edit), the \.github/agents/squad.agent.md`\ file is NOT updated. This causes the Squad coordinator to be unaware of agents that exist on the team, leading to:
- Invisible agents — the coordinator never routes work to them
- Missing reviews — PR reviews don't include their perspective
- Stale routing — routing summary doesn't reflect actual team structure
Reproduction
- Create a Squad team with initial agents (e.g., 6 agents)
- Add new agents later: `squad cast Riley "Architect"`\
- Observe: `.squad/team.md
\ shows 8 agents, \.github/agents/squad.agent.md`\ still shows 6
- Start a new session — coordinator only knows about the original 6
Real-world impact
In `diberry/microsoft-mcp-doc-generation`:
Root cause
`.github/agents/squad.agent.md\ hardcodes the team roster and routing summary. It's generated once during Squad init but never regenerated when the team changes. \.squad/team.md\ is the source of truth but \squad.agent.md`\ doesn't derive from it.
Expected behavior
When agents are added/removed/renamed in `team.md`:
- `squad.agent.md`\ should auto-regenerate the Team Roster table
- `squad.agent.md`\ should auto-regenerate the Routing Summary based on agent roles
- OR the coordinator should read `team.md
\ at runtime instead of relying on hardcoded roster in \squad.agent.md`\
Suggested fix options
Option A (recommended): During `squad cast\ / \squad release\ / \squad promote\, regenerate the Team Roster and Routing Summary sections of \squad.agent.md\ from \team.md`.
Option B: Add a `squad sync\ command that regenerates \squad.agent.md\ from \team.md`. Run automatically after any team mutation.
Option C: Change the coordinator prompt to read `team.md\ directly instead of hardcoding the roster in \squad.agent.md`. The agent instructions would say "Read .squad/team.md for the current roster" instead of listing agents inline.
Files involved
- `.github/agents/squad.agent.md`\ — Coordinator prompt (hardcoded roster)
- `.squad/team.md`\ — Source of truth (updated by cast/release commands)
- `.squad/routing.md`\ — Routing rules (also potentially stale)
Summary
When new agents are added to `.squad/team.md
\ (via \squad cast\ or manual edit), the \.github/agents/squad.agent.md`\ file is NOT updated. This causes the Squad coordinator to be unaware of agents that exist on the team, leading to:Reproduction
\ shows 8 agents, \.github/agents/squad.agent.md`\ still shows 6Real-world impact
In `diberry/microsoft-mcp-doc-generation`:
\ was updated correctly (commits \374259c\, \6acb8e5\, \045759b`)\ was NEVER updated (last touched at initial Squad setup \69ca6eb`)Root cause
`.github/agents/squad.agent.md
\ hardcodes the team roster and routing summary. It's generated once during Squad init but never regenerated when the team changes. \.squad/team.md\ is the source of truth but \squad.agent.md`\ doesn't derive from it.Expected behavior
When agents are added/removed/renamed in `team.md`:
\ at runtime instead of relying on hardcoded roster in \squad.agent.md`\Suggested fix options
Option A (recommended): During `squad cast
\ / \squad release\ / \squad promote\, regenerate the Team Roster and Routing Summary sections of \squad.agent.md\ from \team.md`.Option B: Add a `squad sync
\ command that regenerates \squad.agent.md\ from \team.md`. Run automatically after any team mutation.Option C: Change the coordinator prompt to read `team.md
\ directly instead of hardcoding the roster in \squad.agent.md`. The agent instructions would say "Read .squad/team.md for the current roster" instead of listing agents inline.Files involved