get-shit-pretty 0.7.3 → 0.8.2

package/gsp/skills/gsp-brand-refine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-refine
-description: Targeted brand adjustments mid-project — tweak colors, typography, or spacing without re-running the full branding diamond
+description: Adjust brand mid-project — use when: tweak the colors, change the font, adjust spacing, the brand feels off, refine the brand
 user-invocable: true
 allowed-tools:
   - Read
@@ -82,14 +82,13 @@ Show a clear before/after for each affected token:
 
   ─── Proposed Changes ─────────────────
 
-  color.brand.accent
+  color.accent
     before: #B8860B
     after:  #E8A317
     change: increased chroma
 
   Cascade:
-    color.semantic.link        → #E8A317
-    color.semantic.focus-ring  → #E8A317
+    color.ring  → #E8A317 (shares accent as focus ring)
 
   Contrast: accent on white 3.2:1 → 2.8:1 ⚠️ below AA
             accent on dark  8.4:1 → 9.2:1 ✓
@@ -133,8 +132,8 @@ Append to `{BRAND_PATH}/REFINE-LOG.md`:
 
 | Token | Before | After |
 |-------|--------|-------|
-| color.brand.accent | #B8860B | #E8A317 |
-| color.semantic.link | #B8860B | #E8A317 |
+| color.accent | #B8860B | #E8A317 |
+| color.ring | #B8860B | #E8A317 |
 ```
 
 Display summary:

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-research
-description: Research your market and competitors
+description: Research market and competitors — use when: research competitors, who else is doing this, market analysis, what do competitors look like
 user-invocable: true
 allowed-tools:
   - Read

package/gsp/skills/gsp-brand-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsp-brand-strategy
-description: Define positioning, voice, and messaging (creative phase — benefits from capable models)
+description: Define positioning, voice, and messaging (creative phase — benefits from capable models) — use when: define our positioning, brand strategy, what's our voice, how do we talk to customers
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-design-system
-description: Scan and document the existing design system state
+description: Scan and document the existing design system — use when: scan the codebase, document what components exist, what's already built, inventory the design system
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-doctor
-description: Check project health
+description: Check project health — use when: something's broken, check the project, is everything set up right, health check, what's the status of my GSP setup
 user-invocable: true
 allowed-tools:
   - Read
@@ -87,6 +87,9 @@ Check each exists:
 - All present → PASS
 - Core files missing → FAIL: list which are missing, suggest `/gsp-start`
 
+**Monorepo app_path check:**
+- If `repo_type` is `monorepo` (in config.json) and `app_path` is empty → WARN: "Project has no `app_path` set. Run `/gsp-project-brief` to assign a target app."
+
 **Design system check:**
 - If `.design/system/` directory exists, verify at least `STACK.md` is present → PASS
 - If `.design/system/` is missing and codebase is not greenfield → WARN: "Design system scan missing. Run `/gsp-design-system` to scan."
@@ -261,7 +264,45 @@ Check if `~/.claude/skills/` contains `gsp-*` directories when running from a lo
 - No matches → PASS
 - Matches found → FAIL: "Found {N} stale GSP skills in ~/.claude/skills/. Fix: run `npx get-shit-pretty --claude --local` to reinstall (the installer cleans stale globals automatically), or manually remove: `rm -rf ~/.claude/skills/gsp-*`"
 
-### Cross-Instance Checks
+### Stack Compliance Checks (shadcn targets)
+
+Only run these checks when `.design/system/STACK.md` exists and at least one project has `implementation_target: shadcn`.
+
+> **Monorepo note:** For monorepos, each project's S-checks run in its declared `app_path`. Read `config.json` → `preferences.app_path` before running commands. If `app_path` is empty, run in repo root.
+
+**Check S1: Alias drift**
+
+Read `config.json` → `preferences.app_path`. Set `APP_PATH` (default `.` if empty).
+
+Run `cd {APP_PATH} && npx shadcn@latest info --json` and extract `aliases.components`. Compare to `## Key Paths → Components` in STACK.md.
+
+If mismatch → FAIL: "shadcn alias drift — STACK.md declares `{declared}` but live config has `{live}`. Imports will break. Fix by updating `components.json` or `STACK.md`."
+
+**Check S2: Tailwind version drift**
+
+Run `cd {APP_PATH} && node -e "console.log(require('tailwindcss/package.json').version)"`. Compare major version to `## Tech Stack → Styling` in STACK.md.
+
+If major version differs → FAIL: "Tailwind version drift — STACK.md declares `{declared}` but `{live}` is installed. Run `/gsp-scaffold` to realign or update STACK.md."
+
+**Check S3: Icon library drift**
+
+Read `components.json` → `iconLibrary`. Compare to icon library recorded in STACK.md (if present).
+
+If mismatch → WARN: "Icon library drift — STACK.md declares `{declared}` but `components.json` says `{live}`. Agents may import from the wrong package."
+
+**Check S4: Token presence in globals.css**
+
+Find the global CSS file (from `cd {APP_PATH} && npx shadcn@latest info --json` → `tailwindCssFile`, or glob for `globals.css` inside `APP_PATH`). Check it contains `--background`, `--foreground`, `--primary` CSS custom properties.
+
+If missing → WARN: "CSS custom properties not found in `{file}`. Token integration may be incomplete. Run `/gsp-project-build` foundations phase to regenerate."
+
+**Check S5: Tailwind v4 source scoping (if Tailwind v4)**
+
+If Tailwind v4 detected, check `globals.css` for `@import "tailwindcss"`. If present without `source(...)` modifier, and the repo contains non-source directories with Tailwind class names (like `.design/`) → WARN: "Tailwind v4 source not scoped. Add `source(\"../\")` to avoid scanning `.design/` spec files."
+
+All S checks pass → single PASS line: "S1-S5. Stack compliance .......... PASS"
+
+
 
 **Check X1: Multiple projects, same brand**
 If multiple projects reference the same brand, and brand has changed since any project consumed it → WARN with list of affected projects.
