Feature: Global SQUAD_HOME for roaming agents across repos

[paulyuk]

🎒 Roaming Squad Agents: Global SQUAD_HOME

Problem

Today, squad agents only resolve from a local .squad/ directory in the current repo. When I move between repos, I lose my squad. I have to either:

• Symlink .squad/ into every repo (fragile)
• Re-init with snap-squad in every repo (copies, drift)
• Reference charters by absolute path (clunky)

Proposal

Add a global squad home fallback so personal agents are always in scope, regardless of which repo I am in.

Option A: Environment variable

export SQUAD_HOME=~/src/dispatch/.squad

Squad CLI checks SQUAD_HOME when no local .squad/ exists.

Option B: Conventional global directory

~/.squad/
  agents/
    triage/charter.md
    review/charter.md

Squad CLI checks ~/.squad/ as a fallback.

Resolution order

1. Repo-local .squad/ (highest priority — team/project-specific agents)
2. Global SQUAD_HOME or ~/.squad/ (personal agents that roam everywhere)

Local agents can override or extend global ones. If a repo has .squad/agents/triage/charter.md, it wins over the global triage agent.

Why this matters

I work across many repos on multiple machines. I have a personal squad of agents I have tuned — triage, review, security, etc. I want them available everywhere without per-repo setup. This is the difference between:

• npm install (local to this project) → repo squad
• npm install -g (available everywhere) → global squad

Integration with snap-squad

snap-squad presets would continue to scaffold repo-local .squad/ directories. The global squad home is complementary — it is the personal baseline that snap-squad repos can extend or override.

Context

This is part of a broader vision for a distributed nervous system architecture where agents, rules, and learnings roam across machines and repos. See: https://github.com/coreai-microsoft/dispatch-insiders/issues/74

---

Incorporate Best of Snap Squad into Squad

Rather than keeping snap-squad as a separate tool, consider folding its best ideas directly into Squad:

1. Presets built into Squad CLI

squad init --preset default     # generalist squad
squad init --preset fast        # rapid POC, ship fast
squad init --preset specialists # deep expertise
squad init --preset my-squad    # custom personal preset

No need for a separate npx snap-squad init. Squad itself knows how to scaffold from presets. Users can publish and share custom presets.

2. Sub-agent routing

The real power of a squad is not just having agents — it is the dispatcher knowing which agent to route to. Squad should support:

• Automatic routing — based on the task, Squad picks the best agent (triage routes to triage agent, code review routes to reviewer, etc.)
• Agent delegation — one agent can hand off sub-tasks to another agent in the squad
• Capability matching — agents declare what they are good at, the router matches tasks to capabilities

# Instead of explicitly picking an agent:
squad run triage "review this PR"

# Squad figures it out:
squad run "review this PR"
# → routes to reviewer agent based on task analysis

3. The unified vision

Today	Proposed
snap-squad scaffolds .squad/	squad init --preset does the same, built-in
Manual agent selection	Smart routing picks the best agent for the task
Agents are siloed	Agents can delegate sub-tasks to each other
Local to one repo	Global SQUAD_HOME + repo-local layering

This makes Squad a complete system: scaffold, roam, route, delegate. One tool, not two.

4. Personal default preset

When I run squad init with no flags, it should use my default preset — not a generic one.

# First time: set my default
squad config set default-preset pauls-squad

# Now every repo I init just works:
squad init
# → uses pauls-squad preset automatically

# Override when needed:
squad init --preset fast

Where does the preset live? Options:

• ~/.squad/presets/pauls-squad/ — local preset directory, synced via dotfiles or git
• GitHub repo — squad init --preset github:paulyuk/my-squad pulls from a repo
• SQUAD_HOME directory — the global squad home IS the default preset. squad init copies from there.

The simplest version: SQUAD_HOME doubles as the default preset source. squad init with no args copies agents from SQUAD_HOME into the repo. No registry, no config file, just "use whatever I have globally."

export SQUAD_HOME=~/src/dispatch/.squad

cd ~/src/new-project
squad init
# → scaffolds .squad/ from ~/src/dispatch/.squad
# → Paul's agents are the default everywhere

[paulyuk]

🎒 PR: SQUAD_HOME + Preset System

PR: #1041

Quick Start — 4 Commands, Any Repo

# 1. Start with a preset (init + apply in one shot)
squad init --preset default

# 2. Customize your agents — make it yours
#    edit .squad/agents/*/charter.md, add/remove agents

# 3. Save as your personal preset
squad preset save my-team

# 4. Any new repo — one command, feels like the default
squad init --preset my-team

What's In the PR

Feature	Description
SQUAD_HOME env var	Roaming squad root (~/.squad/ default) for user-level assets
squad init --preset <name>	Init + apply preset in one command
squad preset list/show/apply/save/init	Full preset lifecycle CLI
Built-in default preset	Ships 5 agents: lead, reviewer, devrel, security, docs
24 tests	Full coverage including round-trip save → apply

Preset Format

~/.squad/presets/<name>/
  preset.json                   # { name, description, agents: [...] }
  agents/<agent>/charter.md     # Standard charter format

Aligned with existing Squad charter structure. Collision policy: skip existing agents by default, --force to overwrite.

cc @bradygaster @paulyuk