2 Commits

Author SHA1 Message Date
261c1f9d02 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).
2026-03-15 15:49:45 +01:00
89368c2651 docs: update retrospective for v1.0 2026-03-15 15:49:35 +01:00
39 changed files with 248 additions and 167 deletions

19
.planning/MILESTONES.md Normal file
View File

@@ -0,0 +1,19 @@
# Milestones
## v1.0 MVP (Shipped: 2026-03-15)
**Phases completed:** 3 phases, 10 plans
**Timeline:** 2 days (2026-03-14 → 2026-03-15)
**Codebase:** 5,742 LOC TypeScript, 53 commits, 114 files
**Key accomplishments:**
- Full gear collection with item CRUD, categories, weight/cost totals, and image uploads
- Planning threads with candidate comparison and thread resolution into collection
- Named setups (loadouts) composed from collection items with live totals
- Dashboard home page with summary cards linking to all features
- Onboarding wizard for first-time setup experience
- Complete test suite with service-level and route-level integration tests
**Archive:** `.planning/milestones/v1.0-ROADMAP.md`, `.planning/milestones/v1.0-REQUIREMENTS.md`
---

View File

@@ -2,7 +2,7 @@
## What This Is
A web-based gear management and purchase planning app. Users can catalog their gear collections (bikepacking, sim racing, or any hobby), track details like weight, price, and source, and use planning threads to research and compare new purchases against their existing setup. Built as a single-user app with a clean, minimalist interface.
A web-based gear management and purchase planning app. Users catalog their gear collections (bikepacking, sim racing, or any hobby), track weight, price, and source details, and use planning threads to research and compare new purchases. Named setups let users compose loadouts from their collection with live weight/cost totals. Built as a single-user app with a clean, minimalist interface.
## Core Value
@@ -12,36 +12,45 @@ Make it effortless to manage gear and plan new purchases — see how a potential
### Validated
<!-- Shipped and confirmed valuable. -->
(None yet — ship to validate)
- ✓ Gear collection with item CRUD (name, weight, price, category, notes, product link) — v1.0
- ✓ Image uploads for gear items — v1.0
- ✓ User-defined categories with emoji and automatic weight/cost totals — v1.0
- ✓ Planning threads for purchase research with candidate products — v1.0
- ✓ Thread resolution: pick a winner, it moves to collection — v1.0
- ✓ Named setups (loadouts) composed from collection items — v1.0
- ✓ Live weight and cost totals per setup — v1.0
- ✓ Dashboard home page with summary cards — v1.0
- ✓ Onboarding wizard for first-time setup — v1.0
### Active
<!-- Current scope. Building toward these. -->
- [ ] Gear collection with items including weight, price, purchase source, category, photos, product links, and notes
- [ ] Planning threads for researching purchases — add candidate products, compare side-by-side
- [ ] See how candidates affect overall setup (total weight/cost impact)
- [ ] Named setups (e.g. "Summer Bikepacking") composed from collection items with total weight/cost
- [ ] Thread resolution — pick a winner, it moves to your collection, thread closes
- [ ] Status tracking on thread items (researching → ordered → arrived)
- [ ] Priority/ranking within threads to mark favorites
- [ ] Dashboard home page with cards linking to collection, threads, and setups
- [ ] Search items by name and filter by category
- [ ] Side-by-side candidate comparison on weight and price
- [ ] Candidate status tracking (researching → ordered → arrived)
- [ ] Candidate ranking/prioritization within threads
- [ ] Impact preview: how a candidate affects setup weight/cost
- [ ] Weight unit selection (g, oz, lb, kg)
- [ ] CSV import/export for gear collections
- [ ] Weight distribution visualization (pie/bar chart by category)
- [ ] Classify items as base weight, worn, or consumable per setup
### Out of Scope
- Authentication / multi-user — single user for v1, no login needed
- Custom comparison parameters — future enhancement, not v1
- Mobile app — web-first
- Social/sharing features — may add later
- Custom comparison parameters — complexity trap, weight/price covers 80% of cases
- Mobile native app — web-first, responsive design sufficient
- Social/sharing features — different product, defer to v2+
- Price tracking / deal alerts — requires scraping, fragile
- Barcode scanning / product database — requires external database
- Community gear database — requires moderation, accounts
- Real-time weather integration — only outdoor-specific, GearBox is hobby-agnostic
## Context
- Primary use case is bikepacking gear, but the data model should be generic enough for any hobby/collection type
- Replaces a spreadsheet-based workflow for tracking gear and planning purchases
- Single user, no auth — simplest possible setup
- User prefers Bun over npm as package manager/runtime
Shipped v1.0 MVP with 5,742 LOC TypeScript across 114 files.
Tech stack: React 19, Hono, Drizzle ORM, SQLite, TanStack Router/Query, Tailwind CSS v4, all on Bun.
Primary use case is bikepacking gear but data model is hobby-agnostic.
Replaces spreadsheet-based gear tracking workflow.
## Constraints
@@ -54,10 +63,18 @@ Make it effortless to manage gear and plan new purchases — see how a potential
| Decision | Rationale | Outcome |
|----------|-----------|---------|
| No auth for v1 | Single user, simplicity first | — Pending |
| Generic data model | Support any hobby, not just bikepacking | — Pending |
| Dashboard navigation | Clean entry point, not persistent nav | — Pending |
| Bun runtime | User preference | — Pending |
| No auth for v1 | Single user, simplicity first | ✓ Good |
| Generic data model | Support any hobby, not just bikepacking | ✓ Good |
| Dashboard navigation | Clean entry point, not persistent nav | ✓ Good |
| Bun runtime | User preference | ✓ Good |
| Service layer with DI | Accept db as first param for testability | ✓ Good |
| Hono context variables for DB | Enables in-memory SQLite integration tests | ✓ Good |
| Prices stored as cents | Avoids float rounding issues | ✓ Good |
| Vite proxy dev setup | Required by TanStack Router plugin | ✓ Good |
| drizzle-kit needs better-sqlite3 | bun:sqlite not supported by CLI | ✓ Good |
| Tab navigation via URL params | Shareable URLs between gear/planning | ✓ Good |
| Setup item sync: delete-all + re-insert | Simpler than diffing, atomic in transaction | ✓ Good |
| Onboarding state in SQLite settings | Source of truth in DB, not Zustand | ✓ Good |
---
*Last updated: 2026-03-14 after initialization*
*Last updated: 2026-03-15 after v1.0 milestone*

