# Implementation Plan: GlowTrack — Mood & Habit Wellbeing Grid

**Branch**: `001-glowtrack-a-mood` | **Date**: 18 September 2025 | **Spec**: `/home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/spec.md`
**Input**: Feature specification from `/home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/spec.md`

## Execution Flow (/plan command scope)
```
1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
7. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command
```

**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
- Phase 2: /tasks command creates tasks.md
- Phase 3-4: Implementation execution (manual or via tools)

## Summary
GlowTrack is a browser-first PWA that turns daily mood and habit inputs into a vibrant, artistic wellbeing grid. Each day is a tile whose mood defines base hue; positive habits increase glow, negative habits reduce it and add a subtle static overlay, with glyphs indicating counts. The app is offline-first, private (no accounts, no servers), and supports PNG export of the grid and JSON import/export for full data portability.

Technical approach: SvelteKit + TypeScript using `@sveltejs/adapter-static` (no backend). Local-first storage with IndexedDB via `idb`. Grid visualization via a lightweight Canvas/SVG renderer tuned for mobile. Styling with Tailwind CSS and CSS variables for theming (including color-blind modes). PWA with SvelteKit service worker and minimal runtime cache. Tooling and reproducible builds via Nix flakes (devShell and build). CI executes Nix builds, Vitest unit tests, and Playwright smoke tests.

## Technical Context
**Language/Version**: TypeScript (ES2022), SvelteKit
**Primary Dependencies**: SvelteKit, `@sveltejs/adapter-static`, `idb`, Tailwind CSS, `@tailwindcss/forms`, Vite, `svelte-check`, ESLint, Prettier
**Storage**: IndexedDB via `idb` with versioned schema; JSON import/export
**Testing**: Vitest (unit), Playwright (e2e smoke), svelte-check (types)
**Target Platform**: Modern browsers (mobile and desktop) as a PWA, offline-capable
**Project Type**: Web (frontend-only PWA)
**Performance Goals**: 60 fps interactions and animations on mid-range mobile; initial interactive < 2s on 3G-like; maintain smooth canvas/SVG rendering for up to 365 tiles
**Constraints**: No servers or accounts; full offline read/write; local-only data; small bundle; accessible (WCAG AA); keyboard-first interactions
**Scale/Scope**: Single-user, local dataset (1–3 years of daily entries, dozens of habits)

## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

The constitution file contains placeholders and no explicit project principles. Adopt default gates aligned with simplicity and test-first intent:
- Tests-first mindset captured in plan (Vitest/Playwright before features land)
- Simplicity: no backend, minimal dependencies, static hosting
- Observability via simple structured logs in dev and explicit export/import contracts

Initial Constitution Check: PASS (no violations detected)

## Project Structure

### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
```

### Source Code (repository root)
```
apps/
└── web/                 # SvelteKit PWA (UI & routes)

packages/
├── viz/                 # Tile/grid renderer (Canvas/SVG)
├── storage/             # IndexedDB schema, migrations, import/export
└── theme/               # Palettes, CSS variables, color-blind modes

tools/
└── ci/                  # CI configs/scripts (Nix, Vitest, Playwright)
```

**Structure Decision**: Custom web monorepo (frontend-only) with shared packages for viz, storage, and theme per requirements

## Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
   - For each NEEDS CLARIFICATION → research task
   - For each dependency → best practices task
   - For each integration → patterns task

2. **Generate and dispatch research agents**:
   ```
   For each unknown in Technical Context:
     Task: "Research {unknown} for {feature context}"
   For each technology choice:
     Task: "Find best practices for {tech} in {domain}"
   ```

3. **Consolidate findings** in `research.md` using format:
   - Decision: [what was chosen]
   - Rationale: [why chosen]
   - Alternatives considered: [what else evaluated]

**Output**: research.md with all NEEDS CLARIFICATION resolved

## Phase 1: Design & Contracts
*Prerequisites: research.md complete*

1. **Extract entities from feature spec** → `data-model.md`:
   - Entity name, fields, relationships
   - Validation rules from requirements
   - State transitions if applicable

2. **Generate API contracts** from functional requirements:
   - For each user action → endpoint
   - Use standard REST/GraphQL patterns
   - Output OpenAPI/GraphQL schema to `/contracts/`

3. **Generate contract tests** from contracts:
   - One test file per endpoint
   - Assert request/response schemas
   - Tests must fail (no implementation yet)

4. **Extract test scenarios** from user stories:
   - Each story → integration test scenario
   - Quickstart test = story validation steps

5. **Update agent file incrementally** (O(1) operation):
   - Run `.specify/scripts/bash/update-agent-context.sh copilot` for your AI assistant
   - If exists: Add only NEW tech from current plan
   - Preserve manual additions between markers
   - Update recent changes (keep last 3)
   - Keep under 150 lines for token efficiency
   - Output to repository root

**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file

## Phase 2: Task Planning Approach
*This section describes what the /tasks command will do - DO NOT execute during /plan*

**Task Generation Strategy**:
- Load `.specify/templates/tasks-template.md` as base
- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
- Each contract → contract test task [P]
- Each entity → model creation task [P] 
- Each user story → integration test task
- Implementation tasks to make tests pass

**Ordering Strategy**:
- TDD order: Tests before implementation 
- Dependency order: Models before services before UI
- Mark [P] for parallel execution (independent files)

**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md

**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan

## Phase 3+: Future Implementation
*These phases are beyond the scope of the /plan command*

**Phase 3**: Task execution (/tasks command creates tasks.md)  
**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)

## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |


## Progress Tracking
*This checklist is updated during execution flow*

**Phase Status**:
- [x] Phase 0: Research complete (/plan command)
- [x] Phase 1: Design complete (/plan command)
- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
- [ ] Phase 3: Tasks generated (/tasks command)
- [ ] Phase 4: Implementation complete
- [ ] Phase 5: Validation passed

**Gate Status**:
- [x] Initial Constitution Check: PASS
- [x] Post-Design Constitution Check: PASS
- [x] All NEEDS CLARIFICATION resolved
- [ ] Complexity deviations documented

---
*Based on Constitution v2.1.1 - See `/memory/constitution.md`*