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 follows platform-ui-generation for it)
or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams,
skills, docs READMEs, AGENTS.md, and README updated; docs/design README also
gains the screen-inventory.md entry.

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

.opencode/command/define-design.md

@@ -24,11 +24,9 @@ opencode
   ↓
 /define-design        ← you are here
   ↓
-/generate-app web | flutter | winui3
+/plan-milestones      (milestone 01 = app shell, generated from this design)
   ↓
-/plan-milestones
+/execute-milestones phase1-milestones.md   (or /add-feature per feature)
-  ↓
-/add-feature
 ```
 
 ## Pre-Run Check
@@ -203,7 +201,7 @@ Design documents created:
 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 /generate-app web | flutter | winui3 to generate the initial app
+- 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)
 "

.opencode/command/execute-milestones.md

@@ -30,8 +30,6 @@ opencode
   ↓
 /define-design
   ↓
-/generate-app web | flutter | winui3
-  ↓
 /plan-milestones
   ↓
 /execute-milestones phase1-milestones.md   ← you are here (one phase file per run)
@@ -59,6 +57,7 @@ opencode
 
 1. Follow the **milestone-execution** skill (loaded automatically) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
 2. The **steering** and **development-guidelines** skills apply during implementation, exactly as in `/add-feature`.
+3. **If the milestone is the App Shell milestone (milestone 01)**, additionally follow the **platform-ui-generation** skill (loaded automatically) 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
 

.opencode/command/generate-app.md

@@ -1,155 +0,0 @@
----
-description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec
-agent: build
----
-
-# Generate App (Platform App Generation Phase)
-
-This command generates the **initial application** for the selected target platform, using the design files in `docs/design/` as the source of truth. It creates the app shell, theme, routes, screens, and reusable components — **not** feature logic. Features are added later with `/add-feature`.
-
-**Target platform**: `$ARGUMENTS` — must be one of `web`, `flutter`, `winui3`.
-
-## How to Run
-
-```
-opencode
-> /generate-app web
-> /generate-app flutter
-> /generate-app winui3
-```
-
-## Position in the Workflow
-
-```
-/setup-project
-  ↓
-/define-design
-  ↓
-/generate-app web | flutter | winui3   ← you are here
-  ↓
-/plan-milestones
-  ↓
-/add-feature
-```
-
-## Pre-Run Check
-
-1. Validate the target:
-   - If `$ARGUMENTS` is not one of `web`, `flutter`, `winui3`, stop and ask the user to provide a valid target.
-2. Confirm the design files exist. If any of these 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`
-3. **Important**: Do **not** generate any platform-specific implementation before this command is executed. This command is the only place initial app scaffolding is created.
-4. This command generates from the design **as-is**. Refine the design first (re-run `/define-design` or use `/update-design <change>`) if anything needs to change — it is far easier to refine before code is generated than after.
-
-## Procedure
-
-### Step 0: Read the Inputs
-
-Read all of the following:
-
-- `docs/product-requirements.md`
-- `docs/functional-design.md`
-- `docs/architecture.md`
-- `docs/repository-structure.md`
-- `docs/development-guidelines.md`
-- `docs/design/design-brief.md`
-- `docs/design/design-tokens.json`
-- `docs/design/ui-blueprint.json`
-- `docs/design/platform-mapping.md`
-
-### Step 1: Load the Platform Generation Skill
-
-Follow the **platform-ui-generation** skill (loaded automatically) for the mapping rules from design files to the selected platform's code.
-
-### Step 2: Generate the App Shell
-
-Generate the initial application for the selected target. In all cases:
-
-- Respect the design tokens and the UI blueprint exactly.
-- Create reusable UI components (do not inline everything into screens).
-- Create the initial screen structure (one screen per entry in `ui-blueprint.json`).
-- Create the initial route/navigation structure.
-- Use semantic, accessible markup/semantics where the platform supports it.
-- **Do not implement features that are not described in the current project documents.** Only the app shell, theme, routes, screens, and shared components.
-
-### Step 3: Platform-Specific Requirements
-
-Apply the requirements for the selected target:
-
-#### `/generate-app web`
-- Generate a Web app using the technology defined in `docs/architecture.md`.
-- If no framework is specified, ask the user or choose a simple default suitable for the repository.
-- Convert `design-tokens.json` into CSS variables, a Tailwind config, or an equivalent styling system.
-- Convert `ui-blueprint.json` into pages, layouts, and components.
-- Use semantic HTML where possible.
-- Respect responsive layout requirements (use breakpoints from the tokens).
-
-#### `/generate-app flutter`
-- Generate a Flutter app.
-- Convert `design-tokens.json` into:
-  - `ThemeData`
-  - `ColorScheme`
-  - spacing constants
-  - radius constants
-  - text styles
-- Convert `ui-blueprint.json` into:
-  - routes
-  - screens
-  - reusable widgets
-- Keep clean separation between: `screens`, `widgets`, `theme`, `models`, `services`.
-
-#### `/generate-app winui3`
-- Generate a WinUI 3 application structure.
-- Convert `design-tokens.json` into:
-  - `ResourceDictionary`
-  - theme resources
-  - styles
-- Convert `ui-blueprint.json` into:
-  - XAML pages
-  - `UserControl`s
-  - navigation structure
-- Use C# and XAML.
-- Keep UI logic separated from business logic where possible.
-
-### Step 4: Update Repository Structure Document
-
-If new directories/files were created, update `docs/repository-structure.md` so it reflects the generated layout.
-
-### Step 5: Verify (including Playwright E2E)
-
-- If the target is `web`:
-  - 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 (loaded automatically) 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
-
-- The initial app shell exists for the selected target.
-- Design tokens are converted into the platform's styling system.
-- The UI blueprint is converted into screens, routes, and reusable components.
-- No feature logic beyond what the project documents describe has been implemented.
-- `docs/repository-structure.md` has been updated if the layout changed.
-
-Completion message:
-```
-"App generation is complete for target: [target]
-
-Generated:
-✅ App shell + entry point
-✅ Theme / styling system (from design-tokens.json)
-✅ 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
-- Run /plan-milestones to break the product into milestones with a feature list each
-- Use /add-feature to implement features (they will respect the design spec)
-- Use /update-design when a feature changes the UI
-"
-```

