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

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

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?