docs: spec — trim onboarding from 12 steps to 5 - #256
Open
oxedom wants to merge 2 commits into
Open
Conversation
Cuts the first-run wizard to five screens: intro, name, what-is-a-Cabinet, create-Cabinet (with provider detection resolving inline), and launch. The knowledge-graph, hire-agent, and first-task steps are disabled behind a flag rather than deleted, and agent creation moves to the tour tail. Adds CONTEXT.md as the vocabulary glossary and ADR-0001 recording that "Cabinet" is the only user-facing noun, which is why homeName, roomType, and workspaceName appear in code with no matching words in the UI. Verification overturned several drafting assumptions: step 7's firstTask is never persisted, the tour already runs the real task flow, step 4 is not a modal, and the repo has neither a feature-flag pattern nor a component-test stack. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The text said eight index-dependent sites; the table lists fourteen. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design spec only. No code changes. Also adds
CONTEXT.md(the vocabulary glossary) and ADR-0001.The goal
The first-run wizard is 12 steps (
onboarding-wizard.tsx, 3,607 lines,STEP_COUNT = 12at:155). Only five collect anything that survives launch. The rest are intro, explainer, or community/marketing screens sitting between "I opened the app" and "I can use it".The new flow: five screens
Disabled behind a flag, not deleted: knowledge graph (3), hire first agent (6), first task (7). Step 6 doesn't leave the product, it moves after onboarding into the tour tail. The wizard's job is to get the user into a Cabinet, not to populate it.
Provider detection auto-selects the first ready CLI and stays optional — "0 ready" is treated as the default case, since a fresh machine with no agent CLI installed is the common first run.
What verification changed
The spec was written first, then checked line-by-line. Seven claims were wrong, each changing the work:
firstTask(:1807) is read only by its own field and a preview caption. It is not in thelaunch()payload and appears nowhere in the setup route. The step asks the user for a first task and silently throws it away — it's decorative, so there's no data-loss question to answer.onLaunchTaskis already the real task flow (handleLaunchTourTask→ realStartWorkDialogwith the live roster). The missing half is agent creation, not task creation.:2469-2578is a plain centred form). The draft's "modal with a fetch resolving behind it" described nothing that exists.NEXT_PUBLIC_CABINET_EDITION. The spec proposes one rather than reusing one..test.tsonly), so the draft's component tests were unbuildable.home-blueprint-background.tsxis the welcome step's background — flagging it off with the knowledge step would have broken screen 2.Main risk: index-shifting
STEP_COUNTis hardcoded and 14 other sites key off the same integers. The spec tables all of them. The nastiest is the index-keyedSTEP_NAMEStelemetry map (:1646-1659) — a wrong entry emits valid, mislabelled funnel data that nothing catches.Server tolerance was verified by reading the route:
/api/onboarding/setuphas no schema validation and guardsfirstAgent, so dropping steps 6/7 will not break it.Pre-existing bugs surfaced (not fixed here)
launch()never checksres.ok(:2077). A 500 from/api/onboarding/setupresolves,onComplete()runs, andwizard-done="1"is written for a Cabinet that was never created. The trim must not inherit this.:2476-2477reads "Your room is your workspace. Inside your room you have one big cabinet…" — both banned nouns, in the exact screen this spec merges.Note on scope
CONTEXT.mdlands in this PR since ADR-0001 (vocabulary) is core to it, but the glossary is repo-wide and also defines the Template/Library terms used by the templates spec.See ADR-0001.
🤖 Generated with Claude Code