get-shit-pretty 0.7.3 → 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`.
@@ -146,7 +148,6 @@ Pass in the agent prompt:
 The agent writes chunks directly:
 - `design/screen-{NN}-{name}.md` (one per screen)
 - `design/shared/` (personas, IA, navigation, micro-interactions, responsive, component-plan)
-- `design/preview.html` (self-contained wireframe preview)
 - `design/INDEX.md`
 - Updates `{PROJECT_PATH}/exports/INDEX.md` (design section)
 

package/gsp/skills/gsp-project-design/methodology/gsp-project-designer.md

@@ -13,21 +13,40 @@ When an **Existing Components** inventory is provided (for `shadcn`, `rn-reusabl
 <methodology>
 ## Design Process
 
+### Step 0: Internalize brand DNA (BEFORE designing anything)
+
+When `STYLE.md` is provided, read it first and extract a working checklist before designing any screen. STYLE.md is your design law — not a reference to consult later, but the lens through which every decision is made.
+
+Extract and hold in working memory:
+- **Constraints** → hard boundaries (never/always lists). Violating these is a Critical error.
+- **Patterns** → component composition rules (how to build cards, buttons, inputs, etc.)
+- **Effects vocabulary** → the ONLY interaction techniques you may use. Anything not listed is off-limits.
+- **Bold bets** → brand-specific techniques you MUST actively implement. These are what prevent generic output. If the brand has "purple atmospheric glow" as a bold bet, every relevant screen must show it.
+- **Intensity dials** → calibrate your creativity (variance drives layout, motion drives animation, density drives spacing)
+
+Every screen you design must reference specific techniques by name (e.g., "lift-shadow on feature cards", "press-down on CTA", "purple glow behind glass hero") — never generic terms like "use brand styling."
+
+### Steps 1-8: Design with brand DNA active
+
 1. **Define personas** — From BRIEF.md audience, create primary persona with goals and pain points
 2. **Map information architecture** — Hierarchy, grouping, navigation structure
 3. **Choose navigation pattern** — Tab bar, sidebar, or custom — justified by use case
-4. **Design 8 core screens** — Each with wireframe description, component usage, interactions, and all states
+4. **Design core screens** — Each with wireframe description, component usage, interactions, and all states. Apply brand patterns and effects in every screen — not as a separate pass, but as the default visual language.
 5. **Specify accessibility** — WCAG compliance, VoiceOver order, Dynamic Type behavior
-6. **Define micro-interactions** — Meaningful animations that communicate state changes
+6. **Define micro-interactions** — Only use techniques from the effects vocabulary. Reference them by name.
 7. **Specify image resources** — For each screen section that needs imagery, define: type (photo/illustration/icon composition/CSS-only), description and search terms for sourcing, treatment (dark overlay, blur, crop, rounded). Match the brand's imagery style from `imagery-style.md` — if the brand uses photography, specify photo subjects and mood; if illustration, specify style and subject; if CSS-only, specify the pattern or gradient approach.
 8. **Build component plan** — When existing components inventory is provided, annotate which components to reuse, refactor, or create new
-9. **Apply brand visual DNA** — When `STYLE.md` is provided, use its philosophy, patterns, constraints, effects vocabulary, and bold bets to specify visual treatments per screen. STYLE.md is your design law:
-   - **Patterns** → component composition rules (how to build cards, buttons, inputs, etc.)
-   - **Constraints** → hard boundaries (never/always lists — do not violate these)
-   - **Effects** → interaction vocabulary (only use techniques from the allowed list)
-   - **Bold Bets** → brand-specific techniques to actively implement (prevents generic output)
-   - **Intensity dials** → calibrate your creativity (variance drives layout, motion drives animation, density drives spacing)
-   In screen chunks, reference specific techniques by name (e.g., "lift-shadow on feature cards", "press-down on CTA") — not generic terms like "use brand styling"
+
+### Step 9: Brand fidelity self-check
+
+Before writing INDEX.md, verify your output against STYLE.md:
+- [ ] Every constraint respected (check the never/always lists)
+- [ ] Every bold bet appears in at least one screen (list which screen for each)
+- [ ] Effects vocabulary is the only source of interaction techniques used
+- [ ] Intensity dials match — variance, motion, density are calibrated correctly
+- [ ] No generic visual treatments — every surface, shadow, glow, gradient references a named brand technique
+
+If any bold bet is missing from all screens, go back and add it. Bold bets are the brand's differentiation — skipping them produces generic output.
 
 ## Style Feedback Detection
 
@@ -111,18 +130,6 @@ Write to `design/shared/` (~50-100 lines each):
 
 Shared chunks link to related shared chunks and relevant screen chunks.
 
-### `design/preview.html`
-
-After writing all screen chunks, generate a self-contained HTML preview file:
-- Single HTML file with embedded CSS (no external dependencies)
-- One section per screen showing a wireframe-level layout visualization
-- Use simple boxes, text labels, and semantic structure to represent each screen's layout
-- Include navigation between screens
-- Use the brand's color tokens (from the brand `.yml`) for accents if available, otherwise use neutral grays
-- Responsive — preview itself adapts to viewport width
-- Add a table of contents sidebar listing all screens
-- Keep it minimal — this is a wireframe preview, not a polished mockup
-
 ### `INDEX.md`
 
 After writing all chunks, write `INDEX.md` in the design directory:

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` |
 
-Read `.design/system/STACK.md` if it exists — check what's already set up.
+3. **Gate on divergence:**
+   - If any divergence found, surface it clearly:
+     ```
+     ⚠️  Stack compliance — divergence detected
 
-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).
+       STACK.md declares:   aliases.components = @/components/ui
+       Live codebase has:   aliases.components = ~/components/ui
+
+       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)
+
+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:
@@ -184,6 +221,21 @@ Clear any build cache first (`rm -rf .next` for Next.js), then run the build com
   - After fix attempt, clear cache and re-run build once
 - **Second failure:** Log the error and stop. Do not loop.
 
+## Step 5.5: Capture project context (shadcn targets)
+
+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
+- `style` — component visual treatment (nova, vega, etc.)
+- `base` — primitive library (radix or base)
+- `iconLibrary` — determines icon imports (lucide-react, @tabler/icons-react, etc.)
+- `resolvedPaths` — exact file-system destinations for components, utils, hooks
+- `framework` — routing and file conventions (Next.js App Router, Vite SPA, etc.)
+- `isRSC` — whether "use client" directives are needed
+
+Include this JSON in the scaffold log under a `## Project Context` section so the foundations agent can reference it.
+
 ## Step 6: Write scaffold log
 
 Write `{PROJECT_PATH}/build/SCAFFOLD-LOG.md`:
@@ -191,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
 
@@ -225,6 +277,10 @@ Write `{PROJECT_PATH}/build/SCAFFOLD-LOG.md`:
 - **Result:** {pass / fail}
 - **Output:** {first/last lines if relevant}
 
+## Project Context
+
+{If shadcn target: JSON output from `npx shadcn@latest info --json`. Otherwise: "N/A — non-shadcn target"}
+
 ## Issues
 
 {Any problems encountered and how they were resolved, or "None"}