fix: improve TanStack Start skill to reduce first-attempt build failures (#83)

* fix: improve TanStack Start skill to reduce first-attempt build failures

Three changes to address common agent self-correction patterns:

1. Use createStart(() => ({ ... })) as the default start.ts pattern.
   The generated routeTree.gen.ts imports createStart types, so a plain
   object export fails type checking. createStart takes a function
   returning the options, not the options directly.

2. Add Finalize section with mandatory pre-completion steps: regenerate
   route tree, ensure vite-env.d.ts exists, verify the build.

3. Instruct agents to read existing start.ts before modifying, matching
   the project's export style instead of rewriting from scratch.

* chore: formatting

* chore: remove unused import

Author: nicknisi

skills/workos-authkit-tanstack-start/SKILL.md

@@ -88,32 +88,33 @@ Default redirect URI: `http://localhost:3000/api/auth/callback`
 
 **WARNING: Do NOT add middleware to `createRouter()` in `router.tsx` or `app.tsx`. That is TanStack Router (client-side only). Server middleware belongs in `start.ts` using `requestMiddleware`.**
 
-Create or update `src/start.ts` (or `app/start.ts` for legacy):
+### If `start.ts` already exists
 
-```typescript
-import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';
+Read the existing file first. Add `authkitMiddleware` to the existing `requestMiddleware` array (or create the array if missing). Preserve the existing export style. Do not rewrite the file from scratch.
 
-export default {
-  requestMiddleware: [authkitMiddleware()],
-};
-```
+### If `start.ts` does not exist
 
-Alternative pattern with createStart:
+Create `src/start.ts` (or `app/start.ts` for legacy) using `createStart`:
 
 ```typescript
 import { createStart } from '@tanstack/react-start';
 import { authkitMiddleware } from '@workos/authkit-tanstack-react-start';
 
-export default createStart({
+export const startInstance = createStart(() => ({
   requestMiddleware: [authkitMiddleware()],
-});
+}));
 ```
 
+**Two things matter here:**
+
+1. **Named export `startInstance`** — the build plugin generates `import type { startInstance }` from this file. A `default` export will cause a build error.
+2. **`createStart` takes a function** returning the options object, not the options directly. `createStart({ ... })` will fail.
+
 ### Verification Checklist
 
 - [ ] `authkitMiddleware` imported from `@workos/authkit-tanstack-react-start`
-- [ ] Middleware in `requestMiddleware` array
-- [ ] File exports the config (default export or named `startInstance`)
+- [ ] Middleware in `requestMiddleware` array (not `middleware`)
+- [ ] Named export: `export const startInstance = createStart(...)` (not `export default`)
 
 Verify: `grep -r "authkitMiddleware" src/ app/ 2>/dev/null`
 
@@ -210,6 +211,40 @@ function Profile() {
 
 **Note:** Server-side `getAuth()` is preferred for most use cases.
 
+## Finalize (REQUIRED before declaring success)
+
+After creating/editing all files, run these steps in order. Skipping them is the most common cause of build failures.
+
+### 1. Regenerate the route tree
+
+Adding new route files (callback, signout, etc.) makes the existing `routeTree.gen.ts` stale. The build will fail with type errors about missing routes until it is regenerated.
+
+```bash
+pnpm build 2>/dev/null || npx tsr generate
+```
+
+The build itself triggers route tree regeneration. If it fails for other reasons, use `tsr generate` directly.
+
+### 2. Ensure Vite type declarations exist
+
+TanStack Start projects import CSS with `import styles from './styles.css?url'`. Without Vite's type declarations, TypeScript will error on these imports. Check if `src/vite-env.d.ts` (or `app/vite-env.d.ts`) exists — if not, create it now (before attempting the build):
+
+```typescript
+/// <reference types="vite/client" />
+```
+
+### 3. Verify the build
+
+```bash
+pnpm build
+```
+
+Do not skip this step. If the build fails, fix the errors before finishing. Common causes:
+
+- Stale route tree → re-run step 1
+- Missing Vite types → re-run step 2
+- Wrong import paths → check package name is `@workos/authkit-tanstack-react-start`
+
 ## Error Recovery
 
 ### "AuthKit middleware is not configured"

src/lib/agent-interface.ts

@@ -3,7 +3,6 @@
  * Uses Claude Agent SDK directly with WorkOS MCP server
  */
 
-import path from 'path';
 import { getPackageRoot } from '../utils/paths.js';
 import { debug, logInfo, logWarn, logError, initLogFile, getLogFilePath } from '../utils/debug.js';
 import type { InstallerOptions } from '../utils/types.js';