# .pm/workstreams/ws-001.yaml
id: ws-001
backlog_id: BL-001
title: Implement config parser
status: RUNNING # RUNNING, PAUSED, COMPLETED, FAILED
agent: builder
started_at: "2025-11-21T11:00:00Z"
completed_at: null
process_id: null
elapsed_minutes: 45
progress_notes:
  - "Started implementation"
  - "Config loading working"
dependencies: [] # List of BL-IDs this depends on
last_activity: "2025-11-21T11:45:00Z"

User: What's the status?

Coordinator: [Calls scripts/coordinate.py]

Workstream Status:

**Active Workstreams** (3/5):
✓ ws-001: Implement config parser (builder, 45 mins, ON TRACK)
✓ ws-002: Add CLI help (builder, 30 mins, ON TRACK)
⚠ ws-003: Error handling tests (tester, STALLED 2 hours)

**Capacity**: 60% utilization (2 slots available)

**Issues Detected**:
⚠ ws-003 stalled - no progress for 2 hours

**Recommendations**:
1. Investigate ws-003 stall cause (agent blocked? waiting for input?)
2. Capacity for 2 more workstreams if needed

**Backlog**: 8 items READY (3 HIGH, 4 MEDIUM, 1 LOW)

Coordinator: Stall Analysis

⚠ ws-003: Error handling tests
  Agent: tester
  Idle: 2.3 hours
  Last activity: 2025-11-21 09:00Z

  Recommendation: Check if agent is blocked or needs input.
  Consider pausing and investigating.

Coordinator: Dependency Conflict Detected

⚠ ws-005 depends on BL-001 which is in ws-001 (RUNNING)

Details:
- ws-005: Add CLI commands (depends on config parser BL-001)
- ws-001: Implement config parser (still in progress)

Recommendation: ws-005 should wait for ws-001 to complete.
Consider pausing ws-005 until ws-001 finishes.

Coordinator: Capacity Analysis

Active: 3 workstreams
Max Concurrent: 5 workstreams
Utilization: 60%
Available: 2 slots

Status: HEALTHY - Can start 2 more workstreams

Coordinator: ⚠ CAPACITY WARNING

Active: 6 workstreams
Max Concurrent: 5 workstreams
Utilization: 120%

Recommendation: Over capacity! Consider:
1. Pausing lower-priority workstreams
2. Waiting for workstreams to complete
3. Increasing max concurrent (if resources allow)

Recommendation: No active work but 5 items READY.
Should I recommend next work to start?

Recommendation: 80% capacity utilization.
Consider prioritizing completion over starting new work.

Recommendations:
1. Investigate 2 stalled workstreams (URGENT)
2. Resolve 1 dependency conflict
3. Then capacity for 1 more workstream

def coordinate(project_root):
    # Load workstreams
    workstreams = load_all_workstreams(project_root)

    # Categorize by status
    active = [ws for ws in workstreams if ws.status == "RUNNING"]
    paused = [ws for ws in workstreams if ws.status == "PAUSED"]
    completed = [ws for ws in workstreams if ws.status == "COMPLETED"]

    # Detect issues
    stalled = detect_stalled(active, threshold_hours=2)
    conflicts = detect_conflicts(active, backlog_items)

    # Analyze capacity
    capacity = analyze_capacity(len(active), max_concurrent=5)

    # Generate recommendations
    recommendations = []
    if stalled:
        recommendations.append(f"Investigate {len(stalled)} stalled workstream(s)")
    if conflicts:
        recommendations.append(f"Resolve {len(conflicts)} dependency conflict(s)")
    if capacity.utilization > 80:
        recommendations.append("High capacity - prioritize completion")
    if len(active) == 0 and ready_items > 0:
        recommendations.append(f"No active work - {ready_items} items ready")

    return {
        "active": active,
        "stalled": stalled,
        "conflicts": conflicts,
        "capacity": capacity,
        "recommendations": recommendations
    }

def detect_stalled(workstreams, threshold_hours=2):
    stalled = []
    now = datetime.now(timezone.utc)

    for ws in workstreams:
        if ws.status != "RUNNING":
            continue

        last_activity = parse_timestamp(ws.last_activity)
        idle_hours = (now - last_activity).total_seconds() / 3600

        if idle_hours > threshold_hours:
            stalled.append({
                "workstream": ws.id,
                "title": ws.title,
                "idle_hours": round(idle_hours, 1),
                "recommendation": "Investigate or pause"
            })

    return stalled

def detect_conflicts(workstreams, backlog_items):
    conflicts = []

    # Build dependency map
    item_deps = {item.id: item.dependencies for item in backlog_items}

    # Check each active workstream
    for ws in workstreams:
        if ws.status != "RUNNING":
            continue

        deps = item_deps.get(ws.backlog_id, [])

        # Check if any dependency is also active
        for other_ws in workstreams:
            if other_ws.id == ws.id:
                continue

            if other_ws.status == "RUNNING" and other_ws.backlog_id in deps:
                conflicts.append({
                    "type": "dependency",
                    "workstream": ws.id,
                    "depends_on": other_ws.id,
                    "reason": f"{ws.id} depends on {other_ws.backlog_id} in progress"
                })

    return conflicts

PM: [User asks for status]

Let me check with Workstream Coordinator...

[Invokes workstream-coordinator skill]
[Coordinator analyzes all workstreams]

PM: Based on coordination analysis:
    - 3 workstreams active and on track
    - 1 workstream stalled (needs attention)
    - Capacity for 2 more workstreams

    Should I investigate the stalled workstream?

PM: Mark ws-001 as completed

Coordinator: [Updates ws-001.yaml]

✓ ws-001 status updated: RUNNING → COMPLETED
  Completed at: 2025-11-21T12:30:00Z
  Total elapsed: 90 minutes

Backlog item BL-001 can now be marked DONE.

User: Morning status check

Coordinator: Good morning! Workstream Status:

Yesterday:
✓ ws-001: COMPLETED (config parser, 90 mins)
✓ ws-002: COMPLETED (CLI help, 45 mins)

Today:
⚠ ws-003: STALLED 14 hours (error handling tests)
✓ ws-004: RUNNING (API docs, 30 mins, ON TRACK)

Recommendations:
1. URGENT: Investigate ws-003 (stalled overnight)
2. Otherwise on track - capacity for 3 more workstreams

Coordinator: ⚠ Dependency Conflict

ws-006 (Add user management) depends on BL-005 (Auth system)
ws-005 is currently implementing BL-005 (estimated 2 hours remaining)

Recommendation: Pause ws-006 until ws-005 completes.
This avoids integration issues and rework.

User: Can I start 3 more workstreams?

Coordinator: Capacity Check

Current: 3 active workstreams
Requested: +3 new workstreams
Total would be: 6 workstreams
Max allowed: 5 workstreams

Answer: ⚠ NO - This would exceed capacity by 1.

Options:
1. Start 2 now (reaches capacity)
2. Wait for 1 to complete, then start 3
3. Increase max_concurrent if resources allow