I've been testing Personal squads with the new CLI and its not currently a smooth experience. I've prototype some of this and feel like that it works decently but this is just a proposal please feel free to suggest alternatives.

personal squad: multi-team support and linking teams to projects

Summary

This proposal introduces multiple domain-specific personal teams (e.g., frontend-focused, API consulting, quick-fixes), each with its own charter and skills, managed via a new squad personal subcommand. Consult mode and --mode remote and link become one concept --team-root: it resolves a personal team name to a path. Clearer mental model, fewer overlapping commands.

Problem

Several overlapping features created confusion:

1. Three ways to connect a squad: squad consult, squad link, and squad init --mode remote — unclear when to use which
2. Single personal squad limitation: Users often want different squads for different work (frontend vs backend vs quick fixes) but could only have one personal team
3. Consult mode's copy-then-extract model: Copying the entire personal squad, then requiring a manual squad extract step was used to extract the learnings to the personal squad but there is a dual root write in the SDK (see Open Design Question — the old extract step is essentially approach 3, "post-session sync," which maybe necessary if using copilot)
4. Personal squad doesn't go through casting: squad init --global creates a bare scaffold — you don't get a real team
5. Confusing flag naming: The difference between squad init --mode remote and squad link wasn't clear

Solution

Multiple Personal Teams

Users can create multiple named personal teams, each stored directly under ~/.config/squad/teams/{name}/:

~/.config/squad/
├── teams/
│   ├── api-crew/             # IS the squad root (agents/, team.md, decisions.md, skills/, etc.)
│   ├── ui-squad/
│   └── quick-fixes/
└── config.json               # global config, preferences

Each team directory IS the squad structure directly — no nested .squad/ subdirectory. In a project repo, .squad/ exists to namespace squad files alongside your code. In a personal team directory, there are no other files, so the extra nesting is redundant.

Resolver note: resolveSquadPaths() currently appends .squad/ to the root. For personal teams, the resolver needs to recognize it's already pointing at a squad root and skip the extra nesting. This is a small change to packages/squad-sdk/src/resolution.ts.

Each team has its own charter, skills, history, and decisions. No persistent "active team" concept — you choose which team at squad init time.

How this relates to Inheritance (Two Layers)

These are separate concerns:

• teamRoot — where your team identity lives (charters, skills, routing). "Who is on my squad?" Used by consult and team-root modes.
• Upstream (upstream.json) — inherited context from other squads (org-level skills, decisions, wisdom). "What does my org know?" Orthogonal, works with any mode.

Usage Examples

# Create your first personal team (walks through casting)
squad personal add "api-crew"

# Create a second team for UI work
squad personal add "ui-squad"

# See your teams
squad personal teams

# Add a member to a team
squad personal hire "api-crew"

# Consult on someone else's project
cd ~/projects/their-repo
squad init --consult "api-crew"

# Normal project squad (committed, how it works today)
cd ~/projects/my-repo
squad init

# Link to a shared team identity (advanced)
squad init --team-root ../shared-team

Adding teams to projects

squad init                              # normal local squad, everything gets initialized in the project
squad init --consult "api-crew"         # personal team, hidden from git (90% use case)
squad init --consult                    # prompts to pick team if multiple exist
squad init --team-root ../shared-team   # shared/org team, visible (advanced)

The key insight: --consult and --team-root use the same underlying mechanism (both set teamRoot in config.json). Consult adds two bits of sugar:

1. Resolves a personal team name to a path ("api-crew" → ~/.config/squad/teams/api-crew/)
2. Hides .squad/ from git via .git/info/exclude

Unified Architecture

Note: Consult is sugar over Team Root — both set teamRoot in config.json. Consult adds personal team name resolution + git invisibility.

In Consult and Team Root modes:

• Agent identity (charters, skills, casting) lives at the teamRoot
• Runtime state (session logs, orchestration logs) stays in the local project .squad/
• The dual-root resolver handles this split

What Changes

Added Commands

• squad personal add [name] — create a new personal team with casting
• squad personal teams — list personal teams
• squad personal hire [team-name] — add member to personal team
• squad personal remove [team-name] — archive a personal team
• squad init --consult [team-name] — consult mode (sugar over --team-root + git invisibility)
• squad init --team-root <path> — link to external team identity

Removed Commands

• squad consult — replaced by squad init --consult
• squad extract — no longer needed (remote mode handles write paths)
• squad link — replaced by squad init --team-root <path>
• squad init --mode remote — replaced by squad init --team-root <path>
• squad init --global — replaced by squad personal add

Removed Config

• sourceSquad field — no longer needed (teamRoot handles this) (depends on outcome of Open Design Question

⚠️ Open Design Question: Dual-Root Agent Write Paths

The SDK's resolveSquadPaths() (in packages/squad-sdk/src/resolution.ts) returns two paths:

• projectDir — local .squad/ for session state (logs, orchestration)
• teamDir — remote identity root (charters, history, decisions, skills)

This works in SDK mode (Node.js code writes to the correct path programmatically). But when agents are spawned via Copilot's task tool, they receive a single TEAM_ROOT in their prompt and write everything relative to it. There's no dual-root awareness in the agent prompt template today.

The problem: In consult mode (teamRoot = ~/.squad/), the agent needs to write history and decisions to the personal squad (teamDir) but session logs to the local project (projectDir). With one root, it can't do both correctly.

Possible approaches:

1. Two roots in spawn prompt — pass both TEAM_ROOT (identity) and PROJECT_ROOT (session state), with clear guidance on which files go where
2. Coordinator-managed routing — coordinator tells each agent exactly which paths to write to, rather than a generic root
3. Post-session sync — agents write everything to one root, a post-session step moves files to the correct locations. ⚠️ This is essentially the old squad extract model we're trying to eliminate — if we pick this approach, we haven't actually simplified anything.