Require Playwright E2E tests in every verification step

- New skill e2e-testing: on-demand Playwright setup (config, test:e2e script), acceptance-criteria-driven specs (one per feature + app-shell smoke), blueprint-driven semantic locators, and the shared verification checklist
- /add-feature Step 7 and /execute-milestones Step 2.6 now write/update E2E specs and run npm run test:e2e alongside test/lint/typecheck; milestone gates and completion criteria include E2E
- /generate-app Step 5 sets up Playwright and creates the app-shell smoke spec for the web target (integration_test / UI automation noted for flutter/winui3)
- steering tasklist template, milestone-planning Definition of Done, milestone-execution task slicing/gates, development-guidelines pointers, and implementation-validator checks updated
- CLAUDE.md, README, and settings.json updated

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

.claude/agents/implementation-validator.md

@@ -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

@@ -26,7 +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 milestone document that contains this feature. Use its description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any milestone, note that it is unplanned work and proceed.
+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
 
@@ -121,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.**
 
@@ -151,9 +155,9 @@ If any of the following situations occur while the implementation loop is runnin
    - ✅ `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 milestone document, use the `Edit` tool to check the feature off (`[ ]` → `[x]`).
+   - 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 milestone document and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone.
+   - 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 document as a completed (`[x]`) feature so the plan reflects reality.
+   - 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.
 
@@ -164,7 +168,7 @@ If any of the following situations occur while the implementation loop is runnin
 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 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 milestone document (if `docs/milestones/` exists).
+- 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/execute-milestones.md

@@ -1,22 +1,25 @@
 ---
-description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
+description: Execute one phase file (phaseN-milestones.md) - implement its milestones one by one with separate steering documents per milestone
 ---
 
-# Execute Milestones (Fully Autonomous Milestone Execution Mode)
+# Execute Milestones (Fully Autonomous Phase Execution Mode)
 
-This command works through the milestone plan in `docs/milestones/` **one milestone at a time**. 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.
+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.
 
-**Target**: `$ARGUMENTS` — optional: a milestone number (e.g. `2`), a range (e.g. `1-3`), or empty to execute **all remaining milestones in order**.
+**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            # execute all remaining milestones one by one
+> /execute-milestones phase1-milestones.md
-> /execute-milestones 1          # execute only milestone 1
+> /execute-milestones docs/milestones/phase2-milestones.md
-> /execute-milestones 2-3       # execute milestones 2 through 3
+> /execute-milestones 1
 ```
 
 ## Position in the Workflow
@@ -30,21 +33,26 @@ claude
   ↓
 /plan-milestones
   ↓
-/execute-milestones      ← you are here (alternative: /add-feature per feature)
+/execute-milestones phase1-milestones.md   ← you are here (one phase file per run)
+  ↓
+/execute-milestones phase2-milestones.md   (next run)
 ```
 
 ## Pre-Run Check
 
-1. Confirm `docs/milestones/roadmap.md` and at least one `docs/milestones/milestone-*.md` exist. If not, stop and tell the user to run `/plan-milestones` first.
+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. 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.
+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 `docs/milestones/roadmap.md` and every milestone document.
+1. Read the specified phase file and `docs/milestones/roadmap.md`.
-2. The execution queue is the milestones selected by `$ARGUMENTS` (all of them when empty), **excluding** milestones whose status is already `Completed`, in ascending milestone number.
+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 all selected milestones are already completed and finish.
+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
 
@@ -71,7 +79,7 @@ Each milestone gets its **own** directory — never reuse or append to another m
 
 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 milestone document).
+- `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.
 
@@ -95,15 +103,19 @@ Use the `Task` tool to launch the `implementation-validator` subagent:
 - `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
+#### 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.
+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
 
@@ -111,39 +123,42 @@ 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 milestone document: check off every feature (`[ ]` → `[x]`), set the status to `Completed`, and fill in the "Completion Notes".
+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 (or mark the roadmap complete).
+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 are green, the six documents are reconciled, and the milestone + roadmap statuses are updated.
+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` and in `roadmap.md`, then stop and report — this is the only permitted early stop.
+**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: Final Report
+### Step 3: Close the Phase and Report
 
