claudecode-boilerplate/.claude/commands/generate-app.md

---
description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec
---

# 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

```bash
claude
> /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

Load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) 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

- 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.
- For `flutter` / `winui3`, run the platform's available static checks if the toolchain is present; 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

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
"
```