View File

@@ -0,0 +1,67 @@
# Project Retrospective
*A living document updated after each milestone. Lessons feed forward into future planning.*
## Milestone: v1.0 — MVP
**Shipped:** 2026-03-15
**Phases:** 3 | **Plans:** 10 | **Commits:** 53
### What Was Built
- Full gear collection with item CRUD, categories, weight/cost totals, and image uploads
- Planning threads with candidate comparison and thread resolution into collection
- Named setups (loadouts) composed from collection items with live totals
- Dashboard home page with summary cards
- Onboarding wizard for first-time user experience
- Service-level and route-level integration tests
### What Worked
- Coarse 3-phase structure kept momentum high — no planning overhead between tiny phases
- TDD approach for backend (service tests first) caught issues early and made frontend integration smooth
- Service layer with DI (db as first param) made testing trivial with in-memory SQLite
- Visual verification checkpoints at end of each phase caught UI issues before moving on
- Bun + Vite + Hono stack had zero friction — everything worked together cleanly
### What Was Inefficient
- Verification plans (XX-03) were mostly rubber-stamp auto-approvals in yolo mode — could skip for v2
- Some ROADMAP plan checkboxes never got checked off (cosmetic, didn't affect tracking)
- Performance metrics in STATE.md had stale placeholder data alongside real data
### Patterns Established
- Service functions: `(db, params) => result` with production db default
- Route-level integration tests using Hono context variables for db injection
- Prices in cents everywhere, display conversion in UI only
- Tab navigation via URL search params for shareability
- Atomic sync pattern: delete-all + re-insert in transaction
### Key Lessons
1. Coarse granularity (3 phases for an MVP) is the right call for a greenfield app — avoids over-planning
2. The Vite proxy pattern is required when using TanStack Router plugin — can't do Bun fullstack serving
3. drizzle-kit needs better-sqlite3 even on Bun — can't use bun:sqlite for migrations
4. Onboarding state belongs in the database (settings table), not in client-side stores
### Cost Observations
- Model mix: quality profile throughout
- Sessions: ~10 plan executions across 2 days
- Notable: Most plans completed in 3-5 minutes, total wall time under 1 hour
---
## Cross-Milestone Trends
### Process Evolution
| Milestone | Commits | Phases | Key Change |
|-----------|---------|--------|------------|
| v1.0 | 53 | 3 | Initial build, coarse granularity, TDD backend |
### Cumulative Quality
| Milestone | LOC | Files | Tests |
|-----------|-----|-------|-------|
| v1.0 | 5,742 | 114 | Service + route integration |
### Top Lessons (Verified Across Milestones)
1. Coarse phases with TDD backend → smooth frontend integration
2. Service DI pattern enables fast, reliable testing without mocks

View File

@@ -1,80 +1,24 @@
# Roadmap: GearBox
## Overview
## Milestones
GearBox delivers a gear management and purchase planning web app in three phases. Phase 1 establishes the foundation and builds the complete gear collection feature — the core entity everything else depends on. Phase 2 adds planning threads, the product's differentiator, enabling structured purchase research with candidate comparison and thread resolution into the collection. Phase 3 completes the app with named setups (loadouts composed from collection items) and the dashboard home page that ties everything together.
-**v1.0 MVP** — Phases 1-3 (shipped 2026-03-15)
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
<details>
<summary>✅ v1.0 MVP (Phases 1-3) — SHIPPED 2026-03-15</summary>
Decimal phases appear between their surrounding integers in numeric order.
- [x] Phase 1: Foundation and Collection (4/4 plans) — completed 2026-03-14
- [x] Phase 2: Planning Threads (3/3 plans) — completed 2026-03-15
- [x] Phase 3: Setups and Dashboard (3/3 plans) — completed 2026-03-15
- [x] **Phase 1: Foundation and Collection** - Project scaffolding, data model, and complete gear item CRUD with categories and totals (completed 2026-03-14)
- [x] **Phase 2: Planning Threads** - Purchase research workflow with candidates, comparison, and thread resolution (completed 2026-03-15)
- [x] **Phase 3: Setups and Dashboard** - Named loadouts from collection items and dashboard home page (completed 2026-03-15)
## Phase Details
### Phase 1: Foundation and Collection
**Goal**: Users can catalog their gear collection with full item details, organize by category, and see aggregate weight and cost totals
**Depends on**: Nothing (first phase)
**Requirements**: COLL-01, COLL-02, COLL-03, COLL-04
**Success Criteria** (what must be TRUE):
1. User can add a gear item with name, weight, price, category, notes, and product link and see it in their collection
2. User can edit any field on an existing item and delete items they no longer want
3. User can create, rename, and delete categories, and every item belongs to a user-defined category
4. User can see automatic weight and cost totals per category and for the entire collection
5. The app runs as a single Bun process with SQLite storage and serves a clean, minimalist UI
**Plans:** 4/4 plans complete
Plans:
- [ ] 01-01-PLAN.md — Project scaffolding, DB schema, shared schemas, and test infrastructure
- [ ] 01-02-PLAN.md — Backend API: item CRUD, category CRUD, totals, image upload with tests
- [ ] 01-03-PLAN.md — Frontend collection UI: card grid, slide-out panel, category picker, totals bar
- [ ] 01-04-PLAN.md — Onboarding wizard and visual verification checkpoint
### Phase 2: Planning Threads
**Goal**: Users can research potential purchases through planning threads — adding candidates, comparing them, and resolving a thread by picking a winner that moves into their collection
**Depends on**: Phase 1
**Requirements**: THRD-01, THRD-02, THRD-03, THRD-04
**Success Criteria** (what must be TRUE):
1. User can create a planning thread with a descriptive name and see it in a threads list
2. User can add candidate products to a thread with weight, price, notes, and product link
3. User can edit and remove candidates from an active thread
4. User can resolve a thread by selecting a winning candidate, which automatically creates a new item in their collection and archives the thread
**Plans:** 3/3 plans complete
Plans:
- [ ] 02-01-PLAN.md — Backend API: thread/candidate CRUD, resolution transaction, with TDD
- [ ] 02-02-PLAN.md — Frontend: tab navigation, thread list, candidate UI, resolution flow
- [ ] 02-03-PLAN.md — Visual verification checkpoint
### Phase 3: Setups and Dashboard
**Goal**: Users can compose named loadouts from their collection items with live totals, and navigate the app through a dashboard home page
**Depends on**: Phase 1, Phase 2
**Requirements**: SETP-01, SETP-02, SETP-03, DASH-01
**Success Criteria** (what must be TRUE):
1. User can create a named setup (e.g. "Summer Bikepacking") and see it in a setups list
2. User can add and remove collection items from a setup
3. User can see total weight and cost for a setup, computed live from current item data
4. User sees a dashboard home page with cards linking to their collection, active threads, and setups
**Plans:** 3/3 plans complete
Plans:
- [ ] 03-01-PLAN.md — Backend TDD: setup schema, service, routes, and tests with junction table
- [ ] 03-02-PLAN.md — Frontend: navigation restructure, dashboard, setup UI, and item picker
- [ ] 03-03-PLAN.md — Visual verification checkpoint
</details>
## Progress
**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation and Collection | 4/4 | Complete | 2026-03-14 |
| 2. Planning Threads | 3/3 | Complete | 2026-03-15 |
| 3. Setups and Dashboard | 3/3 | Complete | 2026-03-15 |
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Foundation and Collection | v1.0 | 4/4 | Complete | 2026-03-14 |
| 2. Planning Threads | v1.0 | 3/3 | Complete | 2026-03-15 |
| 3. Setups and Dashboard | v1.0 | 3/3 | Complete | 2026-03-15 |

View File

@@ -1,11 +1,11 @@
---
gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
status: completed
stopped_at: Completed 03-03-PLAN.md — All phases complete
last_updated: "2026-03-15T11:57:37.090Z"
last_activity: 2026-03-15 — Completed 03-03 visual verification
milestone_name: MVP
status: milestone_complete
stopped_at: "v1.0 MVP shipped"
last_updated: "2026-03-15"
last_activity: 2026-03-15 — v1.0 milestone archived
progress:
total_phases: 3
completed_phases: 3
@@ -18,91 +18,36 @@ progress:
## Project Reference
See: .planning/PROJECT.md (updated 2026-03-14)
See: .planning/PROJECT.md (updated 2026-03-15)
**Core value:** Make it effortless to manage gear and plan new purchases — see how a potential buy affects your total setup weight and cost before committing.
**Current focus:** Phase 3: Setups and Dashboard
**Current focus:** Planning next milestone
## Current Position
Phase: 3 of 3 (Setups and Dashboard)
Plan: 3 of 3 in current phase
Status: Complete
Last activity: 2026-03-15 — Completed 03-03 visual verification
Milestone v1.0 MVP shipped 2026-03-15.
All 3 phases, 10 plans complete.
Ready for next milestone planning.
Progress: [██████████] 100%
## Performance Metrics
**Velocity:**
- Total plans completed: 0
- Average duration: -
- Total execution time: 0 hours
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| - | - | - | - |
**Recent Trend:**
- Last 5 plans: -
- Trend: -
*Updated after each plan completion*
| Phase 01 P02 | 3min | 2 tasks | 13 files |
| Phase 01 P03 | 3min | 2 tasks | 16 files |
| Phase 01 P04 | 3min | 2 tasks | 5 files |
| Phase 02 P01 | 5min | 2 tasks | 9 files |
| Phase 02 P02 | 4min | 2 tasks | 10 files |
| Phase 02 P03 | 1min | 1 tasks | 0 files |
| Phase 03 P01 | 8min | 2 tasks | 9 files |
| Phase 03 P02 | 5min | 2 tasks | 14 files |
| Phase 03 P03 | 1min | 1 tasks | 0 files |
## Accumulated Context
### Decisions
Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:
- [Roadmap]: 3-phase coarse structure — Collection, Threads, Setups+Dashboard
- [Roadmap]: Setups and Dashboard combined into single phase (coarse granularity)
- [01-01]: TanStack Router requires routesDirectory config when routes are in src/client/routes
- [01-01]: drizzle-kit CLI needs better-sqlite3 (cannot use bun:sqlite)
- [Phase 01-02]: Service functions accept db as first param with production default for DI/testability
- [Phase 01-02]: Routes use Hono context variables for DB injection enabling in-memory SQLite integration tests
- [Phase 01-03]: ItemForm converts dollar input to cents for API (display dollars, store cents)
- [Phase 01-03]: CategoryPicker uses native ARIA combobox pattern with keyboard navigation
- [Phase 01-04]: Onboarding state persisted in SQLite settings table, not Zustand (source of truth in DB)
- [Phase 01-04]: Settings API is generic key-value store usable beyond onboarding
- [Phase 02-01]: Drizzle sql template literals use raw table.column refs in correlated subqueries (not interpolated)
- [Phase 02-01]: Thread deletion collects candidate image filenames before cascade for filesystem cleanup
- [Phase 02-01]: Resolution validates categoryId existence, falls back to Uncategorized (id=1)
- [Phase 02-02]: Tab navigation uses URL search params (?tab=gear|planning) for shareable URLs
- [Phase 02-02]: Candidate panel runs as separate SlideOutPanel instance with independent uiStore state
- [Phase 02-02]: Resolution invalidates threads, items, and totals queries for cross-tab data freshness
- [Phase 02-03]: All four THRD requirements verified working end-to-end in browser
- [Phase 03-01]: syncSetupItems uses delete-all + re-insert in transaction for simplicity
- [Phase 03-01]: SQL COALESCE ensures 0 returned for empty setups instead of null
- [Phase 03-02]: TotalsBar refactored with optional props for route-aware display
- [Phase 03-02]: Setup detail computes totals client-side from items array
- [Phase 03-02]: ItemPicker tracks selections locally, syncs batch on Done
- [Phase 03-02]: FAB restricted to /collection gear tab only
- [Phase 03-03]: All four Phase 3 requirements verified working end-to-end (auto-approved)
Decisions logged in PROJECT.md Key Decisions table.
All v1.0 decisions have outcomes marked.
### Pending Todos
None yet.
None.
### Blockers/Concerns
- ~~Verify @hono/zod-validator supports Zod 4.x before starting Phase 1. If not, pin Zod 3.23.x.~~ RESOLVED: @hono/zod-validator@0.7.6 works with Zod 4.3.6
- ~~Confirm Bun fullstack vs. Vite proxy dev setup pattern before project scaffolding.~~ RESOLVED: Using Vite proxy pattern (required by TanStack Router plugin)
None active.
## Session Continuity
Last session: 2026-03-15T11:53:36.000Z
Stopped at: Completed 03-03-PLAN.md — All phases complete
Resume file: N/A — project milestone complete
Last session: 2026-03-15
Stopped at: v1.0 milestone complete
Resume file: N/A — start next milestone with /gsd:new-milestone

View File

@@ -1,3 +1,12 @@
# Requirements Archive: v1.0 MVP
**Archived:** 2026-03-15
**Status:** SHIPPED
For current requirements, see `.planning/REQUIREMENTS.md`.
---
# Requirements: GearBox
**Defined:** 2026-03-14

View File

@@ -0,0 +1,80 @@
# Roadmap: GearBox
## Overview
GearBox delivers a gear management and purchase planning web app in three phases. Phase 1 establishes the foundation and builds the complete gear collection feature — the core entity everything else depends on. Phase 2 adds planning threads, the product's differentiator, enabling structured purchase research with candidate comparison and thread resolution into the collection. Phase 3 completes the app with named setups (loadouts composed from collection items) and the dashboard home page that ties everything together.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
Decimal phases appear between their surrounding integers in numeric order.
- [x] **Phase 1: Foundation and Collection** - Project scaffolding, data model, and complete gear item CRUD with categories and totals (completed 2026-03-14)
- [x] **Phase 2: Planning Threads** - Purchase research workflow with candidates, comparison, and thread resolution (completed 2026-03-15)
- [x] **Phase 3: Setups and Dashboard** - Named loadouts from collection items and dashboard home page (completed 2026-03-15)
## Phase Details
### Phase 1: Foundation and Collection
**Goal**: Users can catalog their gear collection with full item details, organize by category, and see aggregate weight and cost totals
**Depends on**: Nothing (first phase)
**Requirements**: COLL-01, COLL-02, COLL-03, COLL-04
**Success Criteria** (what must be TRUE):
1. User can add a gear item with name, weight, price, category, notes, and product link and see it in their collection
2. User can edit any field on an existing item and delete items they no longer want
3. User can create, rename, and delete categories, and every item belongs to a user-defined category
4. User can see automatic weight and cost totals per category and for the entire collection
5. The app runs as a single Bun process with SQLite storage and serves a clean, minimalist UI
**Plans:** 4/4 plans complete
Plans:
- [ ] 01-01-PLAN.md — Project scaffolding, DB schema, shared schemas, and test infrastructure
- [ ] 01-02-PLAN.md — Backend API: item CRUD, category CRUD, totals, image upload with tests
- [ ] 01-03-PLAN.md — Frontend collection UI: card grid, slide-out panel, category picker, totals bar
- [ ] 01-04-PLAN.md — Onboarding wizard and visual verification checkpoint
### Phase 2: Planning Threads
**Goal**: Users can research potential purchases through planning threads — adding candidates, comparing them, and resolving a thread by picking a winner that moves into their collection
**Depends on**: Phase 1
**Requirements**: THRD-01, THRD-02, THRD-03, THRD-04
**Success Criteria** (what must be TRUE):
1. User can create a planning thread with a descriptive name and see it in a threads list
2. User can add candidate products to a thread with weight, price, notes, and product link
3. User can edit and remove candidates from an active thread
4. User can resolve a thread by selecting a winning candidate, which automatically creates a new item in their collection and archives the thread
**Plans:** 3/3 plans complete
Plans:
- [ ] 02-01-PLAN.md — Backend API: thread/candidate CRUD, resolution transaction, with TDD
- [ ] 02-02-PLAN.md — Frontend: tab navigation, thread list, candidate UI, resolution flow
- [ ] 02-03-PLAN.md — Visual verification checkpoint
### Phase 3: Setups and Dashboard
**Goal**: Users can compose named loadouts from their collection items with live totals, and navigate the app through a dashboard home page
**Depends on**: Phase 1, Phase 2
**Requirements**: SETP-01, SETP-02, SETP-03, DASH-01
**Success Criteria** (what must be TRUE):
1. User can create a named setup (e.g. "Summer Bikepacking") and see it in a setups list
2. User can add and remove collection items from a setup
3. User can see total weight and cost for a setup, computed live from current item data
4. User sees a dashboard home page with cards linking to their collection, active threads, and setups
**Plans:** 3/3 plans complete
Plans:
- [ ] 03-01-PLAN.md — Backend TDD: setup schema, service, routes, and tests with junction table
- [ ] 03-02-PLAN.md — Frontend: navigation restructure, dashboard, setup UI, and item picker
- [ ] 03-03-PLAN.md — Visual verification checkpoint
## Progress
**Execution Order:**
Phases execute in numeric order: 1 -> 2 -> 3
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Foundation and Collection | 4/4 | Complete | 2026-03-14 |
| 2. Planning Threads | 3/3 | Complete | 2026-03-15 |
| 3. Setups and Dashboard | 3/3 | Complete | 2026-03-15 |