docs: add user-facing documentation for state backends#996
Conversation
Adds comprehensive docs for the git-notes, orphan-branch, and worktree state backends covering configuration, usage, comparison, SDK API, security hardening, and inspection commands. Closes #995 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a new user-facing Starlight docs page describing Squad’s Git-native state backends (worktree, git-notes, orphan-branch), including configuration, inspection commands, SDK usage, and security hardening notes.
Changes:
- Introduces
state-backends.mdfeature documentation covering backend behavior, tradeoffs, and configuration priority/fallback. - Documents inspection/sharing commands for git-notes and orphan-branch backends plus the
resolveStateBackend()/StateBackendSDK API. - Adds a changeset marking this documentation update as a
@bradygaster/squad-clipatch.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/src/content/docs/features/state-backends.md | New comprehensive documentation page for state backends, configuration, inspection, SDK API, and security notes. |
| .changeset/docs-state-backends.md | Changeset to publish the docs update as a patch release for @bradygaster/squad-cli. |
| ### CLI Flag (per-invocation) | ||
|
|
||
| Pass `--state-backend` to any squad command: | ||
|
|
||
| ```bash | ||
| squad watch --state-backend git-notes | ||
| squad watch --state-backend orphan | ||
| squad watch --state-backend worktree | ||
| ``` |
There was a problem hiding this comment.
--state-backend is documented here as working with “any squad command”, but the CLI currently only parses/accepts this flag for the watch/triage command path. Please narrow the wording (or list the supported commands) so readers don’t try it with other subcommands and get unexpected behavior.
| | Appears in PRs | Yes (if committed) | No | No | | ||
| | Human-readable on disk | ✅ Files | ❌ JSON blob | ⚠️ Via `git show` | | ||
| | Git history | Via normal commits | Per-note | Per-branch commits | | ||
| | Branch-switch safe | ❌ (if uncommitted) | ✅ | ✅ | |
There was a problem hiding this comment.
The “Branch-switch safe” row marks Git Notes as ✅, but earlier the Git Notes section notes state is per-commit and switching commits loses note context. Consider changing this cell to
| | Branch-switch safe | ❌ (if uncommitted) | ✅ | ✅ | | |
| | Branch-switch safe | ❌ (if uncommitted) | ⚠️ | ✅ | |
|
|
||
| - State backends are **opt-in** — the default is `worktree` (no behavior change) | ||
| - All backends implement the same interface — agents don't know or care which backend is active | ||
| - The `external` backend type exists as a stub for future external storage (see [External State](./external-state)) |
There was a problem hiding this comment.
Relative links in docs/src/content/docs/features/ typically include the .md suffix (e.g., ./routing.md). For consistency (and to avoid any build/link-checker surprises), consider changing [External State](./external-state) to [External State](./external-state.md).
| - The `external` backend type exists as a stub for future external storage (see [External State](./external-state)) | |
| - The `external` backend type exists as a stub for future external storage (see [External State](./external-state.md)) |
|
@copilot apply changes based on the comments in this thread |
Agent-Logs-Url: https://github.com/bradygaster/squad/sessions/f521e322-ed1a-4c87-af67-32ebfa106315 Co-authored-by: bradygaster <41929050+bradygaster@users.noreply.github.com>
Implemented in |
Extend StateBackend interface with delete() and append() methods. Implement for all three backends (worktree, git-notes, orphan). Add SquadStateContext and resolveSquadState() factory to the resolution module so any command can resolve the configured backend once at entry. Add comprehensive docs for state backends feature. This is Phase 1 of making state backends squad-wide (not just watch). Individual CLI commands will be migrated to use SquadStateContext in follow-up PRs. 17 new tests (60 total for state-backend). Closes #996 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds comprehensive docs for the git-notes, orphan-branch, and worktree state backends.
What's included
Follows the existing Astro Starlight doc pattern (see external-state.md, storage-provider.md).
Closes #995