Skip to content

2026 11 04 setup wizard

Xopher edited this page Nov 4, 2026 · 1 revision

Setup Wizard Implementation Plan

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

Global Constraints

  • 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 age values: little (7 and under), kid (8 to 12), teen (13 and up; the parent is always teen).
  • 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 through play$fx; no Ionic alerts; toasts use rpgToastOptions.
  • 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.

Review Focus

  1. Every room unticked for a hero's band has no library chores: review shows "nothing common here, add your own", never an empty crash.
  2. Two heroes tick the same chore beast: one quest, assigned to both, not two quests with one id.
  3. 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.
  4. 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.
  5. The apply step throws midway: Begin re-enables and a retry is safe (idempotent).

File Structure

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

Task 1: The planner

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 teen
    • bandOf 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 every libraryRooms() entry maps to an id in STARTER_CATEGORIES
    • suggestedChores returns only chore beasts of that band in those rooms (every result has age === band, room in rooms, none classic) and returns [] for a room with no chores of that band
    • choreQuest is an individual quest assigned to the given heroes (type "individual", assignee equals ids, beastId equals the beast id, id equals `quest-${beast.slug}`, categoryId from the room, adventureType "beast")
    • choreQuest scales difficulty by band (little 1, kid 2, teen 3), schedule weekly
    • 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 from newId)
    • setupPlan: existing heroes create no profiles; new heroes create profiles via quickStartHero; a new parent creates a Game Master via quickStartGameMaster (newProfiles.length and isAdult)
    • setupPlan: extras off leaves __abilities, __accessories, __shops, __dosDonts out; on includes them; a shop id already in shopsNow is not replaced
    • setupPlan 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.ts as signed above. suggestedChores calls browseLibrary({ room, age: band, classic: false }) per room and concatenates in library order. choreQuest builds questFromSeed({ id, name: beast.chore, categoryId, beastId: beast.id, schedule: "weekly", difficulty }) then overrides type: "individual" and assignee (the way assignQuests does). setupPlan builds the backup like quickStartPlan: __profiles (new only), __achievementCategories, __beasts, __achievements; when answers.extras, spread buildStarterWorld(now).stores entries for only __abilities, __accessories, __shops (minus keys in shopsNow) 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"

Task 2: Wizard steps and draft

Files:

  • Create: src/lib/services/setup/setupSteps.ts
  • Test: tests/unit/setupSteps.spec.ts

Interfaces:

  • Consumes: SetupAnswers, SetupHero, bandOf, suggestedChores (Task 1); WizardStep<Draft> from src/lib/services/wizard/wizardSteps.ts; heroNames, gameMasterProblem from quickStart.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 (uses gameMasterProblem)
    • house step is invalid with no rooms
    • review step is invalid when a hero has no chores
    • extras and summary steps are always valid
    • preTick fills chores per hero from their band and rooms, and a second call keeps the parent's unticks
    • emptyDraft 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 the WizardStep shape 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"

Task 3: Storage, emptiness and apply

Files:

  • Create: src/lib/services/setup/runSetup.ts
  • Test: tests/unit/runSetup.spec.ts (copy the memory() / device() fakes from tests/unit/quickStart.spec.ts)

Interfaces:

  • Consumes: setupPlan, SetupAnswers, SetupPlan, SetupHero (Task 1); QuickStartDeps-style deps (storage(name), restore(file)) as in quickStart.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 storageOf and the first-run BackupService merge restore from quickStart.ts; export those two from quickStart.ts rather 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 exists
    • existingHeroes lists profiles with existing true and the adult as isParent
    • runSetup restores the plan in merge mode and returns it
    • runSetup 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.ts using the readAll pattern from quickStart.ts (export it). runSetup reads __shops for shopsNow, builds the plan, then deps.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"

Task 4: The wizard modal

Files:

  • Create: src/app/SideMenu/SetupWizard/SetupWizard.vue, SetupWizard.ts, _SetupWizard.scss

Interfaces:

  • Consumes: XpWizardShell (props steps, draft, index, verb, busy, accent; emits close, submit; one slot per step id), SETUP_STEPS, emptyDraft, preTick (Task 2), existingHeroes, isGameEmpty, runSetup (Task 3), suggestBeasts and libraryRooms (librarySuggest.ts), rpgToastOptions.

  • Produces: component SetupWizard presented with modalController.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 into emptyDraft. Bind v-model:index. verb="Begin". busy while runSetup runs. 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 to QUICK_START_MAX_HEROES; when no profile exists, one "Parent" row with name + 4-digit PIN feeding draft.gameMaster.
    • house: tickable room chips from libraryRooms().
    • review: on entering, call preTick; per hero a section of beast cards (avatar, name, chore) with tick/untick; empty state "Nothing common here, add your own"; a type-ahead using suggestBeasts(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 sets index to that step.
  • Step 3: Begin. Call runSetup(draft); on success play play$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 typecheck and chemx 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"

Task 5: Entry points

Files:

  • Modify: src/app/SideMenu/SwitchProfile/SwitchProfile.vue (near openQuickStart, ~L601)
  • Modify: src/app/SideMenu/XpSettings/components/GeneralSettings.vue
  • Modify: the bestiary empty state in src/app/Admin/ (find with chemx q -g "No beasts")

Interfaces:

  • Consumes: SetupWizard (Task 4), isGameEmpty (Task 3).

  • Step 1: Offer on first launch. In SwitchProfile.vue add openSetupWizard() beside openQuickStart and call it once on mount when await isGameEmpty() and a module-level offeredThisSession flag is false; set the flag when the modal closes either way so it never nags again in the session. After a finished run call loadProfiles() and show the same style of toast as Quick Start.

  • Step 2: Settings row. Add "Run setup again" in GeneralSettings.vue that opens the same modal; it runs regardless of isGameEmpty.

  • 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 typecheck and chemx lint; check that XpFirstRunTour (started from MyPortal.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"

Task 6: Cypress smoke

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; if curl -s localhost:8100 fails, 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"

Self-review notes

  • 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.age is draft-only), and an existing Game Master appears as an existing hero row with isParent.
  • 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.

Table of Contents


Home - See Pages

Developer Docs

Start Screen

User Management

My Portal

My Home

The City (Hometown)

The World Map

The Dungeon

Game Master

Settings

Support & Glossary

About XP

Clone this wiki locally