@pavp/wavefront 0.1.0 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@
 Claude Code agent framework for apps generated by **scaffold-nextjs-app**
 (Next.js 15 · React 19 · MUI 7 · React Query · Zustand · RHF + Zod · next-intl · Jest/RTL · Clean Architecture).
 
-5 specialist agents + 19 self-contained skills + a 9-command orchestration loop, so you describe work items instead of writing boilerplate. Generates responsive, composed UI continuous with your app — from a Figma export, screenshot, description, or nothing — with a colocated test in every layer.
+5 specialist agents + 20 self-contained skills + a 9-command orchestration loop, so you describe work items instead of writing boilerplate. Generates responsive, composed UI continuous with your app — from a Figma export, screenshot, description, or nothing — with a colocated test in every layer.
 
 > Distilled from real scaffold code, pinned at commit `8edaa0b` (modules `todo`/`auth`, `about-view`, `test/`, `src/i18n`). Not from docs — from the source. E2E-validated against a generated app.
 
@@ -166,6 +166,7 @@ Design:
 - `design-intake` — normalize any design source (Figma export/image/HTML/reference/description/none) → design-spec mapped to `@/ui`+tokens
 - `responsive-layouts` — mandatory mobile-first responsive: theme breakpoints + responsive `sx` + `useResponsiveScreen`
 - `component-composition` — decompose into subcomponents; composition over inheritance; compound components (Modal pattern)
+- `error-boundary` — recoverable error+retry state every data-fetching view renders when its query fails
 
 Meta:
 - `sync-audit` — detect skill drift vs scaffold `source_version` (used by `reviewer` audit mode)
@@ -217,10 +218,10 @@ This repo follows **Conventional Commits**, enforced by commitlint (`commit-msg`
 
 ## Roadmap (see `docs/plan.md` + `docs/roadmap.md`)
 
-- ✅ **MVP** — 5 agents + 19 skills, E2E-validated.
+- ✅ **MVP** — 5 agents + 20 skills, E2E-validated.
 - ✅ **F4** — `sync-audit` drift detection (reviewer audit mode).
 - ✅ **F5** — quality-gate hooks (eslint/stylelint on edit, tsc on stop).
 - ✅ **F1** — standalone repo + global/local install + **npm distribution (F1d)**. Scaffold auto-injection (F1c) not pursued.
 - ✅ **F2** — orchestration loop (`/wavefront-*`) + parallel waves + change/fix flows.
 - ✅ **F6/F7** — design intake (incl. live Figma MCP) + component composition.
-- ⏳ **F3** — per-layer agent subdivision — only open phase, gated on a measured win over the broad builder.
+- ❌ **F3** — per-layer agent subdivision — **won't ship**: linear layer deps mean zero intra-module parallelism, and F2 waves already parallelize across modules. Broad builder stands.

package/agents/module-builder.md

@@ -13,7 +13,7 @@ The implementer that owns the full Clean Architecture chain for a feature module
 
 ## Operating rules
 - Always: read the knowledge skills before generating; mirror the `todo`/`auth` reference modules; use kebab-case + correct suffixes; respect layer direction (View → business hook → repository → gateway → api); type boundaries with interfaces; validate at the api boundary with Zod; build UI from `@/ui` + `@/styles/tokens`; create `index.ts` barrels; pass `dataSource` (default `'http'`) through repository/selector/hook signatures.
-- Always (UI): before writing views/components, read `design-system-inventory` (catalog + continuity) and `responsive-layouts`; if a design-spec exists, implement it. With NO design, follow the continuity rule — mirror the closest existing screen's components/layout/spacing. Always implement the four states (loading/empty/error/populated). Never hand-roll raw `<div>`/`<input>` to match a visual — translate to `@/ui` + tokens.
+- Always (UI): before writing views/components, read `design-system-inventory` (catalog + continuity) and `responsive-layouts`; if a design-spec exists, implement it. With NO design, follow the continuity rule — mirror the closest existing screen's components/layout/spacing. Always implement the four states (loading/empty/error/populated). For the **error** state, every data-fetching view returns the error-boundary pattern (an error+retry component wired to the query's `refetch`) when its business hook reports `error` — never let a failed fetch render blank (see `error-boundary` skill). Never hand-roll raw `<div>`/`<input>` to match a visual — translate to `@/ui` + tokens.
 - Always (responsive — mandatory): every view/component is mobile-first responsive using the theme's custom breakpoints (`minMobile`/`minTablet`/`minDesktop`/`largeScreen`, NOT xs/sm/md) via `sx` objects (`{ minMobile: ..., minTablet: ... }`) or `useResponsiveScreen` for branching. No fixed pixel widths that overflow mobile; the four states are responsive too.
 - Always (composition — mandatory): decompose UI into focused subcomponents under `components/` (mirror todo: `*-form`, `*-item`, `*-list`, sections) — the view ORCHESTRATES + wires hooks, it does NOT hold all markup inline. Apply the `component-composition` "when to extract" decision rule: **anything rendered inside `.map()` is ALWAYS its own component** (a list extracts its item — never inline JSX in the map); also extract on distinct responsibility, reuse, own state/handlers, ~30–40+ line JSX blocks. Extraction is recursive — components have subcomponents too. Compose via children/props; for multi-part UI use the compound-component pattern. NO inheritance, NO boolean-prop explosion. Each component independently renderable + testable. Don't over-fragment trivial markup.
 - Always: after generating, run `tsc --noEmit` (or `yarn typecheck`) and `yarn lint`; fix what you generated until clean; then hand off to `tester` and `reviewer`.
