Problem
When .squad/ is in .gitignore (common when using Squad in a repo you do not own), agent-triggered git checkout commands silently destroy all Squad state files (dashboards, agent history, decisions, orchestration logs).
Root Cause
.squad/ files are untracked. Git does not preserve untracked files during branch switches. Agents that run git checkout <branch> in the main worktree — instead of git worktree add — cause the deletion.
How We Hit This
We used Squad to triage a 78-issue backlog in Azure/azure-cli. Since we cannot commit .squad/ to that repo, we gitignored it. During live validation, an agent ran git checkout fix/ssl-branch in the main worktree. All .squad/ files were wiped — dashboards, agent charters, history, logs. This happened twice in one session.
Suggested Improvements
-
Detect gitignored .squad/ at init — If .squad/ matches a .gitignore rule, warn the user: "⚠️ .squad/ is gitignored. State will not survive branch switches. Consider using --external-state or committing .squad/."
-
Enforce worktree usage in agent prompts — The coordinator already instructs agents to use git worktree add, but there is no enforcement. Consider adding a pre-flight check or a git hook that prevents git checkout when .squad/ is untracked.
-
Support external state directory — For "contributor" scenarios (using Squad in repos you do not own), allow .squad/ state to live outside the repo, e.g. ~/.squad/projects/<repo-name>/. This would be immune to checkout/worktree issues.
-
Auto-backup before risky git ops — Before any branch switch, snapshot .squad/ to a temp location. Restore if files are missing after the operation.
Environment
- Squad v0.9.1
- Copilot CLI
- macOS, Azure/azure-cli repo
.squad/ in .gitignore
Problem
When
.squad/is in.gitignore(common when using Squad in a repo you do not own), agent-triggeredgit checkoutcommands silently destroy all Squad state files (dashboards, agent history, decisions, orchestration logs).Root Cause
.squad/files are untracked. Git does not preserve untracked files during branch switches. Agents that rungit checkout <branch>in the main worktree — instead ofgit worktree add— cause the deletion.How We Hit This
We used Squad to triage a 78-issue backlog in
Azure/azure-cli. Since we cannot commit.squad/to that repo, we gitignored it. During live validation, an agent rangit checkout fix/ssl-branchin the main worktree. All.squad/files were wiped — dashboards, agent charters, history, logs. This happened twice in one session.Suggested Improvements
Detect gitignored⚠️ .squad/ is gitignored. State will not survive branch switches. Consider using
.squad/at init — If.squad/matches a.gitignorerule, warn the user: "--external-stateor committing .squad/."Enforce worktree usage in agent prompts — The coordinator already instructs agents to use
git worktree add, but there is no enforcement. Consider adding a pre-flight check or a git hook that preventsgit checkoutwhen.squad/is untracked.Support external state directory — For "contributor" scenarios (using Squad in repos you do not own), allow
.squad/state to live outside the repo, e.g.~/.squad/projects/<repo-name>/. This would be immune to checkout/worktree issues.Auto-backup before risky git ops — Before any branch switch, snapshot
.squad/to a temp location. Restore if files are missing after the operation.Environment
.squad/in.gitignore