.opencode/command/plan-milestones.md

@@ -24,11 +24,9 @@ opencode
   ↓
 /define-design
   ↓
-/generate-app web | flutter | winui3
-  ↓
 /plan-milestones        ← you are here
   ↓
-/execute-milestones phase1-milestones.md   (one phase file at a time)
+/execute-milestones phase1-milestones.md   (one phase file at a time; milestone 01 generates the app shell)
 ```
 
 ## Pre-Run Check
@@ -37,7 +35,7 @@ opencode
    - `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 suggest running `/define-design` first. Continue only if the user accepts.
+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
@@ -60,6 +58,7 @@ 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.
 
+- **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
@@ -84,9 +83,10 @@ Size each feature so it can be implemented with **one `/add-feature` run**. Spli
 ### Step 4: Group Features into Milestones, and Milestones into Phases
 
 - 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.
+- **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 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.
+- **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
@@ -116,6 +116,7 @@ For each phase, create `docs/milestones/phase[N]-milestones.md` (e.g. `phase1-mi
 
 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.
@@ -137,13 +138,13 @@ Completion message:
 
 Milestone documents created:
 ✅ docs/milestones/roadmap.md            (overview + status)
-✅ docs/milestones/phase1-milestones.md  (MVP phase: milestones 01–NN)
+✅ 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 1]
+- 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
 "
 ```

.opencode/command/update-design.md

@@ -1,11 +1,11 @@
 ---
-description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs)
+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)
 agent: build
 ---
 
 # Update Design
 
-This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (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.
+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`)
 

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

@@ -91,7 +91,7 @@ test.describe('Edit user profile', () => {
 
 ## Writing the App-Shell Smoke Spec
 
-Created by `/generate-app` (web target). `e2e/app-shell.spec.ts` must verify:
+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.
@@ -108,7 +108,7 @@ npm run test:e2e
 
 ## Verification Checklist
 
-Used by `/add-feature` Step 7, `/execute-milestones` Step 2.6, and `/generate-app` Step 5:
+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.

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

@@ -18,13 +18,14 @@ Roadmap (roadmap.md)
 
 ## Core Principles
 
-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.
+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. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
+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. **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.
+3. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
-4. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
+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. **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.
+5. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
-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.
+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. **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`.
+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
 
@@ -50,6 +51,20 @@ File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-miles
 
 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:
@@ -66,10 +81,11 @@ Too small (merge it): "Change button color" → fold into the feature that owns
 ## How to Group Milestones and Phases
 
 1. Tag every feature with its PRD priority and its dependencies.
-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).
+2. Milestone 01 (App Shell): always first — see "Milestone 01" above.
-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.
+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. **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.
+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. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.
+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
 
