Repository navigation
Open
Description
Problem
The global WizardSession and the TUI store have become a catch-all. Every program's state lives flat on one shared object, so the core keeps growing and infrastructure code carries product knowledge it shouldn't.
Today:
src/lib/wizard-session.ts— 404 lines, ~164 fields/members on the session interface.src/ui/tui/store.ts— 944 lines, 29 explicit setters (each must remember to callemitChange()).- Program-specific state is flat on the shared session regardless of which program is running, e.g.
mcpComplete/mcpOutcome/mcpInstalledClients/mcpSuggestedPromptsDismissed,slackStepDismissed/slackConnected,skillsComplete/skillId, … These exist on the session for anauditorrevenue-analyticsrun that never touches MCP or Slack.
This violates the repo's own design discipline (AGENTS.md: product knowledge never enters infrastructure code). The store/session are machinery, but they currently know about MCP, Slack, skills, etc. Adding a program means widening the shared session and adding setters to the shared store — the bloat compounds.
Goal
Make the store and session composable and driven by program definitions (src/lib/programs/), so:
- The core session holds only program-agnostic state (install dir, credentials, detected framework, run phase, current screen).
- Each program contributes its own typed state slice (e.g.
mcp,slack,skills) declared alongside its program definition, mounted only when that program runs. - The store composes setters/selectors from the active program's slices instead of hardcoding all 29.
- Screens read/write their program's slice, not a flat global.
Sketch (not prescriptive)
- A program definition declares an optional
state: { initial, setters }slice with a typed shape. buildSession()composes core + the active program's slices; the store derives its setter surface from them (soemitChange()is wired once, generically).- Migrate the obvious clusters first:
mcp*,slack*,skill*→ owned by the programs that use them.
Acceptance criteria
- Core
WizardSessionno longer references program-specific concepts (MCP/Slack/skills/etc.). - At least the MCP, Slack, and skills state are program-owned slices, mounted only for programs that declare them.
- Store setter/selector surface is composed from active slices, not a flat hardcoded list;
emitChange()stays centralized. - Adding a new program needs no edits to the core session/store — only its own definition + slice.
-
pnpm build && pnpm testgreen; router/screen-resolution behavior unchanged.
Notes
- Read
.claude/skills/wizard-development/SKILL.md+references/ARCHITECTURE.mdfirst — this is a structural change to the pipeline's core. - Keep the nanostore single-shallow-copy + explicit-setter invariant; the change is about where slices are defined and composed, not how mutation/emit works.
Metadata
Metadata
Assignees
Labels
No labels
Activity
gewenyu99 commentedon Jun 30, 2026
Context from the self-driving runner work (#760): the composition seam is the step list / screens, not just the program id.
The runner now walks a program's step list and advances each step itself — auth authenticates, a run step runs its agent, a screen waits for the user (
advanceStepinrun-wizard.ts). State should compose the same way: a program's slice is the union of what its screens read and write, and the step list already declares which screens a program mounts. So the screen set is the natural key for which slices to mount.This is compounding in real time. Self-driving just added flat fields to the shared session —
integrate,selfDrivingHandoffConfirmed,completedRuns(pluscloudRegion/apiProjectfor auth reuse) — each used by exactly one of its screens. Anauditorrevenue-analyticsrun now carries self-driving's handoff flag for no reason. Every new program widens the global a bit more.So the slice should hang off the screen/step that owns it:
integration-check↔{ integrate }integration-detect↔ the pickedintegration+ pathself-driving-handoff↔{ selfDrivingHandoffConfirmed }{ completedRuns }buildSession()mounts the slices for the screens in the active program's step list; the store derives its setters from them; screens read their own slice instead of a flat global. Same "compose from program definitions" goal, keyed on the screens each program declares.