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

title

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 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 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:

curl -X POST http://127.0.0.1:8000/workplans/ \
  -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.