get-shit-pretty 0.7.4 → 0.8.3

package/gsp/skills/gsp-project-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-build
-description: Translate designs to code (technical phase — benefits from capable models)
+description: Translate designs to code (technical phase — benefits from capable models) — use when: build this, implement, code this up, build me a X, add a X to the app, make the X page
 user-invocable: true
 allowed-tools:
   - Read
@@ -70,6 +70,8 @@ Implement designs as production-ready code in the codebase via phased pipeline w
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
@@ -83,7 +85,9 @@ Exception: if `design_scope` is `tokens` in config.json, skip this check (tokens
 
 ## Step 1: Load config and check state
 
-Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`, `codebase_type`.
+Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`, `codebase_type`, `app_path`.
+
+Set `APP_PATH` = value of `app_path`. If empty, default to `.` (repo root).
 
 ### Branch check
 
@@ -132,7 +136,7 @@ Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-builder.md`. Include the full
 Read these reference files:
 - `${CLAUDE_SKILL_DIR}/visual-effects.md`
 - `${CLAUDE_SKILL_DIR}/../gsp-project-design/block-patterns.md`
-- `${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/token-mapping.md`
+- `${CLAUDE_SKILL_DIR}/shadcn-composition.md`
 
 Hold their content for inlining into agent prompts in Steps 3, 4.5, 5, 7, and 8.
 
@@ -149,12 +153,13 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 | `{BRAND_PATH}/patterns/{brand-name}.yml` | Token values only — used with token-mapping.md to generate CSS variables. Do NOT re-read patterns/constraints/effects from here — those are in STYLE.md. |
 | `{BRAND_PATH}/patterns/STYLE.md` | Design law — philosophy, patterns, constraints, effects, bold bets, implementation hints (if exists; fall back to `{brand-name}.md`) |
 | `{PROJECT_PATH}/brief/target-adaptations.md` | Component adaptations for target |
-| `.design/system/STACK.md` | Stack state |
+| `.design/system/STACK.md` | Stack state (or `.design/system/stacks/{APP_NAME}.md` for monorepos) |
 | `.design/system/CONVENTIONS.md` | Codebase conventions (if exists) |
 | `.design/system/COMPONENTS.md` | Existing components (if exists) |
-| `{PROJECT_PATH}/config.json` | Tech stack, target |
+| `{PROJECT_PATH}/config.json` | Tech stack, target, `app_path` |
+| `APP_PATH = {APP_PATH}` | Working directory — all file writes and build commands run here |
 | Build output template (from execution_context) | Build log structure |
-| Token mapping ref (loaded in Step 2.6) | Deterministic `.yml` → CSS variable mapping per target (shadcn HSL, Tailwind, vanilla). Includes all 26+ shadcn variables, hex→HSL conversion, dark mode, shape/radius derivation. |
+| Token mapping ref (loaded in Step 2.6) | shadcn component composition rules, semantic token usage, `cn()`, `cva`, RSC patterns |
 | Visual effects, block patterns refs (loaded in Step 2.6) | Design patterns + CSS recipes |
 | Agent methodology (loaded in Step 2.5) | Builder role, process, quality standards |
 
@@ -164,7 +169,7 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 >
 > Build token integration, global styles, and layout primitives ONLY.
 >
-> 1. Integrate design tokens into the codebase using the token-mapping reference: read the `.yml` token values and the token-mapping.md spec, then generate CSS variables per target (shadcn: HSL space-separated in `:root`/`.dark`, Tailwind: custom properties + config extend, vanilla: full custom property system). Map ALL variables — not just colors: background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, and --radius.
+> 1. Integrate design tokens into the codebase: run `node bin/theme-css.js {brand-name}.yml --stdout` and paste the OKLCH `:root`/`.dark` output into `globals.css`. For shadcn targets, follow the `@theme inline` pattern from `shadcn-rules.md`. Map ALL variables — background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, and --radius.
 > 2. Create global CSS (resets, base styles, font imports, dark mode setup)
 > 3. Create root layout with nav shell and footer shell (structure only — no page content)
 > 4. Create shared utilities (cn helper, theme provider if needed)
@@ -178,14 +183,14 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 
 ### Checkpoint: Compile check
 
-After the foundations agent completes, run the build command:
+After the foundations agent completes, run the build command in `APP_PATH`:
 
 | Stack | Build command |
 |-------|--------------|
-| Next.js | `npx next build` |
-| Vite | `npx vite build` |
-| TypeScript only | `npx tsc --noEmit` |
-| Generic | `npm run build` |
+| Next.js | `cd {APP_PATH} && npx next build` |
+| Vite | `cd {APP_PATH} && npx vite build` |
+| TypeScript only | `cd {APP_PATH} && npx tsc --noEmit` |
+| Generic | `cd {APP_PATH} && npm run build` |
 
 **Pass:** Continue to preview verification, then Step 4.
 **Fail:** Log the error. Do NOT re-spawn the agent. Surface the error to the user and ask how to proceed.
@@ -497,25 +502,13 @@ Invoke `/gsp-phase-transition` with phase `build` and output directory `{PROJECT
 
 ## Step 7: Figma fallback
 
-For `implementation_target: figma`, skip the phased pipeline. Spawn a single `gsp-project-builder` agent with execution_mode: `full` and spec-only flag. Builder writes `build/CODE.md` + `build/components/` instead of editing codebase. Then continue from Step 6 (finalize).
-
-## Step 8: Revision mode
-
-For `needs-revision` status, spawn a single `gsp-project-builder` agent with execution_mode: `full` and `review/issues.md` contents. The agent fixes QA issues in the codebase and appends revision sections to BUILD-LOG.md.
+Read `${CLAUDE_SKILL_DIR}/flows/figma.md` for full instructions.
 
-### Checkpoint: Compile check
-
-After the revision agent completes, run the build command (same stack table as Step 3 checkpoint).
-
-**Pass:** Continue to brand feedback check below.
-**Fail:** Log the error. Surface to user: "Revision introduced build errors: {error}. Fix before finalizing?"
+For `implementation_target: figma`, skip the phased pipeline. Produce Figma-ready implementation specs instead of editing the codebase. Then continue from Step 6 (finalize).
 
-### Brand feedback on revisions
-
-After the revision agent completes, check if any QA fixes changed token-level values (colors, typography, spacing, shadows). If so:
+## Step 8: Revision mode
 
-1. Ask: "These revisions changed brand-level values. Update brand patterns so future projects inherit the fix?"
-2. If yes, spawn a background `gsp-brand-engineer` agent with the changed values to update `{BRAND_PATH}/patterns/`.
+Read `${CLAUDE_SKILL_DIR}/flows/revision.md` for full instructions.
 
-Then continue from Step 6 (finalize).
+For `needs-revision` status, fix QA issues from `review/issues.md` via a single revision agent. Then continue from Step 6 (finalize).
 </process>

package/gsp/skills/gsp-project-build/flows/figma.md

@@ -0,0 +1,50 @@
+# Build Flow: Figma Fallback
+
+Activated when `implementation_target` is `figma` in `config.json`.
+
+## When this runs
+
+When the project's target is Figma (designer handoff), there is no codebase to edit. Instead, the builder produces structured implementation specs that a developer can use to implement in Figma or hand off to their dev team.
+
+## Steps
+
+### 1. Log intent
+
+Log: "Figma target — producing implementation specs (no codebase to edit)"
+
+### 2. Spawn spec agent
+
+Spawn a single `gsp-project-builder` agent with:
+- `execution_mode: full`
+- `spec_only: true`
+- All design chunks from `{PROJECT_PATH}/design/` inlined
+- Brand system: `{BRAND_PATH}/patterns/STYLE.md` and `{BRAND_PATH}/patterns/{brand-name}.yml`
+- Brief: `{PROJECT_PATH}/brief/target-adaptations.md` and `{PROJECT_PATH}/brief/scope.md`
+- Agent methodology (loaded in Step 2.5 of main flow)
+
+Agent instructions:
+
+> execution_mode: full
+> spec_only: true
+>
+> Produce Figma-ready implementation specs — no codebase to edit.
+>
+> Output:
+> 1. `{PROJECT_PATH}/build/CODE.md` — component-by-component implementation guide:
+>    - For each screen: component tree, token values, interaction states, responsive behavior
+>    - For each component: props, variants, accessibility requirements
+>    - Token table: all CSS variables with values from the brand `.yml`
+>
+> 2. `{PROJECT_PATH}/build/components/` — one `.md` file per significant custom component:
+>    - Structure (HTML/JSX pseudocode)
+>    - Variants and states
+>    - Token usage (which CSS variables drive which properties)
+>    - Accessibility notes (ARIA roles, keyboard, focus)
+>
+> Format specs for developer consumption — be precise about measurements, colors (include both OKLCH and hex), and interaction behavior.
+
+### 3. Finalize
+
+After the spec agent completes, continue from Step 6 (Finalize) of the main build flow.
+
+`BUILD-LOG.md` in this mode documents spec files produced rather than codebase changes.

package/gsp/skills/gsp-project-build/flows/revision.md

@@ -0,0 +1,64 @@
+# Build Flow: Revision Mode
+
+Activated when `{PROJECT_PATH}/STATE.md` shows build status `needs-revision`.
+
+## When this runs
+
+After `/gsp-project-review` completes and writes `{PROJECT_PATH}/review/issues.md` with QA issues, the next invocation of `/gsp-project-build` enters revision mode automatically.
+
+## Steps
+
+### 1. Read issues
+
+Read `{PROJECT_PATH}/review/issues.md`. This file contains QA issues prioritized by severity.
+
+Log: "Revision mode — addressing QA issues from review/issues.md"
+
+### 2. Spawn revision agent
+
+Spawn a single `gsp-project-builder` agent with:
+- `execution_mode: full`
+- `revision: true`
+- Full content of `review/issues.md` inlined
+- Agent methodology (loaded in Step 2.5 of main flow)
+- Visual effects and block patterns refs (loaded in Step 2.6 of main flow)
+
+Agent instructions:
+
+> execution_mode: full
+> revision: true
+>
+> Fix the QA issues from review/issues.md in the codebase.
+>
+> 1. Work through issues in priority order (critical → high → medium → low)
+> 2. Read the relevant codebase files before editing — don't guess at existing structure
+> 3. Do NOT modify foundation files unless the QA issue explicitly requires it
+> 4. Do NOT refactor or improve code outside the scope of the listed issues
+> 5. Leave changes unstaged
+>
+> After completing revisions, append a `## Revision` section to `{PROJECT_PATH}/build/BUILD-LOG.md` listing each issue addressed (issue ID, file changed, what was fixed).
+
+### 3. Compile check
+
+After the revision agent completes, run the build command:
+
+| Stack | Build command |
+|-------|--------------|
+| Next.js | `npx next build` |
+| Vite | `npx vite build` |
+| TypeScript only | `npx tsc --noEmit` |
+| Generic | `npm run build` |
+
+**Pass:** Continue to brand feedback check.
+**Fail:** Log the error. Surface to user: "Revision introduced build errors: {error}. Fix before finalizing?"
+
+### 4. Brand feedback on revisions
+
+After the revision agent completes, check if any QA fixes changed token-level values (colors, typography, spacing, shadows). If so:
+
+1. Ask: "These revisions changed brand-level values. Update brand patterns so future projects inherit the fix?"
+2. If yes, spawn a background `gsp-brand-engineer` agent with the changed values to update `{BRAND_PATH}/patterns/`.
+
+### 5. Finalize
+
+Continue from Step 6 (Finalize) of the main build flow.

package/gsp/skills/gsp-project-build/methodology/gsp-project-builder.md

@@ -17,7 +17,7 @@ You are spawned with an `execution_mode` parameter. Follow the mode strictly:
 
 ### `foundations`
 Build token integration, global styles, and layout primitives ONLY. Stop after foundations.
-- Design tokens → CSS variables / Tailwind config. Use the **token-mapping.md** reference to map `.yml` values to the correct format per target. For shadcn: convert hex to HSL space-separated channels (e.g., `#1E40AF` → `221 72% 40%`), write ALL variables in `:root` and `.dark` scopes (background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, --radius). Write only **global tokens**: brand colors, font families, spacing scale, base radius, base shadows. Do NOT write screen-specific tokens yet.
+- Design tokens → CSS variables / Tailwind config. Run `node bin/theme-css.js <preset.yml> --stdout` to generate a ready-to-paste `:root` and `.dark` block in OKLCH format. If `bin/theme-css.js` is unavailable, convert hex to OKLCH manually. Write ALL variables in `:root` and `.dark` scopes (background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, sidebar-*, chart-1 through chart-5, --radius). Write only **global tokens**: brand colors, font families, spacing scale, base radius, base shadows. Do NOT write screen-specific tokens yet.
 - Global CSS (resets, base styles, dark mode)
 - Layout components (root layout, nav shell, footer shell)
 - Shared utilities (cn helper, theme provider)
@@ -125,19 +125,72 @@ These rules are always enforced for shadcn targets. They reflect the official sh
 - Use full Card composition (`CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`)
 - `TabsTrigger` must be inside `TabsList`
 - `Avatar` always needs `AvatarFallback`
-- Use `Alert` for callouts, `Badge` for status, `Skeleton` for loading, `Separator` for dividers, `sonner` for toast
+- Use `Alert` for callouts, `Badge` for status, `Skeleton` for loading, `Separator` for dividers, `Empty` for empty states, `sonner` for toast
+- `Button` has no `isPending`/`isLoading` prop — compose with `<Spinner data-icon="inline-start" />` + `disabled`
+
+**Forms:**
+- Use `FieldGroup` + `Field` for form layout — never raw `div` with `space-y-*` or `grid gap-*`
+- Option sets (2–7 choices) use `ToggleGroup` + `ToggleGroupItem` — not a loop of `Button` with manual active state
+- Buttons inside inputs use `InputGroup` + `InputGroupAddon` — not `relative` positioning with `absolute` button
+- Use `InputGroupInput` / `InputGroupTextarea` inside `InputGroup` — not raw `Input`/`Textarea`
+- Group related checkboxes/radios with `FieldSet` + `FieldLegend` — not `div` with a heading
+- Field validation: `data-invalid` on `Field`, `aria-invalid` on the control; `data-disabled` on `Field`, `disabled` on the control
+
+**base vs radix API (check `base` from `npx shadcn@latest info`):**
+- Custom triggers: `asChild` (radix) vs `render` prop (base)
+- Button as link: `<Button asChild><a>` (radix) vs `<Button render={<a />} nativeButton={false}>` (base)
+- `ToggleGroup`: radix uses `type="single"/"multiple"` + string `defaultValue`; base uses no `type` + array `defaultValue`
+- `Slider`: radix always uses array (`defaultValue={[50]}`); base uses plain number for single thumb
+- `Select`: base requires `items` prop on root; radix uses inline JSX only
 
 **Icons:**
-- Icons in `Button` use `data-icon` attribute (`data-icon="inline-start"` or `data-icon="inline-end"`)
+- Icons in `Button` use `data-icon` attribute (`data-icon="inline-start"` or `data-icon="inline-end"`) — do NOT add `mr-2`/`ml-2` margin; the component handles spacing via CSS
 - No sizing classes on icons inside components — components handle icon sizing via CSS
 
 **CLI awareness:**
 - Install components via `npx shadcn@latest add {name}` — never copy/paste from GitHub
-- Use `npx shadcn@latest search` to find components before building custom ones
+- Use `npx shadcn@latest search {name}` to find components before building custom ones
+- Use `npx shadcn@latest docs {name}` to get live docs and example URLs before implementing or debugging a component
+- Use `npx shadcn@latest add {name} --dry-run` to preview all affected files before writing
+- Use `npx shadcn@latest add {name} --diff {file}` to preview a specific file's changes before overwriting
 - After installing components from registries, verify imports match the project's alias config
+- After installing from community registries, check added non-UI files for hardcoded `@/components/ui/...` paths — rewrite to match the project's actual aliases
+
+**Charts (Recharts v3):**
+- Color references: `fill="var(--chart-1)"` or `fill="var(--color-chart-1)"` — **no `hsl()` wrapper** (tokens are OKLCH, not HSL channels)
+- `<ChartContainer>` **requires** an explicit height — add `className="min-h-[200px]"` or `aspect-video`; no implicit height is set
+- Add `accessibilityLayer` prop to chart root elements (`<BarChart accessibilityLayer>`)
+- The `layout` prop belongs on the parent chart (`<BarChart layout="vertical">`), not on `<Bar>`
+
+**Forms (React Hook Form + Field API):**
+- New projects use the `<Field>/<Controller>` API — not `<FormField>/<FormItem>/<FormControl>/<FormMessage>`:
+  ```jsx
+  <Controller
+    name="email"
+    control={form.control}
+    render={({ field, fieldState }) => (
+      <Field data-invalid={fieldState.invalid}>
+        <FieldLabel htmlFor={field.name}>Email</FieldLabel>
+        <Input {...field} id={field.name} aria-invalid={fieldState.invalid} />
+        {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+      </Field>
+    )}
+  />
+  ```
+- Components: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `FieldGroup`, `FieldSet`, `FieldLegend`
+- If the existing project has the old `form.tsx` (with `FormField`/`FormItem`), match its pattern — do not mix APIs
+
+**Sidebar:**
+- Set custom sidebar width via inline CSS prop on `<SidebarProvider>`:
+  ```jsx
+  <SidebarProvider style={{ "--sidebar-width": "20rem" } as React.CSSProperties}>
+  ```
+- Do not override `--sidebar-width` in `globals.css` — it belongs on the provider instance
 
 Full reference: `references/anti-patterns.md` (available via Read for the complete list with fixes).
 
+**Theming reference:** when building or fixing themes, read `${CLAUDE_SKILL_DIR}/../../gsp-scaffold/shadcn-theming.md` — full token table, dark mode setup, common theming bugs and fixes.
+
 ## Visual Quality Checklist
 
 Every screen must pass these before marking complete. When `STYLE.md` is provided, it overrides these defaults.

package/gsp/skills/gsp-project-build/shadcn-composition.md

@@ -0,0 +1,217 @@
+# shadcn/ui Rules — Tier 2: Component Composition
+
+Rules for the build phase. The builder agent reads this to compose shadcn components correctly.
+
+---
+
+## The `cn()` helper
+
+All conditional class merging uses `cn()` from `@/lib/utils`:
+
+```ts
+import { cn } from "@/lib/utils"
+
+// Correct
+<Button className={cn("mt-4", isActive && "ring-2 ring-ring")} />
+
+// Wrong — never string-concatenate classes
+<Button className={"mt-4" + (isActive ? " ring-2 ring-ring" : "")} />
+```
+
+`cn` is `clsx` + `tailwind-merge`. It handles class deduplication and Tailwind conflict resolution automatically.
+
+---
+
+## Semantic color tokens — always use these
+
+| Instead of | Use |
+|------------|-----|
+| `bg-white` / `bg-black` | `bg-background` |
+| `text-gray-900` | `text-foreground` |
+| `text-gray-500` | `text-muted-foreground` |
+| `bg-gray-100` | `bg-muted` |
+| `bg-gray-50` | `bg-secondary` |
+| `border-gray-200` | `border-border` |
+| `ring-blue-500` | `ring-ring` |
+| raw hex/rgb | Never — always a token |
+
+shadcn components use these tokens internally. Using them in custom code makes dark mode automatic.
+
+---
+
+## Slot pattern (asChild)
+
+Use `asChild` to merge props into a child component without an extra DOM node:
+
+```tsx
+// Button as a link
+<Button asChild>
+  <Link href="/dashboard">Dashboard</Link>
+</Button>
+
+// Never add an <a> inside <Button> without asChild
+```
+
+---
+
+## Variants with `cva`
+
+For custom components that need multiple variants, use `cva` (class-variance-authority):
+
+```tsx
+import { cva, type VariantProps } from "class-variance-authority"
+
+const cardVariants = cva(
+  "rounded-lg border bg-card text-card-foreground shadow",
+  {
+    variants: {
+      size: {
+        sm: "p-4",
+        md: "p-6",
+        lg: "p-8",
+      },
+      elevated: {
+        true: "shadow-lg",
+        false: "shadow-sm",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      elevated: false,
+    },
+  }
+)
+
+interface CardProps extends VariantProps<typeof cardVariants> {
+  className?: string
+}
+```
+
+---
+
+## Composing shadcn primitives
+
+shadcn components are composed from their sub-parts:
+
+```tsx
+// Card with all sub-parts
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Subtitle</CardDescription>
+  </CardHeader>
+  <CardContent>Content here</CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+**Rule:** never nest card-level markup inside `<Card>` without using `CardHeader`/`CardContent`/`CardFooter` — it breaks the spacing contract.
+
+---
+
+## Dialog / Sheet
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    {/* content */}
+    <DialogFooter>
+      <Button type="submit">Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+`DialogDescription` is required for accessibility — the dialog announces it to screen readers. Omitting it triggers a console warning.
+
+---
+
+## Form + react-hook-form
+
+shadcn Form wraps react-hook-form. Always use the `<Form>` components for labeled inputs — never raw `<input>`:
+
+```tsx
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)}>
+    <FormField
+      control={form.control}
+      name="email"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Email</FormLabel>
+          <FormControl>
+            <Input placeholder="you@example.com" {...field} />
+          </FormControl>
+          <FormDescription>We'll never share your email.</FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  </form>
+</Form>
+```
+
+`FormMessage` renders validation errors automatically from react-hook-form's state.
+
+---
+
+## Sizing utilities
+
+| Instead of | Use |
+|------------|-----|
+| `w-6 h-6` | `size-6` (when width === height) |
+| `space-y-4` | `gap-4` (prefer `flex`/`grid` with `gap`) |
+| `mr-2` on icon | `gap-2` on parent flex container |
+
+---
+
+## Server Components (RSC)
+
+Check `isRSC` from `npx shadcn@latest info --json`. If true:
+- shadcn components work as Server Components by default
+- Only add `"use client"` when a component uses `useState`, `useEffect`, event handlers, or browser APIs
+- Prefer `onClick` on leaf elements rather than wrapping entire sections in `"use client"`
+
+```tsx
+// Correct — only the interactive button is a client component
+// page.tsx (Server Component)
+import { SubmitButton } from "./submit-button" // "use client"
+
+// Wrong — entire section becomes client component unnecessarily
+"use client"
+export function Section() { ... }
+```
+
+---
+
+## Icon imports
+
+Use the icon library from `shadcn info`:
+
+```tsx
+// lucide-react (default for most styles)
+import { ChevronRight, Settings, User } from "lucide-react"
+
+// @tabler/icons-react (some styles)
+import { IconChevronRight, IconSettings } from "@tabler/icons-react"
+```
+
+Never import from both in the same project — check `iconLibrary` once and use it everywhere.
+
+---
+
+## Customization rules
+
+1. **Override via className** — always add `className` on top of the component's defaults, never fork the component file unless strictly necessary
+2. **CSS variables over arbitrary values** — `text-[#FF0000]` is a code smell; use a token instead
+3. **Brand effects go in globals.css as utilities** — create `.shadow-brand`, `.glow-accent` etc. as CSS utilities; use them as Tailwind class names
+4. **Never edit generated component files for visual tweaks** — only edit for structural/API changes. Token changes in globals.css automatically propagate

package/gsp/skills/gsp-project-critique/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-critique
-description: Critique your designs + accessibility audit (creative phase — benefits from capable models)
+description: Critique designs + accessibility audit (creative phase — benefits from capable models) — use when: review the designs, critique this, check accessibility, what's wrong with, give feedback on
 user-invocable: true
 context: fork
 allowed-tools:
@@ -26,6 +26,8 @@ Critique design quality and audit accessibility compliance.
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.

package/gsp/skills/gsp-project-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-design
-description: Design screens and interaction flows (creative phase — benefits from capable models)
+description: Design screens and interaction flows (creative phase — benefits from capable models) — use when: design this, mock up, create wireframes, how should X look, lay out the UI for
 user-invocable: true
 context: fork
 allowed-tools:
@@ -32,6 +32,8 @@ Design core UI/UX screens and interaction flows.
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.

package/gsp/skills/gsp-project-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-research
-description: Research UX patterns and technical approaches
+description: Research UX patterns and technical approaches — use when: research this, look up how X works, find patterns for, what's the best approach for
 user-invocable: true
 allowed-tools:
   - Read
@@ -35,6 +35,8 @@ Deep research into UX patterns, competitor experiences, and technical approaches
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.

package/gsp/skills/gsp-project-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-review
-description: QA review — validate implementation against designs
+description: QA review — validate implementation against designs — use when: review the build, QA this, does it match the designs, check what was built, verify implementation
 user-invocable: true
 context: fork
 allowed-tools:
@@ -32,6 +32,8 @@ QA validate the codebase implementation against design intent.
 <process>
 ## Step 0: Resolve project and brand
 
+If `.design/projects/` does not exist: output "No GSP project found. Run `/gsp-start` to begin." and stop.
+
 Resolve project from `.design/projects/` (one → use it, multiple → ask). Set `PROJECT_PATH`.
 
 Read `{PROJECT_PATH}/brand.ref` → set `BRAND_PATH`.
@@ -133,6 +135,13 @@ Update `{PROJECT_PATH}/STATE.md`:
 - If Pass or Conditional Pass: Set Prettiness Level to 100%
 - Update `## Screen Build Status` table — set Review Status per screen based on acceptance-report.md findings
 
+If Pass or Conditional Pass, update `.design/CLAUDE.md` — replace the existing `### {project-name}` entry (written by gsp-project-brief when started) with the completed entry:
+
+```markdown
+### {project-name} · complete · {DATE}
+brand: {brand-name} · .design/projects/{project-name}/
+```
+
 ### QA loop — if Fail
 
 If verdict is **Fail**: