---
name: state-hub
description: Use when coordinating with Custodian State Hub: orienting with domain summaries, checking agent inbox messages, updating workplan-backed task status, recording decisions/progress, or batching task status sync through MCP/REST without re-discovering tool schemas.
---

# State Hub Coordination

Use this skill at the start and close of State Hub aware coding sessions. The
hub is a read/cache/index model over repo-owned workplan files; do not invent
work structure in the hub when a workplan file is the canon.

## Session Flow

1. Orient with `get_domain_summary(domain_slug)` when working inside one domain
   repo. Use `get_state_summary()` only for cross-domain/custodian-wide work.
2. Check inbox with `get_messages(to_agent=<repo-slug>, unread_only=true)`.
   Mark acted-on messages with `mark_message_read(message_id)`.
3. During work, edit the workplan file first. Mirror task/workstream status to
   the hub at checkpoints.
4. Prefer `bulk_update_task_statuses(...)` for checkpoint syncs with multiple
   task updates. Use `update_task_status(...)` for one-off changes.
5. Close with one concise `add_progress_event(...)`, then run the repo's
   `make fix-consistency REPO=<repo-slug>` command when workplan files changed.
6. If finishing a workplan with leftovers: create **residual** work records
   first (intake with `origin: residual` + `origin_ref: <WP-id>`, or a child
   workplan). Residual is a role, not a kind; do not leave backlog only in
   finished-file prose or `SCOPE.md`. Canon: work-record-types § Residuals.

## High-Frequency MCP Signatures

```text
get_domain_summary(domain_slug: str) -> str
get_messages(to_agent?: str, from_agent?: str, unread_only: bool = false, limit: int = 20) -> str
send_message(from_agent: str, to_agent: str, subject: str, body: str, thread_id?: str) -> str

create_workstream(topic_id: str, title: str, slug?: str, description?: str, owner?: str, due_date?: str, repo_id?: str, planning_priority?: str, planning_order?: int) -> str
create_task(workstream_id: str, title: str, priority: str = "medium", description?: str, assignee?: str, due_date?: str) -> str
update_task_status(task_id: str, status: str, blocking_reason?: str, tokens_in?: int, tokens_out?: int, workplan_tokens_in?: int, workplan_tokens_out?: int, note?: str, model?: str, agent?: str, session_id?: str) -> str
bulk_update_task_statuses(updates: list[dict], author?: str = "custodian", session_id?: str) -> str
add_progress_event(summary: str, event_type: str = "note", topic_id?: str, workstream_id?: str, task_id?: str, detail?: dict | str) -> str
record_decision(title: str, decision_type: str = "pending", topic_id?: str, workstream_id?: str, description?: str, rationale?: str, decided_by?: str, deadline?: str) -> str
```

`bulk_update_task_statuses` updates `N` task statuses in one call:

```json
{
  "updates": [
    {"task_id": "<uuid>", "status": "progress"},
    {"task_id": "<uuid>", "status": "wait", "blocking_reason": "waiting for operator"}
  ],
  "author": "codex",
  "session_id": "<optional-session-id>"
}
```

Each bulk item emits a `task_status_changed` progress event. Keep separate
progress notes coarse: milestones, blockers, handoffs, or final summaries.

## Boundaries

- Canon lives in files: workplans, `INTENT.md`, repo docs, and commits.
- The hub indexes and broadcasts state; it is not a substitute workplan author.
- For new multi-step work, create or update the workplan file, then sync.
- If MCP returns an error payload, use the matching REST endpoint as fallback
  and record what happened once the write succeeds.

For REST paths, response shapes, and fallback examples, read
`references/tool-signatures.md`.