How GSD Workstreams Enable Parallel Milestone Work Without Context Conflicts

Apr 21, 2026

Working on multiple milestones simultaneously creates state conflicts. Your ROADMAP gets cluttered, STATE.md tracks conflicting positions, and phase plans overlap. GSD’s workstream feature solves this by creating namespaced parallel work spaces.

The Problem: Single State Bottleneck

When I work on Milestone 1 and Milestone 2 at the same time, a single .planning/ directory creates problems:

ROADMAP.md can only track one milestone’s phases
STATE.md gets confused about current position
Phase plans from different milestones collide
Research files mix domain knowledge from different contexts

I needed isolation between parallel work streams.

What GSD Workstreams Do

GSD workstreams create isolated namespaces within a project. Each workstream has its own complete planning state:

.planning/
├── ROADMAP.md              # Main roadmap (default workstream)
├── STATE.md                # Main state
├── phases/                 # Main phases
├── .workstream-flag        # Points to active workstream
└── workstreams/
    ├── feature-auth/       # Auth workstream namespace
    │   ├── ROADMAP.md      # Independent roadmap
    │   ├── STATE.md        # Independent state
    │   └── phases/         # Independent phases
    └── feature-payments/   # Payments workstream namespace
        ├── ROADMAP.md
        ├── STATE.md
        └── phases/

The .workstream-flag file contains the active workstream name. All GSD commands read this flag to scope their operations.

Creating a Workstream

I create a new workstream when I need to start parallel milestone work:

/gsd-workstreams create feature-auth

This creates:

.planning/workstreams/feature-auth/ directory
Independent ROADMAP.md for auth milestone
Independent STATE.md for tracking auth work
Independent phases/ for auth phase plans
Sets .workstream-flag to feature-auth

Switching Between Workstreams

I switch contexts to work on different milestones:

/gsd-workstreams switch feature-auth

The switch updates .workstream-flag. All subsequent GSD commands operate within the feature-auth namespace. When I run /gsd-discuss-phase 1, it reads and writes to .planning/workstreams/feature-auth/phases/phase-1/.

/gsd-workstreams switch main

Listing All Workstreams

I can see all workstreams and their status:

/gsd-workstreams list

Output shows:

Workstream name
Current phase
Position (planning, executing, verifying)
Active indicator (which one I’m currently in)

This gives me a quick view of all parallel work and where each stands.

Workstream State Isolation

Each workstream maintains completely independent state:

ROADMAP.md isolation:

Auth workstream has phases for login, registration, OAuth
Payments workstream has phases for checkout, subscriptions, invoices
No cross-contamination between planning artifacts

STATE.md isolation:

Auth workstream tracks: “Phase 2 executing, decided to use JWT”
Payments workstream tracks: “Phase 1 planning, researching Stripe vs PayPal”
Different decisions, different positions, no conflicts

Phase directory isolation:

.planning/workstreams/feature-auth/phases/phase-1/ contains auth phase 1 plans
.planning/workstreams/feature-payments/phases/phase-1/ contains payments phase 1 plans
Same phase numbers, different content

Research isolation:

Auth workstream stores OAuth documentation, password hashing research
Payments workstream stores Stripe API docs, pricing model research
Domain knowledge stays scoped

Completing a Workstream

When I finish a milestone, I complete the workstream:

/gsd-workstreams complete feature-auth

The completion process:

Merges workstream ROADMAP phases into main ROADMAP
Updates main STATE.md with completed position and decisions
Archives workstream directory for reference
Switches active workstream back to main

This preserves the work history while consolidating the final state.

SDK Support for Workstreams

The GSD SDK provides workstream-aware queries:

gsd-sdk query state.load  # Loads from active workstream
gsd-sdk query phase.get 1  # Gets phase 1 from active workstream

The SDK reads .workstream-flag to determine the correct paths. My custom scripts and integrations automatically work within the correct namespace.

Practical Workflow Example

Here’s how I use workstreams for parallel development:

# Start working on auth feature
/gsd-workstreams create feature-auth
/gsd-workstreams switch feature-auth
/gsd-discuss-phase 1
/gsd-plan-phase 1

# Need to start payments in parallel
/gsd-workstreams create feature-payments
/gsd-workstreams switch feature-payments
/gsd-discuss-phase 1
/gsd-plan-phase 1

# Continue auth work
/gsd-workstreams switch feature-auth
/gsd-execute-phase 1

# Check all workstream status
/gsd-workstreams list

# Complete auth milestone
/gsd-workstreams complete feature-auth

Each milestone progresses independently without state conflicts.

When to Use Workstreams

I create workstreams for:

Parallel milestone work: Different deadlines, different stakeholders
Feature branches: Long-running features alongside main development
Spike work: Experimental approaches I might discard
Hotfix parallelism: Emergency fixes while main work continues

I don’t use workstreams for:

Sequential milestone work (just use phases)
Small tasks (adds unnecessary overhead)
Single-developer single-thread work (no isolation needed)

Key Benefits

No state conflicts: Each workstream has independent ROADMAP, STATE, and phases.

Context preservation: I can pause work on one milestone and resume later without losing context.

Clean separation: Domain knowledge, decisions, and plans stay scoped to their workstream.

Merge control: I complete workstreams on my schedule, merging when milestones finish.

SDK integration: Custom tools automatically respect workstream boundaries.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 GSD: Get Shit Done - A Structured Approach to Project Planning
👨‍💻 GSD Features Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!