-When the queue is empty, report per milestone: steering directory created, features implemented, test results, and document updates.
+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 execution queue has status `Completed` in `docs/milestones/roadmap.md`.
+- 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, and typecheck pass on the final state.
+- 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:
 ```
-"Milestone execution is complete!
+"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 docs/milestones/roadmap.md.
+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 milestones end-to-end
+- 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/generate-app.md

@@ -117,10 +117,13 @@ Apply the requirements for the selected target:
 
 If new directories/files were created, update `docs/repository-structure.md` so it reflects the generated layout.
 
-### Step 5: Verify
+### Step 5: Verify (including Playwright E2E)
 
-- If the target is `web` and the repo has `npm test`, `npm run lint`, `npm run typecheck`, run them and fix any errors caused by the generated code.
+- If the target is `web`:
-- For `flutter` / `winui3`, run the platform's available static checks if the toolchain is present; otherwise note what should be checked manually.
+  - Run `npm test`, `npm run lint`, `npm run typecheck` (where present) and fix any errors caused by the generated code.
+  - Set up Playwright following the **e2e-testing skill** (`Skill('e2e-testing')`) if it is not set up yet, and create the app-shell smoke spec `e2e/app-shell.spec.ts` (shell renders, every blueprint route navigates, primary navigation works).
+  - Run `npm run test:e2e` and fix any failures caused by the generated code.
+- For `flutter` / `winui3`, run the platform's available static checks and UI/integration tests if the toolchain is present (`integration_test` for Flutter, the platform's UI automation for WinUI 3); otherwise note what should be checked manually.
 
 ## Completion Criteria
 
@@ -140,6 +143,7 @@ Generated:
 ✅ Routes / navigation (from ui-blueprint.json)
 ✅ Screens (one per blueprint screen)
 ✅ Reusable components
+✅ Playwright E2E smoke spec (e2e/app-shell.spec.ts, web target)
 
 Next steps:
 - Run the app and verify the shell renders

.claude/commands/plan-milestones.md

@@ -1,19 +1,19 @@
 ---
-description: Plan development milestones and generate milestone documents with the features for each milestone
+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 an ordered set of **milestones** and generates milestone documents under `docs/milestones/`. Each milestone document lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run.
+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 3 milestones, MVP in 2 weeks, auth first`)
+**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 3 milestones, MVP first, payments last
+> /plan-milestones 2 phases, MVP first, payments last
 ```
 
 ## Position in the Workflow
@@ -27,7 +27,7 @@ claude
   ↓
 /plan-milestones        ← you are here
   ↓
-/add-feature (once per feature, milestone by milestone)
+/execute-milestones phase1-milestones.md   (one phase file at a time)
 ```
 
 ## Pre-Run Check
@@ -59,8 +59,8 @@ Read all of the following:
 
 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.
 
-- **Number of milestones** (default: 2–4 depending on scope)
+- **Number of phases** (default: 2–3) and **milestones per phase** (default: 1–3)
-- **MVP definition** — what is the smallest product worth releasing?
+- **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
 
@@ -68,7 +68,7 @@ Collect the answers in a single round; do not pause again until generation is co
 
 ### Step 2: Load the Milestone Planning Skill
 
-Load the **milestone-planning skill** (`Skill('milestone-planning')`) for the planning rules and the milestone document template.
+Load the **milestone-planning skill** (`Skill('milestone-planning')`) for the planning rules and the phase file template.
 
 ### Step 3: Build the Feature Inventory
 
@@ -80,49 +80,55 @@ Derive the complete list of features from the documents:
 
 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
+### Step 4: Group Features into Milestones, and Milestones into Phases
 
-- **Milestone 1 is the MVP**: the smallest set of features that forms a coherent, end-to-end usable product.
+- Number milestones globally and consecutively across all phases (`01`, `02`, …).
+- **Milestone 1 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product.
 - Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
-- Every feature belongs to **exactly one** milestone. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
+- **Phase 1 delivers the MVP**: it contains milestone 1 (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 milestones: number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
+- 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 milestone
+- A pointer to the current phase file and current milestone
 - The "Later / Icebox" list of consciously deferred items
 
-### Step 6: Create One Document per Milestone
+### Step 6: Create One File per Phase
 
-For each milestone, create `docs/milestones/milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`) following the milestone-planning skill's template. Each document lists the milestone's features, and each feature includes:
+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:
 
