Managing Workstreams and Dependencies

Master workstreams (teams) and dependencies to create accurate project forecasts. Learn how capacity, concurrency, and dependencies affect your timeline.

What is a Workstream?

A workstream represents a team or group of people working on your project. Think of workstreams as:

Development teams (Frontend, Backend, Mobile)
Functional groups (Design, QA, DevOps)
Individual contributors working independently

Examples:

"Frontend Team" (5 developers)
"Design" (2 designers)
"Backend Services" (3 engineers)
"QA Team" (2 testers)

Workstream Properties

Name (required)

The display name for the team.

name: Frontend Team

Capacity (required)

How much work the team can complete per week, in your project's units.

capacity: 10

What capacity means:

If using story points: "This team completes 10 story points per week"
If using days: "This team has 10 person-days of capacity per week"
If using hours: "This team has 10 hours per week"

Calculating capacity:

Team size × velocity per person = capacity
Example: 5 developers × 2 points each = 10 points/week
Or use historical data from past sprints

Work Items (required)

The list of work items this workstream will complete.

work_items:
  - id: feature-a
    name: Feature A
    size: 20
  - id: feature-b
    name: Feature B
    size: 30

Start Delay (optional)

Delay when the workstream begins work, in weeks.

start_delay: 2

Use cases:

Team not available immediately
Waiting for hiring to complete
Phased project start dates

WIP Limit / Max Concurrent Items (optional)

Maximum number of work items the team can work on simultaneously (Work In Progress limit).

max_concurrent_items: 2

Default behavior: Teams work on as many items as capacity allows (up to floor of capacity)

With WIP limit: Team works on max 2 items at a time, even if capacity could support more

Why use WIP limits?

Focus: Fewer concurrent items means more capacity per item and faster completion
Reduced context switching: Teams aren't spread thin across many items
Realistic schedules: Matches how agile/kanban teams actually work
Higher throughput: Counterintuitively, limiting WIP often increases delivery rate

Example without WIP limit:

workstreams:
  - name: Development
    capacity: 5
    # No max_concurrent_items - all ready items run in parallel
work_items:
  - id: A, B, C, D, E
    size: 50
    workstream: Development

Result: All 5 items start together, each gets 1 capacity (5/5), taking 50 weeks each

Example with WIP limit:

workstreams:
  - name: Development
    capacity: 5
    max_concurrent_items: 2  # Focus on 2 items at a time
work_items:
  - id: A, B, C, D, E
    size: 50
    workstream: Development

Result: A and B start first (2.5 capacity each = 20 weeks), then C and D start when slots open, then E

Best practice: Set WIP limit to 2-3 for focused teams, or leave unlimited for flexible teams

How Capacity Affects Timeline

Capacity is the most important factor in project duration.

Example: Low Capacity

name: Small Team
capacity: 5
work_items:
  - id: item-1
    name: Big Feature
    size: 50

Result: Takes 10 weeks (50 ÷ 5 = 10)

Example: High Capacity

name: Large Team
capacity: 20
work_items:
  - id: item-1
    name: Big Feature
    size: 50

Result: Takes 2.5 weeks (50 ÷ 20 = 2.5)

name: Team
capacity: 10
work_items:
  - id: item-a
    name: Feature A
    size: 40
  - id: item-b
    name: Feature B
    size: 40

If no dependencies:

Both items start simultaneously
Each gets 5 capacity (10 ÷ 2)
Both take 8 weeks (40 ÷ 5)
Project completes in 8 weeks

If item-b depends on item-a:

item-a gets full 10 capacity
item-a takes 4 weeks (40 ÷ 10)
item-b starts after item-a, gets full 10 capacity
item-b takes 4 weeks
Project completes in 8 weeks

Organizing Teams

One Workstream Per Team

Match workstreams to your actual team structure:

workstreams:
  - name: iOS Team
    capacity: 8
    work_items: [...]

  - name: Android Team
    capacity: 8
    work_items: [...]

  - name: Backend Team
    capacity: 12
    work_items: [...]

Pros:

Reflects real org structure
Easy to understand
Clear ownership

Multiple Workstreams Per Specialty

