Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/claude-init-inline-cast.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@bradygaster/squad-sdk": patch
"@bradygaster/squad-cli": patch
---

The Claude Code coordinator's Init Mode step now names the casting commands itself: `squad cast` for each member (or `node .squad/squad.mjs cast`), then `squad client sync`, and says never to write under `.claude/` directly. In a live run the coordinator skipped loading the init-mode skill, hand-wrote the charters and spent turns fighting Claude Code's write protection on `.claude/agents/`, so the member subagents were never created.
5 changes: 5 additions & 0 deletions .changeset/dashboard-headless-end.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@bradygaster/squad-cli": patch
---

`squad dashboard` shows a headless `claude -p` session as finished when it ends. Without Stop hooks, those sessions write neither `turn_duration` nor `stop_hook_summary`, so the page said "Prompt 1 running" forever; the dashboard now also ends the turn at the `cost-state` record the process writes when it exits.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o
- New `squad client sync` refreshes the configured hosts' files without a full upgrade. Init Mode runs it after writing `routing.md`, so each Claude Code member subagent's description names what the member owns instead of repeating its role (#2456).
- `squad_state_health` and `squad health --json` add `resolvedTeamRoot` (the directory that contains `.squad`) and `resolvedSquadDir` (the squad directory itself). `resolvedTeamDir` keeps its value, the team root, for existing consumers (#2455).
- The Claude coordinator no longer asks Scribe for session or orchestration logs, matching Scribe's charter and the Copilot coordinator (#2454).
- The Claude coordinator's Init Mode step names the casting commands itself (`squad cast` for each member, then `squad client sync`) and says never to write under `.claude/` directly. In a live run the coordinator skipped the init-mode skill and hand-wrote files Claude Code blocks, so member subagents were never created.
- `squad dashboard` shows a headless `claude -p` session as finished when it ends. Without Stop hooks, those sessions never write the records the page used, so it said "Prompt 1 running" forever.
- Copilot output, `.github/agents/squad.agent.md` and the projections for other hosts are unchanged, apart from the portable `squad_state` launch command below, which every host gets.

#### Fixed
Expand Down
9 changes: 9 additions & 0 deletions packages/squad-cli/src/cli/dashboard/sources.ts
Original file line number Diff line number Diff line change
Expand Up @@ -422,6 +422,15 @@ export class ClaudeTranscriptSource implements DashboardSource {
}
return this.skip(`attachment:${at}`);
}
// Written when the Claude Code process exits. Headless (`claude -p`) sessions without Stop hooks
// write neither turn_duration nor stop_hook_summary, so this is their only end-of-turn marker.
if (type === 'cost-state') {
if (!this.idle && this.turn > 0) {
this.idle = true;
out.push({ t, lane: 'coordinator', kind: 'idle', text: `prompt ${this.turn} waiting for input`, extra: { run: this.turn } });
}
return;
}
if (type === 'system') {
const sub = str(m['subtype']);
if (sub === 'stop_hook_summary' || sub === 'turn_duration') {
Expand Down
2 changes: 1 addition & 1 deletion packages/squad-sdk/src/client/adapters/claude-members.ts
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ export function renderClaudeMember(
const notes = [...host.rejected];

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.`);
const description = oneLine(
`${summary}${routed.length > 0 ? ` Owns: ${routed.join('; ')}.` : ''} Spawned by the Squad coordinator.`,
);
Expand Down
2 changes: 1 addition & 1 deletion packages/squad-sdk/src/client/adapters/coordinator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ const ON_DEMAND: readonly OnDemandSection[] = [
skill: 'squad-coordinator-init-mode',
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.`,
},
{
marker: '9. **Ralph mode',
Expand Down
2 changes: 1 addition & 1 deletion plugins/squad/agents/squad.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep

## Core protocol (host-agnostic)

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 `.squad/`). 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 `squad-coordinator-init-mode` skill and follow it before doing anything else.
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 `.squad/`). 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 `squad-coordinator-init-mode` 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 .squad/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 `.squad/routing.md`; then run `squad client sync` (or `node .squad/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.
1. **Load team context first.** Read `.squad/team.md` (roster), `.squad/routing.md` (who owns what), `.squad/decisions.md` and the decisions inbox before routing anything. Cache them for the session; re-read only when a state change was announced.
2. **Route by ownership.** Match the request to the member whose role owns it per `routing.md`. Every work item has exactly ONE accountable owner (others contribute/review). If nobody owns it, ask the user or propose a new member. Named requests ("Dallas, fix X") go to that member.
3. **Spawn specialists with full context.** Each specialist prompt must include: the member's charter (`.squad/agents/<name>/charter.md`), the task with explicit deliverables AND exclusions (no silent scope expansion; approved expansion is routed as separate work), relevant decisions, the working directory, and the `squad_state` usage rules below. Name tasks "<Name>: <what>" (e.g. "Dallas: build server") and never do the specialist's work yourself.
Expand Down
7 changes: 7 additions & 0 deletions test/claude-members.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,13 @@ describe('renderClaudeMember: charter → Claude subagent frontmatter', () => {
expect(fm).toMatchObject({ name: 'dallas', model: 'sonnet', effort: 'high' });
});

it('does not double the period after a role that ends in one', () => {
const md = renderClaudeMember('dallas', charter().replace('# Dallas — Backend Dev', '# Dallas — Backend Dev. Writes APIs.'), [], '.squad', NOTE);
const description = JSON.parse(frontmatter(md).description!);
expect(description).toContain('Writes APIs.');
expect(description).not.toContain('..');
});

it('omits model and effort for auto (charter §6: auto is never a literal override)', () => {
const md = renderClaudeMember('dallas', charter(), [], '.squad', NOTE);
const fm = frontmatter(md);
Expand Down
11 changes: 11 additions & 0 deletions test/claude-skills.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,17 @@ describe('Claude coordinator slimming', () => {
expect(claude).toMatch(/never delegate the loop itself/);
});

it('carries the casting commands inline, so a coordinator that skips the skill still uses the CLI', () => {
// Seen live: the model ignored "load the skill", hand-wrote charters and fought Claude Code's
// write protection on .claude/agents/ instead of running squad cast and squad client sync.
expect(claude).toContain('squad cast --name <Name> --role "<Role>"');
expect(claude).toContain('node .squad/squad.mjs cast');
expect(claude).toContain('squad client sync');
expect(claude).toMatch(/NEVER write or edit files under `\.claude\/` yourself/);
// Other hosts keep the full item; the inline summary is Claude-only.
expect(buildCoordinatorInstructions('kiro')).not.toContain('NEVER write or edit files under `.claude/` yourself');
});

it('moves every item verbatim: the skill bodies match the full digest other hosts load', () => {
const kiro = buildCoordinatorInstructions('kiro');
for (const k of claudeCoordinatorSkills()) {
Expand Down
14 changes: 14 additions & 0 deletions test/dashboard-sources.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,20 @@ describe('Claude transcript source', () => {
expect(JSON.stringify(events)).not.toContain('system-reminder');
});

it('ends a headless session without Stop hooks at its cost-state record', () => {
// `claude -p` with no Stop hooks writes neither stop_hook_summary nor turn_duration; the process
// writes cost-state when it exits. Without it the page said "Prompt 1 running" forever.
const dir = path.join(tmp, 'projects', '-work-demo');
fs.cpSync(path.dirname(SESSION_FILE), dir, { recursive: true });
const file = path.join(dir, `${SESSION}.jsonl`);
const noHooks = fs.readFileSync(file, 'utf8').split('\n').filter((l) => !l.includes('"stop_hook_summary"')).join('\n');
fs.writeFileSync(file, noHooks);
expect(new ClaudeTranscriptSource(file).poll().filter((e) => e.kind === 'idle')).toEqual([]);
fs.writeFileSync(file, `${noHooks.trimEnd()}\n{"type":"cost-state","sessionId":"${SESSION}"}\n`);
const events = new ClaudeTranscriptSource(file).poll();
expect(events.at(-1)).toMatchObject({ lane: 'coordinator', kind: 'idle', extra: { run: 2 } });
});

it('reads appends incrementally, including member files created later', () => {
const dir = path.join(tmp, 'projects', '-work-demo');
fs.cpSync(path.dirname(SESSION_FILE), dir, { recursive: true });
Expand Down
Loading