Remove /generate-app: app shell is now milestone 01 of the plan

The initial app is no longer generated by a separate command. /plan-milestones
now always makes milestone 01 'App Shell Generation' (target platform asked in
the single question round): theme from design tokens, one screen per blueprint
entry, routes, reusable components — no feature logic — plus Playwright setup
and the e2e/app-shell.spec.ts smoke spec. It is executed like any other
milestone via /execute-milestones (which loads platform-ui-generation for it)
or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams,
skills, docs READMEs, CLAUDE.md, and README updated; docs/design README also
gains the screen-inventory.md entry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/agents/doc-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: doc-reviewer
-description: A subagent that reviews document quality and provides improvement suggestions
+description: A subagent that reviews document quality and provides improvement suggestions. Use when reviewing project documents (PRD, functional design, architecture, etc.) for completeness, clarity, consistency, implementability, and measurability.
 model: sonnet
 ---
 

.claude/agents/implementation-validator.md

@@ -1,6 +1,6 @@
 ---
 name: implementation-validator
-description: A subagent that validates implementation code quality and confirms consistency with the spec
+description: A subagent that validates implementation code quality and confirms consistency with the spec. Use when verifying that implemented code meets spec requirements, coding standards, test coverage, security, and performance targets.
 model: sonnet
 ---
 
@@ -53,6 +53,7 @@ Verify that the implemented code meets the following criteria:
 - [ ] Is the coverage target met?
 - [ ] Are edge cases tested?
 - [ ] Are the tests named appropriately?
+- [ ] Are there Playwright E2E tests covering the feature's acceptance criteria (e2e/*.spec.ts)?
 
 **Evaluation Criteria**:
 - ✅ Sufficient: Coverage of 80% or more, covering the main cases
@@ -213,6 +214,11 @@ npm test
 npm run test:coverage
 ```
 
+### Run E2E Tests (Playwright)
+```bash
+npm run test:e2e
+```
+
 ### Build Check
 ```bash
 npm run build

.claude/commands/add-feature.md

@@ -6,14 +6,14 @@ description: Implement a new feature following existing patterns, fully autonomo
 
 **Important:** This workflow is designed to run fully automatically from start to finish without user intervention. After completing each step, immediately move on to the next step. Do not ask the user for confirmation mid-thought or interrupt the work.
 
-**Argument:** feature name (e.g. `/add-feature User profile editing`)
+**Feature name**: `$ARGUMENTS` (e.g. `/add-feature User profile editing`)
 
 ---
 
 ## Step 1: Preparation and Context Setup
 
 1. Establish the current task context:
-  - Feature name: `[the feature name given as an argument]`
+  - Feature name: `$ARGUMENTS`
   - Date: `[get the current date in YYYYMMDD format]`
   - Steering directory path: `.steering/[date]-[feature name]/`
 2. Create the steering directory above.
@@ -26,6 +26,7 @@ description: Implement a new feature following existing patterns, fully autonomo
 
 1. Read `CLAUDE.md` to grasp the overall picture of the project.
 2. Review the persistent documents in the `docs/` directory to understand the relevant design philosophy and architecture.
+3. If `docs/milestones/` exists, read `docs/milestones/roadmap.md` and find the phase file (`docs/milestones/phase[N]-milestones.md`) whose milestone contains this feature. Use the feature's description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any phase file, note that it is unplanned work and proceed.
 
 ## Step 3: Investigate Existing Patterns
 
