From 227125d1f4401a92202db18987960ca856035a41 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Fri, 10 Apr 2026 07:28:38 -0700 Subject: [PATCH] docs: optimize personal squad docs for git-first usage Closes #937 - Add prominent 'Git is mandatory' warning at the top highlighting data loss risks - Expand Tips section with clear git-first workflow guidance - Emphasize commits as insurance policy for team state - Add concrete examples of when state is lost without version control - Strengthen backup warnings for personal squad directory Changes focus on making the git-first requirement unmissable and actionable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/guide/personal-squad.md | 24 ++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/docs/src/content/docs/guide/personal-squad.md b/docs/src/content/docs/guide/personal-squad.md index 36f4e1676..5f71faf3a 100644 --- a/docs/src/content/docs/guide/personal-squad.md +++ b/docs/src/content/docs/guide/personal-squad.md @@ -2,6 +2,9 @@ > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. +:::tip[Git helps protect your project state] +We strongly recommend using git to version-control your project `.squad/` directory. Every session writes to it — decisions, logs, orchestration history. Agent charters, skills, and casting histories live in your personal squad directory (not committed to projects). Without version control, context window resets, crashes, or accidental deletions could be unrecoverable. If git isn't an option, regular manual backups to external storage or cloud sync can help protect your work. +::: **Try this:** ```bash @@ -310,11 +313,26 @@ We're building in the open. If something feels off, [open an issue](https://gith ## Tips -- **Start with one project.** Get comfortable with the personal squad on one repo before connecting others. The value compounds, but so does confusion if something's misconfigured. -- **Commit project `.squad/` but not personal squad directory.** The project-local state (decisions, logs) belongs in version control. Your global identity is personal — keep it out of repos. +- **Git-first workflow is strongly recommended.** Commit your project `.squad/` directory to git after any session. Without version control: + - Session state could be lost on crashes, context resets, or machine reboots + - Project-local decisions and logs are at risk + - Accidental deletions may be unrecoverable + - Cross-project context could vanish + + Think of git as your insurance policy for your project's local state. It's a good habit: after a session ends, run `git add .squad/ && git commit -m "squad: project state"`. (Agent histories, skills, and team identity are stored in your personal squad directory — not in project repos.) + +- **Commit project `.squad/` but not personal squad directory.** The project-local state (decisions, logs) belongs in version control. Your global identity (agents, skills, casting) is personal — keep it out of repos. + ```bash + # DO THIS + git add .squad/ + git commit -m "squad: project state" + + # DON'T commit your personal squad directory (~/.config/squad/ or similar) — it's machine-specific + ``` + - **Check status anytime.** `squad status` shows your global squad directory and which projects are connected. - **Skills are the payoff.** The more projects you work across, the more skills accumulate. After a month, your agents have a real knowledge base tailored to how *you* build software. -- **It's just files.** Your personal squad directory is a folder on your machine. You can browse it, edit it, back it up, copy it to another machine manually. No magic, no cloud, no lock-in. +- **It's just files.** Your personal squad directory is a folder on your machine. You can browse it, edit it, back it up, copy it to another machine manually. No magic, no cloud, no lock-in. But **always back up or version-control your `.squad/` state**. - **Global install matters.** `npm install -g @bradygaster/squad-cli` gives you the `squad` command everywhere. Without it, you'd need `npx` in each project. Global CLI + global squad = full portability. ---