From e7a14456bd0e73dd4259cb45f909467ff6033e23 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 25 Feb 2026 16:55:58 +0100 Subject: [PATCH] Add State Hub v0.2 workplan and register in hub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit roadmap/state-hub-v0.2/PLAN.md covers three stages: - S0: Design boundary cleanup (observation + 2 write exceptions) - S1: Workstream dependency graph (schema → API → MCP → dashboard) - S2: Suggesting Next Steps (derived endpoint → MCP tool → dashboard) - S3: Integration, seeding known deps, CLAUDE.md rollout Registered in State Hub: - Workstream 6585ee66: State Hub v0.2 — Decisions, Suggestions & Dependencies (7 tasks, all todo) - Workstream a2d9919d: Custodian Agent Runtime — Bootstrap (2 tasks; bootstrap task marked blocked on markitect/llm-shared-library) Co-Authored-By: Claude Sonnet 4.6 --- roadmap/state-hub-v0.2/PLAN.md | 115 +++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 roadmap/state-hub-v0.2/PLAN.md diff --git a/roadmap/state-hub-v0.2/PLAN.md b/roadmap/state-hub-v0.2/PLAN.md new file mode 100644 index 0000000..c8a6101 --- /dev/null +++ b/roadmap/state-hub-v0.2/PLAN.md @@ -0,0 +1,115 @@ +--- +title: "State Hub v0.2 — Decisions, Suggestions & Dependencies" +domain: custodian +workstream_slug: state-hub-v0.2 +status: active +created: 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):** +```json +{ + "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.