generated from coulomb/repo-seed
tegwick
d86b3cec14
T01: copy agent-scope-analyst.md to the-custodian/agents/
T02: add scope.template, prepend @SCOPE.md to claude-md.template,
update register_project.sh to write SCOPE.md stub on new registration,
add scope-analyst row to TOOLS.md
T03: SCOPE.md for the-custodian itself
Workplan: CUST-WP-0017 registered in state-hub
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
9.2 KiB
9.2 KiB
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. |
update_repo_path(repo_slug, path, host?) |
repo_slug: e.g. "marki-docx"; path: absolute local path; host: defaults to current hostname |
Register this machine's local path for a repo. Use when the same repo lives at different paths on different machines (e.g. /home/worsch/… vs /home/tegwick/…). The consistency checker prefers this over local_path. |
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
Kaizen Agents
Specialized agent personas from kaizen-agentic/agents/. Each agent is a markdown
instruction set — load it and follow the instructions it contains.
| Tool | Key Args | When to use |
|---|---|---|
list_kaizen_agents(category?) |
category: optional filter (testing/quality/process/infrastructure) |
Discover all 17 available agent personas with name, description, category. |
get_kaizen_agent(name) |
name: e.g. "tdd-workflow", "code-refactoring" |
Load full agent instructions. Read and follow them. |
Common agents:
| Agent | Category | When to use |
|---|---|---|
tdd-workflow |
testing | Step-by-step TDD8 workflow for any feature |
code-refactoring |
quality | Code quality analysis and safe refactoring |
test-maintenance |
testing | Diagnose and fix failing tests |
requirements-engineering |
process | Prevent interface/mock mismatches upfront |
keepaTodofile |
process | Maintain TODO.md during work |
project-management |
process | Track status, determine next steps |
scope-analyst |
project-management | Analyze a repo and produce/improve SCOPE.md |
datamodel-optimization |
quality | Optimize dataclasses and data structures |
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")