diff --git a/docs/src/content/docs/concepts/repo-anatomy.md b/docs/src/content/docs/concepts/repo-anatomy.md new file mode 100644 index 000000000..168b6158e --- /dev/null +++ b/docs/src/content/docs/concepts/repo-anatomy.md @@ -0,0 +1,134 @@ +# Repo Anatomy + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Every Squad-enabled repository has a `.squad/` directory at the root. This page explains what each file and folder does, how they relate to each other, and which ones you should edit vs. leave to the agents. + +--- + +## Try This + +``` +What's in our .squad directory? +``` + +``` +Show me the team's current decisions +``` + +``` +Which skills has the team learned? +``` + +--- + +## Directory Structure + +After running `squad init`, your repo looks like this: + +``` +.squad/ +├── team.md # Team roster and member profiles +├── routing.md # Work routing rules +├── charter.md # Team charter and mission +├── decisions.md # Shared decision log (all agents read this) +├── decisions-archive.md # Archived decisions +├── history.md # Team-wide session history +├── roster.md # Member list with roles +├── ceremonies.md # Team rituals (standup, retro, etc.) +├── config.json # Local configuration +├── agents/ +│ └── {name}/ +│ ├── charter.md # Agent's role, domain, and voice +│ └── history.md # Agent's personal memory +├── skills/ +│ └── {name}/ +│ └── SKILL.md # Learned patterns and tool usage +├── decisions/ +│ └── inbox/ # Pending decision drafts (gitignored) +├── sessions/ # Session logs (gitignored) +├── templates/ # File templates for new squads +└── identity/ # Team identity and wisdom docs +``` + +--- + +## What Each File Does + +### Files You Should Know + +| File | Purpose | Who writes it | You edit? | +|------|---------|---------------|-----------| +| `team.md` | Roster of all agents with roles and capabilities | `squad init` and Scribe | Rarely — add human members here | +| `routing.md` | Rules for which agent handles what | You or Scribe | Yes — tune routing as your team evolves | +| `decisions.md` | Shared rules every agent reads at session start | Scribe (merges from inbox) | Yes — this is your team's law | +| `charter.md` | Team mission and operating principles | `squad init` | Occasionally — when team direction changes | + +### Per-Agent Files + +| File | Purpose | Who writes it | +|------|---------|---------------| +| `agents/{name}/charter.md` | Defines the agent's role, domain expertise, voice, and boundaries | `squad init` or casting | +| `agents/{name}/history.md` | Personal memory — only this agent reads its own | The agent itself | + +Charters are your primary lever for shaping agent behavior. Edit a charter to change how an agent thinks, what it prioritizes, and how it communicates. + +### Skills + +| File | Purpose | Who writes it | +|------|---------|---------------| +| `skills/{name}/SKILL.md` | Reusable pattern with tools, examples, and anti-patterns | Agents (typically Procedures or the agent that learned it) | + +Skills are portable. You can copy a skill from one repo to another, and any Squad team can use it. They follow a standard template with Context, Patterns, Examples, and Anti-Patterns sections. + +--- + +## The Decision Lifecycle + +Decisions flow through a specific path: + +``` +Agent drafts note → .squad/decisions/inbox/{agent}-{slug}.md + ↓ +Scribe reviews and merges → .squad/decisions.md + ↓ +All agents read decisions.md at session start + ↓ +Old decisions archived → .squad/decisions-archive.md +``` + +The `inbox/` directory is gitignored — it's a staging area for drafts that haven't been reviewed yet. Once Scribe merges a decision, it becomes team law. + +--- + +## What Gets Checked In vs. Gitignored + +| Checked in | Gitignored | +|------------|------------| +| `team.md`, `routing.md`, `charter.md` | `decisions/inbox/` (draft staging) | +| `decisions.md`, `decisions-archive.md` | `sessions/` (session logs) | +| `agents/{name}/charter.md` and `history.md` | `config.json` (local machine paths) | +| `skills/{name}/SKILL.md` | `*.local.json` (local secrets and config) | +| `ceremonies.md`, `templates/` | `orchestration-log/`, `log/` | + +**Rule of thumb:** If it shapes agent behavior, check it in. If it contains local paths, secrets, or transient state, gitignore it. + +--- + +## Relationship to Other Config + +Squad also uses files outside `.squad/`: + +| File | Purpose | +|------|---------| +| `squad.config.ts` | SDK configuration (when using `squad init --sdk`) | +| `.github/agents/squad.agent.md` | GitHub Copilot Coding Agent coordinator prompt | +| `.github/copilot-instructions.md` | Global Copilot instructions (Squad adds team context here) | + +--- + +## Next Steps + +- [Team Setup](../features/team-setup) — configure your team roster +- [Memory and Knowledge](memory-and-knowledge) — how the three memory layers interact +- [Skills](../features/skills) — how to create and manage skills diff --git a/docs/src/content/docs/concepts/session-model.md b/docs/src/content/docs/concepts/session-model.md new file mode 100644 index 000000000..ac5daefd6 --- /dev/null +++ b/docs/src/content/docs/concepts/session-model.md @@ -0,0 +1,115 @@ +# Session Model + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Squad sessions are the container for everything you do with your team. Understanding the session model helps you work confidently across tools, recover from interruptions, and know exactly where your context lives. + +--- + +## Try This + +``` +What did we work on last session? +``` + +``` +Can you pick up where we left off? +``` + +``` +Show me the decisions from today's sessions +``` + +--- + +## What Is a Session? + +A session starts when you open a conversation with Squad (CLI, VS Code, or Copilot Chat) and ends when you close it. During that time: + +- **Agents remember context** — your current task, decisions made, files changed +- **Memory accumulates** — skills learned, conventions captured, decisions recorded +- **Work products persist** — commits, branches, PRs, and `.squad/` file changes survive the session + +The session itself is ephemeral. The work it produces is permanent. + +--- + +## Session Boundaries + +| Surface | Session starts | Session ends | +|---------|---------------|--------------| +| CLI (`copilot` or `squad`) | You run the command | You exit (Ctrl+C or `/exit`) | +| VS Code Copilot Chat | You open a chat thread | You close the thread or window | +| Copilot Coding Agent | An issue is assigned | The PR is opened | + +Each surface creates an independent session. Switching from CLI to VS Code starts a **new** session — the agents don't automatically carry over mid-conversation context. + +--- + +## What Survives Between Sessions + +Memory in Squad is layered. Some things persist automatically, others need explicit action: + +| Layer | Persists? | Where | +|-------|-----------|-------| +| **Skills** (learned patterns) | ✅ Always | `.squad/skills/{name}/SKILL.md` | +| **Decisions** (team rules) | ✅ Always | `.squad/decisions.md` | +| **Agent history** (per-agent memory) | ✅ Always | `.squad/agents/{name}/history.md` | +| **Conversation context** | ❌ Session-only | Lives in the chat thread | +| **Uncommitted file changes** | ⚠️ If saved | Local working tree | + +**Key insight:** If an agent learns something important mid-session, it writes it to a skill or decision file. That's what makes it permanent. Conversation context alone doesn't persist. + +--- + +## Resuming Work + +When you start a new session and want to continue previous work: + +``` +Pick up where we left off on the auth refactor +``` + +Squad reads the persisted layers (skills, decisions, history) and reconstructs context. The more your team has written to these layers, the smoother the resume. + +For long-running projects, consider asking your team to checkpoint progress: + +``` +Scribe, log what we've done today before I close out +``` + +--- + +## Crashes and Restarts + +During preview, session crashes and restarts are **expected behavior**. This is normal and not a sign of misconfiguration. When it happens: + +1. Your persisted memory (skills, decisions, history) is safe — it lives in files +2. Uncommitted code changes are safe — they're in your working tree +3. Conversation context is lost — you'll need to re-establish what you were doing + +A quick restart prompt works well: + +``` +I just restarted. We were working on [topic]. What's the current state? +``` + +--- + +## Sessions Across Surfaces + +You can use different surfaces throughout the day without conflict: + +- **Morning:** CLI session for focused coding +- **Midday:** VS Code chat for quick questions +- **Evening:** CLI session to review the day's work + +Each reads the same `.squad/` directory, so decisions and skills are shared. The only thing that doesn't transfer is the live conversation thread. + +--- + +## Next Steps + +- [Memory and Knowledge](memory-and-knowledge) — how the three memory layers work +- [Your First Session](../get-started/first-session) — guided walkthrough +- [Tips and Tricks](../guide/tips-and-tricks) — productivity patterns diff --git a/docs/src/content/docs/get-started/known-limitations.md b/docs/src/content/docs/get-started/known-limitations.md new file mode 100644 index 000000000..2d6c1fe31 --- /dev/null +++ b/docs/src/content/docs/get-started/known-limitations.md @@ -0,0 +1,92 @@ +# Known Limitations + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Squad is in active preview. This page documents current limitations and expected behaviors so you can work confidently and know what to expect. + +--- + +## Stability + +### Session crashes are normal + +During preview, sessions may crash and restart. This is expected behavior — not a sign of misconfiguration. Your work is safe: + +- ✅ Files you've saved are in your working tree +- ✅ Skills, decisions, and history persist in `.squad/` +- ✅ Commits and branches are in Git +- ❌ Conversation context is lost — restart with a brief summary of what you were doing + +### Long sessions may degrade + +Very long sessions (many hours, hundreds of tool calls) can experience slowdowns or context overflow. Consider: + +- Asking Scribe to checkpoint progress before ending a long session +- Starting fresh sessions for new topics +- Keeping per-session scope focused + +--- + +## Tool Approval + +### Copilot requires tool call approval by default + +Without `--yolo` mode, Copilot prompts for approval on every tool call (file reads, git operations, agent spawns). Squad sessions involve many tool calls, so this creates significant friction. + +**Recommendation:** Use `--yolo` mode for Squad sessions: + +```bash +copilot --yolo +``` + +This is the single most impactful change for Squad usability. See [Quick Start](five-minute-start) for setup. + +--- + +## Context and Memory + +### Conversation context doesn't persist across sessions + +When you close a session and start a new one, the live conversation is gone. Agents retain what they wrote to skills, decisions, and history files — but not the conversational back-and-forth. See [Session Model](../concepts/session-model) for details. + +### Agent memory has limits per session + +Each agent reads from its own history file at session start. Very large history files may exceed context limits. The team periodically compacts history during ceremonies. + +--- + +## Multi-Surface + +### Switching tools creates new sessions + +Moving from CLI to VS Code (or vice versa) starts a fresh session. The persisted `.squad/` state is shared, but conversation context does not transfer. This is by design — each surface is independent. + +### VS Code Copilot Chat has shorter context + +VS Code chat threads have a smaller context window than CLI sessions. Complex multi-agent work is more reliable in the CLI. + +--- + +## Platform + +### Path handling differs across operating systems + +Squad generates paths in agent output. On Windows, some paths may use forward slashes or Unix-style `~/.squad/` notation. The runtime handles this correctly, but log output may look inconsistent. + +### Git operations require a clean repo root + +Running `squad init` inside a subdirectory of an existing Git repo can cause agents to be invisible or misconfigured. Always initialize at the Git repository root. + +--- + +## What's Improving + +These limitations are actively being addressed. Check [What's New](../whatsnew) for the latest fixes, or watch the [GitHub repo](https://github.com/bradygaster/squad) for releases. + +--- + +## Next Steps + +- [Quick Start](five-minute-start) — get set up with recommended defaults +- [Troubleshooting](../scenarios/troubleshooting) — common problems and fixes +- [Session Model](../concepts/session-model) — understand session boundaries diff --git a/docs/src/content/docs/guide/faq.md b/docs/src/content/docs/guide/faq.md new file mode 100644 index 000000000..e7e53097b --- /dev/null +++ b/docs/src/content/docs/guide/faq.md @@ -0,0 +1,120 @@ +# FAQ + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Answers to frequently asked questions, sourced from the Squad community. + +--- + +## Setup and Getting Started + +### Why is Squad asking me to approve every file edit? + +By default, Copilot requires approval for each tool call. Squad sessions involve many tool calls (agent spawns, file reads, git operations), which makes this very disruptive. + +**Fix:** Use `--yolo` mode: + +```bash +copilot --yolo +``` + +This is the recommended way to run Squad. See [Quick Start](../get-started/five-minute-start) for details. + +### Why does setup differ from what the README shows? + +Squad evolves quickly during preview. If the README instructions don't match your experience, check [What's New](../whatsnew) for recent changes, or run: + +```bash +npx github:bradygaster/squad@latest init +``` + +The `@latest` tag ensures you're using the most current version. + +### I ran `squad init` but my agents aren't showing up + +This usually happens when you run `squad init` inside a subdirectory of an existing Git repository, or when there's a parent `.git/` directory above your project. Squad needs to be initialized at the **Git repository root**. + +**Fix:** Run `squad init` from the root of your Git repo, not a subdirectory. + +--- + +## Sessions and Context + +### Did I lose my Squad session? + +If you switched tools (CLI to VS Code, or vice versa), you started a new session. Your persisted memory (skills, decisions, history) is intact — only the live conversation context was lost. + +**Fix:** Start the new session with context: + +``` +I was working on [topic]. Pick up where we left off. +``` + +See [Session Model](../concepts/session-model) for more on how sessions work. + +### Do I need to keep using the terminal? + +No. Squad works across multiple surfaces: + +- **CLI** (`copilot` or `squad`) — best for focused, multi-step work +- **VS Code Copilot Chat** — good for quick questions and small tasks +- **Copilot Coding Agent** — best for autonomous issue-to-PR workflows + +All surfaces read the same `.squad/` directory, so your team's memory is shared. + +### Is it okay to restart Squad? + +Yes. During preview, crashes and restarts are normal. Your work is safe — files, commits, and `.squad/` state all persist. See [Known Limitations](../get-started/known-limitations) for details. + +--- + +## Team and Memory + +### Where do decisions actually live? + +In `.squad/decisions.md`. This is the single source of truth that every agent reads at session start. Decisions get there through a lifecycle: + +1. An agent drafts a note → `.squad/decisions/inbox/` +2. Scribe reviews and merges → `.squad/decisions.md` +3. Old decisions get archived → `.squad/decisions-archive.md` + +See [Repo Anatomy](../concepts/repo-anatomy) for the full directory structure. + +### How do I change how an agent behaves? + +Edit its charter at `.squad/agents/{name}/charter.md`. The charter defines the agent's role, domain, voice, and boundaries. Changes take effect at the next session start. + +### Can I add human team members? + +Yes. Add them to `.squad/team.md` and reference them in `.squad/routing.md`. See [Human Team Members](../features/human-team-members) for details. + +--- + +## Is Squad Right for Me? + +### Is Squad faster than working alone with Copilot? + +Speed isn't Squad's primary value. The real benefits are: + +- **Management altitude** — you direct a team instead of doing everything yourself +- **Role separation** — agents specialize (architect, reviewer, docs writer) so quality improves +- **Continuity** — memory compounds across sessions, so the team gets better over time +- **Consistency** — decisions are enforced uniformly across the codebase + +Squad shines when you have multi-step workflows, long-lived projects, or team coordination needs. For simple one-off tasks, plain Copilot may be simpler. + +### When is Squad overkill? + +- Quick one-line fixes +- Simple questions that don't need team context +- Throwaway scripts or prototypes + +For these, use Copilot directly. You can always `squad init` later when the project grows. + +--- + +## Still Have Questions? + +- Open an issue on [GitHub](https://github.com/bradygaster/squad/issues) +- Join the discussion in the Squad Teams channel +- Check [Troubleshooting](../scenarios/troubleshooting) for common problems diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts index 0521230b7..d869a8af4 100644 --- a/docs/src/navigation.ts +++ b/docs/src/navigation.ts @@ -19,6 +19,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Choose your path', slug: 'get-started/choosing-your-path' }, { title: 'Your First Session', slug: 'get-started/first-session' }, { title: 'Migration Guide', slug: 'get-started/migration' }, + { title: 'Known Limitations', slug: 'get-started/known-limitations' }, ], }, { @@ -30,6 +31,7 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Personal Squad', slug: 'guide/personal-squad' }, { title: 'Interactive Shell', slug: 'guide/shell' }, { title: 'Contributing', slug: 'guide/contributing' }, + { title: 'FAQ', slug: 'guide/faq' }, { title: 'Contributors', slug: 'guide/contributors' }, ], }, @@ -124,6 +126,8 @@ export const NAV_SECTIONS: NavSection[] = [ { title: 'Memory & Knowledge', slug: 'concepts/memory-and-knowledge' }, { title: 'Parallel Work', slug: 'concepts/parallel-work' }, { title: 'GitHub Workflow', slug: 'concepts/github-workflow' }, + { title: 'Session Model', slug: 'concepts/session-model' }, + { title: 'Repo Anatomy', slug: 'concepts/repo-anatomy' }, { title: 'Portability', slug: 'concepts/portability' }, ], },