---
title: Workplans — Reference
---

# Workplans — Reference

A **workplan** is a work-record kind: a bounded, dependency-bearing unit of
work within a topic. It carries a stored lifecycle label in the `status`
field, an optional owner and due date, and belongs to exactly one project
domain. The Workplans page gives you a filtered, visual overview of active
work, derived blocked state, and the dependency graph between workplans.

Umbrella: [Work Records](/docs/work-records). Lifecycle detail:
[Workplan Lifecycle](/docs/workstream-lifecycle).

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

---

## Workstation Distribution chart

A horizontal bar chart showing the count of workplans 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 [Workplan 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 workplans from selected domains |
| **Status** | Multi-select — show only workplans 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 Workplans table

| Column | Source |
|---|---|
| Title | Workplan 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 workplans that have at least one `depends_on` or `blocks` relationship. Each card displays:

- **Workplan title** and current status badge
- **↳ depends on** — workplans that must complete before this one can proceed
- **⊳ blocks** — workplans 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 workplans

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/workplans/ \
  -H "Content-Type: application/json" \
  -d '{"topic_id": "<uuid>", "title": "…", "status": "ready"}'
```

---

## Advancing a workplan

```
get_flow_state(entity_type="workplan", entity_id="<uuid>")
advance_workstation(entity_type="workplan", 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()`.

---

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