@@ -314,7 +355,14 @@ Overall Health: {SCORE}/100 {emoji}
   ✅ I4. VERSION file ............ PASS
   ✅ I5. No duplicate skills ..... PASS
 
-─── Cross-Instance ────────────────────
+  ─── Stack Compliance (shadcn) ────────
+  ✅ S1. Alias ....................... PASS
+  ✅ S2. Tailwind version ........... PASS
+  ✅ S3. Icon library ............... PASS
+  ✅ S4. CSS custom properties ....... PASS
+  ✅ S5. Source scoping .............. PASS
+
+  ─── Cross-Instance ────────────────────
   ✅ X1. Brand Consistency ...... PASS
 
 ─── Issues Found ──────────────────────

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-progress
-description: How pretty are we?
+description: Show pipeline progress dashboard — use when: where are we, what's done, show progress, how far along, what phase are we on
 user-invocable: true
 allowed-tools:
   - Read

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

@@ -1,6 +1,6 @@
 ---
 name: gsp-project-brief
-description: Scope what you're building
+description: Scope a feature or flow — use when: scope this, define what we're building, plan the project, what should we build, write a brief
 user-invocable: true
 allowed-tools:
   - Read
@@ -31,6 +31,8 @@ Scope the project and plan adaptations from the brand system.
 <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`. If brand.ref doesn't exist, tell the user to run `/gsp-start`.
@@ -49,16 +51,41 @@ Also read the brand `.yml` preset from `{BRAND_PATH}/patterns/`.
 
 Read:
 - `{PROJECT_PATH}/BRIEF.md` — what we're building, platforms, tech stack
-- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`
+- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`, `app_path`, `repo_type`
+
+After reading config, check if `app_path` is empty. If empty AND (`repo_type` is `monorepo` OR multiple `package.json` files are found at `apps/*/package.json` or `packages/*/package.json`), set flag `NEEDS_APP_SELECTION = true`.
 
 ### Codebase context
 
 Read `.design/system/STACK.md` and `.design/system/COMPONENTS.md` (if exist) — existing tech stack, components, architecture.
 
+**Stack inheritance (existing codebases):** If `STACK.md` exists and the project `config.json` has empty or generic values for `tech_stack`, `implementation_target`, or `codebase_type`, inherit them from `STACK.md` directly — do not ask the user questions the stack already answers. Update `config.json` with the inherited values before proceeding.
+
+The global stack is the compliance baseline. Every project in this workspace must target it. If the user's brief describes a different stack than what `STACK.md` declares (e.g., "I want to use Radix directly" when `STACK.md` says `shadcn/ui`), surface the conflict: "⚠️ Your brief mentions {X}, but the workspace stack is {Y} per STACK.md. Proceed with the workspace stack, or update STACK.md first?"
+
 Read `.design/CHANGELOG.md` — quick history of what prior projects built.
 For projects with overlapping scope, read their `codebase/MANIFEST.md` for detail.
 Glob `.design/projects/*/STATE.md` — detect active sibling projects.
 
+## Step 1.3: App targeting
+
+Run when `NEEDS_APP_SELECTION = true`.
+
+1. Glob for `apps/*/package.json` and `packages/*/package.json` to find all app packages.
+2. Read each package.json to extract `name` and the primary framework dependency (Next.js, Vite, React Native, etc.).
+3. Build an app list, e.g.:
+   ```
+   apps/web        → my-app-web     (Next.js)
+   apps/mobile     → my-app-mobile  (Expo / React Native)
+   packages/ui     → my-app-ui      (Vite)
+   ```
+4. Use `AskUserQuestion`: "Which app does this project target?" with one option per detected app (showing path + framework) plus **Whole repo (no specific app)**.
+5. Based on the user's choice:
+   - If an app was selected: set `app_path` to the chosen path (e.g. `apps/web`) and `repo_type` to `monorepo`
+   - If "Whole repo" was selected: set `app_path` to `""` and `repo_type` to `monorepo`
+6. Write the updated `app_path` and `repo_type` back to `{PROJECT_PATH}/config.json`.
+7. Derive `APP_NAME` = last segment of `app_path` (e.g. `apps/web` → `web`, empty → `root`). Note that the per-app stack file will live at `.design/system/stacks/{APP_NAME}.md`.
+
 ## Step 1.5: Scope check
 
 **If `design_scope` is `tokens`:**
@@ -69,10 +96,10 @@ Glob `.design/projects/*/STATE.md` — detect active sibling projects.
 
 ## Step 1.7: Issue framing
 
-Suggest to the user:
-"Consider framing this project as a bounded issue (or set of issues) and a PR. Smaller scope = higher quality. What's the tightest version of this that ships?"
-
-If the project scope feels large, suggest breaking it into multiple bounded issues — each one a focused deliverable that can be reviewed independently.
+Ask the user (via `AskUserQuestion`): "Is this project linked to a GitHub issue?"
+- **Yes — paste the issue URL** → read the issue number from the URL, write `git.issue` to `{PROJECT_PATH}/config.json` and populate the `| Issue |` row in STATE.md. Also read the issue title/body via `gh issue view {number} --json title,body,labels` and use that content to pre-populate scope context (saves the user from re-describing what the issue already states).
+- **No — describe it** → continue with manual brief as before
+- **Skip** → continue without issue link
 
 ## Step 2: Scope the project
 
@@ -157,6 +184,13 @@ Update `{PROJECT_PATH}/STATE.md`:
 - Set Phase 1 (Brief) status to `complete`
 - Record completion date
 
+Write/update `.design/CLAUDE.md` — register the project as started. If the file doesn't exist, read the template from `${CLAUDE_SKILL_DIR}/../../templates/design-claude.md` first. Append under `## Projects`:
+
+```markdown
+### {project-name} · in progress · {DATE}
+brand: {brand-name} · next: gsp-project-research · .design/projects/{project-name}/
+```
+
 ## Step 5: Phase transition output
 
 Invoke `/gsp-phase-transition` with phase `brief` and output directory `{PROJECT_PATH}/brief/`.

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,6 +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}/shadcn-composition.md`
 
 Hold their content for inlining into agent prompts in Steps 3, 4.5, 5, 7, and 8.
 
@@ -145,14 +150,16 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 
 | File | Purpose |
 |------|---------|
-| `{BRAND_PATH}/patterns/{brand-name}.yml` | Token values only — used with `gsp-brand-guidelines/token-mapping.md` to generate CSS variables. Do NOT re-read patterns/constraints/effects from here — those are in STYLE.md. |
+| `{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) | 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 |
 
