state-hub/skills/state-hub/SKILL.md

---

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

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:

{
  "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.