Squad Integration

Rally integrates with the Squad SDK to enable AI development teams to work across multiple projects. This integration uses consult mode to make your personal Squad available to any dispatch worktree.

How Rally Uses Squad SDK

Rally imports key functions from @bradygaster/squad-sdk:

• initSquad — Creates a new squad with specified agents/roles
• setupConsultMode — Configures a worktree to consult an external squad
• extractLearnings — Retrieves learnings from completed work
• getPersonalSquadRoot — Returns the path to the personal squad (~/.rally/squad)
• isConsultMode — Checks if a directory is in consult mode

Personal Squad

Your personal squad is a Squad instance stored in ~/.rally/squad that follows you across all dispatches. It’s created once and reused for every issue and PR you work on.

Core roles (always included):

• 🏗️ Lead — Scope, decisions, code review
• 📋 Scribe — Memory, decisions, session logs

Optional roles you can add:

• Developer, Frontend, Backend, Tester, DevOps, Docs, Security

Rally prompts you to create a personal squad on first dispatch if one doesn’t exist.

Consult Mode

Consult mode links a worktree to your personal squad without moving or copying files. Instead of creating a squad inside each worktree, Rally sets up a .squad/config.json that points to your personal squad.

How It Works

When dispatching an issue or PR, Rally calls setupConsultMode():

setupConsultMode({
  projectRoot: worktreePath,              // e.g., .worktrees/issue-123/
  personalSquadRoot: getPersonalSquadRoot(), // ~/.rally/squad
  projectName: 'owner-repo',              // Derived from repo name
});

This creates .squad/config.json in the worktree:

{
  "consultMode": true,
  "personalSquadRoot": "/home/user/.rally/squad",
  "projectName": "owner-repo"
}

Now when Copilot CLI runs in that worktree, the Squad SDK detects consult mode and loads agents from your personal squad instead of the local directory.

Dispatch Flow

1. Validate inputs — Check repo is onboarded, issue/PR number is valid
2. Create worktree — git worktree add .worktrees/issue-123 rally/issue-123
3. Setup consult mode — Write .squad/config.json pointing to personal squad
4. Launch Copilot — Start AI session in the worktree
5. Register dispatch — Track in ~/rally/active/dispatches.yaml

If the personal squad doesn’t exist, Rally throws PersonalSquadNotFoundError and prompts the user to create it interactively.

Extracting Learnings

After work is completed, Rally can extract learnings from the worktree to feed back into the squad knowledge base:

const learnings = await extractLearnings(worktreePath);

This is typically done before merging a PR or closing an issue, capturing insights about code patterns, architecture decisions, or project conventions.

Configuration

Consult mode configuration is stored in .squad/config.json within each worktree:

Field	Description
consultMode	Always true for Rally worktrees
personalSquadRoot	Absolute path to ~/.rally/squad
projectName	Repository identifier (e.g., owner-repo)

This file is auto-generated by Rally and should not be edited manually.

Why Consult Mode?

Without consult mode, you’d need to:

• Copy squad configuration into every worktree
• Manually sync agent changes across all active dispatches
• Duplicate agent prompt files and settings

With consult mode:

• ✅ Single source of truth for your team
• ✅ Update agents once, applies everywhere
• ✅ Lightweight worktrees (just a config file)
• ✅ Easy to switch between personal squad and project-specific squads