@@ -83,6 +99,7 @@ Too small (merge it): "Change button color" → fold into the feature that owns
 
 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.

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

@@ -2,6 +2,8 @@
 
 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]
 

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

@@ -1,18 +1,18 @@
 ---
 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 running /generate-app or implementing UI against the design spec.
+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.
 ---
 
 # Platform UI Generation Skill
 
-This skill explains how to convert the design files under `docs/design/` into application code. It is used by `/generate-app` and by `/add-feature` when implementing UI.
+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**: `/generate-app` creates the shell, theme, routes, screens, and shared components only. Features come from `/add-feature`.
+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
@@ -84,7 +84,7 @@ Each generated reusable component must:
 - Reference tokens for all visual values — no hard-coded literals.
 - Stay presentational: no feature/business logic.
 
-## Scaffolding Scope (what `/generate-app` creates)
+## Scaffolding Scope (what the App Shell milestone creates)
 
 - App entry point and shell
 - Theme/styling system from tokens

AGENTS.md

@@ -85,7 +85,7 @@ Define "what to build" and "how to build it" for the entire application:
 - **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 `/generate-app` and `/add-feature`
+- 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
@@ -103,7 +103,7 @@ Define "what to do this time" for a specific development task:
 ### opencode Configuration (`.opencode/`)
 
 - `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
-- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
+- `.opencode/command/` - Slash commands (setup-project, define-design, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
 - `.opencode/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,10 +114,9 @@ Define "what to do this time" for a specific development task:
 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. Generate the initial app with `/generate-app web | flutter | winui3`
+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. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with one `phase[N]-milestones.md` per phase)
+6. Implement, either way:
-7. 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
-   - `/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
@@ -135,7 +134,6 @@ Define "what to do this time" for a specific development task:
 
 # Design phase
 > /define-design
-> /generate-app web
 > /update-design add a profile screen
 
 # Milestone planning and execution

README.md

@@ -14,7 +14,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
 How a project goes from idea to working code with this boilerplate:
 
 ```
-Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /execute-milestones (phase by phase)
+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
@@ -42,18 +42,17 @@ This is the key design-decision gate: iterate on the design while it is still ch
 - Re-run `/define-design` — change the overall direction
 - Repeat until you approve the design (especially `ui-blueprint.json`)
 
-### Step 5 — Generate the initial app: `/generate-app web | flutter | winui3`
+### Step 5 — Plan milestones: `/plan-milestones`
-Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and
-reusable components. No feature logic yet.
-
-### Step 6 — 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. Phase 1 delivers the MVP; later phases build on it by priority and dependency.
+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 7 — Implement the milestones
+### Step 6 — Implement the milestones
 
 Two ways to work through the plan:
 
@@ -75,7 +74,7 @@ A fully autonomous loop, one feature per run. Each run:
 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 8 — Repeat and maintain
+### 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
@@ -228,7 +227,6 @@ opencode
     ├── command/               # Slash commands
     │   ├── setup-project.md
     │   ├── define-design.md
-    │   ├── generate-app.md
     │   ├── update-design.md
     │   ├── plan-milestones.md
     │   ├── execute-milestones.md
@@ -344,18 +342,7 @@ than on generated code:
 
 **The design source of truth is `docs/design/ui-blueprint.json`.** SVG files are visual references only.
 
-### 3. Generate the app
+### 3. Plan milestones
-
-```
-> /generate-app web
-> /generate-app flutter
-> /generate-app winui3
-```
-
-Scaffolds the initial application for the selected target from the design spec — app shell, theme
-(from tokens), routes, screens, and reusable components. No feature logic is implemented here.
-
-### 4. Plan milestones
 
 ```
 > /plan-milestones
@@ -365,10 +352,13 @@ Scaffolds the initial application for the selected target from the design spec
 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`, …) listing its
 milestones and their features — each feature sized for one `/add-feature` run, with acceptance
-criteria and a ready-to-run command. Phase 1 delivers the MVP. You'll be asked once about phase
+criteria and a ready-to-run command. **Milestone 01 is always "App Shell Generation"**: executed
-count, MVP scope, priorities, and constraints; sensible defaults are proposed from the PRD.
+like any other milestone, it scaffolds the initial app from the design spec (theme from tokens,
+one screen per blueprint entry, routes, reusable components — no feature logic) plus the Playwright
+smoke spec. Phase 1 delivers the MVP. You'll be asked once about target platform, phase count,
+MVP scope, priorities, and constraints; sensible defaults are proposed from the PRD.
 
