generated from coulomb/repo-seed
tegwick
fcd0f06536
Replaces the hardcoded 6-domain PostgreSQL ENUM with a first-class
`domains` DB table, and adds a `managed_repos` table for multi-repo
support per domain.
P1 — Domain as a DB entity:
- Migration b1c2d3e4f5a6: creates `domains` table, migrates topics.domain
ENUM column to domain_id FK, drops the domain ENUM type
- Domain ORM model (api/models/domain.py) + Pydantic schemas
- Domain API router: GET/POST /domains/, GET/PATCH /domains/{slug}/,
rename and archive endpoints with EP/TD cascade on rename
- Topic model updated: domain_id FK + @property domain_slug for
backwards-compatible JSON serialization (field renamed domain → domain_slug)
- TopicCreate/TopicRead updated; seed.py rewritten to use FK lookup
P2 — Multi-repo support:
- ManagedRepo ORM model (api/models/managed_repo.py) + schemas
- Repo API router: GET/POST /repos/, GET/PATCH /repos/{slug}/, archive
- Makefile: add-domain, rename-domain, add-repo, list-repos targets
- register_project.sh: verify domain via /domains/ API + POST /repos/
P3 — MCP tools & live validation:
- 6 new MCP tools: list_domains, create_domain, rename_domain,
archive_domain, list_domain_repos, register_repo
- EP/TD routers: replace hardcoded VALID_DOMAINS set with per-request
DB lookup — returns 422 with list of valid slugs on unknown domain
- State summary: adds domains: list[DomainSummary] (slug, name,
repo_count, active_workstream_count, ep_count, td_count)
- TOOLS.md updated with domain management section
P4 — Dashboard:
- New domains.md page with KPI row + domain cards + repo lists
- domains.json.py + repos.json.py data loaders
- Domains page added to observablehq.config.js nav
- workstreams.md, extensions.md, techdept.md: domain_slug fix +
dynamic domain list loaded from /domains/ API (no longer hardcoded)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
# 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_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. |
|
|
|
|
---
|
|
|
|
## 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 | |
|
|
|
|
---
|
|
|
|
## 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. |
|
|
|
|
---
|
|
|
|
## Domain Slugs
|
|
|
|
Run `list_domains()` to get the live list. Default 6: `custodian` · `railiance` · `markitect` · `coulomb_social` · `personhood` · `foerster_capabilities`
|
|
|
|
---
|
|
|
|
## Common Patterns
|
|
|
|
```python
|
|
# 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")
|
|
```
|