Repository navigation
2026 11 04 setup wizard
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: A first-launch, five-step wizard that asks who plays and which rooms the house has, then preloads heroes, chores-as-beasts and (optionally) the starter shops, powers and rewards.
Architecture: A pure planner (setupPlan) turns the wizard's answers into a BackupFile; runSetup applies it with the existing merge restore; a thin modal on XpWizardShell collects the answers. Entry points: a one-time offer on the profile screen when the game is empty, a Settings row, and an empty-bestiary prompt.
Tech Stack: Vue 3 <script setup>, Ionic 7 modals, Pinia, jest. Reuses XpWizardShell, browseLibrary / suggestBeasts (librarySuggest.ts), questFromSeed (packSeeds.ts), quickStartHero / quickStartGameMaster (quickStart.ts), buildStarterWorld.
Spec: docs/superpowers/specs/2026-11-04-setup-wizard-design.md
- Nothing is written until the summary's Begin button; quitting earlier leaves the game untouched.
- Re-runs only add or replace records the plan owns by id (merge restore); never wipe the family's own beasts, quests or art. Library ids are reused so a re-run updates instead of duplicating.
- Age bands are the library's
agevalues:little(7 and under),kid(8 to 12),teen(13 and up; the parent is alwaysteen). - Extras (shops, powers, rewards, Do/Don't rules) default on; they never overwrite a shop id that already exists.
- Existing profiles are never created, changed or deleted by the wizard.
- Game rules in pure modules under
src/lib/services/setup/with jest specs; screens stay thin. New components use<script setup lang="ts">. Sounds throughplay$fx; no Ionic alerts; toasts userpgToastOptions. - Max six heroes and 24-character names (
QUICK_START_MAX_HEROES,QUICK_START_NAME_LENGTH,heroNames). - Local checks: only the spec you touch (
chemx test tests/unit/<Spec>.spec.ts),chemx typecheck,chemx lint. Never the full suite; CI runs it on the PR.
- Every room unticked for a hero's band has no library chores: review shows "nothing common here, add your own", never an empty crash.
- Two heroes tick the same chore beast: one quest, assigned to both, not two quests with one id.
- Re-running setup after the family edited a chore beast's checklist: the merge restore overwrites only library-owned ids and the spec says so; the test pins which ids are owned.
- Profiles already exist (Quick Start was used, or a hero was added by hand): no profile is created and the existing heroes are listed with only the age asked.
- The apply step throws midway: Begin re-enables and a retry is safe (idempotent).
| File | Responsibility |
|---|---|
src/lib/services/setup/setupPlan.ts (new) |
Types, age bands, room → category, pre-ticked chores, setupPlan
|
src/lib/services/setup/setupSteps.ts (new) |
The five WizardStep<SetupDraft> definitions and the draft type |
src/lib/services/setup/runSetup.ts (new) |
isGameEmpty, existingHeroes, runSetup (storage + restore) |
src/app/SideMenu/SetupWizard/SetupWizard.vue, SetupWizard.ts, _SetupWizard.scss (new) |
The modal: draft state, one slot per step, Begin |
src/app/SideMenu/SwitchProfile/SwitchProfile.vue (modify) |
One-time offer when the game is empty |
src/app/SideMenu/XpSettings/components/GeneralSettings.vue (modify) |
"Run setup again" row |
tests/unit/setupPlan.spec.ts, setupSteps.spec.ts, runSetup.spec.ts (new) |
Unit specs |
tests/e2e/specs/setup-wizard.spec.js (new) |
Cypress smoke at 390x844 |
Files:
- Create:
src/lib/services/setup/setupPlan.ts - Test:
tests/unit/setupPlan.spec.ts
Interfaces:
-
Produces:
export type AgeBand = "little" | "kid" | "teen"; export interface SetupHero { id: string; name: string; age: number | null; existing: boolean; isParent: boolean } export interface SetupAnswers { heroes: SetupHero[]; rooms: string[]; chores: Record<string, string[]>; // hero id -> library beast ids extras: boolean; gameMaster?: QuickStartGameMaster; // only when a new parent hero must be created } export interface SetupPlan { backup: BackupFile; newProfiles: StoredProfile[] } export const bandForAge = (age: number): AgeBand; export const bandOf = (hero: SetupHero): AgeBand; // parent -> "teen"; null age -> "kid" export const categoryForRoom = (room: string): string; // a STARTER_CATEGORIES id export const suggestedChores = (band: AgeBand, rooms: readonly string[]): LibraryBeast[]; export const choreQuest = (beast: LibraryBeast, band: AgeBand, heroIds: readonly string[]): Achievement; export const setupPlan = (answers: SetupAnswers, shopsNow?: ReadonlyMap<string, unknown>, now?: Date, newId?: () => string): SetupPlan;
-
Step 1: Write the failing tests in
tests/unit/setupPlan.spec.ts, each with its assertions:bandForAge maps 7 to little, 8 and 12 to kid, 13 to teenbandOf makes the parent teen whatever the age and an unset age kid-
categoryForRoom maps bedroom/laundry/living to cat-chamber, kitchen to cat-mess-hall, yard to cat-grounds, school to cat-tower, bathroom/pets to cat-upkeep, self to cat-health, family to cat-family, and everylibraryRooms()entry maps to an id inSTARTER_CATEGORIES -
suggestedChores returns only chore beasts of that band in those rooms(every result hasage === band,roomin rooms, none classic) andreturns [] for a room with no chores of that band -
choreQuest is an individual quest assigned to the given heroes(type "individual",assigneeequals ids,beastIdequals the beast id,idequals`quest-${beast.slug}`,categoryIdfrom the room,adventureType "beast") -
choreQuest scales difficulty by band(little 1, kid 2, teen 3), scheduleweekly setupPlan: two heroes ticking the same beast make one quest assigned to both-
setupPlan: running twice gives the same quest and beast ids(ids are stable; profile ids come fromnewId) -
setupPlan: existing heroes create no profiles; new heroes create profiles via quickStartHero; a new parent creates a Game Master via quickStartGameMaster(newProfiles.lengthandisAdult) setupPlan: extras off leaves __abilities, __accessories, __shops, __dosDonts out; on includes them; a shop id already in shopsNow is not replacedsetupPlan always carries STARTER_CATEGORIES and the ticked beasts as plainBeast records
-
Step 2: Run to verify it fails. Run:
chemx test tests/unit/setupPlan.spec.ts. Expected: FAIL, module not found. -
Step 3: Implement
setupPlan.tsas signed above.suggestedChorescallsbrowseLibrary({ room, age: band, classic: false })per room and concatenates in library order.choreQuestbuildsquestFromSeed({ id, name: beast.chore, categoryId, beastId: beast.id, schedule: "weekly", difficulty })then overridestype: "individual"andassignee(the wayassignQuestsdoes).setupPlanbuilds the backup likequickStartPlan:__profiles(new only),__achievementCategories,__beasts,__achievements; whenanswers.extras, spreadbuildStarterWorld(now).storesentries for only__abilities,__accessories,__shops(minus keys inshopsNow) and__dosDonts. -
Step 4: Run to verify it passes. Run:
chemx test tests/unit/setupPlan.spec.ts. Expected: PASS. -
Step 5: Commit
git add src/lib/services/setup/setupPlan.ts tests/unit/setupPlan.spec.ts
git commit -m "feat(setup): the setup planner turns wizard answers into a backup plan"Files:
- Create:
src/lib/services/setup/setupSteps.ts - Test:
tests/unit/setupSteps.spec.ts
Interfaces:
-
Consumes:
SetupAnswers,SetupHero,bandOf,suggestedChores(Task 1);WizardStep<Draft>fromsrc/lib/services/wizard/wizardSteps.ts;heroNames,gameMasterProblemfromquickStart.ts. -
Produces:
export type SetupDraft = SetupAnswers; export const SETUP_STEPS: readonly WizardStep<SetupDraft>[]; // ids: family, house, review, extras, summary export const preTick = (draft: SetupDraft): SetupDraft; // fills `chores` from suggestedChores for heroes with no entry yet; keeps edits export const emptyDraft = (existing: SetupHero[]): SetupDraft; // extras true, no rooms
-
Step 1: Write the failing tests:
-
family step is invalid with no heroes, a blank or duplicate name, or a missing age (parent excepted); the invalid message is one line ("Name at least one hero", "Every hero needs an age") -
family step needs a Game Master name and 4-digit PIN when a new parent is added(usesgameMasterProblem) house step is invalid with no roomsreview step is invalid when a hero has no choresextras and summary steps are always validpreTick fills chores per hero from their band and rooms, and a second call keeps the parent's unticksemptyDraft marks extras true and carries the existing heroes with existing: true
-
-
Step 2: Run to verify it fails. Run:
chemx test tests/unit/setupSteps.spec.ts. Expected: FAIL. -
Step 3: Implement
setupSteps.ts. Each step is{ id, title, guide, isValid(draft) }in the family's voice (guide lines are short in-world sentences, e.g. house: "Which rooms do monsters haunt?"). Follow theWizardStepshape the Quest Wizard already uses. -
Step 4: Run to verify it passes. Run:
chemx test tests/unit/setupSteps.spec.ts. Expected: PASS. -
Step 5: Commit
git add src/lib/services/setup/setupSteps.ts tests/unit/setupSteps.spec.ts
git commit -m "feat(setup): the five wizard steps and their validity rules"Files:
- Create:
src/lib/services/setup/runSetup.ts - Test:
tests/unit/runSetup.spec.ts(copy thememory()/device()fakes fromtests/unit/quickStart.spec.ts)
Interfaces:
-
Consumes:
setupPlan,SetupAnswers,SetupPlan,SetupHero(Task 1);QuickStartDeps-style deps (storage(name),restore(file)) as inquickStart.ts. -
Produces:
export interface SetupDeps { storage: (name: string) => PackStorage; restore: (file: BackupFile) => Promise<unknown> } export const isGameEmpty = (deps?: SetupDeps): Promise<boolean>; // __beasts and __achievements both empty export const existingHeroes = (deps?: SetupDeps): Promise<SetupHero[]>; // from __profiles; age null, existing true, isParent from isAdult export const runSetup = (answers: SetupAnswers, deps?: SetupDeps): Promise<SetupPlan>;
Default deps reuse the module-level
storageOfand the first-runBackupServicemerge restore fromquickStart.ts; export those two fromquickStart.tsrather than copying them (small modify, no behaviour change). -
Step 1: Write the failing tests:
isGameEmpty is true on empty stores, false once a beast or a quest existsexistingHeroes lists profiles with existing true and the adult as isParentrunSetup restores the plan in merge mode and returns itrunSetup keeps a shop that already exists-
runSetup rejects with the restore's error and writes nothing it was not asked to(restore throws; second call succeeds with the same ids) runSetup never touches __profiles when every hero is existing
-
Step 2: Run to verify it fails. Run:
chemx test tests/unit/runSetup.spec.ts. Expected: FAIL. -
Step 3: Implement
runSetup.tsusing thereadAllpattern fromquickStart.ts(export it).runSetupreads__shopsforshopsNow, builds the plan, thendeps.restore(plan.backup). -
Step 4: Run to verify it passes. Run:
chemx test tests/unit/runSetup.spec.ts tests/unit/quickStart.spec.ts. Expected: PASS (Quick Start spec guards the exports). -
Step 5: Commit
git add src/lib/services/setup/runSetup.ts src/lib/services/core/packs/quickStart.ts tests/unit/runSetup.spec.ts
git commit -m "feat(setup): runSetup applies the plan with the merge restore"Files:
- Create:
src/app/SideMenu/SetupWizard/SetupWizard.vue,SetupWizard.ts,_SetupWizard.scss
Interfaces:
-
Consumes:
XpWizardShell(propssteps,draft,index,verb,busy,accent; emitsclose,submit; one slot per step id),SETUP_STEPS,emptyDraft,preTick(Task 2),existingHeroes,isGameEmpty,runSetup(Task 3),suggestBeastsandlibraryRooms(librarySuggest.ts),rpgToastOptions. -
Produces: component
SetupWizardpresented withmodalController.create({ component: SetupWizard, cssClass: "fullscreen" }); dismisses with{ done: true, heroCount }after Begin and{ done: false }on close. -
Step 1: Build the shell host. Load
existingHeroes()on mount intoemptyDraft. Bindv-model:index.verb="Begin".busywhilerunSetupruns. Close dismisses without writing. -
Step 2: Fill the five slots.
-
family: one row per hero (name input, age stepper; adult rows from existing profiles show age only); "Add hero" up toQUICK_START_MAX_HEROES; when no profile exists, one "Parent" row with name + 4-digit PIN feedingdraft.gameMaster. -
house: tickable room chips fromlibraryRooms(). -
review: on entering, callpreTick; per hero a section of beast cards (avatar, name, chore) with tick/untick; empty state "Nothing common here, add your own"; a type-ahead usingsuggestBeasts(text, 6, { classic: false, exclude: ticked })to add more. -
extras: one switch, on by default, with a one-line list of what it loads. -
summary: counts and per-hero chore lists; tapping a line setsindexto that step.
-
-
Step 3: Begin. Call
runSetup(draft); on success playplay$fx("select"), show a toast "Your world is ready!", dismiss{ done: true }. On error show the message in the summary, keep Begin enabled. -
Step 4: Verify by hand and by type. Run:
chemx typecheckandchemx lint. Expected: no errors. Open the modal on the running dev server (:8100) at 390x844 and walk the five steps; Begin populates the Compendium. -
Step 5: Commit
git add src/app/SideMenu/SetupWizard
git commit -m "feat(setup): the setup wizard modal on the wizard shell"Files:
- Modify:
src/app/SideMenu/SwitchProfile/SwitchProfile.vue(nearopenQuickStart, ~L601) - Modify:
src/app/SideMenu/XpSettings/components/GeneralSettings.vue - Modify: the bestiary empty state in
src/app/Admin/(find withchemx q -g "No beasts")
Interfaces:
-
Consumes:
SetupWizard(Task 4),isGameEmpty(Task 3). -
Step 1: Offer on first launch. In
SwitchProfile.vueaddopenSetupWizard()besideopenQuickStartand call it once on mount whenawait isGameEmpty()and a module-levelofferedThisSessionflag is false; set the flag when the modal closes either way so it never nags again in the session. After a finished run callloadProfiles()and show the same style of toast as Quick Start. -
Step 2: Settings row. Add "Run setup again" in
GeneralSettings.vuethat opens the same modal; it runs regardless ofisGameEmpty. -
Step 3: Empty-bestiary prompt. Where the Compendium shows an empty bestiary, add a "Run setup" button that opens the modal.
-
Step 4: Verify. Run:
chemx typecheckandchemx lint; check thatXpFirstRunTour(started fromMyPortal.ts) cannot start while the modal is open, since the modal lives on the profile screen before any hero is picked. Expected: no errors. -
Step 5: Commit
git add src/app/SideMenu src/app/Admin
git commit -m "feat(setup): offer the setup wizard on first launch, in Settings and on an empty bestiary"Files:
-
Create:
tests/e2e/specs/setup-wizard.spec.js -
Step 1: Write the spec. Fresh store, visit the app, expect the wizard offer; add one hero with an age, tick two rooms, keep the pre-ticks, leave extras on, Begin; assert the toast and that the Compendium bestiary and quest list are non-empty. Follow the
cy.tapToWakeAudio()convention of the existing specs. -
Step 2: Run against the shared dev server. Run:
pnpm vue-cli-service test:e2e --headless --browser chrome --url http://localhost:8100 --spec tests/e2e/specs/setup-wizard.spec.js. Expected: PASS. (Do not start a second dev server; ifcurl -s localhost:8100fails, ask first.) -
Step 3: Commit
git add tests/e2e/specs/setup-wizard.spec.js
git commit -m "test(setup): the setup wizard end to end at phone size"- Spec coverage: section 3 (when it runs) is Task 5; section 4 (steps) Tasks 2 and 4; section 5 (design) Tasks 1 and 3; sections 6 and 7 are Review Focus plus the specs. Open items are resolved: the offer lives on the profile screen (the tour starts later in
MyPortal), profiles have no age field so age only picks the band (SetupHero.ageis draft-only), and an existing Game Master appears as an existing hero row withisParent. - Types match across tasks:
SetupHero,SetupAnswers,SetupPlan,SetupDraft = SetupAnswers,SetupDeps. - Defaults I chose where the spec was silent, editable later in the Compendium: weekly schedule, difficulty 1/2/3 by band, room → category map in Task 1.
- Architecture
- Component-Library
- Hooks-Reference
- Temple-System
- Battle-Field-Architecture
- current_context - For AI/Human Handoff
- User Menu
- General Settings
- Family Settings
- Sound Settings
- Notification Settings
- Reward Settings
- Party Settings
- Theme Settings
- Chore Settings