@@ -39,6 +39,7 @@ The implementer that owns the full Clean Architecture chain for a feature module
 - `.claude/skills/design-intake/SKILL.md` — the design-spec to implement (when a design source was provided).
 - `.claude/skills/responsive-layouts/SKILL.md` — mandatory mobile-first responsive: theme breakpoints + `sx` responsive + `useResponsiveScreen`.
 - `.claude/skills/component-composition/SKILL.md` — decompose UI into subcomponents; composition over inheritance; compound components (Modal pattern).
+- `.claude/skills/error-boundary/SKILL.md` — recoverable error state (error+retry component) every data view returns when its business hook reports an error.
 
 ## Workflow
 1. Read all knowledge skills.

package/agents/reviewer.md

@@ -33,7 +33,7 @@ Convention and architecture guardian for scaffold-nextjs-app projects. Reads cod
    - Structure: files live in the right layer dir; module shape matches `module-structure`; absolute `@/` imports.
    - Architecture: dependency direction (no View→API/gateway; goes through repository); dependency inversion; no side effects in render; business hook vs controller hook separated.
    - Imports: import-sort order; restricted-import rule (test bits from `@test/utils/test-utils`).
-   - UI/responsive: UI from `@/ui` (not raw `@mui/material`); spacing/color via tokens (no literals); strings via next-intl; **responsive present** — no fixed pixel widths that overflow mobile, breakpoint usage via theme keys (`minMobile`/`minTablet`/`minDesktop`, not xs/sm/md); the four states (loading/empty/error/populated) handled.
+   - UI/responsive: UI from `@/ui` (not raw `@mui/material`); spacing/color via tokens (no literals); strings via next-intl; **responsive present** — no fixed pixel widths that overflow mobile, breakpoint usage via theme keys (`minMobile`/`minTablet`/`minDesktop`, not xs/sm/md); the four states (loading/empty/error/populated) handled — for a data-fetching view the **error** state must render a recoverable error+retry UI (error-boundary pattern wired to `refetch`); BLOCKER if a failed query renders blank.
    - Composition: UI decomposed into `components/` subcomponents (no monolithic view holding form+list+states inline); composition over inheritance; no boolean-prop explosion; each component independently testable. **Flag inline JSX inside `.map()`** — a mapped row/item must be its own component (e.g. list → item), not inline markup. Apply the "when to extract" rule (map / distinct responsibility / own state / ~30–40+ lines); also flag over-fragmentation of trivial markup.
    - Test coverage (per layer): flag any logic layer WITHOUT a colocated test — api, gateway, repository queries+mutations, store, selectors, business+controller hooks, helpers, each component, view. One happy-path test ≠ covered. Note missing unit vs integration.
 4. Tooling pass: run `yarn lint` and `yarn typecheck` if present; capture real errors.

package/agents/tester.md

@@ -24,8 +24,8 @@ Mirror the scaffold (`src/modules/todo` has a colocated test in EVERY layer). Fo
 - **selectors** (each `*-selector.hook.test.ts`) — derived value correct.
 - **hooks** — business (`*-business.hook.test.ts`) AND controller (`*-controller.hook.test.ts`).
 - **helpers** (`*.helper.test.ts`) — pure unit tests.
