Skip to content

Commit 8a0956c

Browse files
bradygasterclaude
andcommitted
fix(remote): address linked-team review
- squad client list expects the linked team's member files - a linked member's charter is carried in its subagent file; history via squad_state_read only when its authored tool list allows (never widened) - effort overrides come from the project's own config - teamRoot "." is not a linked team in the coordinator rule - init advertises the linked team's cast in Copilot's agent file - the interactive shell reads the linked team's roster Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3299c79 commit 8a0956c

9 files changed

Lines changed: 74 additions & 14 deletions

File tree

‎packages/squad-cli/src/cli/commands/client.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import {
1919
type ClientId,
2020
type ProjectionFile,
2121
} from '@bradygaster/squad-sdk/client';
22-
import { readClientFlag, readConfiguredClients, readUnknownConfiguredClients, syncClients, reportClientResults, parseClients } from '../core/clients.js';
22+
import { linkedTeamDir, readClientFlag, readConfiguredClients, readUnknownConfiguredClients, syncClients, reportClientResults, parseClients } from '../core/clients.js';
2323
import { detectSquadDir } from '../core/detect-squad-dir.js';
2424
import { projectSquadStateMcpSpec, resolveCommittedSquadStateMcpSpec } from '../core/mcp-spec.js';
2525
import { getPackageVersion } from '../core/version.js';
@@ -62,6 +62,8 @@ export async function listClients(dest: string): Promise<ClientListResult> {
6262
root: dest,
6363
mcp: { command: spec.command, args: spec.args },
6464
squadDir: path.relative(dest, squadDir).split(path.sep).join('/') || '.squad',
65+
// A linked team's members are projected too, so they are expected here as well.
66+
...linkedTeamDir(dest),
6567
};
6668

6769
const clients: ClientStatus[] = CLIENT_IDS

‎packages/squad-cli/src/cli/core/clients.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ export function linkedTeamSquadDir(dest: string): string | null {
166166
}
167167

168168
/** `{ teamDir }` when `dest` is linked to a team repository (remote mode), else nothing. */
169-
function linkedTeamDir(dest: string): { teamDir?: string } {
169+
export function linkedTeamDir(dest: string): { teamDir?: string } {
170170
const teamDir = linkedTeamSquadDir(dest);
171171
return teamDir ? { teamDir } : {};
172172
}

‎packages/squad-cli/src/cli/core/init.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -313,12 +313,14 @@ export async function runInit(dest: string, options: RunInitOptions = {}): Promi
313313
}
314314

315315
// A project linked to a team repository (`squad link`, `init --mode remote`) uses that team.
316-
const linkedTeam = linkedTeamSquadDir(dest) !== null;
316+
const linkedTeamDir = linkedTeamSquadDir(dest);
317+
const linkedTeam = linkedTeamDir !== null;
317318

