Skip to content

docs: get-started cleanup — installation fix, squad init, interface canonical (WS-D) #1573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bradygaster merged 1 commit into from
Aug 3, 2026
Merged

docs: get-started cleanup — installation fix, squad init, interface canonical (WS-D) #1573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
298 changes: 120 additions & 178 deletions docs/src/content/docs/get-started/choose-your-interface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,178 +1,120 @@
# Choose your interface

> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.


Squad works across multiple interfaces. Pick the one that fits your workflow.

---

## Try this:

```bash
# Day-to-day work with your squad
copilot --agent squad

# Setup and diagnostics
squad init
squad doctor
```

---

## What are the ways to use Squad?

Squad runs in multiple modes and across multiple platforms:

### GitHub Copilot CLI (`copilot` command)

The conversational terminal interface. Powered by the GitHub Copilot CLI, this is the recommended way to work with Squad day-to-day.

```bash
copilot --agent squad
```

Reads `.squad/` and uses `squad.agent.md` to coordinate your team. Full feature set — sub-agent spawning, per-spawn model selection, background execution, SQL tools, parallel fan-out.

### VS Code (GitHub Copilot in the editor)

Squad works identically in VS Code through GitHub Copilot. Same `.squad/` directory, same agents, same decisions. Full file access, parallel execution, MCP tool inheritance. See [Squad in VS Code](../features/vscode.md) for details.

### Squad CLI (`squad` command)

The Squad CLI provides setup, diagnostics, and automation commands. Not conversational — use this for installation, validation, and operational tasks.

```bash
# Setup
squad init

# Validation
squad doctor

# Monitoring
squad watch

# Observability
squad aspire
```

See [CLI Reference](../reference/cli.md) for all commands.

### Interactive shell (`squad start` / `squad shell`)

> ⚠️ **Deprecated:** The interactive shell is no longer recommended. Use [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) instead for a richer agent experience.
>
> ```bash
> copilot --agent squad
> ```

REPL mode for conversational interaction directly via the Squad CLI. Enter `squad` with no arguments to start a persistent shell session.

### SDK (`@bradygaster/squad-sdk`)

Programmatic access for building tools on top of Squad. Typed APIs, routing config, agent lifecycle hooks.

```bash
npm install @bradygaster/squad-sdk
```

```typescript
import { resolveSquad, loadConfig, SquadCoordinator } from '@bradygaster/squad-sdk';
```

See [SDK Reference](../reference/sdk.md) for the complete API.

### Copilot Coding Agent (`@copilot`)

Autonomous GitHub bot that picks up labeled issues and opens draft PRs. Works across your entire organization without human intervention. Issue gets labeled → agent picks it up → PR gets opened → human reviews.

See [Copilot Coding Agent](../features/copilot-coding-agent.md) for setup.

---

## Which should I use?

| You want to... | Use | Why |
|----------------|-----|-----|
| **Work with your squad day-to-day** | **GitHub Copilot CLI** or **VS Code** | Conversational interface, full agent spawning, parallel execution. Most natural way to collaborate with your team. |
| **Set up Squad in a new repo** | **Squad CLI** (`squad init`) | One command initializes `.squad/` directory and all configuration. |
| **Check if Squad is working** | **Squad CLI** (`squad doctor`) | Validates directory structure, agents, configuration integrity. |
| **Monitor work 24/7** | **Squad CLI** (`squad watch`) | Persistent polling for new issues, auto-triage, agent assignment. |
| **View OpenTelemetry traces** | **Squad CLI** (`squad aspire`) | Launches Aspire dashboard for observability. |
| **Process issues autonomously** | **Copilot Coding Agent** | GitHub Actions workflow watches for labeled issues and dispatches `@copilot`. |
| **Build tools on top of Squad** | **SDK** | Typed APIs, configuration loading, agent lifecycle hooks. |

---

## Feature availability matrix

Not every feature works everywhere. Here's what's available where:

| Feature | GitHub Copilot CLI | VS Code | Squad CLI | Interactive shell | SDK |
|---------|:------------------:|:-------:|:---------:|:--------:|:---:|
| Agent spawning | ✅ | ✅ | ✅ | ⚠️ (deprecated) | ✅ |
| Ralph / work monitoring | ✅ | ✅ | ✅ (`squad watch`) | ❌ | ✅ |
| Per-spawn model selection | ✅ | ⚠️ (session model only) | ✅ | ❌ | ✅ |
| Background execution | ✅ | ⚠️ (parallel sync) | ✅ | ❌ | ✅ |
| SQL tool | ✅ | ❌ | ✅ | ❌ | ✅ |
| Aspire dashboard | ❌ | ❌ | ✅ | ❌ | ❌ |
| `squad doctor` diagnostics | ❌ | ❌ | ✅ | ❌ | ✅ |
| Issue assignment to `@copilot` | ❌ | ❌ | ✅ (setup) | ❌ | ❌ |

**Legend:**
- ✅ Fully supported
- ⚠️ Limited or constrained
- ❌ Not available

For a detailed breakdown of VS Code constraints and CLI parity, see [Client Compatibility Matrix](../scenarios/client-compatibility.md).

---

## Common workflows

### "I use GitHub Copilot CLI for everything"

```bash
# Terminal 1: Work with Squad
copilot --agent squad

# Let Squad call `squad` commands when needed (doctor, watch, aspire)
```

This is the recommended workflow. The CLI automatically invokes Squad CLI commands when needed.

### "I run squad watch in one terminal and use GitHub Copilot CLI in another"

```bash
# Terminal 1: Monitoring (persistent)
squad watch --interval 10

# Terminal 2: Work with Squad
copilot --agent squad
```

Keep Ralph monitoring issues in the background while you work conversationally.

### "I use VS Code with Copilot for coding and Squad CLI for setup"

```bash
# One-time setup
squad init
squad doctor

# Open VS Code, select Squad from agent picker
# Same .squad/ directory, same team
```

Initialize with CLI, work in VS Code.

---

## See also

- [Installation](installation.md) — Install Squad CLI, SDK, or use in VS Code
- [First Session](first-session.md) — Get started with your first Squad conversation
- [Client Compatibility Matrix](../scenarios/client-compatibility.md) — Full feature comparison across platforms
- [CLI Reference](../reference/cli.md) — All Squad CLI commands
- [Squad in VS Code](../features/vscode.md) — VS Code-specific guidance
- [SDK Reference](../reference/sdk.md) — Programmatic API
# Choose your interface
Squad works across multiple interfaces. Pick the one that fits your workflow.

---
## Try this:
```bash
# Day-to-day work with your squad
copilot --agent squad
# Setup and diagnostics
squad init
squad doctor
```

---
## What are the ways to use Squad?
Squad runs in multiple modes and across multiple platforms:
### GitHub Copilot CLI (`copilot` command)
The conversational terminal interface. Powered by the GitHub Copilot CLI, this is the recommended way to work with Squad day-to-day.
```bash
copilot --agent squad
```
Reads `.squad/` and uses `squad.agent.md` to coordinate your team. Full feature set — sub-agent spawning, per-spawn model selection, background execution, SQL tools, parallel fan-out.
### VS Code (GitHub Copilot in the editor)
Squad works identically in VS Code through GitHub Copilot. Same `.squad/` directory, same agents, same decisions. Full file access, parallel execution, MCP tool inheritance. See [Squad in VS Code](../features/vscode.md) for details.
### Squad CLI (`squad` command)
The Squad CLI provides setup, diagnostics, and automation commands. Not conversational — use this for installation, validation, and operational tasks.
```bash
# Setup
squad init
# Validation
squad doctor
# Monitoring
squad watch
# Observability
squad aspire
```
See [CLI Reference](../reference/cli.md) for all commands.
### SDK (`@bradygaster/squad-sdk`)
Programmatic access for building tools on top of Squad. Typed APIs, routing config, agent lifecycle hooks.
```bash
npm install @bradygaster/squad-sdk
```
```typescript
import { resolveSquad, loadConfig, SquadCoordinator } from '@bradygaster/squad-sdk';
```
See [SDK Reference](../reference/sdk.md) for the complete API.
### Copilot Coding Agent (`@copilot`)
Background GitHub automation that picks up labeled issues and opens draft PRs. Works across your organization with human-defined guardrails. Issue gets labeled → agent picks it up → PR gets opened → human reviews.
See [Copilot Coding Agent](../features/copilot-coding-agent.md) for setup.