@@ -162,27 +169,28 @@ 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 (CSS variables, Tailwind config, or theme file)
+> 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)
 > 5. Apply the STYLE.md bold bets and effects vocabulary — create CSS utilities or Tailwind extensions for the brand's signature effects. Validate against constraints (never/always rules are non-negotiable).
-> 6. Do NOT build individual screens or page content
-> 7. Write code directly to the codebase, not to `.design/`
-> 8. Leave changes unstaged
+> 6. For shadcn targets: use semantic color tokens (`bg-primary`, `text-muted-foreground`) — never raw color values like `bg-blue-500`. Use `gap-*` not `space-y-*`. Use `size-*` when width and height are equal.
+> 7. Do NOT build individual screens or page content
+> 8. Write code directly to the codebase, not to `.design/`
+> 9. Leave changes unstaged
 >
 > After completing foundations, write `{PROJECT_PATH}/build/logs/foundations.md` with what was done (foundations section). Do NOT write to BUILD-LOG.md directly — the orchestrator merges logs after each phase.
 
 ### 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.
@@ -494,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).
+Read `${CLAUDE_SKILL_DIR}/flows/figma.md` for full instructions.
 
-## 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.
+For `implementation_target: figma`, skip the phased pipeline. Produce Figma-ready implementation specs instead of editing the codebase. Then continue from Step 6 (finalize).
 
-### 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?"
-
-### 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. 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)
@@ -106,8 +106,91 @@ Check code against these before marking a screen complete — **but STYLE.md tak
 - **Components:** customize shadcn radii/colors/shadows, skeleton loaders not spinners, semantic HTML
 - **Code:** no inline styles mixed with utilities, relative units, clean z-index scale, alt text, verify imports exist
 
+## shadcn/ui Rules (when target is shadcn)
+
+These rules are always enforced for shadcn targets. They reflect the official shadcn/ui composition patterns:
+
+**Styling:**
+- Use semantic color tokens (`bg-primary`, `text-muted-foreground`) — never raw values like `bg-blue-500`
+- No manual `dark:` color overrides — use semantic tokens that auto-adapt
+- Use `gap-*` with flex/grid — never `space-x-*` or `space-y-*`
+- Use `size-*` when width and height are equal — `size-10` not `w-10 h-10`
+- Use `cn()` for conditional classes — never manual template literal ternaries
+- No manual `z-index` on overlay components (Dialog, Sheet, Popover handle their own stacking)
+- Use built-in variants before custom styles (`variant="outline"`, `size="sm"`)
+
+**Composition:**
+- Items always inside their Group (`SelectItem` → `SelectGroup`, `DropdownMenuItem` → `DropdownMenuGroup`)
+- Dialog, Sheet, and Drawer always need a Title (use `className="sr-only"` if visually hidden)
+- 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, `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"`) — 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 {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.