318319
// Build SDK options
319320
const initOptions: InitOptions = {
320321
teamRoot: dest,
321322
linkedTeam,
323+
...(linkedTeamDir ? { linkedTeamDir } : {}),
322324
agentFileRoot,
323325
projectName: path.basename(dest) || 'my-project',
324326
agents: [

‎packages/squad-cli/src/cli/shell/lifecycle.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import path from 'node:path';
1111
import { FSStorageProvider } from '@bradygaster/squad-sdk';
1212
import { resolveStateDir } from '../core/effective-squad-dir.js';
13+
import { linkedTeamSquadDir } from '../core/clients.js';
1314
import { SessionRegistry } from './sessions.js';
1415
import { ShellRenderer } from './render.js';
1516
import type { ShellState, ShellMessage } from './types.js';
@@ -75,8 +76,9 @@ export class ShellLifecycle {
7576
throw err;
7677
}
7778

78-
// Resolve effective state dir (external when externalized)
79-
const squadDir = resolveStateDir(localSquadDir);
79+
// The team's files come from a linked team repository when there is one (remote mode), then
80+
// from external state when externalized. Project-local files (.init-prompt) stay in localSquadDir.
81+
const squadDir = resolveStateDir(linkedTeamSquadDir(this.options.teamRoot) ?? localSquadDir);
8082

8183
const teamPath = path.join(squadDir, 'team.md');
8284
const teamContent = await storage.read(teamPath);

‎packages/squad-sdk/src/client/adapters/claude-members.ts‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,10 +173,22 @@ export function renderClaudeMember(
173173

174174
const charterPath = `${squadDir}/agents/${id}/charter.md`;
175175
const historyPath = `${squadDir}/agents/${id}/history.md`;
176+
// A linked team's files are outside this project, so the charter is carried in this file (it is
177+
// regenerated on every sync). The history is read through squad_state only when the authored tool
178+
// list allows it; the list is never widened.
179+
const canReadState =
180+
!host.tools || host.tools.some((t) => t === `${mcpPrefix}squad_state_read` || t === `${mcpPrefix}*` || t === mcpPrefix.replace(/__$/, ''));
181+
if (linked && !canReadState) {
182+
notes.push(`History not readable (the Tools list has no \`${mcpPrefix}squad_state_read\`; the spawn prompt must carry it)`);
183+
}
176184
const readCharter = linked
177-
? `This project uses a linked team repository, so read your charter and history with \`squad_state_read\` (keys \`agents/${id}/charter.md\` and \`agents/${id}/history.md\`), not from \`${squadDir}/\`. `
185+
? `This project uses a linked team repository. Your charter from it is below. ` +
186+
(canReadState
187+
? `Read your history with \`squad_state_read\` (key \`agents/${id}/history.md\`), not from \`${squadDir}/\`. `
188+
: `Your history is not available to you here: rely on the spawn prompt. `)
178189
: `Before you start, read your charter at \`${charterPath}\` and your history at \`${historyPath}\`. ` +
179190
`If the spawn prompt gives a TEAM ROOT, resolve these paths under it instead. `;
191+
const linkedCharter = linked ? `\n## Your charter (linked team repository)\n\n${charter.replace(/\r\n?/g, '\n').trim()}\n` : '';
180192
const notesBlock =
181193
notes.length > 0
182194
? `\n<!-- Charter preferences not projected to Claude Code: ${notes.join('; ').replace(/--/g, '- -')}. -->\n`
@@ -189,7 +201,8 @@ export function renderClaudeMember(
189201
readCharter +
190202
`Your charter is authoritative: follow its responsibilities and boundaries, and the task in the spawn prompt.\n\n` +
191203
`Squad dispatches specialists only from the coordinator: do not spawn subagents of your own. ` +
192-
`Read and write shared team state through the \`squad_state\` MCP tools (\`${mcpPrefix}*\`) when they are available.\n`
204+
`Read and write shared team state through the \`squad_state\` MCP tools (\`${mcpPrefix}*\`) when they are available.\n` +
205+
linkedCharter
193206
);
194207
}
195208

@@ -210,7 +223,8 @@ export function projectClaudeMembers(
210223
const agentsAbs = path.join(squadAbs, 'agents');
211224
const routing = readRouting(squadAbs);
212225
const ids = memberIds(agentsAbs);
213-
const effortConfig = readEffortConfig(squadAbs);
226+
// Effort overrides are this project's own settings, even when the team is linked.
227+
const effortConfig = readEffortConfig(path.resolve(ctx.root, squadDir));
214228
const files: ProjectionFile[] = [];
215229
for (const id of ids) {
216230
let charter: string;

‎packages/squad-sdk/src/client/adapters/coordinator.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep
124124
- **Phase 2 (create).** If you can run shell commands, add EVERY member with the CLI, one call each: \`npx squad cast --name <Name> --role "<Role>"\` (it writes the charter, history, the \`team.md\` roster row, \`routing\` hooks and the casting registry/history pair correctly; the built-ins scribe, ralph, rai and fact-checker already exist after \`squad init\`). Then write/adjust \`${S}/routing.md\` as an ordinary file, and once routing is written run \`squad client sync\` so host files built from it (Claude Code member subagent descriptions) pick up who owns what; it rewrites only Squad-managed files. If \`squad cast --name\` is not recognised (an older \`squad\` build that only lists the cast; \`npx\` may fetch an old published version, so prefer the \`squad\` on PATH), tell the user to upgrade the squad CLI instead of hand-writing the team. NEVER hand-write or edit anything under \`${S}/casting/\` (\`registry.json\`, \`history.json\`, \`registry-history.commit.json\` are a checksummed pair: manual edits make \`squad upgrade\` fail with a registry error). If you cannot run shell commands, write \`team.md\` (a markdown table with \`Name\`, \`Role\`, \`Charter\`, \`Status\` columns; the Coordinator row stays separate), \`${S}/agents/<lowercase-name>/charter.md\` and \`history.md\` as ordinary files, leave \`${S}/casting/\` untouched and tell the user to run \`squad cast --name <Name> --role "<Role>"\` for each member to register them.
125125
- **After casting**, STOP and report the roster unless the user's request also asked for work (setting up the team is not a request to build anything).
126126
- **Scratch space.** Use \`${S}/scratch/\` (inside the workspace) for temporary files; never write outside the workspace directory (hosts reject external-directory access).
127-
1. **Load team context first.** Read \`${S}/team.md\` (roster), \`${S}/routing.md\` (who owns what), \`${S}/decisions.md\` and the decisions inbox before routing anything. Cache them for the session; re-read only when a state change was announced. **Linked team:** when \`${S}/config.json\` sets \`teamRoot\`, the project uses a team repository: team files (\`team.md\`, \`routing.md\`, charters, decisions) live there, so read them with \`squad_state_read\` / \`squad_state_list\` (which serve that team), never from \`${S}/\` directly, and never create a local roster.
127+
1. **Load team context first.** Read \`${S}/team.md\` (roster), \`${S}/routing.md\` (who owns what), \`${S}/decisions.md\` and the decisions inbox before routing anything. Cache them for the session; re-read only when a state change was announced. **Linked team:** when \`${S}/config.json\` sets \`teamRoot\` to a path other than \`.\` (\`.\` means no linked team), the project uses a team repository: team files (\`team.md\`, \`routing.md\`, charters, decisions) live there, so read them with \`squad_state_read\` / \`squad_state_list\` (which serve that team), never from \`${S}/\` directly, and never create a local roster.
128128
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.
129129
3. **Spawn specialists with full context.** Each specialist prompt must include: the member's charter (\`${S}/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.
130130
4. **Mutable state goes through the \`squad_state\` MCP server** (backend). Use \`squad_state_read\`, \`squad_state_list\`, \`squad_state_write\`, \`squad_state_append\`, \`squad_state_delete\` for runtime state (decisions inbox, agent history, logs, sessions, scratch) and \`squad_decide\` to record decisions. Never edit those files directly when the MCP backend is available. **Static team config is the exception:** \`team.md\`, \`routing.md\`, \`config.json\`, charters (\`${S}/agents/<name>/charter.md\`), templates and skills are NOT mutable state; the state tools reject writes to them, so create and edit them as ordinary files (\`squad_state_read\` / \`squad_state_list\` can still read them). **Tool names are host-prefixed:** hosts expose these tools as e.g. \`mcp__squad_state__squad_state_read\` (Claude Code), \`squad_state_squad_state_read\` (opencode) or \`@squad_state/squad_state_read\` (Kiro); always call the name actually present in your tool list. **Files vs directories:** \`squad_state_read\` takes a FILE key (e.g. \`decisions.md\`, \`agents/dallas/history.md\`); for a directory (\`identity\`, \`templates\`, \`decisions/inbox\`, \`agents\`) call \`squad_state_list\` instead, never read it (that fails with EISDIR).

‎packages/squad-sdk/src/config/init.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,8 @@ export interface InitOptions {
132132
* built-ins' policies), which live in that repository. Project-local state directories stay.
133133
*/
134134
linkedTeam?: boolean;
135+
/** The linked team's squad directory (with `linkedTeam`): its cast is advertised in the agent file. */
136+
linkedTeamDir?: string;
135137
/** Project name */
136138
projectName: string;
137139
/** Project description (optional) */
@@ -1487,7 +1489,7 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre
14871489
createdFiles.push(toRelativePath(agentFile));
14881490
// Advertise the (possibly still empty) cast to outer coordinators (#1608).
14891491
try {
1490-
syncTeamCapabilities({ squadDir, agentFile, storage });
1492+
syncTeamCapabilities({ squadDir: (options.linkedTeam && options.linkedTeamDir) || squadDir, agentFile, storage });
14911493
} catch (error) {
14921494
warnings.push(
14931495
`Could not refresh squad.agent.md team capabilities: ${

‎plugins/squad/agents/squad.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep
1313
## Core protocol (host-agnostic)
1414

1515
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.
16-
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. **Linked team:** when `.squad/config.json` sets `teamRoot`, the project uses a team repository: team files (`team.md`, `routing.md`, charters, decisions) live there, so read them with `squad_state_read` / `squad_state_list` (which serve that team), never from `.squad/` directly, and never create a local roster.
16+
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. **Linked team:** when `.squad/config.json` sets `teamRoot` to a path other than `.` (`.` means no linked team), the project uses a team repository: team files (`team.md`, `routing.md`, charters, decisions) live there, so read them with `squad_state_read` / `squad_state_list` (which serve that team), never from `.squad/` directly, and never create a local roster.
1717
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.
1818
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.
1919
4. **Mutable state goes through the `squad_state` MCP server** (backend). Use `squad_state_read`, `squad_state_list`, `squad_state_write`, `squad_state_append`, `squad_state_delete` for runtime state (decisions inbox, agent history, logs, sessions, scratch) and `squad_decide` to record decisions. Never edit those files directly when the MCP backend is available. **Static team config is the exception:** `team.md`, `routing.md`, `config.json`, charters (`.squad/agents/<name>/charter.md`), templates and skills are NOT mutable state; the state tools reject writes to them, so create and edit them as ordinary files (`squad_state_read` / `squad_state_list` can still read them). **Tool names are host-prefixed:** hosts expose these tools as e.g. `mcp__squad_state__squad_state_read` (Claude Code), `squad_state_squad_state_read` (opencode) or `@squad_state/squad_state_read` (Kiro); always call the name actually present in your tool list. **Files vs directories:** `squad_state_read` takes a FILE key (e.g. `decisions.md`, `agents/dallas/history.md`); for a directory (`identity`, `templates`, `decisions/inbox`, `agents`) call `squad_state_list` instead, never read it (that fails with EISDIR).

0 commit comments

Comments
 (0)