@polymorphism-tech/morph-spec 4.10.7 → 4.10.9

package/framework/skills/level-0-meta/morph-code-review-nextjs/references/review-example-nextjs.md

@@ -1,254 +1,254 @@
-# Code Review Report — User Management Feature
-
-> Example of a well-structured Next.js code review output. Filled-in reference — not a template.
-
-**Scope:** `src/features/users/` + `src/app/(dashboard)/users/page.tsx`
-**Date:** 2026-02-23
-**Reviewer:** code-review-nextjs skill
-
----
-
-## Automated Scan Results
-
-```bash
-$ node scripts/scan-nextjs.mjs src/features/users/
-
-CRITICAL (1)
-  features/users/components/UserList.tsx:1  — React hooks used (useState) without 'use client'
-
-HIGH/MEDIUM (2)
-  features/users/components/UserList.tsx  — PascalCase filename (should be user-list.tsx)
-  features/users/components/user-form.tsx — 'use client' directive present but no interactivity detected
-
-Summary: 8 files scanned | 3 issues (1 critical, 2 high/medium)
-```
-
----
-
-## Findings by Severity
-
-| Severity | Count |
-|----------|-------|
-| CRITICAL | 2 |
-| HIGH | 3 |
-| MEDIUM | 2 |
-| LOW | 1 |
-
----
-
-### [CRITICAL] Missing 'use client' on interactive component
-
-**File:** `src/features/users/components/UserList.tsx:1`
-
-**Current code:**
-```tsx
-import { useState } from 'react';
-
-export function UserList() {
-  const [selected, setSelected] = useState<string | null>(null);
-  return <div onClick={() => setSelected('test')}>...</div>;
-}
-```
-
-**Suggested fix:**
-```tsx
-'use client';
-
-import { useState } from 'react';
-// ... rest unchanged
-```
-
-**Why:** React hooks (`useState`) require `'use client'`. Without it, Next.js treats this as a Server Component and the `useState` call fails at runtime.
-
----
-
-### [CRITICAL] useEffect for data fetching
-
-**File:** `src/features/users/components/user-list.tsx:8`
-
-**Current code:**
-```tsx
-'use client';
-import { useEffect, useState } from 'react';
-
-export function UserList() {
-  const [users, setUsers] = useState([]);
-  useEffect(() => {
-    fetch('/api/users').then(r => r.json()).then(setUsers);
-  }, []);
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
-}
-```
-
-**Suggested fix:**
-```tsx
-// Option A — Server Component (no 'use client' needed)
-// app/(dashboard)/users/page.tsx
-async function getUsers() {
-  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
-  return res.json();
-}
-export default async function UsersPage() {
-  const users = await getUsers();
-  return <UserList initialData={users} />;
-}
-
-// Option B — TanStack Query (when client interactivity needed)
-'use client';
-import { useUsers } from '@/features/users/hooks/use-users';
-export function UserList() {
-  const { data: users = [], isLoading } = useUsers();
-  if (isLoading) return <div>Loading...</div>;
-  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
-}
-```
-
-**Why:** `useEffect` + `useState` for fetching: (1) doubles renders, (2) no caching, (3) no SSR, (4) no error/loading states, (5) can't be cancelled. TanStack Query or Server Components solve all five.
-
----
-
-### [HIGH] PascalCase file name
-
-**File:** `src/features/users/components/UserList.tsx`
-
-**Suggested fix:** Rename to `user-list.tsx`
-
-**Why:** Linux servers are case-sensitive. `UserList.tsx` and `user-list.tsx` are different files on the server but the same on macOS/Windows, causing import failures in production.
-
----
-
-### [HIGH] Default export on non-page component
-
-**File:** `src/features/users/components/user-card.tsx:3`
-
-**Current code:**
-```tsx
-export default function UserCard({ user }: { user: User }) {
-```
-
-**Suggested fix:**
-```tsx
-export function UserCard({ user }: { user: User }) {
-```
-
-**Why:** Named exports are refactor-safe — IDEs track renames automatically. Default exports are anonymous in imports (`import X from './user-card'` allows `X` to be anything).
-
----
-
-### [HIGH] Type defined manually instead of deriving from Zod schema
-
-**File:** `src/features/users/types/user.types.ts:1`
-
-**Current code:**
-```ts
-export type User = {
-  id: string;
-  name: string;
-  email: string;
-  role: 'admin' | 'user';
-};
-```
-
-**Suggested fix:**
-```ts
-// user.schemas.ts — single source of truth
-export const userSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  role: z.enum(['admin', 'user']),
-});
-
-// user.types.ts — derived, never written manually
-export type User = z.infer<typeof userSchema>;
-```
-
-**Why:** Manually written types drift from API responses. `z.infer<>` ensures the TypeScript type is always in sync with the runtime validation.
-
----
-
-### [MEDIUM] Deep path import instead of feature index
-
-**File:** `src/app/(dashboard)/users/page.tsx:2`
-
-**Current code:**
-```tsx
-import { UserList } from '@/features/users/components/user-list';
-```
-
-**Suggested fix:**
-```tsx
-import { UserList } from '@/features/users';
-```
-
-**Why:** Deep path imports expose internal structure. When `user-list.tsx` moves or is renamed, every consumer breaks. The feature index is the stable public API.
-
----
-
-### [MEDIUM] Query key not using factory pattern
-
-**File:** `src/features/users/hooks/use-users.ts:8`
-
-**Current code:**
-```ts
-return useQuery({
-  queryKey: ['users'],
-```
-
-**Suggested fix:**
-```ts
-// query-keys.ts
-export const userKeys = {
-  all: ['users'] as const,
-  lists: () => [...userKeys.all, 'list'] as const,
-};
-
-// use-users.ts
-return useQuery({
-  queryKey: userKeys.lists(),
-```
-
-**Why:** Hardcoded `['users']` cannot be selectively invalidated. `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` correctly invalidates only list queries, not detail queries with the same prefix.
-
----
-
-### [LOW] Test uses fireEvent instead of userEvent
-
-**File:** `src/features/users/components/user-card.test.tsx:14`
-
-**Current code:**
-```tsx
-fireEvent.click(screen.getByRole('button', { name: /edit/i }));
-```
-
-**Suggested fix:**
-```tsx
-await userEvent.click(screen.getByRole('button', { name: /edit/i }));
-```
-
-**Why:** `fireEvent.click` dispatches a synthetic event. `userEvent.click` simulates the full browser interaction sequence (pointerdown, mousedown, focus, click, etc.) — closer to real user behaviour.
-
----
-
-## Top Priorities
-
-1. `UserList.tsx:1` — CRITICAL missing `'use client'` (2 min fix)
-2. `user-list.tsx:8` — CRITICAL useEffect fetch → useQuery (15 min)
-3. `UserList.tsx` — HIGH rename to `user-list.tsx` (2 min)
-4. `user-card.tsx:3` — HIGH named export (2 min)
-5. `user.types.ts:1` — HIGH derive from Zod (10 min)
-
----
-
-## Passed Checks ✅
-
-- `components/ui/` files untouched
-- `zodResolver` correctly wired in `user-form.tsx`
-- `isPending` used (v5 correct — not `isLoading`)
-- `loading.tsx` and `error.tsx` present in `app/(dashboard)/users/`
-- Feature has `index.ts` re-exporting public API
-- Test file co-located with component
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Code Review Report — User Management Feature
+
+> Example of a well-structured Next.js code review output. Filled-in reference — not a template.
+
+**Scope:** `src/features/users/` + `src/app/(dashboard)/users/page.tsx`
+**Date:** 2026-02-23
+**Reviewer:** code-review-nextjs skill
+
+---
+
+## Automated Scan Results
+
+```bash
+$ node scripts/scan-nextjs.mjs src/features/users/
+
+CRITICAL (1)
+  features/users/components/UserList.tsx:1  — React hooks used (useState) without 'use client'
+
+HIGH/MEDIUM (2)
+  features/users/components/UserList.tsx  — PascalCase filename (should be user-list.tsx)
+  features/users/components/user-form.tsx — 'use client' directive present but no interactivity detected
+
+Summary: 8 files scanned | 3 issues (1 critical, 2 high/medium)
+```
+
+---
+
+## Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | 2 |
+| HIGH | 3 |
+| MEDIUM | 2 |
+| LOW | 1 |
+
+---
+
+### [CRITICAL] Missing 'use client' on interactive component
+
+**File:** `src/features/users/components/UserList.tsx:1`
+
+**Current code:**
+```tsx
+import { useState } from 'react';
+
+export function UserList() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return <div onClick={() => setSelected('test')}>...</div>;
+}
+```
+
+**Suggested fix:**
+```tsx
+'use client';
+
+import { useState } from 'react';
+// ... rest unchanged
+```
+
+**Why:** React hooks (`useState`) require `'use client'`. Without it, Next.js treats this as a Server Component and the `useState` call fails at runtime.
+
+---
+
+### [CRITICAL] useEffect for data fetching
+
+**File:** `src/features/users/components/user-list.tsx:8`
+
+**Current code:**
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+export function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers);
+  }, []);
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Suggested fix:**
+```tsx
+// Option A — Server Component (no 'use client' needed)
+// app/(dashboard)/users/page.tsx
+async function getUsers() {
+  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
+  return res.json();
+}
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialData={users} />;
+}
+
+// Option B — TanStack Query (when client interactivity needed)
+'use client';
+import { useUsers } from '@/features/users/hooks/use-users';
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Why:** `useEffect` + `useState` for fetching: (1) doubles renders, (2) no caching, (3) no SSR, (4) no error/loading states, (5) can't be cancelled. TanStack Query or Server Components solve all five.
+
+---
+
+### [HIGH] PascalCase file name
+
+**File:** `src/features/users/components/UserList.tsx`
+
+**Suggested fix:** Rename to `user-list.tsx`
+
+**Why:** Linux servers are case-sensitive. `UserList.tsx` and `user-list.tsx` are different files on the server but the same on macOS/Windows, causing import failures in production.
+
+---
+
+### [HIGH] Default export on non-page component
+
+**File:** `src/features/users/components/user-card.tsx:3`
+
+**Current code:**
+```tsx
+export default function UserCard({ user }: { user: User }) {
+```
+
+**Suggested fix:**
+```tsx
+export function UserCard({ user }: { user: User }) {
+```
+
+**Why:** Named exports are refactor-safe — IDEs track renames automatically. Default exports are anonymous in imports (`import X from './user-card'` allows `X` to be anything).
+
+---
+
+### [HIGH] Type defined manually instead of deriving from Zod schema
+
+**File:** `src/features/users/types/user.types.ts:1`
+
+**Current code:**
+```ts
+export type User = {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+};
+```
+
+**Suggested fix:**
+```ts
+// user.schemas.ts — single source of truth
+export const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+});
+
+// user.types.ts — derived, never written manually
+export type User = z.infer<typeof userSchema>;
+```
+
+**Why:** Manually written types drift from API responses. `z.infer<>` ensures the TypeScript type is always in sync with the runtime validation.
+
+---
+
+### [MEDIUM] Deep path import instead of feature index
+
+**File:** `src/app/(dashboard)/users/page.tsx:2`
+
+**Current code:**
+```tsx
+import { UserList } from '@/features/users/components/user-list';
+```
+
+**Suggested fix:**
+```tsx
+import { UserList } from '@/features/users';
+```
+
+**Why:** Deep path imports expose internal structure. When `user-list.tsx` moves or is renamed, every consumer breaks. The feature index is the stable public API.
+
+---
+
+### [MEDIUM] Query key not using factory pattern
+
+**File:** `src/features/users/hooks/use-users.ts:8`
+
+**Current code:**
+```ts
+return useQuery({
+  queryKey: ['users'],
+```
+
+**Suggested fix:**
+```ts
+// query-keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+};
+
+// use-users.ts
+return useQuery({
+  queryKey: userKeys.lists(),
+```
+
+**Why:** Hardcoded `['users']` cannot be selectively invalidated. `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` correctly invalidates only list queries, not detail queries with the same prefix.
+
+---
+
+### [LOW] Test uses fireEvent instead of userEvent
+
+**File:** `src/features/users/components/user-card.test.tsx:14`
+
+**Current code:**
+```tsx
+fireEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Suggested fix:**
+```tsx
+await userEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Why:** `fireEvent.click` dispatches a synthetic event. `userEvent.click` simulates the full browser interaction sequence (pointerdown, mousedown, focus, click, etc.) — closer to real user behaviour.
+
+---
+
+## Top Priorities
+
+1. `UserList.tsx:1` — CRITICAL missing `'use client'` (2 min fix)
+2. `user-list.tsx:8` — CRITICAL useEffect fetch → useQuery (15 min)
+3. `UserList.tsx` — HIGH rename to `user-list.tsx` (2 min)
+4. `user-card.tsx:3` — HIGH named export (2 min)
+5. `user.types.ts:1` — HIGH derive from Zod (10 min)
+
+---
+
+## Passed Checks ✅
+
+- `components/ui/` files untouched
+- `zodResolver` correctly wired in `user-form.tsx`
+- `isPending` used (v5 correct — not `isLoading`)
+- `loading.tsx` and `error.tsx` present in `app/(dashboard)/users/`
+- Feature has `index.ts` re-exporting public API
+- Test file co-located with component
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/morph-init/SKILL.md

@@ -42,17 +42,19 @@ Use the resolved CLI prefix (e.g. `npx morph-spec`) for ALL bash commands in the
 
 ## Step 1 — Required Plugins
 
-Check for required Claude Code plugins: **superpowers** and **context7**.
+Check for required Claude Code plugins: **superpowers**, **context7**, and **playwright**.
 
 Read `~/.claude/plugins/installed_plugins.json` and check for:
 - `superpowers@claude-plugins-official`
 - `context7@claude-plugins-official`
+- `playwright@claude-plugins-official`
 
 For each missing plugin, run:
 
 ```bash
 claude plugin install superpowers@claude-plugins-official
 claude plugin install context7@claude-plugins-official
+claude plugin install playwright@claude-plugins-official
 ```
 
 **If the command succeeds:** `✓ {plugin} installed. Restart Claude Code after /morph-init completes.`
@@ -66,7 +68,7 @@ Run manually and restart Claude Code:
 Then re-run /morph-init.
 ```
 
-Both `superpowers` and `context7` are required. Do not continue if either is missing.
+All three plugins are required. Do not continue if any is missing.
 
 ---
 
@@ -151,6 +153,137 @@ Do **not** ask about technology already confirmed by file evidence.
 
 ---
 
+## Step 4.5 — Scaffold Design System
+
+### 4.5.0 — Check if DS already exists
+
+```
+Read: .morph/context/design-system.md
+```
+
+**If the file EXISTS with non-TODO content in the Aesthetic Direction section:**
+→ Skip steps 4.5.1–4.5.2. Print: `✓ Design system found — .morph/context/design-system.md`
+
+### 4.5.1 — ALWAYS scan for existing CSS tokens
+
+Search for existing CSS custom properties across the project's frontend directories.
+
+Glob these patterns (exclude `node_modules/`, `.next/`, `dist/`, `build/`):
+```
+wwwroot/**/*.css
+wwwroot/**/*.scss
+styles/**/*.css
+src/styles/**/*.css
+src/**/*.css
+src/**/*.scss
+src/**/*.module.css
+public/**/*.css
+```
+
+For each CSS/SCSS file found, Grep for `:root {` blocks containing `--` custom properties.
+
+Track:
+- `cssTokensFound` (bool)
+- `tokenCount` (int — total number of `--variable` lines found)
+- `sourceFiles` (array of file paths that had tokens)
+
+### 4.5.2 — Decision tree
+
+**Case A: CSS tokens found (existing project)**
+
+1. Create `.morph/context/design-system.md` from scanned tokens:
+   - `## Color Tokens` → `:root { }` block with all found color variables (preserve exact variable names from CSS)
+   - `## Typography` → found font-family values (map to `--font-display` / `--font-body` by variable name heuristic)
+   - `## Spacing Tokens` → found spacing variables
+   - `## Aesthetic Direction` → `#TODO` (requires user judgment — fill in during `/morph-phase-uiux`)
+   - `## Changelog` → `- [today's date] [morph-init] Auto-generated from CSS scan ([N] tokens from [files])`
+
+2. Skip the `AskUserQuestion` for direction/brand color — the project has established colors
+
+3. Print:
+   ```
+   ✓ Design system scaffolded from existing CSS
+     Source: [file list]
+     Tokens: [N] colors, [M] font families, [K] spacing values
+     Note: Aesthetic Direction is TODO — fill in during /morph-phase-uiux
+   ```
+
+4. Continue to Step 5.
+
+**Case B: No CSS tokens found (greenfield project)**
+
+1. Copy the template:
+   ```bash
+   cp .morph/framework/templates/context/design-system.md .morph/context/design-system.md
+   ```
+   *(The template is at `framework/templates/context/design-system.md` in the installed framework)*
+
+2. Ask 3 quick questions using `AskUserQuestion`:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Design System Setup",
+      "question": "Let's set up your project's design system. What is the aesthetic direction for [ProjectName]?",
+      "multiSelect": false,
+      "options": [
+        { "label": "Minimal Refined", "description": "Luxurious and precise — elegant serif + light sans, monochromatic + 1 sharp accent" },
+        { "label": "Editorial", "description": "Magazine-grade, opinionated — strong display font + high contrast, dramatic reveals" },
+        { "label": "Soft Professional", "description": "Warm and trustworthy — rounded sans + warm pastels, gentle micro-interactions" },
+        { "label": "Industrial", "description": "Technical and direct — monospace/condensed + neutral colors, minimal motion" },
+        { "label": "Modern Luxury", "description": "Exclusive and refined — italic display + dark background + gold/copper accent" },
+        { "label": "Skip for now", "description": "Leave as TODO — fill in manually later" }
+      ]
+    }
+  ]
+}
+```
+
+3. **If user chose a direction (not "Skip for now")**, ask a follow-up:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Brand Color",
+      "question": "What is your approximate dominant/primary color? (You can adjust exact values later)",
+      "multiSelect": false,
+      "options": [
+        { "label": "Deep blue/navy", "description": "Professional, trustworthy" },
+        { "label": "Rich green", "description": "Growth, sustainability" },
+        { "label": "Warm orange/red", "description": "Energy, urgency" },
+        { "label": "Cool purple/violet", "description": "Creative, premium" },
+        { "label": "True black/dark", "description": "Minimal, premium, editorial" },
+        { "label": "I'll specify manually", "description": "Leave as TODO" }
+      ]
+    }
+  ]
+}
+```
+
+4. Fill in the design-system.md with user responses:
+
+| User answered | What to update |
+|--------------|----------------|
+| Direction chosen | Replace `[Minimal Refined / Editorial / ...]` with chosen direction. Update Font Pair with the correct fonts: Minimal Refined → Cormorant Garamond + DM Sans; Editorial → Playfair Display + Source Sans 3; Soft Professional → Nunito + Inter; Industrial → JetBrains Mono + IBM Plex Sans; Modern Luxury → Bodoni Moda + Sora |
+| Color chosen | Replace `--color-primary: #TODO` with a reasonable hex for that color family: deep blue → #1e3a5f, rich green → #065f46, warm orange → #c2410c, purple → #6d28d9, black → #0a0a0a. Add note: "Adjust exact values to match your brand" |
+| "Skip for now" | Leave all TODOs in place |
+
+5. Update the Changelog in design-system.md:
+   Add entry: `- [today's date] [morph-init] Initial scaffold from morph-init`
+
+6. Print confirmation:
+   ```
+   ✓ Design system scaffolded — .morph/context/design-system.md
+     Direction: [chosen direction or "TODO — fill in manually"]
+     Edit to refine exact token values before the UI/UX phase.
+   ```
+
+7. Continue to Step 5.
+
+---
+
 ## Step 5 — Generate `context/README.md`
 
 Write `.morph/context/README.md`:
@@ -358,7 +491,7 @@ For Node.js CLI projects, update config:
 Before printing the summary, check `~/.claude/settings.local.json` for `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. If set to `"1"`, mark Agent Teams as enabled; otherwise show the warning.
 
 ```
-✓ Plugins:       superpowers ✓   context7 ✓
+✓ Plugins:       superpowers ✓   context7 ✓   playwright ✓
 ✓ Infrastructure: .morph/ structure, hooks, agents, rules, skills
 ✓ Agents:        [N] total ([T1] orchestrators, [T2] domain leaders, [S] specialists)
 ✓ context/README.md generated