feat: Squad Workstreams — horizontal scaling via Codespaces

.gitignore

@@ -11,3 +11,6 @@ coverage/
 .test-cli-*
 # Docs site generated files
 docs/dist/
+# Squad: workstream activation file (local to this machine)
+.squad-workstream
+.squad/.first-run

docs/blog/023-workstreams-horizontal-scaling.md

@@ -0,0 +1,133 @@
+---
+title: "Workstreams — Scaling Squad Across Multiple Codespaces"
+date: 2026-03-05
+author: "Tamir Dresher (Community Contributor)"
+wave: null
+tags: [squad, workstreams, scaling, codespaces, horizontal-scaling, multi-instance, community]
+status: draft
+hero: "Squad Workstreams lets you partition a repo's work across multiple Codespaces — each running its own scoped Squad instance. One repo, multiple AI teams, zero conflicts."
+---
+
+# Workstreams — Scaling Squad Across Multiple Codespaces
+
+> Blog post #23 — A community contribution: horizontal scaling for Squad.
+
+## The Problem We Hit
+
+We were building a multiplayer Tetris game with Squad. One team, 30 issues — UI, backend, cloud infra. Squad handled it fine at first, but as the issue count grew, a single Squad instance became a bottleneck. Agents stepped on each other in shared packages, there was no workflow enforcement, and we had no way to scope each Codespace to its slice of work.
+
+So we built Workstreams.
+
+## What Are Workstreams?
+
+Workstreams partition your repo's issues into labeled subsets. Each Codespace (or machine) runs one workstream, scoped to matching issues only.
+
+```
+┌─────────────────────────────────────────────────┐
+│  Repository: acme/starship                      │
+│                                                 │
+│  ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
+│  │ Codespace 1 │ │ Codespace 2 │ │ Codespace 3│ │
+│  │ team:bridge │ │ team:engine │ │ team:ops   │ │
+│  │ UI + API    │ │ Core engine │ │ Infra + CI │ │
+│  └─────────────┘ └─────────────┘ └───────────┘ │
+│                                                 │
+│  Ralph only picks up issues matching            │
+│  the active workstream's label.                 │
+└─────────────────────────────────────────────────┘
+```
+
+## How It Works
+
+**1. Define workstreams** in `.squad/workstreams.json`:
+
+```json
+{
+  "defaultWorkflow": "branch-per-issue",
+  "workstreams": [
+    {
+      "name": "bridge",
+      "labelFilter": "team:bridge",
+      "folderScope": ["src/api", "src/ui"],
+      "description": "Bridge crew — API and UI"
+    },
+    {
+      "name": "engine",
+      "labelFilter": "team:engine",
+      "folderScope": ["src/core"],
+      "description": "Engineering — core systems"
+    }
+  ]
+}
+```
+
+**2. Activate a workstream:**
+
+```bash
+# Via environment variable (ideal for Codespaces)
+export SQUAD_TEAM=bridge
+
+# Or via CLI (local machines)
+squad workstreams activate bridge
+```
+
+**3. Run Squad normally.** Ralph will only pick up issues labeled `team:bridge`. Agents enforce branch+PR workflow. `folderScope` guides where agents focus (advisory, not enforced — shared code is still accessible).
+
+## The Tetris Experiment
+
+We validated this with [tamirdresher/squad-tetris](https://github.com/tamirdresher/squad-tetris) — 3 Codespaces, 30 issues, Star Trek TNG crew names:
+
+| Codespace | Workstream | Squad Members | Focus |
+|-----------|-----------|---------------|-------|
+| CS-1 | `ui` | Riker, Troi | React game board, animations |
+| CS-2 | `backend` | Geordi, Worf | WebSocket server, game state |
+| CS-3 | `cloud` | Picard, Crusher | Azure, CI/CD, deployment |
+
+**Results:** 9 issues closed, 16 branches created, 6+ PRs merged, real code shipped across all three teams. We discovered that `folderScope` needs to be advisory (shared packages require cross-team access) and that workflow enforcement (`branch-per-issue`) is critical to prevent direct commits to main.
+
+## CLI Commands
+
+```bash
+squad workstreams list       # Show all configured workstreams
+squad workstreams status     # Activity per workstream (branches, PRs)
+squad workstreams activate X # Activate a workstream for this machine
+```
+
+## Resolution Chain
+
+Squad resolves the active workstream in priority order:
+
+1. `SQUAD_TEAM` environment variable
+2. `.squad-workstream` file (written by `activate`, gitignored)
+3. Auto-select if exactly one workstream is defined
+4. No workstream → single-squad mode (backward compatible)
+
+## Key Design Decisions
+
+- **folderScope is advisory** — agents prefer these directories but can modify shared code when needed
+- **Workflow enforcement** — `branch-per-issue` means every issue gets a branch and PR, never direct commits to main
+- **Backward compatible** — repos without `workstreams.json` work exactly as before
+- **Single-machine testing** — use `squad workstreams activate` to switch workstreams sequentially without needing multiple Codespaces
+
+## What's Next
+
+We're looking at cross-workstream coordination — a central dashboard showing all workstreams' activity, conflict detection for shared files, and auto-merge coordination. See the [PRD](https://github.com/bradygaster/squad/issues/200) for the full roadmap.
+
+Also: we haven't settled on the name yet! "Workstreams" is the working title, but we're considering alternatives like "Lanes", "Teams", or "Streams". If you have an opinion, let us know in the [discussion](https://github.com/bradygaster/squad/issues/200).
+
+## Try It
+
+```bash
+# Install Squad
+npm install -g @bradygaster/squad-cli
+
+# Init in your repo
+squad init
+
+# Create workstreams.json and label your issues
+# Then activate and go
+squad workstreams activate frontend
+squad start
+```
+
+Full docs: [Scaling with Workstreams](../scenarios/scaling-workstreams.md) | [Multi-Codespace Setup](../scenarios/multi-codespace.md) | [Workstreams PRD](../specs/streams-prd.md)

docs/features/streams.md

@@ -0,0 +1,146 @@
+# Squad Workstreams
+
+> Scale Squad across multiple Codespaces by partitioning work into labeled workstreams.
+
+## What Are Workstreams?
+
+A **workstream** is a named partition of work within a Squad project. Each workstream targets a specific GitHub label (e.g., `team:ui`, `team:backend`) and optionally restricts agents to certain directories. Multiple Squad instances — each running in its own Codespace — can each activate a different workstream, enabling parallel work across teams.
+
+## Why Workstreams?
+
+Squad was originally designed for a single team per repository. As projects grow, a single Codespace becomes a bottleneck:
+
+- **Model rate limits** — One Codespace hitting API limits slows the whole team
+- **Context overload** — Ralph picks up all issues, not just the relevant ones
+- **Folder conflicts** — Multiple agents editing the same files causes merge pain
+
+Workstreams solve this by giving each Codespace a scoped view of the project.
+
+## Configuration
+
+### 1. Create `.squad/workstreams.json`
+
+```json
+{
+  "workstreams": [
+    {
+      "name": "ui-team",
+      "labelFilter": "team:ui",
+      "folderScope": ["apps/web", "packages/ui"],
+      "workflow": "branch-per-issue",
+      "description": "Frontend team — React, CSS, components"
+    },
+    {
+      "name": "backend-team",
+      "labelFilter": "team:backend",
+      "folderScope": ["apps/api", "packages/core"],
+      "workflow": "branch-per-issue",
+      "description": "Backend team — APIs, database, services"
+    },
+    {
+      "name": "infra-team",
+      "labelFilter": "team:infra",
+      "folderScope": [".github", "infrastructure"],
+      "workflow": "direct",
+      "description": "Infrastructure — CI/CD, deployment, monitoring"
+    }
+  ],
+  "defaultWorkflow": "branch-per-issue"
+}
+```
+
+### 2. Activate a Workstream
+
+There are three ways to tell Squad which workstream to use:
+
+#### Environment Variable (recommended for Codespaces)
+
+```bash
+export SQUAD_TEAM=ui-team
+```
+
+Set this in your Codespace's environment or devcontainer.json:
+
+```json
+{
+  "containerEnv": {
+    "SQUAD_TEAM": "ui-team"
+  }
+}
+```
+
+#### .squad-workstream File (local activation)
+
+```bash
+squad workstreams activate ui-team
+```
+
+This writes a `.squad-workstream` file (gitignored) so the setting is local to your machine.
+
+#### Auto-select (single workstream)
+
+If `workstreams.json` contains only one workstream, it's automatically selected.
+
+### 3. Resolution Priority
+
+1. `SQUAD_TEAM` env var (highest)
+2. `.squad-workstream` file
+3. Single-workstream auto-select
+4. No workstream (classic single-squad mode)
+
+## Workstream Definition Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique workstream identifier (kebab-case) |
+| `labelFilter` | Yes | GitHub label to filter issues |
+| `folderScope` | No | Directories this workstream may modify |
+| `workflow` | No | `branch-per-issue` (default) or `direct` |
+| `description` | No | Human-readable purpose |
+
+## CLI Reference
+
+```bash
+# List configured workstreams
+squad workstreams list
+
+# Show workstream activity (branches, PRs)
+squad workstreams status
+
+# Activate a workstream locally
+squad workstreams activate <name>
+```
+
+## How It Works
+
+### Triage (Ralph)
+
+When a workstream is active, Ralph's triage only picks up issues labeled with the workstream's `labelFilter`. Unmatched issues are left for other workstreams or the main squad.
+
+### Workflow Enforcement
+
+- **branch-per-issue** (default): Every issue gets its own branch and PR. Agents never commit directly to main.
+- **direct**: Agents may commit directly (useful for infra/ops workstreams).
+
+### Folder Scope
+
+When `folderScope` is set, agents should primarily modify files within those directories. However, `folderScope` is **advisory, not a hard lock** — agents may still touch shared files (types, configs, package exports) when their issue requires it. The real protection comes from `branch-per-issue` workflow: each issue gets its own branch, so two workstreams editing the same file won't conflict until merge time.
+
+> **Tip:** If two workstreams' PRs touch the same file, Git resolves non-overlapping changes automatically. For semantic conflicts (incompatible API changes), use PR review to catch them.
+
+### Cost Optimization: Single-Machine Multi-Workstream
+
+You don't need a separate Codespace per workstream. One machine can serve multiple workstreams:
+
+```bash
+# Switch between workstreams manually
+squad workstreams activate ui-team      # Ralph works team:ui issues
+# ... later ...
+squad workstreams activate backend-team # now works team:backend issues
+```
+
+This gives you 1× Codespace cost instead of N×, at the expense of serial (not parallel) execution. Each issue still gets its own branch — no conflicts.
+
+## Example: Multi-Codespace Setup
+
+See [Multi-Codespace Scenario](../scenarios/multi-codespace.md) for a complete walkthrough.