-### 5. Add a feature
+### 4. Add a feature
 
 ```
 > /add-feature User authentication
@@ -384,7 +374,7 @@ This fully autonomous workflow:
 7. Writes Playwright E2E tests for the acceptance criteria, then runs `npm test`, `npm run lint`, `npm run typecheck`, `npm run test:e2e`
 8. Records a retrospective, reconciles all six persistent docs with the feature, and checks the feature off in its phase file
 
-### 6. Execute a phase file (alternative to per-feature runs)
+### 5. Execute a phase file (alternative to per-feature runs)
 
 ```
 > /execute-milestones phase1-milestones.md
@@ -400,7 +390,7 @@ runs the test suite, reconciles the docs, marks the milestone `Completed` — an
 the next one. When the last milestone finishes, the phase is marked `Completed` in the roadmap.
 It only stops early on a genuine external blocker, which it records in the roadmap.
 
-### 7. Review a document
+### 6. Review a document
 
 ```
 > /review-docs docs/product-requirements.md
@@ -409,7 +399,7 @@ It only stops early on a genuine external blocker, which it records in the roadm
 Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
 completeness, clarity, consistency, implementability, and measurability.
 
-### 8. Day-to-day editing
+### 7. Day-to-day editing
 
 You don't always need a command — just ask in normal conversation:
 
@@ -432,17 +422,16 @@ Recommended workflow:
 3. Review `docs/design/` and refine the UI/UX until approved:
    - Re-run `/define-design` to change direction, or
    - Run `/update-design <change>` for targeted refinements
-4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
+4. Run `/plan-milestones` to break the product into phases and milestones (one `phaseN-milestones.md` per phase; milestone 01 = App Shell Generation for the chosen platform)
-5. Run `/plan-milestones` to break the product into phases and milestones (one `phaseN-milestones.md` per phase)
+5. Use `/execute-milestones phase1-milestones.md` to implement a phase's milestones one by one (milestone 01 generates the initial app), or `/add-feature` to go feature by feature
-6. Use `/execute-milestones phase1-milestones.md` to implement a phase's milestones one by one, or `/add-feature` to go feature by feature
+6. Use `/update-design` whenever a feature changes the UI
-7. Use `/update-design` whenever a feature changes the UI
 
 Source of truth:
 
 - The design source of truth is `docs/design/ui-blueprint.json`.
 - SVG files (`docs/design/screens/*.svg`) are only visual references.
 - Generated UI should follow `docs/design/design-tokens.json` — no hard-coded values.
-- No platform-specific implementation is generated before `/generate-app` is executed.
+- No platform-specific implementation is generated before the App Shell milestone (milestone 01) is executed.
 
 See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 
@@ -451,7 +440,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 ## E2E Testing (Playwright)
 
 Every verification step in this boilerplate includes end-to-end tests. The standard verification
-sequence — used by `/add-feature`, `/execute-milestones`, and `/generate-app` — is:
+sequence — used by `/add-feature` and `/execute-milestones` — is:
 
 ```bash
 npm test           # unit tests
@@ -467,7 +456,7 @@ How it works (defined in the `e2e-testing` skill):
   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**: `/generate-app` creates `e2e/app-shell.spec.ts`, which
+- **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.
@@ -492,9 +481,8 @@ Playwright covers the `web` target; for `flutter` the equivalent is `integration
 |---|---|---|
 | `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
 | `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
-| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
 | `/update-design` | Update the design spec 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 | `/plan-milestones 2 phases, MVP first` |
+| `/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

@@ -1,6 +1,6 @@
 # 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 `/generate-app` and `/add-feature`.
+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
 
@@ -16,6 +16,7 @@ Generated UI must follow `design-tokens.json` — no hard-coded values.
 
 ```
 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
@@ -28,6 +29,9 @@ docs/design/
 
 ## 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.
 
@@ -52,11 +56,11 @@ Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `<screen-i
 ```
 /setup-project   → product/architecture docs
 /define-design   → creates the files above
-/generate-app web | flutter | winui3   → scaffolds the app from these files
+/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 `/generate-app` will ask you to run `/define-design` first.
+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

@@ -39,8 +39,7 @@ One file per phase — the execution unit for `/execute-milestones`. Contains th
 ```
 /setup-project     → product/architecture docs
 /define-design     → UI/UX design spec
-/generate-app      → initial app shell
+/plan-milestones   → creates the files above (milestone 01 = App Shell Generation)
-/plan-milestones   → creates the files above
 /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
 ```