260224:1606 20260224:1600 V1.8.0

.agents/workflows/create-frontend-page.md

@@ -0,0 +1,64 @@
+---
+description: Create a new Next.js App Router page following project standards
+---
+
+# Create Next.js Frontend Page
+
+Use this workflow when creating a new page in `frontend/app/`.
+Follows `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`, ADR-011, ADR-012, ADR-013, ADR-014.
+
+## Steps
+
+1. **Determine route** — decide the route path, e.g. `app/(dashboard)/documents/page.tsx`
+
+2. **Classify components** — decide what is Server Component (default) vs Client Component (`'use client'`)
+   - Server Component: initial data load, static content, SEO
+   - Client Component: interactivity, forms, TanStack Query hooks, Zustand
+
+3. **Create page file** — Server Component by default:
+
+```typescript
+// app/(dashboard)/<route>/page.tsx
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: '<Page Title> | LCBP3-DMS',
+};
+
+export default async function <PageName>Page() {
+  return (
+    <div>
+      {/* Page content */}
+    </div>
+  );
+}
+```
+
+4. **Create API hook** (if client-side data needed) — add to `hooks/use-<feature>.ts`:
+
+```typescript
+'use client';
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '@/lib/api-client';
+
+export function use<Feature>() {
+  return useQuery({
+    queryKey: ['<feature>'],
+    queryFn: () => apiClient.get('<endpoint>'),
+  });
+}
+```
+
+5. **Build UI components** — use Shadcn/UI primitives. Place reusable components in `components/<feature>/`.
+
+6. **Handle forms** — use React Hook Form + Zod schema validation. Never access form values without validation.
+
+7. **Handle errors** — add `error.tsx` alongside `page.tsx` for route-level error boundaries.
+
+8. **Add loading state** — add `loading.tsx` for Suspense fallback if page does async work.
+
+9. **Add to navigation** — update sidebar/nav config if the page should appear in the menu.
+
+10. **Access control** — ensure page checks CASL permissions. Redirect unauthorized users via middleware or `notFound()`.
+
+11. **Citation** — confirm implementation references `specs/01-Requirements/` and `specs/05-Engineering-Guidelines/05-03-frontend-guidelines.md`