@@ -35,6 +36,30 @@ description: Implement a new feature following existing patterns, fully autonomo
   ```
 2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.
 
+## Step 3.5: Check the Design Specification (Before Implementation)
+
+Before implementing any feature, respect the UI/UX design specification.
+
+1. Check whether the design files exist:
+   - `docs/design/design-brief.md`
+   - `docs/design/design-tokens.json`
+   - `docs/design/ui-blueprint.json`
+   - `docs/design/platform-mapping.md`
+
+2. **If the design files do not exist**, warn the user and suggest running `/define-design` before continuing. Do not silently proceed without a design spec.
+
+3. **If the design files exist**, read all four of them before implementation:
+   1. `docs/design/design-brief.md`
+   2. `docs/design/design-tokens.json`
+   3. `docs/design/ui-blueprint.json` (source of truth)
+   4. `docs/design/platform-mapping.md`
+
+4. **If the feature changes the UI**, update the design files first, following the `/update-design` order:
+   - `ui-blueprint.json` → `design-tokens.json` → `design-brief.md` → `platform-mapping.md` → regenerate affected `screens/*.svg`
+   - The blueprint is the source of truth; SVGs are visual references only.
+
+5. Then implement the feature according to the selected platform mapping in `platform-mapping.md`, using tokens from `design-tokens.json` (no hard-coded values) and the component tree from `ui-blueprint.json`.
+
 ## Step 4: Planning Phase (Automatic Generation of Steering Files)
 
 1. Run `Skill('steering')` in **planning mode** to generate the contents of the three files created in Step 1 (`requirements.md`, `design.md`, `tasklist.md`).
@@ -96,15 +121,19 @@ If any of the following situations occur while the implementation loop is runnin
 
 **Once this step completes successfully, never stop; immediately proceed to Step 7.**
 
-## Step 7: Run Automated Tests
+## Step 7: Run Automated Tests (including Playwright E2E)
 
-1. Run the following commands in order and confirm that all tests pass.
+1. Write or update the feature's end-to-end tests following the **e2e-testing skill** (`Skill('e2e-testing')`):
+  - Create/update `e2e/[feature-name].spec.ts` covering the feature's acceptance criteria.
+  - If Playwright is not yet set up in the repository, set it up first as described in the skill.
+2. Run the following commands in order and confirm that all of them pass.
   ```bash
   Bash('npm test')
   Bash('npm run lint')
   Bash('npm run typecheck')
+  Bash('npm run test:e2e')
   ```
-2. If any command produces an error, analyze the problem, generate and apply a fix, and then run this step again.
+3. If any command produces an error, analyze the problem, generate and apply a fix, and then run this step again. Never skip or delete a failing test to make verification pass.
 
 **Once this step completes successfully, never stop; immediately proceed to Step 8.**
 
@@ -116,16 +145,30 @@ If any of the following situations occur while the implementation loop is runnin
   - Lessons learned
   - Improvement suggestions for next time
 
-2. Determine whether this change affects the project's fundamental design or architecture.
+2. **Reconcile all six persistent documents in `docs/` with the feature just implemented.** For each document, read its current content, then use the `Edit` tool to update it so it reflects the new feature. An update may be skipped **only** when the document genuinely requires no change for this feature — in that case, leave the document untouched and note the skip reason in the retrospective.
 
-3. If there is an impact, use the `Edit` tool to update the relevant persistent documents in `docs/`.
+   - ✅ `docs/product-requirements.md` — add/update user stories, acceptance criteria, non-functional requirements, and success metrics for the feature
+   - ✅ `docs/functional-design.md` — add/update functional modules, screens, data flows, and state changes introduced by the feature
+   - ✅ `docs/architecture.md` — add/update components, layers, data models, APIs, and non-functional decisions affected by the feature
+   - ✅ `docs/repository-structure.md` — add/update any new directories, files, or modules created for the feature
+   - ✅ `docs/development-guidelines.md` — add/update any new conventions, patterns, or standards established during the feature
+   - ✅ `docs/glossary.md` — add/update any new domain terms introduced by the feature
+
+3. **Update the milestone documents (if `docs/milestones/` exists)**:
+   - In the feature's phase file, use the `Edit` tool to check the feature off (`[ ]` → `[x]`).
+   - If this was the last unchecked feature of the milestone, set the milestone's status to `Completed` (in both the phase file and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone. If it was also the phase's last milestone, mark the phase `Completed` and point the roadmap at the next phase file.
+   - If the feature was not part of any milestone, add it to the current milestone's section in the current phase file as a completed (`[x]`) feature so the plan reflects reality.
+
+4. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
+
+5. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
 
 ## Completion Criteria
 
 This workflow completes automatically once all of the following conditions are met.
 - Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
 - Step 6: The `implementation-validator` subagent's validation passes.
-- Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
-- Step 8: Handover notes are recorded in `tasklist.md`.
+- Step 7: The `test`, `lint`, `typecheck`, and `test:e2e` (Playwright) commands all succeed without errors, and the feature has E2E tests covering its acceptance criteria.
+- Step 8: Handover notes are recorded in `tasklist.md`, all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its phase file (if `docs/milestones/` exists).
 
 Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.

.claude/commands/define-design.md

@@ -0,0 +1,207 @@
+---
+description: Create the UI/UX design specification (design brief, tokens, UI blueprint, platform mapping, SVG wireframes)
+---
+
+# Define Design (UI/UX Design Phase)
+
+This command creates (or updates) the project's design specification under `docs/design/`. The design is **AI-readable and implementation-ready**: the source of truth is structured text/JSON, not visual images.
+
+**Design source of truth**: `docs/design/ui-blueprint.json`
+**Visual references only**: `docs/design/screens/*.svg`
+
+## How to Run
+
+```bash
+claude
+> /define-design
+```
+
+## Position in the Workflow
+
+```
+/setup-project
+  ↓
+/define-design        ← you are here
+  ↓
+/plan-milestones      (milestone 01 = app shell, generated from this design)
+  ↓
+/execute-milestones phase1-milestones.md   (or /add-feature per feature)
+```
+
+## Pre-Run Check
+
+1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
+   - `docs/product-requirements.md`
+   - `docs/functional-design.md`
+   - `docs/architecture.md`
+2. Create the design directory if it does not exist:
+   ```bash
+   mkdir -p docs/design/screens
+   ```
+
+## Procedure
+
+### Step 0: Read the Inputs
+
+Read all of the following to understand what is being built:
+
+- `docs/product-requirements.md`
+- `docs/functional-design.md`
+- `docs/architecture.md`
+- `docs/repository-structure.md`
+- `docs/development-guidelines.md`
+- `docs/glossary.md`
+- `docs/ideas/*` (if present)
+
+### Step 1: Gather Design Preferences (ask the user once)
+
+Ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the product requirements and confirm it before proceeding.
+
+- **Target platform**: `web`, `flutter`, `winui3`, or `multi`
+- **Visual style** (e.g. friendly/modern/rounded/calm, dark or light, density)
+- **Main screens** the app must have (treat the answer as additions and constraints — the complete screen list is derived from the PRD in Step 3, never limited to what the user names here)
+- **Navigation style** (e.g. tab bar, drawer, sidebar, stack)
+- **Branding preferences** (name, colors, tone)
+- **Accessibility requirements** (e.g. WCAG level, minimum contrast, large-touch targets)
+
+Collect the answers in a single round; do not pause again until generation is complete.
+
+### Step 2: Load the Design Skills
+
+- Load the **ui-design skill** (`Skill('ui-design')`) to create `design-brief.md`, `ui-blueprint.json`, and the SVG wireframes.
+- Load the **design-tokens skill** (`Skill('design-tokens')`) to create `design-tokens.json`.
+
+### Step 3: Build the Screen Inventory (exhaustive — before designing anything)
+
+The most common design failure is a missing screen — e.g. a todo app with a list screen but no screen for adding a new item. To prevent it, enumerate **every** screen the requirements imply and write the list to `docs/design/screen-inventory.md` **before** creating any other design file.
+
+Derive the inventory from the documents read in Step 0. The user's Step 1 answer about main screens is input, never the ceiling.
+
+1. **Walk every user story and requirement** in `docs/product-requirements.md`, and every flow in `docs/functional-design.md`. For each one, write down every screen the user passes through to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
+2. **Apply CRUD coverage to every entity** the user manages (e.g. todo item, project, profile). For each entity, explicitly decide each of: list/overview, detail, **create/add**, edit, delete confirmation. Include each as an inventory entry unless the requirements clearly exclude it. If create/edit happens in a modal, dialog, or inline form rather than a full page, it is **still an inventory entry** (record its presentation) — it still needs a blueprint entry and a wireframe.
+3. **Add the supporting screens** the requirements imply: authentication (sign in / sign up / password reset), settings, onboarding, search/filter results, empty states, error / not-found.
+
+Write each entry in this format:
+
+```markdown
+- [ ] `screen-id` — Title
+  - Purpose: what the user accomplishes here
+  - Source: the PRD user story / functional-design section it comes from
+  - Reached from: the screens/actions that navigate here
+  - Presentation: page | modal | drawer
+  - Key elements: main components, inputs, and actions on the screen
+```
+
+End the file with a **traceability table**: one row per user story, listing the screen ids that fulfill it. Every user story must map to at least one screen, and every screen must trace back to at least one requirement. Do not proceed to Step 4 until both directions are fully covered.
+
+### Step 4: Create the Design Brief
+
+Create `docs/design/design-brief.md` covering:
+
+- Target users
+- Design concept
+- Visual mood
+- Layout principles
+- Navigation principles
+- Accessibility considerations
+- Platform-specific notes
+- Examples of preferred UI style
+- Examples of UI style to avoid
+
+### Step 5: Create the Design Tokens
+
+Create `docs/design/design-tokens.json` using a JSON structure inspired by the Design Tokens Community Group format (each token has `$type` and `$value`). Include:
+
+- Colors (semantic names: background, text, accent, border, state, etc.)
+- Typography (font families, sizes, weights, line heights)
+- Spacing scale
+- Border radius
+- Shadows / elevation
+- Animation durations / easings
+- Breakpoints (if the target includes web)
+
+### Step 6: Create the UI Blueprint (source of truth)
+
+Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI generation. It must describe:
+
+- App name and target platforms
+- Overall style summary
+- Routes
+- Screens (each with id, title, route, layout, and component tree)
+- Layouts
+- Components (variants and states)
+- Component hierarchy
+- User actions and navigation behavior
+
+**Coverage rule**: the blueprint must contain one screen entry for **every** entry in `docs/design/screen-inventory.md` — including modal/drawer entries. As each screen is added, check it off (`[ ]` → `[x]`) in the inventory. Do not finish this step while any inventory entry is unchecked.
+
+### Step 7: Create the Platform Mapping
+
+Create `docs/design/platform-mapping.md` describing how the design spec is converted to each platform:
+
+```text
+Web:
+- design-tokens.json → CSS variables or Tailwind theme
+- ui-blueprint.json → pages, routes, React components, layout components
+
+Flutter:
+- design-tokens.json → ThemeData, ColorScheme, constants
+- ui-blueprint.json → Widget tree, routes, reusable widgets
+
+WinUI 3:
+- design-tokens.json → ResourceDictionary
+- ui-blueprint.json → XAML pages, UserControls, styles
+```
+
+### Step 8: Generate SVG Wireframes (visual references only)
+
+For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe under `docs/design/screens/`:
+
+- `docs/design/screens/home.svg`
+- `docs/design/screens/settings.svg`
+- `docs/design/screens/[screen-id].svg`
+
+**Important rule**: SVG files are **not** the source of truth. They are generated as visual references for human review only. The source of truth is `ui-blueprint.json`. If the blueprint and an SVG ever disagree, the blueprint wins and the SVG must be regenerated.
+
+### Step 9: Consistency Check
+
+Re-read all generated files and confirm:
+
+- Every entry in `docs/design/screen-inventory.md` is checked off and has a matching screen (same id) in `ui-blueprint.json`.
+- Every user story in the PRD can be completed end-to-end using only the screens and actions in the blueprint — in particular, every entity the user can create, edit, or delete has a screen (or modal) for each of those operations.
+- Every screen in `ui-blueprint.json` has a matching SVG in `screens/`.
+- Token names referenced in `ui-blueprint.json` exist in `design-tokens.json`.
+- `platform-mapping.md` covers all target platforms selected in Step 1.
+- The design is consistent with `docs/product-requirements.md` and `docs/functional-design.md`.
+
+Fix any inconsistencies found before finishing.
+
+## Completion Criteria
+
+- `docs/design/screen-inventory.md` exists and every entry is checked off
+- `docs/design/design-brief.md` exists
+- `docs/design/design-tokens.json` exists and is valid JSON
+- `docs/design/ui-blueprint.json` exists and is valid JSON
+- `docs/design/platform-mapping.md` exists
+- One SVG per screen exists under `docs/design/screens/`
+
+Completion message:
+```
+"Design phase is complete!
+
+Design documents created:
+✅ docs/design/screen-inventory.md  (exhaustive screen list — all entries covered)
+✅ docs/design/design-brief.md
+✅ docs/design/design-tokens.json
+✅ docs/design/ui-blueprint.json   (source of truth)
+✅ docs/design/platform-mapping.md
+✅ docs/design/screens/*.svg        (visual references)
+
+Next steps:
+- Review docs/design/ (especially ui-blueprint.json)
+- Refine the design with /update-design <change> (or re-run /define-design) until approved — do this BEFORE generating code
+- Run /plan-milestones — milestone 01 (App Shell Generation) scaffolds the app from this design
+- Use /update-design when a feature changes the UI
+- Use /add-feature to add features (it respects the design spec)
+"
+```

.claude/commands/execute-milestones.md

@@ -0,0 +1,163 @@
+---
+description: Execute one phase file (phaseN-milestones.md) - implement its milestones one by one with separate steering documents per milestone
+---
+
+# Execute Milestones (Fully Autonomous Phase Execution Mode)
+
+This command executes **one phase file** from `docs/milestones/` — implementing its milestones **one at a time, in order**. For each milestone it generates a **separate set of steering documents** under `.steering/`, divides the milestone's features into concrete tasks, implements them all, validates, tests, and reconciles the documents — then immediately moves on to the next milestone in the phase file.
+
+**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. Do not ask the user for confirmation between milestones.
+
+**Phase file (required)**: `$ARGUMENTS` — the phase file to execute. Accepted forms:
+- `phase1-milestones.md`
+- `docs/milestones/phase1-milestones.md`
+- `phase1` or `1` (resolved to `docs/milestones/phase1-milestones.md`)
+
+## How to Run
+
+```bash
+claude
+> /execute-milestones phase1-milestones.md
+> /execute-milestones docs/milestones/phase2-milestones.md
+> /execute-milestones 1
+```
+
+## Position in the Workflow
+
+```
+/setup-project
+  ↓
+/define-design
+  ↓
+/plan-milestones
+  ↓
+/execute-milestones phase1-milestones.md   ← you are here (one phase file per run)
+  ↓
+/execute-milestones phase2-milestones.md   (next run)
+```
+
+## Pre-Run Check
+
+1. **The phase file argument is required.** If `$ARGUMENTS` is empty, or it does not resolve to an existing `docs/milestones/phase[N]-milestones.md` file, **stop**, list the phase files that exist under `docs/milestones/` with their statuses, and ask the user to specify one. Never pick a phase file yourself.
+2. If no phase files exist at all, stop and tell the user to run `/plan-milestones` first.
+3. Read `docs/milestones/roadmap.md`. If an **earlier phase** is not yet `Completed`, warn the user (later phases build on earlier ones) and continue only if the user accepts.
+4. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user and suggest running `/define-design` first. Do not silently proceed without a design spec.
+
+## Procedure
+
+### Step 0: Build the Execution Queue
+
+1. Read the specified phase file and `docs/milestones/roadmap.md`.
+2. The execution queue is every milestone in the phase file whose status is not already `Completed`, in ascending milestone number.
+3. If the queue is empty, report that the phase is already completed and finish.
+4. Set the phase's status to `In progress` (in the phase file header and in `roadmap.md`).
+
+### Step 1: Load the Skills
+
+1. Load the **milestone-execution skill** (`Skill('milestone-execution')`) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
+2. The **steering skill** and **development-guidelines skill** apply during implementation, exactly as in `/add-feature`.
+3. **If the milestone is the App Shell milestone (milestone 01)**, additionally load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) for the design→code mapping rules of the target platform recorded in the milestone. Its E2E verification is the `e2e/app-shell.spec.ts` smoke spec (shell renders, every blueprint route navigates).
+
+### Step 2: Milestone Loop
+
+**This step repeats for each milestone in the queue, strictly in order. Never start a milestone before the previous one has passed its gate (Step 2.8).**
+
+For the current milestone `[NN] [name]`:
+
+#### 2.1 Create the Milestone Steering Directory
+
+Create `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` with the three files:
+
+- `requirements.md`
+- `design.md`
+- `tasklist.md`
+
+Each milestone gets its **own** directory — never reuse or append to another milestone's steering documents.
+
+#### 2.2 Generate the Steering Documents
+
+Following the milestone-execution skill:
+
+- `requirements.md`: the milestone's goal, scope, and every feature with its description, related PRD requirements, affected screens, and acceptance criteria (copied and expanded from the phase file).
+- `design.md`: the implementation approach across the milestone's features — shared components, data model changes, and order of implementation — consistent with `docs/architecture.md` and `docs/design/`.
+- `tasklist.md`: the milestone's features **divided into concrete tasks, grouped by feature** (one `## Feature:` section per feature, each ending with its verification tasks). Every task must be small enough to complete in one implementation-loop iteration.
+
+#### 2.3 Check the Design Specification
+
+Apply `/add-feature` Step 3.5 for the milestone as a whole: read all four design files before implementation; if any feature in this milestone changes the UI, update the design files first (blueprint → tokens → brief → mapping → SVGs).
+
+#### 2.4 Implementation Loop
+
+Work through `tasklist.md` top to bottom using the same rules as `/add-feature` Step 5:
+
+- Use `Skill('steering')` in **implementation mode**; follow the coding standards in `Skill('development-guidelines')`.
+- Mark each task `[ ]` → `[x]` with the `Edit` tool as it completes.
+- Exception rules A (split oversized tasks) and B (strike obsolete tasks with a reason) apply.
+- **Forbidden**: skipping tasks, ending the loop with unchecked tasks, or asking the user to decide.
+
+#### 2.5 Validate the Milestone
+
+Use the `Task` tool to launch the `implementation-validator` subagent:
+- `subagent_type`: "implementation-validator"
+- `description`: "Milestone implementation validation"
+- `prompt`: "Please validate the quality of all changes implemented for milestone `[NN] [name]`. The target files are `[list of implemented file paths]`. Focus on coding standards, error handling, testability, consistency with existing patterns, and whether every feature's acceptance criteria in `.steering/[dir]/requirements.md` are met."
+
+#### 2.6 Run Automated Tests (including Playwright E2E)
+
+1. Write or update the milestone's end-to-end tests following the **e2e-testing skill** (`Skill('e2e-testing')`): one `e2e/[feature-name].spec.ts` per feature in the milestone, covering its acceptance criteria. Set up Playwright first (as described in the skill) if it is missing.
+2. Run:
+
+```bash
+Bash('npm test')
+Bash('npm run lint')
+Bash('npm run typecheck')
+Bash('npm run test:e2e')
+```
+
+If any command fails, analyze, fix, and re-run until all pass. Never skip or delete a failing test to make verification pass.
+
+#### 2.7 Retrospective and Document Reconciliation
+
+Apply `/add-feature` Step 8 for the milestone:
+
+1. Run `Skill('steering')` in **retrospective mode**; record handover notes in this milestone's `tasklist.md`.
+2. Reconcile all six persistent documents in `docs/` with everything implemented in this milestone (updates applied, or a skip reason noted for each).
+3. In the **phase file**: check off every feature of this milestone (`[ ]` → `[x]`), set the milestone's status to `Completed`, and fill in its "Completion Notes".
+4. In `docs/milestones/roadmap.md`: set this milestone's status to `Completed` and move the current-milestone pointer to the next milestone in the queue.
+
+#### 2.8 Milestone Gate — then Continue
+
+The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck/E2E (Playwright) are green, the six documents are reconciled, and the milestone status is updated in the phase file and the roadmap.
+
+**Once the gate passes, never stop; immediately start Step 2 for the next milestone in the queue.** If the gate genuinely cannot be passed (external blocker), record the blocker in the milestone's `tasklist.md`, the phase file, and `roadmap.md`, then stop and report — this is the only permitted early stop.
+
+### Step 3: Close the Phase and Report
+
+1. When the queue is empty, set the phase's status to `Completed` in the phase file header and in `roadmap.md`, and move the roadmap's current-phase pointer to the next phase file (or mark the roadmap complete if this was the last phase).
+2. Report per milestone: steering directory created, features implemented, test results, and document updates.
+
+## Completion Criteria
+
+- Every milestone in the specified phase file has status `Completed`.
+- The phase's status is `Completed` in both the phase file and `docs/milestones/roadmap.md`.
+- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
+- Tests, lint, typecheck, and Playwright E2E tests pass on the final state, with E2E coverage for every implemented feature's acceptance criteria.
+- The six persistent documents reflect everything implemented.
+
+Completion message:
+```
+"Phase execution is complete: [phase file]
+
+Executed:
+✅ Milestone 01 [name] — .steering/[date]-milestone-01-[name]/ ([n] features, [m] tasks)
+✅ Milestone NN [name] — .steering/[date]-milestone-NN-[name]/ ([n] features, [m] tasks)
+
+All statuses updated in [phase file] and docs/milestones/roadmap.md.
+
+Next steps:
+- Review the retrospectives in each milestone's tasklist.md
+- Run the app and verify the phase end-to-end
+- Continue with the next phase: /execute-milestones [next phase file]
+- Re-run /plan-milestones if the remaining roadmap should change
+"
+```

.claude/commands/plan-milestones.md

@@ -0,0 +1,149 @@
+---
+description: Plan development milestones grouped into phases and generate one phase file (phaseN-milestones.md) with the milestones and features for each phase
+---
+
+# Plan Milestones (Milestone Planning Phase)
+
+This command breaks the product down into **phases**, each containing one or more **milestones**, and generates one file per phase under `docs/milestones/` (`phase1-milestones.md`, `phase2-milestones.md`, …). Each milestone lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run. Each phase file is the execution unit for `/execute-milestones`.
+
+**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 2 phases, MVP in phase 1, auth first`)
+
+## How to Run
+
+```bash
+claude
+> /plan-milestones
+> /plan-milestones 2 phases, MVP first, payments last
+```
+
+## Position in the Workflow
+
+```
+/setup-project
+  ↓
+/define-design
+  ↓
+/plan-milestones        ← you are here
+  ↓
+/execute-milestones phase1-milestones.md   (one phase file at a time; milestone 01 generates the app shell)
+```
+
+## Pre-Run Check
+
+1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
+   - `docs/product-requirements.md`
+   - `docs/functional-design.md`
+   - `docs/architecture.md`
+2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user that milestones will be planned without a design spec — and that milestone 01 (App Shell Generation) is scaffolded from that spec — and suggest running `/define-design` first. Continue only if the user accepts.
+3. Create the milestones directory if it does not exist:
+   ```bash
+   mkdir -p docs/milestones
+   ```
+
+## Procedure
+
+### Step 0: Read the Inputs
+
+Read all of the following:
+
+- `docs/product-requirements.md` (especially user stories and priorities)
+- `docs/functional-design.md`
+- `docs/architecture.md`
+- `docs/design/ui-blueprint.json` and `docs/design/design-brief.md` (if present)
+- `docs/ideas/*` (if present)
+- The planning preferences provided in `$ARGUMENTS` (if any)
+
+### Step 1: Gather Planning Preferences (ask the user once)
+
+If `$ARGUMENTS` does not already answer these, ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the PRD priorities and confirm it before proceeding.
+
+- **Target platform** — `web`, `flutter`, or `winui3` (propose the default from `docs/architecture.md` and `docs/design/platform-mapping.md`); milestone 01 generates the app shell for this platform
+- **Number of phases** (default: 2–3) and **milestones per phase** (default: 1–3)
+- **MVP definition** — what is the smallest product worth releasing? (phase 1 must deliver it)
+- **Priorities** — features that must come first or last
+- **Constraints** — deadlines, dependencies on external systems, team capacity
+
+Collect the answers in a single round; do not pause again until generation is complete.
+
+### Step 2: Load the Milestone Planning Skill
+
+Load the **milestone-planning skill** (`Skill('milestone-planning')`) for the planning rules and the phase file template.
+
+### Step 3: Build the Feature Inventory
+
+Derive the complete list of features from the documents:
+
+- Every user story / requirement in the PRD (with its priority)
+- Every functional module in the functional design
+- Every screen and user action in `ui-blueprint.json` (if present)
+
+Size each feature so it can be implemented with **one `/add-feature` run**. Split anything larger; merge trivial fragments.
+
+### Step 4: Group Features into Milestones, and Milestones into Phases
+
+- Number milestones globally and consecutively across all phases (`01`, `02`, …).
+- **Milestone 01 is always "App Shell Generation"** (there is no separate generate-app command — the shell is built as the first milestone). Following the **platform-ui-generation skill**, it scaffolds the app for the target platform from `docs/design/`: theme from `design-tokens.json`, routes/screens (one per blueprint screen) and reusable components from `ui-blueprint.json`, **no feature logic**, plus Playwright setup with the `e2e/app-shell.spec.ts` smoke spec. Its features are pre-defined in the milestone-planning skill.
+- **Milestone 02 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product on top of the shell.
+- Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
+- **Phase 1 delivers the MVP**: it contains milestones 01 (app shell) and 02 (plus any milestone needed to make the MVP releasable). Later phases group the remaining milestones by theme and priority — each phase should be a meaningful release on its own.
+- Every feature belongs to **exactly one** milestone, and every milestone to **exactly one** phase. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
+
+### Step 5: Create the Roadmap Overview
+
+Create `docs/milestones/roadmap.md` containing:
+
+- A table of all phases and their milestones: phase, file, milestone number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
+- The ordering rationale (why this sequence)
+- A pointer to the current phase file and current milestone
+- The "Later / Icebox" list of consciously deferred items
+
+### Step 6: Create One File per Phase
+
+For each phase, create `docs/milestones/phase[N]-milestones.md` (e.g. `phase1-milestones.md`, `phase2-milestones.md`) following the milestone-planning skill's template. Each phase file contains:
+
+- The phase header: goal, status, and its ready-to-run command: `/execute-milestones phase[N]-milestones.md`
+- One section per milestone in the phase (goal, scope, dependencies, definition of done)
+- Under each milestone, its features — and each feature includes:
+  - A checkbox for status tracking (`- [ ]`)
+  - Description and user value
+  - Related PRD requirements / user stories
+  - Affected screens from `ui-blueprint.json` (if a design spec exists)
+  - Acceptance criteria
+  - The ready-to-run command: `/add-feature [feature name]`
+
+### Step 7: Consistency Check
+
+Re-read all generated files and confirm:
+
+- Milestone 01 is the App Shell milestone (target platform recorded, features per the milestone-planning skill).
+- Every P0/P1 requirement in the PRD is covered by a milestone (or explicitly parked in the icebox).
+- Every feature appears in exactly one milestone, and every milestone in exactly one phase file.
+- Milestone numbering is global and consecutive across the phase files.
+- Dependencies are ordered correctly across milestones and phases.
+- Phase 1 delivers a coherent, usable MVP on its own.
+- Each feature name works as a `/add-feature` argument, and each phase file name works as an `/execute-milestones` argument.
+
+Fix any inconsistencies found before finishing.
+
+## Completion Criteria
+
+- `docs/milestones/roadmap.md` exists
+- One `phase[N]-milestones.md` per phase exists
+- Every feature is assigned to exactly one milestone (in exactly one phase file) with acceptance criteria
+
+Completion message:
+```
+"Milestone planning is complete!
+
+Milestone documents created:
+✅ docs/milestones/roadmap.md            (overview + status)
+✅ docs/milestones/phase1-milestones.md  (MVP phase: milestone 01 = app shell, milestones 02–NN)
+✅ docs/milestones/phase2-milestones.md  (milestones NN–NN)
+
+Next steps:
+- Review docs/milestones/ and adjust priorities if needed
+- Run /execute-milestones phase1-milestones.md to implement phase 1 (a separate steering directory is created per milestone)
+- Or go feature by feature: run /add-feature [first feature of milestone 01 — the app shell]
+- Either way, each feature is marked complete in its phase file as it finishes
+"
+```

.claude/commands/review-docs.md

@@ -4,7 +4,7 @@ description: Run a detailed document review using a subagent
 
 # Document Review
 
-Argument: document path (e.g. `/review-docs docs/product-requirements.md`)
+**Document path**: `$ARGUMENTS` (e.g. `/review-docs docs/product-requirements.md`)
 
 ## How to Run
 
@@ -26,7 +26,7 @@ Launch the doc-reviewer subagent to run the review:
 Use the Task tool to launch the doc-reviewer subagent:
 - subagent_type: "doc-reviewer"
 - description: "Document detailed review"
-- prompt: "Please review [document path] in detail.\n\nEvaluate it from the following perspectives:\n1. Completeness: Are all required items included?\n2. Specificity: Are there any ambiguous expressions?\n3. Consistency: Is it consistent with other documents?\n4. Measurability: Are success metrics measurable? (for a PRD)\n\nPlease produce a review report."
+- prompt: "Please review $ARGUMENTS in detail.\n\nEvaluate it from the following perspectives:\n1. Completeness: Are all required items included?\n2. Specificity: Are there any ambiguous expressions?\n3. Consistency: Is it consistent with other documents?\n4. Measurability: Are success metrics measurable? (for a PRD)\n\nPlease produce a review report."
 
 ### Step 3: Summarize the Review Results
 

.claude/commands/setup-project.md

@@ -1,10 +1,10 @@
 ---
-description: "Initial setup: interactively create the six persistent documents"
+description: "Initial setup: automatically create the six persistent documents"
 ---
 
 # Initial Project Setup
 
-This command interactively creates the project's six persistent documents.
+This command automatically creates the project's six persistent documents without pausing for human feedback between steps.
 
 ## How to Run
 
@@ -26,7 +26,7 @@ ls docs/ideas/
 
 # If no files exist
 ⚠️  No files found in docs/ideas/
-   The PRD will be created interactively
+   The PRD will be created from the project context
 ```
 
 ## Procedure
@@ -38,21 +38,21 @@ ls docs/ideas/
 
 ### Step 1: Create the Product Requirements Document
 
-1. Load the **prd-writing skill**
+1. Load the **prd-writing skill** to guide PRD creation
 2. Create `docs/product-requirements.md` based on the contents of `docs/ideas/`
 3. Flesh out the ideas raised during brainstorming:
    - Detailed user stories
    - Acceptance criteria
    - Non-functional requirements
    - Success metrics
-4. Ask the user for confirmation and **wait until approved**
+4. Run the skill's self-check checkpoints; if issues are found, fix them inline, then proceed immediately to the next step
 
-**The subsequent steps are based on the Product Requirements Document, so they are created automatically**
+**All subsequent steps run automatically without waiting for human feedback.**
 
 ### Step 2: Create the Functional Design Document
 
 1. Load the **functional-design skill**
-1. Read `docs/product-requirements.md`
+2. Read `docs/product-requirements.md`
 3. Create `docs/functional-design.md` following the skill's template and guide
 
 ### Step 3: Create the Architecture Design Document

.claude/commands/update-design.md

@@ -0,0 +1,92 @@
+---
+description: Refine the design before the app shell is generated (milestone 01), or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
+---
+
+# Update Design
+
+This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** the app shell is generated by milestone 01 (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested.
+
+**Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)
+
+## How to Run
+
+```bash
+claude
+> /update-design add a profile screen with avatar and edit form
+```
+
+## Pre-Run Check
+
+Confirm the design files exist. If they are missing, stop and tell the user to run `/define-design` first:
+
+- `docs/design/design-brief.md`
+- `docs/design/design-tokens.json`
+- `docs/design/ui-blueprint.json`
+- `docs/design/platform-mapping.md`
+
+## Procedure
+
+### Step 0: Read the Inputs
+
+Read:
+
+- The existing design files listed above
+- `docs/product-requirements.md` and `docs/functional-design.md` for context
+- The change description provided in `$ARGUMENTS`
+
+### Step 1: Update `ui-blueprint.json` First
+
+The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.
+
+If the change adds or removes screens, also update `docs/design/screen-inventory.md` (create it if missing — see the ui-design skill) so it stays the complete screen list: new screens get a checked (`[x]`) entry with purpose, source, and how they are reached; removed screens are deleted from it.
+
+### Step 2: Update `design-tokens.json` (if needed)
+
+If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.
+
+### Step 3: Update `design-brief.md` (if the direction changes)
+
+If the change affects the overall design direction (visual mood, layout principles, navigation principles, accessibility), update the brief. If it is a localized screen/component change, leave the brief unchanged.
+
+### Step 4: Update `platform-mapping.md` (if needed)
+
+If the change introduces a new platform target or a new kind of mapping (e.g. a new component family that maps differently per platform), update the mapping. Otherwise leave it unchanged.
+
+### Step 5: Regenerate Affected SVG Wireframes
+
+For every screen added or modified in `ui-blueprint.json`, generate or regenerate the corresponding SVG under `docs/design/screens/`. Remember: SVGs are visual references only — the blueprint is the source of truth.
+
+### Step 6: Consistency Check
+
+- Every screen in `ui-blueprint.json` has a matching SVG.
+- `docs/design/screen-inventory.md` (if present) lists exactly the blueprint's screens.
+- Token names referenced in the blueprint exist in `design-tokens.json`.
+- The brief and mapping remain consistent with the blueprint.
+
+### Step 7: Do Not Implement Code
+
+Do **not** modify application code in this command. If the user also wants the code updated, they should run `/add-feature` (which reads the updated design files) or ask explicitly.
+
+## Completion Criteria
+
+- `ui-blueprint.json` has been updated (source of truth).
+- `design-tokens.json` updated only if new tokens were needed.
+- `design-brief.md` updated only if the direction changed.
+- `platform-mapping.md` updated only if mappings changed.
+- Affected SVG wireframes regenerated.
+- No application code was changed.
+
+Completion message:
+```
+"Design has been updated.
+
+Updated:
+✅ docs/design/ui-blueprint.json   (source of truth)
+✅ docs/design/design-tokens.json   (if new tokens were needed)
+✅ docs/design/design-brief.md      (if the direction changed)
+✅ docs/design/platform-mapping.md  (if mappings changed)
+✅ docs/design/screens/*.svg        (regenerated as needed)
+
+Note: application code was not changed. Run /add-feature to implement the change, respecting the updated design.
+"
+```

.claude/settings.json

@@ -6,7 +6,14 @@
       "Skill(architecture-design)",
       "Skill(repository-structure)",
       "Skill(development-guidelines)",
-      "Skill(glossary-creation)"
+      "Skill(glossary-creation)",
+      "Skill(ui-design)",
+      "Skill(design-tokens)",
+      "Skill(platform-ui-generation)",
+      "Skill(milestone-planning)",
+      "Skill(milestone-execution)",
+      "Skill(e2e-testing)",
+      "Skill(steering)"
     ],
     "deny": [],
     "ask": []

.claude/skills/design-tokens/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: design-tokens
+description: Guide for creating and maintaining design-tokens.json, the single source of styling values for Web, Flutter, and WinUI 3. Use when creating or updating design tokens.
+allowed-tools: Read, Write, Edit
+---
+
+# Design Tokens Skill
+
+This skill explains how to create and maintain `docs/design/design-tokens.json` — the single source of truth for all styling values (color, typography, spacing, radius, shadow, motion, breakpoints). Generated platform code must read from these tokens and must never hard-code values.
+
+## Core Principle
+
+> One token definition → many platform outputs. Never hard-code a color, size, or spacing in generated code.
+
+## Format
+
+Use a JSON structure inspired by the Design Tokens Community Group format. Every token is an object with `$type` and `$value`:
+
+```json
+{
+  "color": {
+    "background": {
+      "primary": { "$type": "color", "$value": "#0F172A" }
+    }
+  },
+  "spacing": {
+    "md": { "$type": "dimension", "$value": "16px" }
+  }
+}
+```
+
+Supported `$type` values: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, `strokeStyle`.
+
+## Token Groups
+
+`design-tokens.json` should include these groups (omit a group only if it truly does not apply):
+
+- **color** — semantic color tokens
+- **typography** — font families, sizes, weights, line heights
+- **spacing** — spacing scale (xs, sm, md, lg, xl, …)
+- **radius** — border radius scale
+- **shadow** / **elevation** — box-shadow / elevation tokens
+- **motion** — animation durations and easings
+- **breakpoint** — responsive breakpoints (include when `web` is a target)
+
+## Rules
+
+### Naming tokens
+
+- Use **semantic names**, not descriptive names. `color.text.primary` (good) vs `color.slate-900` (bad).
+- Use a consistent scale for numeric families: `sm`, `md`, `lg`, `xl` — or numeric `4`, `8`, `12` — pick one and stick to it.
+- Group by role then by emphasis: `color.background.primary`, `color.background.muted`, `color.text.primary`, `color.text.secondary`, `color.accent.primary`, `color.state.success`, `color.state.danger`.
+- Token names are referenced verbatim in `ui-blueprint.json` (e.g. `"padding": "lg"`). They must match exactly.
+
+### Using semantic color names
+
+- Define colors by **role** (background, text, accent, border, state, overlay) and **emphasis** (primary, secondary, muted).
+- Do not expose raw hex scales as the only option. If you need a raw scale, keep it in a separate `color.palette` group and reference it from semantic tokens.
+- Provide both light and dark values where the app supports them: `color.background.primary` (light) and `color.background.primary-dark`, or a `dark` sub-object — pick one convention and document it in `platform-mapping.md`.
+
+### Avoiding hard-coded values in generated code
+
+- Generated Web code uses CSS variables / Tailwind theme keys / theme objects derived from tokens.
+- Generated Flutter code uses `ThemeData`, `ColorScheme`, and constants derived from tokens.
+- Generated WinUI 3 code uses `ResourceDictionary` entries derived from tokens.
+- **Never** inline `#0F172A` or `16px` in generated source. Always reference the token-derived variable/resource.
+- If a value is needed that has no token, add the token to `design-tokens.json` first, then use it.
+
+### Mapping tokens to platform-specific code
+
+`design-tokens.json` is platform-agnostic. The conversion to each platform is documented in `docs/design/platform-mapping.md` and performed by the **platform-ui-generation** skill. This skill only defines and maintains the tokens.
+
+## Example
+
+```json
+{
+  "color": {
+    "background": {
+      "primary": { "$type": "color", "$value": "#0F172A" },
+      "muted": { "$type": "color", "$value": "#1E293B" }
+    },
+    "text": {
+      "primary": { "$type": "color", "$value": "#F8FAFC" },
+      "secondary": { "$type": "color", "$value": "#94A3B8" }
+    },
+    "accent": {
+      "primary": { "$type": "color", "$value": "#38BDF8" }
+    },
+    "state": {
+      "success": { "$type": "color", "$value": "#22C55E" },
+      "danger": { "$type": "color", "$value": "#EF4444" }
+    }
+  },
+  "typography": {
+    "fontFamily": {
+      "base": { "$type": "fontFamily", "$value": "Inter, system-ui, sans-serif" }
+    },
+    "size": {
+      "sm": { "$type": "dimension", "$value": "14px" },
+      "md": { "$type": "dimension", "$value": "16px" },
+      "lg": { "$type": "dimension", "$value": "20px" }
+    }
+  },
+  "spacing": {
+    "sm": { "$type": "dimension", "$value": "8px" },
+    "md": { "$type": "dimension", "$value": "16px" },
+    "lg": { "$type": "dimension", "$value": "24px" }
+  },
+  "radius": {
+    "card": { "$type": "dimension", "$value": "16px" },
+    "pill": { "$type": "dimension", "$value": "9999px" }
+  },
+  "shadow": {
+    "card": { "$type": "shadow", "$value": "0 4px 12px rgba(0,0,0,0.15)" }
+  },
+  "motion": {
+    "duration": {
+      "fast": { "$type": "duration", "$value": "120ms" },
+      "base": { "$type": "duration", "$value": "200ms" }
+    }
+  },
+  "breakpoint": {
+    "sm": { "$type": "dimension", "$value": "640px" },
+    "md": { "$type": "dimension", "$value": "768px" },
+    "lg": { "$type": "dimension", "$value": "1024px" }
+  }
+}
+```
+
+## Maintenance Checklist
+
+When updating tokens:
+
+- [ ] JSON is valid.
+- [ ] Token names referenced in `ui-blueprint.json` still exist (no broken references after a rename).
+- [ ] New tokens follow the naming and semantic-name rules.
+- [ ] No duplicate tokens (same role under two names).
+- [ ] `platform-mapping.md` still covers how every token group maps to each target platform.

.claude/skills/development-guidelines/SKILL.md

@@ -90,6 +90,7 @@ When creating development guidelines: ./template.md
 ### When Designing Tests
 - "Test Strategy" in ./guides/process.md (pyramid, coverage)
 - "Test Code" in ./guides/implementation.md (implementation patterns)
+- E2E tests: the **e2e-testing skill** (Playwright — E2E is part of every verification step)
 
 ### When Preparing a Release
 - "Git Workflow Rules" in ./guides/process.md (policy for merging into main)

.claude/skills/e2e-testing/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: e2e-testing
+description: Guide for writing and running Playwright end-to-end tests as part of every verification step. Use when verifying a feature, milestone, or generated app shell, or when setting up Playwright in the repository.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# E2E Testing Skill (Playwright)
+
+This skill defines how end-to-end tests are written and run in this project. **Every verification step includes E2E tests**: a feature, milestone, or app shell is not "verified" until its Playwright tests pass alongside unit tests, lint, and typecheck.
+
+## Core Principles
+
+1. **E2E is part of verification, not an extra**: the standard verification sequence is `npm test` → `npm run lint` → `npm run typecheck` → `npm run test:e2e`. All four must pass.
+2. **Tests are derived from acceptance criteria**: every feature's acceptance criteria (from its phase file or steering `requirements.md`) map to E2E assertions. If a criterion cannot be asserted in an E2E test, note why in the tasklist.
+3. **Blueprint-driven selectors**: screens, routes, and actions come from `docs/design/ui-blueprint.json`. Tests navigate by the blueprint's routes and interact via the blueprint's actions.
+4. **One spec file per feature** plus one smoke spec for the app shell.
+5. **Web-first**: Playwright covers the `web` target. For `flutter` use `integration_test`, for `winui3` use the platform's UI automation — apply the same acceptance-criteria mapping; note in the tasklist when Playwright does not apply.
+
+## Setup (run once, on demand)
+
+If Playwright is not yet set up in the repository (no `@playwright/test` in `package.json`), set it up before the first E2E run:
+
+```bash
+npm install -D @playwright/test
+npx playwright install --with-deps chromium
+```
+
+Create `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: [['list'], ['html', { open: 'never' }]],
+  use: {
+    baseURL: process.env.E2E_BASE_URL ?? 'http://localhost:3000',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+  },
+  webServer: {
+    command: 'npm run dev',       // adjust to the project's start command
+    url: 'http://localhost:3000', // adjust to the project's port
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+Add the script to `package.json`:
+
+```json
+"test:e2e": "playwright test"
+```
+
+Adjust `baseURL`, `webServer.command`, and the port to the project's actual dev server (see `docs/architecture.md`). Add `e2e/` artifacts (`playwright-report/`, `test-results/`) to `.gitignore`.
+
+## Test Layout
+
+```
+e2e/
+├── app-shell.spec.ts        # smoke: shell renders, every blueprint route navigates
+├── [feature-name].spec.ts   # one spec per feature
+└── helpers/                  # shared fixtures/utilities (only when duplicated 3+ times)
+```
+
+## Writing Feature Specs
+
+For each feature, create `e2e/[kebab-case-feature-name].spec.ts`:
+
+- One `test.describe` block per feature; one `test` per acceptance criterion (or a tight group of criteria).
+- Navigate using the route of the affected screen from `ui-blueprint.json`.
+- Prefer semantic locators: `getByRole`, `getByLabel`, `getByText` — matching the blueprint's component types and labels. Avoid CSS/XPath selectors tied to implementation details.
+- No fixed waits (`waitForTimeout`); rely on Playwright's auto-waiting and explicit `expect(...).toBeVisible()` style assertions.
+- Keep tests independent: each test sets up its own state and does not depend on execution order.
+
+Example:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Edit user profile', () => {
+  test('saves a changed display name', async ({ page }) => {
+    await page.goto('/profile');
+    await page.getByLabel('Display name').fill('New Name');
+    await page.getByRole('button', { name: 'Save' }).click();
+    await expect(page.getByText('Profile updated')).toBeVisible();
+  });
+});
+```
+
+## Writing the App-Shell Smoke Spec
+
+Created by the App Shell milestone (milestone 01, web target). `e2e/app-shell.spec.ts` must verify:
+
+- The app starts and the entry screen renders.
+- Every route in `ui-blueprint.json` is reachable and renders its screen title.
+- Primary navigation (from the blueprint's nav component) works.
+
+## Running
+
+```bash
+npm run test:e2e
+```
+
+- If a test fails, analyze the trace/screenshot in `test-results/`, fix the code (or the test if the spec was wrong against the acceptance criteria), and re-run until green.
+- Never delete or skip a failing test to make verification pass; a skipped test requires a written reason in the tasklist, same as a struck task.
+
+## Verification Checklist
+
+Used by `/add-feature` Step 7 and `/execute-milestones` Step 2.6 (including the App Shell milestone):
+
+- [ ] Playwright is set up (`test:e2e` script exists) — set it up via this skill if missing.
+- [ ] Every implemented feature has `e2e/[feature].spec.ts` covering its acceptance criteria.
+- [ ] The app-shell smoke spec still passes.
+- [ ] `npm test`, `npm run lint`, `npm run typecheck`, and `npm run test:e2e` all pass.
+- [ ] No test was skipped or deleted without a written reason.

.claude/skills/milestone-execution/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: milestone-execution
+description: Guide for executing one phase file (phaseN-milestones.md) - implementing its milestones one by one, with a separate steering directory per milestone, features divided into tasks, and gate criteria between milestones. Use when running /execute-milestones or implementing a whole milestone in one run.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Milestone Execution Skill
+
+This skill explains how to execute **one phase file** (`docs/milestones/phase[N]-milestones.md`) — implementing its milestones one at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory, and a `/execute-milestones` run covers exactly the milestones of the given phase file, strictly in order.
+
+## Core Principles
+
+1. **One phase file per run**: `/execute-milestones` always operates on an explicitly specified phase file — never on "everything". The next phase requires a new run with the next file.
+2. **One milestone = one steering directory**: every milestone gets its own `.steering/[YYYYMMDD]-milestone-[NN]-[name]/` with its own `requirements.md`, `design.md`, and `tasklist.md`. Documents are never shared or reused between milestones.
+3. **Strict order, one at a time**: milestones execute in ascending number within the phase file. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
+4. **Features divided into tasks**: the milestone's features (from its section in the phase file) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The phase file stays the "what"; the steering tasklist is the "how".
+5. **Same discipline as `/add-feature`**: the steering skill's implementation mode, the development guidelines, the validator subagent, and the test loop all apply per milestone.
+6. **Status flows upward**: task status lives in the steering `tasklist.md`; feature, milestone, and phase status live in the phase file and `roadmap.md`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer; when the phase's last milestone completes, mark the phase `Completed` and point the roadmap at the next phase file.
+
+## Steering Directory per Milestone
+
+Naming: `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` (e.g. `.steering/20260702-milestone-01-mvp/`).
+
+### `requirements.md`
+- Milestone goal (from the milestone's section in the phase file)
+- In/out of scope
+- One section per feature: description, related PRD requirements, affected screens, acceptance criteria
+- The milestone's Definition of Done
+
+### `design.md`
+- Implementation approach across the whole milestone
+- Shared components and data-model changes used by multiple features (build these first)
+- Feature implementation order within the milestone, with a one-line rationale
+- Consistency notes against `docs/architecture.md` and `docs/design/ui-blueprint.json`
+
+### `tasklist.md`
+Tasks are **grouped by feature**, in the implementation order chosen in `design.md`:
+
+```markdown
+# Tasklist: Milestone 01 — MVP
+
+## Shared Foundations
+- [ ] [Task that multiple features depend on, e.g. data model, shared component]
+
+## Feature: Register account
+- [ ] [Task 1: data/model layer]
+- [ ] [Task 2: logic/service layer]
+- [ ] [Task 3: UI per affected screen]
+- [ ] [Task 4: unit tests + Playwright E2E spec for the acceptance criteria]
+
+## Feature: Log in / log out
+- [ ] ...
+
+## Milestone Verification
+- [ ] All acceptance criteria in requirements.md confirmed
+- [ ] E2E specs exist for every feature (e2e/[feature].spec.ts, per the e2e-testing skill)
+- [ ] npm test / lint / typecheck / test:e2e pass
+
+## Post-Implementation Retrospective
+_Filled at the end: completion date, plan vs. actual, lessons learned._
+```
+
+## How to Divide a Feature into Tasks
+
+- 3–8 tasks per feature; each completable in **one implementation-loop iteration**.
+- Slice along the natural layers the feature touches: data/model → logic/service → UI (one task per affected screen) → tests (unit + Playwright E2E).
+- Every feature's section ends with a task that verifies its acceptance criteria via the feature's E2E spec (see the e2e-testing skill).
+- Tasks that unblock several features go into a "Shared Foundations" section at the top — never duplicated per feature.
+
+## Gate Criteria Between Milestones
+
+A milestone passes its gate only when **all** of the following hold. Only then may the next milestone start:
+
+- [ ] Every task in the milestone's `tasklist.md` is `[x]` (or struck with a technical reason).
+- [ ] The `implementation-validator` subagent's validation passed.
+- [ ] Every feature of the milestone has a Playwright E2E spec covering its acceptance criteria.
+- [ ] `npm test`, `npm run lint`, `npm run typecheck`, `npm run test:e2e` all succeed.
+- [ ] The six persistent documents in `docs/` are reconciled with the milestone's changes.
+- [ ] In the phase file: every feature of the milestone is checked off, and the milestone status is `Completed` with Completion Notes.
+- [ ] `roadmap.md` points to the next milestone (or, after the phase's last milestone, the phase is `Completed` and the roadmap points to the next phase file).
+
+## Failure Handling
+
+- **A task fails repeatedly**: split it (exception rule A) or re-approach via `design.md`; do not skip it.
+- **A feature turns out to be unimplementable as specified**: update the phase file and `requirements.md` with the revised scope and reason, then continue — the plan must reflect reality.
+- **An external blocker stops the milestone** (missing credential, unavailable service, a decision only the user can make): record the blocker in the milestone's `tasklist.md`, in the phase file, and in `roadmap.md` (status stays `In progress`), then stop and report. This is the **only** permitted early stop; never silently skip to the next milestone, because later milestones depend on earlier ones.
+
+## Consistency Checklist
+
+Before declaring a milestone (or the whole run) complete:
+
+- [ ] Each executed milestone has exactly one steering directory, named `[date]-milestone-[NN]-[name]`.
+- [ ] Every feature of the milestone appears as a section in that `tasklist.md`.
+- [ ] Feature checkboxes in the phase file match the completed work.
+- [ ] Milestone and phase statuses in the phase file match `roadmap.md`, and the roadmap pointers are correct.
+- [ ] No task or feature from a later milestone or a later phase file was implemented early.

.claude/skills/milestone-planning/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: milestone-planning
+description: Guide for planning development milestones grouped into phases and generating one phase file (phaseN-milestones.md) with the milestones and feature breakdown for each phase. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
+allowed-tools: Read, Write, Edit
+---
+
+# Milestone Planning Skill
+
+This skill explains how to break a product into ordered **phases** and **milestones**, and produce one phase file per phase under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation: every feature in every milestone is sized to be implemented with **one `/add-feature` run**, and every phase file is sized to be executed with **one `/execute-milestones` run**.
+
+## Hierarchy
+
+```
+Roadmap (roadmap.md)
+└── Phase (phase[N]-milestones.md — the /execute-milestones unit)
+    └── Milestone (numbered globally: 01, 02, …)
+        └── Feature (the /add-feature unit)
+```
+
+## Core Principles
+
+1. **App shell first**: Milestone 01 is always **App Shell Generation** — there is no separate generate-app command; the initial app is built as the first milestone (see "Milestone 01" below).
+2. **MVP first**: Phase 1 delivers the MVP; milestone 02 is its core — the smallest coherent, end-to-end usable product on top of the shell. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
+3. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
+4. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
+5. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
+6. **Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
+7. **Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
+8. **Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`.
+
+## Inputs
+
+Before planning, read:
+
+- `docs/product-requirements.md` — user stories, priorities (P0/P1/P2), success metrics
+- `docs/functional-design.md` — functional modules and data flows
+- `docs/architecture.md` — technical constraints and dependencies
+- `docs/design/ui-blueprint.json` (if present) — screens and user actions
+- `docs/ideas/*` (if present)
+
+## Outputs
+
+```
+docs/milestones/
+├── roadmap.md               # Overview: phase/milestone table, ordering rationale, icebox
+├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
+├── phase2-milestones.md
+└── phaseN-milestones.md
+```
+
+File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-milestones.md`). Milestones are numbered globally and consecutively across all phase files (`01`, `02`, …) — numbering never restarts per phase.
+
+Use the structure in `template.md` for each phase file and for the roadmap.
+
+## Milestone 01: App Shell Generation (always the first milestone)
+
+The initial app is not created by a separate command — it is **milestone 01**, the first milestone of phase 1, executed like any other milestone (via `/execute-milestones phase1-milestones.md` or feature by feature with `/add-feature`). Implementation follows the **platform-ui-generation skill** for the design→code mapping.
+
+Record the **target platform** (`web` | `flutter` | `winui3`) in the milestone's Scope. Its features are:
+
+- [ ] Generate the app shell and theme from the design tokens — entry point, layout shell, and the platform's styling system converted from `design-tokens.json`
+- [ ] Generate routes, screens, and reusable components from the UI blueprint — one screen per `ui-blueprint.json` entry, navigation wired, shared components extracted, **no feature logic**
+- [ ] Set up Playwright and the app-shell smoke spec — `playwright.config.ts`, `test:e2e` script, and `e2e/app-shell.spec.ts` verifying the shell renders and every blueprint route navigates (see the e2e-testing skill; platform equivalents for flutter/winui3)
+
+Definition of done (in addition to the standard one): the app runs, every blueprint screen is reachable, tokens are the only styling source (no hard-coded values), and no feature logic exists beyond what the documents describe.
+
+**Dependency**: milestone 01 requires the design spec (`docs/design/`). Every later milestone depends on milestone 01.
+
+## How to Slice Features
+
+A well-sized feature:
+
+- Delivers observable user value (or unblocks one that does)
+- Touches one primary screen/flow (may touch shared components)
+- Has 3–7 acceptance criteria
+- Can be described in one sentence starting with a verb ("Edit user profile", "Filter tasks by tag")
+- Works verbatim as a command argument: `/add-feature Edit user profile`
+
+Too big (split it): "User management" → "Register account", "Log in / log out", "Edit user profile", "Reset password".
+Too small (merge it): "Change button color" → fold into the feature that owns that screen.
+
+## How to Group Milestones and Phases
+
+1. Tag every feature with its PRD priority and its dependencies.
+2. Milestone 01 (App Shell): always first — see "Milestone 01" above.
+3. Milestone 02 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
+4. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
+5. **Phase 1** contains milestones 01 and 02 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
+6. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.
+
+## Status Tracking Rules
+
+- Feature status lives **only** in the feature checkbox inside its phase file.
+- Milestone status (`Not started` / `In progress` / `Completed`) lives in the milestone's section of the phase file **and** in the roadmap table — keep them in sync.
+- Phase status lives in the phase file header **and** in the roadmap table.
+- `/add-feature` Step 8 updates the feature checkbox; `/execute-milestones` additionally updates milestone and phase statuses and the roadmap pointers.
+- Re-planning (adding/moving/removing features or milestones) must update both the affected phase file(s) and `roadmap.md` in the same change.
+
+## Consistency Checklist
+
+Before finishing:
+
+- [ ] Milestone 01 is the App Shell milestone, with its target platform recorded and the three shell features listed.
+- [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox).
+- [ ] Every feature appears in exactly one milestone; every milestone in exactly one phase file.
+- [ ] Milestone numbering is global and consecutive across phase files.
+- [ ] No feature or milestone precedes one of its dependencies.
+- [ ] Phase 1 delivers a usable end-to-end MVP on its own.
+- [ ] Every feature has acceptance criteria and a ready-to-run `/add-feature` command line.
+- [ ] Every phase file header has its ready-to-run `/execute-milestones` command line.
+- [ ] `roadmap.md` table matches the phase files (names, counts, statuses).

.claude/skills/milestone-planning/template.md

@@ -0,0 +1,107 @@
+# Phase File Template
+
+Use this structure for each `docs/milestones/phase[N]-milestones.md`. A phase file contains one or more milestones; milestone numbers are global across all phase files.
+
+**Milestone 01 is always "App Shell Generation"** (first milestone of phase 1): its In Scope records the target platform (`web` | `flutter` | `winui3`), its features are the three shell features defined in SKILL.md (theme from tokens, screens/routes from the blueprint, Playwright + app-shell smoke spec), and its Definition of Done additionally requires that every blueprint screen is reachable and no feature logic was implemented.
+
+```markdown
+# Phase [N]: [Name]
+
+**Status**: Not started | In progress | Completed
+**Goal**: [One sentence: what this phase delivers as a release]
+**Execute**: `/execute-milestones phase[N]-milestones.md`
+**Milestones**: [NN]–[NN]
+
+---
+
+## Milestone [NN]: [Name]
+
+**Status**: Not started | In progress | Completed
+**Goal**: [One sentence: what the user can do after this milestone that they could not before]
+
+### Scope
+
+#### In Scope
+- [Theme or capability included in this milestone]
+
+#### Out of Scope
+- [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
+
+### Dependencies
+
+- [What must exist before this milestone can start: previous milestone, external system, decision]
+
+### Features
+
+> One `/add-feature` run per feature. Check off each feature when its run completes.
+
+- [ ] [Feature 1 name]
+- [ ] [Feature 2 name]
+
+#### Feature: [Feature 1 name]
+
+- **Description**: [What it does and the user value, 1–3 sentences]
+- **Related requirements**: [PRD user story / requirement IDs or headings]
+- **Affected screens**: [screen ids from ui-blueprint.json, or "n/a"]
+- **Acceptance criteria**:
+  - [Criterion 1]
+  - [Criterion 2]
+  - [Criterion 3]
+- **Command**: `/add-feature [Feature 1 name]`
+
+#### Feature: [Feature 2 name]
+
+- **Description**: ...
+- **Related requirements**: ...
+- **Affected screens**: ...
+- **Acceptance criteria**:
+  - ...
+- **Command**: `/add-feature [Feature 2 name]`
+
+### Definition of Done
+
+- [ ] All features above are checked off
+- [ ] Every feature has a Playwright E2E spec covering its acceptance criteria
+- [ ] `npm test`, `npm run lint`, `npm run typecheck`, `npm run test:e2e` pass
+- [ ] Persistent documents in `docs/` are reconciled with all features
+- [ ] [Milestone-specific criterion, e.g. "demo flow X→Y→Z works end-to-end"]
+
+### Completion Notes
+
+_Filled in when the milestone completes: completion date, deviations from plan, lessons learned._
+
+---
+
+## Milestone [NN+1]: [Name]
+
+[Same structure as above]
+```
+
+# Roadmap Template
+
+Use this structure for `docs/milestones/roadmap.md`.
+
+```markdown
+# Development Roadmap
+
+**Current phase**: [N — name] (`phase[N]-milestones.md`)
+**Current milestone**: [NN — name]
+
+## Phases and Milestones
+
+| Phase | File | Milestone | Name | Goal | Features | Status |
+|-------|------|-----------|------|------|----------|--------|
+| 1 | `phase1-milestones.md` | 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
+| 1 | `phase1-milestones.md` | 02 | [name] | [one-line goal] | [count] | Not started |
+| 2 | `phase2-milestones.md` | 03 | [name] | [one-line goal] | [count] | Not started |
+
+## Ordering Rationale
+
+[Why this sequence: MVP definition, dependency chains, priority decisions made with the user]
+
+## Later / Icebox
+
+Consciously deferred — revisit when re-planning:
+
+- [Deferred item] — [why deferred]
+```

.claude/skills/platform-ui-generation/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: platform-ui-generation
+description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when executing the App Shell milestone (milestone 01) or implementing UI against the design spec.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Platform UI Generation Skill
+
+This skill explains how to convert the design files under `docs/design/` into application code. It is used by the **App Shell milestone** (milestone 01 — planned by `/plan-milestones`, executed by `/execute-milestones` or `/add-feature`) and by `/add-feature` when implementing UI.
+
+## Core Principles
+
+1. **Source of truth**: `docs/design/ui-blueprint.json` defines structure; `docs/design/design-tokens.json` defines values.
+2. **No hard-coded values**: every color, size, spacing, radius, and duration in generated code must come from a token.
+3. **Reusable components first**: extract reusable components; do not inline the entire tree into screens.
+4. **No feature logic during scaffolding**: the App Shell milestone creates the shell, theme, routes, screens, and shared components only. Features come from the later milestones.
+5. **Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform.
+
+## Inputs
+
+- `docs/design/design-brief.md` — direction
+- `docs/design/design-tokens.json` — values
+- `docs/design/ui-blueprint.json` — structure (source of truth)
+- `docs/design/platform-mapping.md` — per-platform conversion rules
+- `docs/architecture.md` — technology choices (framework, language)
+
+## General Conversion Rules
+
+- One screen in the blueprint → one screen/page in the target platform.
+- One route in the blueprint → one route entry in the navigation config.
+- A reusable component referenced in multiple screens → a shared component file/widget/control.
+- Component `variant` → a variant/style modifier on the shared component.
+- Component `state` → visual states the component must support (default, hover, pressed, disabled, etc.).
+- `action: navigate:<screen-id>` → navigation to the corresponding route.
+- Other `action:` values → wire to a handler/placeholder; do not implement feature logic.
+
+## Web Mapping
+
+- **design tokens →** CSS variables, a Tailwind config, or a theme object.
+  - `color.*` → CSS custom properties (`--color-background-primary`) or Tailwind theme colors.
+  - `spacing.*`, `radius.*`, `typography.*` → CSS variables / Tailwind theme keys.
+  - `breakpoint.*` → responsive breakpoints.
+- **ui-blueprint →**
+  - `screens` → pages/routes.
+  - `layout` → layout components (vertical/horizontal stack, grid).
+  - `components` → React (or framework) components, one file per reusable component.
+- Use **semantic HTML** (`<header>`, `<main>`, `<nav>`, `<button>`, `<label>`) where possible.
+- Respect responsive layout requirements using the breakpoint tokens.
+- If no framework is specified in `architecture.md`, choose a simple default suitable for the repository and note the choice.
+
+## Flutter Mapping
+
+- **design tokens →**
+  - `color.*` → `ColorScheme` + a color constants file.
+  - `typography.*` → `TextTheme` / text styles.
+  - `spacing.*`, `radius.*` → constants (`spacing_md`, `radiusCard`).
+  - `shadow.*` → `BoxShadow` / elevation.
+  - `motion.duration.*` → `Duration` constants.
+  - Assemble into a `ThemeData`.
+- **ui-blueprint →**
+  - `screens` → `Screen` widgets + routes (named routes or a router).
+  - `layout.type` → `Column` / `Row` / `Wrap` / `ListView` with `padding` and `SizedBox` gaps from spacing tokens.
+  - `components` → reusable widgets, one file per widget.
+- Keep clean separation between: `screens/`, `widgets/`, `theme/`, `models/`, `services/`.
+
+## WinUI 3 Mapping
+
+- **design tokens →**
+  - `color.*`, `spacing.*`, `radius.*`, `typography.*` → a `ResourceDictionary` (`.xaml`) with `Color`, `Thickness`, `CornerRadius`, `FontFamily`, `Style` resources.
+  - Assemble theme resources and styles keyed by the token names.
+- **ui-blueprint →**
+  - `screens` → XAML pages (`Page`).
+  - `layout.type` → `StackPanel` / `Grid` with `Padding`/`Margin` from token resources.
+  - `components` → `UserControl`s, one file per reusable component.
+  - Navigation → `Frame` + navigation entries per route.
+- Use **C# and XAML**.
+- Keep UI logic separated from business logic (code-behind stays thin; logic goes to services/viewmodels).
+
+## Shared Component Contract
+
+Each generated reusable component must:
+
+- Accept the `variant` as a parameter/prop/style modifier.
+- Support the `states` declared in the blueprint (default, hover, pressed, disabled).
+- Reference tokens for all visual values — no hard-coded literals.
+- Stay presentational: no feature/business logic.
+
+## Scaffolding Scope (what the App Shell milestone creates)
+
+- App entry point and shell
+- Theme/styling system from tokens
+- Router/navigation config from routes
+- One screen per blueprint screen (layout + components wired, but no feature logic)
+- One shared component file per reusable component in `components`
+
+## Out of Scope (handled by `/add-feature`)
+
+- Feature/business logic
+- Data fetching and state management for features
+- Form validation and submission behavior
+- Anything not described in the current project documents
+
+## Generation Checklist
+
+Before finishing a generation:
+
+- [ ] Every screen in the blueprint has a corresponding generated screen.
+- [ ] Every route is wired in the navigation config.
+- [ ] Every reusable component in `components` has a generated file.
+- [ ] No hard-coded color/size/spacing in generated code — all from tokens.
+- [ ] Components accept `variant` and support declared `states`.
+- [ ] No feature logic was implemented beyond the project documents.
+- [ ] `docs/repository-structure.md` updated if the layout changed.

.claude/skills/steering/templates/tasklist.md

@@ -59,6 +59,9 @@ When skipping, always state the reason clearly:
   - [ ] `npm run lint`
 - [ ] Confirm that there are no type errors
   - [ ] `npm run typecheck`
+- [ ] Confirm that the E2E tests pass (Playwright — see the e2e-testing skill)
+  - [ ] E2E specs exist for this work's acceptance criteria
+  - [ ] `npm run test:e2e`
 - [ ] Confirm that the build succeeds
   - [ ] `npm run build`
 

.claude/skills/ui-design/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: ui-design
+description: Guide for creating the UI/UX design specification (design brief, UI blueprint JSON, and SVG wireframes). Use when defining or updating the design under docs/design/.
+allowed-tools: Read, Write, Edit
+---
+
+# UI Design Skill
+
+This skill explains how to create an **AI-readable, implementation-ready** UI/UX design specification. It prefers structured, machine-consumable descriptions over vague visual descriptions.
+
+## Core Principle
+
+> The source of truth is structured text/JSON. Visual images (SVG) are references for humans, not inputs for code generation.
+
+Prefer describing **what a component is and how it behaves** over describing **what it looks like**. "A primary button with label 'Save' that triggers `action:save`" is better than "a nice blue button in the corner".
+
+## Outputs
+
+This skill produces four kinds of artifacts under `docs/design/`:
+
+1. `screen-inventory.md` — an exhaustive checklist of every screen the requirements imply (always created first)
+2. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
+3. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
+4. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)
+
+## Prerequisites
+
+Before creating the design, read:
+
+- `docs/product-requirements.md`
+- `docs/functional-design.md`
+- `docs/architecture.md`
+
+The design must serve the product requirements and stay consistent with the functional design.
+
+## Creating `screen-inventory.md` (always first)
+
+Never design screens from memory of the requirements — a screen that is not on a written list will be forgotten (the classic miss: a list screen exists but the create/add screen does not). Build the inventory before the brief or the blueprint:
+
+1. **Walk every user story** in the PRD and every flow in the functional design; list every screen the user needs to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
+2. **Apply CRUD coverage per entity**: for each domain object the user manages, explicitly decide list/overview, detail, **create/add**, edit, and delete confirmation — include each unless the requirements clearly exclude it. Modal/dialog/inline forms count as inventory entries too (record the presentation); they still need blueprint entries and wireframes.
+3. **Add supporting screens**: authentication, settings, onboarding, search results, empty states, error / not-found — wherever the requirements imply them.
+
+Each entry is a checkbox item with `screen-id`, title, purpose, source requirement, how it is reached, presentation (page / modal / drawer), and key elements. End the file with a traceability table mapping every user story to the screen ids that fulfill it — both directions must be covered (no story without screens, no screen without a source).
+
+Check entries off (`[x]`) as their screens are added to `ui-blueprint.json`. The blueprint is not complete while any entry is unchecked.
+
+## Creating `design-brief.md`
+
+A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:
+
+- **Target users** — who the UI is for, and their key contexts/constraints
+- **Design concept** — the one-paragraph idea the UI embodies
+- **Visual mood** — concrete descriptors (density, light/dark, rounding, motion amount)
+- **Layout principles** — grid, alignment, content width, spacing rhythm
+- **Navigation principles** — primary navigation pattern, depth, back behavior
+- **Accessibility considerations** — target contrast, touch-target sizes, focus visibility, font scaling
+- **Platform-specific notes** — how the design adapts to web / Flutter / WinUI 3
+- **Examples of preferred UI style** — concrete references and why they fit
+- **Examples of UI style to avoid** — anti-patterns to stay away from
+
+## Creating `ui-blueprint.json` (source of truth)
+
+This is the most important file. It must be valid JSON and fully describe the app's UI structure so that a generator can produce Web, Flutter, or WinUI 3 code without guessing.
+
+### Required top-level fields
+
+- `app.name`
+- `app.platformTargets` — e.g. `["web", "flutter", "winui3"]`
+- `app.style` — short style summary string
+- `screens` — array of screen objects
+- `components` — map of reusable component definitions
+
+### Screen object shape
+
+Each screen has:
+
+- `id` — stable identifier (used as the SVG filename)
+- `title`
+- `route`
+- `layout` — type + spacing tokens (e.g. `{ "type": "vertical", "padding": "lg", "gap": "md" }`)
+- `components` — a tree of component nodes
+
+### Component node shape
+
+Each node has:
+
+- `type` — e.g. `header`, `card`, `text`, `button`, `list`, `input`, `image`, `nav`
+- `variant` — optional, must exist in the component's `variants`
+- `role` — optional semantic role (e.g. `title`, `subtitle`, `body`)
+- `content` / `label` — text content where applicable
+- `action` — user action, e.g. `navigate:details`, `submit`, `toggle:filters`
+- `children` — nested component nodes
+
+### Reusable component definition
+
+```json
+"components": {
+  "button": {
+    "variants": ["primary", "secondary", "ghost"],
+    "states": ["default", "hover", "pressed", "disabled"]
+  }
+}
+```
+
+### Example (excerpt)
+
+```json
+{
+  "app": {
+    "name": "Example App",
+    "platformTargets": ["web", "flutter", "winui3"],
+    "style": "friendly, modern, rounded, calm"
+  },
+  "screens": [
+    {
+      "id": "home",
+      "title": "Home",
+      "route": "/",
+      "layout": { "type": "vertical", "padding": "lg", "gap": "md" },
+      "components": [
+        { "type": "header", "title": "Dashboard", "subtitle": "Welcome back" },
+        {
+          "type": "card",
+          "variant": "primary",
+          "children": [
+            { "type": "text", "role": "title", "content": "Start here" },
+            { "type": "button", "label": "Open", "action": "navigate:details" }
+          ]
+        }
+      ]
+    }
+  ],
+  "components": {
+    "button": {
+      "variants": ["primary", "secondary", "ghost"],
+      "states": ["default", "hover", "pressed", "disabled"]
+    },
+    "card": {
+      "variants": ["primary", "secondary", "danger"]
+    }
+  }
+}
+```
+
+### Rules
+
+- Every `variant` referenced in a screen must exist in `components[type].variants`.
+- Every spacing/radius/color name referenced in layout/components must exist in `design-tokens.json`.
+- Use `action:` prefixes consistently: `navigate:<screen-id>`, `submit`, `toggle:<id>`, `open:<id>`, etc.
+- One screen = one route. Do not overload a screen with multiple routes.
+- Keep the blueprint free of hard-coded pixel values; reference token names instead.
+
+## Creating SVG wireframes (`screens/*.svg`)
+
+- Generate **one SVG per screen**, named `<screen-id>.svg`.
+- The SVG is a **low-fidelity wireframe**, not a pixel-perfect mock. Use boxes, labels, and placeholders.
+- It must reflect the component tree of its screen in `ui-blueprint.json`.
+- **If the blueprint and an SVG disagree, the blueprint wins.** Regenerate the SVG.
+- SVGs exist only so humans can review the design at a glance.
+
+## Consistency Checklist
+
+Before finishing:
+
+- [ ] Every entry in `screen-inventory.md` is checked off and exists in the blueprint (same id).
+- [ ] Every user story can be completed end-to-end using only blueprint screens and actions — every entity that can be created, edited, or deleted has a screen or modal for each operation.
+- [ ] Every screen in the blueprint has a matching SVG.
+- [ ] Every `variant` used in a screen is declared in `components`.
+- [ ] Every token name used in the blueprint exists in `design-tokens.json`.
+- [ ] The brief and the blueprint describe the same app (same screens, same navigation).
+- [ ] No hard-coded values in the blueprint.

CLAUDE.md

@@ -14,8 +14,8 @@
 1. **Document creation**: Define "what to build" in persistent documents (`docs/`)
 2. **Work planning**: Plan "what to do this time" in steering files (`.steering/`)
 3. **Implementation**: Implement according to tasklist.md and update progress as you go
-4. **Verification**: Testing and operation checks
-5. **Update**: Update documents as needed
+4. **Verification**: Testing and operation checks — unit tests, lint, typecheck, and Playwright E2E tests (see the e2e-testing skill)
+5. **Update**: Reconcile all `docs/` documents with the implemented feature (see `/add-feature` Step 8)
 
 ### Important Rules
 
@@ -78,6 +78,20 @@ Define "what to build" and "how to build it" for the entire application:
 - **development-guidelines.md** - Development guidelines
 - **glossary.md** - Ubiquitous language definitions
 
+#### Design Documents (`docs/design/`)
+- **screen-inventory.md** - Exhaustive screen checklist derived from the PRD (coverage guarantee for the blueprint)
+- **design-brief.md** - UI/UX direction
+- **design-tokens.json** - Styling tokens (source of values)
+- **ui-blueprint.json** - UI structure (source of truth for UI generation)
+- **platform-mapping.md** - How the design maps to Web / Flutter / WinUI 3
+- **screens/\*.svg** - Visual wireframes (references only)
+- Created by `/define-design`, updated by `/update-design`, consumed by the App Shell milestone (milestone 01) and `/add-feature`
+
+#### Milestone Documents (`docs/milestones/`)
+- **roadmap.md** - Overview: phase/milestone table, ordering rationale, current phase and milestone, icebox
+- **phase[N]-milestones.md** - One per phase (the `/execute-milestones` unit): its milestones and their features (each feature sized for one `/add-feature` run)
+- Created by `/plan-milestones`; `/execute-milestones` and `/add-feature` check features off as they complete them
+
 ### Work-Unit Documents (`.steering/`)
 
 Define "what to do this time" for a specific development task:
@@ -86,13 +100,24 @@ Define "what to do this time" for a specific development task:
 - `design.md`: The design of the changes
 - `tasklist.md`: The task list
 
+### Claude Code Configuration (`.claude/`)
+
+- `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator)
+- `.claude/commands/` - Slash commands (setup-project, define-design, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
+- `.claude/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, milestone-planning, milestone-execution, e2e-testing, steering)
+
 ## Development Process
 
 ### Initial Setup
 
 1. Use this template
-2. Create persistent documents with `/setup-project` (interactively creating six)
-3. Implement features with `/add-feature [feature]`
+2. Create persistent documents with `/setup-project` (automatically creating six)
+3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
+4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
+5. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with one `phase[N]-milestones.md` per phase; milestone 01 is always App Shell Generation from the design spec)
+6. Implement, either way:
+   - `/execute-milestones phase1-milestones.md` — execute one phase file: its milestones one by one autonomously (one steering directory per milestone; milestone 01 generates the initial app); repeat with the next phase file, or
+   - `/add-feature [feature]` — one feature at a time, milestone by milestone
 
 ### Day-to-Day Usage
 
@@ -107,6 +132,16 @@ Define "what to do this time" for a specific development task:
 # Adding features (use commands for the standard flow)
 > /add-feature edit user profile
 
+# Design phase
+> /define-design
+> /update-design add a profile screen
+
+# Milestone planning and execution
+> /plan-milestones
+> /plan-milestones 2 phases, MVP first
+> /execute-milestones phase1-milestones.md
+> /execute-milestones phase2-milestones.md
+
 # Detailed review (when a detailed report is needed)
 > /review-docs docs/product-requirements.md
 ```
@@ -118,8 +153,8 @@ Define "what to do this time" for a specific development task:
 ### Persistent Documents (`docs/`)
 
 - Describe the fundamental design
-- Not updated frequently
 - The "north star" for the entire project
+- **Kept in sync with every feature**: at the end of `/add-feature` (Step 8), all six documents are reconciled with the implemented feature (product-requirements, functional-design, architecture, repository-structure, development-guidelines, glossary)
 
 ### Work-Unit Documents (`.steering/`)
 

README.md

@@ -8,6 +8,117 @@ For questions about the book's content or to report errata, please use the issue
 
 https://github.com/GenerativeAgents/claude-code-book
 
+## Development Workflow (Step by Step)
+
+How a project goes from idea to working code with this boilerplate:
+
+```
+Idea → /setup-project → /define-design → refine design → /plan-milestones → /execute-milestones (phase by phase; milestone 01 generates the app)
+```
+
+### Step 1 — Write down your idea
+Put your brainstorming notes, requirements, and constraints into
+`docs/ideas/initial-requirements.md` (free-form; replace the sample content with your own).
+
+### Step 2 — Create the specification: `/setup-project`
+Automatically creates the six persistent documents that define **what to build**:
+PRD, functional design, architecture, repository structure, development guidelines, and glossary
+(all under `docs/`). Review them and request edits in normal conversation if needed.
+
+### Step 3 — Define the UI/UX design: `/define-design`
+First builds an **exhaustive screen inventory** (`screen-inventory.md`) from the PRD and
+functional design — every user story walked end-to-end, plus list/detail/create/edit/delete
+coverage for every entity — so no screen gets skipped. Then creates the design specification
+under `docs/design/`: design brief, design tokens, **`ui-blueprint.json` (the source of truth
+for UI generation, one entry per inventory screen)**, platform mapping, and SVG wireframes
+(visual references only). You'll be asked once about platform, style, screens, navigation,
+branding, and accessibility.
+
+### Step 4 — Review and refine the design **before writing any code**
+This is the key design-decision gate: iterate on the design while it is still cheap to change.
+
+- `/update-design <change>` — targeted refinements (e.g. `add a profile screen`)
+- Re-run `/define-design` — change the overall direction
+- Repeat until you approve the design (especially `ui-blueprint.json`)
+
+### Step 5 — Plan milestones: `/plan-milestones`
+Breaks the product into **phases** and milestones, and generates `docs/milestones/`:
+a `roadmap.md` overview plus **one file per phase** (`phase1-milestones.md`,
+`phase2-milestones.md`, …). Each phase file lists its milestones and **the features they
+contain** — each feature sized for exactly one `/add-feature` run, with acceptance criteria and a
+ready-to-run command. **Milestone 01 is always "App Shell Generation"**: it scaffolds the initial
+app from the approved design (theme from tokens, one screen per blueprint entry, routes, reusable
+components — no feature logic) plus the Playwright smoke spec; there is no separate generate-app
+step. Phase 1 delivers the MVP; later phases build on it by priority and dependency.
+
+### Step 6 — Implement the milestones
+
+Two ways to work through the plan:
+
+**Option A — execute a phase file: `/execute-milestones <phase-file>`**
+Requires the phase file to execute, e.g. `/execute-milestones phase1-milestones.md`. Runs that
+phase's milestones **one by one, autonomously**. For each milestone it creates a **separate
+steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the milestone's
+features into concrete tasks grouped by feature, implements them all, validates, tests,
+reconciles the docs, and marks the milestone completed — then immediately starts the next
+milestone in the file. When the phase completes, run it again with the next phase file.
+
+**Option B — one feature at a time: `/add-feature <feature>`**
+A fully autonomous loop, one feature per run. Each run:
+
+1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
+2. Reads the feature's entry in its phase file and the design spec first — and updates the design first if the feature changes the UI
+3. Implements every task in `tasklist.md`, checking items off as it goes
+4. Validates quality with the `implementation-validator` subagent
+5. Writes Playwright E2E tests for the feature's acceptance criteria, then runs `npm test`, `npm run lint`, `npm run typecheck`, and `npm run test:e2e` until green
+6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its phase file
+
+### Step 7 — Repeat and maintain
+- Remaining phases → `/execute-milestones <next phase file>`, or feature by feature with `/add-feature <feature>`
+- UI changes → `/update-design <change>` first, then `/add-feature`
+- Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation
+- Document quality checks → `/review-docs <path>`
+
+**A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
+test/lint/typecheck and the Playwright E2E suite succeed, and the persistent documents are back
+in sync with the code.
+
+## E2E Testing (Playwright)
+
+Every verification step in this boilerplate includes end-to-end tests. The standard verification
+sequence — used by `/add-feature` and `/execute-milestones` — is:
+
+```bash
+npm test           # unit tests
+npm run lint
+npm run typecheck
+npm run test:e2e   # Playwright E2E
+```
+
+How it works (defined in the `e2e-testing` skill):
+
+- **Setup is automatic**: on the first verification, if Playwright is missing, the agent installs
+  `@playwright/test`, creates `playwright.config.ts` (dev-server integration, trace/screenshot on
+  failure), and adds the `test:e2e` script.
+- **Tests are derived from acceptance criteria**: each feature gets `e2e/[feature].spec.ts` with
+  one test per acceptance criterion, written before verification runs.
+- **The app shell has a smoke spec**: the App Shell milestone (milestone 01) creates `e2e/app-shell.spec.ts`, which
+  checks that the shell renders and every route in `ui-blueprint.json` navigates.
+- **Blueprint-driven locators**: tests navigate by the blueprint's routes and use semantic
+  locators (`getByRole`, `getByLabel`) — no CSS/XPath tied to implementation details, no fixed waits.
+- **No green-washing**: a failing E2E test is fixed, never skipped or deleted; milestone gates in
+  `/execute-milestones` do not pass without a green E2E suite.
+
+```
+e2e/
+├── app-shell.spec.ts        # smoke: shell renders, all blueprint routes navigate
+├── [feature-name].spec.ts   # one spec per feature (acceptance criteria)
+└── helpers/                 # shared fixtures (only when duplicated 3+ times)
+```
+
+Playwright covers the `web` target; for `flutter` the equivalent is `integration_test`, and for
+`winui3` the platform's UI automation — with the same acceptance-criteria mapping.
+
 ## Notes
 
 The content of this repository may be changed to improve prompt performance based on feedback from readers. Differences will be reflected in the book as needed, but please be aware that there may be discrepancies with the edition you have on hand.
@@ -30,3 +141,29 @@ When you select "Reopen in Container" in Visual Studio Code, the environment is
 - Installing the latest version of Claude Code
 
 * When using Dev Container, you need to install Docker in advance.
+
+### 3. Start Claude Code and follow the workflow
+
+```bash
+claude
+> /setup-project
+> /define-design
+> /update-design [refinement]      # repeat until the design is approved
+> /plan-milestones                  # milestone 01 = app shell generation
+> /execute-milestones phase1-milestones.md   # one phase at a time, or:
+> /add-feature [feature name]                # one feature at a time
+```
+
+See [Development Workflow (Step by Step)](#development-workflow-step-by-step) above for what each step does.
+
+## Commands Reference
+
+| Command | Description | Example |
+|---|---|---|
+| `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
+| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
+| `/update-design` | Refine the design before generation, or update it when a feature changes the UI | `/update-design add a profile screen` |
+| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase (milestone 01 = App Shell Generation) | `/plan-milestones 2 phases, MVP first` |
+| `/execute-milestones` | Execute one phase file: its milestones one by one, with separate steering documents per milestone (file argument required) | `/execute-milestones phase1-milestones.md` |
+| `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
+| `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |

docs/design/README.md

@@ -0,0 +1,66 @@
+# Design Specification (`docs/design/`)
+
+This directory holds the project's **UI/UX design specification**. It is created and maintained by the `/define-design` and `/update-design` commands and consumed by the App Shell milestone (milestone 01) and `/add-feature`.
+
+## Source of truth
+
+```
+docs/design/ui-blueprint.json   ← THE source of truth for UI generation
+```
+
+SVG files are **visual references only**. If an SVG and the blueprint disagree, the blueprint wins and the SVG must be regenerated.
+
+Generated UI must follow `design-tokens.json` — no hard-coded values.
+
+## Structure
+
+```
+docs/design/
+├── screen-inventory.md     # Exhaustive screen checklist derived from the PRD (built first)
+├── design-brief.md         # UI/UX direction (human-readable, concrete)
+├── design-tokens.json      # Styling values (color, type, spacing, radius, …)
+├── ui-blueprint.json        # Source of truth: screens, components, routes, actions
+├── platform-mapping.md      # How the design maps to Web / Flutter / WinUI 3
+└── screens/                 # SVG wireframes (one per blueprint screen)
+    ├── home.svg
+    ├── settings.svg
+    └── [screen-id].svg
+```
+
+## File purposes
+
+### `screen-inventory.md`
+The exhaustive checklist of every screen the requirements imply — built first, before any other design file. Derived from every PRD user story walked end-to-end, CRUD coverage per entity (list/detail/create/edit/delete, modals included), and supporting screens, ending with a story→screen traceability table. Every entry must exist in `ui-blueprint.json`.
+
+### `design-brief.md`
+Overall UI/UX direction: target users, design concept, visual mood, layout/navigation principles, accessibility, platform-specific notes, preferred styles, and styles to avoid.
+
+### `design-tokens.json`
+Design tokens in a Design Tokens Community Group–inspired JSON format (`$type` / `$value`). Covers color, typography, spacing, radius, shadow, motion, and breakpoints. Platform code reads from these tokens and never hard-codes values.
+
+### `ui-blueprint.json`
+The source of truth for UI generation. Describes the app name, target platforms, routes, screens (each with a layout and component tree), reusable components (variants and states), and user actions/navigation.
+
+### `platform-mapping.md`
+Documents how `design-tokens.json` and `ui-blueprint.json` are converted to each target platform:
+
+- **Web**: tokens → CSS variables / Tailwind theme; blueprint → pages, routes, components.
+- **Flutter**: tokens → `ThemeData` / `ColorScheme` / constants; blueprint → widgets, routes.
+- **WinUI 3**: tokens → `ResourceDictionary`; blueprint → XAML pages, `UserControl`s, navigation.
+
+### `screens/*.svg`
+Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `<screen-id>.svg`. Generated for human review only — never the source of truth.
+
+## Workflow
+
+```
+/setup-project   → product/architecture docs
+/define-design   → creates the files above
+/plan-milestones → milestone 01 (App Shell) scaffolds the app from these files
+/update-design   → updates these files when a feature changes the UI
+/add-feature     → reads these files before implementing; updates them first if the UI changes
+```
+
+## Status
+
+This directory is populated by running `/define-design`. Until then, the files above do not exist and milestone planning/execution will warn you to run `/define-design` first.

docs/milestones/README.md

@@ -0,0 +1,49 @@
+# Milestone Documents (`docs/milestones/`)
+
+This directory holds the project's **milestone plan**: an ordered breakdown of the product into phases and milestones, with the features for each milestone. It is created by `/plan-milestones` and kept up to date by `/execute-milestones` and `/add-feature`.
+
+## Hierarchy
+
+```
+Roadmap (roadmap.md)
+└── Phase (phase[N]-milestones.md — the /execute-milestones unit)
+    └── Milestone (numbered globally: 01, 02, …)
+        └── Feature (the /add-feature unit)
+```
+
+## Structure
+
+```
+docs/milestones/
+├── roadmap.md               # Overview: phase/milestone table, ordering rationale, icebox
+├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
+├── phase2-milestones.md
+└── phaseN-milestones.md
+```
+
+## File purposes
+
+### `roadmap.md`
+The overview: a table of all phases and their milestones (goal, feature count, status), the ordering rationale, pointers to the current phase file and current milestone, and a "Later / Icebox" list of consciously deferred items.
+
+### `phase[N]-milestones.md`
+One file per phase — the execution unit for `/execute-milestones`. Contains the phase's goal and status, and one section per milestone: goal, scope, dependencies, definition of done, and its **feature list** — each feature sized for exactly one `/add-feature` run, with description, related PRD requirements, affected screens, acceptance criteria, and the ready-to-run command.
+
+## Status tracking
+
+- Each feature has a checkbox in its phase file; `/execute-milestones` and `/add-feature` check it off (`[ ]` → `[x]`) when the feature completes.
+- Milestone and phase statuses (`Not started` / `In progress` / `Completed`) are kept in sync between the phase file and the roadmap table.
+
+## Workflow
+
+```
+/setup-project     → product/architecture docs
+/define-design     → UI/UX design spec
+/plan-milestones   → creates the files above (milestone 01 = App Shell Generation)
+/execute-milestones phase1-milestones.md → implements that phase's milestones one by one (one steering directory per milestone), updating statuses here
+/add-feature       → implements one feature, then checks it off here
+```
+
+## Status
+
+This directory is populated by running `/plan-milestones`. Until then, the files above do not exist and `/execute-milestones` will ask you to run `/plan-milestones` first.