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

[bradygaster]

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:

1. Run squad export to save current team state
2. Add .squad/ to .gitignore
3. Run git rm -r --cached .squad/
4. Commit
5. 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

[github-actions]

🏗️ 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.

[mlinnen]

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

1. Cross machine usage - Development on one machine with a squad and then later developing on another machine.
2. 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?