get-shit-pretty 0.8.3 → 0.10.0

package/gsp/skills/gsp-brand-guidelines/methodology/gsp-brand-engineer.md

@@ -74,7 +74,7 @@ Read `system_strategy` from brand config:
 
 Leverage existing UI libraries — don't rewrite from scratch.
 
-**Tier 1: Token mapping** (always) — `components/token-mapping.md`. Maps brand tokens to library's theming API. Copy-paste-ready. Generate the CSS variables block by running `node bin/theme-css.js {brand-name}.yml` — it outputs a ready-to-paste `:root`/`.dark` block with OKLCH values. Token names in `.yml` are 1:1 with shadcn/ui CSS var names — no translation needed.
+**Tier 1: Token mapping** (always) — `components/token-mapping.md`. Maps brand tokens to library's theming API. Documents the OKLCH values generated by `theme-css.js` — these are installed into `globals.css` via `/gsp-brand-apply` (not manually pasted). Token names in `.yml` are 1:1 with shadcn/ui CSS var names — no translation needed.
 
 **Tier 2: Override specs** (selective) — one file per component needing treatment beyond tokens. Why it's overridden, code hints.
 

package/gsp/skills/gsp-brand-guidelines/token-mapping.md

@@ -1,4 +1,4 @@
-# Token Mapping → bin/theme-css.js
+# Token Mapping → theme-css.js
 
 > **Superseded in v0.8.0.** The static mapping table has been replaced by a deterministic script.
 
@@ -7,7 +7,7 @@ GSP presets use shadcn/ui-native token names directly. The `.yml` token keys mat
 ## Generating CSS from a preset
 
 ```bash
-node bin/theme-css.js gsp/skills/gsp-style/styles/professional.yml --stdout
+node gsp/skills/gsp-brand-guidelines/bin/theme-css.js gsp/skills/gsp-style/styles/professional.yml --stdout
 ```
 
 Output is `:root { }` + `.dark { }` blocks ready to paste into `globals.css`.

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

@@ -89,7 +89,7 @@ Spawn the `gsp-brand-creative-director` agent. **Inline all content** — the ag
 
 Pass in the agent prompt:
 - **Content of** BRIEF.md (loaded in Step 1)
-- **Content of** strategy chunks: archetype.md, positioning.md, brand-platform.md, voice-and-tone.md (loaded in Step 1)
+- **Content of** strategy chunks: archetype.md, positioning.md, brand-platform.md, voice-and-tone.md, messaging.md (all 5 loaded in Step 1; older brands without messaging.md proceed without it). Tagline directions and core message in `messaging.md` materially shape logo concept rationale and typography voice — do not skip it.
 - **Content of** discover/mood-board-direction.md (loaded in Step 1)
 - **Content of** style base preset `.yml` + `.md` (when loaded in Step 1) — `.yml` as structural scaffold, `.md` as design philosophy and signature techniques
 - **Content of** audit/brand-inventory.md (when loaded in Step 2)
