coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: advance retirement with SBOM receipts and caller migrations

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a06ed7-828d-7ca0-a8d4-0c3e5a0c4102
This commit is contained in:
tegwick 2026-09-05 10:24:54 +02:00
parent 74a3b22c05
commit f04de759a1
8 changed files with 1852 additions and 483 deletions
Download patch file Download diff file Expand all files Collapse all files

33
skills/state-hub/SKILL.md
View file

@ -1,6 +1,6 @@
---
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.
description: 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
@ -11,21 +11,32 @@ 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.
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. Mirror task/workstream status to
the hub at checkpoints.
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 `add_progress_event(...)`, then run the repo's
`make fix-consistency REPO=<repo-slug>` command when workplan files changed.
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
```text
@ -33,12 +44,12 @@ 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
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, 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
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:

22
skills/state-hub/references/tool-signatures.md
View file

@ -10,8 +10,8 @@ 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,
Use `get_domain_summary("infotech")` inside State Hub work. It returns the
domain topic, active workplans, blocking decisions, recent progress, repos,
and compact capability hints.
## Agent Messages
@ -30,19 +30,25 @@ REST: PATCH /messages/{message_id}/read
Use repo slugs as agent names. Use `broadcast` only for genuinely shared
coordination.
## Workstreams and Tasks
## Workplans 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_workplan(repo_id, title, topic_id?, slug?, description?, owner?, due_date?, planning_priority?, planning_order?)
REST: POST /workplans/
MCP: create_task(workstream_id, title, priority="medium", description?, assignee?, due_date?)
MCP: create_task(workplan_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}
```
For repository-owned work, write the workplan/task files and sync with Repo
Manager; the create signatures above describe the projection API. Read using
`GET /workplans/{id}` and `GET /tasks/?workplan_id=<id>`. Send
`X-StateHub-Component: <repo-slug>` on direct HTTP requests for caller attribution.
The removed workstream tools and `/workstreams/` routes are not fallbacks.
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.
@ -86,10 +92,10 @@ The endpoint rejects duplicate task ids with `400` and missing task ids with
## Progress and Decisions
```text
MCP: add_progress_event(summary, event_type="note", topic_id?, workstream_id?, task_id?, detail?)
MCP: add_progress_event(summary, event_type="note", topic_id?, workplan_id?, task_id?, detail?)
REST: POST /progress/
MCP: record_decision(title, decision_type="pending", topic_id?, workstream_id?, description?, rationale?, decided_by?, deadline?)
MCP: record_decision(title, decision_type="pending", topic_id?, workplan_id?, description?, rationale?, decided_by?, deadline?)
REST: POST /decisions/
```