PRD: Squad Workstreams — horizontal scaling via multi-Codespace partitioning

[tamirdresher]

Overview

Squad Workstreams enables horizontal scaling by partitioning a single repo's issues across multiple Codespaces. Each Codespace runs its own Squad instance scoped to a subset of issues via label filters, enforcing branch+PR workflow per partition.

---

Problem Statement

1. Single-Instance Bottleneck

Squad runs as one team per repo. Large repos with many issues overwhelm a single agent team.

2. No Issue Partitioning

No built-in way to scope a Squad instance to specific issues (by label, area, etc.)

3. No Workflow Enforcement

Squads may commit directly to main instead of using branch+PR workflow.

4. No Cross-Instance Monitoring

When running multiple Codespaces, no central view of all instances' activity.

5. Manual Scoping

Currently requires verbal directives per Codespace to set focus area.

Evidence

Multi-Codespace experiment with tamirdresher/squad-tetris — 3 Codespaces (UI, Backend, Cloud teams), each with Star Trek TNG crew:

• Backend squad pushed branch but no PR (no workflow enforcement)
• Other squads didn't push branches (no branch-per-issue discipline)
• Manual labels needed per Codespace to set scope
• 9/30 issues closed, but cross-team conflicts in shared packages

---

Proposed Solution

Core Concept: Workstream Definitions

workstreams.json in .squad/ defines named partitions:

{
  "defaultWorkflow": "branch-per-issue",
  "streams": [
    {
      "name": "ui",
      "labelFilter": "team:ui",
      "folderScope": ["src/ui", "src/components"],
      "workflow": "branch-per-issue"
    }
  ]
}

Resolution Chain

1. SQUAD_TEAM env var → match by name
2. .squad-workstream file → written by squad workstreams activate
3. Single-stream auto-select → if only one stream defined
4. null → single-squad mode (backward compatible)

SDK Module (packages/squad-sdk/src/streams/)

• WorkstreamDefinition type: name, labelFilter, folderScope (advisory), workflow
• resolveWorkstream() — resolution chain above
• filterIssuesByWorkstream() — filter issues by label
• loadWorkstreamsConfig() — parse and validate workstreams.json

CLI Commands

• squad workstreams list — show configured workstreams
• squad workstreams status — show per-workstream activity (branches, PRs, issues)
• squad workstreams activate <name> — write .squad-workstream file
• Backward compat: squad streams alias still works

Coordinator Integration

• Auto-detect workstream on session start
• Apply labelFilter to Ralph triage
• Enforce workflow (branch+PR per issue)
• folderScope is advisory (shared packages need cross-team access)

Key Design Decisions

• folderScope is advisory — not a hard lock. Agents prefer these directories but can modify shared code (with callout)
• Single-machine multi-workstream — squad workstreams activate allows sequential testing on one machine
• Backward compatible — repos without workstreams.json work exactly as before

---

Phases

Phase 1: Core SDK (Shipped in PR #189)

• WorkstreamDefinition types
• Resolver (env var → file → auto-select → null)
• Filter (label-based issue scoping)
• Config parsing with validation
• 44 unit tests

Phase 2: CLI Commands (Shipped in PR #189)

• list, status, activate subcommands
• Backward compat alias (streams → workstreams)

Phase 3: Coordinator Integration (Shipped in PR #189)

• squad.agent.md Stream Awareness section
• Init support with --stream flag

Phase 4: Future — Cross-Workstream Coordination

• Central dashboard showing all workstream activity
• Conflict detection for shared files
• Auto-merge coordination between workstreams
• WebSocket-based real-time status

---

Risks & Mitigations

Risk	Impact	Likelihood	Mitigation
Label leakage — issues with multiple team labels	Medium	High	Document convention: one team label per issue
Merge conflicts in shared packages	High	Medium	folderScope advisory, not enforced. Document patterns for shared code.
Codespace timeouts	Medium	High	Document state persistence, auto-restart
Over-partitioning	Medium	Low	Start with 2-3 workstreams, scale gradually

---

Open Questions

1. Should workstreams support area-path-based scoping (in addition to labels)?
2. Should there be a "coordinator workstream" that monitors all others?
3. How should workstreams interact with upstream inheritance?

[bradygaster]

Closing as... you did this. :)

[github-actions]

📋 Assigned to Keaton (Lead)

Issue: #200 — PRD: Squad Workstreams — horizontal scaling via multi-Codespace partitioning

Keaton will pick this up in the next Copilot session.

For Copilot coding agent: If enabled, this issue will be worked automatically.
Otherwise, start a Copilot session and say:
Keaton, work on issue #200

[github-actions]

🏗️ Squad Triage — Keaton (Lead)

Issue: #200 — PRD: Squad Workstreams — horizontal scaling via multi-Codespace partitioning
Assigned to: Hockney (Tester)
Reason: Issue relates to testing/quality work

@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.

Team roster:

• Keaton (Lead) → label: squad:keaton
• Verbal (Prompt Engineer) → label: squad:verbal
• Fenster (Core Dev) → label: squad:fenster
• Hockney (Tester) → label: squad:hockney
• McManus (DevRel) → label: squad:mcmanus
• Kujan (SDK Expert) → label: squad:kujan
• Edie (TypeScript Engineer) → label: squad:edie
• Kobayashi (Git & Release) → label: squad:kobayashi
• Fortier (Node.js Runtime) → label: squad:fortier
• Rabin (Distribution) → label: squad:rabin
• Baer (Security) → label: squad:baer
• Redfoot (Graphic Designer) → label: squad:redfoot
• Strausz (VS Code Extension) → label: squad:strausz
• Saul (Aspire & Observability) → label: squad:saul
• Kovash (REPL & Interactive Shell) → label: squad:kovash
• Marquez (CLI UX Designer) → label: squad:marquez
• Cheritto (TUI Engineer) → label: squad:cheritto
• Breedan (E2E Test Engineer) → label: squad:breedan
• Nate (Accessibility Reviewer) → label: squad:nate
• Waingro (Product Dogfooder) → label: squad:waingro
• Ralph (Work Monitor) → label: squad:ralph
• @copilot (Coding Agent) → label: squad:copilot

To reassign, remove the current squad:* label and add the correct one.

[bradygaster]

Excellent PRD, @tamirdresher! Squad Workstreams—partitioning repos across Codespaces with label filtering—is exactly the horizontal scaling pattern we need. Your Tetris experiment with multi-Codespace teams showed the gaps perfectly. This is shipping in phases and we're excited to see it in the wild! 💪

— McManus 📝, on behalf of the Squad