@devo-bmad-custom/agent-orchestration 1.0.1 → 1.0.3

package/src/.agents/skills/next-best-practices/route-handlers.md

@@ -1,146 +1,146 @@
-# Route Handlers
-
-Create API endpoints with `route.ts` files.
-
-## Basic Usage
-
-```tsx
-// app/api/users/route.ts
-export async function GET() {
-  const users = await getUsers()
-  return Response.json(users)
-}
-
-export async function POST(request: Request) {
-  const body = await request.json()
-  const user = await createUser(body)
-  return Response.json(user, { status: 201 })
-}
-```
-
-## Supported Methods
-
-`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
-
-## GET Handler Conflicts with page.tsx
-
-**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
-
-```
-app/
-├── api/
-│   └── users/
-│       └── route.ts    # /api/users
-└── users/
-    ├── page.tsx        # /users (page)
-    └── route.ts        # Warning: Conflicts with page.tsx!
-```
-
-If you need both a page and an API at the same path, use different paths:
-
-```
-app/
-├── users/
-│   └── page.tsx        # /users (page)
-└── api/
-    └── users/
-        └── route.ts    # /api/users (API)
-```
-
-## Environment Behavior
-
-Route handlers run in a **Server Component-like environment**:
-
-- Yes: Can use `async/await`
-- Yes: Can access `cookies()`, `headers()`
-- Yes: Can use Node.js APIs
-- No: Cannot use React hooks
-- No: Cannot use React DOM APIs
-- No: Cannot use browser APIs
-
-```tsx
-// Bad: This won't work - no React DOM in route handlers
-import { renderToString } from 'react-dom/server'
-
-export async function GET() {
-  const html = renderToString(<Component />)  // Error!
-  return new Response(html)
-}
-```
-
-## Dynamic Route Handlers
-
-```tsx
-// app/api/users/[id]/route.ts
-export async function GET(
-  request: Request,
-  { params }: { params: Promise<{ id: string }> }
-) {
-  const { id } = await params
-  const user = await getUser(id)
-
-  if (!user) {
-    return Response.json({ error: 'Not found' }, { status: 404 })
-  }
-
-  return Response.json(user)
-}
-```
-
-## Request Helpers
-
-```tsx
-export async function GET(request: Request) {
-  // URL and search params
-  const { searchParams } = new URL(request.url)
-  const query = searchParams.get('q')
-
-  // Headers
-  const authHeader = request.headers.get('authorization')
-
-  // Cookies (Next.js helper)
-  const cookieStore = await cookies()
-  const token = cookieStore.get('token')
-
-  return Response.json({ query, token })
-}
-```
-
-## Response Helpers
-
-```tsx
-// JSON response
-return Response.json({ data })
-
-// With status
-return Response.json({ error: 'Not found' }, { status: 404 })
-
-// With headers
-return Response.json(data, {
-  headers: {
-    'Cache-Control': 'max-age=3600',
-  },
-})
-
-// Redirect
-return Response.redirect(new URL('/login', request.url))
-
-// Stream
-return new Response(stream, {
-  headers: { 'Content-Type': 'text/event-stream' },
-})
-```
-
-## When to Use Route Handlers vs Server Actions
-
-| Use Case | Route Handlers | Server Actions |
-|----------|----------------|----------------|
-| Form submissions | No | Yes |
-| Data mutations from UI | No | Yes |
-| Third-party webhooks | Yes | No |
-| External API consumption | Yes | No |
-| Public REST API | Yes | No |
-| File uploads | Both work | Both work |
-
-**Prefer Server Actions** for mutations triggered from your UI.
-**Use Route Handlers** for external integrations and public APIs.
+# Route Handlers
+
+Create API endpoints with `route.ts` files.
+
+## Basic Usage
+
+```tsx
+// app/api/users/route.ts
+export async function GET() {
+  const users = await getUsers()
+  return Response.json(users)
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const user = await createUser(body)
+  return Response.json(user, { status: 201 })
+}
+```
+
+## Supported Methods
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+
+## GET Handler Conflicts with page.tsx
+
+**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
+
+```
+app/
+├── api/
+│   └── users/
+│       └── route.ts    # /api/users
+└── users/
+    ├── page.tsx        # /users (page)
+    └── route.ts        # Warning: Conflicts with page.tsx!
+```
+
+If you need both a page and an API at the same path, use different paths:
+
+```
+app/
+├── users/
+│   └── page.tsx        # /users (page)
+└── api/
+    └── users/
+        └── route.ts    # /api/users (API)
+```
+
+## Environment Behavior
+
+Route handlers run in a **Server Component-like environment**:
+
+- Yes: Can use `async/await`
+- Yes: Can access `cookies()`, `headers()`
+- Yes: Can use Node.js APIs
+- No: Cannot use React hooks
+- No: Cannot use React DOM APIs
+- No: Cannot use browser APIs
+
+```tsx
+// Bad: This won't work - no React DOM in route handlers
+import { renderToString } from 'react-dom/server'
+
+export async function GET() {
+  const html = renderToString(<Component />)  // Error!
+  return new Response(html)
+}
+```
+
+## Dynamic Route Handlers
+
+```tsx
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+  const user = await getUser(id)
+
+  if (!user) {
+    return Response.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  return Response.json(user)
+}
+```
+
+## Request Helpers
+
+```tsx
+export async function GET(request: Request) {
+  // URL and search params
+  const { searchParams } = new URL(request.url)
+  const query = searchParams.get('q')
+
+  // Headers
+  const authHeader = request.headers.get('authorization')
+
+  // Cookies (Next.js helper)
+  const cookieStore = await cookies()
+  const token = cookieStore.get('token')
+
+  return Response.json({ query, token })
+}
+```
+
+## Response Helpers
+
+```tsx
+// JSON response
+return Response.json({ data })
+
+// With status
+return Response.json({ error: 'Not found' }, { status: 404 })
+
+// With headers
+return Response.json(data, {
+  headers: {
+    'Cache-Control': 'max-age=3600',
+  },
+})
+
+// Redirect
+return Response.redirect(new URL('/login', request.url))
+
+// Stream
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/event-stream' },
+})
+```
+
+## When to Use Route Handlers vs Server Actions
+
+| Use Case | Route Handlers | Server Actions |
+|----------|----------------|----------------|
+| Form submissions | No | Yes |
+| Data mutations from UI | No | Yes |
+| Third-party webhooks | Yes | No |
+| External API consumption | Yes | No |
+| Public REST API | Yes | No |
+| File uploads | Both work | Both work |
+
+**Prefer Server Actions** for mutations triggered from your UI.
+**Use Route Handlers** for external integrations and public APIs.

package/src/.agents/skills/next-best-practices/rsc-boundaries.md

@@ -1,159 +1,159 @@
-# RSC Boundaries
-
-Detect and prevent invalid patterns when crossing Server/Client component boundaries.
-
-## Detection Rules
-
-### 1. Async Client Components Are Invalid
-
-Client components **cannot** be async functions. Only Server Components can be async.
-
-**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
-
-```tsx
-// Bad: async client component
-'use client'
-export default async function UserProfile() {
-  const user = await getUser() // Cannot await in client component
-  return <div>{user.name}</div>
-}
-
-// Good: Remove async, fetch data in parent server component
-// page.tsx (server component - no 'use client')
-export default async function Page() {
-  const user = await getUser()
-  return <UserProfile user={user} />
-}
-
-// UserProfile.tsx (client component)
-'use client'
-export function UserProfile({ user }: { user: User }) {
-  return <div>{user.name}</div>
-}
-```
-
-```tsx
-// Bad: async arrow function client component
-'use client'
-const Dashboard = async () => {
-  const data = await fetchDashboard()
-  return <div>{data}</div>
-}
-
-// Good: Fetch in server component, pass data down
-```
-
-### 2. Non-Serializable Props to Client Components
-
-Props passed from Server → Client must be JSON-serializable.
-
-**Detect:** Server component passes these to a client component:
-- Functions (except Server Actions with `'use server'`)
-- `Date` objects
-- `Map`, `Set`, `WeakMap`, `WeakSet`
-- Class instances
-- `Symbol` (unless globally registered)
-- Circular references
-
-```tsx
-// Bad: Function prop
-// page.tsx (server)
-export default function Page() {
-  const handleClick = () => console.log('clicked')
-  return <ClientButton onClick={handleClick} />
-}
-
-// Good: Define function inside client component
-// ClientButton.tsx
-'use client'
-export function ClientButton() {
-  const handleClick = () => console.log('clicked')
-  return <button onClick={handleClick}>Click</button>
-}
-```
-
-```tsx
-// Bad: Date object (silently becomes string, then crashes)
-// page.tsx (server)
-export default async function Page() {
-  const post = await getPost()
-  return <PostCard createdAt={post.createdAt} /> // Date object
-}
-
-// PostCard.tsx (client) - will crash on .getFullYear()
-'use client'
-export function PostCard({ createdAt }: { createdAt: Date }) {
-  return <span>{createdAt.getFullYear()}</span> // Runtime error!
-}
-
-// Good: Serialize to string on server
-// page.tsx (server)
-export default async function Page() {
-  const post = await getPost()
-  return <PostCard createdAt={post.createdAt.toISOString()} />
-}
-
-// PostCard.tsx (client)
-'use client'
-export function PostCard({ createdAt }: { createdAt: string }) {
-  const date = new Date(createdAt)
-  return <span>{date.getFullYear()}</span>
-}
-```
-
-```tsx
-// Bad: Class instance
-const user = new UserModel(data)
-<ClientProfile user={user} /> // Methods will be stripped
-
-// Good: Pass plain object
-const user = await getUser()
-<ClientProfile user={{ id: user.id, name: user.name }} />
-```
-
-```tsx
-// Bad: Map/Set
-<ClientComponent items={new Map([['a', 1]])} />
-
-// Good: Convert to array/object
-<ClientComponent items={Object.fromEntries(map)} />
-<ClientComponent items={Array.from(set)} />
-```
-
-### 3. Server Actions Are the Exception
-
-Functions marked with `'use server'` CAN be passed to client components.
-
-```tsx
-// Valid: Server Action can be passed
-// actions.ts
-'use server'
-export async function submitForm(formData: FormData) {
-  // server-side logic
-}
-
-// page.tsx (server)
-import { submitForm } from './actions'
-export default function Page() {
-  return <ClientForm onSubmit={submitForm} /> // OK!
-}
-
-// ClientForm.tsx (client)
-'use client'
-export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
-  return <form action={onSubmit}>...</form>
-}
-```
-
-## Quick Reference
-
-| Pattern | Valid? | Fix |
-|---------|--------|-----|
-| `'use client'` + `async function` | No | Fetch in server parent, pass data |
-| Pass `() => {}` to client | No | Define in client or use server action |
-| Pass `new Date()` to client | No | Use `.toISOString()` |
-| Pass `new Map()` to client | No | Convert to object/array |
-| Pass class instance to client | No | Pass plain object |
-| Pass server action to client | Yes | - |
-| Pass `string/number/boolean` | Yes | - |
-| Pass plain object/array | Yes | - |
+# RSC Boundaries
+
+Detect and prevent invalid patterns when crossing Server/Client component boundaries.
+
+## Detection Rules
+
+### 1. Async Client Components Are Invalid
+
+Client components **cannot** be async functions. Only Server Components can be async.
+
+**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
+
+```tsx
+// Bad: async client component
+'use client'
+export default async function UserProfile() {
+  const user = await getUser() // Cannot await in client component
+  return <div>{user.name}</div>
+}
+
+// Good: Remove async, fetch data in parent server component
+// page.tsx (server component - no 'use client')
+export default async function Page() {
+  const user = await getUser()
+  return <UserProfile user={user} />
+}
+
+// UserProfile.tsx (client component)
+'use client'
+export function UserProfile({ user }: { user: User }) {
+  return <div>{user.name}</div>
+}
+```
+
+```tsx
+// Bad: async arrow function client component
+'use client'
+const Dashboard = async () => {
+  const data = await fetchDashboard()
+  return <div>{data}</div>
+}
+
+// Good: Fetch in server component, pass data down
+```
+
+### 2. Non-Serializable Props to Client Components
+
+Props passed from Server → Client must be JSON-serializable.
+
+**Detect:** Server component passes these to a client component:
+- Functions (except Server Actions with `'use server'`)
+- `Date` objects
+- `Map`, `Set`, `WeakMap`, `WeakSet`
+- Class instances
+- `Symbol` (unless globally registered)
+- Circular references
+
+```tsx
+// Bad: Function prop
+// page.tsx (server)
+export default function Page() {
+  const handleClick = () => console.log('clicked')
+  return <ClientButton onClick={handleClick} />
+}
+
+// Good: Define function inside client component
+// ClientButton.tsx
+'use client'
+export function ClientButton() {
+  const handleClick = () => console.log('clicked')
+  return <button onClick={handleClick}>Click</button>
+}
+```
+
+```tsx
+// Bad: Date object (silently becomes string, then crashes)
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost()
+  return <PostCard createdAt={post.createdAt} /> // Date object
+}
+
+// PostCard.tsx (client) - will crash on .getFullYear()
+'use client'
+export function PostCard({ createdAt }: { createdAt: Date }) {
+  return <span>{createdAt.getFullYear()}</span> // Runtime error!
+}
+
+// Good: Serialize to string on server
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost()
+  return <PostCard createdAt={post.createdAt.toISOString()} />
+}
+
+// PostCard.tsx (client)
+'use client'
+export function PostCard({ createdAt }: { createdAt: string }) {
+  const date = new Date(createdAt)
+  return <span>{date.getFullYear()}</span>
+}
+```
+
+```tsx
+// Bad: Class instance
+const user = new UserModel(data)
+<ClientProfile user={user} /> // Methods will be stripped
+
+// Good: Pass plain object
+const user = await getUser()
+<ClientProfile user={{ id: user.id, name: user.name }} />
+```
+
+```tsx
+// Bad: Map/Set
+<ClientComponent items={new Map([['a', 1]])} />
+
+// Good: Convert to array/object
+<ClientComponent items={Object.fromEntries(map)} />
+<ClientComponent items={Array.from(set)} />
+```
+
+### 3. Server Actions Are the Exception
+
+Functions marked with `'use server'` CAN be passed to client components.
+
+```tsx
+// Valid: Server Action can be passed
+// actions.ts
+'use server'
+export async function submitForm(formData: FormData) {
+  // server-side logic
+}
+
+// page.tsx (server)
+import { submitForm } from './actions'
+export default function Page() {
+  return <ClientForm onSubmit={submitForm} /> // OK!
+}
+
+// ClientForm.tsx (client)
+'use client'
+export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
+  return <form action={onSubmit}>...</form>
+}
+```
+
+## Quick Reference
+
+| Pattern | Valid? | Fix |
+|---------|--------|-----|
+| `'use client'` + `async function` | No | Fetch in server parent, pass data |
+| Pass `() => {}` to client | No | Define in client or use server action |
+| Pass `new Date()` to client | No | Use `.toISOString()` |
+| Pass `new Map()` to client | No | Convert to object/array |
+| Pass class instance to client | No | Pass plain object |
+| Pass server action to client | Yes | - |
+| Pass `string/number/boolean` | Yes | - |
+| Pass plain object/array | Yes | - |