-- A checkbox for status tracking (`- [ ]`)
+- The phase header: goal, status, and its ready-to-run command: `/execute-milestones phase[N]-milestones.md`
-- Description and user value
+- One section per milestone in the phase (goal, scope, dependencies, definition of done)
-- Related PRD requirements / user stories
+- Under each milestone, its features — and each feature includes:
-- Affected screens from `ui-blueprint.json` (if a design spec exists)
+  - A checkbox for status tracking (`- [ ]`)
-- Acceptance criteria
+  - Description and user value
-- The ready-to-run command: `/add-feature [feature name]`
+  - 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:
 
 - 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.
+- Every feature appears in exactly one milestone, and every milestone in exactly one phase file.
-- Dependencies are ordered correctly across milestones.
+- Milestone numbering is global and consecutive across the phase files.
-- Milestone 1 is a coherent, usable MVP on its own.
+- Dependencies are ordered correctly across milestones and phases.
-- Each feature name works as a `/add-feature` argument.
+- 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 `milestone-[NN]-[name].md` per milestone exists
+- One `phase[N]-milestones.md` per phase exists
-- Every feature is assigned to exactly one milestone with acceptance criteria
+- Every feature is assigned to exactly one milestone (in exactly one phase file) with acceptance criteria
 
 Completion message:
 ```
@@ -130,13 +136,13 @@ Completion message:
 
 Milestone documents created:
 ✅ docs/milestones/roadmap.md            (overview + status)
-✅ docs/milestones/milestone-01-....md   (MVP)
+✅ docs/milestones/phase1-milestones.md  (MVP phase: milestones 01–NN)
-✅ docs/milestones/milestone-NN-....md
+✅ docs/milestones/phase2-milestones.md  (milestones NN–NN)
 
 Next steps:
 - Review docs/milestones/ and adjust priorities if needed
-- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
+- 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 1]
-- Either way, each feature is marked complete in its milestone document as it finishes
+- Either way, each feature is marked complete in its phase file as it finishes
 "
 ```

.claude/settings.json

@@ -12,6 +12,7 @@
       "Skill(platform-ui-generation)",
       "Skill(milestone-planning)",
       "Skill(milestone-execution)",
+      "Skill(e2e-testing)",
       "Skill(steering)"
     ],
     "deny": [],

.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 `/generate-app` (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, `/execute-milestones` Step 2.6, and `/generate-app` Step 5:
+
+- [ ] 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

@@ -1,27 +1,28 @@
 ---
 name: milestone-execution
-description: Guide for executing milestones one by one - creating a separate steering directory per milestone, dividing the milestone's features into tasks, and enforcing gate criteria between milestones. Use when running /execute-milestones or implementing a whole milestone in one run.
+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 the milestone plan (`docs/milestones/`) one milestone at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory — and processes milestones strictly in roadmap order.
+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 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.
+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. **Strict order, one at a time**: milestones execute in ascending number. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
+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. **Features divided into tasks**: the milestone's features (from its milestone document) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The milestone document stays the "what"; the steering tasklist is the "how".
+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. **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.
+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. **Status flows upward**: task status lives in the steering `tasklist.md`; feature and milestone status live in `docs/milestones/`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer.
+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 document)
+- 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
@@ -45,14 +46,15 @@ Tasks are **grouped by feature**, in the implementation order chosen in `design.
 - [ ] [Task 1: data/model layer]
 - [ ] [Task 2: logic/service layer]
 - [ ] [Task 3: UI per affected screen]
-- [ ] [Task 4: tests for the acceptance criteria]
+- [ ] [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
-- [ ] npm test / lint / typecheck pass
+- [ ] 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._
@@ -61,8 +63,8 @@ _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.
+- 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.
+- 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
@@ -71,15 +73,17 @@ A milestone passes its gate only when **all** of the following hold. Only then m
 
 - [ ] Every task in the milestone's `tasklist.md` is `[x]` (or struck with a technical reason).
 - [ ] The `implementation-validator` subagent's validation passed.
-- [ ] `npm test`, `npm run lint`, `npm run typecheck` all succeed.
+- [ ] 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 `docs/milestones/`: every feature is checked off, the milestone status is `Completed` with Completion Notes, and `roadmap.md` points to the next milestone.
+- [ ] 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 milestone document and `requirements.md` with the revised scope and reason, then continue — the plan must reflect reality.
+- **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` 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.
+- **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
 
