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 status, an optional owner and due date, and belongs to exactly one of the six project domains. The Workstreams page gives you a filtered, visual overview of all active work and the dependency graph between workstreams.

---

## Status Distribution chart

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

| Status | Meaning |
|---|---|
| **active** | Work in progress or ready to start |
| **blocked** | Waiting on something outside the workstream — see Dependencies |
| **completed** | Formally accepted after custodian review (shown as **accepted** in the overview chart) |
| **archived** | Closed without completion; no longer relevant |

See [Workstream Lifecycle](/docs/workstream-lifecycle) for the full state model including derived states (finished, stalled, oldies).

---

## Filter bar

| Filter | Effect |
|---|---|
| **Domain** | Multi-select — show only workstreams from selected domains |
| **Status** | Multi-select — show only workstreams with selected statuses |
| **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 workstream status |
| 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      = "active",
  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": "active"}'
```

---

## Updating workstream status

```
update_workstream_status(workstream_id="<uuid>", status="completed")
```

Valid transitions: `active` → `blocked` / `completed` / `archived`; `blocked` → `active`; `completed` → `archived`.

---

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