feat: add State Hub bulk status skill

skills/state-hub/SKILL.md

@@ -0,0 +1,65 @@
+---
+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.
+
+## 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`.

skills/state-hub/references/tool-signatures.md

@@ -0,0 +1,97 @@
+# State Hub Tool Signatures
+
+Load this reference when a session needs exact REST fallback paths or batched
+write payloads.
+
+## Orientation
+
+```text
+MCP: get_domain_summary(domain_slug)
+REST: GET /state/summary then filter by topic/domain when MCP is unavailable
+```
+
+Use `get_domain_summary("custodian")` inside State Hub work. It returns the
+domain topic, active workstreams, blocking decisions, recent progress, repos,
+and compact capability hints.
+
+## Agent Messages
+
+```text
+MCP: get_messages(to_agent?, from_agent?, unread_only?, limit?)
+REST: GET /messages/?to_agent=<repo>&unread_only=true
+
+MCP: send_message(from_agent, to_agent, subject, body, thread_id?)
+REST: POST /messages/
+
+MCP: mark_message_read(message_id)
+REST: PATCH /messages/{message_id}/read
+```
+
+Use repo slugs as agent names. Use `broadcast` only for genuinely shared
+coordination.
+
+## Workstreams and Tasks
+
+```text
+MCP: create_workstream(topic_id, title, slug?, description?, owner?, due_date?, repo_id?, planning_priority?, planning_order?)
+REST: POST /workstreams/
+
+MCP: create_task(workstream_id, title, priority="medium", description?, assignee?, due_date?)
+REST: POST /tasks/
+
+MCP: update_task_status(task_id, status, blocking_reason?, tokens_in?, tokens_out?, workplan_tokens_in?, workplan_tokens_out?, note?, model?, agent?, session_id?)
+REST: PATCH /tasks/{task_id}
+```
+
+Canonical task statuses are `wait`, `todo`, `progress`, `done`, and `cancel`.
+Legacy aliases are accepted during migration, but do not emit new workplan files
+with old vocabulary.
+
+## Bulk Task Status Sync
+
+```text
+MCP: bulk_update_task_statuses(updates, author?, session_id?)
+REST: POST /tasks/bulk-status-sync
+```
+
+Payload:
+
+```json
+{
+  "updates": [
+    {"task_id": "uuid-1", "status": "progress"},
+    {"task_id": "uuid-2", "status": "done"},
+    {"task_id": "uuid-3", "status": "wait", "blocking_reason": "needs approval"}
+  ],
+  "author": "codex",
+  "session_id": "optional-session-id"
+}
+```
+
+Response:
+
+```json
+{
+  "updated": [
+    {"id": "uuid-1", "status": "progress", "...": "..."}
+  ],
+  "progress_event_ids": ["event-uuid-1"]
+}
+```
+
+The endpoint rejects duplicate task ids with `400` and missing task ids with
+`404` before changing any task. Each successful item emits one
+`task_status_changed` progress event with `detail.bulk_status_sync = true`.
+
+## Progress and Decisions
+
+```text
+MCP: add_progress_event(summary, event_type="note", topic_id?, workstream_id?, task_id?, detail?)
+REST: POST /progress/
+
+MCP: record_decision(title, decision_type="pending", topic_id?, workstream_id?, description?, rationale?, decided_by?, deadline?)
+REST: POST /decisions/
+```
+
+Prefer one progress event per checkpoint. A useful close event says what changed,
+which tests ran, whether consistency sync passed, and what remains.