the-custodian/roadmap/state-hub-v0.2/PLAN.md

title, domain, workstream_slug, status, created

title	domain	workstream_slug	status	created
State Hub v0.2 — Decisions, Suggestions & Dependencies	custodian	state-hub-v0.2	active	2026-02-25

State Hub v0.2 — Decisions, Suggestions & Dependencies

Purpose

Evolve the State Hub from a cross-domain state tracker to an active coordination layer.

Three additions:

1. Design boundary clarity — formalise the "observation + 2 write exceptions" model across all integration surfaces
2. Workstream dependency graph — track, query, and visualise how workstreams depend on each other across domains
3. Suggesting Next Steps — surface contextual next-action suggestions derived from hub state (post-decision unlocks, unblocked dependencies, high-priority open tasks)

Design Boundary

The State Hub is a read model with exactly two bounded write operations:

Use Case	Rationale
Resolving Decisions	Decisions are cross-cutting artefacts; their resolution must propagate to all parties watching a domain, not just the project file
Suggesting Next Steps	Bridge between hub overview and domain action; the hub surfaces what, where, and why — the domain owns the how

All other write operations (create_workstream, create_task) are bootstrapping utilities (First Session Protocol), not general-purpose project management. Formal work structure — requirements, workplans, milestones — belongs in domain repos.

What is out of scope

The Custodian as acting agent (LLM-powered autonomous reasoning and tool use) is a separate concern and a separate workstream (custodian-agent-runtime). It will:

• Be built on top of markitect's llm-shared-library (llm-connect), not on Claude Code
• Not live in the-custodian repo directly — the repo provides its State Hub environment, not its runtime
• Only begin after markitect/llm-shared-library reaches a stable installable state

---

Stages

S0 — Design Boundary Cleanup

Establish the "observation + 2 exceptions" principle in all integration surfaces before adding new write operations.

#	Task	Priority
S0.1	Update TOOLS.md, project CLAUDE.md template, and global CLAUDE.md to reflect the observation model and two write use cases	medium
S0.2	Mark create_workstream / create_task MCP tools and CLI commands as "bootstrap-only" with a note pointing to the domain as the authoritative source	medium

---

S1 — Workstream Dependency Graph

Add a directed dependency graph to the schema: workstream A depends on workstream B means B must reach a certain state before A can fully proceed.

Schema addition: WorkstreamDependency(id, from_workstream_id, to_workstream_id, description, created_at) — directed edge, FK-constrained, no soft-delete (hard delete is safe here as it removes a constraint, not information).

#	Task	Priority
S1.1	DB model + Alembic migration for WorkstreamDependency	high
S1.2	API: POST /workstreams/{id}/dependencies/, GET /workstreams/{id}/dependencies/, DELETE /workstreams/{id}/dependencies/{dep_id}	high
S1.3	Enrich /state/summary → open_workstreams[] with depends_on and blocks lists	high
S1.4	MCP tools: create_dependency(from_ws_id, to_ws_id, description?), list_dependencies(workstream_id?)	medium
S1.5	Dashboard workstreams page: show depends-on and blocks lists on each workstream card	medium

---

S2 — Suggesting Next Steps

Derive contextual next-action suggestions from resolved decisions, newly unblocked dependencies, and high-priority open tasks. Suggestions are read-only — they point to where work should happen, they don't create it.

Suggestion schema (derived, not persisted):

{
  "type": "unblocked_task | resolved_decision | dependency_cleared",
  "domain": "markitect",
  "workstream_id": "...",
  "workstream_title": "LLM Adapter Layer",
  "message": "D1 resolved → S2.1 (create package scaffold) is now the highest-priority open task",
  "project_path": "/home/worsch/markitect_project",
  "task_id": "...",
  "task_title": "S2.1 — Resolve D1 and create package scaffold"
}

#	Task	Priority
S2.1	API: GET /state/next_steps — derive suggestions from current hub state (recently resolved decisions → open tasks in same workstream; cleared dependencies → first open task in now-unblocked workstream)	high
S2.2	Enrich get_state_summary() response with next_steps list	high
S2.3	MCP tool: get_next_steps() — returns suggestions with domain, workstream, task, project_path, and a plain-language message	high
S2.4	Dashboard overview: "What's next?" section — cards per suggestion with domain badge and link context	medium

---

S3 — Integration & Validation

#	Task	Priority
S3.1	Seed known inter-domain dependencies: custodian-agent-runtime ← markitect/llm-shared-library; railiance as infrastructure dependency for all deployment-bound workstreams	medium
S3.2	End-to-end test: resolve a decision → confirm next_steps surfaces correct task → confirm Claude in domain picks it up via get_next_steps() in session start	medium
S3.3	Update all registered project CLAUDE.mds to include get_next_steps() call in session start protocol	low

---

Dependencies

• S1.1 blocks all of S1 and all of S2 (summary enrichment needs the dependency data)
• S0 has no blockers — can start immediately
• This workstream has no external dependencies (the State Hub is self-contained)
• The custodian-agent-runtime workstream depends on this workstream reaching S1 completion and on markitect/llm-shared-library reaching a stable installable state

Known Decisions

None open at the time of writing.