Split work by type rather than team:

workstreams:
  - name: UI Development
    capacity: 15
    work_items: [...]

  - name: API Development
    capacity: 10
    work_items: [...]

  - name: Data Pipeline
    capacity: 5
    work_items: [...]

Pros:

Shows work distribution by area
Highlights specialty bottlenecks
Useful for skill-based planning

Hybrid Approach

Combine teams and specialties:

workstreams:
  - name: Product Team (Frontend)
    capacity: 12
    work_items: [...]

  - name: Product Team (Backend)
    capacity: 8
    work_items: [...]

  - name: Platform Team
    capacity: 6
    work_items: [...]

  - name: Design
    capacity: 4
    work_items: [...]

Dependencies Between Workstreams

Dependencies create handoffs and sequencing across teams.

Simple Handoff

Design completes mockups before Engineering starts:

workstreams:
  - name: Design
    work_items:
      - id: mockups
        name: Design Mockups
        size: 10

  - name: Engineering
    work_items:
      - id: build-ui
        name: Build UI
        size: 40
        dependencies: [mockups]

Timeline:

Design works on mockups (1-2 weeks)
Engineering starts build-ui after mockups complete
Total time = design time + engineering time

Multi-Team Integration

Multiple teams working toward a shared integration point:

workstreams:
  - name: Frontend
    work_items:
      - id: ui-components
        name: UI Components
        size: 30

  - name: Backend
    work_items:
      - id: api-endpoints
        name: API Endpoints
        size: 25

  - name: Integration Team
    work_items:
      - id: connect-ui-api
        name: Connect UI to API
        size: 15
        dependencies: [ui-components, api-endpoints]

Timeline:

Frontend and Backend work in parallel
Integration Team waits for BOTH to finish
Integration starts when last dependency completes

Phased Dependencies

Each phase builds on previous work:

workstreams:
  - name: Infrastructure
    work_items:
      - id: cloud-setup
        name: Cloud Infrastructure
        size: 10

  - name: Backend
    work_items:
      - id: services
        name: Build Services
        size: 30
        dependencies: [cloud-setup]

  - name: Frontend
    work_items:
      - id: app
        name: Build App
        size: 40
        dependencies: [services]

Timeline:

Infrastructure (1 week)
Backend (3 weeks) - starts after infrastructure
Frontend (4 weeks) - starts after backend
Total = 8 weeks (sequential chain)

Priority vs Dependencies

Understanding when to use priority vs depends_on:

Priority (Soft Scheduling Hint)

Use priority when you want to influence which items get slots first when WIP limits apply, but items can still run in parallel if capacity allows.

workstreams:
  - name: Development
    capacity: 10
    max_concurrent_items: 2  # WIP limit = 2
work_items:
  - id: feature-a
    priority: 1  # Gets slot first
  - id: feature-b
    priority: 2  # Gets slot second
  - id: feature-c
    priority: 3  # Waits for slot

Behavior: With WIP limit of 2, feature-a and feature-b start first. When one completes, feature-c gets the slot.

Key points:

Priority is a soft hint - doesn't block parallel work
Only matters when WIP limits are in effect
Items with same priority can run in parallel
Lower numbers = higher priority

Dependencies (Hard Blocking Constraint)

Use depends_on when one item must complete before another can start.

work_items:
  - id: design
    size: 10
  - id: build
    size: 30
    depends_on: [design]  # Cannot start until design completes

Behavior: build waits until design finishes, then starts.

Key points:

Dependencies create hard blocking constraints
Item cannot start until all dependencies complete
Creates sequential ordering
Use for true prerequisites (e.g., "can't build until design is done")

When to Use Each

Use Priority when:

You want to influence slot allocation with WIP limits
Items can technically run in parallel
You want to express preference, not requirement
Example: "Feature A is more important, so give it slots first"

Use Dependencies when:

One item truly requires another to complete first
There's a technical or logical prerequisite
You want to enforce sequential ordering
Example: "Can't test until code is written"

Use Both Together:

work_items:
  - id: design-a
    priority: 1
  - id: design-b
    priority: 2
  - id: build
    priority: 1
    depends_on: [design-a, design-b]  # Waits for both designs