@@ -87,6 +91,6 @@ 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 milestone document match the completed work.
+- [ ] Feature checkboxes in the phase file match the completed work.
-- [ ] `roadmap.md` statuses and current-milestone pointer are correct.
+- [ ] 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 was implemented early.
+- [ ] No task or feature from a later milestone or a later phase file was implemented early.

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

@@ -1,21 +1,31 @@
 ---
 name: milestone-planning
-description: Guide for planning development milestones and generating milestone documents with a feature breakdown. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
+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 milestones and produce milestone documents under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation (`/add-feature`): every feature in every milestone is sized to be implemented with **one `/add-feature` run**.
+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. **MVP first**: Milestone 1 is the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
+1. **MVP first**: Phase 1 delivers the MVP; milestone 1 is its core — the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
 2. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
 3. **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.
-4. **Dependency order**: A feature never lands in an earlier milestone than something it depends on.
+4. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
-5. **Exactly-once assignment**: Every feature belongs to exactly one milestone. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
+5. **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.
-6. **Living documents**: Milestone documents track status. `/add-feature` checks off a feature (`[ ]` → `[x]`) when it completes, and the roadmap status is updated when a milestone finishes.
+6. **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.
+7. **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
 
@@ -31,15 +41,15 @@ Before planning, read:
 
 ```
 docs/milestones/
-├── roadmap.md                      # Overview: milestone table, ordering rationale, icebox
+├── roadmap.md               # Overview: phase/milestone table, ordering rationale, icebox
-├── milestone-01-[name].md          # MVP
+├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
-├── milestone-02-[name].md
+├── phase2-milestones.md
-└── milestone-NN-[name].md
+└── phaseN-milestones.md
 ```
 
-File naming: `milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`, `milestone-02-collaboration.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 milestone document.
+Use the structure in `template.md` for each phase file and for the roadmap.
 
 ## How to Slice Features
 
@@ -54,27 +64,31 @@ A well-sized feature:
 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
+## How to Group Milestones and Phases
 
 1. Tag every feature with its PRD priority and its dependencies.
-2. Milestone 1 (MVP): 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).
+2. Milestone 1 (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).
-3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful release on its own ("after milestone N ships, the user can additionally …").
+3. 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.
-4. Prefer 2–4 milestones with 3–8 features each. More than ~8 features in one milestone usually means it should be split.
+4. **Phase 1** contains milestone 1 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.
+5. 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 of its milestone document.
+- Feature status lives **only** in the feature checkbox inside its phase file.
-- Milestone status (`Not started` / `In progress` / `Completed`) lives in both the milestone document header and the roadmap table — keep them in sync.
+- 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.
-- `/add-feature` Step 8 updates the feature checkbox and, when the last feature of a milestone completes, the milestone and roadmap statuses.
+- Phase status lives in the phase file header **and** in the roadmap table.
-- Re-planning (adding/moving/removing features) must update both the milestone document(s) and `roadmap.md` in the same change.
+- `/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:
 
 - [ ] 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 feature appears in exactly one milestone; every milestone in exactly one phase file.
-- [ ] No feature precedes one of its dependencies.
+- [ ] Milestone numbering is global and consecutive across phase files.
-- [ ] Milestone 1 is a usable end-to-end product on its own.
+- [ ] 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.
-- [ ] `roadmap.md` table matches the milestone documents (names, counts, statuses).
+- [ ] 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

@@ -1,34 +1,42 @@
-# Milestone Document Template
+# Phase File Template
 
-Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
+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.
 
 ```markdown
-# Milestone [NN]: [Name]
+# 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
+### Scope
 
-### In Scope
+#### In Scope
 - [Theme or capability included in this milestone]
 
-### Out of Scope
+#### Out of Scope
 - [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
 
-## Dependencies
+### Dependencies
 
 - [What must exist before this milestone can start: previous milestone, external system, decision]
 
-## Features
+### Features
 
 > One `/add-feature` run per feature. Check off each feature when its run completes.
 
 - [ ] [Feature 1 name]
 - [ ] [Feature 2 name]
-- [ ] [Feature 3 name]
 
-### Feature: [Feature 1 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]
@@ -39,7 +47,7 @@ Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
   - [Criterion 3]
 - **Command**: `/add-feature [Feature 1 name]`
 
-### Feature: [Feature 2 name]
+#### Feature: [Feature 2 name]
 
 - **Description**: ...
 - **Related requirements**: ...
@@ -48,16 +56,23 @@ Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
   - ...
 - **Command**: `/add-feature [Feature 2 name]`
 
-## Definition of Done
+### Definition of Done
 
 - [ ] All features above are checked off
-- [ ] `npm test`, `npm run lint`, `npm run typecheck` pass
+- [ ] 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
+### 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
@@ -67,14 +82,16 @@ Use this structure for `docs/milestones/roadmap.md`.
 ```markdown
 # Development Roadmap
 
