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

name	description
state-hub	Coordinate repository-backed work through State Hub REST or optional MCP, including canonical workplan reads, inbox checks, task status sync, and progress logging.

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. Prefer REST/statehub for Codex. Verify /state/health identifies the expected primary, then read /workplans/ with repo/topic filters. MCP is opt-in; use get_domain_summary(domain_slug) when enabled.
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. Use workplan_id in API payloads and task queries; legacy workstream_id is accepted only for compatibility.
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 progress event. After committing workplan file changes, run uv run --project ~/repo-manager rmgr sync --path . --push. Reserve statehub fix-consistency for a separate deep audit.
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.

Canonical reads and caller attribution

Use GET /workplans/{id} and GET /tasks/?workplan_id=<id>. The /workstreams/ REST routes return 410 and the create_workstream MCP tool has been removed. Create repository-owned records in files before syncing. For direct HTTP calls, send X-StateHub-Component: <repo-slug> so a remaining legacy call can be attributed to its caller. Do not replace authoritative state_hub_workstream_id frontmatter fields; those are a separate file contract.

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_workplan(repo_id: str, title: str, topic_id?: str, slug?: str, description?: str, owner?: str, due_date?: str, planning_priority?: str, planning_order?: int) -> str
create_task(workplan_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, workplan_id?: str, task_id?: str, detail?: dict | str) -> str
record_decision(title: str, decision_type: str = "pending", topic_id?: str, workplan_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.