---
## Which should I use?

| You want to... | Use | Why |
|----------------|-----|-----|
| **Work with your squad day-to-day** | **GitHub Copilot CLI** or **VS Code** | Conversational interface, full agent spawning, parallel execution. Most natural way to collaborate with your team. |
| **Set up Squad in a new repo** | **Squad CLI** (`squad init`) | One command initializes `.squad/` directory and all configuration. |
| **Check if Squad is working** | **Squad CLI** (`squad doctor`) | Validates directory structure, agents, configuration integrity. |
| **Monitor work 24/7** | **Squad CLI** (`squad watch`) | Persistent polling for new issues, auto-triage, agent assignment. |
| **View OpenTelemetry traces** | **Squad CLI** (`squad aspire`) | Launches Aspire dashboard for observability. |
| **Process approved issues in the background** | **Copilot Coding Agent** | GitHub Actions workflow watches for labeled issues and dispatches `@copilot`. |
| **Build tools on top of Squad** | **SDK** | Typed APIs, configuration loading, agent lifecycle hooks. |

---
## Feature availability matrix
Not every feature works everywhere. Here's what's available where:

| Feature | GitHub Copilot CLI | VS Code | Squad CLI | SDK |
|---------|:------------------:|:-------:|:---------:|:---:|
| Agent spawning | ✅ | ✅ | ✅ | ✅ |
| Ralph / work monitoring | ✅ | ✅ | ✅ (`squad watch`) | ✅ |
| Per-spawn model selection | ✅ | ⚠️ (session model only) | ✅ | ✅ |
| Background execution | ✅ | ⚠️ (parallel sync) | ✅ | ✅ |
| SQL tool | ✅ | ❌ | ✅ | ✅ |
| Aspire dashboard | ❌ | ❌ | ✅ | ❌ |
| `squad doctor` diagnostics | ❌ | ❌ | ✅ | ✅ |
| Issue assignment to `@copilot` | ❌ | ❌ | ✅ (setup) | ❌ |

**Legend:**

- ✅ Fully supported
- ⚠️ Limited or constrained
- ❌ Not available
For a detailed breakdown of VS Code constraints and CLI parity, see [Client Compatibility Matrix](../scenarios/client-compatibility.md).

---
## Common workflows
### "I use GitHub Copilot CLI for everything"
```bash
# Terminal 1: Work with Squad
copilot --agent squad
# Let Squad call `squad` commands when needed (doctor, watch, aspire)
```
This is the recommended workflow. The CLI automatically invokes Squad CLI commands when needed.
### "I run squad watch in one terminal and use GitHub Copilot CLI in another"
```bash
# Terminal 1: Monitoring (persistent)
squad watch --interval 10
# Terminal 2: Work with Squad
copilot --agent squad
```
Keep Ralph monitoring issues in the background while you work conversationally.
### "I use VS Code with Copilot for coding and Squad CLI for setup"
```bash
# One-time setup
squad init
squad doctor
# Open VS Code, select Squad from agent picker
# Same .squad/ directory, same team
```
Initialize with CLI, work in VS Code.

---
## See also
- [Installation](installation.md) — Install Squad CLI, SDK, or use in VS Code
- [First Session](first-session.md) — Get started with your first Squad conversation
- [Client Compatibility Matrix](../scenarios/client-compatibility.md) — Full feature comparison across platforms
- [CLI Reference](../reference/cli.md) — All Squad CLI commands
- [Squad in VS Code](../features/vscode.md) — VS Code-specific guidance
- [SDK Reference](../reference/sdk.md) — Programmatic API
82 changes: 0 additions & 82 deletions docs/src/content/docs/get-started/choosing-your-path.md
View file
Open in desktop

This file was deleted.

Loading
Loading