Repository navigation
fix(claude): first-run fixes from the demo run: inline casting, member descriptions, dashboard end of session - #2484
Conversation
A live headless run skipped loading squad-coordinator-init-mode, hand-wrote charters and tried 15 times to write .claude/agents/*.md, which Claude Code blocks. The Claude stub now names squad cast / squad client sync (or the repository launcher) and forbids writing under .claude/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…criptions Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🟡 Impact Analysis — PR #2484Risk tier: 🟡 MEDIUM 📊 Summary
🎯 Risk Factors
📦 Modules Affectedroot (4 files)
squad-cli (1 file)
squad-sdk (2 files)
tests (3 files)
This report is generated automatically for every PR. See #733 for details. |
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 4 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ❌ | Copilot threads resolved | 1 unresolved Copilot thread(s) — fix and resolve before merging |
| ❌ | CI passing | 1 check(s) still running |
Files Changed (10 files, +57 −3)
| File | +/− |
|---|---|
.changeset/claude-init-inline-cast.md |
+6 −0 |
.changeset/dashboard-headless-end.md |
+5 −0 |
CHANGELOG.md |
+2 −0 |
packages/squad-cli/src/cli/dashboard/sources.ts |
+9 −0 |
packages/squad-sdk/src/client/adapters/claude-members.ts |
+1 −1 |
packages/squad-sdk/src/client/adapters/coordinator.ts |
+1 −1 |
plugins/squad/agents/squad.md |
+1 −1 |
test/claude-members.test.ts |
+7 −0 |
test/claude-skills.test.ts |
+11 −0 |
test/dashboard-sources.test.ts |
+14 −0 |
Total: +57 −3
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
There was a problem hiding this comment.
🟡 Changes recommended
The advertised commands fail in fresh npx-initialized repositories without a global squad installation because they rely on a local launcher that is not created.
1 open issue
What changed in this PR
This PR makes Claude Code team initialization less dependent on loading a skill by placing casting and synchronization commands directly in the coordinator instructions.
Changes:
- Adds Claude-only guidance to cast members through the CLI, write routing, then sync subagents without directly editing
.claude/. - Prevents duplicate periods in member descriptions.
- Updates the generated plugin coordinator, regression tests, and release notes.
| File | Description |
|---|---|
test/claude-skills.test.ts |
Checks inline commands and Claude-only scope. |
test/claude-members.test.ts |
Covers roles ending in a period. |
plugins/squad/agents/squad.md |
Refreshes generated Init Mode guidance. |
packages/squad-sdk/src/client/adapters/coordinator.ts |
Adds inline casting and synchronization instructions. |
packages/squad-sdk/src/client/adapters/claude-members.ts |
Normalizes trailing role punctuation. |
CHANGELOG.md |
Documents the initialization guidance change. |
.changeset/claude-init-inline-cast.md |
Records SDK and CLI patch release notes. |
Review effort: Balanced (auto)
| title: 'Init Mode and casting', | ||
| description: 'Squad coordinator only: Init Mode, proposing and casting a new team. Load when team.md is missing or has an empty roster, or when asked to set up or cast a team.', | ||
| stub: (k, S) => `0. **Init Mode (only when there is truly no team).** Decide this with \`squad_state_read\` of \`team.md\` (or \`squad_state_list\`), NEVER with glob/grep/search tools (they skip dot-directories like \`${S}/\`). If \`team.md\` is readable and lists members, a team exists: NEVER overwrite or re-cast it. Only if \`team.md\` does not exist or has an empty roster, load the \`${k}\` skill and follow it before doing anything else.`, | ||
| stub: (k, S) => `0. **Init Mode (only when there is truly no team).** Decide this with \`squad_state_read\` of \`team.md\` (or \`squad_state_list\`), NEVER with glob/grep/search tools (they skip dot-directories like \`${S}/\`). If \`team.md\` is readable and lists members, a team exists: NEVER overwrite or re-cast it. Only if \`team.md\` does not exist or has an empty roster, load the \`${k}\` skill with the \`Skill\` tool and follow it before doing anything else. Its essentials: cast EVERY member with Bash, one call each, \`squad cast --name <Name> --role "<Role>"\` (if \`squad\` is not on PATH, \`node ${S}/squad.mjs cast --name <Name> --role "<Role>"\`), where the role is a short title such as "Tester" or "Node.js Engineer", not a description; the CLI writes the charter, history, roster row and casting records; then write \`${S}/routing.md\`; then run \`squad client sync\` (or \`node ${S}/squad.mjs client sync\`), which writes each member's subagent in \`.claude/agents/\`. NEVER write or edit files under \`.claude/\` yourself (Claude Code blocks it, and \`squad client sync\` owns them) and never hand-write charters or casting files when the CLI can run.`, |
claude -p without Stop hooks writes neither turn_duration nor stop_hook_summary, so the page showed 'Prompt 1 running' after the session ended. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
||
| const routed = routing.filter((r) => r.routeTo === id).map((r) => r.workType); | ||
| const summary = parsed.identity.purpose ?? (role ? `${name}, ${role}.` : `${name}, Squad team member.`); | ||
| const summary = parsed.identity.purpose ?? (role ? `${name}, ${role.replace(/[.\s]+$/, '')}.` : `${name}, Squad team member.`); |

Found while recording the Claude Code demo for #2469: a fresh
squad init --client clauderepository, thenclaude -p --agent squad "Cast a small team…".What went wrong
The coordinator's Init Mode item tells the model to "load the
squad-coordinator-init-modeskill and follow it". The model never loaded it. Instead it improvised:.claude/agents/<member>.mdwith Write,cat >andtee. Claude Code blocks writes under.claude/.squad castorsquad client sync(added in fix(claude): refresh members after routing, clearer health dirs, no retired logs, plugin validates clean (#2456, #2455, #2454, #2458) #2471).The member subagents were never created, and it took 54 turns and $1.49.
Fix
Init Mode stub (Claude only). It keeps "load the skill", and now also names the essentials inline:
squad cast --name <Name> --role "<Role>"per member, ornode .squad/squad.mjs cast …whensquadisn't on PATHrouting.mdsquad client sync.claude/The other hosts keep the full item unchanged.
Dashboard.
squad dashboardnow ends a headless session at itscost-staterecord.claude -pwithout Stop hooks (the default) writes neitherturn_durationnorstop_hook_summary, so after the run the page still said "Prompt 1 running". A new test covers it, and checked against the recording session the last event is now "prompt 1 waiting for input".Member descriptions. No double period after a role that ends in one.
Result
The same prompt on a fresh repository:
squad cast×3 →routing.md→squad client sync, and all three member subagents are written. It took 17 turns, 47 s, $0.37.Testing
claude-skills.test.ts: the stub carries the commands, and Kiro's digest doesn't.claude-members.test.ts: no..in the description.agents/squad.mdis regenerated (pinned topreview.4, so no release work).🤖 Generated with Claude Code