+**Current phase**: [N — name] (`phase[N]-milestones.md`)
 **Current milestone**: [NN — name]
 
-## Milestones
+## Phases and Milestones
 
-| # | Name | Goal | Features | Status |
+| Phase | File | Milestone | Name | Goal | Features | Status |
-|---|------|------|----------|--------|
+|-------|------|-----------|------|------|----------|--------|
-| 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
+| 1 | `phase1-milestones.md` | 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
-| 02 | [name] | [one-line goal] | [count] | Not started |
+| 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
 

.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.md

@@ -14,7 +14,7 @@
 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
+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
@@ -87,9 +87,9 @@ Define "what to build" and "how to build it" for the entire application:
 - Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature`
 
 #### Milestone Documents (`docs/milestones/`)
-- **roadmap.md** - Milestone overview: table, ordering rationale, current milestone, icebox
+- **roadmap.md** - Overview: phase/milestone table, ordering rationale, current phase and milestone, icebox
-- **milestone-[NN]-[name].md** - One per milestone: goal, scope, and the features it contains (each sized for one `/add-feature` run)
+- **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`; `/add-feature` checks features off as it completes them
+- Created by `/plan-milestones`; `/execute-milestones` and `/add-feature` check features off as they complete them
 
 ### Work-Unit Documents (`.steering/`)
 
@@ -103,7 +103,7 @@ Define "what to do this time" for a specific development task:
 
 - `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator)
 - `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, 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, steering)
+- `.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
 
@@ -114,9 +114,9 @@ Define "what to do this time" for a specific development task:
 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. Generate the initial app with `/generate-app web | flutter | winui3`
-6. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with the features for each milestone)
+6. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with one `phase[N]-milestones.md` per phase)
 7. Implement, either way:
-   - `/execute-milestones` — execute all milestones one by one autonomously (one steering directory per milestone), or
+   - `/execute-milestones phase1-milestones.md` — execute one phase file: its milestones one by one autonomously (one steering directory per milestone); repeat with the next phase file, or
    - `/add-feature [feature]` — one feature at a time, milestone by milestone
 
 ### Day-to-Day Usage
@@ -139,9 +139,9 @@ Define "what to do this time" for a specific development task:
 
 # Milestone planning and execution
 > /plan-milestones
-> /plan-milestones 3 milestones, MVP first
+> /plan-milestones 2 phases, MVP first
-> /execute-milestones
+> /execute-milestones phase1-milestones.md
-> /execute-milestones 1
+> /execute-milestones phase2-milestones.md
 
 # Detailed review (when a detailed report is needed)
 > /review-docs docs/product-requirements.md

README.md

@@ -13,7 +13,7 @@ https://github.com/GenerativeAgents/claude-code-book
 How a project goes from idea to working code with this boilerplate:
 
 ```
-Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /add-feature (repeat)
+Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /execute-milestones (phase by phase)
 ```
 
 ### Step 1 — Write down your idea
@@ -43,40 +43,43 @@ Scaffolds the app shell from the approved design: theme (from tokens), routes, s
 reusable components. No feature logic yet.
 
 ### Step 6 — Plan milestones: `/plan-milestones`
-Breaks the product into an ordered set of milestones and generates `docs/milestones/`:
+Breaks the product into **phases** and milestones, and generates `docs/milestones/`:
-a `roadmap.md` overview plus one document per milestone listing **the features it contains** —
+a `roadmap.md` overview plus **one file per phase** (`phase1-milestones.md`,
-each sized for exactly one `/add-feature` run, with acceptance criteria and a ready-to-run command.
+`phase2-milestones.md`, …). Each phase file lists its milestones and **the features they
-Milestone 1 is the MVP; later milestones build on it by priority and dependency.
+contain** — each feature sized for exactly one `/add-feature` run, with acceptance criteria and a
+ready-to-run command. Phase 1 delivers the MVP; later phases build on it by priority and dependency.
 
 ### Step 7 — Implement the milestones
 
 Two ways to work through the plan:
 
-**Option A — execute whole milestones: `/execute-milestones`**
+**Option A — execute a phase file: `/execute-milestones <phase-file>`**
-Runs all remaining milestones **one by one, autonomously**. For each milestone it creates a
+Requires the phase file to execute, e.g. `/execute-milestones phase1-milestones.md`. Runs that
-**separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
+phase's milestones **one by one, autonomously**. For each milestone it creates a **separate
-milestone's features into concrete tasks grouped by feature, implements them all, validates,
+steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the milestone's
-tests, reconciles the docs, and marks the milestone completed — then immediately starts the next
+features into concrete tasks grouped by feature, implements them all, validates, tests,
-milestone. Takes an optional target (`/execute-milestones 1` or `/execute-milestones 2-3`).
+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 milestone document and the design spec first — and updates the design first if the feature changes the UI
+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. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
+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 milestone document
+6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its phase file
 
 ### Step 8 — Repeat and maintain
-- Remaining milestones → `/execute-milestones`, or feature by feature with `/add-feature <feature>`
+- 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 succeed, and the persistent documents are back in sync with the code.
+test/lint/typecheck and the Playwright E2E suite succeed, and the persistent documents are back
+in sync with the code.
 
 ## Notes
 
@@ -110,7 +113,7 @@ claude
 > /update-design [refinement]      # repeat until the design is approved
 > /generate-app web                 # or flutter | winui3
 > /plan-milestones
-> /execute-milestones               # all milestones one by one, or:
+> /execute-milestones phase1-milestones.md   # one phase at a time, or:
 > /add-feature [feature name]                # one feature at a time
 ```
 
@@ -124,7 +127,7 @@ See [Development Workflow (Step by Step)](#development-workflow-step-by-step) ab
 | `/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` |
 | `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
-| `/plan-milestones` | Plan milestones and generate milestone documents with the features for each | `/plan-milestones 3 milestones, MVP first` |
+| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase | `/plan-milestones 2 phases, MVP first` |
-| `/execute-milestones` | Execute milestones one by one, with separate steering documents per milestone | `/execute-milestones` |
+| `/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/milestones/README.md

@@ -1,29 +1,38 @@
 # Milestone Documents (`docs/milestones/`)
 
-This directory holds the project's **milestone plan**: an ordered breakdown of the product into releases, with the features for each milestone. It is created by `/plan-milestones` and kept up to date by `/add-feature`.
+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: milestone table, ordering rationale, icebox
+├── roadmap.md               # Overview: phase/milestone table, ordering rationale, icebox
-├── milestone-01-[name].md          # Milestone 1 (the MVP)
+├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
-├── milestone-02-[name].md
+├── phase2-milestones.md
-└── milestone-NN-[name].md
+└── phaseN-milestones.md
 ```
 
 ## File purposes
 
 ### `roadmap.md`
-The overview: a table of all milestones (goal, feature count, status), the ordering rationale, a pointer to the current milestone, and a "Later / Icebox" list of consciously deferred items.
+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.
 
-### `milestone-[NN]-[name].md`
+### `phase[N]-milestones.md`
-One document per milestone. Contains the milestone's goal, scope, dependencies, 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.
+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 milestone document; `/add-feature` checks it off (`[ ]` → `[x]`) when the feature completes.
+- Each feature has a checkbox in its phase file; `/execute-milestones` and `/add-feature` check it off (`[ ]` → `[x]`) when the feature completes.
-- Milestone status (`Not started` / `In progress` / `Completed`) is kept in sync between the milestone document and the roadmap table.
+- Milestone and phase statuses (`Not started` / `In progress` / `Completed`) are kept in sync between the phase file and the roadmap table.
 
 ## Workflow
 
@@ -32,10 +41,10 @@ One document per milestone. Contains the milestone's goal, scope, dependencies,
 /define-design     → UI/UX design spec
 /generate-app      → initial app shell
 /plan-milestones   → creates the files above
-/execute-milestones → implements all milestones one by one (one steering directory per milestone), updating statuses here
+/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.
+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.