From 0f1d405d8fc3fa8b684495aa6d244962be88507b Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:00:50 +0000
Subject: [PATCH 1/8] Add openapi-to-frontend plugin

This plugin generates a full TypeScript client, React component library,
and frontend app from an OpenAPI specification.

Features:
- Phase 1: Generate TypeScript client (types, API class, auth handlers)
- Phase 2: Generate React components (Form, Detail, List per schema)
- Phase 3: Generate React frontend app (routing, context, pages)
- Phase 4: Generate comprehensive tests (unit, integration, e2e)
- Phase 5: Generate GitHub Actions CI/CD workflows

Additional capabilities:
- Incremental updates when spec changes (surgical edits, not regeneration)
- Support for API Key, Bearer Token, and OAuth2 authentication
- E2E backend strategy detection (Docker, mock server, external URL)
- Verification scripts for coverage and component completeness

Co-authored-by: openhands <openhands@all-hands.dev>
---
 marketplaces/default.json                     |  16 +
 plugins/openapi-to-frontend/README.md         | 252 +++++
 .../openapi-to-frontend/agents/spec-differ.md | 357 +++++++
 .../commands/generate-all.md                  | 188 ++++
 plugins/openapi-to-frontend/hooks/hooks.json  |   6 +
 .../references/auth-patterns.md               | 629 ++++++++++++
 .../references/change-taxonomy.md             | 577 +++++++++++
 .../references/naming-conventions.md          | 311 ++++++
 .../scripts/lint-generated.sh                 | 105 ++
 .../scripts/parse-openapi.py                  | 321 ++++++
 .../scripts/verify-components.py              | 291 ++++++
 .../scripts/verify-coverage.py                | 255 +++++
 .../skills/generate-ci/SKILL.md               | 494 +++++++++
 .../skills/generate-client/SKILL.md           | 482 +++++++++
 .../skills/generate-components/SKILL.md       | 740 ++++++++++++++
 .../skills/generate-frontend/SKILL.md         | 769 ++++++++++++++
 .../skills/generate-tests/SKILL.md            | 946 ++++++++++++++++++
 .../skills/update-from-spec/SKILL.md          | 456 +++++++++
 18 files changed, 7195 insertions(+)
 create mode 100644 plugins/openapi-to-frontend/README.md
 create mode 100644 plugins/openapi-to-frontend/agents/spec-differ.md
 create mode 100644 plugins/openapi-to-frontend/commands/generate-all.md
 create mode 100644 plugins/openapi-to-frontend/hooks/hooks.json
 create mode 100644 plugins/openapi-to-frontend/references/auth-patterns.md
 create mode 100644 plugins/openapi-to-frontend/references/change-taxonomy.md
 create mode 100644 plugins/openapi-to-frontend/references/naming-conventions.md
 create mode 100755 plugins/openapi-to-frontend/scripts/lint-generated.sh
 create mode 100755 plugins/openapi-to-frontend/scripts/parse-openapi.py
 create mode 100755 plugins/openapi-to-frontend/scripts/verify-components.py
 create mode 100755 plugins/openapi-to-frontend/scripts/verify-coverage.py
 create mode 100644 plugins/openapi-to-frontend/skills/generate-ci/SKILL.md
 create mode 100644 plugins/openapi-to-frontend/skills/generate-client/SKILL.md
 create mode 100644 plugins/openapi-to-frontend/skills/generate-components/SKILL.md
 create mode 100644 plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md
 create mode 100644 plugins/openapi-to-frontend/skills/generate-tests/SKILL.md
 create mode 100644 plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md

diff --git a/marketplaces/default.json b/marketplaces/default.json
index 60c03b7..28c7d75 100644
--- a/marketplaces/default.json
+++ b/marketplaces/default.json
@@ -483,6 +483,22 @@
                 "verification",
                 "sample"
             ]
+        },
+        {
+            "name": "openapi-to-frontend",
+            "source": "./plugins/openapi-to-frontend",
+            "description": "Generate a full TypeScript client, React component library, and frontend app from an OpenAPI spec. Includes tests and CI/CD workflows.",
+            "category": "development",
+            "keywords": [
+                "openapi",
+                "swagger",
+                "typescript",
+                "react",
+                "codegen",
+                "frontend",
+                "api",
+                "client"
+            ]
         }
     ]
 }
diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
new file mode 100644
index 0000000..d43ef9c
--- /dev/null
+++ b/plugins/openapi-to-frontend/README.md
@@ -0,0 +1,252 @@
+# openapi-to-frontend
+
+Generate a full TypeScript client, React component library, and frontend app from an OpenAPI spec.
+
+## Overview
+
+This plugin converts an OpenAPI specification into three layers of output:
+
+1. **TypeScript Client** — one class per schema, one method per API endpoint
+2. **React Component Library** — one component per schema, wired to the TS client
+3. **React Frontend App** — a purpose-built UI inferred from the API's description
+4. **Comprehensive Tests** — unit, integration, and e2e tests
+5. **GitHub Actions CI/CD** — build/test on PR, deploy to GitHub Pages, publish to npm
+
+The plugin also handles **incremental updates**: given a change to the OpenAPI spec, it produces targeted changes rather than regenerating everything.
+
+## Quick Start
+
+Provide an OpenAPI spec (JSON or YAML) and run phases sequentially:
+
+```
+/generate-all path/to/openapi.yaml
+```
+
+Or run individual phases:
+
+1. **Generate client**: Creates TypeScript types and API class
+2. **Generate components**: Creates React components for each schema
+3. **Generate frontend**: Creates a full application shell
+4. **Generate tests**: Creates unit, integration, and e2e tests
+5. **Generate CI**: Creates GitHub Actions workflows
+
+## Plugin Contents
+
+```
+plugins/openapi-to-frontend/
+├── README.md                           # This file
+├── commands/
+│   └── generate-all.md                 # Slash command: run all phases
+├── skills/
+│   ├── generate-client/
+│   │   └── SKILL.md                    # Phase 1: OpenAPI → TypeScript client
+│   ├── generate-components/
+│   │   └── SKILL.md                    # Phase 2: TS client → React components
+│   ├── generate-frontend/
+│   │   └── SKILL.md                    # Phase 3: Components → full app
+│   ├── generate-tests/
+│   │   └── SKILL.md                    # Phase 4: Tests
+│   ├── generate-ci/
+│   │   └── SKILL.md                    # Phase 5: GitHub Actions
+│   └── update-from-spec/
+│       └── SKILL.md                    # Incremental updates
+├── agents/
+│   └── spec-differ.md                  # Subagent: diffs two spec versions
+├── hooks/
+│   └── hooks.json                      # (reserved for future use)
+├── scripts/
+│   ├── parse-openapi.py                # Extract schemas, endpoints, auth from spec
+│   ├── lint-generated.sh               # Run eslint + tsc on generated code
+│   ├── verify-coverage.py              # Cross-reference spec against client
+│   └── verify-components.py            # Cross-reference components against client
+├── references/
+│   ├── auth-patterns.md                # Bearer, API key, OAuth2 handling
+│   ├── naming-conventions.md           # Spec→TS→React naming rules
+│   └── change-taxonomy.md              # Enumerated change types + handling
+└── .mcp.json                           # (reserved for future use)
+```
+
+## Features
+
+- **Full Stack Generation** — From spec to deployable frontend in one workflow
+- **Type Safety** — TypeScript throughout, with proper generics and inference
+- **Auth Support** — API Key, Bearer Token, and OAuth2 flows
+- **Component Library** — Reusable Form, Detail, and List components per schema
+- **Tailored UIs** — Frontend design inferred from API purpose (CRUD, analytics, workflow)
+- **Incremental Updates** — Surgical edits when the spec changes
+- **Test Coverage** — Unit, integration, and e2e tests with mock factories
+- **CI/CD Ready** — GitHub Actions for build, test, deploy, and publish
+
+## Prerequisites
+
+- Node.js 18+ with npm or yarn
+- TypeScript 5+
+- React 18+
+- OpenAPI 3.0+ specification (JSON or YAML)
+
+## Output Structure
+
+After running all phases:
+
+```
+your-project/
+├── client/
+│   ├── types.ts            # TypeScript interfaces for all schemas
+│   ├── api.ts              # API class with async methods
+│   ├── auth.ts             # Auth configuration
+│   └── index.ts            # Barrel export
+├── components/
+│   ├── <SchemaName>/
+│   │   ├── <SchemaName>Form.tsx
+│   │   ├── <SchemaName>Detail.tsx
+│   │   ├── <SchemaName>List.tsx
+│   │   └── index.ts
+│   ├── shared/
+│   │   ├── LoadingSpinner.tsx
+│   │   ├── ErrorDisplay.tsx
+│   │   └── Pagination.tsx
+│   └── index.ts
+├── app/
+│   ├── App.tsx
+│   ├── pages/
+│   ├── context/
+│   ├── hooks/
+│   └── utils/
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   ├── e2e/
+│   └── setup/
+└── .github/
+    └── workflows/
+        ├── ci.yml
+        ├── deploy.yml
+        └── publish.yml
+```
+
+## Workflow Phases
+
+### Phase 1: Generate Client
+
+Creates the TypeScript API client:
+
+- **types.ts** — Interface for every schema in `components/schemas`
+- **api.ts** — Class with async methods for every endpoint
+- **auth.ts** — Auth handlers based on `securitySchemes`
+
+See [skills/generate-client/SKILL.md](skills/generate-client/SKILL.md)
+
+### Phase 2: Generate Components
+
+Creates React components for each schema:
+
+- **Form** — Create/edit with validation
+- **Detail** — Read-only view
+- **List** — Table with pagination
+
+See [skills/generate-components/SKILL.md](skills/generate-components/SKILL.md)
+
+### Phase 3: Generate Frontend
+
+Creates the application shell:
+
+- Routing based on API resources
+- Auth context and guards
+- UI tailored to API purpose (CRUD, analytics, workflow, search)
+
+See [skills/generate-frontend/SKILL.md](skills/generate-frontend/SKILL.md)
+
+### Phase 4: Generate Tests
+
+Creates comprehensive test coverage:
+
+- **Unit** — Client methods, type guards, component rendering
+- **Integration** — Form→Client flows, auth context
+- **E2E** — Smoke tests, CRUD flows, auth flows
+
+See [skills/generate-tests/SKILL.md](skills/generate-tests/SKILL.md)
+
+### Phase 5: Generate CI
+
+Creates GitHub Actions workflows:
+
+- **ci.yml** — Build + test on push/PR
+- **deploy.yml** — Deploy to GitHub Pages
+- **publish.yml** — Publish packages to npm
+
+See [skills/generate-ci/SKILL.md](skills/generate-ci/SKILL.md)
+
+## Incremental Updates
+
+When the OpenAPI spec changes:
+
+1. The spec-differ agent compares old and new specs
+2. Changes are classified (new schema, removed endpoint, etc.)
+3. Surgical edits are applied to existing files
+
+See [skills/update-from-spec/SKILL.md](skills/update-from-spec/SKILL.md)
+
+## Auth Patterns
+
+The plugin supports three auth styles:
+
+| Style | Client Handling | Frontend UI |
+|-------|-----------------|-------------|
+| API Key | Attached as header/query per spec | Settings page for key input |
+| Bearer Token | `Authorization: Bearer <token>` | Token input or login form |
+| OAuth2 | Full flow with PKCE, auto-refresh | Login/callback/logout pages |
+
+See [references/auth-patterns.md](references/auth-patterns.md)
+
+## Naming Conventions
+
+| OpenAPI | TypeScript | React Component |
+|---------|------------|-----------------|
+| `UserProfile` schema | `interface UserProfile` | `UserProfileForm`, `UserProfileDetail` |
+| `GET /users/{id}` | `getUser(id: string)` | Used in `UserDetail` |
+| `POST /users` | `createUser(data)` | Used in `UserForm` |
+| `snake_case` field | `camelCase` property | "Title Case" label |
+
+See [references/naming-conventions.md](references/naming-conventions.md)
+
+## Scripts
+
+### parse-openapi.py
+
+```bash
+python scripts/parse-openapi.py openapi.yaml > spec-summary.json
+```
+
+Outputs structured JSON with schemas, endpoints, and auth schemes.
+
+### lint-generated.sh
+
+```bash
+./scripts/lint-generated.sh
+```
+
+Runs eslint and tsc on generated code. Returns non-zero on errors.
+
+### verify-coverage.py
+
+```bash
+python scripts/verify-coverage.py openapi.yaml client/
+```
+
+Ensures every schema and endpoint has corresponding TypeScript code.
+
+### verify-components.py
+
+```bash
+python scripts/verify-components.py client/ components/
+```
+
+Ensures every type has corresponding React components.
+
+## Contributing
+
+See the main [extensions repository](https://github.com/OpenHands/extensions) for contribution guidelines.
+
+## License
+
+This plugin is part of the OpenHands extensions repository. See [LICENSE](../../LICENSE) for details.
diff --git a/plugins/openapi-to-frontend/agents/spec-differ.md b/plugins/openapi-to-frontend/agents/spec-differ.md
new file mode 100644
index 0000000..8f1e399
--- /dev/null
+++ b/plugins/openapi-to-frontend/agents/spec-differ.md
@@ -0,0 +1,357 @@
+# Spec Differ Agent
+
+A subagent that compares two OpenAPI specification versions and produces a structured diff.
+
+## Purpose
+
+This agent analyzes the differences between two OpenAPI specs and classifies each change into a type that can be acted upon by the update-from-spec skill.
+
+## Invocation
+
+```
+@spec-differ <old-spec-path> <new-spec-path>
+```
+
+## Output Format
+
+The agent produces a JSON structure:
+
+```json
+{
+  "summary": {
+    "schemas_added": 2,
+    "schemas_removed": 0,
+    "schemas_modified": 3,
+    "endpoints_added": 4,
+    "endpoints_removed": 1,
+    "endpoints_modified": 2,
+    "auth_changed": false
+  },
+  "changes": [
+    {
+      "type": "schema_added",
+      "path": "components/schemas/Order",
+      "details": {
+        "name": "Order",
+        "fields": [
+          { "name": "id", "type": "string", "required": true },
+          { "name": "userId", "type": "string", "required": true },
+          { "name": "items", "type": "array", "items": "OrderItem", "required": true },
+          { "name": "status", "type": "OrderStatus", "required": true },
+          { "name": "createdAt", "type": "string", "format": "date-time", "required": true }
+        ]
+      }
+    },
+    {
+      "type": "field_added",
+      "path": "components/schemas/User.properties.phoneNumber",
+      "details": {
+        "schema": "User",
+        "field": "phoneNumber",
+        "type": "string",
+        "required": false
+      }
+    },
+    {
+      "type": "endpoint_added",
+      "path": "paths./orders.get",
+      "details": {
+        "method": "GET",
+        "path": "/orders",
+        "operationId": "listOrders",
+        "parameters": [
+          { "name": "page", "in": "query", "type": "integer" },
+          { "name": "status", "in": "query", "type": "OrderStatus" }
+        ],
+        "response": "OrderListResponse"
+      }
+    }
+  ],
+  "breaking_changes": [
+    {
+      "type": "field_removed",
+      "path": "components/schemas/User.properties.legacyId",
+      "severity": "high",
+      "migration": "Ensure no client code references User.legacyId before removing"
+    }
+  ]
+}
+```
+
+## Change Types
+
+### Schema Changes
+
+| Type | Description |
+|------|-------------|
+| `schema_added` | New schema in components/schemas |
+| `schema_removed` | Schema deleted |
+| `schema_renamed` | Schema name changed (detected by field similarity) |
+| `field_added` | New property added to schema |
+| `field_removed` | Property removed from schema |
+| `field_type_changed` | Property type changed |
+| `field_required_changed` | Required status changed |
+
+### Endpoint Changes
+
+| Type | Description |
+|------|-------------|
+| `endpoint_added` | New path+method combination |
+| `endpoint_removed` | Path+method deleted |
+| `endpoint_method_changed` | HTTP method changed (rare) |
+| `param_added` | New parameter (path, query, header, body) |
+| `param_removed` | Parameter removed |
+| `param_type_changed` | Parameter type changed |
+| `response_type_changed` | Response schema changed |
+| `response_code_added` | New response code |
+| `response_code_removed` | Response code removed |
+
+### Auth Changes
+
+| Type | Description |
+|------|-------------|
+| `auth_scheme_added` | New security scheme |
+| `auth_scheme_removed` | Security scheme removed |
+| `auth_scheme_modified` | Scheme configuration changed |
+| `security_requirement_changed` | Endpoint auth requirements changed |
+
+### Metadata Changes
+
+| Type | Description |
+|------|-------------|
+| `info_changed` | title, version, description changed |
+| `server_added` | New server URL |
+| `server_removed` | Server URL removed |
+| `tag_added` | New tag |
+| `tag_removed` | Tag removed |
+
+## Diff Algorithm
+
+### Step 1: Normalize Specs
+
+1. Parse both specs (JSON or YAML)
+2. Resolve all `$ref` references
+3. Sort keys for consistent comparison
+4. Handle nullable and oneOf/anyOf unions
+
+### Step 2: Compare Schemas
+
+For each schema in old spec:
+- If not in new spec → `schema_removed`
+- If in new spec → compare fields
+
+For each schema in new spec:
+- If not in old spec → `schema_added`
+
+For each field:
+- Compare type, format, required, enum values
+
+### Step 3: Compare Endpoints
+
+Build a key for each endpoint: `{method} {path}`
+
+For each endpoint in old spec:
+- If not in new spec → `endpoint_removed`
+- If in new spec → compare parameters and responses
+
+For each endpoint in new spec:
+- If not in old spec → `endpoint_added`
+
+### Step 4: Compare Auth
+
+Compare `components/securitySchemes`:
+- Added/removed schemes
+- Changed scheme configurations
+
+Compare `security` requirements on paths
+
+### Step 5: Identify Breaking Changes
+
+Flag changes that may break existing clients:
+
+- `schema_removed`
+- `field_removed`
+- `endpoint_removed`
+- `param_added` (required)
+- `field_type_changed`
+- `auth_scheme_removed`
+
+## Example Usage
+
+### Input: old-spec.yaml
+
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email]
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        legacyId:
+          type: string
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+```
+
+### Input: new-spec.yaml
+
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.1.0
+components:
+  schemas:
+    User:
+      type: object
+      required: [id, email]
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        phoneNumber:
+          type: string
+    Order:
+      type: object
+      required: [id, userId]
+      properties:
+        id:
+          type: string
+        userId:
+          type: string
+paths:
+  /users:
+    get:
+      operationId: listUsers
+      parameters:
+        - name: search
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+  /orders:
+    get:
+      operationId: listOrders
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Order'
+```
+
+### Output
+
+```json
+{
+  "summary": {
+    "schemas_added": 1,
+    "schemas_removed": 0,
+    "schemas_modified": 1,
+    "endpoints_added": 1,
+    "endpoints_removed": 0,
+    "endpoints_modified": 1,
+    "auth_changed": false
+  },
+  "changes": [
+    {
+      "type": "schema_added",
+      "path": "components/schemas/Order",
+      "details": {
+        "name": "Order",
+        "fields": [
+          { "name": "id", "type": "string", "required": true },
+          { "name": "userId", "type": "string", "required": true }
+        ]
+      }
+    },
+    {
+      "type": "field_added",
+      "path": "components/schemas/User.properties.phoneNumber",
+      "details": {
+        "schema": "User",
+        "field": "phoneNumber",
+        "type": "string",
+        "required": false
+      }
+    },
+    {
+      "type": "field_removed",
+      "path": "components/schemas/User.properties.legacyId",
+      "details": {
+        "schema": "User",
+        "field": "legacyId",
+        "type": "string"
+      }
+    },
+    {
+      "type": "param_added",
+      "path": "paths./users.get.parameters.search",
+      "details": {
+        "endpoint": "GET /users",
+        "param": "search",
+        "in": "query",
+        "type": "string",
+        "required": false
+      }
+    },
+    {
+      "type": "endpoint_added",
+      "path": "paths./orders.get",
+      "details": {
+        "method": "GET",
+        "path": "/orders",
+        "operationId": "listOrders",
+        "response": "Order[]"
+      }
+    }
+  ],
+  "breaking_changes": [
+    {
+      "type": "field_removed",
+      "path": "components/schemas/User.properties.legacyId",
+      "severity": "medium",
+      "migration": "Remove references to User.legacyId in generated code"
+    }
+  ]
+}
+```
+
+## Error Handling
+
+- If specs are invalid YAML/JSON, report parsing errors
+- If specs are not valid OpenAPI 3.x, report validation errors
+- If `$ref` cannot be resolved, report reference errors
+
+## See Also
+
+- [../skills/update-from-spec/SKILL.md](../skills/update-from-spec/SKILL.md) — Uses this agent's output
+- [../references/change-taxonomy.md](../references/change-taxonomy.md) — Full change type definitions
diff --git a/plugins/openapi-to-frontend/commands/generate-all.md b/plugins/openapi-to-frontend/commands/generate-all.md
new file mode 100644
index 0000000..08e2666
--- /dev/null
+++ b/plugins/openapi-to-frontend/commands/generate-all.md
@@ -0,0 +1,188 @@
+# /generate-all
+
+Run all generation phases end-to-end from an OpenAPI specification.
+
+## Usage
+
+```
+/generate-all <spec-file> [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `spec-file` | Path to OpenAPI specification (JSON or YAML) |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--output-dir <dir>` | Output directory (default: current directory) |
+| `--skip-tests` | Skip test generation |
+| `--skip-ci` | Skip CI/CD workflow generation |
+| `--client-only` | Generate only the TypeScript client |
+| `--dry-run` | Show what would be generated without writing files |
+
+## Examples
+
+### Full generation
+
+```
+/generate-all ./openapi.yaml
+```
+
+This will:
+1. Parse the OpenAPI spec
+2. Generate TypeScript client in `client/`
+3. Generate React components in `components/`
+4. Generate React frontend in `app/`
+5. Generate tests in `tests/`
+6. Generate GitHub Actions in `.github/workflows/`
+
+### Client only
+
+```
+/generate-all ./api-spec.json --client-only
+```
+
+### Custom output directory
+
+```
+/generate-all ./openapi.yaml --output-dir ./packages/generated
+```
+
+### Skip CI
+
+```
+/generate-all ./openapi.yaml --skip-ci
+```
+
+## Workflow
+
+The command runs these phases in sequence:
+
+### Phase 1: Parse Spec
+
+```bash
+python scripts/parse-openapi.py <spec-file> > .generated/spec-summary.json
+```
+
+Extracts schemas, endpoints, and auth schemes into a normalized format.
+
+### Phase 2: Generate Client
+
+Uses `skills/generate-client/SKILL.md`:
+
+- Creates `client/types.ts` with TypeScript interfaces
+- Creates `client/api.ts` with API class and methods
+- Creates `client/auth.ts` with auth handlers
+- Creates `client/index.ts` barrel export
+
+### Phase 3: Generate Components
+
+Uses `skills/generate-components/SKILL.md`:
+
+- Creates `components/<Schema>/` directories
+- Creates Form, Detail, List components per schema
+- Creates `components/shared/` utilities
+- Creates barrel exports
+
+### Phase 4: Generate Frontend
+
+Uses `skills/generate-frontend/SKILL.md`:
+
+- Infers app type from API structure
+- Creates `app/App.tsx` with routing
+- Creates `app/pages/` per resource
+- Creates `app/context/` for API and auth
+- Creates `app/hooks/` for data fetching
+
+### Phase 5: Generate Tests
+
+Uses `skills/generate-tests/SKILL.md`:
+
+- Creates `tests/setup/` with config and factories
+- Creates `tests/unit/` for client and components
+- Creates `tests/integration/` for flows
+- Creates `tests/e2e/` for Playwright
+
+### Phase 6: Generate CI
+
+Uses `skills/generate-ci/SKILL.md`:
+
+- Creates `.github/workflows/ci.yml`
+- Creates `.github/workflows/deploy.yml`
+- Creates `.github/workflows/publish.yml`
+
+## Verification
+
+After generation, the command runs:
+
+```bash
+# Lint check
+./scripts/lint-generated.sh
+
+# Coverage verification
+python scripts/verify-coverage.py <spec-file> client/
+python scripts/verify-components.py client/ components/
+```
+
+## Output Structure
+
+```
+<output-dir>/
+├── client/
+│   ├── types.ts
+│   ├── api.ts
+│   ├── auth.ts
+│   └── index.ts
+├── components/
+│   ├── <Schema>/
+│   │   ├── <Schema>Form.tsx
+│   │   ├── <Schema>Detail.tsx
+│   │   ├── <Schema>List.tsx
+│   │   └── index.ts
+│   ├── shared/
+│   └── index.ts
+├── app/
+│   ├── App.tsx
+│   ├── Layout.tsx
+│   ├── main.tsx
+│   ├── pages/
+│   ├── context/
+│   ├── hooks/
+│   └── utils/
+├── tests/
+│   ├── setup/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+└── .github/
+    └── workflows/
+        ├── ci.yml
+        ├── deploy.yml
+        └── publish.yml
+```
+
+## Interactive Mode
+
+When the API purpose is ambiguous, the command asks for confirmation:
+
+> "Based on the API, this appears to be a **user management system**. I'll generate:
+> - Dashboard with user list
+> - User detail and edit pages
+> - Role management section
+> - OAuth2 login flow
+>
+> Does this match your expectations? [Y/n]"
+
+## Incremental Updates
+
+For updating existing generated code when the spec changes, use:
+
+```
+/update-from-spec <old-spec> <new-spec>
+```
+
+See `skills/update-from-spec/SKILL.md` for details.
diff --git a/plugins/openapi-to-frontend/hooks/hooks.json b/plugins/openapi-to-frontend/hooks/hooks.json
new file mode 100644
index 0000000..89cfb38
--- /dev/null
+++ b/plugins/openapi-to-frontend/hooks/hooks.json
@@ -0,0 +1,6 @@
+{
+  "$schema": "https://openhands.dev/schemas/hooks.json",
+  "version": "1.0.0",
+  "description": "Lifecycle hooks for openapi-to-frontend plugin (reserved for future use)",
+  "hooks": {}
+}
diff --git a/plugins/openapi-to-frontend/references/auth-patterns.md b/plugins/openapi-to-frontend/references/auth-patterns.md
new file mode 100644
index 0000000..fa5ede7
--- /dev/null
+++ b/plugins/openapi-to-frontend/references/auth-patterns.md
@@ -0,0 +1,629 @@
+# Auth Patterns Reference
+
+This document describes how to handle different authentication methods found in OpenAPI specs.
+
+## Detecting Auth Type
+
+Read `components/securitySchemes` in the OpenAPI spec:
+
+```yaml
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+    BearerAuth:
+      type: http
+      scheme: bearer
+    OAuth2:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.example.com/authorize
+          tokenUrl: https://auth.example.com/token
+          scopes:
+            read: Read access
+            write: Write access
+```
+
+## Pattern 1: API Key
+
+### Detection
+
+```yaml
+securitySchemes:
+  ApiKeyAuth:
+    type: apiKey
+    in: header  # or "query"
+    name: X-API-Key  # header/query param name
+```
+
+### Client Implementation
+
+```typescript
+export interface ApiKeyAuth {
+  type: 'apiKey';
+  key: string;
+  location: 'header' | 'query';
+  name: string;
+}
+
+export function attachApiKey(
+  headers: Record<string, string>,
+  url: URL,
+  auth: ApiKeyAuth
+): void {
+  if (auth.location === 'header') {
+    headers[auth.name] = auth.key;
+  } else {
+    url.searchParams.set(auth.name, auth.key);
+  }
+}
+```
+
+### Client Constructor
+
+```typescript
+const client = new ApiClient({
+  baseUrl: 'https://api.example.com',
+  auth: {
+    type: 'apiKey',
+    key: 'your-api-key',
+    location: 'header',
+    name: 'X-API-Key',
+  },
+});
+```
+
+### Frontend UI
+
+- Settings page with API key input
+- Store key in localStorage
+- No login flow required
+
+```tsx
+function ApiKeySettings() {
+  const [key, setKey] = useState(localStorage.getItem('api_key') || '');
+
+  const handleSave = () => {
+    localStorage.setItem('api_key', key);
+    // Reinitialize API client
+  };
+
+  return (
+    <div>
+      <label>API Key</label>
+      <input
+        type="password"
+        value={key}
+        onChange={(e) => setKey(e.target.value)}
+      />
+      <button onClick={handleSave}>Save</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Pattern 2: Bearer Token
+
+### Detection
+
+```yaml
+securitySchemes:
+  BearerAuth:
+    type: http
+    scheme: bearer
+    bearerFormat: JWT  # optional
+```
+
+### Client Implementation
+
+```typescript
+export interface BearerAuth {
+  type: 'bearer';
+  token: string;
+}
+
+export function attachBearer(
+  headers: Record<string, string>,
+  auth: BearerAuth
+): void {
+  headers['Authorization'] = `Bearer ${auth.token}`;
+}
+```
+
+### Client Constructor
+
+```typescript
+const client = new ApiClient({
+  baseUrl: 'https://api.example.com',
+  auth: {
+    type: 'bearer',
+    token: 'your-jwt-token',
+  },
+});
+```
+
+### Frontend UI
+
+Two approaches based on how tokens are obtained:
+
+#### Option A: Token Input
+
+If tokens are externally issued (e.g., service accounts):
+
+```tsx
+function TokenSettings() {
+  const [token, setToken] = useState('');
+
+  return (
+    <div>
+      <label>Access Token</label>
+      <textarea value={token} onChange={(e) => setToken(e.target.value)} />
+      <button onClick={() => localStorage.setItem('token', token)}>
+        Save
+      </button>
+    </div>
+  );
+}
+```
+
+#### Option B: Login Form
+
+If tokens are obtained via username/password:
+
+```tsx
+function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleSubmit = async () => {
+    const response = await fetch('/api/auth/login', {
+      method: 'POST',
+      body: JSON.stringify({ email, password }),
+    });
+    const { token } = await response.json();
+    localStorage.setItem('token', token);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} />
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Pattern 3: OAuth2
+
+### Detection
+
+```yaml
+securitySchemes:
+  OAuth2:
+    type: oauth2
+    flows:
+      authorizationCode:
+        authorizationUrl: https://auth.example.com/authorize
+        tokenUrl: https://auth.example.com/token
+        scopes:
+          read: Read access
+          write: Write access
+```
+
+### Supported Flows
+
+| Flow | Use Case |
+|------|----------|
+| `authorizationCode` | User login in browser (most common) |
+| `clientCredentials` | Server-to-server (no user) |
+| `implicit` | Legacy, avoid |
+| `password` | Legacy, avoid |
+
+### Client Implementation
+
+```typescript
+export interface OAuth2Auth {
+  type: 'oauth2';
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  token?: OAuthToken;
+}
+
+export interface OAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType: string;
+  scope?: string;
+}
+
+export class OAuth2Manager {
+  private config: OAuth2Auth;
+  private codeVerifier?: string;
+
+  constructor(config: Omit<OAuth2Auth, 'type' | 'token'>) {
+    this.config = { ...config, type: 'oauth2' };
+  }
+
+  // Generate PKCE code verifier and challenge
+  private generateCodeVerifier(): string {
+    const array = new Uint8Array(32);
+    crypto.getRandomValues(array);
+    return this.base64UrlEncode(array);
+  }
+
+  private async generateCodeChallenge(verifier: string): Promise<string> {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    const hash = await crypto.subtle.digest('SHA-256', data);
+    return this.base64UrlEncode(new Uint8Array(hash));
+  }
+
+  private base64UrlEncode(buffer: Uint8Array): string {
+    return btoa(String.fromCharCode(...buffer))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '');
+  }
+
+  // Step 1: Get authorization URL
+  async getAuthorizationUrl(state?: string): Promise<string> {
+    this.codeVerifier = this.generateCodeVerifier();
+    const codeChallenge = await this.generateCodeChallenge(this.codeVerifier);
+
+    const url = new URL(this.config.authorizationUrl);
+    url.searchParams.set('client_id', this.config.clientId);
+    url.searchParams.set('redirect_uri', this.config.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', this.config.scopes.join(' '));
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    if (state) {
+      url.searchParams.set('state', state);
+    }
+
+    // Store verifier for later
+    sessionStorage.setItem('oauth_code_verifier', this.codeVerifier);
+
+    return url.toString();
+  }
+
+  // Step 2: Exchange authorization code for token
+  async exchangeCode(code: string): Promise<OAuthToken> {
+    const codeVerifier = sessionStorage.getItem('oauth_code_verifier');
+    if (!codeVerifier) {
+      throw new Error('No code verifier found');
+    }
+
+    const response = await fetch(this.config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: this.config.clientId,
+        redirect_uri: this.config.redirectUri,
+        code,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Token exchange failed: ${response.status}`);
+    }
+
+    const data = await response.json();
+    sessionStorage.removeItem('oauth_code_verifier');
+
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+      tokenType: data.token_type,
+      scope: data.scope,
+    };
+  }
+
+  // Step 3: Refresh token
+  async refreshToken(token: OAuthToken): Promise<OAuthToken> {
+    if (!token.refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    const response = await fetch(this.config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: this.config.clientId,
+        refresh_token: token.refreshToken,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Token refresh failed: ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token || token.refreshToken,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+      tokenType: data.token_type,
+      scope: data.scope,
+    };
+  }
+
+  // Check if token is expired or expiring soon
+  isTokenExpired(token: OAuthToken, bufferMs = 60000): boolean {
+    if (!token.expiresAt) return false;
+    return token.expiresAt < Date.now() + bufferMs;
+  }
+}
+```
+
+### Frontend Implementation
+
+**AuthContext.tsx:**
+
+```tsx
+import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+import { OAuth2Manager, OAuthToken } from '../client/auth';
+
+interface AuthContextValue {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  token: OAuthToken | null;
+  login: () => void;
+  logout: () => void;
+  handleCallback: (code: string) => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+const STORAGE_KEY = 'oauth_token';
+
+const oauth2Manager = new OAuth2Manager({
+  clientId: import.meta.env.VITE_OAUTH_CLIENT_ID,
+  redirectUri: `${window.location.origin}/callback`,
+  scopes: ['read', 'write'],
+  authorizationUrl: import.meta.env.VITE_OAUTH_AUTH_URL,
+  tokenUrl: import.meta.env.VITE_OAUTH_TOKEN_URL,
+});
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [token, setToken] = useState<OAuthToken | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  // Load token from storage
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      try {
+        const parsed = JSON.parse(stored) as OAuthToken;
+        if (!oauth2Manager.isTokenExpired(parsed)) {
+          setToken(parsed);
+        } else if (parsed.refreshToken) {
+          // Try to refresh
+          oauth2Manager.refreshToken(parsed).then(setToken).catch(() => {
+            localStorage.removeItem(STORAGE_KEY);
+          });
+        }
+      } catch {
+        localStorage.removeItem(STORAGE_KEY);
+      }
+    }
+    setIsLoading(false);
+  }, []);
+
+  // Auto-refresh before expiry
+  useEffect(() => {
+    if (!token?.expiresAt || !token.refreshToken) return;
+
+    const refreshTime = token.expiresAt - Date.now() - 60000; // 1 min before
+    if (refreshTime <= 0) return;
+
+    const timeout = setTimeout(async () => {
+      try {
+        const newToken = await oauth2Manager.refreshToken(token);
+        setToken(newToken);
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(newToken));
+      } catch {
+        setToken(null);
+        localStorage.removeItem(STORAGE_KEY);
+      }
+    }, refreshTime);
+
+    return () => clearTimeout(timeout);
+  }, [token]);
+
+  const login = useCallback(async () => {
+    const state = crypto.randomUUID();
+    sessionStorage.setItem('oauth_state', state);
+    const authUrl = await oauth2Manager.getAuthorizationUrl(state);
+    window.location.href = authUrl;
+  }, []);
+
+  const logout = useCallback(() => {
+    setToken(null);
+    localStorage.removeItem(STORAGE_KEY);
+    sessionStorage.removeItem('oauth_state');
+    sessionStorage.removeItem('oauth_code_verifier');
+  }, []);
+
+  const handleCallback = useCallback(async (code: string) => {
+    setIsLoading(true);
+    try {
+      const newToken = await oauth2Manager.exchangeCode(code);
+      setToken(newToken);
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(newToken));
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  return (
+    <AuthContext.Provider
+      value={{
+        isAuthenticated: !!token,
+        isLoading,
+        token,
+        login,
+        logout,
+        handleCallback,
+      }}
+    >
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) throw new Error('useAuth must be used within AuthProvider');
+  return context;
+}
+```
+
+**CallbackPage.tsx:**
+
+```tsx
+import { useEffect } from 'react';
+import { useNavigate, useSearchParams } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+
+export function CallbackPage() {
+  const [searchParams] = useSearchParams();
+  const navigate = useNavigate();
+  const { handleCallback } = useAuth();
+
+  useEffect(() => {
+    const code = searchParams.get('code');
+    const state = searchParams.get('state');
+    const storedState = sessionStorage.getItem('oauth_state');
+
+    if (!code) {
+      navigate('/login?error=no_code');
+      return;
+    }
+
+    if (state !== storedState) {
+      navigate('/login?error=invalid_state');
+      return;
+    }
+
+    handleCallback(code)
+      .then(() => {
+        const returnTo = sessionStorage.getItem('return_to') || '/';
+        sessionStorage.removeItem('return_to');
+        navigate(returnTo);
+      })
+      .catch(() => {
+        navigate('/login?error=exchange_failed');
+      });
+  }, [searchParams, navigate, handleCallback]);
+
+  return <div>Completing sign in...</div>;
+}
+```
+
+**AuthGuard.tsx:**
+
+```tsx
+import { Navigate, useLocation } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+import { LoadingSpinner } from '../components/shared';
+
+export function AuthGuard({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return <LoadingSpinner />;
+  }
+
+  if (!isAuthenticated) {
+    sessionStorage.setItem('return_to', location.pathname);
+    return <Navigate to="/login" replace />;
+  }
+
+  return <>{children}</>;
+}
+```
+
+---
+
+## Multiple Auth Methods
+
+If the spec defines multiple auth methods:
+
+```yaml
+securitySchemes:
+  ApiKeyAuth:
+    type: apiKey
+    in: header
+    name: X-API-Key
+  BearerAuth:
+    type: http
+    scheme: bearer
+```
+
+Generate a union type:
+
+```typescript
+export type AuthConfig =
+  | { type: 'apiKey'; key: string; location: 'header' | 'query'; name: string }
+  | { type: 'bearer'; token: string }
+  | { type: 'none' };
+
+export function attachAuth(
+  headers: Record<string, string>,
+  url: URL,
+  auth: AuthConfig
+): void {
+  switch (auth.type) {
+    case 'apiKey':
+      if (auth.location === 'header') {
+        headers[auth.name] = auth.key;
+      } else {
+        url.searchParams.set(auth.name, auth.key);
+      }
+      break;
+    case 'bearer':
+      headers['Authorization'] = `Bearer ${auth.token}`;
+      break;
+    case 'none':
+      break;
+  }
+}
+```
+
+---
+
+## Security Best Practices
+
+1. **Never store tokens in URL params** — Use localStorage or sessionStorage
+2. **Use PKCE for OAuth2** — Required for SPAs
+3. **Validate state parameter** — Prevent CSRF attacks
+4. **Refresh before expiry** — Don't wait for 401
+5. **Clear tokens on logout** — Remove from all storage
+6. **Use HttpOnly cookies when possible** — For better security (requires backend support)
diff --git a/plugins/openapi-to-frontend/references/change-taxonomy.md b/plugins/openapi-to-frontend/references/change-taxonomy.md
new file mode 100644
index 0000000..99d1071
--- /dev/null
+++ b/plugins/openapi-to-frontend/references/change-taxonomy.md
@@ -0,0 +1,577 @@
+# Change Taxonomy Reference
+
+This document enumerates all change types detected by the spec-differ agent and how each should be handled by the update-from-spec skill.
+
+## Change Types Overview
+
+| Category | Change Types |
+|----------|--------------|
+| Schema | added, removed, renamed |
+| Field | added, removed, type_changed, required_changed |
+| Endpoint | added, removed |
+| Parameter | added, removed, type_changed, location_changed |
+| Response | type_changed, code_added, code_removed |
+| Auth | scheme_added, scheme_removed, scheme_modified |
+| Enum | values_added, values_removed, values_reordered |
+| Metadata | info_changed, server_changed, tag_changed |
+
+---
+
+## Schema Changes
+
+### schema_added
+
+**When:** New schema appears in `components/schemas`
+
+**Impact:**
+- Client: Add interface to types.ts, add methods to api.ts if endpoints exist
+- Components: Add component directory with Form/Detail/List
+- Frontend: Add page and route if it's a primary resource
+- Tests: Add factory, type guard, component tests
+
+**Actions:**
+
+```
+1. types.ts: Add interface
+   export interface NewSchema { ... }
+
+2. api.ts: Add methods (if endpoints exist)
+   async listNewSchemas(): Promise<...>
+   async getNewSchema(id: string): Promise<...>
+
+3. components/NewSchema/: Create directory
+   - NewSchemaForm.tsx
+   - NewSchemaDetail.tsx
+   - NewSchemaList.tsx
+   - index.ts
+
+4. components/index.ts: Add export
+   export * from './NewSchema';
+
+5. app/pages/: Add page (if primary resource)
+   NewSchemasPage.tsx
+
+6. app/App.tsx: Add routes
+
+7. app/Layout.tsx: Add nav item
+
+8. tests/setup/factories.ts: Add makeNewSchema()
+
+9. tests/unit/components/: Add test files
+```
+
+---
+
+### schema_removed
+
+**When:** Schema no longer exists in `components/schemas`
+
+**Impact:**
+- Client: Remove interface, remove methods, remove imports
+- Components: Remove entire directory
+- Frontend: Remove page, route, navigation
+- Tests: Remove factories, guards, tests
+
+**Actions:**
+
+```
+1. types.ts: Remove interface
+   - Delete interface definition
+   - Remove from any union types
+   - Remove related enums
+
+2. api.ts: Remove methods
+   - Delete methods using this type
+   - Update imports
+
+3. components/SchemaName/: Delete directory
+   rm -rf components/SchemaName/
+
+4. components/index.ts: Remove export
+
+5. app/pages/: Delete page
+   rm app/pages/SchemaNamesPage.tsx
+   rm app/pages/SchemaNameDetailPage.tsx
+   rm app/pages/SchemaNameFormPage.tsx
+
+6. app/App.tsx: Remove routes
+
+7. app/Layout.tsx: Remove nav item
+
+8. tests/: Remove all related test files
+```
+
+**Breaking Change:** Yes — warn user before applying
+
+---
+
+### schema_renamed
+
+**When:** Schema name changed but fields are similar (>80% match)
+
+**Impact:** Same as remove + add, but preserve user customizations
+
+**Actions:**
+
+```
+1. types.ts: Rename interface
+   - Find: interface OldName
+   - Replace: interface NewName
+
+2. Update all imports and usages
+
+3. Rename component directory
+   mv components/OldName/ components/NewName/
+
+4. Rename component files
+   mv OldNameForm.tsx NewNameForm.tsx
+   
+5. Update component names inside files
+
+6. Update routes and navigation
+```
+
+---
+
+## Field Changes
+
+### field_added
+
+**When:** New property added to schema
+
+**Impact:**
+- Client: Add to interface
+- Components: Add to Form, Detail, List
+- Tests: Update factories
+
+**Actions:**
+
+```
+1. types.ts: Add field to interface
+   export interface User {
+     // existing fields...
+     newField?: string;  // ADD
+   }
+
+2. UserForm.tsx: Add input
+   <div>
+     <label>New Field</label>
+     <input name="newField" ... />
+   </div>
+
+3. UserDetail.tsx: Add display
+   <div>
+     <dt>New Field</dt>
+     <dd>{user.newField}</dd>
+   </div>
+
+4. UserList.tsx: Add column (if important)
+   <th>New Field</th>
+   <td>{user.newField}</td>
+
+5. factories.ts: Add to factory
+   export function makeUser(overrides = {}) {
+     return {
+       ...existing,
+       newField: null,  // ADD
+       ...overrides
+     };
+   }
+```
+
+---
+
+### field_removed
+
+**When:** Property deleted from schema
+
+**Impact:**
+- Client: Remove from interface
+- Components: Remove from Form, Detail, List
+- Tests: Update factories and assertions
+
+**Actions:**
+
+```
+1. types.ts: Remove field from interface
+
+2. Form: Remove input and label
+
+3. Detail: Remove display row
+
+4. List: Remove column
+
+5. factories.ts: Remove from factory
+
+6. Existing tests: Remove assertions on this field
+```
+
+**Breaking Change:** Yes if field was required
+
+---
+
+### field_type_changed
+
+**When:** Property type changed
+
+**Examples:**
+- `string` → `number`
+- `string` → `enum`
+- `string` → `$ref`
+
+**Impact:**
+- Client: Update type
+- Components: Update input component
+
+**Actions:**
+
+```
+1. types.ts: Update field type
+   // Before: status: string;
+   // After:  status: OrderStatus;
+
+2. Form: Update input type
+   // Before: <input type="text" ...>
+   // After:  <select>...</select>
+
+3. factories.ts: Update mock value
+
+4. Tests: Update assertions
+```
+
+---
+
+### field_required_changed
+
+**When:** Field moved in/out of `required` array
+
+**Impact:**
+- Client: Add/remove `?` from field
+- Components: Add/remove required validation
+
+**Actions:**
+
+```
+1. types.ts:
+   // Now required: field: string;
+   // Now optional: field?: string;
+
+2. Form: Update required attribute
+   <input required={true/false} ...>
+
+3. Validation: Update schema/logic
+```
+
+---
+
+## Endpoint Changes
+
+### endpoint_added
+
+**When:** New path+method combination
+
+**Impact:**
+- Client: Add method
+- Components: Add functionality if creates new capability
+- Frontend: Add route if new resource
+
+**Actions:**
+
+```
+1. api.ts: Add method
+   async newEndpoint(...): Promise<...> {
+     return this.request('METHOD', '/path', ...);
+   }
+
+2. types.ts: Add params/response types if needed
+
+3. Components:
+   - GET list → Add List component
+   - GET single → Add Detail component
+   - POST → Add Form component
+   - DELETE → Add delete button
+   - Custom action → Add action button
+
+4. Frontend: Add page/route if new resource
+```
+
+---
+
+### endpoint_removed
+
+**When:** Path+method no longer exists
+
+**Impact:**
+- Client: Remove method
+- Components: Disable/hide functionality
+- Frontend: Remove route if resource deleted
+
+**Actions:**
+
+```
+1. api.ts: Remove method
+
+2. Components:
+   - List endpoint removed → Hide/disable list
+   - Detail endpoint removed → Hide/disable detail view
+   - Create endpoint removed → Hide create button
+   - Delete endpoint removed → Hide delete button
+
+3. Frontend: Remove route if applicable
+
+4. Tests: Remove related tests
+```
+
+**Breaking Change:** Yes — warn user
+
+---
+
+## Parameter Changes
+
+### param_added
+
+**When:** New parameter added to endpoint
+
+**Impact:**
+- Client: Update method signature
+- Components: Add filter/input for new param
+
+**Actions:**
+
+```
+1. api.ts: Add to params type
+   interface ListUsersParams {
+     existing: string;
+     newParam?: string;  // ADD
+   }
+
+2. Components: Add UI for new param
+   - Query param → Add filter/search input
+   - Path param → Usually affects route
+   - Body param → Add form field
+```
+
+---
+
+### param_removed
+
+**When:** Parameter removed from endpoint
+
+**Actions:**
+
+```
+1. api.ts: Remove from params type
+
+2. Components: Remove filter/input
+```
+
+---
+
+### param_type_changed
+
+**When:** Parameter type changed
+
+**Actions:**
+
+```
+1. api.ts: Update param type
+
+2. Components: Update input type
+```
+
+---
+
+## Response Changes
+
+### response_type_changed
+
+**When:** Response schema changed
+
+**Actions:**
+
+```
+1. api.ts: Update return type
+
+2. types.ts: Update response interface
+
+3. Components: Update rendering
+```
+
+---
+
+### response_code_added
+
+**When:** New response code added (e.g., 400, 404)
+
+**Actions:**
+
+```
+1. Consider adding error handling for new code
+
+2. Components: Handle new error case
+```
+
+---
+
+## Auth Changes
+
+### auth_scheme_added
+
+**When:** New security scheme in securitySchemes
+
+**Impact:**
+- Client: Add auth handler
+- Frontend: Add login flow if first auth
+
+**Actions:**
+
+```
+1. auth.ts: Add handler type and function
+   export interface NewAuth { type: 'new'; ... }
+   
+2. api.ts: Update attachAuth
+
+3. Frontend (if first auth):
+   - Add AuthContext
+   - Add AuthGuard
+   - Add LoginPage
+   - Add callback route (if OAuth)
+```
+
+---
+
+### auth_scheme_removed
+
+**When:** Security scheme removed
+
+**Actions:**
+
+```
+1. auth.ts: Remove handler
+
+2. Frontend (if last auth):
+   - Remove login flow
+   - Remove guards
+```
+
+---
+
+### auth_scheme_modified
+
+**When:** Scheme configuration changed
+
+**Examples:**
+- OAuth URLs changed
+- Scopes changed
+- Header name changed
+
+**Actions:**
+
+```
+1. auth.ts: Update configuration
+
+2. Frontend: Update OAuth config
+```
+
+---
+
+## Enum Changes
+
+### enum_values_added
+
+**When:** New values added to enum
+
+**Actions:**
+
+```
+1. types.ts: Add values
+   type Status = 'a' | 'b' | 'c';  // added 'c'
+
+2. Components: Add option
+   <option value="c">C</option>
+```
+
+---
+
+### enum_values_removed
+
+**When:** Values removed from enum
+
+**Actions:**
+
+```
+1. types.ts: Remove values
+
+2. Components: Remove option
+```
+
+**Breaking Change:** Yes — data may have removed values
+
+---
+
+## Metadata Changes
+
+### info_changed
+
+**When:** API info (title, description, version) changed
+
+**Impact:** Usually none — consider updating UI titles
+
+---
+
+### server_changed
+
+**When:** Server URLs changed
+
+**Impact:** Update base URL configuration
+
+---
+
+### tag_changed
+
+**When:** Tags added/removed/modified
+
+**Impact:** Update navigation grouping
+
+---
+
+## Change Severity
+
+| Severity | Description | Action |
+|----------|-------------|--------|
+| **None** | Metadata only | Auto-apply |
+| **Low** | Additive change | Auto-apply, notify |
+| **Medium** | Non-breaking modification | Apply with review |
+| **High** | Breaking change | Warn, require confirmation |
+
+### High Severity (Breaking)
+
+- schema_removed
+- field_removed (required)
+- endpoint_removed
+- param_added (required)
+- field_type_changed (incompatible)
+- enum_values_removed
+- auth_scheme_removed
+
+### Medium Severity
+
+- field_type_changed (compatible)
+- param_removed
+- response_type_changed
+- auth_scheme_modified
+
+### Low Severity
+
+- schema_added
+- field_added
+- endpoint_added
+- param_added (optional)
+- enum_values_added
+
+### None
+
+- info_changed
+- description_changed
+- server_changed
+- tag_changed
diff --git a/plugins/openapi-to-frontend/references/naming-conventions.md b/plugins/openapi-to-frontend/references/naming-conventions.md
new file mode 100644
index 0000000..03eef8e
--- /dev/null
+++ b/plugins/openapi-to-frontend/references/naming-conventions.md
@@ -0,0 +1,311 @@
+# Naming Conventions Reference
+
+This document defines how names are transformed from OpenAPI spec to TypeScript to React components.
+
+## Overview
+
+| Layer | Naming Style | Example |
+|-------|--------------|---------|
+| OpenAPI Schema | PascalCase | `UserProfile` |
+| TypeScript Interface | PascalCase | `interface UserProfile` |
+| TypeScript Field | camelCase | `firstName: string` |
+| React Component | PascalCase + Suffix | `UserProfileForm` |
+| React Prop | camelCase | `onUserSelect` |
+| CSS Class | kebab-case | `user-profile-form` |
+| File Name | PascalCase.tsx | `UserProfileForm.tsx` |
+| Directory | PascalCase | `UserProfile/` |
+
+---
+
+## Schema → TypeScript Interface
+
+### Schema Name
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| `UserProfile` | `interface UserProfile` |
+| `user_profile` | `interface UserProfile` |
+| `User-Profile` | `interface UserProfile` |
+
+**Rule:** Convert to PascalCase
+
+### Field Name
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| `first_name` | `firstName` |
+| `firstName` | `firstName` |
+| `FIRST_NAME` | `firstName` |
+| `FirstName` | `firstName` |
+
+**Rule:** Convert to camelCase
+
+### Type Mapping
+
+| OpenAPI Type | OpenAPI Format | TypeScript |
+|--------------|----------------|------------|
+| `string` | — | `string` |
+| `string` | `date` | `string` (YYYY-MM-DD) |
+| `string` | `date-time` | `string` (ISO 8601) |
+| `string` | `email` | `string` |
+| `string` | `uri` | `string` |
+| `string` | `uuid` | `string` |
+| `string` | `binary` | `Blob` |
+| `string` | `byte` | `string` (base64) |
+| `integer` | — | `number` |
+| `integer` | `int32` | `number` |
+| `integer` | `int64` | `number` |
+| `number` | — | `number` |
+| `number` | `float` | `number` |
+| `number` | `double` | `number` |
+| `boolean` | — | `boolean` |
+| `array` | — | `T[]` |
+| `object` | — | Interface or `Record<string, unknown>` |
+| `null` | — | `null` |
+
+### Enum Mapping
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| `enum: ['active', 'inactive']` | `type Status = 'active' \| 'inactive'` |
+| Named enum with many values | `enum Status { Active = 'active', ... }` |
+
+### Nullable Fields
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| `nullable: true` | `T \| null` |
+| `x-nullable: true` | `T \| null` |
+
+### Optional Fields
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| Not in `required` | `field?: T` |
+| In `required` | `field: T` |
+
+---
+
+## Endpoint → API Method
+
+### Method Name
+
+| HTTP Method | Path | Method Name |
+|-------------|------|-------------|
+| GET | `/users` | `listUsers()` |
+| GET | `/users/{id}` | `getUser(id)` |
+| POST | `/users` | `createUser(data)` |
+| PUT | `/users/{id}` | `updateUser(id, data)` |
+| PATCH | `/users/{id}` | `patchUser(id, data)` |
+| DELETE | `/users/{id}` | `deleteUser(id)` |
+| GET | `/users/{userId}/posts` | `listUserPosts(userId)` |
+| POST | `/users/{id}/activate` | `activateUser(id)` |
+| GET | `/search` | `search(params)` |
+
+### Naming Algorithm
+
+1. Start with HTTP method:
+   - GET (list) → `list`
+   - GET (single) → `get`
+   - POST → `create` or action verb
+   - PUT → `update`
+   - PATCH → `patch`
+   - DELETE → `delete`
+
+2. Add resource name (singular for single, plural for list):
+   - `/users` → `Users`
+   - `/users/{id}` → `User`
+
+3. For nested resources, include parent:
+   - `/users/{userId}/posts` → `UserPosts`
+
+4. For actions, use the action verb:
+   - `/users/{id}/activate` → `activateUser`
+   - `/orders/{id}/cancel` → `cancelOrder`
+
+5. If operationId is defined, prefer it (convert to camelCase):
+   - `operationId: listAllActiveUsers` → `listAllActiveUsers()`
+
+### Parameter Types
+
+| Parameter Location | TypeScript |
+|--------------------|------------|
+| Path `{id}` | Method argument: `id: string` |
+| Query `?page=1` | Optional params object: `params?: { page?: number }` |
+| Header | Handled internally or config |
+| Body | Data argument: `data: CreateUserRequest` |
+
+### Return Type
+
+| Response | TypeScript |
+|----------|------------|
+| `200` with schema | `Promise<ResponseType>` |
+| `201` with schema | `Promise<ResponseType>` |
+| `204` no content | `Promise<void>` |
+| List response | `Promise<ListResponse<T>>` |
+
+---
+
+## Schema → React Component
+
+### Component Names
+
+| Schema | Form | Detail | List |
+|--------|------|--------|------|
+| `User` | `UserForm` | `UserDetail` | `UserList` |
+| `UserProfile` | `UserProfileForm` | `UserProfileDetail` | `UserProfileList` |
+| `OrderItem` | `OrderItemForm` | `OrderItemDetail` | `OrderItemList` |
+
+### File Names
+
+```
+components/
+├── User/
+│   ├── UserForm.tsx
+│   ├── UserDetail.tsx
+│   ├── UserList.tsx
+│   └── index.ts
+├── UserProfile/
+│   ├── UserProfileForm.tsx
+│   ├── UserProfileDetail.tsx
+│   ├── UserProfileList.tsx
+│   └── index.ts
+```
+
+### Prop Names
+
+| Purpose | Prop Name |
+|---------|-----------|
+| Entity data | `user`, `userProfile`, `order` |
+| Entity ID | `userId`, `userProfileId`, `orderId` |
+| Selection handler | `onSelect`, `onUserSelect` |
+| Success handler | `onSuccess` |
+| Cancel handler | `onCancel` |
+| Delete handler | `onDelete` |
+| Loading state | `loading`, `isLoading` |
+| Error state | `error` |
+| CSS class | `className` |
+
+---
+
+## Field → UI Label
+
+| TypeScript Field | UI Label |
+|------------------|----------|
+| `firstName` | "First Name" |
+| `lastName` | "Last Name" |
+| `emailAddress` | "Email Address" |
+| `createdAt` | "Created At" |
+| `isActive` | "Is Active" or "Active" |
+| `userId` | "User ID" |
+| `httpStatus` | "HTTP Status" |
+
+### Label Algorithm
+
+1. Split camelCase into words
+2. Capitalize each word
+3. Handle common abbreviations (ID, HTTP, URL, API)
+
+```typescript
+function toLabel(field: string): string {
+  return field
+    // Insert space before capitals
+    .replace(/([A-Z])/g, ' $1')
+    // Handle ID specially
+    .replace(/\bId\b/g, 'ID')
+    // Trim and capitalize
+    .trim()
+    .replace(/^\w/, c => c.toUpperCase());
+}
+```
+
+---
+
+## Field → Input Type
+
+| Field Type | Field Name Pattern | Input Type |
+|------------|-------------------|------------|
+| `string` | — | `<input type="text">` |
+| `string` | `email`, `*Email` | `<input type="email">` |
+| `string` | `password`, `*Password` | `<input type="password">` |
+| `string` | `url`, `*Url`, `*Link` | `<input type="url">` |
+| `string` | `phone`, `*Phone` | `<input type="tel">` |
+| `string` (format: date) | — | `<input type="date">` |
+| `string` (format: date-time) | — | `<input type="datetime-local">` |
+| `string` (format: time) | — | `<input type="time">` |
+| `string` (long text) | `description`, `*Description`, `bio`, `*Content` | `<textarea>` |
+| `number` / `integer` | — | `<input type="number">` |
+| `boolean` | — | `<input type="checkbox">` |
+| enum / union | — | `<select>` |
+| `array` | — | Repeatable group |
+| `$ref` | — | Nested form or select |
+
+---
+
+## Route Paths
+
+| Resource | Route |
+|----------|-------|
+| User list | `/users` |
+| User detail | `/users/:id` |
+| User create | `/users/new` |
+| User edit | `/users/:id/edit` |
+| Nested resource | `/users/:userId/posts` |
+
+---
+
+## Barrel Exports
+
+**components/User/index.ts:**
+
+```typescript
+export { UserForm } from './UserForm';
+export type { UserFormProps } from './UserForm';
+export { UserDetail } from './UserDetail';
+export type { UserDetailProps } from './UserDetail';
+export { UserList } from './UserList';
+export type { UserListProps } from './UserList';
+```
+
+**components/index.ts:**
+
+```typescript
+export * from './User';
+export * from './UserProfile';
+export * from './Order';
+export * from './shared';
+```
+
+---
+
+## Special Cases
+
+### Acronyms
+
+| OpenAPI | TypeScript | React |
+|---------|------------|-------|
+| `URL` | `url: string` | Label: "URL" |
+| `HTTP` | `http: string` | Label: "HTTP" |
+| `API` | `api: string` | Label: "API" |
+| `APIKey` | `apiKey: string` | Label: "API Key" |
+| `HTMLContent` | `htmlContent: string` | Label: "HTML Content" |
+
+### Plural/Singular
+
+| OpenAPI | Context | TypeScript |
+|---------|---------|------------|
+| `User` | Single entity | `User` |
+| `User` | Array | `User[]` |
+| `users` | Field name | `users: User[]` |
+| `Users` | Don't use as schema name | — |
+
+### Reserved Words
+
+If a field name conflicts with TypeScript reserved words, escape or rename:
+
+| OpenAPI | TypeScript |
+|---------|------------|
+| `class` | `_class` or `classValue` |
+| `function` | `_function` or `functionName` |
+| `type` | `_type` or `typeValue` |
+| `default` | `_default` or `defaultValue` |
diff --git a/plugins/openapi-to-frontend/scripts/lint-generated.sh b/plugins/openapi-to-frontend/scripts/lint-generated.sh
new file mode 100755
index 0000000..bba891c
--- /dev/null
+++ b/plugins/openapi-to-frontend/scripts/lint-generated.sh
@@ -0,0 +1,105 @@
+#!/bin/bash
+#
+# Lint generated code to ensure quality and type correctness.
+#
+# Usage:
+#   ./lint-generated.sh [directory]
+#
+# Runs:
+#   - ESLint for code style and potential issues
+#   - TypeScript compiler in no-emit mode for type checking
+#
+# Exit codes:
+#   0 - All checks passed
+#   1 - One or more checks failed
+#
+
+set -u
+
+# Default directory to lint
+TARGET_DIR="${1:-.}"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo "🔍 Linting generated code in: $TARGET_DIR"
+echo ""
+
+FAILED=0
+
+# Check for package.json
+if [[ ! -f "package.json" ]]; then
+    echo -e "${YELLOW}Warning: No package.json found. Running checks anyway...${NC}"
+fi
+
+# Run ESLint
+echo "📝 Running ESLint..."
+if command -v npx &> /dev/null; then
+    if npx eslint "$TARGET_DIR" --ext .ts,.tsx --max-warnings 0 2>/dev/null; then
+        echo -e "${GREEN}✓ ESLint passed${NC}"
+    else
+        # Check if eslint is configured
+        if [[ -f ".eslintrc" ]] || [[ -f ".eslintrc.js" ]] || [[ -f ".eslintrc.json" ]] || [[ -f "eslint.config.js" ]]; then
+            echo -e "${RED}✗ ESLint found issues${NC}"
+            FAILED=1
+        else
+            echo -e "${YELLOW}⚠ ESLint not configured, skipping${NC}"
+        fi
+    fi
+else
+    echo -e "${YELLOW}⚠ npx not found, skipping ESLint${NC}"
+fi
+
+echo ""
+
+# Run TypeScript type check
+echo "🔷 Running TypeScript type check..."
+if command -v npx &> /dev/null; then
+    if [[ -f "tsconfig.json" ]]; then
+        if npx tsc --noEmit 2>&1; then
+            echo -e "${GREEN}✓ TypeScript check passed${NC}"
+        else
+            echo -e "${RED}✗ TypeScript found type errors${NC}"
+            FAILED=1
+        fi
+    else
+        echo -e "${YELLOW}⚠ No tsconfig.json found, skipping TypeScript check${NC}"
+    fi
+else
+    echo -e "${YELLOW}⚠ npx not found, skipping TypeScript check${NC}"
+fi
+
+echo ""
+
+# Run Prettier check (if configured)
+echo "🎨 Checking formatting with Prettier..."
+if command -v npx &> /dev/null; then
+    if [[ -f ".prettierrc" ]] || [[ -f ".prettierrc.js" ]] || [[ -f ".prettierrc.json" ]] || [[ -f "prettier.config.js" ]]; then
+        if npx prettier --check "$TARGET_DIR/**/*.{ts,tsx}" 2>/dev/null; then
+            echo -e "${GREEN}✓ Prettier check passed${NC}"
+        else
+            echo -e "${YELLOW}⚠ Formatting issues found (run 'npx prettier --write' to fix)${NC}"
+            # Don't fail on formatting, just warn
+        fi
+    else
+        echo -e "${YELLOW}⚠ Prettier not configured, skipping${NC}"
+    fi
+fi
+
+echo ""
+
+# Summary
+if [[ $FAILED -eq 0 ]]; then
+    echo -e "${GREEN}═══════════════════════════════════════${NC}"
+    echo -e "${GREEN}✓ All lint checks passed!${NC}"
+    echo -e "${GREEN}═══════════════════════════════════════${NC}"
+    exit 0
+else
+    echo -e "${RED}═══════════════════════════════════════${NC}"
+    echo -e "${RED}✗ Some lint checks failed${NC}"
+    echo -e "${RED}═══════════════════════════════════════${NC}"
+    exit 1
+fi
diff --git a/plugins/openapi-to-frontend/scripts/parse-openapi.py b/plugins/openapi-to-frontend/scripts/parse-openapi.py
new file mode 100755
index 0000000..c86da9f
--- /dev/null
+++ b/plugins/openapi-to-frontend/scripts/parse-openapi.py
@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""
+Parse an OpenAPI spec and output a structured JSON summary.
+
+This script extracts all schemas, endpoints, and auth schemes from an OpenAPI
+specification file (JSON or YAML) and outputs a normalized JSON structure
+that can be consumed by the generation skills.
+
+Usage:
+    python parse-openapi.py <spec-file> [--output <output-file>]
+
+Example:
+    python parse-openapi.py openapi.yaml > spec-summary.json
+    python parse-openapi.py openapi.json --output summary.json
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    """Load an OpenAPI spec from a JSON or YAML file."""
+    content = path.read_text()
+    
+    if path.suffix in ('.yaml', '.yml'):
+        if yaml is None:
+            print("Error: PyYAML is required for YAML files. Install with: pip install pyyaml", file=sys.stderr)
+            sys.exit(1)
+        return yaml.safe_load(content)
+    else:
+        return json.loads(content)
+
+
+def resolve_ref(spec: dict[str, Any], ref: str) -> dict[str, Any]:
+    """Resolve a $ref to its definition."""
+    if not ref.startswith('#/'):
+        return {'type': 'external', 'ref': ref}
+    
+    parts = ref[2:].split('/')
+    current = spec
+    for part in parts:
+        current = current.get(part, {})
+    return current
+
+
+def parse_type(spec: dict[str, Any], schema: dict[str, Any]) -> dict[str, Any]:
+    """Parse a schema type into a normalized format."""
+    if '$ref' in schema:
+        ref = schema['$ref']
+        ref_name = ref.split('/')[-1]
+        return {'type': 'ref', 'ref': ref_name}
+    
+    schema_type = schema.get('type', 'object')
+    result: dict[str, Any] = {'type': schema_type}
+    
+    if 'format' in schema:
+        result['format'] = schema['format']
+    
+    if 'enum' in schema:
+        result['enum'] = schema['enum']
+    
+    if 'nullable' in schema or schema.get('x-nullable'):
+        result['nullable'] = True
+    
+    if schema_type == 'array':
+        items = schema.get('items', {})
+        result['items'] = parse_type(spec, items)
+    
+    if schema_type == 'object':
+        if 'properties' in schema:
+            result['properties'] = {}
+            for name, prop in schema.get('properties', {}).items():
+                result['properties'][name] = parse_type(spec, prop)
+        if 'additionalProperties' in schema:
+            result['additionalProperties'] = parse_type(spec, schema['additionalProperties'])
+    
+    if 'oneOf' in schema:
+        result['oneOf'] = [parse_type(spec, s) for s in schema['oneOf']]
+    
+    if 'anyOf' in schema:
+        result['anyOf'] = [parse_type(spec, s) for s in schema['anyOf']]
+    
+    if 'allOf' in schema:
+        result['allOf'] = [parse_type(spec, s) for s in schema['allOf']]
+    
+    return result
+
+
+def parse_schemas(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all schemas from the spec."""
+    schemas = []
+    components = spec.get('components', {})
+    
+    for name, schema in components.get('schemas', {}).items():
+        parsed = {
+            'name': name,
+            'description': schema.get('description', ''),
+            'type': schema.get('type', 'object'),
+            'required': schema.get('required', []),
+            'fields': [],
+        }
+        
+        for field_name, field_schema in schema.get('properties', {}).items():
+            field = {
+                'name': field_name,
+                'required': field_name in parsed['required'],
+                **parse_type(spec, field_schema),
+            }
+            if 'description' in field_schema:
+                field['description'] = field_schema['description']
+            parsed['fields'].append(field)
+        
+        if 'enum' in schema:
+            parsed['enum'] = schema['enum']
+        
+        schemas.append(parsed)
+    
+    return schemas
+
+
+def parse_parameter(spec: dict[str, Any], param: dict[str, Any]) -> dict[str, Any]:
+    """Parse an endpoint parameter."""
+    if '$ref' in param:
+        param = resolve_ref(spec, param['$ref'])
+    
+    schema = param.get('schema', {})
+    return {
+        'name': param.get('name', ''),
+        'in': param.get('in', 'query'),
+        'required': param.get('required', False),
+        'description': param.get('description', ''),
+        **parse_type(spec, schema),
+    }
+
+
+def parse_request_body(spec: dict[str, Any], body: dict[str, Any]) -> dict[str, Any] | None:
+    """Parse a request body."""
+    if not body:
+        return None
+    
+    if '$ref' in body:
+        body = resolve_ref(spec, body['$ref'])
+    
+    content = body.get('content', {})
+    json_content = content.get('application/json', {})
+    schema = json_content.get('schema', {})
+    
+    if not schema:
+        return None
+    
+    return {
+        'required': body.get('required', False),
+        **parse_type(spec, schema),
+    }
+
+
+def parse_response(spec: dict[str, Any], code: str, response: dict[str, Any]) -> dict[str, Any]:
+    """Parse a response definition."""
+    if '$ref' in response:
+        response = resolve_ref(spec, response['$ref'])
+    
+    result = {
+        'code': code,
+        'description': response.get('description', ''),
+    }
+    
+    content = response.get('content', {})
+    json_content = content.get('application/json', {})
+    schema = json_content.get('schema', {})
+    
+    if schema:
+        result['schema'] = parse_type(spec, schema)
+    
+    return result
+
+
+def parse_endpoints(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all endpoints from the spec."""
+    endpoints = []
+    
+    for path, path_item in spec.get('paths', {}).items():
+        # Handle path-level parameters
+        path_params = path_item.get('parameters', [])
+        
+        for method in ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']:
+            if method not in path_item:
+                continue
+            
+            operation = path_item[method]
+            
+            # Merge path and operation parameters
+            all_params = path_params + operation.get('parameters', [])
+            
+            endpoint = {
+                'path': path,
+                'method': method.upper(),
+                'operationId': operation.get('operationId', ''),
+                'summary': operation.get('summary', ''),
+                'description': operation.get('description', ''),
+                'tags': operation.get('tags', []),
+                'parameters': [parse_parameter(spec, p) for p in all_params],
+                'requestBody': parse_request_body(spec, operation.get('requestBody', {})),
+                'responses': [],
+                'security': operation.get('security', spec.get('security', [])),
+            }
+            
+            for code, response in operation.get('responses', {}).items():
+                endpoint['responses'].append(parse_response(spec, code, response))
+            
+            endpoints.append(endpoint)
+    
+    return endpoints
+
+
+def parse_auth_schemes(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all security schemes from the spec."""
+    schemes = []
+    components = spec.get('components', {})
+    
+    for name, scheme in components.get('securitySchemes', {}).items():
+        parsed = {
+            'name': name,
+            'type': scheme.get('type', ''),
+            'description': scheme.get('description', ''),
+        }
+        
+        if scheme['type'] == 'apiKey':
+            parsed['in'] = scheme.get('in', 'header')
+            parsed['paramName'] = scheme.get('name', '')
+        
+        elif scheme['type'] == 'http':
+            parsed['scheme'] = scheme.get('scheme', '')
+            if 'bearerFormat' in scheme:
+                parsed['bearerFormat'] = scheme['bearerFormat']
+        
+        elif scheme['type'] == 'oauth2':
+            parsed['flows'] = {}
+            for flow_name, flow in scheme.get('flows', {}).items():
+                flow_data = {'scopes': flow.get('scopes', {})}
+                if 'authorizationUrl' in flow:
+                    flow_data['authorizationUrl'] = flow['authorizationUrl']
+                if 'tokenUrl' in flow:
+                    flow_data['tokenUrl'] = flow['tokenUrl']
+                if 'refreshUrl' in flow:
+                    flow_data['refreshUrl'] = flow['refreshUrl']
+                parsed['flows'][flow_name] = flow_data
+        
+        elif scheme['type'] == 'openIdConnect':
+            parsed['openIdConnectUrl'] = scheme.get('openIdConnectUrl', '')
+        
+        schemes.append(parsed)
+    
+    return schemes
+
+
+def parse_spec(spec: dict[str, Any]) -> dict[str, Any]:
+    """Parse an entire OpenAPI spec into a normalized structure."""
+    info = spec.get('info', {})
+    
+    return {
+        'openapi': spec.get('openapi', spec.get('swagger', '')),
+        'info': {
+            'title': info.get('title', ''),
+            'version': info.get('version', ''),
+            'description': info.get('description', ''),
+        },
+        'servers': spec.get('servers', []),
+        'tags': spec.get('tags', []),
+        'schemas': parse_schemas(spec),
+        'endpoints': parse_endpoints(spec),
+        'authSchemes': parse_auth_schemes(spec),
+        'globalSecurity': spec.get('security', []),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Parse an OpenAPI spec and output a structured JSON summary.'
+    )
+    parser.add_argument('spec_file', type=Path, help='Path to the OpenAPI spec file')
+    parser.add_argument('--output', '-o', type=Path, help='Output file (default: stdout)')
+    parser.add_argument('--pretty', '-p', action='store_true', help='Pretty-print JSON output')
+    
+    args = parser.parse_args()
+    
+    if not args.spec_file.exists():
+        print(f"Error: File not found: {args.spec_file}", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        spec = load_spec(args.spec_file)
+    except Exception as e:
+        print(f"Error loading spec: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        result = parse_spec(spec)
+    except Exception as e:
+        print(f"Error parsing spec: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    indent = 2 if args.pretty else None
+    output = json.dumps(result, indent=indent)
+    
+    if args.output:
+        args.output.write_text(output)
+        print(f"Output written to {args.output}", file=sys.stderr)
+    else:
+        print(output)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/plugins/openapi-to-frontend/scripts/verify-components.py b/plugins/openapi-to-frontend/scripts/verify-components.py
new file mode 100755
index 0000000..e81a4a7
--- /dev/null
+++ b/plugins/openapi-to-frontend/scripts/verify-components.py
@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""
+Verify that React components exist for all TypeScript client types.
+
+This script cross-references the TypeScript client against the generated React
+components to ensure each schema has appropriate Form, Detail, and List components.
+
+Usage:
+    python verify-components.py <client-dir> <components-dir>
+
+Example:
+    python verify-components.py client/ components/
+
+Exit codes:
+    0 - All expected components exist
+    1 - Missing components detected
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def extract_schema_types(types_file: Path) -> dict[str, dict]:
+    """
+    Extract interface definitions from types.ts and categorize them.
+    
+    Returns a dict mapping schema names to their info:
+    {
+        'User': {
+            'fields': ['id', 'email', ...],
+            'is_request': False,
+            'is_response': False,
+        }
+    }
+    """
+    if not types_file.exists():
+        return {}
+    
+    content = types_file.read_text()
+    schemas = {}
+    
+    # Find all interfaces
+    interface_pattern = r'export\s+interface\s+(\w+)\s*\{([^}]+)\}'
+    
+    for match in re.finditer(interface_pattern, content, re.DOTALL):
+        name = match.group(1)
+        body = match.group(2)
+        
+        # Extract field names
+        field_pattern = r'(\w+)\s*[?]?\s*:'
+        fields = re.findall(field_pattern, body)
+        
+        # Categorize
+        is_request = name.endswith('Request') or 'Create' in name or 'Update' in name
+        is_response = name.endswith('Response') or name.endswith('ListResponse')
+        is_params = name.endswith('Params')
+        
+        # Skip helper types
+        if is_params:
+            continue
+        
+        schemas[name] = {
+            'fields': fields,
+            'is_request': is_request,
+            'is_response': is_response,
+            'is_helper': is_request or is_response,
+        }
+    
+    # Also find type aliases (enums/unions)
+    type_pattern = r'export\s+type\s+(\w+)\s*='
+    for match in re.finditer(type_pattern, content):
+        name = match.group(1)
+        if name not in schemas:
+            schemas[name] = {
+                'fields': [],
+                'is_request': False,
+                'is_response': False,
+                'is_helper': True,  # Type aliases are usually helper types
+            }
+    
+    return schemas
+
+
+def extract_api_endpoints(api_file: Path) -> dict[str, set[str]]:
+    """
+    Extract what operations exist for each schema type.
+    
+    Returns a dict mapping schema names to available operations:
+    {
+        'User': {'list', 'get', 'create', 'update', 'delete'}
+    }
+    """
+    if not api_file.exists():
+        return {}
+    
+    content = api_file.read_text()
+    operations = {}
+    
+    # Match method definitions with their return types
+    # async listUsers(...): Promise<UserListResponse>
+    method_pattern = r'async\s+(list|get|create|update|delete|patch)(\w+)\s*\([^)]*\)\s*:\s*Promise<([^>]+)>'
+    
+    for match in re.finditer(method_pattern, content):
+        operation = match.group(1).lower()
+        resource_part = match.group(2)
+        return_type = match.group(3)
+        
+        # Derive schema name from method name
+        # listUsers -> User, getUser -> User
+        schema_name = resource_part.rstrip('s')  # Remove trailing 's' for list
+        
+        if schema_name not in operations:
+            operations[schema_name] = set()
+        operations[schema_name].add(operation)
+    
+    return operations
+
+
+def check_components(
+    schemas: dict[str, dict],
+    operations: dict[str, set[str]],
+    components_dir: Path
+) -> tuple[list[str], list[str], list[str]]:
+    """
+    Check which components exist and which are missing.
+    
+    Returns (missing, present, optional) component lists.
+    """
+    missing = []
+    present = []
+    optional = []
+    
+    # Determine which schemas need components
+    primary_schemas = {
+        name: info
+        for name, info in schemas.items()
+        if not info['is_helper']
+    }
+    
+    for schema_name, info in primary_schemas.items():
+        schema_dir = components_dir / schema_name
+        ops = operations.get(schema_name, set())
+        
+        # Check Form component (needed if create or update exists)
+        form_file = schema_dir / f'{schema_name}Form.tsx'
+        if 'create' in ops or 'update' in ops:
+            if form_file.exists():
+                present.append(f"{schema_name}/Form")
+            else:
+                missing.append(f"{schema_name}/Form (has create/update endpoint)")
+        else:
+            if form_file.exists():
+                optional.append(f"{schema_name}/Form (no create/update endpoint)")
+        
+        # Check Detail component (needed if get exists)
+        detail_file = schema_dir / f'{schema_name}Detail.tsx'
+        if 'get' in ops:
+            if detail_file.exists():
+                present.append(f"{schema_name}/Detail")
+            else:
+                missing.append(f"{schema_name}/Detail (has get endpoint)")
+        else:
+            if detail_file.exists():
+                optional.append(f"{schema_name}/Detail (no get endpoint)")
+        
+        # Check List component (needed if list exists)
+        list_file = schema_dir / f'{schema_name}List.tsx'
+        if 'list' in ops:
+            if list_file.exists():
+                present.append(f"{schema_name}/List")
+            else:
+                missing.append(f"{schema_name}/List (has list endpoint)")
+        else:
+            if list_file.exists():
+                optional.append(f"{schema_name}/List (no list endpoint)")
+        
+        # Check index.ts barrel export
+        index_file = schema_dir / 'index.ts'
+        if schema_dir.exists() and not index_file.exists():
+            missing.append(f"{schema_name}/index.ts (barrel export)")
+    
+    # Check shared components
+    shared_dir = components_dir / 'shared'
+    shared_components = ['LoadingSpinner', 'ErrorDisplay', 'Pagination']
+    
+    for comp in shared_components:
+        comp_file = shared_dir / f'{comp}.tsx'
+        if comp_file.exists():
+            present.append(f"shared/{comp}")
+        else:
+            missing.append(f"shared/{comp}")
+    
+    # Check top-level barrel export
+    root_index = components_dir / 'index.ts'
+    if root_index.exists():
+        present.append("index.ts (root barrel)")
+    else:
+        missing.append("index.ts (root barrel)")
+    
+    return missing, present, optional
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Verify React components exist for TypeScript client types.'
+    )
+    parser.add_argument('client_dir', type=Path, help='Path to the client directory')
+    parser.add_argument('components_dir', type=Path, help='Path to the components directory')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    
+    args = parser.parse_args()
+    
+    types_file = args.client_dir / 'types.ts'
+    api_file = args.client_dir / 'api.ts'
+    
+    if not types_file.exists():
+        print(f"Error: types.ts not found in {args.client_dir}", file=sys.stderr)
+        sys.exit(1)
+    
+    # Extract information
+    schemas = extract_schema_types(types_file)
+    operations = extract_api_endpoints(api_file)
+    
+    # Check components
+    missing, present, optional = check_components(
+        schemas, operations, args.components_dir
+    )
+    
+    if args.json:
+        result = {
+            'missing': missing,
+            'present': present,
+            'optional': optional,
+            'schemas': list(schemas.keys()),
+            'operations': {k: list(v) for k, v in operations.items()},
+            'coverage': {
+                'required': len(missing) + len(present),
+                'present': len(present),
+                'missing': len(missing),
+                'percentage': round(
+                    len(present) / (len(missing) + len(present)) * 100, 1
+                ) if missing or present else 100
+            }
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print("=" * 60)
+        print("TypeScript Client to React Components Coverage Report")
+        print("=" * 60)
+        print()
+        
+        print(f"Schemas found: {len(schemas)}")
+        print(f"Primary schemas (need components): {len([s for s in schemas.values() if not s['is_helper']])}")
+        print()
+        
+        if present:
+            print(f"✓ Present ({len(present)}):")
+            for item in sorted(present):
+                print(f"  • {item}")
+            print()
+        
+        if missing:
+            print(f"✗ Missing ({len(missing)}):")
+            for item in sorted(missing):
+                print(f"  • {item}")
+            print()
+        
+        if optional:
+            print(f"? Optional ({len(optional)}):")
+            for item in sorted(optional):
+                print(f"  • {item}")
+            print()
+        
+        required = len(missing) + len(present)
+        if required > 0:
+            percentage = len(present) / required * 100
+            print("=" * 60)
+            print(f"Coverage: {len(present)}/{required} ({percentage:.1f}%)")
+            print("=" * 60)
+    
+    if missing:
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/plugins/openapi-to-frontend/scripts/verify-coverage.py b/plugins/openapi-to-frontend/scripts/verify-coverage.py
new file mode 100755
index 0000000..ae78e3c
--- /dev/null
+++ b/plugins/openapi-to-frontend/scripts/verify-coverage.py
@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Verify that generated TypeScript code covers all schemas and endpoints in the OpenAPI spec.
+
+This script cross-references the OpenAPI spec against the generated TypeScript client
+to ensure completeness.
+
+Usage:
+    python verify-coverage.py <spec-file> <client-dir>
+
+Example:
+    python verify-coverage.py openapi.yaml client/
+
+Exit codes:
+    0 - All items covered
+    1 - Missing coverage detected
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml
+except ImportError:
+    yaml = None
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    """Load an OpenAPI spec from a JSON or YAML file."""
+    content = path.read_text()
+    
+    if path.suffix in ('.yaml', '.yml'):
+        if yaml is None:
+            print("Error: PyYAML is required for YAML files. Install with: pip install pyyaml", file=sys.stderr)
+            sys.exit(1)
+        return yaml.safe_load(content)
+    else:
+        return json.loads(content)
+
+
+def extract_schema_names(spec: dict[str, Any]) -> set[str]:
+    """Extract all schema names from the spec."""
+    components = spec.get('components', {})
+    return set(components.get('schemas', {}).keys())
+
+
+def extract_endpoint_keys(spec: dict[str, Any]) -> set[str]:
+    """Extract all endpoint keys (METHOD /path) from the spec."""
+    endpoints = set()
+    
+    for path, path_item in spec.get('paths', {}).items():
+        for method in ['get', 'post', 'put', 'patch', 'delete', 'options', 'head']:
+            if method in path_item:
+                endpoints.add(f"{method.upper()} {path}")
+    
+    return endpoints
+
+
+def extract_enum_names(spec: dict[str, Any]) -> set[str]:
+    """Extract all enum schema names from the spec."""
+    enums = set()
+    components = spec.get('components', {})
+    
+    for name, schema in components.get('schemas', {}).items():
+        if 'enum' in schema:
+            enums.add(name)
+    
+    return enums
+
+
+def parse_types_file(path: Path) -> set[str]:
+    """Extract interface/type names from types.ts."""
+    if not path.exists():
+        return set()
+    
+    content = path.read_text()
+    
+    # Match: export interface Name, export type Name
+    pattern = r'export\s+(?:interface|type)\s+(\w+)'
+    return set(re.findall(pattern, content))
+
+
+def parse_api_file(path: Path) -> set[tuple[str, str]]:
+    """Extract method signatures from api.ts to infer covered endpoints."""
+    if not path.exists():
+        return set()
+    
+    content = path.read_text()
+    methods = set()
+    
+    # Match async method definitions
+    # async methodName(...): Promise<...>
+    pattern = r'async\s+(\w+)\s*\([^)]*\)\s*:\s*Promise'
+    method_names = re.findall(pattern, content)
+    
+    # Also look for request calls to infer endpoints
+    # this.request('GET', '/users', ...)
+    request_pattern = r"this\.request\s*\(\s*['\"](\w+)['\"]\s*,\s*['\"`]([^'\"`]+)['\"`]"
+    for match in re.finditer(request_pattern, content):
+        http_method = match.group(1)
+        path = match.group(2)
+        # Normalize path parameters
+        normalized_path = re.sub(r'\$\{[^}]+\}', '{param}', path)
+        methods.add((http_method, normalized_path))
+    
+    return methods
+
+
+def normalize_path(path: str) -> str:
+    """Normalize a path for comparison."""
+    # Replace {param} variations with a standard format
+    return re.sub(r'\{[^}]+\}', '{id}', path)
+
+
+def verify_coverage(spec_path: Path, client_dir: Path) -> tuple[list[str], list[str], list[str]]:
+    """
+    Verify coverage and return (missing, covered, extraneous) items.
+    """
+    spec = load_spec(spec_path)
+    
+    # Expected from spec
+    expected_schemas = extract_schema_names(spec)
+    expected_endpoints = extract_endpoint_keys(spec)
+    expected_enums = extract_enum_names(spec)
+    
+    # Found in generated code
+    types_file = client_dir / 'types.ts'
+    api_file = client_dir / 'api.ts'
+    
+    found_types = parse_types_file(types_file)
+    found_methods = parse_api_file(api_file)
+    
+    # Check schema coverage
+    missing = []
+    covered = []
+    extraneous = []
+    
+    # Check interfaces
+    for schema in expected_schemas:
+        if schema in found_types:
+            covered.append(f"Schema: {schema}")
+        else:
+            missing.append(f"Schema: {schema}")
+    
+    # Check for extra types (not necessarily bad, could be helper types)
+    spec_schema_names = expected_schemas | expected_enums
+    extra_types = found_types - spec_schema_names
+    # Filter out common helper types
+    helper_patterns = ['Request', 'Response', 'Params', 'Config', 'Error', 'Options']
+    for t in extra_types:
+        is_helper = any(p in t for p in helper_patterns)
+        if not is_helper:
+            extraneous.append(f"Extra type: {t}")
+    
+    # Check endpoint coverage
+    found_paths = {normalize_path(p) for _, p in found_methods}
+    for endpoint in expected_endpoints:
+        method, path = endpoint.split(' ', 1)
+        normalized = normalize_path(path)
+        
+        # Check if any found method matches
+        matched = False
+        for found_method, found_path in found_methods:
+            if found_method == method and normalize_path(found_path) == normalized:
+                matched = True
+                break
+        
+        if matched:
+            covered.append(f"Endpoint: {endpoint}")
+        else:
+            missing.append(f"Endpoint: {endpoint}")
+    
+    return missing, covered, extraneous
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Verify TypeScript client coverage against OpenAPI spec.'
+    )
+    parser.add_argument('spec_file', type=Path, help='Path to the OpenAPI spec file')
+    parser.add_argument('client_dir', type=Path, help='Path to the client directory')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    
+    args = parser.parse_args()
+    
+    if not args.spec_file.exists():
+        print(f"Error: Spec file not found: {args.spec_file}", file=sys.stderr)
+        sys.exit(1)
+    
+    if not args.client_dir.exists():
+        print(f"Error: Client directory not found: {args.client_dir}", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        missing, covered, extraneous = verify_coverage(args.spec_file, args.client_dir)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    
+    if args.json:
+        result = {
+            'missing': missing,
+            'covered': covered,
+            'extraneous': extraneous,
+            'coverage': {
+                'total': len(missing) + len(covered),
+                'covered': len(covered),
+                'missing': len(missing),
+                'percentage': round(len(covered) / (len(missing) + len(covered)) * 100, 1) if missing or covered else 100
+            }
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        print("=" * 60)
+        print("OpenAPI to TypeScript Coverage Report")
+        print("=" * 60)
+        print()
+        
+        if covered:
+            print(f"✓ Covered ({len(covered)}):")
+            for item in sorted(covered):
+                print(f"  • {item}")
+            print()
+        
+        if missing:
+            print(f"✗ Missing ({len(missing)}):")
+            for item in sorted(missing):
+                print(f"  • {item}")
+            print()
+        
+        if extraneous:
+            print(f"? Extraneous ({len(extraneous)}):")
+            for item in sorted(extraneous):
+                print(f"  • {item}")
+            print()
+        
+        total = len(missing) + len(covered)
+        if total > 0:
+            percentage = len(covered) / total * 100
+            print("=" * 60)
+            print(f"Coverage: {len(covered)}/{total} ({percentage:.1f}%)")
+            print("=" * 60)
+    
+    if missing:
+        sys.exit(1)
+    else:
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/plugins/openapi-to-frontend/skills/generate-ci/SKILL.md b/plugins/openapi-to-frontend/skills/generate-ci/SKILL.md
new file mode 100644
index 0000000..3496980
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/generate-ci/SKILL.md
@@ -0,0 +1,494 @@
+---
+name: openapi-generate-ci
+description: Generate GitHub Actions workflows for CI/CD. Includes build/test on PR, deploy to GitHub Pages, and publish to npm.
+license: MIT
+compatibility: Requires GitHub Actions, optionally npm for publishing
+triggers:
+  - openapi ci
+  - generate ci
+  - github actions
+  - ci cd
+  - deploy workflow
+---
+
+Generate GitHub Actions workflows for the generated codebase.
+
+## Overview
+
+This skill produces three workflow files:
+
+- `.github/workflows/ci.yml` — Build + test on push/PR
+- `.github/workflows/deploy.yml` — Deploy frontend to GitHub Pages
+- `.github/workflows/publish.yml` — Publish packages to npm
+
+## Prerequisites
+
+- Generated codebase (client, components, frontend, tests)
+- GitHub repository
+- Optional: npm account for publishing
+
+## Workflow
+
+### Step 1: Detect Project Configuration
+
+Analyze `package.json` to determine:
+
+- Node.js version (from `engines.node` or default to LTS)
+- Package manager (npm, yarn, pnpm)
+- Test commands available
+- Build commands
+- Scope for npm packages (from name or repo)
+
+### Step 2: Generate ci.yml
+
+**.github/workflows/ci.yml:**
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint
+
+      - name: Type check
+        run: npm run typecheck
+
+  test-unit:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests
+        run: npm run test:unit
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+
+  test-integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run integration tests
+        run: npm run test:integration
+
+  test-e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    # E2E Backend Strategy: Detected method documented here
+    # Using: Docker Compose / npm start / Prism mock / E2E_BASE_URL
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      # Option 1: Docker Compose backend
+      - name: Start backend (Docker)
+        run: |
+          docker compose up -d
+          # Wait for backend to be ready
+          timeout 60 bash -c 'until curl -s http://localhost:3000/health; do sleep 2; done'
+        if: hashFiles('docker-compose.yml') != ''
+
+      # Option 2: Start mock server with Prism
+      - name: Start mock server
+        run: |
+          npm install -g @stoplight/prism-cli
+          prism mock openapi.yaml --port 3000 &
+          sleep 5
+        if: hashFiles('docker-compose.yml') == '' && hashFiles('openapi.yaml') != ''
+
+      - name: Build frontend
+        run: npm run build
+
+      - name: Run E2E tests
+        run: npm run test:e2e
+        env:
+          E2E_BASE_URL: ${{ secrets.E2E_BASE_URL || 'http://localhost:3000' }}
+
+      - name: Upload test artifacts
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+
+      - name: Stop backend
+        run: docker compose down
+        if: always() && hashFiles('docker-compose.yml') != ''
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit, test-integration]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+```
+
+### Step 3: Generate deploy.yml
+
+**.github/workflows/deploy.yml:**
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+        env:
+          # Set base path for GitHub Pages
+          VITE_BASE_URL: /${{ github.event.repository.name }}/
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### Step 4: Generate publish.yml
+
+**.github/workflows/publish.yml:**
+
+```yaml
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 1.0.0)'
+        required: true
+        type: string
+
+jobs:
+  publish:
+    name: Publish Packages
+    runs-on: ubuntu-latest
+    # Only run if NPM_TOKEN is available
+    if: ${{ secrets.NPM_TOKEN != '' }}
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: |
+          npm run test:unit
+          npm run test:integration
+
+      - name: Build packages
+        run: npm run build
+
+      # Publish TypeScript client
+      - name: Publish client package
+        run: |
+          cd client
+          npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Publish React components
+      - name: Publish components package
+        run: |
+          cd components
+          npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  skip-publish:
+    name: Skip Publish (no NPM_TOKEN)
+    runs-on: ubuntu-latest
+    if: ${{ secrets.NPM_TOKEN == '' }}
+    steps:
+      - name: Notice
+        run: |
+          echo "::notice::Skipping npm publish - NPM_TOKEN secret not configured"
+          echo "To enable publishing, add NPM_TOKEN to repository secrets"
+```
+
+### Step 5: Generate Dependabot Configuration
+
+**.github/dependabot.yml:**
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        patterns:
+          - '*'
+        exclude-patterns:
+          - 'react*'
+          - 'typescript'
+      react:
+        patterns:
+          - 'react*'
+          - '@types/react*'
+    ignore:
+      - dependency-name: '*'
+        update-types: ['version-update:semver-major']
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns:
+          - '*'
+```
+
+### Step 6: Generate Branch Protection Suggestion
+
+Output a reminder for the user:
+
+```
+## Recommended Branch Protection Rules
+
+For the `main` branch, consider enabling:
+
+1. **Require status checks to pass before merging:**
+   - lint
+   - test-unit
+   - test-integration
+   - build
+
+2. **Require branches to be up to date before merging**
+
+3. **Require pull request reviews:**
+   - At least 1 approval
+
+4. **Do not allow bypassing the above settings**
+
+You can configure these at:
+Settings → Branches → Add branch protection rule
+```
+
+## Secrets Configuration
+
+| Secret | Required By | Purpose |
+|--------|-------------|---------|
+| `NPM_TOKEN` | publish.yml | npm authentication (optional) |
+| `E2E_BASE_URL` | ci.yml | Backend URL for e2e (optional fallback) |
+| `CODECOV_TOKEN` | ci.yml | Coverage upload (optional) |
+
+## Package.json Scripts
+
+Ensure these scripts exist:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "lint": "eslint . --ext .ts,.tsx",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "playwright test"
+  }
+}
+```
+
+## E2E Backend Strategy Selection
+
+The ci.yml workflow uses this priority order for starting the backend:
+
+1. **Docker Compose** — If `docker-compose.yml` exists, start services and wait for health endpoint
+2. **Mock Server** — If only OpenAPI spec exists, use Prism to mock the API
+3. **External URL** — Fall back to `E2E_BASE_URL` secret
+
+The workflow includes comments documenting which strategy was selected.
+
+## Vite Configuration for GitHub Pages
+
+**vite.config.ts:**
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  // Use VITE_BASE_URL for GitHub Pages deployment
+  base: process.env.VITE_BASE_URL || '/',
+});
+```
+
+## Output Files
+
+| File | Purpose |
+|------|---------|
+| `.github/workflows/ci.yml` | Build + test on push/PR |
+| `.github/workflows/deploy.yml` | Deploy to GitHub Pages |
+| `.github/workflows/publish.yml` | Publish to npm on release |
+| `.github/dependabot.yml` | Automated dependency updates |
+
+## Verification
+
+After generating, verify:
+
+1. Push to a branch and check that CI runs
+2. Create a PR and verify all checks pass
+3. Merge to main and verify GitHub Pages deploy
+4. Create a release to test npm publish (if configured)
+
+## Next Steps
+
+All phases complete! The generated codebase now includes:
+
+- TypeScript API client
+- React component library
+- Frontend application
+- Comprehensive tests
+- CI/CD pipelines
+
+For incremental updates when the spec changes, see:
+[../update-from-spec/SKILL.md](../update-from-spec/SKILL.md)
diff --git a/plugins/openapi-to-frontend/skills/generate-client/SKILL.md b/plugins/openapi-to-frontend/skills/generate-client/SKILL.md
new file mode 100644
index 0000000..0d56949
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/generate-client/SKILL.md
@@ -0,0 +1,482 @@
+---
+name: openapi-generate-client
+description: Generate a TypeScript API client from an OpenAPI specification. Creates types, API class, and auth handlers.
+license: MIT
+compatibility: Requires Node.js 18+, TypeScript 5+
+triggers:
+  - openapi client
+  - generate typescript client
+  - openapi to typescript
+  - api client from spec
+---
+
+Generate a TypeScript API client from an OpenAPI specification.
+
+## Overview
+
+This skill produces a complete TypeScript client layer:
+
+- `client/types.ts` — TypeScript interfaces/types for every schema
+- `client/api.ts` — A class with one async method per API endpoint
+- `client/auth.ts` — Auth configuration based on securitySchemes
+- `client/index.ts` — Barrel export
+
+## Prerequisites
+
+- OpenAPI 3.0+ specification (JSON or YAML)
+- Node.js 18+ with npm
+- TypeScript 5+
+
+## Workflow
+
+### Step 1: Parse the OpenAPI Spec
+
+Run the parse script to extract structured data:
+
+```bash
+python scripts/parse-openapi.py path/to/openapi.yaml > .generated/spec-summary.json
+```
+
+This outputs:
+- All schemas with field names, types, and constraints
+- All endpoints with methods, parameters, and responses
+- All security schemes with their configuration
+
+### Step 2: Generate types.ts
+
+For each schema in `components/schemas`, create a TypeScript interface:
+
+**Mapping Rules:**
+
+| OpenAPI Type | TypeScript Type |
+|--------------|-----------------|
+| `string` | `string` |
+| `string` (format: date-time) | `string` (ISO 8601) |
+| `string` (format: date) | `string` (YYYY-MM-DD) |
+| `string` (format: email) | `string` |
+| `string` (format: uuid) | `string` |
+| `string` (format: binary) | `Blob` |
+| `integer` | `number` |
+| `number` | `number` |
+| `boolean` | `boolean` |
+| `array` | `T[]` |
+| `object` | Nested interface or `Record<string, unknown>` |
+| `$ref` | Import reference to another interface |
+| `enum` | Union type (`'a' \| 'b' \| 'c'`) or TypeScript `enum` |
+| `oneOf` | Union type |
+| `anyOf` | Union type |
+| `allOf` | Intersection type (`A & B`) |
+| `nullable: true` | `T \| null` |
+
+**Field naming:** Convert `snake_case` to `camelCase`.
+
+**Required fields:** Mark non-required fields as optional with `?`.
+
+**Example output:**
+
+```typescript
+// client/types.ts
+
+export interface User {
+  id: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  role: UserRole;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export type UserRole = 'admin' | 'user' | 'guest';
+
+export interface CreateUserRequest {
+  email: string;
+  firstName: string;
+  lastName: string;
+  password: string;
+  role?: UserRole;
+}
+
+export interface UpdateUserRequest {
+  firstName?: string;
+  lastName?: string;
+  role?: UserRole;
+}
+
+export interface UserListResponse {
+  items: User[];
+  total: number;
+  page: number;
+  pageSize: number;
+}
+```
+
+### Step 3: Generate api.ts
+
+Create an API class with methods for each endpoint:
+
+**Method naming:**
+
+| HTTP Method | Path Pattern | Method Name |
+|-------------|--------------|-------------|
+| GET | `/resources` | `listResources()` |
+| GET | `/resources/{id}` | `getResource(id)` |
+| POST | `/resources` | `createResource(data)` |
+| PUT | `/resources/{id}` | `updateResource(id, data)` |
+| PATCH | `/resources/{id}` | `patchResource(id, data)` |
+| DELETE | `/resources/{id}` | `deleteResource(id)` |
+| POST | `/resources/{id}/action` | `actionResource(id)` |
+
+**Parameters:**
+
+- Path parameters → method arguments (typed)
+- Query parameters → optional `params` object
+- Request body → `data` argument (typed to request schema)
+- Headers → handled internally (content-type, auth)
+
+**Return type:** `Promise<ResponseType>` based on response schema.
+
+**Example output:**
+
+```typescript
+// client/api.ts
+
+import type {
+  User,
+  CreateUserRequest,
+  UpdateUserRequest,
+  UserListResponse,
+} from './types';
+import { AuthConfig, attachAuth } from './auth';
+
+export interface ApiConfig {
+  baseUrl: string;
+  auth?: AuthConfig;
+}
+
+export interface ListUsersParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+}
+
+export class ApiClient {
+  private baseUrl: string;
+  private auth?: AuthConfig;
+
+  constructor(config: ApiConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, '');
+    this.auth = config.auth;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    options: {
+      params?: Record<string, string | number | boolean | undefined>;
+      body?: unknown;
+    } = {}
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl);
+    if (options.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (this.auth) {
+      attachAuth(headers, url, this.auth);
+    }
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (!response.ok) {
+      throw new ApiError(response.status, await response.text());
+    }
+
+    return response.json();
+  }
+
+  // User endpoints
+  async listUsers(params?: ListUsersParams): Promise<UserListResponse> {
+    return this.request('GET', '/users', { params });
+  }
+
+  async getUser(id: string): Promise<User> {
+    return this.request('GET', `/users/${id}`);
+  }
+
+  async createUser(data: CreateUserRequest): Promise<User> {
+    return this.request('POST', '/users', { body: data });
+  }
+
+  async updateUser(id: string, data: UpdateUserRequest): Promise<User> {
+    return this.request('PUT', `/users/${id}`, { body: data });
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    return this.request('DELETE', `/users/${id}`);
+  }
+}
+
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    public body: string
+  ) {
+    super(`API Error ${status}: ${body}`);
+    this.name = 'ApiError';
+  }
+}
+```
+
+### Step 4: Generate auth.ts
+
+Based on `components/securitySchemes`, generate auth handlers:
+
+**API Key:**
+
+```typescript
+export interface ApiKeyAuth {
+  type: 'apiKey';
+  key: string;
+  location: 'header' | 'query';
+  name: string; // e.g., 'X-API-Key' or 'api_key'
+}
+```
+
+**Bearer Token:**
+
+```typescript
+export interface BearerAuth {
+  type: 'bearer';
+  token: string;
+}
+```
+
+**OAuth2:**
+
+```typescript
+export interface OAuth2Auth {
+  type: 'oauth2';
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  token?: OAuthToken;
+}
+
+export interface OAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+```
+
+**Example output:**
+
+```typescript
+// client/auth.ts
+
+export type AuthConfig = ApiKeyAuth | BearerAuth | OAuth2Auth;
+
+export interface ApiKeyAuth {
+  type: 'apiKey';
+  key: string;
+  location: 'header' | 'query';
+  name: string;
+}
+
+export interface BearerAuth {
+  type: 'bearer';
+  token: string;
+}
+
+export interface OAuth2Auth {
+  type: 'oauth2';
+  clientId: string;
+  redirectUri: string;
+  scopes: string[];
+  authorizationUrl: string;
+  tokenUrl: string;
+  token?: OAuthToken;
+}
+
+export interface OAuthToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+export function attachAuth(
+  headers: Record<string, string>,
+  url: URL,
+  auth: AuthConfig
+): void {
+  switch (auth.type) {
+    case 'apiKey':
+      if (auth.location === 'header') {
+        headers[auth.name] = auth.key;
+      } else {
+        url.searchParams.set(auth.name, auth.key);
+      }
+      break;
+    case 'bearer':
+      headers['Authorization'] = `Bearer ${auth.token}`;
+      break;
+    case 'oauth2':
+      if (auth.token?.accessToken) {
+        headers['Authorization'] = `Bearer ${auth.token.accessToken}`;
+      }
+      break;
+  }
+}
+
+// OAuth2 helpers (only generated if OAuth2 is used)
+export class OAuth2Manager {
+  private config: OAuth2Auth;
+  private codeVerifier?: string;
+
+  constructor(config: Omit<OAuth2Auth, 'type' | 'token'>) {
+    this.config = { ...config, type: 'oauth2' };
+  }
+
+  getAuthorizationUrl(): string {
+    this.codeVerifier = this.generateCodeVerifier();
+    const codeChallenge = this.generateCodeChallenge(this.codeVerifier);
+
+    const url = new URL(this.config.authorizationUrl);
+    url.searchParams.set('client_id', this.config.clientId);
+    url.searchParams.set('redirect_uri', this.config.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', this.config.scopes.join(' '));
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+
+    return url.toString();
+  }
+
+  async exchangeCode(code: string): Promise<OAuthToken> {
+    const response = await fetch(this.config.tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: this.config.clientId,
+        redirect_uri: this.config.redirectUri,
+        code,
+        code_verifier: this.codeVerifier || '',
+      }),
+    });
+
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+    };
+  }
+
+  async refreshToken(token: OAuthToken): Promise<OAuthToken> {
+    if (!token.refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    const response = await fetch(this.config.tokenUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: this.config.clientId,
+        refresh_token: token.refreshToken,
+      }),
+    });
+
+    const data = await response.json();
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token || token.refreshToken,
+      expiresAt: data.expires_in
+        ? Date.now() + data.expires_in * 1000
+        : undefined,
+    };
+  }
+
+  private generateCodeVerifier(): string {
+    const array = new Uint8Array(32);
+    crypto.getRandomValues(array);
+    return btoa(String.fromCharCode(...array))
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '');
+  }
+
+  private generateCodeChallenge(verifier: string): string {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    return crypto.subtle
+      .digest('SHA-256', data)
+      .then((hash) =>
+        btoa(String.fromCharCode(...new Uint8Array(hash)))
+          .replace(/\+/g, '-')
+          .replace(/\//g, '_')
+          .replace(/=/g, '')
+      ) as unknown as string;
+  }
+}
+```
+
+### Step 5: Generate index.ts
+
+Create a barrel export:
+
+```typescript
+// client/index.ts
+
+export * from './types';
+export * from './api';
+export * from './auth';
+```
+
+### Step 6: Verify Output
+
+Run the verification scripts:
+
+```bash
+# Lint the generated code
+./scripts/lint-generated.sh
+
+# Verify coverage against spec
+python scripts/verify-coverage.py openapi.yaml client/
+```
+
+## Output Files
+
+| File | Contents |
+|------|----------|
+| `client/types.ts` | TypeScript interfaces for all schemas |
+| `client/api.ts` | API client class with typed methods |
+| `client/auth.ts` | Auth config types and helpers |
+| `client/index.ts` | Barrel export |
+
+## Next Steps
+
+After generating the client, proceed to:
+
+1. **Generate Components** — Create React components using the client
+2. **Generate Tests** — Create unit tests for the client
+
+See [../generate-components/SKILL.md](../generate-components/SKILL.md)
diff --git a/plugins/openapi-to-frontend/skills/generate-components/SKILL.md b/plugins/openapi-to-frontend/skills/generate-components/SKILL.md
new file mode 100644
index 0000000..e840355
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/generate-components/SKILL.md
@@ -0,0 +1,740 @@
+---
+name: openapi-generate-components
+description: Generate React components from a TypeScript API client. Creates Form, Detail, and List components for each schema.
+license: MIT
+compatibility: Requires React 18+, TypeScript 5+
+triggers:
+  - openapi components
+  - generate react components
+  - api to react
+  - schema components
+---
+
+Generate React components from a TypeScript API client.
+
+## Overview
+
+This skill produces a React component library based on the TypeScript client:
+
+- `components/<SchemaName>/` — Directory per schema containing:
+  - `<SchemaName>Form.tsx` — Create/edit form
+  - `<SchemaName>Detail.tsx` — Read-only detail view
+  - `<SchemaName>List.tsx` — List/table view with pagination
+  - `index.ts` — Barrel export
+- `components/shared/` — Common UI pieces
+- `components/index.ts` — Top-level barrel export
+
+## Prerequisites
+
+- Generated TypeScript client (from generate-client phase)
+- React 18+
+- TypeScript 5+
+
+## Workflow
+
+### Step 1: Analyze the Client Types
+
+Read `client/types.ts` to understand available schemas and their fields.
+
+For each schema, determine:
+- Which endpoints exist (POST/PUT → Form, GET single → Detail, GET list → List)
+- Field types for input rendering
+- Required vs optional fields
+- Nested schemas and relationships
+
+### Step 2: Generate Shared Components
+
+Create common UI pieces in `components/shared/`:
+
+**LoadingSpinner.tsx:**
+
+```tsx
+import React from 'react';
+
+export interface LoadingSpinnerProps {
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+
+export function LoadingSpinner({
+  size = 'md',
+  className = '',
+}: LoadingSpinnerProps) {
+  const sizeClasses = {
+    sm: 'w-4 h-4',
+    md: 'w-8 h-8',
+    lg: 'w-12 h-12',
+  };
+
+  return (
+    <div className={`flex justify-center items-center ${className}`}>
+      <div
+        className={`${sizeClasses[size]} border-2 border-gray-200 border-t-blue-600 rounded-full animate-spin`}
+      />
+    </div>
+  );
+}
+```
+
+**ErrorDisplay.tsx:**
+
+```tsx
+import React from 'react';
+
+export interface ErrorDisplayProps {
+  error: Error | string;
+  onRetry?: () => void;
+  className?: string;
+}
+
+export function ErrorDisplay({
+  error,
+  onRetry,
+  className = '',
+}: ErrorDisplayProps) {
+  const message = typeof error === 'string' ? error : error.message;
+
+  return (
+    <div
+      className={`bg-red-50 border border-red-200 rounded-lg p-4 ${className}`}
+    >
+      <div className="flex items-center gap-2 text-red-700">
+        <svg className="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
+          <path
+            fillRule="evenodd"
+            d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z"
+            clipRule="evenodd"
+          />
+        </svg>
+        <span className="font-medium">Error</span>
+      </div>
+      <p className="mt-2 text-red-600">{message}</p>
+      {onRetry && (
+        <button
+          onClick={onRetry}
+          className="mt-3 px-4 py-2 bg-red-100 text-red-700 rounded hover:bg-red-200 transition-colors"
+        >
+          Retry
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+**Pagination.tsx:**
+
+```tsx
+import React from 'react';
+
+export interface PaginationProps {
+  page: number;
+  pageSize: number;
+  total: number;
+  onPageChange: (page: number) => void;
+  className?: string;
+}
+
+export function Pagination({
+  page,
+  pageSize,
+  total,
+  onPageChange,
+  className = '',
+}: PaginationProps) {
+  const totalPages = Math.ceil(total / pageSize);
+  const canGoPrev = page > 1;
+  const canGoNext = page < totalPages;
+
+  return (
+    <div
+      className={`flex items-center justify-between px-4 py-3 ${className}`}
+    >
+      <div className="text-sm text-gray-700">
+        Showing {(page - 1) * pageSize + 1} to{' '}
+        {Math.min(page * pageSize, total)} of {total} results
+      </div>
+      <div className="flex gap-2">
+        <button
+          onClick={() => onPageChange(page - 1)}
+          disabled={!canGoPrev}
+          className="px-3 py-1 border rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
+        >
+          Previous
+        </button>
+        <span className="px-3 py-1">
+          Page {page} of {totalPages}
+        </span>
+        <button
+          onClick={() => onPageChange(page + 1)}
+          disabled={!canGoNext}
+          className="px-3 py-1 border rounded disabled:opacity-50 disabled:cursor-not-allowed hover:bg-gray-50"
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 3: Generate Schema Components
+
+For each schema with API endpoints, create a component directory.
+
+#### Form Component
+
+Generated when POST or PUT endpoints exist for the schema.
+
+**Mapping Rules:**
+
+| Field Type | Input Component |
+|------------|-----------------|
+| `string` | `<input type="text">` |
+| `string` (format: email) | `<input type="email">` |
+| `string` (format: password) | `<input type="password">` |
+| `string` (format: date) | `<input type="date">` |
+| `string` (format: date-time) | `<input type="datetime-local">` |
+| `string` (format: uri) | `<input type="url">` |
+| `string` (multiline/long) | `<textarea>` |
+| `number` / `integer` | `<input type="number">` |
+| `boolean` | `<input type="checkbox">` or toggle |
+| `enum` / union | `<select>` with options |
+| `array` | Repeatable field group with add/remove |
+| `$ref` (related schema) | Nested form or select dropdown |
+
+**Example UserForm.tsx:**
+
+```tsx
+import React, { useState, FormEvent } from 'react';
+import type {
+  User,
+  CreateUserRequest,
+  UpdateUserRequest,
+  UserRole,
+} from '../../client/types';
+import { useApiClient } from '../../app/context/ApiContext';
+import { LoadingSpinner } from '../shared/LoadingSpinner';
+import { ErrorDisplay } from '../shared/ErrorDisplay';
+
+export interface UserFormProps {
+  user?: User; // If provided, edit mode; otherwise create mode
+  onSuccess?: (user: User) => void;
+  onCancel?: () => void;
+  className?: string;
+}
+
+const USER_ROLES: UserRole[] = ['admin', 'user', 'guest'];
+
+export function UserForm({
+  user,
+  onSuccess,
+  onCancel,
+  className = '',
+}: UserFormProps) {
+  const client = useApiClient();
+  const isEditMode = !!user;
+
+  const [formData, setFormData] = useState({
+    email: user?.email || '',
+    firstName: user?.firstName || '',
+    lastName: user?.lastName || '',
+    password: '',
+    role: user?.role || ('user' as UserRole),
+  });
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const handleChange = (
+    e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>
+  ) => {
+    const { name, value } = e.target;
+    setFormData((prev) => ({ ...prev, [name]: value }));
+  };
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError(null);
+
+    try {
+      let result: User;
+      if (isEditMode && user) {
+        const updateData: UpdateUserRequest = {
+          firstName: formData.firstName,
+          lastName: formData.lastName,
+          role: formData.role,
+        };
+        result = await client.updateUser(user.id, updateData);
+      } else {
+        const createData: CreateUserRequest = {
+          email: formData.email,
+          firstName: formData.firstName,
+          lastName: formData.lastName,
+          password: formData.password,
+          role: formData.role,
+        };
+        result = await client.createUser(createData);
+      }
+      onSuccess?.(result);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className={`space-y-4 ${className}`}>
+      {error && <ErrorDisplay error={error} />}
+
+      <div>
+        <label htmlFor="email" className="block text-sm font-medium mb-1">
+          Email <span className="text-red-500">*</span>
+        </label>
+        <input
+          type="email"
+          id="email"
+          name="email"
+          value={formData.email}
+          onChange={handleChange}
+          required
+          disabled={isEditMode}
+          className="w-full px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
+        />
+      </div>
+
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <label htmlFor="firstName" className="block text-sm font-medium mb-1">
+            First Name <span className="text-red-500">*</span>
+          </label>
+          <input
+            type="text"
+            id="firstName"
+            name="firstName"
+            value={formData.firstName}
+            onChange={handleChange}
+            required
+            className="w-full px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500"
+          />
+        </div>
+        <div>
+          <label htmlFor="lastName" className="block text-sm font-medium mb-1">
+            Last Name <span className="text-red-500">*</span>
+          </label>
+          <input
+            type="text"
+            id="lastName"
+            name="lastName"
+            value={formData.lastName}
+            onChange={handleChange}
+            required
+            className="w-full px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500"
+          />
+        </div>
+      </div>
+
+      {!isEditMode && (
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium mb-1">
+            Password <span className="text-red-500">*</span>
+          </label>
+          <input
+            type="password"
+            id="password"
+            name="password"
+            value={formData.password}
+            onChange={handleChange}
+            required
+            minLength={8}
+            className="w-full px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500"
+          />
+        </div>
+      )}
+
+      <div>
+        <label htmlFor="role" className="block text-sm font-medium mb-1">
+          Role
+        </label>
+        <select
+          id="role"
+          name="role"
+          value={formData.role}
+          onChange={handleChange}
+          className="w-full px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500"
+        >
+          {USER_ROLES.map((role) => (
+            <option key={role} value={role}>
+              {role.charAt(0).toUpperCase() + role.slice(1)}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      <div className="flex gap-3 pt-4">
+        <button
+          type="submit"
+          disabled={loading}
+          className="flex-1 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50"
+        >
+          {loading ? (
+            <LoadingSpinner size="sm" />
+          ) : isEditMode ? (
+            'Update User'
+          ) : (
+            'Create User'
+          )}
+        </button>
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="px-4 py-2 border rounded hover:bg-gray-50"
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}
+```
+
+#### Detail Component
+
+Generated when GET (single) endpoints exist.
+
+**Example UserDetail.tsx:**
+
+```tsx
+import React, { useEffect, useState } from 'react';
+import type { User } from '../../client/types';
+import { useApiClient } from '../../app/context/ApiContext';
+import { LoadingSpinner } from '../shared/LoadingSpinner';
+import { ErrorDisplay } from '../shared/ErrorDisplay';
+
+export interface UserDetailProps {
+  userId: string;
+  onEdit?: (user: User) => void;
+  onDelete?: (user: User) => void;
+  className?: string;
+}
+
+export function UserDetail({
+  userId,
+  onEdit,
+  onDelete,
+  className = '',
+}: UserDetailProps) {
+  const client = useApiClient();
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchUser = async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getUser(userId);
+      setUser(data);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchUser();
+  }, [userId]);
+
+  if (loading) {
+    return <LoadingSpinner className="py-8" />;
+  }
+
+  if (error) {
+    return <ErrorDisplay error={error} onRetry={fetchUser} />;
+  }
+
+  if (!user) {
+    return <div className="text-gray-500">User not found</div>;
+  }
+
+  const handleDelete = async () => {
+    if (!confirm('Are you sure you want to delete this user?')) return;
+    try {
+      await client.deleteUser(userId);
+      onDelete?.(user);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+
+  return (
+    <div className={`bg-white rounded-lg shadow ${className}`}>
+      <div className="px-6 py-4 border-b">
+        <h2 className="text-xl font-semibold">
+          {user.firstName} {user.lastName}
+        </h2>
+        <p className="text-gray-500">{user.email}</p>
+      </div>
+
+      <dl className="px-6 py-4 space-y-3">
+        <div className="flex">
+          <dt className="w-32 text-gray-500">ID</dt>
+          <dd className="font-mono text-sm">{user.id}</dd>
+        </div>
+        <div className="flex">
+          <dt className="w-32 text-gray-500">Role</dt>
+          <dd>
+            <span className="px-2 py-1 text-xs rounded bg-blue-100 text-blue-700">
+              {user.role}
+            </span>
+          </dd>
+        </div>
+        <div className="flex">
+          <dt className="w-32 text-gray-500">Created</dt>
+          <dd>{new Date(user.createdAt).toLocaleDateString()}</dd>
+        </div>
+        {user.updatedAt && (
+          <div className="flex">
+            <dt className="w-32 text-gray-500">Updated</dt>
+            <dd>{new Date(user.updatedAt).toLocaleDateString()}</dd>
+          </div>
+        )}
+      </dl>
+
+      <div className="px-6 py-4 border-t flex gap-3">
+        {onEdit && (
+          <button
+            onClick={() => onEdit(user)}
+            className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
+          >
+            Edit
+          </button>
+        )}
+        {onDelete && (
+          <button
+            onClick={handleDelete}
+            className="px-4 py-2 border border-red-300 text-red-600 rounded hover:bg-red-50"
+          >
+            Delete
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+#### List Component
+
+Generated when GET (list) endpoints exist.
+
+**Example UserList.tsx:**
+
+```tsx
+import React, { useEffect, useState, useCallback } from 'react';
+import type { User, UserListResponse } from '../../client/types';
+import { useApiClient } from '../../app/context/ApiContext';
+import { LoadingSpinner } from '../shared/LoadingSpinner';
+import { ErrorDisplay } from '../shared/ErrorDisplay';
+import { Pagination } from '../shared/Pagination';
+
+export interface UserListProps {
+  onSelect?: (user: User) => void;
+  className?: string;
+}
+
+export function UserList({ onSelect, className = '' }: UserListProps) {
+  const client = useApiClient();
+  const [data, setData] = useState<UserListResponse | null>(null);
+  const [page, setPage] = useState(1);
+  const [search, setSearch] = useState('');
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const pageSize = 10;
+
+  const fetchUsers = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const response = await client.listUsers({
+        page,
+        pageSize,
+        search: search || undefined,
+      });
+      setData(response);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setLoading(false);
+    }
+  }, [client, page, pageSize, search]);
+
+  useEffect(() => {
+    fetchUsers();
+  }, [fetchUsers]);
+
+  const handleSearch = (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setPage(1);
+    fetchUsers();
+  };
+
+  return (
+    <div className={`bg-white rounded-lg shadow ${className}`}>
+      <div className="px-6 py-4 border-b">
+        <form onSubmit={handleSearch} className="flex gap-2">
+          <input
+            type="search"
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            placeholder="Search users..."
+            className="flex-1 px-3 py-2 border rounded focus:ring-2 focus:ring-blue-500"
+          />
+          <button
+            type="submit"
+            className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
+          >
+            Search
+          </button>
+        </form>
+      </div>
+
+      {loading ? (
+        <LoadingSpinner className="py-8" />
+      ) : error ? (
+        <ErrorDisplay error={error} onRetry={fetchUsers} className="m-4" />
+      ) : !data || data.items.length === 0 ? (
+        <div className="px-6 py-8 text-center text-gray-500">
+          No users found
+        </div>
+      ) : (
+        <>
+          <table className="w-full">
+            <thead className="bg-gray-50">
+              <tr>
+                <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase">
+                  Name
+                </th>
+                <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase">
+                  Email
+                </th>
+                <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase">
+                  Role
+                </th>
+                <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase">
+                  Created
+                </th>
+              </tr>
+            </thead>
+            <tbody className="divide-y">
+              {data.items.map((user) => (
+                <tr
+                  key={user.id}
+                  onClick={() => onSelect?.(user)}
+                  className={onSelect ? 'cursor-pointer hover:bg-gray-50' : ''}
+                >
+                  <td className="px-6 py-4">
+                    {user.firstName} {user.lastName}
+                  </td>
+                  <td className="px-6 py-4 text-gray-500">{user.email}</td>
+                  <td className="px-6 py-4">
+                    <span className="px-2 py-1 text-xs rounded bg-blue-100 text-blue-700">
+                      {user.role}
+                    </span>
+                  </td>
+                  <td className="px-6 py-4 text-gray-500">
+                    {new Date(user.createdAt).toLocaleDateString()}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+
+          <Pagination
+            page={page}
+            pageSize={pageSize}
+            total={data.total}
+            onPageChange={setPage}
+            className="border-t"
+          />
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+### Step 4: Generate Barrel Exports
+
+**components/<SchemaName>/index.ts:**
+
+```typescript
+export { UserForm } from './UserForm';
+export type { UserFormProps } from './UserForm';
+export { UserDetail } from './UserDetail';
+export type { UserDetailProps } from './UserDetail';
+export { UserList } from './UserList';
+export type { UserListProps } from './UserList';
+```
+
+**components/shared/index.ts:**
+
+```typescript
+export { LoadingSpinner } from './LoadingSpinner';
+export type { LoadingSpinnerProps } from './LoadingSpinner';
+export { ErrorDisplay } from './ErrorDisplay';
+export type { ErrorDisplayProps } from './ErrorDisplay';
+export { Pagination } from './Pagination';
+export type { PaginationProps } from './Pagination';
+```
+
+**components/index.ts:**
+
+```typescript
+export * from './User';
+// ... other schema exports
+export * from './shared';
+```
+
+### Step 5: Verify Output
+
+Run the verification scripts:
+
+```bash
+# Lint the generated code
+./scripts/lint-generated.sh
+
+# Verify components match client types
+python scripts/verify-components.py client/ components/
+```
+
+## Component Conventions
+
+1. **API Client via Context** — Components receive the client through React context, not props
+2. **Loading States** — All data-fetching components show a spinner while loading
+3. **Error Handling** — All components display errors with retry option
+4. **Empty States** — List components show appropriate message when no data
+5. **Accessibility** — Labels linked to inputs, semantic HTML
+6. **Styling** — Tailwind CSS classes (no UI framework dependency)
+
+## Output Files
+
+| Directory | Contents |
+|-----------|----------|
+| `components/<Schema>/` | Form, Detail, List components per schema |
+| `components/shared/` | LoadingSpinner, ErrorDisplay, Pagination |
+| `components/index.ts` | Top-level barrel export |
+
+## Next Steps
+
+After generating components, proceed to:
+
+1. **Generate Frontend** — Create application shell and routing
+2. **Generate Tests** — Create component tests
+
+See [../generate-frontend/SKILL.md](../generate-frontend/SKILL.md)
diff --git a/plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md b/plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md
new file mode 100644
index 0000000..9872dc9
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md
@@ -0,0 +1,769 @@
+---
+name: openapi-generate-frontend
+description: Generate a complete React frontend application from components and API client. Creates routing, context, and purpose-built UI.
+license: MIT
+compatibility: Requires React 18+, TypeScript 5+, React Router 6+
+triggers:
+  - openapi frontend
+  - generate react app
+  - api to app
+  - frontend from api
+---
+
+Generate a complete React frontend application from the component library.
+
+## Overview
+
+This skill produces a full React application:
+
+- `app/App.tsx` — Main app shell with routing
+- `app/pages/` — One page per major resource/workflow
+- `app/context/` — API client provider, auth context
+- `app/hooks/` — Custom hooks for data fetching
+- `app/utils/localStorage.ts` — UI state persistence helpers
+
+## Prerequisites
+
+- Generated TypeScript client (from generate-client phase)
+- Generated React components (from generate-components phase)
+- React 18+, React Router 6+
+
+## Workflow
+
+### Step 1: Analyze the API Purpose
+
+Read the OpenAPI spec's `info.title`, `info.description`, and endpoint patterns to infer what the app is *for*:
+
+| API Pattern | Frontend Style |
+|-------------|----------------|
+| **CRUD API** (resources with full CRUD) | Dashboard with list pages, forms, detail views |
+| **Data/Analytics API** (read-heavy, aggregations) | Dashboard with charts, filters, summary cards |
+| **Auth-heavy API** (user management, permissions) | Login flow, user profile, admin panel |
+| **Workflow API** (status transitions, steps) | Step-by-step wizards, status tracking |
+| **Search API** (query endpoints, filters) | Search-first UI with results and filters |
+| **Mixed** | Sidebar navigation grouping by resource tag |
+
+**Before generating, explain the inference to the user:**
+
+> "Based on the API, this appears to be a **user management system** with CRUD operations for users, roles, and permissions. I'll generate a dashboard-style app with:
+> - Login/logout flow (OAuth2 detected)
+> - Users list page with search
+> - User detail and edit pages
+> - Roles management section
+>
+> Does this match your expectations, or would you like a different approach?"
+
+### Step 2: Generate Context Providers
+
+**app/context/ApiContext.tsx:**
+
+```tsx
+import React, { createContext, useContext, useMemo } from 'react';
+import { ApiClient, ApiConfig } from '../../client';
+
+const ApiContext = createContext<ApiClient | null>(null);
+
+export interface ApiProviderProps {
+  config: ApiConfig;
+  children: React.ReactNode;
+}
+
+export function ApiProvider({ config, children }: ApiProviderProps) {
+  const client = useMemo(() => new ApiClient(config), [config]);
+
+  return <ApiContext.Provider value={client}>{children}</ApiContext.Provider>;
+}
+
+export function useApiClient(): ApiClient {
+  const client = useContext(ApiContext);
+  if (!client) {
+    throw new Error('useApiClient must be used within an ApiProvider');
+  }
+  return client;
+}
+```
+
+**app/context/AuthContext.tsx (if auth is present):**
+
+```tsx
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+} from 'react';
+import type { AuthConfig, OAuthToken } from '../../client';
+
+interface AuthState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  token: OAuthToken | null;
+  error: Error | null;
+}
+
+interface AuthContextValue extends AuthState {
+  login: () => void;
+  logout: () => void;
+  handleCallback: (code: string) => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+const STORAGE_KEY = 'auth_token';
+
+export interface AuthProviderProps {
+  children: React.ReactNode;
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+  const [state, setState] = useState<AuthState>({
+    isAuthenticated: false,
+    isLoading: true,
+    token: null,
+    error: null,
+  });
+
+  // Load token from storage on mount
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      try {
+        const token = JSON.parse(stored) as OAuthToken;
+        // Check if token is expired
+        if (!token.expiresAt || token.expiresAt > Date.now()) {
+          setState({
+            isAuthenticated: true,
+            isLoading: false,
+            token,
+            error: null,
+          });
+          return;
+        }
+      } catch {
+        localStorage.removeItem(STORAGE_KEY);
+      }
+    }
+    setState((prev) => ({ ...prev, isLoading: false }));
+  }, []);
+
+  const login = useCallback(() => {
+    // Redirect to OAuth authorization URL
+    // This URL should be constructed using OAuth2Manager from client/auth.ts
+    window.location.href = '/api/auth/login';
+  }, []);
+
+  const logout = useCallback(() => {
+    localStorage.removeItem(STORAGE_KEY);
+    setState({
+      isAuthenticated: false,
+      isLoading: false,
+      token: null,
+      error: null,
+    });
+  }, []);
+
+  const handleCallback = useCallback(async (code: string) => {
+    setState((prev) => ({ ...prev, isLoading: true, error: null }));
+    try {
+      // Exchange code for token
+      const response = await fetch('/api/auth/callback', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code }),
+      });
+      const token = (await response.json()) as OAuthToken;
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(token));
+      setState({
+        isAuthenticated: true,
+        isLoading: false,
+        token,
+        error: null,
+      });
+    } catch (err) {
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        error: err instanceof Error ? err : new Error(String(err)),
+      }));
+    }
+  }, []);
+
+  return (
+    <AuthContext.Provider
+      value={{ ...state, login, logout, handleCallback }}
+    >
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth(): AuthContextValue {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return context;
+}
+```
+
+**app/context/AuthGuard.tsx:**
+
+```tsx
+import React from 'react';
+import { Navigate, useLocation } from 'react-router-dom';
+import { useAuth } from './AuthContext';
+import { LoadingSpinner } from '../../components/shared';
+
+export interface AuthGuardProps {
+  children: React.ReactNode;
+}
+
+export function AuthGuard({ children }: AuthGuardProps) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <LoadingSpinner size="lg" />
+      </div>
+    );
+  }
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" state={{ from: location }} replace />;
+  }
+
+  return <>{children}</>;
+}
+```
+
+### Step 3: Generate Custom Hooks
+
+**app/hooks/useResource.ts:**
+
+```tsx
+import { useState, useEffect, useCallback } from 'react';
+
+interface UseResourceOptions<T> {
+  fetchFn: () => Promise<T>;
+  deps?: unknown[];
+}
+
+interface UseResourceResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+export function useResource<T>({
+  fetchFn,
+  deps = [],
+}: UseResourceOptions<T>): UseResourceResult<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetch = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const result = await fetchFn();
+      setData(result);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setLoading(false);
+    }
+  }, [fetchFn]);
+
+  useEffect(() => {
+    fetch();
+  }, [...deps, fetch]);
+
+  return { data, loading, error, refetch: fetch };
+}
+```
+
+**app/hooks/usePagination.ts:**
+
+```tsx
+import { useState, useCallback } from 'react';
+
+interface UsePaginationOptions {
+  initialPage?: number;
+  initialPageSize?: number;
+}
+
+interface UsePaginationResult {
+  page: number;
+  pageSize: number;
+  setPage: (page: number) => void;
+  setPageSize: (size: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  reset: () => void;
+}
+
+export function usePagination({
+  initialPage = 1,
+  initialPageSize = 10,
+}: UsePaginationOptions = {}): UsePaginationResult {
+  const [page, setPage] = useState(initialPage);
+  const [pageSize, setPageSize] = useState(initialPageSize);
+
+  const nextPage = useCallback(() => setPage((p) => p + 1), []);
+  const prevPage = useCallback(() => setPage((p) => Math.max(1, p - 1)), []);
+  const reset = useCallback(() => setPage(initialPage), [initialPage]);
+
+  return { page, pageSize, setPage, setPageSize, nextPage, prevPage, reset };
+}
+```
+
+### Step 4: Generate Utility Functions
+
+**app/utils/localStorage.ts:**
+
+```typescript
+const PREFIX = 'app_';
+
+export const storage = {
+  get<T>(key: string, defaultValue: T): T {
+    try {
+      const item = localStorage.getItem(PREFIX + key);
+      return item ? JSON.parse(item) : defaultValue;
+    } catch {
+      return defaultValue;
+    }
+  },
+
+  set<T>(key: string, value: T): void {
+    try {
+      localStorage.setItem(PREFIX + key, JSON.stringify(value));
+    } catch {
+      // Storage full or unavailable
+    }
+  },
+
+  remove(key: string): void {
+    localStorage.removeItem(PREFIX + key);
+  },
+
+  // UI preferences
+  getTheme(): 'light' | 'dark' {
+    return this.get('theme', 'light');
+  },
+
+  setTheme(theme: 'light' | 'dark'): void {
+    this.set('theme', theme);
+  },
+
+  getSidebarCollapsed(): boolean {
+    return this.get('sidebar_collapsed', false);
+  },
+
+  setSidebarCollapsed(collapsed: boolean): void {
+    this.set('sidebar_collapsed', collapsed);
+  },
+
+  getLastVisitedPage(): string | null {
+    return this.get('last_page', null);
+  },
+
+  setLastVisitedPage(path: string): void {
+    this.set('last_page', path);
+  },
+};
+```
+
+### Step 5: Generate Pages
+
+Create pages based on API structure. For a CRUD API:
+
+**app/pages/UsersPage.tsx:**
+
+```tsx
+import React, { useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import type { User } from '../../client/types';
+import { UserList } from '../../components/User';
+
+export function UsersPage() {
+  const navigate = useNavigate();
+
+  const handleSelect = (user: User) => {
+    navigate(`/users/${user.id}`);
+  };
+
+  const handleCreate = () => {
+    navigate('/users/new');
+  };
+
+  return (
+    <div className="p-6">
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl font-bold">Users</h1>
+        <button
+          onClick={handleCreate}
+          className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
+        >
+          Create User
+        </button>
+      </div>
+
+      <UserList onSelect={handleSelect} />
+    </div>
+  );
+}
+```
+
+**app/pages/UserDetailPage.tsx:**
+
+```tsx
+import React from 'react';
+import { useParams, useNavigate } from 'react-router-dom';
+import type { User } from '../../client/types';
+import { UserDetail } from '../../components/User';
+
+export function UserDetailPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+
+  if (!id) {
+    return <div>User ID required</div>;
+  }
+
+  const handleEdit = (user: User) => {
+    navigate(`/users/${user.id}/edit`);
+  };
+
+  const handleDelete = () => {
+    navigate('/users');
+  };
+
+  return (
+    <div className="p-6">
+      <button
+        onClick={() => navigate('/users')}
+        className="mb-4 text-blue-600 hover:underline"
+      >
+        ← Back to Users
+      </button>
+
+      <UserDetail userId={id} onEdit={handleEdit} onDelete={handleDelete} />
+    </div>
+  );
+}
+```
+
+**app/pages/UserFormPage.tsx:**
+
+```tsx
+import React from 'react';
+import { useParams, useNavigate } from 'react-router-dom';
+import type { User } from '../../client/types';
+import { UserForm, UserDetail } from '../../components/User';
+import { useResource } from '../hooks/useResource';
+import { useApiClient } from '../context/ApiContext';
+import { LoadingSpinner, ErrorDisplay } from '../../components/shared';
+
+export function UserFormPage() {
+  const { id } = useParams<{ id: string }>();
+  const navigate = useNavigate();
+  const client = useApiClient();
+  const isEditMode = !!id;
+
+  const { data: user, loading, error } = useResource({
+    fetchFn: () => (id ? client.getUser(id) : Promise.resolve(null)),
+    deps: [id],
+  });
+
+  const handleSuccess = (savedUser: User) => {
+    navigate(`/users/${savedUser.id}`);
+  };
+
+  const handleCancel = () => {
+    navigate(id ? `/users/${id}` : '/users');
+  };
+
+  if (isEditMode && loading) {
+    return <LoadingSpinner className="py-8" />;
+  }
+
+  if (isEditMode && error) {
+    return <ErrorDisplay error={error} />;
+  }
+
+  return (
+    <div className="p-6 max-w-2xl">
+      <h1 className="text-2xl font-bold mb-6">
+        {isEditMode ? 'Edit User' : 'Create User'}
+      </h1>
+
+      <UserForm
+        user={user || undefined}
+        onSuccess={handleSuccess}
+        onCancel={handleCancel}
+      />
+    </div>
+  );
+}
+```
+
+**app/pages/LoginPage.tsx (if auth present):**
+
+```tsx
+import React, { useEffect } from 'react';
+import { useNavigate, useLocation } from 'react-router-dom';
+import { useAuth } from '../context/AuthContext';
+
+export function LoginPage() {
+  const { isAuthenticated, isLoading, login, error } = useAuth();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  const from = (location.state as { from?: Location })?.from?.pathname || '/';
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      navigate(from, { replace: true });
+    }
+  }, [isAuthenticated, navigate, from]);
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <div className="max-w-md w-full p-8 bg-white rounded-lg shadow">
+        <h1 className="text-2xl font-bold text-center mb-6">Sign In</h1>
+
+        {error && (
+          <div className="mb-4 p-3 bg-red-50 text-red-700 rounded">
+            {error.message}
+          </div>
+        )}
+
+        <button
+          onClick={login}
+          disabled={isLoading}
+          className="w-full py-3 bg-blue-600 text-white rounded hover:bg-blue-700 disabled:opacity-50"
+        >
+          {isLoading ? 'Signing in...' : 'Sign in with OAuth'}
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 6: Generate App Shell and Routing
+
+**app/App.tsx:**
+
+```tsx
+import React from 'react';
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import { ApiProvider } from './context/ApiContext';
+import { AuthProvider, AuthGuard } from './context/AuthContext';
+import { Layout } from './Layout';
+import { LoginPage } from './pages/LoginPage';
+import { UsersPage } from './pages/UsersPage';
+import { UserDetailPage } from './pages/UserDetailPage';
+import { UserFormPage } from './pages/UserFormPage';
+// Import other pages as needed
+
+const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000';
+
+export function App() {
+  return (
+    <BrowserRouter>
+      <ApiProvider config={{ baseUrl: API_BASE_URL }}>
+        <AuthProvider>
+          <Routes>
+            {/* Public routes */}
+            <Route path="/login" element={<LoginPage />} />
+
+            {/* Protected routes */}
+            <Route
+              path="/"
+              element={
+                <AuthGuard>
+                  <Layout />
+                </AuthGuard>
+              }
+            >
+              <Route index element={<Navigate to="/users" replace />} />
+              <Route path="users" element={<UsersPage />} />
+              <Route path="users/new" element={<UserFormPage />} />
+              <Route path="users/:id" element={<UserDetailPage />} />
+              <Route path="users/:id/edit" element={<UserFormPage />} />
+              {/* Add other resource routes */}
+            </Route>
+
+            {/* 404 */}
+            <Route path="*" element={<Navigate to="/" replace />} />
+          </Routes>
+        </AuthProvider>
+      </ApiProvider>
+    </BrowserRouter>
+  );
+}
+```
+
+**app/Layout.tsx:**
+
+```tsx
+import React, { useState } from 'react';
+import { Outlet, Link, useLocation } from 'react-router-dom';
+import { useAuth } from './context/AuthContext';
+import { storage } from './utils/localStorage';
+
+const NAV_ITEMS = [
+  { path: '/users', label: 'Users', icon: '👥' },
+  // Add more nav items based on API resources
+];
+
+export function Layout() {
+  const { logout } = useAuth();
+  const location = useLocation();
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(
+    storage.getSidebarCollapsed()
+  );
+
+  const toggleSidebar = () => {
+    const newState = !sidebarCollapsed;
+    setSidebarCollapsed(newState);
+    storage.setSidebarCollapsed(newState);
+  };
+
+  return (
+    <div className="min-h-screen flex">
+      {/* Sidebar */}
+      <aside
+        className={`bg-gray-800 text-white transition-all ${
+          sidebarCollapsed ? 'w-16' : 'w-64'
+        }`}
+      >
+        <div className="p-4 flex items-center justify-between">
+          {!sidebarCollapsed && (
+            <span className="font-bold text-lg">App Name</span>
+          )}
+          <button
+            onClick={toggleSidebar}
+            className="p-2 hover:bg-gray-700 rounded"
+          >
+            {sidebarCollapsed ? '→' : '←'}
+          </button>
+        </div>
+
+        <nav className="mt-4">
+          {NAV_ITEMS.map((item) => (
+            <Link
+              key={item.path}
+              to={item.path}
+              className={`flex items-center px-4 py-3 hover:bg-gray-700 ${
+                location.pathname.startsWith(item.path) ? 'bg-gray-700' : ''
+              }`}
+            >
+              <span className="text-xl">{item.icon}</span>
+              {!sidebarCollapsed && (
+                <span className="ml-3">{item.label}</span>
+              )}
+            </Link>
+          ))}
+        </nav>
+
+        <div className="absolute bottom-0 w-full p-4">
+          <button
+            onClick={logout}
+            className="w-full py-2 text-left hover:bg-gray-700 rounded px-2"
+          >
+            {sidebarCollapsed ? '🚪' : 'Sign Out'}
+          </button>
+        </div>
+      </aside>
+
+      {/* Main content */}
+      <main className="flex-1 bg-gray-50 overflow-auto">
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+```
+
+### Step 7: Generate Entry Point
+
+**app/main.tsx:**
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { App } from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+**app/index.css:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* Custom styles */
+body {
+  @apply bg-gray-50 text-gray-900;
+}
+```
+
+## UI Style Variations
+
+Based on API purpose, adjust the generated UI:
+
+### Analytics Dashboard
+
+- Summary cards at top with key metrics
+- Charts using a library like Recharts or Chart.js
+- Date range filters
+- Export functionality
+
+### Workflow App
+
+- Multi-step wizards for complex operations
+- Status badges and progress indicators
+- Timeline views for history
+- Action buttons based on current status
+
+### Search-First App
+
+- Prominent search bar
+- Faceted filters in sidebar
+- Infinite scroll or pagination
+- Result cards with key info
+
+## Output Files
+
+| Directory | Contents |
+|-----------|----------|
+| `app/App.tsx` | Main app with routing |
+| `app/Layout.tsx` | App shell with navigation |
+| `app/main.tsx` | Entry point |
+| `app/pages/` | Page components |
+| `app/context/` | API and Auth providers |
+| `app/hooks/` | Custom React hooks |
+| `app/utils/` | Helper functions |
+
+## Next Steps
+
+After generating the frontend, proceed to:
+
+1. **Generate Tests** — Create unit, integration, and e2e tests
+2. **Generate CI** — Create GitHub Actions workflows
+
+See [../generate-tests/SKILL.md](../generate-tests/SKILL.md)
diff --git a/plugins/openapi-to-frontend/skills/generate-tests/SKILL.md b/plugins/openapi-to-frontend/skills/generate-tests/SKILL.md
new file mode 100644
index 0000000..c9727f9
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/generate-tests/SKILL.md
@@ -0,0 +1,946 @@
+---
+name: openapi-generate-tests
+description: Generate comprehensive tests for the TypeScript client, React components, and frontend app. Includes unit, integration, and e2e tests.
+license: MIT
+compatibility: Requires Vitest or Jest, React Testing Library, Playwright
+triggers:
+  - openapi tests
+  - generate tests
+  - api tests
+  - frontend tests
+  - e2e tests
+---
+
+Generate comprehensive tests for the generated codebase.
+
+## Overview
+
+This skill produces three layers of tests:
+
+- `tests/unit/` — Unit tests for client methods and components
+- `tests/integration/` — Integration tests for component↔client flows
+- `tests/e2e/` — End-to-end tests (assumes running backend)
+- `tests/setup/` — Test configuration, fixtures, and mock factories
+
+## Prerequisites
+
+- Generated TypeScript client, components, and frontend
+- Node.js 18+
+- Test runner (Vitest recommended, Jest supported)
+- React Testing Library
+- Playwright for e2e
+
+## Workflow
+
+### Step 1: Set Up Test Infrastructure
+
+**tests/setup/vitest.config.ts:**
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./tests/setup/setupTests.ts'],
+    globals: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov'],
+      include: ['client/**/*.ts', 'components/**/*.tsx', 'app/**/*.tsx'],
+    },
+  },
+});
+```
+
+**tests/setup/setupTests.ts:**
+
+```typescript
+import '@testing-library/jest-dom';
+import { afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+
+// Cleanup after each test
+afterEach(() => {
+  cleanup();
+});
+
+// Mock fetch globally
+global.fetch = vi.fn();
+
+// Mock localStorage
+const localStorageMock = {
+  store: {} as Record<string, string>,
+  getItem: vi.fn((key: string) => localStorageMock.store[key] || null),
+  setItem: vi.fn((key: string, value: string) => {
+    localStorageMock.store[key] = value;
+  }),
+  removeItem: vi.fn((key: string) => {
+    delete localStorageMock.store[key];
+  }),
+  clear: vi.fn(() => {
+    localStorageMock.store = {};
+  }),
+};
+Object.defineProperty(window, 'localStorage', { value: localStorageMock });
+```
+
+### Step 2: Generate Mock Factories
+
+For each schema, generate a factory function that produces valid test data.
+
+**tests/setup/factories.ts:**
+
+```typescript
+import type {
+  User,
+  CreateUserRequest,
+  UpdateUserRequest,
+  UserRole,
+  UserListResponse,
+} from '../../client/types';
+
+let idCounter = 0;
+
+export function makeUser(overrides: Partial<User> = {}): User {
+  idCounter++;
+  return {
+    id: `user-${idCounter}`,
+    email: `user${idCounter}@example.com`,
+    firstName: `FirstName${idCounter}`,
+    lastName: `LastName${idCounter}`,
+    role: 'user' as UserRole,
+    createdAt: new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+export function makeCreateUserRequest(
+  overrides: Partial<CreateUserRequest> = {}
+): CreateUserRequest {
+  idCounter++;
+  return {
+    email: `newuser${idCounter}@example.com`,
+    firstName: `NewFirst${idCounter}`,
+    lastName: `NewLast${idCounter}`,
+    password: 'SecurePassword123!',
+    role: 'user',
+    ...overrides,
+  };
+}
+
+export function makeUpdateUserRequest(
+  overrides: Partial<UpdateUserRequest> = {}
+): UpdateUserRequest {
+  return {
+    firstName: 'UpdatedFirst',
+    lastName: 'UpdatedLast',
+    ...overrides,
+  };
+}
+
+export function makeUserListResponse(
+  users: User[] = [],
+  total?: number
+): UserListResponse {
+  return {
+    items: users,
+    total: total ?? users.length,
+    page: 1,
+    pageSize: 10,
+  };
+}
+
+// Reset counter between test files
+export function resetFactories(): void {
+  idCounter = 0;
+}
+```
+
+### Step 3: Generate Type Guards
+
+For each schema, generate runtime type checking for tests.
+
+**tests/setup/typeGuards.ts:**
+
+```typescript
+import type { User, UserRole } from '../../client/types';
+
+const USER_ROLES: UserRole[] = ['admin', 'user', 'guest'];
+
+export function isUser(value: unknown): value is User {
+  if (!value || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+
+  return (
+    typeof obj.id === 'string' &&
+    typeof obj.email === 'string' &&
+    typeof obj.firstName === 'string' &&
+    typeof obj.lastName === 'string' &&
+    typeof obj.role === 'string' &&
+    USER_ROLES.includes(obj.role as UserRole) &&
+    typeof obj.createdAt === 'string' &&
+    (obj.updatedAt === undefined || typeof obj.updatedAt === 'string')
+  );
+}
+
+export function isUserListResponse(value: unknown): value is {
+  items: User[];
+  total: number;
+  page: number;
+  pageSize: number;
+} {
+  if (!value || typeof value !== 'object') return false;
+  const obj = value as Record<string, unknown>;
+
+  return (
+    Array.isArray(obj.items) &&
+    obj.items.every(isUser) &&
+    typeof obj.total === 'number' &&
+    typeof obj.page === 'number' &&
+    typeof obj.pageSize === 'number'
+  );
+}
+```
+
+### Step 4: Generate Unit Tests
+
+#### Client Method Tests
+
+**tests/unit/client/api.test.ts:**
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ApiClient, ApiError } from '../../../client/api';
+import { makeUser, makeCreateUserRequest, makeUserListResponse } from '../../setup/factories';
+
+describe('ApiClient', () => {
+  let client: ApiClient;
+  const mockFetch = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    global.fetch = mockFetch;
+    client = new ApiClient({ baseUrl: 'https://api.example.com' });
+  });
+
+  describe('listUsers', () => {
+    it('should fetch users with pagination', async () => {
+      const users = [makeUser(), makeUser()];
+      const response = makeUserListResponse(users, 100);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(response),
+      });
+
+      const result = await client.listUsers({ page: 1, pageSize: 10 });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('/users'),
+        expect.objectContaining({ method: 'GET' })
+      );
+      expect(result.items).toHaveLength(2);
+      expect(result.total).toBe(100);
+    });
+
+    it('should include search parameter when provided', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(makeUserListResponse([])),
+      });
+
+      await client.listUsers({ search: 'john' });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('search=john'),
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe('getUser', () => {
+    it('should fetch a single user by ID', async () => {
+      const user = makeUser({ id: 'user-123' });
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(user),
+      });
+
+      const result = await client.getUser('user-123');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.example.com/users/user-123',
+        expect.objectContaining({ method: 'GET' })
+      );
+      expect(result.id).toBe('user-123');
+    });
+
+    it('should throw ApiError on 404', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: () => Promise.resolve('Not found'),
+      });
+
+      await expect(client.getUser('nonexistent')).rejects.toThrow(ApiError);
+    });
+  });
+
+  describe('createUser', () => {
+    it('should send POST request with user data', async () => {
+      const createData = makeCreateUserRequest();
+      const createdUser = makeUser({ email: createData.email });
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(createdUser),
+      });
+
+      const result = await client.createUser(createData);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.example.com/users',
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify(createData),
+        })
+      );
+      expect(result.email).toBe(createData.email);
+    });
+  });
+
+  describe('updateUser', () => {
+    it('should send PUT request with update data', async () => {
+      const user = makeUser();
+      const updateData = { firstName: 'Updated' };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ ...user, ...updateData }),
+      });
+
+      const result = await client.updateUser(user.id, updateData);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining(`/users/${user.id}`),
+        expect.objectContaining({
+          method: 'PUT',
+          body: JSON.stringify(updateData),
+        })
+      );
+      expect(result.firstName).toBe('Updated');
+    });
+  });
+
+  describe('deleteUser', () => {
+    it('should send DELETE request', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(undefined),
+      });
+
+      await client.deleteUser('user-123');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.example.com/users/user-123',
+        expect.objectContaining({ method: 'DELETE' })
+      );
+    });
+  });
+});
+```
+
+#### Type Guard Tests
+
+**tests/unit/client/typeGuards.test.ts:**
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { isUser, isUserListResponse } from '../../setup/typeGuards';
+import { makeUser, makeUserListResponse } from '../../setup/factories';
+
+describe('Type Guards', () => {
+  describe('isUser', () => {
+    it('should return true for valid user', () => {
+      expect(isUser(makeUser())).toBe(true);
+    });
+
+    it('should return false for null', () => {
+      expect(isUser(null)).toBe(false);
+    });
+
+    it('should return false for missing required fields', () => {
+      expect(isUser({ id: '123' })).toBe(false);
+    });
+
+    it('should return false for invalid role', () => {
+      const user = makeUser();
+      expect(isUser({ ...user, role: 'invalid' })).toBe(false);
+    });
+
+    it('should accept optional updatedAt', () => {
+      const user = makeUser({ updatedAt: new Date().toISOString() });
+      expect(isUser(user)).toBe(true);
+    });
+  });
+
+  describe('isUserListResponse', () => {
+    it('should return true for valid response', () => {
+      const response = makeUserListResponse([makeUser()]);
+      expect(isUserListResponse(response)).toBe(true);
+    });
+
+    it('should return false for invalid items', () => {
+      expect(isUserListResponse({ items: [{ invalid: true }] })).toBe(false);
+    });
+  });
+});
+```
+
+#### Component Unit Tests
+
+**tests/unit/components/UserForm.test.tsx:**
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { UserForm } from '../../../components/User/UserForm';
+import { ApiProvider } from '../../../app/context/ApiContext';
+import { makeUser } from '../../setup/factories';
+
+// Mock the API client
+const mockClient = {
+  createUser: vi.fn(),
+  updateUser: vi.fn(),
+};
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <ApiProvider config={{ baseUrl: 'http://test' }}>
+    {children}
+  </ApiProvider>
+);
+
+// Override useApiClient to return mock
+vi.mock('../../../app/context/ApiContext', async () => {
+  const actual = await vi.importActual('../../../app/context/ApiContext');
+  return {
+    ...actual,
+    useApiClient: () => mockClient,
+  };
+});
+
+describe('UserForm', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Create mode', () => {
+    it('should render empty form', () => {
+      render(<UserForm />, { wrapper });
+
+      expect(screen.getByLabelText(/email/i)).toHaveValue('');
+      expect(screen.getByLabelText(/first name/i)).toHaveValue('');
+      expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
+    });
+
+    it('should show Create User button', () => {
+      render(<UserForm />, { wrapper });
+
+      expect(screen.getByRole('button', { name: /create user/i })).toBeInTheDocument();
+    });
+
+    it('should call createUser on submit', async () => {
+      const user = userEvent.setup();
+      const newUser = makeUser();
+      mockClient.createUser.mockResolvedValueOnce(newUser);
+
+      render(<UserForm />, { wrapper });
+
+      await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+      await user.type(screen.getByLabelText(/first name/i), 'Test');
+      await user.type(screen.getByLabelText(/last name/i), 'User');
+      await user.type(screen.getByLabelText(/password/i), 'password123');
+      await user.click(screen.getByRole('button', { name: /create user/i }));
+
+      await waitFor(() => {
+        expect(mockClient.createUser).toHaveBeenCalledWith(
+          expect.objectContaining({
+            email: 'test@example.com',
+            firstName: 'Test',
+            lastName: 'User',
+          })
+        );
+      });
+    });
+  });
+
+  describe('Edit mode', () => {
+    it('should populate form with user data', () => {
+      const user = makeUser({ firstName: 'John', lastName: 'Doe' });
+      render(<UserForm user={user} />, { wrapper });
+
+      expect(screen.getByLabelText(/first name/i)).toHaveValue('John');
+      expect(screen.getByLabelText(/last name/i)).toHaveValue('Doe');
+    });
+
+    it('should disable email field in edit mode', () => {
+      const user = makeUser();
+      render(<UserForm user={user} />, { wrapper });
+
+      expect(screen.getByLabelText(/email/i)).toBeDisabled();
+    });
+
+    it('should hide password field in edit mode', () => {
+      const user = makeUser();
+      render(<UserForm user={user} />, { wrapper });
+
+      expect(screen.queryByLabelText(/password/i)).not.toBeInTheDocument();
+    });
+
+    it('should show Update User button', () => {
+      const user = makeUser();
+      render(<UserForm user={user} />, { wrapper });
+
+      expect(screen.getByRole('button', { name: /update user/i })).toBeInTheDocument();
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should display error message on API failure', async () => {
+      const user = userEvent.setup();
+      mockClient.createUser.mockRejectedValueOnce(new Error('Server error'));
+
+      render(<UserForm />, { wrapper });
+
+      await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+      await user.type(screen.getByLabelText(/first name/i), 'Test');
+      await user.type(screen.getByLabelText(/last name/i), 'User');
+      await user.type(screen.getByLabelText(/password/i), 'password123');
+      await user.click(screen.getByRole('button', { name: /create user/i }));
+
+      await waitFor(() => {
+        expect(screen.getByText(/server error/i)).toBeInTheDocument();
+      });
+    });
+  });
+});
+```
+
+### Step 5: Generate Integration Tests
+
+**tests/integration/UserFlow.test.tsx:**
+
+```tsx
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { ApiProvider } from '../../app/context/ApiContext';
+import { UsersPage } from '../../app/pages/UsersPage';
+import { UserDetailPage } from '../../app/pages/UserDetailPage';
+import { UserFormPage } from '../../app/pages/UserFormPage';
+import { makeUser, makeUserListResponse } from '../setup/factories';
+
+const mockClient = {
+  listUsers: vi.fn(),
+  getUser: vi.fn(),
+  createUser: vi.fn(),
+  updateUser: vi.fn(),
+  deleteUser: vi.fn(),
+};
+
+vi.mock('../../app/context/ApiContext', async () => {
+  const actual = await vi.importActual('../../app/context/ApiContext');
+  return {
+    ...actual,
+    useApiClient: () => mockClient,
+  };
+});
+
+const renderWithRouter = (initialRoute: string) => {
+  return render(
+    <MemoryRouter initialEntries={[initialRoute]}>
+      <ApiProvider config={{ baseUrl: 'http://test' }}>
+        <Routes>
+          <Route path="/users" element={<UsersPage />} />
+          <Route path="/users/new" element={<UserFormPage />} />
+          <Route path="/users/:id" element={<UserDetailPage />} />
+          <Route path="/users/:id/edit" element={<UserFormPage />} />
+        </Routes>
+      </ApiProvider>
+    </MemoryRouter>
+  );
+};
+
+describe('User Flow Integration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should navigate from list to detail view', async () => {
+    const users = [makeUser({ id: 'user-1', firstName: 'John' })];
+    mockClient.listUsers.mockResolvedValue(makeUserListResponse(users));
+    mockClient.getUser.mockResolvedValue(users[0]);
+
+    const user = userEvent.setup();
+    renderWithRouter('/users');
+
+    await waitFor(() => {
+      expect(screen.getByText('John')).toBeInTheDocument();
+    });
+
+    await user.click(screen.getByText('John'));
+
+    await waitFor(() => {
+      expect(mockClient.getUser).toHaveBeenCalledWith('user-1');
+    });
+  });
+
+  it('should create a new user and navigate to detail', async () => {
+    const newUser = makeUser({ id: 'new-user' });
+    mockClient.createUser.mockResolvedValue(newUser);
+
+    const user = userEvent.setup();
+    renderWithRouter('/users/new');
+
+    await user.type(screen.getByLabelText(/email/i), 'new@example.com');
+    await user.type(screen.getByLabelText(/first name/i), 'New');
+    await user.type(screen.getByLabelText(/last name/i), 'User');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /create/i }));
+
+    await waitFor(() => {
+      expect(mockClient.createUser).toHaveBeenCalled();
+    });
+  });
+
+  it('should delete user and return to list', async () => {
+    const user = makeUser({ id: 'user-to-delete' });
+    mockClient.getUser.mockResolvedValue(user);
+    mockClient.deleteUser.mockResolvedValue(undefined);
+
+    // Mock window.confirm
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+
+    const userAction = userEvent.setup();
+    renderWithRouter('/users/user-to-delete');
+
+    await waitFor(() => {
+      expect(screen.getByText(user.firstName)).toBeInTheDocument();
+    });
+
+    await userAction.click(screen.getByRole('button', { name: /delete/i }));
+
+    await waitFor(() => {
+      expect(mockClient.deleteUser).toHaveBeenCalledWith('user-to-delete');
+    });
+  });
+});
+```
+
+### Step 6: Generate E2E Tests
+
+**tests/e2e/playwright.config.ts:**
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.E2E_BASE_URL || 'http://localhost:5173',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+**tests/e2e/smoke.spec.ts:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Smoke Tests', () => {
+  test('homepage loads', async ({ page }) => {
+    await page.goto('/');
+    await expect(page).toHaveTitle(/App/);
+  });
+
+  test('users page loads', async ({ page }) => {
+    await page.goto('/users');
+    await expect(page.getByRole('heading', { name: /users/i })).toBeVisible();
+  });
+
+  test('no console errors on main pages', async ({ page }) => {
+    const errors: string[] = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        errors.push(msg.text());
+      }
+    });
+
+    await page.goto('/users');
+    await page.waitForLoadState('networkidle');
+
+    expect(errors).toHaveLength(0);
+  });
+});
+```
+
+**tests/e2e/users.spec.ts:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('User Management', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login if auth is required
+    // await page.goto('/login');
+    // await page.fill('[name="email"]', 'test@example.com');
+    // ...
+  });
+
+  test('can view user list', async ({ page }) => {
+    await page.goto('/users');
+
+    await expect(page.getByRole('table')).toBeVisible();
+    // Or check for at least one user row
+    await expect(page.locator('tbody tr').first()).toBeVisible();
+  });
+
+  test('can create a new user', async ({ page }) => {
+    await page.goto('/users');
+    await page.click('text=Create User');
+
+    await page.fill('[name="email"]', `test-${Date.now()}@example.com`);
+    await page.fill('[name="firstName"]', 'E2E');
+    await page.fill('[name="lastName"]', 'TestUser');
+    await page.fill('[name="password"]', 'SecurePass123!');
+    await page.click('button[type="submit"]');
+
+    // Should navigate to detail page
+    await expect(page.getByText('E2E TestUser')).toBeVisible();
+  });
+
+  test('can edit a user', async ({ page }) => {
+    // First, get an existing user
+    await page.goto('/users');
+    await page.locator('tbody tr').first().click();
+
+    // Click edit
+    await page.click('text=Edit');
+
+    // Update name
+    await page.fill('[name="firstName"]', 'UpdatedName');
+    await page.click('button[type="submit"]');
+
+    // Verify update
+    await expect(page.getByText('UpdatedName')).toBeVisible();
+  });
+
+  test('can delete a user', async ({ page }) => {
+    await page.goto('/users');
+
+    // Get user count before
+    const countBefore = await page.locator('tbody tr').count();
+
+    // Click first user
+    await page.locator('tbody tr').first().click();
+
+    // Delete
+    page.on('dialog', (dialog) => dialog.accept());
+    await page.click('text=Delete');
+
+    // Should be back on list
+    await expect(page).toHaveURL('/users');
+
+    // Count should decrease
+    const countAfter = await page.locator('tbody tr').count();
+    expect(countAfter).toBeLessThan(countBefore);
+  });
+
+  test('handles validation errors', async ({ page }) => {
+    await page.goto('/users/new');
+
+    // Submit empty form
+    await page.click('button[type="submit"]');
+
+    // Should show validation
+    await expect(page.locator('[name="email"]:invalid')).toBeVisible();
+  });
+
+  test('handles API errors gracefully', async ({ page }) => {
+    // Navigate to non-existent user
+    await page.goto('/users/nonexistent-id');
+
+    // Should show error
+    await expect(page.getByText(/error|not found/i)).toBeVisible();
+  });
+});
+```
+
+**tests/e2e/auth.spec.ts (if auth present):**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication', () => {
+  test('redirects to login when not authenticated', async ({ page }) => {
+    await page.goto('/users');
+    await expect(page).toHaveURL(/\/login/);
+  });
+
+  test('can log in', async ({ page }) => {
+    await page.goto('/login');
+    await page.click('text=Sign in');
+
+    // Handle OAuth redirect (mock or real)
+    // ...
+
+    await expect(page).toHaveURL('/');
+  });
+
+  test('can log out', async ({ page }) => {
+    // Assume logged in
+    await page.goto('/');
+    await page.click('text=Sign Out');
+
+    await expect(page).toHaveURL(/\/login/);
+  });
+
+  test('protected routes require auth', async ({ page }) => {
+    // Clear any auth
+    await page.evaluate(() => localStorage.clear());
+
+    await page.goto('/users');
+    await expect(page).toHaveURL(/\/login/);
+  });
+});
+```
+
+### Step 7: Generate E2E Backend Startup Script
+
+**tests/e2e/start-server.sh:**
+
+```bash
+#!/bin/bash
+# E2E Backend Startup Script
+# Auto-generated based on detected backend type
+
+set -e
+
+echo "Starting backend for e2e tests..."
+
+# Strategy: Docker Compose (if available)
+if [ -f "docker-compose.yml" ] || [ -f "../docker-compose.yml" ]; then
+    echo "Using Docker Compose..."
+    docker compose up -d
+    
+    # Wait for health check
+    for i in {1..30}; do
+        if curl -s http://localhost:3000/health > /dev/null; then
+            echo "Backend ready!"
+            exit 0
+        fi
+        echo "Waiting for backend... ($i/30)"
+        sleep 2
+    done
+    echo "Backend failed to start"
+    exit 1
+fi
+
+# Strategy: Node.js backend
+if [ -f "package.json" ] && grep -q '"start"' package.json; then
+    echo "Using npm start..."
+    npm start &
+    SERVER_PID=$!
+    
+    # Wait for server
+    for i in {1..30}; do
+        if curl -s http://localhost:3000 > /dev/null; then
+            echo "Backend ready! (PID: $SERVER_PID)"
+            exit 0
+        fi
+        sleep 1
+    done
+    exit 1
+fi
+
+# Strategy: Python Django
+if [ -f "manage.py" ]; then
+    echo "Using Django runserver..."
+    python manage.py runserver 0.0.0.0:3000 &
+    sleep 5
+    exit 0
+fi
+
+# Strategy: Mock server with Prism
+if command -v prism &> /dev/null; then
+    echo "Using Prism mock server..."
+    prism mock openapi.yaml --port 3000 &
+    sleep 3
+    exit 0
+fi
+
+# Fallback: Check E2E_BASE_URL
+if [ -n "$E2E_BASE_URL" ]; then
+    echo "Using external backend at $E2E_BASE_URL"
+    exit 0
+fi
+
+echo "No backend startup method found!"
+echo "Please set E2E_BASE_URL or add a docker-compose.yml"
+exit 1
+```
+
+## Test Scripts in package.json
+
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  }
+}
+```
+
+## Output Files
+
+| Directory | Contents |
+|-----------|----------|
+| `tests/setup/` | Config, factories, type guards |
+| `tests/unit/client/` | API client tests |
+| `tests/unit/components/` | Component tests |
+| `tests/integration/` | Flow tests |
+| `tests/e2e/` | Playwright tests |
+
+## Next Steps
+
+After generating tests, proceed to:
+
+1. **Generate CI** — Create GitHub Actions to run these tests
+
+See [../generate-ci/SKILL.md](../generate-ci/SKILL.md)
diff --git a/plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md b/plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md
new file mode 100644
index 0000000..dab84e5
--- /dev/null
+++ b/plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md
@@ -0,0 +1,456 @@
+---
+name: openapi-update-from-spec
+description: Apply incremental updates to generated code when the OpenAPI spec changes. Makes surgical edits rather than regenerating.
+license: MIT
+compatibility: Requires existing generated codebase from this plugin
+triggers:
+  - openapi update
+  - spec changed
+  - update from spec
+  - incremental update
+  - api changed
+---
+
+Apply incremental updates when the OpenAPI spec changes.
+
+## Overview
+
+Instead of regenerating all code when the spec changes, this skill:
+
+1. Diffs the old and new spec versions
+2. Classifies each change into a type (see taxonomy)
+3. Applies targeted edits to existing files
+4. Verifies the result compiles and is consistent
+
+## Prerequisites
+
+- Previously generated code (client, components, frontend)
+- Both old and new OpenAPI spec files
+- The spec-differ agent (see `agents/spec-differ.md`)
+
+## Workflow
+
+### Step 1: Diff the Specs
+
+Use the spec-differ agent to compare versions:
+
+```
+@spec-differ old-spec.yaml new-spec.yaml
+```
+
+The agent outputs a structured list of changes:
+
+```json
+{
+  "changes": [
+    {
+      "type": "schema_added",
+      "path": "components/schemas/Order",
+      "details": { "fields": ["id", "userId", "items", "status", "createdAt"] }
+    },
+    {
+      "type": "endpoint_added",
+      "path": "paths./orders.get",
+      "details": { "method": "GET", "operationId": "listOrders" }
+    },
+    {
+      "type": "field_added",
+      "path": "components/schemas/User.properties.phoneNumber",
+      "details": { "type": "string", "required": false }
+    }
+  ]
+}
+```
+
+### Step 2: Apply Changes by Type
+
+For each change, apply the corresponding update strategy:
+
+---
+
+#### Schema Added
+
+**Impact:** Client → Components → (Maybe) Frontend
+
+**Actions:**
+
+1. **types.ts**: Add new interface at end of file
+   ```typescript
+   export interface Order {
+     id: string;
+     userId: string;
+     items: OrderItem[];
+     status: OrderStatus;
+     createdAt: string;
+   }
+   ```
+
+2. **api.ts**: Add methods if endpoints exist for this schema
+   ```typescript
+   async listOrders(params?: ListOrdersParams): Promise<OrderListResponse> {
+     return this.request('GET', '/orders', { params });
+   }
+   ```
+
+3. **components/**: Create new directory with Form/Detail/List components
+   - `components/Order/OrderForm.tsx`
+   - `components/Order/OrderDetail.tsx`
+   - `components/Order/OrderList.tsx`
+   - `components/Order/index.ts`
+
+4. **components/index.ts**: Add export
+   ```typescript
+   export * from './Order';
+   ```
+
+5. **Frontend (if needed)**: Add page and route for new resource
+   - `app/pages/OrdersPage.tsx`
+   - Update `App.tsx` with new routes
+   - Update `Layout.tsx` navigation
+
+---
+
+#### Schema Removed
+
+**Impact:** Client → Components → Frontend
+
+**Actions:**
+
+1. **types.ts**: Remove interface and any references
+   - Search for `interface SchemaName` and delete
+   - Search for imports/usages and remove
+
+2. **api.ts**: Remove methods that used this schema
+   - Delete methods returning or accepting this type
+   - Update imports
+
+3. **components/**: Delete entire directory
+   ```bash
+   rm -rf components/SchemaName/
+   ```
+
+4. **components/index.ts**: Remove export line
+
+5. **Frontend**: Remove page, route, and navigation
+   - Delete `app/pages/SchemaNamePage.tsx`
+   - Remove routes from `App.tsx`
+   - Remove nav item from `Layout.tsx`
+
+6. **Tests**: Remove test files for this schema
+   ```bash
+   rm tests/unit/components/SchemaName.test.tsx
+   rm tests/integration/SchemaNameFlow.test.tsx
+   ```
+
+---
+
+#### Schema Field Added
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **types.ts**: Add field to interface
+   ```typescript
+   // Find interface
+   export interface User {
+     id: string;
+     email: string;
+     // ADD HERE:
+     phoneNumber?: string;
+   }
+   ```
+
+2. **Components**: Add field to Form and Detail
+   
+   **Form** — Add input field:
+   ```tsx
+   <div>
+     <label htmlFor="phoneNumber">Phone Number</label>
+     <input
+       type="tel"
+       id="phoneNumber"
+       name="phoneNumber"
+       value={formData.phoneNumber || ''}
+       onChange={handleChange}
+     />
+   </div>
+   ```
+   
+   **Detail** — Add display row:
+   ```tsx
+   {user.phoneNumber && (
+     <div className="flex">
+       <dt className="w-32 text-gray-500">Phone</dt>
+       <dd>{user.phoneNumber}</dd>
+     </div>
+   )}
+   ```
+   
+   **List** — Add column if important field:
+   ```tsx
+   <th>Phone</th>
+   // ...
+   <td>{user.phoneNumber}</td>
+   ```
+
+3. **Tests**: Update factories and tests
+   ```typescript
+   // factories.ts
+   export function makeUser(overrides = {}) {
+     return {
+       // ... existing fields
+       phoneNumber: null,  // ADD
+       ...overrides
+     };
+   }
+   ```
+
+---
+
+#### Schema Field Removed
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **types.ts**: Remove field from interface
+
+2. **Components**: Remove from Form, Detail, List
+   - Search for field name and remove
+   - Remove associated label, input, display
+
+3. **Tests**: Update factories and test assertions
+
+---
+
+#### Schema Field Type Changed
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **types.ts**: Update field type
+   ```typescript
+   // Before: status: string;
+   // After:  status: OrderStatus;
+   ```
+
+2. **Components**: Update input type if needed
+   - `string` → `enum`: Change text input to select
+   - `number` → `string`: Change number input to text
+   - `boolean` → `string`: Change checkbox to text
+
+3. **Tests**: Update type guards and assertions
+
+---
+
+#### Endpoint Added
+
+**Impact:** Client → (Maybe) Components → (Maybe) Frontend
+
+**Actions:**
+
+1. **api.ts**: Add method
+   ```typescript
+   async cancelOrder(id: string): Promise<Order> {
+     return this.request('POST', `/orders/${id}/cancel`);
+   }
+   ```
+
+2. **Components** (if creates new capability):
+   - GET list → Add List component if missing
+   - POST → Add Form component if missing
+   - Add action buttons (cancel, approve, etc.)
+
+3. **Frontend** (if new resource):
+   - Add page and route
+
+---
+
+#### Endpoint Removed
+
+**Impact:** Client → Components → Frontend
+
+**Actions:**
+
+1. **api.ts**: Remove method
+
+2. **Components**: Remove functionality that depends on it
+   - If DELETE removed → hide delete button
+   - If POST removed → hide create button
+
+3. **Frontend**: Update UI to reflect missing capability
+
+---
+
+#### Endpoint Parameters Changed
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **api.ts**: Update method signature
+   ```typescript
+   // Before: async listOrders(params?: { page?: number })
+   // After:  async listOrders(params?: { page?: number; status?: OrderStatus })
+   ```
+
+2. **Components**: Update to use new params
+   - Add filters for new query params
+   - Update form fields for new body params
+
+---
+
+#### Endpoint Response Changed
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **api.ts**: Update return type
+
+2. **types.ts**: Update response interface if it changed
+
+3. **Components**: Update rendering to handle new shape
+
+---
+
+#### Auth Method Added/Changed/Removed
+
+**Impact:** Client → Frontend
+
+**Actions:**
+
+1. **auth.ts**: Add/update/remove auth handler
+
+2. **Frontend**:
+   - Added OAuth2 → Add login pages if not present
+   - Removed all auth → Remove login flow and guards
+   - Changed → Update login UI accordingly
+
+---
+
+#### Enum Values Changed
+
+**Impact:** Client → Components
+
+**Actions:**
+
+1. **types.ts**: Update union type or enum
+   ```typescript
+   // Before: type Status = 'pending' | 'active';
+   // After:  type Status = 'pending' | 'active' | 'suspended';
+   ```
+
+2. **Components**: Update select options
+   ```tsx
+   const STATUS_OPTIONS = ['pending', 'active', 'suspended'];
+   ```
+
+---
+
+### Step 3: Verify Changes
+
+After applying updates:
+
+```bash
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+
+# Run verification scripts
+python scripts/verify-coverage.py new-spec.yaml client/
+python scripts/verify-components.py client/ components/
+
+# Run tests
+npm run test:unit
+npm run test:integration
+```
+
+### Step 4: Report Summary
+
+Output a summary of changes made:
+
+```
+## Update Summary
+
+Applied 5 changes from spec diff:
+
+### Added
+- Interface `Order` in types.ts
+- Method `listOrders` in api.ts
+- Components: Order/OrderForm.tsx, Order/OrderDetail.tsx, Order/OrderList.tsx
+- Page: app/pages/OrdersPage.tsx
+- Route: /orders
+
+### Modified
+- Interface `User`: added field `phoneNumber`
+- Component UserForm.tsx: added phone input
+
+### Verification
+✓ Type check passed
+✓ Lint passed
+✓ Coverage verification passed
+✓ Unit tests passed
+```
+
+## Change Taxonomy Reference
+
+| Change Type | Scope | Strategy |
+|-------------|-------|----------|
+| schema_added | Client → Components → Frontend | Add interface, methods, components, page |
+| schema_removed | Client → Components → Frontend | Remove all related code |
+| field_added | Client → Components | Add to interface and forms/displays |
+| field_removed | Client → Components | Remove from interface and UI |
+| field_type_changed | Client → Components | Update type and input component |
+| endpoint_added | Client → Components | Add method, maybe add component |
+| endpoint_removed | Client → Components | Remove method, disable UI |
+| endpoint_params_changed | Client → Components | Update signature and UI |
+| endpoint_response_changed | Client → Components | Update return type and rendering |
+| auth_added | Client → Frontend | Add auth handler and login flow |
+| auth_removed | Client → Frontend | Remove auth and guards |
+| auth_changed | Client → Frontend | Update auth handler |
+| enum_changed | Client → Components | Update type and select options |
+| description_changed | None | No code changes |
+
+## Best Practices
+
+1. **Don't regenerate** — Make surgical edits to preserve user customizations
+2. **Preserve formatting** — Match existing code style
+3. **Update tests** — Don't forget to update factories and assertions
+4. **Verify completeness** — Run coverage scripts after every update
+5. **Commit atomically** — One commit per change type for easy rollback
+
+## Edge Cases
+
+### Breaking Changes
+
+If a change would break existing functionality:
+
+1. Warn the user before applying
+2. Suggest migration steps
+3. Add TODO comments for manual review
+
+### Ambiguous Changes
+
+If the impact is unclear:
+
+1. Ask the user for clarification
+2. Show both options and let them choose
+3. Default to the safer option
+
+### Conflicting Changes
+
+If user has modified generated code:
+
+1. Detect modifications (compare to expected output)
+2. Show conflicts
+3. Let user merge manually or accept overwrite
+
+## See Also
+
+- [../agents/spec-differ.md](../../agents/spec-differ.md) — The subagent that produces the diff
+- [../../references/change-taxonomy.md](../../references/change-taxonomy.md) — Full change type reference

From 573b98552e5a3e0d67f3a5273f7ab3617f1ec216 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:09:21 +0000
Subject: [PATCH 2/8] Add sample GitHub Actions workflow for automated
 generation

- Uses OpenHands CLI in headless mode via Docker
- Snapshots OpenAPI spec to track changes between runs
- Initial run: generates full codebase
- Subsequent runs: applies incremental updates
- Creates PR with generated/updated code

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 232 ++++++++++++++++++++++++++
 1 file changed, 232 insertions(+)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index d43ef9c..c7fffc6 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -209,6 +209,238 @@ See [references/auth-patterns.md](references/auth-patterns.md)
 
 See [references/naming-conventions.md](references/naming-conventions.md)
 
+## Automated Generation with GitHub Actions
+
+You can set up a GitHub Action that automatically generates and updates your frontend codebase from a remote OpenAPI spec. The workflow:
+
+1. **First run**: Fetches the spec, generates the full codebase, and commits the spec as a snapshot
+2. **Subsequent runs**: Fetches the new spec, compares with the snapshot, applies incremental updates
+
+### Sample Workflow
+
+Create `.github/workflows/sync-openapi.yml` in your repository:
+
+```yaml
+name: Sync OpenAPI Frontend
+
+on:
+  # Run on demand
+  workflow_dispatch:
+  # Or on a schedule (e.g., daily at midnight)
+  schedule:
+    - cron: '0 0 * * *'
+  # Or when the workflow file itself changes
+  push:
+    paths:
+      - '.github/workflows/sync-openapi.yml'
+
+env:
+  # ⚠️ CONFIGURE THIS: URL to your OpenAPI specification
+  OPENAPI_SPEC_URL: 'https://api.example.com/openapi.json'
+  # Where to store the spec snapshot
+  SPEC_SNAPSHOT_PATH: '.openapi/spec.json'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Create spec directory
+        run: mkdir -p $(dirname $SPEC_SNAPSHOT_PATH)
+
+      - name: Download current OpenAPI spec
+        run: |
+          curl -fSL "$OPENAPI_SPEC_URL" -o new-spec.json
+          echo "Downloaded spec from $OPENAPI_SPEC_URL"
+
+      - name: Check if this is initial generation or update
+        id: check-mode
+        run: |
+          if [ -f "$SPEC_SNAPSHOT_PATH" ]; then
+            echo "mode=update" >> $GITHUB_OUTPUT
+            echo "📝 Existing spec found - will perform incremental update"
+          else
+            echo "mode=initial" >> $GITHUB_OUTPUT
+            echo "🆕 No existing spec - will perform initial generation"
+          fi
+
+      - name: Check for spec changes (update mode only)
+        id: check-changes
+        if: steps.check-mode.outputs.mode == 'update'
+        run: |
+          if diff -q "$SPEC_SNAPSHOT_PATH" new-spec.json > /dev/null 2>&1; then
+            echo "changed=false" >> $GITHUB_OUTPUT
+            echo "✅ Spec unchanged - no update needed"
+          else
+            echo "changed=true" >> $GITHUB_OUTPUT
+            echo "🔄 Spec changed - update required"
+            # Keep the old spec for diff
+            cp "$SPEC_SNAPSHOT_PATH" old-spec.json
+          fi
+
+      - name: Generate initial codebase
+        if: steps.check-mode.outputs.mode == 'initial'
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}:/workspace" \
+            -w /workspace \
+            -e LLM_API_KEY=${{ secrets.LLM_API_KEY }} \
+            -e LLM_MODEL=${{ vars.LLM_MODEL || 'anthropic/claude-sonnet-4-20250514' }} \
+            docker.all-hands.dev/all-hands-ai/openhands:latest \
+            python -m openhands.core.cli \
+            --mode headless \
+            --task "Using the openapi-to-frontend plugin, generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
+
+            Run all phases:
+            1. Generate TypeScript client in client/
+            2. Generate React components in components/  
+            3. Generate React frontend app in app/
+            4. Generate tests in tests/
+            5. Generate CI workflows in .github/workflows/
+
+            After generation, verify the output compiles correctly."
+
+      - name: Apply incremental updates
+        if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'true'
+        run: |
+          docker run --rm \
+            -v "${{ github.workspace }}:/workspace" \
+            -w /workspace \
+            -e LLM_API_KEY=${{ secrets.LLM_API_KEY }} \
+            -e LLM_MODEL=${{ vars.LLM_MODEL || 'anthropic/claude-sonnet-4-20250514' }} \
+            docker.all-hands.dev/all-hands-ai/openhands:latest \
+            python -m openhands.core.cli \
+            --mode headless \
+            --task "Using the openapi-to-frontend plugin's update-from-spec skill, apply incremental updates to the codebase.
+
+            The old spec is at: old-spec.json
+            The new spec is at: new-spec.json
+
+            1. Use the spec-differ agent to compare the specs
+            2. For each detected change, apply the appropriate update
+            3. Do NOT regenerate from scratch - make surgical edits
+            4. Verify the updated code compiles correctly
+            5. Run existing tests to catch regressions"
+
+      - name: Update spec snapshot
+        if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
+        run: |
+          cp new-spec.json "$SPEC_SNAPSHOT_PATH"
+          echo "📸 Spec snapshot updated"
+
+      - name: Create Pull Request
+        if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: |
+            ${{ steps.check-mode.outputs.mode == 'initial' && 'chore: initial frontend generation from OpenAPI spec' || 'chore: update frontend from OpenAPI spec changes' }}
+          title: |
+            ${{ steps.check-mode.outputs.mode == 'initial' && '🆕 Initial frontend generation from OpenAPI' || '🔄 Update frontend from OpenAPI changes' }}
+          body: |
+            ## Summary
+            
+            ${{ steps.check-mode.outputs.mode == 'initial' && 'This PR contains the initial frontend codebase generated from the OpenAPI specification.' || 'This PR contains incremental updates based on changes to the OpenAPI specification.' }}
+            
+            **Spec URL:** `${{ env.OPENAPI_SPEC_URL }}`
+            
+            ## What's included
+            
+            ${{ steps.check-mode.outputs.mode == 'initial' && '- TypeScript API client (`client/`)
+            - React components (`components/`)
+            - Frontend application (`app/`)
+            - Test suite (`tests/`)
+            - CI/CD workflows (`.github/workflows/`)
+            - OpenAPI spec snapshot (`.openapi/spec.json`)' || '- Updated TypeScript types and API methods
+            - Updated React components
+            - Updated tests
+            - New OpenAPI spec snapshot' }}
+            
+            ## Review checklist
+            
+            - [ ] Generated code compiles without errors
+            - [ ] Tests pass
+            - [ ] UI renders correctly
+            - [ ] API integration works as expected
+          branch: openapi-frontend-sync
+          delete-branch: true
+
+      - name: Skip message
+        if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'false'
+        run: echo "✅ No changes detected in OpenAPI spec - nothing to do"
+```
+
+### Configuration
+
+1. **Set your OpenAPI URL**: Update the `OPENAPI_SPEC_URL` environment variable to point to your API's spec
+2. **Configure triggers**: Adjust the `on:` section for your needs (manual, scheduled, or event-based)
+3. **Set up secrets**:
+   - `LLM_API_KEY` (required): Your LLM provider API key (e.g., Anthropic, OpenAI)
+   - `GITHUB_TOKEN`: Ensure it has write permissions for contents and pull-requests
+4. **Optional variables**:
+   - `LLM_MODEL`: Override the default model (defaults to `anthropic/claude-sonnet-4-20250514`)
+
+### How the Snapshot Works
+
+The workflow maintains a snapshot of the OpenAPI spec at `.openapi/spec.json`:
+
+```
+your-repo/
+├── .openapi/
+│   └── spec.json          # Committed snapshot of the last processed spec
+├── client/
+├── components/
+├── app/
+└── ...
+```
+
+- **Initial run**: No snapshot exists, so full generation runs and the spec is committed
+- **Subsequent runs**: The snapshot is compared with the freshly downloaded spec
+  - If unchanged: workflow exits early
+  - If changed: incremental update runs, using `old-spec.json` (the snapshot) and `new-spec.json` (the download)
+
+This ensures the agent always knows the exact state of the codebase relative to the spec it was generated from.
+
+### Alternative: Local Spec File
+
+If your OpenAPI spec is checked into the repository instead of fetched from a URL:
+
+```yaml
+env:
+  # Path to spec in your repo
+  OPENAPI_SPEC_PATH: 'api/openapi.yaml'
+  SPEC_SNAPSHOT_PATH: '.openapi/last-processed-spec.yaml'
+
+# ... in steps:
+- name: Check for spec changes
+  run: |
+    if [ -f "$SPEC_SNAPSHOT_PATH" ]; then
+      if diff -q "$OPENAPI_SPEC_PATH" "$SPEC_SNAPSHOT_PATH" > /dev/null; then
+        echo "No changes"
+      else
+        cp "$SPEC_SNAPSHOT_PATH" old-spec.yaml
+        cp "$OPENAPI_SPEC_PATH" new-spec.yaml
+        # ... trigger update
+      fi
+    else
+      cp "$OPENAPI_SPEC_PATH" new-spec.yaml
+      # ... trigger initial generation
+    fi
+```
+
 ## Scripts
 
 ### parse-openapi.py

From 4644d25f2c4972915309689e80689e9d193f793a Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:11:44 +0000
Subject: [PATCH 3/8] Use OpenHands CLI directly instead of Docker

- Install via uv tool install openhands
- Run with openhands --headless -t for automation
- Configure via ~/.openhands/settings.json

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 82 ++++++++++++++-------------
 1 file changed, 44 insertions(+), 38 deletions(-)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index c7fffc6..eb04f3c 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -253,11 +253,32 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20'
 
+      - name: Install OpenHands CLI
+        run: |
+          pip install uv
+          uv tool install openhands --python 3.12
+
+      - name: Configure OpenHands
+        run: |
+          mkdir -p ~/.openhands
+          cat > ~/.openhands/settings.json << 'EOF'
+          {
+            "llm_provider": "${{ vars.LLM_PROVIDER || 'anthropic' }}",
+            "llm_model": "${{ vars.LLM_MODEL || 'claude-sonnet-4-20250514' }}",
+            "llm_api_key": "${{ secrets.LLM_API_KEY }}"
+          }
+          EOF
+
       - name: Create spec directory
         run: mkdir -p $(dirname $SPEC_SNAPSHOT_PATH)
 
@@ -294,46 +315,30 @@ jobs:
       - name: Generate initial codebase
         if: steps.check-mode.outputs.mode == 'initial'
         run: |
-          docker run --rm \
-            -v "${{ github.workspace }}:/workspace" \
-            -w /workspace \
-            -e LLM_API_KEY=${{ secrets.LLM_API_KEY }} \
-            -e LLM_MODEL=${{ vars.LLM_MODEL || 'anthropic/claude-sonnet-4-20250514' }} \
-            docker.all-hands.dev/all-hands-ai/openhands:latest \
-            python -m openhands.core.cli \
-            --mode headless \
-            --task "Using the openapi-to-frontend plugin, generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
-
-            Run all phases:
-            1. Generate TypeScript client in client/
-            2. Generate React components in components/  
-            3. Generate React frontend app in app/
-            4. Generate tests in tests/
-            5. Generate CI workflows in .github/workflows/
-
-            After generation, verify the output compiles correctly."
+          openhands --headless -t "Using the openapi-to-frontend plugin, generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
+
+          Run all phases:
+          1. Generate TypeScript client in client/
+          2. Generate React components in components/
+          3. Generate React frontend app in app/
+          4. Generate tests in tests/
+          5. Generate CI workflows in .github/workflows/
+
+          After generation, verify the output compiles correctly."
 
       - name: Apply incremental updates
         if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'true'
         run: |
-          docker run --rm \
-            -v "${{ github.workspace }}:/workspace" \
-            -w /workspace \
-            -e LLM_API_KEY=${{ secrets.LLM_API_KEY }} \
-            -e LLM_MODEL=${{ vars.LLM_MODEL || 'anthropic/claude-sonnet-4-20250514' }} \
-            docker.all-hands.dev/all-hands-ai/openhands:latest \
-            python -m openhands.core.cli \
-            --mode headless \
-            --task "Using the openapi-to-frontend plugin's update-from-spec skill, apply incremental updates to the codebase.
-
-            The old spec is at: old-spec.json
-            The new spec is at: new-spec.json
-
-            1. Use the spec-differ agent to compare the specs
-            2. For each detected change, apply the appropriate update
-            3. Do NOT regenerate from scratch - make surgical edits
-            4. Verify the updated code compiles correctly
-            5. Run existing tests to catch regressions"
+          openhands --headless -t "Using the openapi-to-frontend plugin's update-from-spec skill, apply incremental updates to the codebase.
+
+          The old spec is at: old-spec.json
+          The new spec is at: new-spec.json
+
+          1. Use the spec-differ agent to compare the specs
+          2. For each detected change, apply the appropriate update
+          3. Do NOT regenerate from scratch - make surgical edits
+          4. Verify the updated code compiles correctly
+          5. Run existing tests to catch regressions"
 
       - name: Update spec snapshot
         if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
@@ -390,8 +395,9 @@ jobs:
 3. **Set up secrets**:
    - `LLM_API_KEY` (required): Your LLM provider API key (e.g., Anthropic, OpenAI)
    - `GITHUB_TOKEN`: Ensure it has write permissions for contents and pull-requests
-4. **Optional variables**:
-   - `LLM_MODEL`: Override the default model (defaults to `anthropic/claude-sonnet-4-20250514`)
+4. **Optional variables** (repository variables, not secrets):
+   - `LLM_PROVIDER`: Your LLM provider (defaults to `anthropic`)
+   - `LLM_MODEL`: Override the default model (defaults to `claude-sonnet-4-20250514`)
 
 ### How the Snapshot Works
 

From 4ec1135044c9703cee904c4830716b01b61ce800 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:13:07 +0000
Subject: [PATCH 4/8] Add plugin installation step with configurable branch

- Clones OpenHands/extensions repo to get the plugin
- Installs plugin to ~/.openhands/plugins/
- OPENHANDS_EXTENSIONS_BRANCH variable defaults to 'main'
- Task prompts now reference the installed plugin paths

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 35 ++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index eb04f3c..b4cedae 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -239,6 +239,8 @@ env:
   OPENAPI_SPEC_URL: 'https://api.example.com/openapi.json'
   # Where to store the spec snapshot
   SPEC_SNAPSHOT_PATH: '.openapi/spec.json'
+  # OpenHands extensions branch (use 'main' for stable, or a feature branch)
+  OPENHANDS_EXTENSIONS_BRANCH: ${{ vars.OPENHANDS_EXTENSIONS_BRANCH || 'main' }}
 
 jobs:
   sync:
@@ -268,10 +270,23 @@ jobs:
           pip install uv
           uv tool install openhands --python 3.12
 
+      - name: Install openapi-to-frontend plugin
+        run: |
+          # Clone the OpenHands extensions repository
+          git clone --depth 1 --branch "$OPENHANDS_EXTENSIONS_BRANCH" \
+            https://github.com/OpenHands/extensions.git \
+            /tmp/openhands-extensions
+          
+          # Install the plugin to the OpenHands skills directory
+          mkdir -p ~/.openhands/plugins
+          cp -r /tmp/openhands-extensions/plugins/openapi-to-frontend ~/.openhands/plugins/
+          
+          echo "✅ Installed openapi-to-frontend plugin from branch: $OPENHANDS_EXTENSIONS_BRANCH"
+
       - name: Configure OpenHands
         run: |
           mkdir -p ~/.openhands
-          cat > ~/.openhands/settings.json << 'EOF'
+          cat > ~/.openhands/settings.json << EOF
           {
             "llm_provider": "${{ vars.LLM_PROVIDER || 'anthropic' }}",
             "llm_model": "${{ vars.LLM_MODEL || 'claude-sonnet-4-20250514' }}",
@@ -315,7 +330,14 @@ jobs:
       - name: Generate initial codebase
         if: steps.check-mode.outputs.mode == 'initial'
         run: |
-          openhands --headless -t "Using the openapi-to-frontend plugin, generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
+          openhands --headless -t "Using the openapi-to-frontend plugin (installed at ~/.openhands/plugins/openapi-to-frontend), generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
+
+          First, read the plugin's skills to understand the generation process:
+          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-client/SKILL.md
+          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-components/SKILL.md
+          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md
+          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-tests/SKILL.md
+          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-ci/SKILL.md
 
           Run all phases:
           1. Generate TypeScript client in client/
@@ -329,7 +351,12 @@ jobs:
       - name: Apply incremental updates
         if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'true'
         run: |
-          openhands --headless -t "Using the openapi-to-frontend plugin's update-from-spec skill, apply incremental updates to the codebase.
+          openhands --headless -t "Using the openapi-to-frontend plugin (installed at ~/.openhands/plugins/openapi-to-frontend), apply incremental updates to the codebase.
+
+          First, read the update skill:
+          - ~/.openhands/plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md
+          - ~/.openhands/plugins/openapi-to-frontend/agents/spec-differ.md
+          - ~/.openhands/plugins/openapi-to-frontend/references/change-taxonomy.md
 
           The old spec is at: old-spec.json
           The new spec is at: new-spec.json
@@ -361,6 +388,7 @@ jobs:
             ${{ steps.check-mode.outputs.mode == 'initial' && 'This PR contains the initial frontend codebase generated from the OpenAPI specification.' || 'This PR contains incremental updates based on changes to the OpenAPI specification.' }}
             
             **Spec URL:** `${{ env.OPENAPI_SPEC_URL }}`
+            **Plugin branch:** `${{ env.OPENHANDS_EXTENSIONS_BRANCH }}`
             
             ## What's included
             
@@ -398,6 +426,7 @@ jobs:
 4. **Optional variables** (repository variables, not secrets):
    - `LLM_PROVIDER`: Your LLM provider (defaults to `anthropic`)
    - `LLM_MODEL`: Override the default model (defaults to `claude-sonnet-4-20250514`)
+   - `OPENHANDS_EXTENSIONS_BRANCH`: Branch of OpenHands/extensions to use (defaults to `main`)
 
 ### How the Snapshot Works
 

From 49ac119d600c9f74bc57d653c186d97a98a030d3 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:28:42 +0000
Subject: [PATCH 5/8] Simplify command interface to /openapi-to-frontend

- Rename command from generate-all.md to openapi-to-frontend.md
- Single command handles both initial generation and incremental updates
- Usage: /openapi-to-frontend new-spec.json [old-spec.json]
- GitHub Action prompts now just reference the command file
- All detailed instructions moved into the command itself

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md         |  58 ++----
 .../commands/generate-all.md                  | 188 ------------------
 .../commands/openapi-to-frontend.md           | 166 ++++++++++++++++
 3 files changed, 183 insertions(+), 229 deletions(-)
 delete mode 100644 plugins/openapi-to-frontend/commands/generate-all.md
 create mode 100644 plugins/openapi-to-frontend/commands/openapi-to-frontend.md

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index b4cedae..2137cf9 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -16,19 +16,25 @@ The plugin also handles **incremental updates**: given a change to the OpenAPI s
 
 ## Quick Start
 
-Provide an OpenAPI spec (JSON or YAML) and run phases sequentially:
+**Initial generation** — generate a complete frontend from an OpenAPI spec:
 
 ```
-/generate-all path/to/openapi.yaml
+/openapi-to-frontend path/to/openapi.yaml
 ```
 
-Or run individual phases:
+**Incremental update** — update existing code when the spec changes:
 
-1. **Generate client**: Creates TypeScript types and API class
-2. **Generate components**: Creates React components for each schema
-3. **Generate frontend**: Creates a full application shell
-4. **Generate tests**: Creates unit, integration, and e2e tests
-5. **Generate CI**: Creates GitHub Actions workflows
+```
+/openapi-to-frontend new-spec.json old-spec.json
+```
+
+This generates/updates:
+
+1. **TypeScript client** — types and API class
+2. **React components** — Form, Detail, List per schema
+3. **Frontend app** — routing, context, pages
+4. **Tests** — unit, integration, and e2e
+5. **CI workflows** — GitHub Actions for build/test/deploy
 
 ## Plugin Contents
 
@@ -36,7 +42,7 @@ Or run individual phases:
 plugins/openapi-to-frontend/
 ├── README.md                           # This file
 ├── commands/
-│   └── generate-all.md                 # Slash command: run all phases
+│   └── openapi-to-frontend.md          # Main command: generate or update
 ├── skills/
 │   ├── generate-client/
 │   │   └── SKILL.md                    # Phase 1: OpenAPI → TypeScript client
@@ -330,42 +336,12 @@ jobs:
       - name: Generate initial codebase
         if: steps.check-mode.outputs.mode == 'initial'
         run: |
-          openhands --headless -t "Using the openapi-to-frontend plugin (installed at ~/.openhands/plugins/openapi-to-frontend), generate a complete frontend codebase from the OpenAPI spec at new-spec.json.
-
-          First, read the plugin's skills to understand the generation process:
-          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-client/SKILL.md
-          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-components/SKILL.md
-          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-frontend/SKILL.md
-          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-tests/SKILL.md
-          - ~/.openhands/plugins/openapi-to-frontend/skills/generate-ci/SKILL.md
-
-          Run all phases:
-          1. Generate TypeScript client in client/
-          2. Generate React components in components/
-          3. Generate React frontend app in app/
-          4. Generate tests in tests/
-          5. Generate CI workflows in .github/workflows/
-
-          After generation, verify the output compiles correctly."
+          openhands --headless -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json"
 
       - name: Apply incremental updates
         if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'true'
         run: |
-          openhands --headless -t "Using the openapi-to-frontend plugin (installed at ~/.openhands/plugins/openapi-to-frontend), apply incremental updates to the codebase.
-
-          First, read the update skill:
-          - ~/.openhands/plugins/openapi-to-frontend/skills/update-from-spec/SKILL.md
-          - ~/.openhands/plugins/openapi-to-frontend/agents/spec-differ.md
-          - ~/.openhands/plugins/openapi-to-frontend/references/change-taxonomy.md
-
-          The old spec is at: old-spec.json
-          The new spec is at: new-spec.json
-
-          1. Use the spec-differ agent to compare the specs
-          2. For each detected change, apply the appropriate update
-          3. Do NOT regenerate from scratch - make surgical edits
-          4. Verify the updated code compiles correctly
-          5. Run existing tests to catch regressions"
+          openhands --headless -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json old-spec.json"
 
       - name: Update spec snapshot
         if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
diff --git a/plugins/openapi-to-frontend/commands/generate-all.md b/plugins/openapi-to-frontend/commands/generate-all.md
deleted file mode 100644
index 08e2666..0000000
--- a/plugins/openapi-to-frontend/commands/generate-all.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# /generate-all
-
-Run all generation phases end-to-end from an OpenAPI specification.
-
-## Usage
-
-```
-/generate-all <spec-file> [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|----------|-------------|
-| `spec-file` | Path to OpenAPI specification (JSON or YAML) |
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--output-dir <dir>` | Output directory (default: current directory) |
-| `--skip-tests` | Skip test generation |
-| `--skip-ci` | Skip CI/CD workflow generation |
-| `--client-only` | Generate only the TypeScript client |
-| `--dry-run` | Show what would be generated without writing files |
-
-## Examples
-
-### Full generation
-
-```
-/generate-all ./openapi.yaml
-```
-
-This will:
-1. Parse the OpenAPI spec
-2. Generate TypeScript client in `client/`
-3. Generate React components in `components/`
-4. Generate React frontend in `app/`
-5. Generate tests in `tests/`
-6. Generate GitHub Actions in `.github/workflows/`
-
-### Client only
-
-```
-/generate-all ./api-spec.json --client-only
-```
-
-### Custom output directory
-
-```
-/generate-all ./openapi.yaml --output-dir ./packages/generated
-```
-
-### Skip CI
-
-```
-/generate-all ./openapi.yaml --skip-ci
-```
-
-## Workflow
-
-The command runs these phases in sequence:
-
-### Phase 1: Parse Spec
-
-```bash
-python scripts/parse-openapi.py <spec-file> > .generated/spec-summary.json
-```
-
-Extracts schemas, endpoints, and auth schemes into a normalized format.
-
-### Phase 2: Generate Client
-
-Uses `skills/generate-client/SKILL.md`:
-
-- Creates `client/types.ts` with TypeScript interfaces
-- Creates `client/api.ts` with API class and methods
-- Creates `client/auth.ts` with auth handlers
-- Creates `client/index.ts` barrel export
-
-### Phase 3: Generate Components
-
-Uses `skills/generate-components/SKILL.md`:
-
-- Creates `components/<Schema>/` directories
-- Creates Form, Detail, List components per schema
-- Creates `components/shared/` utilities
-- Creates barrel exports
-
-### Phase 4: Generate Frontend
-
-Uses `skills/generate-frontend/SKILL.md`:
-
-- Infers app type from API structure
-- Creates `app/App.tsx` with routing
-- Creates `app/pages/` per resource
-- Creates `app/context/` for API and auth
-- Creates `app/hooks/` for data fetching
-
-### Phase 5: Generate Tests
-
-Uses `skills/generate-tests/SKILL.md`:
-
-- Creates `tests/setup/` with config and factories
-- Creates `tests/unit/` for client and components
-- Creates `tests/integration/` for flows
-- Creates `tests/e2e/` for Playwright
-
-### Phase 6: Generate CI
-
-Uses `skills/generate-ci/SKILL.md`:
-
-- Creates `.github/workflows/ci.yml`
-- Creates `.github/workflows/deploy.yml`
-- Creates `.github/workflows/publish.yml`
-
-## Verification
-
-After generation, the command runs:
-
-```bash
-# Lint check
-./scripts/lint-generated.sh
-
-# Coverage verification
-python scripts/verify-coverage.py <spec-file> client/
-python scripts/verify-components.py client/ components/
-```
-
-## Output Structure
-
-```
-<output-dir>/
-├── client/
-│   ├── types.ts
-│   ├── api.ts
-│   ├── auth.ts
-│   └── index.ts
-├── components/
-│   ├── <Schema>/
-│   │   ├── <Schema>Form.tsx
-│   │   ├── <Schema>Detail.tsx
-│   │   ├── <Schema>List.tsx
-│   │   └── index.ts
-│   ├── shared/
-│   └── index.ts
-├── app/
-│   ├── App.tsx
-│   ├── Layout.tsx
-│   ├── main.tsx
-│   ├── pages/
-│   ├── context/
-│   ├── hooks/
-│   └── utils/
-├── tests/
-│   ├── setup/
-│   ├── unit/
-│   ├── integration/
-│   └── e2e/
-└── .github/
-    └── workflows/
-        ├── ci.yml
-        ├── deploy.yml
-        └── publish.yml
-```
-
-## Interactive Mode
-
-When the API purpose is ambiguous, the command asks for confirmation:
-
-> "Based on the API, this appears to be a **user management system**. I'll generate:
-> - Dashboard with user list
-> - User detail and edit pages
-> - Role management section
-> - OAuth2 login flow
->
-> Does this match your expectations? [Y/n]"
-
-## Incremental Updates
-
-For updating existing generated code when the spec changes, use:
-
-```
-/update-from-spec <old-spec> <new-spec>
-```
-
-See `skills/update-from-spec/SKILL.md` for details.
diff --git a/plugins/openapi-to-frontend/commands/openapi-to-frontend.md b/plugins/openapi-to-frontend/commands/openapi-to-frontend.md
new file mode 100644
index 0000000..f05b7cc
--- /dev/null
+++ b/plugins/openapi-to-frontend/commands/openapi-to-frontend.md
@@ -0,0 +1,166 @@
+# /openapi-to-frontend
+
+Generate or update a frontend codebase from an OpenAPI specification.
+
+## Usage
+
+```
+/openapi-to-frontend <new-spec> [old-spec]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `new-spec` | Path to the current/new OpenAPI specification (JSON or YAML) |
+| `old-spec` | (Optional) Path to the previous OpenAPI spec for incremental updates |
+
+## Behavior
+
+**Initial generation** (no `old-spec` provided):
+```
+/openapi-to-frontend openapi.json
+```
+Generates a complete frontend codebase from scratch.
+
+**Incremental update** (both specs provided):
+```
+/openapi-to-frontend new-spec.json old-spec.json
+```
+Compares the specs and applies surgical updates to existing code.
+
+---
+
+## What This Command Does
+
+### Initial Generation Mode
+
+When only `new-spec` is provided, run all generation phases:
+
+1. **Read the spec** at the provided path
+2. **Generate TypeScript client** in `client/`:
+   - `types.ts` — interfaces for all schemas
+   - `api.ts` — API class with typed methods  
+   - `auth.ts` — auth handlers based on securitySchemes
+   - `index.ts` — barrel export
+3. **Generate React components** in `components/`:
+   - `<Schema>/` directory per schema with Form, Detail, List components
+   - `shared/` — LoadingSpinner, ErrorDisplay, Pagination
+4. **Generate React frontend** in `app/`:
+   - `App.tsx` with routing
+   - `pages/` — one page per resource
+   - `context/` — API client and auth providers
+   - `hooks/` — useResource, usePagination
+   - `utils/` — localStorage helpers
+5. **Generate tests** in `tests/`:
+   - `setup/` — factories, type guards, config
+   - `unit/` — client and component tests
+   - `integration/` — flow tests
+   - `e2e/` — Playwright tests
+6. **Generate CI workflows** in `.github/workflows/`:
+   - `ci.yml` — build and test on PR
+   - `deploy.yml` — deploy to GitHub Pages
+   - `publish.yml` — publish to npm
+7. **Verify** the generated code compiles correctly
+
+### Incremental Update Mode
+
+When both `new-spec` and `old-spec` are provided:
+
+1. **Compare the specs** to identify changes:
+   - Schemas added/removed/modified
+   - Endpoints added/removed/modified
+   - Fields added/removed/type changed
+   - Auth schemes changed
+2. **Apply surgical updates** to existing code:
+   - Add new interfaces for new schemas
+   - Update existing interfaces for changed fields
+   - Add/remove API methods for endpoint changes
+   - Update components to reflect schema changes
+   - Update tests and factories
+3. **Do NOT regenerate from scratch** — preserve user customizations
+4. **Verify** the updated code compiles and tests pass
+
+---
+
+## Reference Skills
+
+This command orchestrates these skills (read them for detailed implementation guidance):
+
+| Phase | Skill | Description |
+|-------|-------|-------------|
+| Client | `skills/generate-client/SKILL.md` | TypeScript types and API class |
+| Components | `skills/generate-components/SKILL.md` | React Form/Detail/List components |
+| Frontend | `skills/generate-frontend/SKILL.md` | App shell, routing, context |
+| Tests | `skills/generate-tests/SKILL.md` | Unit, integration, e2e tests |
+| CI | `skills/generate-ci/SKILL.md` | GitHub Actions workflows |
+| Updates | `skills/update-from-spec/SKILL.md` | Incremental change application |
+| Diffing | `agents/spec-differ.md` | Spec comparison logic |
+
+## Reference Documents
+
+| Topic | Reference |
+|-------|-----------|
+| Auth patterns | `references/auth-patterns.md` |
+| Naming rules | `references/naming-conventions.md` |
+| Change types | `references/change-taxonomy.md` |
+
+---
+
+## Output Structure
+
+```
+./
+├── client/
+│   ├── types.ts
+│   ├── api.ts
+│   ├── auth.ts
+│   └── index.ts
+├── components/
+│   ├── <Schema>/
+│   │   ├── <Schema>Form.tsx
+│   │   ├── <Schema>Detail.tsx
+│   │   ├── <Schema>List.tsx
+│   │   └── index.ts
+│   ├── shared/
+│   └── index.ts
+├── app/
+│   ├── App.tsx
+│   ├── Layout.tsx
+│   ├── main.tsx
+│   ├── pages/
+│   ├── context/
+│   ├── hooks/
+│   └── utils/
+├── tests/
+│   ├── setup/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+└── .github/
+    └── workflows/
+        ├── ci.yml
+        ├── deploy.yml
+        └── publish.yml
+```
+
+## Examples
+
+### Generate from a local spec
+
+```
+/openapi-to-frontend ./api/openapi.yaml
+```
+
+### Update after spec changes
+
+```
+/openapi-to-frontend ./new-spec.json ./old-spec.json
+```
+
+### In CI/CD (GitHub Actions)
+
+```yaml
+- name: Generate/update frontend
+  run: openhands --headless -t "/openapi-to-frontend new-spec.json old-spec.json"
+```

From 463d5d50594c9b3ebc360419967f609d27b7e343 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 22:46:04 +0000
Subject: [PATCH 6/8] Fix OpenHands settings configuration for headless mode

- Use correct settings.json format with LLM_MODEL, LLM_API_KEY, etc.
- Default to ANTHROPIC_API_KEY secret and claude-opus-4-20250514 model
- Add LLM_BASE_URL for custom API endpoints
- Document how to use different LLM providers
- Settings now properly created before running headless mode

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 37 ++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index 2137cf9..8c00f8d 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -290,15 +290,26 @@ jobs:
           echo "✅ Installed openapi-to-frontend plugin from branch: $OPENHANDS_EXTENSIONS_BRANCH"
 
       - name: Configure OpenHands
+        env:
+          LLM_MODEL: ${{ vars.LLM_MODEL || 'anthropic/claude-opus-4-20250514' }}
+          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          LLM_BASE_URL: ${{ vars.LLM_BASE_URL || '' }}
         run: |
           mkdir -p ~/.openhands
+          
+          # Build settings JSON
           cat > ~/.openhands/settings.json << EOF
           {
-            "llm_provider": "${{ vars.LLM_PROVIDER || 'anthropic' }}",
-            "llm_model": "${{ vars.LLM_MODEL || 'claude-sonnet-4-20250514' }}",
-            "llm_api_key": "${{ secrets.LLM_API_KEY }}"
+            "LLM_MODEL": "${LLM_MODEL}",
+            "LLM_API_KEY": "${LLM_API_KEY}",
+            "LLM_BASE_URL": "${LLM_BASE_URL}",
+            "AGENT": "CodeActAgent",
+            "LANGUAGE": "en",
+            "CONFIRMATION_MODE": "false"
           }
           EOF
+          
+          echo "✅ Configured OpenHands with model: ${LLM_MODEL}"
 
       - name: Create spec directory
         run: mkdir -p $(dirname $SPEC_SNAPSHOT_PATH)
@@ -396,14 +407,22 @@ jobs:
 
 1. **Set your OpenAPI URL**: Update the `OPENAPI_SPEC_URL` environment variable to point to your API's spec
 2. **Configure triggers**: Adjust the `on:` section for your needs (manual, scheduled, or event-based)
-3. **Set up secrets**:
-   - `LLM_API_KEY` (required): Your LLM provider API key (e.g., Anthropic, OpenAI)
-   - `GITHUB_TOKEN`: Ensure it has write permissions for contents and pull-requests
-4. **Optional variables** (repository variables, not secrets):
-   - `LLM_PROVIDER`: Your LLM provider (defaults to `anthropic`)
-   - `LLM_MODEL`: Override the default model (defaults to `claude-sonnet-4-20250514`)
+3. **Set up secrets** (in repository Settings → Secrets and variables → Actions):
+   - `ANTHROPIC_API_KEY` (required): Your Anthropic API key
+4. **Optional variables** (in repository Settings → Secrets and variables → Actions → Variables):
+   - `LLM_MODEL`: Model to use (defaults to `anthropic/claude-opus-4-20250514`)
+   - `LLM_BASE_URL`: Custom API base URL (optional, for proxies)
    - `OPENHANDS_EXTENSIONS_BRANCH`: Branch of OpenHands/extensions to use (defaults to `main`)
 
+**Using a different LLM provider:**
+
+To use OpenAI or another provider, update the workflow:
+```yaml
+env:
+  LLM_MODEL: ${{ vars.LLM_MODEL || 'openai/gpt-4o' }}
+  LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+```
+
 ### How the Snapshot Works
 
 The workflow maintains a snapshot of the OpenAPI spec at `.openapi/spec.json`:

From aaf60460af57eebee98b0bbb99b4351a9e64d7f6 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 23:17:39 +0000
Subject: [PATCH 7/8] Use --override-with-envs for headless mode configuration

- Remove settings.json file generation (not needed)
- Use --override-with-envs flag with LLM_API_KEY and LLM_MODEL env vars
- This is the correct way to configure OpenHands CLI in headless mode
- Update configuration docs to explain env vars approach

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 45 +++++++++++----------------
 1 file changed, 19 insertions(+), 26 deletions(-)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index 8c00f8d..05b66ea 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -289,28 +289,6 @@ jobs:
           
           echo "✅ Installed openapi-to-frontend plugin from branch: $OPENHANDS_EXTENSIONS_BRANCH"
 
-      - name: Configure OpenHands
-        env:
-          LLM_MODEL: ${{ vars.LLM_MODEL || 'anthropic/claude-opus-4-20250514' }}
-          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          LLM_BASE_URL: ${{ vars.LLM_BASE_URL || '' }}
-        run: |
-          mkdir -p ~/.openhands
-          
-          # Build settings JSON
-          cat > ~/.openhands/settings.json << EOF
-          {
-            "LLM_MODEL": "${LLM_MODEL}",
-            "LLM_API_KEY": "${LLM_API_KEY}",
-            "LLM_BASE_URL": "${LLM_BASE_URL}",
-            "AGENT": "CodeActAgent",
-            "LANGUAGE": "en",
-            "CONFIRMATION_MODE": "false"
-          }
-          EOF
-          
-          echo "✅ Configured OpenHands with model: ${LLM_MODEL}"
-
       - name: Create spec directory
         run: mkdir -p $(dirname $SPEC_SNAPSHOT_PATH)
 
@@ -346,13 +324,21 @@ jobs:
 
       - name: Generate initial codebase
         if: steps.check-mode.outputs.mode == 'initial'
+        env:
+          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          LLM_MODEL: ${{ vars.LLM_MODEL || 'anthropic/claude-opus-4-20250514' }}
+          LLM_BASE_URL: ${{ vars.LLM_BASE_URL || '' }}
         run: |
-          openhands --headless -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json"
+          openhands --headless --override-with-envs -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json"
 
       - name: Apply incremental updates
         if: steps.check-mode.outputs.mode == 'update' && steps.check-changes.outputs.changed == 'true'
+        env:
+          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          LLM_MODEL: ${{ vars.LLM_MODEL || 'anthropic/claude-opus-4-20250514' }}
+          LLM_BASE_URL: ${{ vars.LLM_BASE_URL || '' }}
         run: |
-          openhands --headless -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json old-spec.json"
+          openhands --headless --override-with-envs -t "Read ~/.openhands/plugins/openapi-to-frontend/commands/openapi-to-frontend.md and execute: /openapi-to-frontend new-spec.json old-spec.json"
 
       - name: Update spec snapshot
         if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
@@ -416,13 +402,20 @@ jobs:
 
 **Using a different LLM provider:**
 
-To use OpenAI or another provider, update the workflow:
+To use OpenAI or another provider, update the `env` sections in the workflow:
 ```yaml
 env:
-  LLM_MODEL: ${{ vars.LLM_MODEL || 'openai/gpt-4o' }}
   LLM_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  LLM_MODEL: ${{ vars.LLM_MODEL || 'openai/gpt-4o' }}
 ```
 
+**Environment Variables:**
+
+The workflow uses `--override-with-envs` to configure OpenHands via environment variables:
+- `LLM_API_KEY`: Your LLM provider API key (required)
+- `LLM_MODEL`: The model to use, e.g., `anthropic/claude-opus-4-20250514` (required)
+- `LLM_BASE_URL`: Custom API endpoint (optional)
+
 ### How the Snapshot Works
 
 The workflow maintains a snapshot of the OpenAPI spec at `.openapi/spec.json`:

From 6a0b87dfcd0014e30ae816a9bcfa943d99550afb Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Sun, 15 Mar 2026 23:38:37 +0000
Subject: [PATCH 8/8] Add step to revert .github/ changes before PR creation

The generated CI workflows could overwrite the sync-openapi workflow itself.
This step ensures the .github/ directory is restored before pushing changes.

Co-authored-by: openhands <openhands@all-hands.dev>
---
 plugins/openapi-to-frontend/README.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/plugins/openapi-to-frontend/README.md b/plugins/openapi-to-frontend/README.md
index 05b66ea..29f0552 100644
--- a/plugins/openapi-to-frontend/README.md
+++ b/plugins/openapi-to-frontend/README.md
@@ -346,6 +346,12 @@ jobs:
           cp new-spec.json "$SPEC_SNAPSHOT_PATH"
           echo "📸 Spec snapshot updated"
 
+      - name: Revert changes to .github directory
+        if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
+        run: |
+          git checkout HEAD -- .github/ 2>/dev/null || true
+          echo "🔄 Reverted any changes to .github/ directory"
+
       - name: Create Pull Request
         if: steps.check-mode.outputs.mode == 'initial' || steps.check-changes.outputs.changed == 'true'
         uses: peter-evans/create-pull-request@v6