Behavior: design-a and design-b run in priority order. build waits for both, then gets priority slot when ready.

Common Dependency Patterns

Parallel + Merge

Teams work independently then integrate:

workstreams:
  - name: Team A
    work_items:
      - id: module-a
        size: 20

  - name: Team B
    work_items:
      - id: module-b
        size: 20

  - name: Integration
    work_items:
      - id: merge
        size: 10
        dependencies: [module-a, module-b]

Sequential Pipeline

Work flows through multiple teams:

workstreams:
  - name: Discovery
    work_items:
      - id: research
        size: 10

  - name: Design
    work_items:
      - id: design
        size: 15
        dependencies: [research]

  - name: Development
    work_items:
      - id: build
        size: 40
        dependencies: [design]

  - name: QA
    work_items:
      - id: test
        size: 10
        dependencies: [build]

Shared Foundation

Multiple teams wait for foundation work:

workstreams:
  - name: Platform
    work_items:
      - id: auth-system
        size: 20

  - name: Feature Team A
    work_items:
      - id: feature-a
        size: 30
        dependencies: [auth-system]

  - name: Feature Team B
    work_items:
      - id: feature-b
        size: 30
        dependencies: [auth-system]

Optimizing Your Timeline

Reduce Sequential Dependencies

Before (slow):

- id: design
  size: 10

- id: develop
  size: 30
  dependencies: [design]

- id: test
  size: 10
  dependencies: [develop]

Total: 50 units sequential

After (faster):

- id: design-and-develop
  size: 35

- id: test
  size: 10
  dependencies: [design-and-develop]

Total: 45 units, overlapped work

Increase Parallelism

Add more teams or split work to run in parallel:

Before:

workstreams:
  - name: Team
    capacity: 10
    work_items:
      - id: feature-1
        size: 40
      - id: feature-2
        size: 40
        dependencies: [feature-1]

Total: 8 weeks sequential

After:

workstreams:
  - name: Team A
    capacity: 10
    work_items:
      - id: feature-1
        size: 40

  - name: Team B
    capacity: 10
    work_items:
      - id: feature-2
        size: 40

Total: 4 weeks parallel

Increase Capacity

Add people or improve velocity:

Before:

capacity: 10

Feature takes 4 weeks

After:

capacity: 15

Same feature takes 2.67 weeks

Common Issues

Bottlenecks

Problem: One team with low capacity blocks others

Example:

- name: Design (bottleneck)
  capacity: 2
  work_items:
    - id: mockups
      size: 20  # Takes 10 weeks!

- name: Engineering
  capacity: 20
  work_items:
    - id: build
      size: 40
      dependencies: [mockups]

Solution: Increase Design capacity or reduce mockups scope

Over-Dependency

Problem: Too many dependencies create sequential work

Example:

- id: a
  size: 10

- id: b
  size: 10
  dependencies: [a]

- id: c
  size: 10
  dependencies: [b]

- id: d
  size: 10
  dependencies: [c]

Solution: Find work that can happen in parallel, reduce chain length

Idle Teams

Problem: Team waiting for dependencies has nothing to do

Example:

- name: QA Team
  capacity: 10
  work_items:
    - id: testing
      size: 20
      dependencies: [all-development]  # QA waits 8 weeks!

Solution: Add earlier QA work, shift-left testing, or reduce QA team size during early phases

Best Practices

Match capacity to reality: Use historical velocity data when possible

Don't over-specify: Not every handoff needs a dependency

Balance teams: Avoid one team being much smaller than others

Plan for ramp-up: Use start_delay for new hires or delayed starts

Review critical path: Identify which workstream determines project end date

Test "what if" scenarios: Use AI to explore capacity changes

Keep it simple: Start with 3-5 workstreams, add more if needed

Working with Work Items - Master work item sizing and organization
Understanding the Forecast View - Read your project timeline
Creating Your First Project - Step-by-step project creation
Understanding Project Definition Structure - Complete project definition reference

Last updated: 2025-12-19

Managing Workstreams and Dependencies

On this page