@@ -109,14 +109,15 @@ The agent writes 5 chunks + INDEX.md (creative decisions only — no technical e
 
 ## Step 3.5: Enrich with domain skills (parallel)
 
-After the creative-director finishes, invoke all 4 domain skills in parallel — they operate on separate chunks with zero dependencies:
+After the creative-director finishes, invoke all 5 domain skills in parallel — they operate on separate chunks with zero dependencies:
 
 - **`/gsp-logo --enrich`** — reads `logo-directions.md`, enriches with construction geometry, variation specs, clear space rules, minimum size calculations.
 - **`/gsp-color --enrich`** — reads `color-system.md`, generates OKLCH palettes via tints.dev, calculates WCAG contrast, writes `palettes.json`, enriches with contrast ratios and semantic mapping.
 - **`/gsp-typography --enrich`** — reads `typography.md`, generates mathematical type scale, adds fluid type formulas, enriches with font loading instructions.
-- **`/gsp-visuals --imagery --enrich`** — reads `imagery-style.md`, adds icon library specifics, CSS texture/treatment recipes, enriches with technical implementation details.
+- **`/gsp-visuals --imagery --enrich`** — reads `imagery-style.md`, enriches with photography/illustration direction, CSS texture/treatment recipes, image processing implementation. Icons are NOT covered here — `gsp-icons` owns them.
+- **`/gsp-icons --enrich`** — defines the icon system: library selection, stroke standardization, size system, container treatments, custom SVG direction.
 
-Invoke all 4 using the Skill tool simultaneously. Each skill loads its own domain references on-demand — no upfront context cost.
+Invoke all 5 using the Skill tool simultaneously. Each skill loads its own domain references on-demand — no upfront context cost.
 
 ## Step 4: Perspective check
 

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

@@ -21,12 +21,11 @@ This skill modifies **`{brand-name}.yml`** — the single source of truth for br
 Accept natural language feedback about brand visuals, identify which `.yml` values are affected, apply targeted changes, and regenerate `STYLE.md` if it exists.
 
 **Input:** Natural language feedback (e.g., "accent is too muted", "make buttons rounder", "more motion")
-**Output:** Updated `{brand-name}.yml` + regenerated `STYLE.md` (if exists) + `REFINE-LOG.md`
+**Output:** Updated `{brand-name}.yml` + regenerated `STYLE.md` (if exists) + `{brand-name}.theme.json` (regenerated) + `REFINE-LOG.md`
 **Agent:** None — inline skill, surgical edits
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
 </execution_context>
 
 <rules>
@@ -123,7 +122,38 @@ Apply confirmed changes:
 1. **`{brand-name}.yml`** — edit values in place with `Edit`. Preserve structure.
 2. **`STYLE.md`** — if it exists, regenerate the affected sections (Patterns tables, Constraints lists, Effects tables, or Intensity dials) to reflect the `.yml` changes. Read the template from `${CLAUDE_SKILL_DIR}/../../templates/phases/style.md` for format reference.
 
-## Step 4: Log and finish
+## Step 4: Regenerate theme.json and offer to apply
+
+After updating `{brand-name}.yml` and (if applicable) regenerating `STYLE.md`, regenerate the shadcn registry artifact:
+
+```bash
+node ${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/bin/theme-css.js \
+  {BRAND_PATH}/patterns/{brand-name}.yml \
+  --registry \
+  --output {BRAND_PATH}/patterns/{brand-name}.theme.json
+```
+
+Verify the file is valid JSON:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('{BRAND_PATH}/patterns/{brand-name}.theme.json', 'utf8'))" \
+  && echo "✓ theme.json refreshed"
+```
+
+If a project config exists (`.design/projects/*/config.json` with a non-empty `app_path`) AND `{app_path}/components.json` exists (a shadcn target), use `AskUserQuestion`:
+
+- Question: "Theme refreshed. Apply changes to `{app_path}` now?"
+- Options:
+  - A: "Yes — apply now"
+  - B: "Skip — apply later"
+
+On A: output `Run /gsp-brand-apply {brand-name}` as the next user step.
+
+On B: output `Refreshed. Apply later with /gsp-brand-apply {brand-name}.`
+
+If no shadcn target is detected, skip the prompt and output a passive note: `Theme refreshed. No shadcn target detected — apply later with /gsp-brand-apply {brand-name} once a shadcn project is set up.`
+
+## Step 5: Log and finish
 
 Append to `{BRAND_PATH}/REFINE-LOG.md`:
 

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

@@ -85,5 +85,5 @@ Update `{BRAND_PATH}/STATE.md`: set Phase 1 (Discover) to `complete`.
 
 ## Step 5: Phase transition
 
-Invoke `/gsp-phase-transition` with phase `discover` and output directory `{BRAND_PATH}/research/`.
+Invoke `/gsp-phase-transition` with phase `discover` and output directory `{BRAND_PATH}/discover/`.
 </process>

package/gsp/skills/gsp-brand-research/methodology/gsp-brand-researcher.md

@@ -31,6 +31,15 @@ Act as a senior design researcher. Analyze the market landscape and competitive
 - Competitor map must use real competitors from BRIEF.md
 - Mood board specs must be actionable (hex values, typeface names)
 - Recommendations must be specific to this brand's personas, not generic
+
+## Downstream expertise context (for mood-board direction)
+
+Stay opinionated but don't over-commit on technical specifics — downstream phases will refine via expertise skills:
+- Hex color picks → `gsp-color` will re-express as OKLCH and validate WCAG contrast in identity phase
+- Typeface picks → `gsp-typography` will pair, scale, and verify rhythm
+- Imagery style direction → `gsp-visuals/domains/imagery.md` owns the canonical imagery vocabulary; align mood-board language with it where possible
+
+This is forward awareness only — research output stays in research's lane.
 </methodology>
 
 <output>

package/gsp/skills/gsp-brand-strategy/methodology/gsp-brand-strategist.md

@@ -32,9 +32,9 @@ Act as Head of Strategy at a top branding agency. Define the strategic foundatio
 </methodology>
 
 <references>
-- `references/brand-archetypes.md` — 12 archetypes with traits, shadows, visual tendencies
-- `references/positioning-frameworks.md` — positioning maps, brand pyramid
-- `references/voice-tone.md` — voice attribute framework, tone spectrum, messaging matrix
+- `${CLAUDE_SKILL_DIR}/brand-archetypes.md` — 12 archetypes with traits, shadows, visual tendencies
+- `${CLAUDE_SKILL_DIR}/positioning-frameworks.md` — positioning maps, brand pyramid
+- `${CLAUDE_SKILL_DIR}/voice-tone.md` — voice attribute framework, tone spectrum, messaging matrix
 </references>
 
 <output>

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

@@ -29,7 +29,6 @@ Compare a project's shipped state against its source brand across all dimensions
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
 @${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 

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

@@ -51,10 +51,15 @@ 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`, `app_path`, `repo_type`
+- `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`, `codebase_type`, `app_path`, `repo_type`, `accessibility_level`, `style_preset`
 
 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`.
 
+**Expertise pointers:**
+- `accessibility_level` (AA vs AAA) carries scope implications for contrast-sensitive components — see `${CLAUDE_SKILL_DIR}/../gsp-accessibility/SKILL.md` for level interpretation when reasoning about adaptations
+- `style_preset` (when set) drives style-preset-specific component conventions — see `${CLAUDE_SKILL_DIR}/../gsp-style/styles/{preset}.md` for the preset's patterns + constraints + effects vocabulary that adaptation reasoning should respect
+- When writing token overrides in `target-adaptations.md`, consult `${CLAUDE_SKILL_DIR}/../gsp-color/domains/palette.md` for OKLCH/contrast considerations and `${CLAUDE_SKILL_DIR}/../gsp-typography/domains/scale.md` for type-scale ratios
+
 ### Codebase context
 
 Read `.design/system/STACK.md` and `.design/system/COMPONENTS.md` (if exist) — existing tech stack, components, architecture.

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

@@ -137,10 +137,33 @@ 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`
+- `${CLAUDE_SKILL_DIR}/agent-rules.md` — common spawn guardrails (universal + per-mode)
 
 Hold their content for inlining into agent prompts in Steps 3, 4.5, 5, 7, and 8.
 
-> **Note:** Anti-patterns are distilled into the `gsp-project-builder` agent prompt. Full ref remains on disk for edge-case agent lookup.
+## Step 2.7: Theme apply gate
+
+Verify brand tokens are installed in the codebase before spawning foundations. Foundations no longer pastes tokens — `/gsp-brand-apply` is the install primitive.
+
+1. If `{APP_PATH}/components.json` does not exist, skip this gate silently — the target is non-shadcn (scaffold's failure gate at end of Step 2 already covers a broken shadcn scaffold).
+2. Resolve the CSS path: read `{APP_PATH}/components.json` and extract the value at `.tailwind.css` (a relative path from `APP_PATH`).
+3. Open `{APP_PATH}/{cssPath}`. Verify:
+   - Contains `oklch(`
+   - Has both `:root {` and `.dark {` blocks
+   - Declares `--background`, `--foreground`, `--primary`, `--radius`
+   - **If** `{BRAND_PATH}/patterns/{brand-name}.theme.json` exists: contains the brand's signature `cssVars.light.background` value from that file (this distinguishes the applied brand from shadcn's nova defaults). If `{brand-name}.theme.json` does NOT exist (older brand from before Task 4 landed), skip the brand-signature check and rely on the structural checks only — log `⚠ Brand theme.json not found — skipping brand-signature check.`
+
+If any required check fails, brand tokens are not applied (or the wrong brand is applied). Use `AskUserQuestion`:
+- Question: "Brand tokens for **{brand-name}** not detected in `{APP_PATH}/{cssPath}`. Run `/gsp-brand-apply {brand-name}` now?"
+- Options:
+  - A: "Yes — I'll run /gsp-brand-apply {brand-name}, then re-run /gsp-project-build"
+  - B: "No, abort the build"
+
+On A: output `Next: run /gsp-brand-apply {brand-name}, then re-invoke /gsp-project-build` and exit this skill. The build does not auto-continue — the apply runs out-of-band and you re-invoke when ready.
+
+On B: stop the build phase. Output: `Build aborted — apply brand tokens with /gsp-brand-apply {brand-name} and re-run /gsp-project-build.`
+
+If all checks pass, log `✓ Brand tokens verified` and continue to Step 3.
 
 ## Step 3: Phase 2 — FOUNDATIONS
 
@@ -166,20 +189,16 @@ Spawn `gsp-project-builder` agent with **execution_mode: foundations**.
 ### Agent instructions:
 
 > execution_mode: foundations
+> Build token integration, global styles, layout primitives, theme provider/utilities ONLY.
 >
-> Build token integration, global styles, and layout primitives ONLY.
+> Foundation-specific actions:
+> 1. Add base styles + dark mode setup + font imports that `apply` did not handle (`cssVars.theme.font-sans` may set the CSS var without the `next/font/google` import — add it if missing)
+> 2. Create root layout with nav + footer shells (structure only)
+> 3. Create shared utilities (cn helper, theme provider)
+> 4. Apply STYLE.md bold bets + effects as CSS utilities / Tailwind extensions; validate against never/always constraints
+> 5. For shadcn targets: semantic tokens (`bg-primary`), never raw values (`bg-blue-500`); `gap-*` not `space-y-*`; `size-*` when w/h equal
 >
-> 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. 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.
+> See `agent-rules.md` (loaded in Step 2.6) for universal + per-mode guardrails (write to codebase, leave unstaged, log to `build/logs/foundations.md`, no BUILD-LOG.md direct write).
 
 ### Checkpoint: Compile check
 
@@ -234,54 +253,13 @@ Use `AskUserQuestion`: "Foundations look good? Continue building components, or
 
 ### Brand feedback loop
 
-If the user requests adjustments during foundation review:
-
-1. Apply the changes to the project codebase first (directly or via a quick builder re-run)
-2. Ask: "Should this change also update the brand system? (Other projects using this brand would inherit it)"
-3. If yes, spawn a background `gsp-brand-engineer` agent to update brand patterns:
-   - Pass: the specific changes made (what tokens/values changed, old → new)
-   - Pass: `{BRAND_PATH}/patterns/{brand-name}.yml` and relevant identity chunks
-   - Agent updates the `.yml` preset, foundation chunks, and STYLE.md if applicable
-   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
-   - Run synchronously (do NOT use `run_in_background`) — Step 4.5 reads the brand `.yml` from disk, so the updated values must be committed before components begin
-4. Wait for brand sync to complete, then continue to Step 4.5
+Read `${CLAUDE_SKILL_DIR}/brand-feedback.md` for the full procedure. Key constraint: the `gsp-brand-engineer` re-sync runs synchronously before Step 4.5 begins.
 
 ## Step 4.5: Phase 4 — COMPONENTS
 
-### Build component manifest
-
-Read ALL design chunks from `{PROJECT_PATH}/design/` — every `screen-{NN}-{name}.md`. Also read:
-- `{PROJECT_PATH}/brief/scope.md` (feature map)
-- `{PROJECT_PATH}/brief/target-adaptations.md` (component adaptations)
-- `{BRAND_PATH}/patterns/components/token-mapping.md` (if exists)
-
-Extract every component referenced across all screens. Deduplicate. Build a manifest:
-
-```
-COMPONENT_MANIFEST = [
-  { name: "Button", source: "shadcn", classification: "library-default", screens: [01, 03, 05] },
-  { name: "Card", source: "shadcn", classification: "library-customize", screens: [01, 02, 04], overrides: "custom radius + shadow from STYLE.md" },
-  { name: "PricingTier", source: "custom", classification: "custom", screens: [03] },
-  ...
-]
-```
-
-### Classify each component
-
-| Category | Criteria | Action |
-|----------|----------|--------|
-| `library-default` | Exists in target library, no brand overrides needed | Install as-is |
-| `library-customize` | Exists in target library, STYLE.md or token-mapping requires overrides | Install then customize |
-| `custom` | No library match, or design requires bespoke component | Build from scratch |
-| `existing` | Already in codebase (from scaffold or prior project) | Skip — already available |
+### Build component manifest + classify + partition
 
-### Partition into agent groups
-
-Group components to minimize conflicts:
-1. No two agents install the same library component
-2. Group related variants together (Card + CardHeader + CardContent + CardFooter → same agent)
-3. Balance work across agents (aim for 3-6 components per agent)
-4. If total components ≤ 5, use a single agent (no need to parallelize)
+Read `${CLAUDE_SKILL_DIR}/component-classification.md` for the manifest schema, classification table (`library-default` / `library-customize` / `custom` / `existing`), and partitioning rules (≤5 → single agent; group related variants; 3-6 components per agent).
 
 ### Resume check
 
@@ -324,18 +302,9 @@ Agent instructions template:
 > implementation_target: {target}
 > components: [{partition list with classifications}]
 >
-> Install, customize, or create the assigned components.
-> 1. For library-default: install via CLI, verify import works
-> 2. For library-customize: install via CLI, then apply brand overrides (STYLE.md constraints, token values)
-> 3. For custom: create from scratch following brand patterns and STYLE.md
-> 4. Read foundations from codebase (tokens, utilities already exist)
-> 5. Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
-> 6. Do NOT build screens or page content
-> 7. Write code directly to the codebase
-> 8. Leave changes unstaged
+> Install, customize, or create the assigned components per their classification (library-default → install as-is; library-customize → install + STYLE.md overrides; custom → create from scratch).
 >
-> After completing components, write `{PROJECT_PATH}/build/logs/component-{partition-name}.md` — list components installed/customized/created, files written, and any issues. Do NOT write to BUILD-LOG.md directly.
-> Also write `{PROJECT_PATH}/build/status/component-{partition-name}.json` with `{"status": "complete", "components": [{list}], "timestamp": "{ISO}"}`.
+> See `agent-rules.md` (loaded in Step 2.6) for guardrails (read foundations from codebase, do not modify foundation files, log to `build/logs/component-{partition-name}.md`, write `build/status/component-{partition-name}.json` for resume support).
 
 ### Checkpoint: Compile check
 
@@ -397,19 +366,14 @@ Agent instructions per screen:
 > execution_mode: screen
 > screen: {name} ({NN})
 >
-> Build the {name} screen. Foundations and components are already in the codebase.
+> Build the {name} screen. Foundations + components are already in the codebase.
 >
-> 1. Read the existing layout, tokens, utilities, and components from the codebase
-> 2. Create the route page and screen-specific components
-> 3. Wire imports to existing foundation and component files
-> 4. Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
-> 5. Do NOT modify shared component files (they were built in the components phase)
-> 6. Write code directly to the codebase, not to `.design/`
-> 7. Leave changes unstaged
-> 8. The brand's visual effects were implemented as utilities during foundations — use those utilities/classes
+> 1. Read existing layout, tokens, utilities, components from the codebase
+> 2. Create the route page + screen-specific components
+> 3. Wire imports to existing foundation + component files
+> 4. The brand's visual effects exist as utilities/classes from foundations — use them, don't redefine
 >
-> After completing this screen, write `{PROJECT_PATH}/build/logs/screen-{NN}-{name}.md` — list files written, components used, and any issues. Do NOT write to BUILD-LOG.md directly.
-> Also write `{PROJECT_PATH}/build/status/screen-{NN}-{name}.json` with `{"status": "complete", "screen": "{name}", "files": [{list}], "timestamp": "{ISO}"}`.
+> See `agent-rules.md` (loaded in Step 2.6) for guardrails (no modifying foundations or shared components, log to `build/logs/screen-{NN}-{name}.md`, write `build/status/screen-{NN}-{name}.json` for resume support).
 
 ### Checkpoint: Compile check
 
@@ -428,35 +392,7 @@ Update `{PROJECT_PATH}/STATE.md` `## Screen Build Status` table — set complete
 
 ## Step 5.5: Extraction review (lightweight)
 
-Components were built in Phase 4, so most reuse is already handled. This is a quick sanity check.
-
-### Automated scan
-
-Run these checks on the built codebase:
-
-1. **Hardcoded values** — Grep for hardcoded hex colors, rgb(), pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
-2. **Duplicated patterns** — Use Grep to find identical `className` strings (>3 classes) appearing in 2+ screen files. These are patterns the components phase missed.
-
-### Surface findings
-
-If issues found, present to user:
-
-```
-  ◆ post-build scan
-
-    Found {N} hardcoded values and {M} duplicated patterns.
-    {list if any}
-
-  ──────────────────────────────
-```
-
-If no issues: "Post-build scan clean — no hardcoded values or duplicated patterns found."
-
-Use `AskUserQuestion` only if issues were found: "Fix these, or continue to finalize?"
-- **Fix** → apply changes inline (mechanical refactors, no agent needed)
-- **Continue** → proceed to Step 6
-
-If hardcoded values map to missing brand tokens, suggest: "These token gaps may also exist in the brand. Consider running `/gsp-brand-refine` after build completes."
+Read `${CLAUDE_SKILL_DIR}/extraction-review.md` for the full procedure. Quick post-build sanity check: hardcoded values + duplicated patterns. If issues found, AskUserQuestion (Fix inline / Continue to Step 6).
 
 ## Step 6: Finalize
 

package/gsp/skills/gsp-project-build/agent-rules.md

@@ -0,0 +1,36 @@
+# Agent Rules (foundations + components + screens)
+
+Common guardrails for `gsp-project-builder` agent spawns. Each spawn references this file once instead of repeating the rules inline. Mode-specific instructions are in the spawn block (foundations / component / screen).
+
+## Universal rules (all modes)
+
+- **Write code directly to the codebase** — not to `.design/`
+- **Leave changes unstaged** — orchestrator handles commits
+- **Do NOT write to BUILD-LOG.md directly** — orchestrator merges per-agent logs after each phase. Each agent writes to `{PROJECT_PATH}/build/logs/{phase}-{name}.md`
+- For component/screen modes, also write `{PROJECT_PATH}/build/status/{phase}-{name}.json` with `{"status": "complete", "timestamp": "{ISO}"}` for resume support
+
+## Mode-specific guardrails
+
+### foundations
+- Verify brand tokens are already installed in `globals.css` (orchestrator gates this; tokens MUST be present before agent runs)
+- If tokens missing, abort with error pointing at `/gsp-brand-apply {brand-name}`. Do NOT manually paste tokens
+- Build root layout shells, shared utilities, theme providers ONLY
+- Do NOT build individual screens or page content
+
+### component
+- Read foundations from codebase (tokens, utilities already exist)
+- Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
+- Do NOT build screens or page content
+- Library-default → install via CLI as-is
+- Library-customize → install + apply STYLE.md overrides (radius, shadow, color tokens)
+- Custom → create from scratch following brand patterns
+
+### screen
+- Read foundations + components from codebase
+- Do NOT modify foundation files
+- Do NOT modify shared component files (built in Phase 4)
+- Build the screen's route page + screen-specific components only
+
+## When in doubt
+
+STYLE.md takes precedence over all defaults. If the preset explicitly defines a technique, implement it. The methodology file (`methodology/gsp-project-builder.md`) has the full domain-rule pointers (color, typography, accessibility, imagery, anti-patterns).

package/gsp/skills/gsp-project-build/brand-feedback.md

@@ -0,0 +1,12 @@
+# Brand Feedback Loop (Step 4)
+
+If the user requests adjustments during foundation review:
+
+1. **Apply to project codebase first** — directly or via a quick builder re-run
+2. **Ask:** "Should this change also update the brand system? (Other projects using this brand would inherit it.)"
+3. **If yes**, spawn a `gsp-brand-engineer` agent **synchronously** (NOT `run_in_background` — Step 4.5 reads the brand `.yml` from disk; updated values must be committed before components begin):
+   - Pass: the specific changes made (what tokens/values changed, old → new)
+   - Pass: `{BRAND_PATH}/patterns/{brand-name}.yml` and relevant identity chunks
+   - Agent updates the `.yml` preset, foundation chunks, and STYLE.md if applicable
+   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
+4. **Wait for brand sync to complete**, then continue to Step 4.5

package/gsp/skills/gsp-project-build/component-classification.md

@@ -0,0 +1,36 @@
+# Component Classification (Step 4.5)
+
+## Build component manifest
+
+Read ALL design chunks from `{PROJECT_PATH}/design/` — every `screen-{NN}-{name}.md`. Also read:
+- `{PROJECT_PATH}/brief/scope.md` (feature map)
+- `{PROJECT_PATH}/brief/target-adaptations.md` (component adaptations)
+- `{BRAND_PATH}/patterns/components/token-mapping.md` (if exists)
+
+Extract every component referenced across all screens. Deduplicate. Build a manifest:
+
+```
+COMPONENT_MANIFEST = [
+  { name: "Button", source: "shadcn", classification: "library-default", screens: [01, 03, 05] },
+  { name: "Card", source: "shadcn", classification: "library-customize", screens: [01, 02, 04], overrides: "custom radius + shadow from STYLE.md" },
+  { name: "PricingTier", source: "custom", classification: "custom", screens: [03] },
+  ...
+]
+```
+
+## Classify each component
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| `library-default` | Exists in target library, no brand overrides needed | Install as-is |
+| `library-customize` | Exists in target library, STYLE.md or token-mapping requires overrides | Install then customize |
+| `custom` | No library match, or design requires bespoke component | Build from scratch |
+| `existing` | Already in codebase (from scaffold or prior project) | Skip — already available |
+
+## Partition into agent groups
+
+Group components to minimize conflicts:
+1. No two agents install the same library component
+2. Group related variants together (Card + CardHeader + CardContent + CardFooter → same agent)
+3. Balance work across agents (aim for 3-6 components per agent)
+4. If total components ≤ 5, use a single agent (no need to parallelize)

package/gsp/skills/gsp-project-build/extraction-review.md

@@ -0,0 +1,31 @@
+# Extraction Review (Step 5.5)
+
+Components were built in Phase 4, so most reuse is already handled. This is a quick sanity check.
+
+## Automated scan
+
+Run these on the built codebase:
+
+1. **Hardcoded values** — Grep for hardcoded hex colors, `rgb()`, pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
+2. **Duplicated patterns** — Grep for identical `className` strings (>3 classes) appearing in 2+ screen files. These are patterns the components phase missed.
+
+## Surface findings
+
+If issues found:
+
+```
+  ◆ post-build scan
+
+    Found {N} hardcoded values and {M} duplicated patterns.
+    {list if any}
+
+  ──────────────────────────────
+```
+
+If no issues: "Post-build scan clean — no hardcoded values or duplicated patterns found."
+
+Use `AskUserQuestion` only if issues were found: "Fix these, or continue to finalize?"
+- **Fix** → apply changes inline (mechanical refactors, no agent needed)
+- **Continue** → proceed to Step 6
+
+If hardcoded values map to missing brand tokens, suggest: "These token gaps may also exist in the brand. Consider running `/gsp-brand-refine` after build completes."

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

@@ -17,8 +17,8 @@ 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. 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)
+- **Verify** brand tokens are already installed in the CSS file (path declared in `components.json` → `.tailwind.css`). The orchestrator has already gated this — by the time you run, tokens MUST be present (installed via `/gsp-brand-apply` either directly or through the brand-guidelines prompt). If you find tokens missing, abort with a clear error pointing at `/gsp-brand-apply {brand-name}`. **Do NOT manually paste tokens or run `theme-css.js`.**
+- Base styles, dark mode setup, and any font imports that `apply` did not handle (`cssVars.theme.font-sans` may set the CSS variable but not generate the `next/font/google` import in `layout.tsx` — add it if missing, leave it alone if present)
 - Layout components (root layout, nav shell, footer shell)
 - Shared utilities (cn helper, theme provider)
 - **Do NOT build individual screens or page content**
@@ -93,16 +93,23 @@ When the user gives feedback during a build, classify it:
 
 Never silently apply style-level changes to code without surfacing the choice. A button radius change in one screen that doesn't flow back to the `.yml` creates drift — the next screen gets built with the old radius.
 
-## Anti-Pattern Awareness (distilled)
+## Anti-Pattern Awareness (delegated to expertise)
 
-Check code against these before marking a screen complete — **but STYLE.md takes precedence**. If the preset explicitly defines a technique listed here, implement what the preset says. These are defaults for when the style is silent.
+**STYLE.md takes precedence over all defaults.** When the preset is silent, defer to the canonical owners:
 
-- **Typography:** no Inter/Roboto defaults, `font-variant-numeric: tabular-nums` for data, `text-wrap: balance` for headings
-- **Color:** off-black not #000, tint shadows to background hue, single accent color, single light source
+- **Color** — `${CLAUDE_SKILL_DIR}/../gsp-color/domains/system.md` (off-black, accent count, shadow tinting, light source) + `${CLAUDE_SKILL_DIR}/../gsp-color/references/color-composition.md` (60-30-10 rule)
+- **Typography** — `${CLAUDE_SKILL_DIR}/../gsp-typography/domains/system.md` + `pairing.md` (no Inter/Roboto defaults, `tabular-nums`, `text-wrap: balance`, scale ratios)
+- **Motion + effects** — `${CLAUDE_SKILL_DIR}/../gsp-accessibility/motion-effects.md` (`prefers-reduced-motion`, contrast on effects, hover magnitudes, spring physics)
+- **Imagery** — `${CLAUDE_SKILL_DIR}/../gsp-visuals/domains/imagery.md` (photography, illustration, treatments)
+- **Full anti-pattern catalog** — `${CLAUDE_SKILL_DIR}/../gsp-project-critique/anti-patterns.md` (consolidated checklist; cite this for code-quality patterns beyond the domains above)
+- **STYLE.md vocabulary** — `${CLAUDE_SKILL_DIR}/../gsp-style/style-preset-schema.md` (constraint/pattern/effects/bold-bet structure)
+
+Do not re-derive these rules inline — read the canonical owner before applying.
+
+**Builder-specific defaults** (not domain knowledge — keep here):
 - **Layout:** `min-h-[100dvh]` not `h-screen`, always max-width, CSS Grid over flexbox %, bottom-align CTAs in card groups
-- **Surfaces:** vary elevation treatments, z-layer system (flat/subtle/elevated/floating/overlay)
+- **Surfaces:** z-layer system (flat/subtle/elevated/floating/overlay)
 - **Content:** real copy always, diverse names, organic numbers, sentence case, no AI clichés
-- **Motion:** spring physics (`cubic-bezier(0.16,1,0.3,1)`), `transform`+`opacity` only, 200-300ms minimum, `prefers-reduced-motion`, stagger entrances
 - **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
 
@@ -187,7 +194,7 @@ These rules are always enforced for shadcn targets. They reflect the official sh
   ```
 - 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).
+Full reference: `${CLAUDE_SKILL_DIR}/../gsp-project-critique/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.
 
@@ -197,7 +204,7 @@ Every screen must pass these before marking complete. When `STYLE.md` is provide
 
 1. **Background treatment** — never plain white/dark. Subtle gradient, texture, or decorative element.
 2. **State polish** — hover/focus/active/pressed feel deliberate (shadow shifts, subtle scale, translateY) not just color swaps
-3. **Icon consistency** — one icon family, one stroke weight throughout
+3. **Icon consistency** — import from `preferences.icon_library` only (project config — defaults to `lucide`); one icon family, one stroke weight throughout. No mixing libraries within a screen
 4. **Image direction** — imagery style (photo/illustration/CSS-only) matches brand character
 5. **Responsive craft** — mobile is a designed experience, not just "it fits"
 

package/gsp/skills/gsp-project-build/visual-effects.md

@@ -457,19 +457,4 @@ Beyond basic glassmorphism — simulating realistic glass edge refraction and de
 
 ## Accessibility
 
-All visual effects must degrade gracefully:
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-- Glow/shadow: ensure text contrast meets WCAG AA without effects
-- Backdrop-blur: `@supports not (backdrop-filter: blur(1px))` solid bg fallback
-- Gradient text: test contrast ratio of gradient endpoints, not just midpoint
-- Hover transforms: keep magnitude small (2-4px translate, 1.02-1.05 scale) to avoid disorientation
+Canonical motion + effects accessibility guidance lives in `${CLAUDE_SKILL_DIR}/../gsp-accessibility/motion-effects.md` — owned by `gsp-accessibility`. Builder must read it before applying any effect from this reference. Covers `prefers-reduced-motion`, contrast on glow/shadow/gradient text, backdrop-filter fallbacks, and hover-transform magnitudes.

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

@@ -69,10 +69,12 @@ Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`
 Read these reference files and hold their content for inlining into agent prompts in Step 2:
 - `${CLAUDE_SKILL_DIR}/../gsp-accessibility-audit/wcag-checklist.md`
 - `${CLAUDE_SKILL_DIR}/../gsp-color/references/color-composition.md`
+- `${CLAUDE_SKILL_DIR}/../gsp-typography/domains/scale.md` — type-scale verification rules
+- `${CLAUDE_SKILL_DIR}/../gsp-visuals/domains/imagery.md` — imagery vocabulary for critique
 - `${CLAUDE_SKILL_DIR}/../gsp-accessibility-audit/methodology/gsp-accessibility-auditor.md`
 - `${CLAUDE_SKILL_DIR}/../../templates/phases/critique.md` — critique output template
 
-> **Note:** Nielsen's heuristics, visual taste, and anti-patterns are distilled into the `gsp-project-critic` agent prompt. Full refs remain on disk for edge-case agent lookup.
+> **Note:** Nielsen's heuristics, visual taste, and anti-patterns are distilled into the `gsp-project-critic` agent prompt. anti-patterns.md is a critic-owned consolidated checklist; canonical sources are gsp-typography, gsp-color, gsp-visuals — update those when fixing drift, not the consolidated checklist alone.
 
 ## Step 1.9: Load agent methodology
 
@@ -92,6 +94,8 @@ Read `${CLAUDE_SKILL_DIR}/methodology/gsp-project-critic.md`. Include the full c
 - **Content of** research recommendations.md (loaded in Step 1)
 - **Content of** BRIEF.md
 - **Content of** color composition reference (loaded in Step 1.8)
+- **Content of** typography scale reference (loaded in Step 1.8)
+- **Content of** imagery vocabulary reference (loaded in Step 1.8)
 - **Content of** critique output template (loaded in Step 1.8)
 - `references_path`: `${CLAUDE_SKILL_DIR}/` — for supplementary Read access to visual-taste.md, anti-patterns.md
 - Output path: `{PROJECT_PATH}/critique/`