---
name: build-from-spec
description: Build a working application from an AutoGherk spec-output folder containing architecture blueprints, design tokens, and reference screenshots
disable-model-invocation: false
argument-hint: "<spec-output-dir> [--framework next|vite|remix]"
allowed-tools: Read Write Edit Bash Glob Grep
---

Build a working application from an AutoGherk build spec.

## What you receive

The user provides a path to a spec-output directory generated by `autogherk generate --format spec`. This directory contains:

```
spec-output/
  spec-overview.md        # Full architecture doc (screens, data model, navigation, components)
  tokens.json             # Design tokens (colors, typography, spacing, border radius, shadows)
  spec.json               # Raw structured JSON for programmatic consumption
  screenshots/            # Reference screenshot per screen (PNG)
  *.spec.md               # Per-screen spec with components, interactions, data model
```

## How to build

### Phase 1: Understand the spec

1. Read `spec-overview.md` completely to understand the full application architecture
2. Read `tokens.json` to understand the design system
3. Read `spec.json` and note the total number of screens, entities, and navigation flows
4. List all screenshot files in `screenshots/` — these are your visual reference for each screen

### Phase 2: Scaffold the project

1. Determine the framework (Next.js by default, or as specified by the user)
2. Initialize the project with the appropriate CLI (`npx create-next-app@latest`, etc.)
3. Wire `tokens.json` into the styling system:
   - For Tailwind: extend `tailwind.config.ts` with the colors, spacing, border radius, and shadows
   - For CSS: create CSS custom properties from the tokens
4. Create TypeScript interfaces from the `dataModel` section of `spec.json`
5. Create mock data files matching the entity schemas with realistic sample data

### Phase 3: Build the shell

1. Build the global layout — sidebar navigation, header, routing structure
2. Reference `globalComponents` in `spec.json` for sidebar menu items, header layout
3. Look at ANY screenshot to verify the sidebar/header matches visually
4. Set up all routes from the `screens` array in `spec.json`

### Phase 4: Build screens (one at a time)

For EACH screen in `spec.json`, in this order:

1. Read the screen's `.spec.md` file for detailed component tree and interactions
2. View the screen's screenshot in `screenshots/` as visual reference
3. Build the route and all components listed in the spec
4. Wire up the mock data
5. Implement the interactions (click handlers, navigation, form submissions)
6. Move to the next screen

**Build order**: Start with the login/auth screen, then the main dashboard, then work through remaining screens following the navigation flow.

### Phase 5: Polish

1. Ensure all navigation flows work (check the `navigation` section of `spec.json`)
2. Verify the visual output matches the reference screenshots
3. Run the dev server and confirm each screen renders correctly

## Key principles

- **Match the screenshots**: The reference screenshots are ground truth for what each screen should look like. Use them as your primary visual guide.
- **Use the tokens**: Every color, font size, spacing value, border radius, and shadow should come from `tokens.json`. Do not hardcode values.
- **Mock the data**: Generate realistic mock data that matches the data model. Use the entity relationships to make the mock data consistent.
- **One screen at a time**: Build and verify each screen before moving on. This keeps the work focused and manageable.
- **Inferred screens**: Some screens may be marked "(inferred)" in the spec — these were not directly shown in the video but are logically necessary. Build them, but note they may need more creative interpretation.

## Example invocation

```
/build-from-spec ./spec-output
/build-from-spec ./spec-output --framework vite
```