get-shit-pretty 0.7.4 → 0.8.2

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**:

package/gsp/skills/gsp-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-scaffold
-description: Deterministic stack setup — install deps, create configs, verify build compiles
+description: Set up the tech stack — install deps, configs, verify build — use when: set up the stack, install shadcn, init the project, scaffold, set up Tailwind
 user-invocable: true
 allowed-tools:
   - Read
@@ -40,20 +40,57 @@ Read `{PROJECT_PATH}/config.json` to get:
 - `preferences.implementation_target` (shadcn, rn-reusables, existing, code)
 - `preferences.tech_stack` (Next.js + Tailwind + shadcn/ui, etc.)
 - `preferences.codebase_type` (greenfield, existing)
+- `preferences.app_path` (relative path from repo root to the target app, e.g. `apps/web`)
+- `preferences.repo_type` (`single` or `monorepo`)
+
+Set `APP_PATH` = value of `app_path`. If empty, default to `.` (repo root).
+Derive `APP_NAME` = last segment of `APP_PATH` (e.g. `apps/web` → `web`, `.` → `root`).
 
 If `implementation_target` is `figma` or `skip`, log "⚠️ No scaffold needed for target: {target}" and exit.
 
-## Step 2: Read stack state
+## Step 2: Read stack state + compliance gate
+
+Read `.design/system/stacks/{APP_NAME}.md` if it exists — this is the per-app stack file for monorepos. Fall back to `.design/system/STACK.md` for legacy single-app setups (or when `APP_NAME` is `root` and the legacy file exists).
+
+### If stack file exists (existing or returning project)
+
+This workspace has a declared stack for this app. Enforce compliance before touching anything.
+
+1. **Read the live stack** from `components.json` (if present) and `package.json` inside `APP_PATH`:
+   - `cd {APP_PATH} && npx shadcn@latest info --json` (if shadcn target) → captures `aliases`, `tailwindVersion`, `style`, `base`, `iconLibrary`
+   - `cd {APP_PATH} && node -e "console.log(require('tailwindcss/package.json').version)"` → actual Tailwind version
+
+2. **Compare against STACK.md** — flag any of these divergences:
+
+   | What to check | STACK.md field | Live source |
+   |---|---|---|
+   | Framework | `## Tech Stack → Framework` | `package.json` dependencies |
+   | Tailwind version | `## Tech Stack → Styling` | Installed `tailwindcss` version |
+   | shadcn alias | `## Key Paths → Components` | `shadcn info` → `aliases.components` |
+   | shadcn style | (if recorded) | `shadcn info` → `style` |
+   | Icon library | (if recorded) | `shadcn info` → `iconLibrary` |
+
+3. **Gate on divergence:**
+   - If any divergence found, surface it clearly:
+     ```
+     ⚠️  Stack compliance — divergence detected
+
+       STACK.md declares:   aliases.components = @/components/ui
+       Live codebase has:   aliases.components = ~/components/ui
 
-Read `.design/system/STACK.md` if it exists — check what's already set up.
+       Proceeding will write files to the wrong paths.
+     ```
+   - Use `AskUserQuestion`: "Stack divergence detected. Proceed anyway (may break imports), or stop to fix STACK.md first?"
+   - **Stop** → exit; user fixes `STACK.md` and re-runs
+   - **Proceed anyway** → log divergence in scaffold log, continue with live values (not STACK.md)
 
-If STACK.md indicates the stack is already initialized (has framework, CSS, component library entries), log existing state and skip to Step 4 (component installs).
+4. If the stack file indicates the stack is already initialized (has framework, CSS, component library entries) **and no divergence found**, log existing state and skip to Step 4 (component installs).
 
 ## Step 3: Initialize stack
 
 Based on `tech_stack` and `implementation_target`, run the appropriate setup.
 
-**Important:** Always check if config files already exist before overwriting. Only create what's missing.
+**Important:** All shell commands in this step run in the `APP_PATH` working directory (`cd {APP_PATH} && ...`). Always check if config files already exist before overwriting. Only create what's missing.
 
 ### Next.js + shadcn (greenfield)
 
@@ -165,14 +202,14 @@ Run additional dependency installs (`npm install ...`) separately from component
 
 ## Step 5: Verify build
 
-Clear any build cache first (`rm -rf .next` for Next.js), then run the build command:
+Clear any build cache first (`cd {APP_PATH} && rm -rf .next` for Next.js), then 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` |
 
 - **Success:** Log "Build compiles cleanly"
 - **Failure:** Log the error output. Attempt to fix common issues:
@@ -186,7 +223,7 @@ Clear any build cache first (`rm -rf .next` for Next.js), then run the build com
 
 ## Step 5.5: Capture project context (shadcn targets)
 
-If `implementation_target` is `shadcn`, run `npx shadcn@latest info --json` and capture the output. This provides:
+If `implementation_target` is `shadcn`, run `cd {APP_PATH} && npx shadcn@latest info --json` and capture the output. This provides:
 - `aliases` — the actual alias prefix for imports (`@/`, `~/`)
 - `tailwindVersion` — `"v4"` (uses `@theme inline`) vs `"v3"` (uses `tailwind.config.js`)
 - `tailwindCssFile` — the global CSS file where custom properties go
@@ -206,7 +243,7 @@ Write `{PROJECT_PATH}/build/SCAFFOLD-LOG.md`:
 ```markdown
 # Scaffold Log
 
-> Phase: build (scaffold) | Project: {name} | Generated: {DATE}
+> Phase: build (scaffold) | Project: {name} | App: {APP_PATH} | Generated: {DATE}
 
 ## Stack