Git-based State Backends
Problem
PR #797 implemented Option C (external directory). This issue covers the two git-native approaches from Tamir's blog Part 7b:
Option A: Git Notes (refs/notes/squad)
- Squad state stored in git notes ref, not working tree
- Survives branch switches (ref-based, not file-based)
- Invisible in
git status, git diff, PRs
- Accessed via
git notes --ref=squad
Option B: Orphan Branch (squad-state)
- Dedicated branch with no common ancestor
- State files live there, never merged into main
- Read via
git show squad-state:.squad/team.md
Implementation
- Add
StateBackend interface to squad-sdk resolution.ts
- Implement
GitNotesBackend and OrphanBranchBackend
- Add
--state-backend flag to CLI (values: worktree | external | git-notes | orphan)
- Config in
.squad/config.json: { \"stateBackend\": \"git-notes\" }
- Fallback: if chosen backend fails, warn and fall back to worktree
Blog reference
https://tamirdresher.github.io - Part 7b of the Scaling AI series
Git-based State Backends
Problem
PR #797 implemented Option C (external directory). This issue covers the two git-native approaches from Tamir's blog Part 7b:
Option A: Git Notes (
refs/notes/squad)git status,git diff, PRsgit notes --ref=squadOption B: Orphan Branch (
squad-state)git show squad-state:.squad/team.mdImplementation
StateBackendinterface to squad-sdk resolution.tsGitNotesBackendandOrphanBranchBackend--state-backendflag to CLI (values:worktree|external|git-notes|orphan).squad/config.json:{ \"stateBackend\": \"git-notes\" }Blog reference
https://tamirdresher.github.io - Part 7b of the Scaling AI series