tegwick
f8bd74e27e
Align agent close/workplan finish with fleet residual convention (live work records, origin residual + origin_ref). Reference pages for work-records and intakes; session and workplan templates updated.
69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
---
|
|
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`.
|