PRD: Remove .squad/ from version control before v1.0

PRD: Remove `.squad/` from version control before v1.0

Author: Brady Gaster
Status: Draft
Target: v0.10.0 (release after v0.9.0, giving one full release cycle for migration)

Problem statement

The .squad/ directory is currently tracked in version control. Since SDK mode (squad.config.ts + squad build) generates .squad/ as build output, tracking it creates several problems:

Merge conflicts on append-only files (decisions.md, history.md) across branches
Dirty working trees when agents work on multiple branches simultaneously
CI noise from .squad/ state changes polluting diffs
Privacy concerns with agent history and session logs in public repos
Conceptual confusion — .squad/ is runtime state, not source code

Current state

128 tracked files, ~889 KB across agents, templates, casting, identity, skills
58 agent files (charters + histories) — the bulk
6 CI workflows reference .squad/team.md for label sync, triage, heartbeat
112 product source files in packages/ reference .squad/ paths
.gitattributes has union merge drivers for .squad/ append-only files
SDK mode already treats .squad/ as generated output from squad.config.ts

Proposed approach

Phase 1: Preparation (v0.9.0 release cycle)

Document the migration path in release notes and docs
Add squad export command to export current .squad/ state (charters, history, decisions) to a portable format
Publish the "Squad squad" (this repo's team) somewhere public so community can reference it
Update squad init to generate .squad/ locally (already does this)
Ensure squad build fully regenerates .squad/ from squad.config.ts
Add .squad/ to .gitignore template used by squad init
Announce deprecation in v0.9.0 release notes

Phase 2: Removal (v0.10.0)

Add .squad/ to .gitignore in this repo
Run git rm -r --cached .squad/ to untrack (files stay on disk)
Update CI workflows to run squad build before reading .squad/team.md
- squad-heartbeat.yml — add squad build step
- squad-issue-assign.yml — add squad build step
- squad-triage.yml — add squad build step
- sync-squad-labels.yml — add squad build step
- squad-preview.yml — add squad build step
- squad-promote.yml — add squad build step
Remove .gitattributes union merge drivers for .squad/ paths
Update docs to reflect that .squad/ is local-only
Update squad init docs to mention .gitignore setup

Phase 3: Validation

Verify fresh clone + npm install + squad build produces working .squad/
Verify all CI workflows pass with build step
Verify squad init on a new project creates .squad/ correctly
Test the full issue -> branch -> PR -> merge lifecycle without tracked .squad/

Migration path for users

Users who have existing .squad/ directories tracked in their repos:

Run squad export to save current team state
Add .squad/ to .gitignore
Run git rm -r --cached .squad/
Commit
Team state persists locally; squad build regenerates from squad.config.ts

Users without SDK mode (squad.config.ts) will need to either:

Adopt SDK mode first (squad init --sdk)
Or keep .squad/ tracked (opt-in, not the default)

Risks

Breaking change for users who depend on .squad/ being in their repo
CI workflows need updating — if missed, label routing breaks on fresh clones
History loss — agent history.md files won't persist across clones (mitigated by squad export)

Timeline

v0.9.0 (this weekend): Announce plan, begin Phase 1 prep
v0.10.0 (next release after v0.9.0): Execute Phase 2 removal
v1.0: .squad/ is fully local-only, generated by squad build

🏗️ Squad Triage — Flight (Lead)

Issue: #498 — PRD: Remove .squad/ from version control before v1.0
Assigned to: FIDO (Quality Owner)
Reason: Issue relates to testing/quality work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

Flight (Lead) → label: squad:flight
Procedures (Prompt Engineer) → label: squad:procedures
EECOM (Core Dev) → label: squad:eecom
FIDO (Quality Owner) → label: squad:fido
PAO (DevRel) → label: squad:pao
CAPCOM (SDK Expert) → label: squad:capcom
CONTROL (TypeScript Engineer) → label: squad:control
Surgeon (Release Manager) → label: squad:surgeon
Booster (CI/CD Engineer) → label: squad:booster
GNC (Node.js Runtime) → label: squad:gnc
Network (Distribution) → label: squad:network
RETRO (Security) → label: squad:retro
INCO (CLI UX & Visual Design) → label: squad:inco
GUIDO (VS Code Extension) → label: squad:guido
Telemetry (Aspire & Observability) → label: squad:telemetry
VOX (REPL & Interactive Shell) → label: squad:vox
DSKY (TUI Engineer) → label: squad:dsky
Sims (E2E Test Engineer) → label: squad:sims
Handbook (SDK Usability) → label: squad:handbook
Ralph (Work Monitor) → label: squad:ralph
@copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

I am curious how squad skills and lessons learned will work moving forward without these components persisted centrally somewhere. Mostly for the following scenarios:

Cross machine usage - Development on one machine with a squad and then later developing on another machine.
Cross team usage - Human team members sharing squad lessons learned.

Will export/import be the only way to manage this or will there be a longer term memory solution that allows for the squad team to maintain lessons learned in a central way?

chore: audit .squad/ VCS references for removal prep (#498)

docs(audit): VCS removal Phase 1 prep (#498) (#542)

chore(.squad): log session completion — #508/#525/#498 all done

docs(.squad): log mega-session — #508 complete, #525 complete, #498 a…

chore(squad): Phase 1 upstream migration cleanup (#1351)

[Squad] Automate git worktree cleanup after PR merge (#1442)

[Kind Aspire] Documentation and samples (#1427) (#1444)