chore: complete v1.0 MVP milestone
Archive roadmap, requirements, and phase directories to milestones/. Evolve PROJECT.md with validated requirements and key decisions. Reorganize ROADMAP.md with milestone grouping. Delete REQUIREMENTS.md (fresh for next milestone).
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
---
|
||||
phase: 01-foundation-and-collection
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on: ["01-03"]
|
||||
files_modified:
|
||||
- src/client/components/OnboardingWizard.tsx
|
||||
- src/client/stores/uiStore.ts
|
||||
- src/client/hooks/useSettings.ts
|
||||
- src/server/routes/settings.ts
|
||||
- src/server/index.ts
|
||||
- src/client/routes/__root.tsx
|
||||
autonomous: false
|
||||
requirements:
|
||||
- COLL-01
|
||||
- COLL-02
|
||||
- COLL-03
|
||||
- COLL-04
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "First-time user sees an onboarding wizard guiding them through creating a category and adding an item"
|
||||
- "After completing onboarding, the wizard does not appear again (persisted to DB)"
|
||||
- "Returning user goes straight to the collection view"
|
||||
- "The complete collection experience works end-to-end visually"
|
||||
artifacts:
|
||||
- path: "src/client/components/OnboardingWizard.tsx"
|
||||
provides: "Step-by-step modal overlay for first-run experience"
|
||||
min_lines: 60
|
||||
- path: "src/client/hooks/useSettings.ts"
|
||||
provides: "TanStack Query hook for settings (onboarding completion flag)"
|
||||
- path: "src/server/routes/settings.ts"
|
||||
provides: "API for reading/writing settings"
|
||||
key_links:
|
||||
- from: "src/client/components/OnboardingWizard.tsx"
|
||||
to: "src/client/hooks/useSettings.ts"
|
||||
via: "Checks and updates onboarding completion"
|
||||
pattern: "onboardingComplete"
|
||||
- from: "src/client/hooks/useSettings.ts"
|
||||
to: "/api/settings"
|
||||
via: "Fetch and update settings"
|
||||
pattern: "fetch.*/api/settings"
|
||||
- from: "src/client/components/OnboardingWizard.tsx"
|
||||
to: "src/client/hooks/useCategories.ts"
|
||||
via: "Creates first category during onboarding"
|
||||
pattern: "useCreateCategory"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the first-run onboarding wizard and perform visual verification of the complete collection experience.
|
||||
|
||||
Purpose: The onboarding wizard ensures new users are not dropped into an empty page. It guides them through creating their first category and item. The checkpoint verifies the entire Phase 1 UI works correctly.
|
||||
Output: Onboarding wizard with DB-persisted completion state, and human-verified collection experience.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/jean-luc-makiola/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/jean-luc-makiola/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/phases/01-foundation-and-collection/01-CONTEXT.md
|
||||
@.planning/phases/01-foundation-and-collection/01-03-SUMMARY.md
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Onboarding wizard with settings API and persisted state</name>
|
||||
<files>src/server/routes/settings.ts, src/server/index.ts, src/client/hooks/useSettings.ts, src/client/components/OnboardingWizard.tsx, src/client/stores/uiStore.ts, src/client/routes/__root.tsx</files>
|
||||
<action>
|
||||
1. Create `src/server/routes/settings.ts`:
|
||||
- GET /api/settings/:key returns { key, value } or 404
|
||||
- PUT /api/settings/:key with body { value } upserts the setting (INSERT OR REPLACE into settings table)
|
||||
- Export as settingsRoutes
|
||||
|
||||
2. Update `src/server/index.ts`: Register app.route("/api/settings", settingsRoutes).
|
||||
|
||||
3. Create `src/client/hooks/useSettings.ts`:
|
||||
- useSetting(key): TanStack Query hook that fetches GET /api/settings/{key}, returns value or null if 404
|
||||
- useUpdateSetting(): mutation that PUTs /api/settings/{key} with { value }, invalidates ["settings", key]
|
||||
- Specifically export useOnboardingComplete() that wraps useSetting("onboardingComplete") for convenience
|
||||
|
||||
4. Create `src/client/components/OnboardingWizard.tsx`: Per user decision, a step-by-step modal overlay (not full-page takeover). 3 steps:
|
||||
- Step 1: Welcome screen. "Welcome to GearBox!" with brief description. "Let's set up your first category." Next button.
|
||||
- Step 2: Create first category. Show a mini form with category name input and emoji picker (simple: text input for emoji, user pastes/types emoji). Use useCreateCategory mutation. On success, advance to step 3.
|
||||
- Step 3: Add first item. Show a simplified item form (just name, weight, price, and the just-created category pre-selected). Use useCreateItem mutation. On success, show "You're all set!" and a Done button.
|
||||
- On Done: call useUpdateSetting to set "onboardingComplete" to "true". Close wizard.
|
||||
- Modal styling: centered overlay with backdrop blur, white card, clean typography, step indicator (1/3, 2/3, 3/3).
|
||||
- Allow skipping the wizard entirely with a "Skip" link that still sets onboardingComplete.
|
||||
|
||||
5. Update `src/client/routes/__root.tsx`: On app load, check useOnboardingComplete(). If value is not "true" (null or missing), render OnboardingWizard as an overlay on top of everything. If "true", render normally. Show a loading state while the setting is being fetched (don't flash the wizard).
|
||||
|
||||
6. Per RESEARCH.md Pitfall 3: onboarding state is persisted in SQLite settings table, NOT just Zustand. Zustand is only for transient UI state (panel, dialog). The settings table is the source of truth for whether onboarding is complete.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>bun run build 2>&1 | tail -5 && bun test --bail 2>&1 | tail -5</automated>
|
||||
</verify>
|
||||
<done>Onboarding wizard renders on first visit (no onboardingComplete setting). Completing it persists the flag. Subsequent visits skip the wizard. Build and tests pass.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 2: Visual verification of complete Phase 1 collection experience</name>
|
||||
<action>Human verifies the complete collection experience works end-to-end: onboarding wizard, card grid, slide-out panel, category management, totals, image upload, and data persistence.</action>
|
||||
<what-built>Complete Phase 1 collection experience: card grid grouped by categories, slide-out panel for add/edit items, category picker with inline creation, delete confirmation, sticky totals bar, image upload on cards, and first-run onboarding wizard.</what-built>
|
||||
<how-to-verify>
|
||||
1. Delete gearbox.db to simulate first-run: `rm gearbox.db`
|
||||
2. Start both dev servers: `bun run dev:server` in one terminal, `bun run dev:client` in another
|
||||
3. Visit http://localhost:5173
|
||||
|
||||
ONBOARDING:
|
||||
4. Verify onboarding wizard appears as a modal overlay
|
||||
5. Step through: create a category (e.g. "Shelter" with tent emoji), add an item (e.g. "Tent, 1200g, $350")
|
||||
6. Complete wizard, verify it closes and collection view shows
|
||||
|
||||
COLLECTION VIEW:
|
||||
7. Verify the item appears in a card with name, weight chip, price chip
|
||||
8. Verify the category header shows "Shelter" with emoji and subtotals
|
||||
9. Verify the sticky totals bar at top shows 1 item, 1200g, $350.00
|
||||
|
||||
ADD/EDIT:
|
||||
10. Click the "+" button, verify slide-out panel opens from right
|
||||
11. Add another item in a new category, verify both categories appear with correct subtotals
|
||||
12. Click an existing card, verify panel opens with pre-filled data for editing
|
||||
13. Edit the weight, save, verify totals update
|
||||
|
||||
CATEGORY MANAGEMENT:
|
||||
14. Hover over a category header, verify edit/delete buttons appear
|
||||
15. Delete a category, verify items reassign to Uncategorized
|
||||
|
||||
DELETE:
|
||||
16. Click delete on an item, verify confirmation dialog appears
|
||||
17. Confirm delete, verify item removed and totals update
|
||||
|
||||
IMAGE:
|
||||
18. Edit an item, upload an image, verify it appears on the card
|
||||
|
||||
PERSISTENCE:
|
||||
19. Refresh the page, verify all data persists and onboarding wizard does NOT reappear
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" if the collection experience works correctly, or describe any issues found.</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- Onboarding wizard appears on first run, not on subsequent visits
|
||||
- All CRUD operations work through the UI
|
||||
- Category management (create, rename, delete with reassignment) works
|
||||
- Totals are accurate and update in real-time after mutations
|
||||
- Cards display clean, minimal aesthetic per user decisions
|
||||
- Image upload and display works
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- First-time users see onboarding wizard that guides through first category and item
|
||||
- Onboarding completion persists across page refreshes (stored in SQLite settings table)
|
||||
- Full collection CRUD works end-to-end through the UI
|
||||
- Visual design matches user decisions: clean, minimal, light and airy, card grid with chips
|
||||
- Human approves the complete collection experience
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/01-foundation-and-collection/01-04-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user