Switchyard Implementation Checklist

April 17, 2026 ยท View on GitHub

Status: baseline delivered; execution-plane unification delivered on 2026-04-16 Scope: current workspace architecture, Workbench framework extraction, execution-plane unification, Switchyard TUI rewrite, integration migration, and delivery verification

Required Reading

Read these before making structural changes:

  1. README.md
  2. guides/index.md
  3. guides/current_state.md
  4. guides/vision.md
  5. guides/monorepo_strategy.md
  6. guides/package_boundaries.md
  7. guides/runtime_model.md
  8. guides/workspace_workflow.md
  9. guides/testing_and_delivery.md
  10. build_support/workspace_contract.exs
  11. build_support/dependency_resolver.exs
  12. build_support/weld.exs
  13. core/workbench_node_ir/README.md
  14. core/workbench_tui_framework/README.md
  15. core/workbench_widgets/README.md
  16. core/workbench_devtools/README.md
  17. apps/terminal_workbench_tui/README.md
  18. apps/terminal_workbench_tui/lib/switchyard/tui/root.ex
  19. apps/terminal_workbench_tui/lib/switchyard/tui/state.ex
  20. core/workbench_tui_framework/lib/workbench/runtime.ex
  21. core/workbench_tui_framework/lib/workbench/effects.ex
  22. core/workbench_process_runtime/README.md
  23. core/workbench_process_runtime/lib/switchyard/process_runtime.ex
  24. core/workbench_daemon/README.md
  25. core/workbench_daemon/lib/switchyard/daemon/server.ex
  26. apps/terminal_workbench_cli/README.md
  27. apps/terminal_workbench_cli/lib/switchyard/cli.ex
  28. apps/terminal_workbench_tui/README.md
  29. apps/terminal_workbench_tui/lib/switchyard/tui.ex
  30. apps/terminal_workbench_tui/lib/switchyard/tui/cli.ex
  31. apps/terminal_workbench_tui/lib/switchyard/tui/root.ex
  32. sites/site_local/README.md
  33. sites/site_local/lib/switchyard/site/local.ex
  34. sites/site_execution_plane/README.md
  35. sites/site_execution_plane/lib/switchyard/site/execution_plane.ex
  36. sites/site_jido/README.md
  37. sites/site_jido/lib/switchyard/site/jido.ex
  38. ../ex_ratatui/lib/ex_ratatui/command.ex
  39. ../ex_ratatui/lib/ex_ratatui/subscription.ex

Invariants

  1. The root is a workspace and docs layer, not a true umbrella.
  2. The daemon owns durable local operational state.
  3. The execution plane owns command placement and sandbox honesty.
  4. The shell owns pure product navigation state.
  5. The Workbench runtime owns generic terminal execution concerns.
  6. Sites own domain mapping and actions.
  7. ex_ratatui transport serves the UI layer, not managed process execution.
  8. Greenfield solutions only: no workarounds, no compatibility shims, no backwards-compatibility layers.

Live Checklist

Phase 0: Baseline

  • Confirm repo state with git status --short --branch.
  • Confirm required reading against the current codebase.
  • Confirm root mix ci is green after the current implementation run.

Phase 1: Framework Packages

  • Add core/workbench_tui_framework.
  • Add core/workbench_node_ir.
  • Add core/workbench_widgets.
  • Add core/workbench_devtools.
  • Update dependency resolution and Weld roots for the new packages.
  • Keep package docs and READMEs aligned with the delivered public surface.

Phase 2: Framework Runtime

  • Add the Workbench component contract.
  • Add context, screen, capability, node, and runtime index structures.
  • Add render tree, focus tree, and region map structures.
  • Add keymap, action, effect, transcript, and renderer seams.
  • Add the thin runtime bridge to ex_ratatui.
  • Expand runtime tests as the public surface grows.

Phase 3: Product TUI Rewrite

  • Replace the legacy mounted-app path with framework-native components.
  • Introduce a thin product app bridge over Workbench.Runtime.
  • Add a Switchyard root component and product state module.
  • Delete the old Command, Controller, Keymap, Model, Mount, Renderer, and ScreenUI modules.
  • Keep the daemon as the operational authority.

Phase 4: Integration Migration

  • Migrate Jido Hive to AppDescriptor.tui_component.
  • Replace RoomsMount with a framework-native component.
  • Move room/runtime/view integration to Workbench widgets and commands.
  • Re-prove the integration seam with tests.

Phase 5: Docs And Delivery

  • Update all repo guides and package READMEs to match the delivered architecture.
  • Run mix mr.format --check-formatted.
  • Run mix mr.compile.
  • Run mix mr.test.
  • Run mix mr.credo --strict.
  • Run mix mr.dialyzer.
  • Run mix mr.docs --warnings-as-errors.
  • Run mix weld.verify.
  • Run root mix ci.

Final Validation Record

  • mix ci
  • mix weld.verify
  • mix mr.compile
  • mix test in jido_hive_switchyard_site
  • mix test in jido_hive_switchyard_tui
  • mix mr.compile in ~/p/g/n/jido_hive

Packaging Note

The welded switchyard_foundation monolith remains an internal artifact and keeps hex_build: false in the Weld manifest.

That does not change the repo's publication posture:

  1. the runtime is designed against the published ex_ratatui Hex package
  2. the welded artifact is still tracked internally through bundle, projection, and archive steps
  3. release.publish remains out of scope for this repo

Current internal artifact operations therefore run through:

  1. mix release.prepare
  2. mix release.track
  3. mix release.archive

mix release.track updates the orphan-backed projection/switchyard_foundation branch so downstream repos can pin a real generated-source ref before any formal release boundary exists.

Keep the committed workspace dependency on the released Hex Weld line. If a coordinated prerelease Weld validation run is needed, do it through a normal prerelease version bump rather than through committed path or git overrides.

Recontextualization Instructions

If work resumes after compaction:

  1. Read this file top to bottom.
  2. Re-read the required reading list.
  3. Confirm current repo state with git status --short --branch.
  4. Confirm workspace state with mix mr.compile, mix mr.test, and mix ci.
  5. Resume from the earliest unchecked item.

TDD / RGR Rule

Wherever behavior is being introduced, use:

  1. red: write the failing test
  2. green: implement the minimum coherent behavior
  3. refactor: improve names, structure, and documentation without weakening the seam

The framework and product TUI should continue to grow by proving the seam first and only then broadening the surface.