Files

tegwick ad87153f2f Implement registration UX wishlist W1–W6 (260224)

W1: Document user-scope MCP config location in ~/.claude/CLAUDE.md —
    adds verification and re-registration commands, warns against
    settings.json (saves ~12K tokens per registration session).

W2: scripts/register_project.sh + make register-project —
    5-step automation: API health → topic lookup → MCP check →
    CLAUDE.md from template → progress event.

W3: state-hub/scripts/project_claude_md.template —
    parameterised CLAUDE.md with {PROJECT_NAME}/{DOMAIN}/{TOPIC_ID}
    placeholders; used by register_project.sh.

W4: Add custodian_topic_id + domain to all 6 canon project charters —
    lets agents grep for topic IDs without touching the API.

W5: state-hub/mcp_server/TOOLS.md — compact 30-line tool reference
    card; replaces reading the full server.py (~350 lines).

W6: Switch .mcp.json to absolute path + PYTHONPATH env so cwd is not
    required; add scripts/patch_mcp_cwd.py for post-registration fix.
    Update ~/.claude.json to match (cwd kept for belt-and-suspenders).

W7 (SessionStart hook) deferred: no SessionStart hook type in Claude
    Code; PreToolUse with empty matcher fires before every tool call.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-02-24 22:22:53 +01:00

2.8 KiB

Raw Blame History

State Hub MCP — Tool Reference Card

Quick reference for all 11 tools and 5 resources. Read this instead of server.py.

Query Tools (read-only)

Tool	Key Args	When to use
`get_state_summary()`	—	Session start. Full snapshot: totals, blocking decisions, blocked tasks, open workstreams, last 20 events.
`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.

Mutate Tools (each auto-emits a progress_event)

Tool	Key Args	Notes
`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
`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 and records who decided.
`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.
`update_workstream_status(workstream_id, status)`	`status`: active/blocked/completed/archived

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 Slugs

custodian · railiance · markitect · coulomb-social · personhood · foerster-capabilities

Common Patterns

# New workstream (via API — no MCP tool yet):
# POST /workstreams/ {"topic_id": "...", "slug": "...", "title": "...", "status": "active", "owner": "..."}

# Session start ritual:
get_state_summary()

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

2.8 KiB Raw Blame History