state-hub/mcp_server/TOOLS.md

State Hub MCP — Tool Reference Card

Quick reference for all tools and resources.

Design Boundary

The State Hub is a read model. It observes and visualises cross-domain state that originates in the projects themselves.

Two write operations are permanently sanctioned:

Use Case	Tools
Resolving Decisions	resolve_decision() — decisions are cross-cutting; resolution must propagate across all domains
Suggesting Next Steps	get_next_steps() (v0.2) — surface what is unblocked; the domain does the work

All other mutate tools are bootstrap-only: use them during First Session Protocol to give a freshly-registered project its initial workstream structure. Do not use them as a substitute for formal work definition inside the domain repo.

---

Query Tools (read-only, use freely)

Tool	Key Args	When to use
get_domain_summary(domain_slug)	domain_slug: e.g. "railiance"	Domain session start. Scoped snapshot: active workstreams, blocking decisions, last 5 events, repo SBOM status — ~10% of get_state_summary() token cost.
get_state_summary()	—	Cross-domain work / custodian sessions. Full snapshot: totals, all blocking decisions, all blocked tasks, all open workstreams, last 20 events. Large (~10k tokens).
get_topic(slug)	slug: e.g. "markitect"	Deep-dive on one topic + its workstreams + recent events.
list_blocked_tasks(workstream_id?)	optional filter	Surface all impediments, optionally scoped to one workstream.
list_pending_decisions(topic_id?)	optional filter	Decisions holding up work, sorted by deadline.
get_recent_progress(limit, since?)	limit default 20; since ISO datetime	Reconstruct recent session history.

---

Sanctioned Write Tools

Tool	Key Args	Notes
record_decision(title, ...)	decision_type: made/pending; topic_id?; workstream_id?; deadline?	Financial/legal + pending → auto-escalated per constitution §4. At least one of topic_id/workstream_id required.
resolve_decision(decision_id, rationale, decided_by)	all required	Marks decision resolved, emits progress event, writes DECISIONS.md to project directory.
add_progress_event(summary, ...)	event_type: note/milestone/blocker/insight; topic_id?; workstream_id?; task_id?; detail?	Append-only log entry. Use at session end.

---

Bootstrap-Only Tools

Use during First Session Protocol to give a freshly-registered project its initial workstream structure. Do not use for ongoing project management — formal work structure belongs in the domain repo (workplans, requirements, milestones).

Tool	Key Args	Notes
create_workstream(topic_id, title, ...)	slug?; owner?; description?; due_date?	Creates workstream under a topic. Use get_state_summary() to find topic IDs.
create_task(workstream_id, title, ...)	priority: low/medium/high/critical; assignee?; due_date?	Creates task under a workstream.
update_task_status(task_id, status, ...)	status: todo/in_progress/blocked/done/cancelled; blocking_reason required when blocked
update_workstream_status(workstream_id, status)	status: active/blocked/completed/archived	Thin shortcut — use update_workstream for full field control.
update_workstream(workstream_id, ...)	title?; description?; owner?; due_date?; repo_goal_id?; status?	Patch any subset of workstream fields. Pass empty string for repo_goal_id to clear the link.

---

Human Interventions

Tasks that agents cannot complete themselves are flagged with needs_human=True. Use list_human_interventions() at session start to see Bernd's action items.

Tool	Key Args	Notes
flag_for_human(task_id, note)	task_id: UUID; note: action description (required)	Sets needs_human=True + intervention_note. Emits progress event.
clear_human_flag(task_id)	task_id: UUID	Clears flag after human completes the action. Emits progress event.
list_human_interventions(workstream_id?)	optional workstream filter	Returns all tasks with needs_human=True.

---

Governance Tools

Tool	Key Args	When to use
validate_repo_adr(repo_path, domain_slug?)	repo_path: absolute path; domain_slug?: for orphan detection	Check a repo against ADR-001. Detects missing workplans/ dir, invalid frontmatter, stale workstream ID references, and DB-only orphan workstreams. Run before and after any workplan changes.

---

Resources (URI-addressable, read-only)

URI	Returns
state://summary	Full StateSummary JSON
state://topics	Active topics list
state://workstreams/{topic_slug}	Workstreams for a topic (by slug)
state://decisions/blocking	All pending decisions
state://tasks/blocked	All blocked tasks

---

Domain Management Tools (v0.5)

Domains are now first-class DB entities. Use list_domains() to discover available slugs.

Tool	Key Args	Notes
list_domains(status?)	status: active/archived/all (default: active)	Discover all registered domains.
create_domain(slug, name, description?)	slug: lowercase_underscored; name: display name	Register a new project domain.
rename_domain(slug, new_slug, new_name)	all required	Renames domain and cascades to EP/TD string columns.
archive_domain(slug)	slug	Soft-delete; fails if active topics exist.
list_domain_repos(domain_slug)	domain_slug	List repos registered under a domain.
register_repo(domain_slug, name, ...)	slug?; local_path?; remote_url?	Register a git repo under a domain.

---

Agent Inbox Tools

Inter-agent coordination via shared message board. Check inbox at session start; send messages to coordinate across Claude instances.

Agent names: use the repo slug (e.g. "marki-docx", "railiance") or "hub" for the custodian agent. Use "broadcast" as to_agent to send to all agents.

Tool	Key Args	When to use
get_messages(to_agent?, from_agent?, unread_only?, limit?)	to_agent: your agent name; unread_only: True recommended at session start	Check for pending coordination messages.
send_message(from_agent, to_agent, subject, body, thread_id?)	all except thread_id required	Send a coordination message to another agent (or broadcast).
mark_message_read(message_id)	message_id: UUID	Mark a message as read after acting on it.
reply_to_message(message_id, from_agent, body)	all required	Reply in-thread; marks original as read.

Dashboard: http://localhost:3000/inbox

---

Domain Slugs

Run list_domains() to get the live list. Default 6: custodian · railiance · markitect · coulomb_social · personhood · foerster_capabilities

---

Common Patterns

# Session start:
get_state_summary()

# Decision resolved in the hub UI or via tool:
resolve_decision(decision_id="<uuid>", rationale="...", decided_by="Bernd")

# Session end:
add_progress_event(
    summary="...",
    event_type="note",          # or milestone / insight / blocker
    topic_id="<uuid>",
    workstream_id="<uuid>",     # optional
    detail={"key": "value"},    # optional
)

# First Session Protocol only — bootstrap a new project:
create_workstream(topic_id="<uuid>", title="My Workstream", owner="me")
create_task(workstream_id="<uuid>", title="Do the thing", priority="high")