Skip to content

feat: wire state backends into all squad operations, not just watch #1003

Closed

Description

@tamirdresher

Problem

The state backend feature (git-notes, orphan-branch, worktree) is currently only wired into the \watch\ command. The
esolveStateBackend()\ function exists in the SDK but is only consumed by \watch/config.ts. All other squad operations (init, agent history reads/writes, decisions, skills) use \FSStorageProvider\ directly.

This means setting \stateBackend: 'git-notes'\ in config.json only affects watch — not the broader squad lifecycle.

Solution (phased)

Phase 1 (this issue) ✅

Phase 2 (follow-up)

  • Migrate \squad init\ to use \SquadStateContext\ when writing initial state files
  • Migrate agent history reads/writes to go through the backend
  • Migrate decisions inbox merge (Scribe) to use the backend

Phase 3 (follow-up)

  • Migrate skills, casting, and remaining modules
  • Add caching layer for git-notes (currently loads full JSON blob on every read)
  • Address concurrency (optimistic retry for git-notes, locking for orphan)

Design decisions

  • Boundary: Bootstrap artifacts (config.json, team.md structure checks) stay on local filesystem. Only mutable squad state flows through the backend.
  • No adapter pattern: We do NOT wrap \StateBackend\ as a \StorageProvider. The interfaces have different semantics (5 vs 24 methods). Instead, commands resolve the backend once and use it directly.
  • Incremental migration: Commands adopt \SquadStateContext\ one at a time in follow-up PRs.

Related: #995 (docs)

Activity

  1. added 14 commits that reference this issue on Apr 18, 2026
    a7c230e
    6311f5a
    82d5117
    2d720f9
    5b12654
    c925120
    525de7d
    d3e5e4b
    8688ca9
    2932646
    cd94d7f
    9edd038
    c1cdb48
    3e81270
  2. added a commit that references this issue on May 3, 2026
    bc86668
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions