Skip to content

Optimize personal squad docs to encourage git-first usage (prevent data loss) #937

Closed

Description

@diberry

Content request from Brady

"I kind of think we should optimize all the docs on personal squads to encourage people to use git primarily because without it, you will suffer loss."

What this means

Personal squads store state in .squad/ — agent history, decisions, orchestration logs, skills. Without git:

  • Session state is ephemeral (lost on context window reset)
  • No cross-session memory persistence
  • No branch-level isolation of team state
  • No recovery from accidental deletions or bad decisions

Investigation needed

  1. Audit current docs — which pages mention git? Which don't but should?
  2. Identify gaps — where do we assume git without saying so? Where do we describe workflows that silently depend on committed .squad/ state?
  3. Propose minimal doc changes — add git-first guidance with minimal touches (warnings, callouts, a "Why Git?" section)

Acceptance criteria

  • Audit of all docs pages re: git mentions completed
  • List of pages that need git-first callouts
  • Single PR with minimal doc changes that make git usage front-and-center for personal squads
  • Each changed page includes a clear warning about data loss without git

Activity

  1. added 3 commits that reference this issue on Apr 10, 2026
    a3c9339
    4589f27
    227125d
  2. added a commit that references this issue on Apr 12, 2026
    5c4629b
  3. added a commit that references this issue on Apr 21, 2026
    afd83db
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