state-hub/dashboard/src/docs/workstreams.md

---
title: Workstreams — Reference
---

# Workstreams — Reference

A workstream is a bounded unit of work within a topic. It carries a stored
workstation label in the `status` field, an optional owner and due date, and
belongs to exactly one project domain. The Workstreams page gives you a
filtered, visual overview of active work, derived blocked state, and the
dependency graph between workstreams.

The [Daily WSJF Triage](/wsjf-triage) page is a companion review surface for
activity-core's daily recommendations. It links recommendation candidates back
to workstream detail pages when the candidate can be resolved through the
workplan index.

---

## Workstation Distribution chart

A horizontal bar chart showing the count of workstreams in each stored
workstation/status label for the current filter selection. Updates immediately
as filters change.

| Workstation | Meaning |
|---|---|
| **proposed** | Plan exists, but needs review against current repo state |
| **ready** | Reviewed and ready to execute |
| **active** | Work is in progress |
| **blocked** | Stored blocker label; the State Hub can also derive blocked state from unmet exit assertions |
| **backlog** | Intentionally parked for later |
| **finished** | Implementation is complete |
| **archived** | Closed historical record |

See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full task-flow
model including derived health labels (`needs_review`, `stalled`) and
assertion-based blocking.

---

## Filter bar

| Filter | Effect |
|---|---|
| **Domain** | Multi-select — show only workstreams from selected domains |
| **Status** | Multi-select — show only workstreams with selected workstation labels |
| **Owner** | Text substring match on the owner field (case-insensitive) |

Leaving a filter empty means "show all". All three filters combine with AND logic. Filters persist across polls — selections are not lost when the page refreshes live data.

The six domains are: `custodian`, `railiance`, `markitect`, `coulomb_social`, `personhood`, `foerster_capabilities`.

---

## All Workstreams table

| Column | Source |
|---|---|
| Title | Workstream title |
| Domain | Derived from the parent topic |
| Status | Current stored workstation/status label |
| Owner | Assigned person (or `—` if unset) |
| Due | Target completion date (or `—`) |
| Updated | Last modification timestamp |

Up to 20 rows displayed; paginate for more.

---

## Dependencies

The Dependencies section shows workstreams that have at least one `depends_on` or `blocks` relationship. Each card displays:

- **Workstream title** and current status badge
- **↳ depends on** — workstreams that must complete before this one can proceed
- **⊳ blocks** — workstreams that are waiting on this one

Dependencies are created via the MCP server:

```
create_dependency(
  from_workstream_id = "<uuid>",   # the one that depends
  to_workstream_id   = "<uuid>",   # the prerequisite
  description        = "needs auth before API can be built"
)
```

If no dependency edges exist for the current filter, the section shows an empty-state message.

---

## Creating workstreams

Via MCP:

```
create_workstream(
  topic_id    = "<uuid>",
  title       = "Build user authentication",
  description = "JWT-based auth, refresh tokens, middleware",
  status      = "ready",
  owner       = "human",
  due_date    = "2026-04-01"
)
```

Via REST:

```bash
curl -X POST http://127.0.0.1:8000/workstreams/ \
  -H "Content-Type: application/json" \
  -d '{"topic_id": "<uuid>", "title": "…", "status": "ready"}'
```

---

## Advancing a workstream

```
get_flow_state(entity_type="workstream", entity_id="<uuid>")
advance_workstation(entity_type="workstream", entity_id="<uuid>", target_workstation="finished")
```

Movement is flow-aware: the task-flow engine evaluates the target
workstation's entry assertions and returns structured blocking assertions when
the target is not reachable. Direct status patching still exists for bootstrap
and compatibility work, but normal lifecycle movement should prefer
`advance_workstation()`.

---

*Workstreams are never hard-deleted — use `archived` to close them without losing history.*