-- **components** (each subcomponent `*.component.test.tsx`) — renders, props, interactions.
-- **view** (`*.view.test.tsx`) — composes parts, the four states render.
+- **components** (each subcomponent `*.component.test.tsx`) — renders, props, interactions. Includes the **error-boundary** component (`error-boundary.component.test.tsx`): renders nothing on `error={null}`, shows message + retry on error, calls `onRetry` on click.
+- **view** (`*.view.test.tsx`) — composes parts, the four states render — including the **error** state (a failing query shows the error+retry UI, not blank).
 
 **Unit vs integration:** unit = pure pieces in isolation (helpers, store, a presentational component with mock props). Integration = pieces wired through providers (`renderHookWithProviders` for a business hook hitting repository→gateway→api; a view rendered with real hooks). Cover both — unit for logic correctness, integration for the wiring.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pavp/wavefront",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Claude Code frontend-engineering agent framework for scaffold-nextjs-app apps (Next.js/React/MUI/Clean Architecture). Installs agents, skills, and an orchestration loop into a project's .claude/.",
   "bin": {
     "wavefront": "bin/wavefront.js"

package/skills/error-boundary/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: error-boundary
+description: Render a recoverable error state for data-driven views in scaffold-nextjs-app — an error+retry presentation component the view returns when its business hook reports an error. Read before building any view that fetches data.
+source: scaffold-nextjs-app/src/modules/todo/components/error-boundary, src/modules/todo/views/todo-management
+source_version: 8edaa0b
+---
+
+# Error boundary (recoverable error state)
+
+Every data-driven view must handle the **error** state, not just loading/empty/populated. The scaffold's pattern is NOT a React class `ErrorBoundary` — it's a small **presentation component** that takes the query `error` + an `onRetry` callback and renders a recoverable error UI. The view early-returns it when its business hook surfaces an error.
+
+This is the "error" leg of the mandatory four states (loading | empty | error | populated). Without it, a failed fetch renders blank or a broken view.
+
+## The component
+
+Colocate under `components/error-boundary/` (kebab dir, `*.component.tsx` suffix). Props: `error: Error | null` + `onRetry: () => void`. `memo` it, build from `@/ui` + tokens, give it a `displayName`.
+
+```tsx
+'use client';
+
+import { memo, type MouseEvent, useCallback } from 'react';
+import { Refresh } from '@mui/icons-material';
+
+import tokens from '@/styles/tokens';
+import { Box, Button, Typography } from '@/ui';
+
+interface ErrorBoundaryProps {
+  error: Error | null;
+  onRetry: () => void;
+}
+
+export const ErrorBoundary = memo(({ error, onRetry }: ErrorBoundaryProps) => {
+  const handleRetry = useCallback(
+    (event?: MouseEvent<HTMLButtonElement>) => {
+      event?.preventDefault();
+      onRetry();
+    },
+    [onRetry],
+  );
+
+  if (!error) return null;
+
+  return (
+    <Box sx={{ p: tokens.spacing.scale6 }}>
+      <Typography color="error" variant="h6">
+        Error loading {/* entity, e.g. todos */}
+      </Typography>
+      <Typography color="error" variant="body2">
+        {error.message}
+      </Typography>
+      <Button startIcon={<Refresh />} sx={{ mt: tokens.spacing.scale4 }} onClick={handleRetry}>
+        Retry
+      </Button>
+    </Box>
+  );
+});
+
+ErrorBoundary.displayName = 'ErrorBoundary';
+```
+
+## Wiring it in the view
+
+The business hook exposes `error` (from the repository query) + `refetch`. The view early-returns the boundary before rendering the populated UI:
+
+```tsx
+const { todos, isLoading, error, refetch, /* ... */ } = useTodoManagementBusiness(dataSource);
+
+if (error) {
+  return <ErrorBoundary error={error} onRetry={refetch} />;
+}
+// ...normal render
+```
+
+- `onRetry` is the query's `refetch` — retry re-runs the failed fetch.
+- The view's business hook MUST surface both `error` and `refetch` (they come from React Query's `useQuery` result via the repository → see [[repository-pattern]] and [[hook-patterns]]).
+
+## Colocated test (role-first)
+
+```tsx
+import { fireEvent, renderWithProviders, screen } from '@test/utils';
+
+import { ErrorBoundary } from './error-boundary.component';
+
+describe('ErrorBoundary', () => {
+  const mockOnRetry = jest.fn();
+  beforeEach(() => mockOnRetry.mockClear());
+
+  it('renders nothing when error is null', () => {
+    const { container } = renderWithProviders(<ErrorBoundary error={null} onRetry={mockOnRetry} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders message + retry when error is provided', () => {
+    renderWithProviders(<ErrorBoundary error={new Error('boom')} onRetry={mockOnRetry} />);
+    expect(screen.getByText('boom')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument();
+  });
+
+  it('calls onRetry on click', () => {
+    renderWithProviders(<ErrorBoundary error={new Error('x')} onRetry={mockOnRetry} />);
+    fireEvent.click(screen.getByRole('button', { name: /retry/i }));
+    expect(mockOnRetry).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+## Rules
+
+- **Always:** every data-fetching view renders the error state via this component (or an equivalent error+retry UI). Never let a failed query render blank.
+- `onRetry` wires to the query's `refetch` — the error must be recoverable, not a dead end.
+- Build from `@/ui` + tokens (never raw `<div>` / hardcoded spacing); show `error.message`.
+- `memo` + `displayName`; `error: null` ⇒ render nothing.
+- Colocate the test; assert by role/text (see [[testing-jest-rtl]]).
+- **Never:** swallow the error silently; render the populated view when `error` is set; hardcode the error copy's spacing/color (use tokens + `color="error"`).
+
+## Related
+[[component-composition]] [[hook-patterns]] [[repository-pattern]] [[data-fetching-react-query]] [[testing-jest-rtl]] [[mui-design-tokens]]