get-shit-pretty 0.5.0 → 0.5.2

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

@@ -1,6 +1,6 @@
 ---
 name: brand-patterns
-description: Build your design system — tokens, components, preview
+description: Build your design system — tokens, components, brand guidelines
 user-invocable: true
 allowed-tools:
   - Read
@@ -11,22 +11,22 @@ allowed-tools:
   - Glob
 ---
 <context>
-Phase 4 of the GSP branding diamond. Builds the design system (foundations, components, tokens), generates a self-contained brand preview HTML, and transitions the user from the branding diamond to the project diamond.
+Phase 4 of the GSP branding diamond. Builds the design system (foundations, components, tokens), generates a self-contained brand guidelines HTML, and transitions the user from the branding diamond to the project diamond.
 
 Adapts strategy based on codebase context — generates from scratch, extends an existing system, or redesigns with migration mapping.
 </context>
 
 <objective>
-Build the design system, generate brand preview, and complete the branding diamond.
+Build the design system, generate brand guidelines, and complete the branding diamond.
 
 **Input:** Brand identity + strategy + BRIEF.md
-**Output:** `{brand}/system/` (foundations/, components/, principles.md, tokens.json, {brand-name}.yml, {brand-name}.md, INDEX.md) + `{brand}/preview.html`
-**Agent:** `gsp-system-architect`
+**Output:** `{brand}/patterns/` (foundations/, components/, principles.md, tokens.json, {brand-name}.yml, {brand-name}.md, INDEX.md) + `{brand}/guidelines.html`
+**Agent:** `gsp-pattern-architect`
 </objective>
 
 <execution_context>
 @${CLAUDE_SKILL_DIR}/../../prompts/01-design-system-architect.md
-@${CLAUDE_SKILL_DIR}/../../templates/phases/system.md
+@${CLAUDE_SKILL_DIR}/../../templates/phases/patterns.md
 @${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
 </execution_context>
 
@@ -106,24 +106,24 @@ Redesign the system from the ground up, informed by what exists.
 4. Preserve conventions unless the brand requires changes
 5. Flag breaking changes explicitly
 
-## Step 3: Spawn system architect — Pass 1: Foundations
+## Step 3: Spawn pattern architect — Pass 1: Foundations
 
-Spawn the `gsp-system-architect` agent with:
+Spawn the `gsp-pattern-architect` agent with:
 - All identity chunks (or IDENTITY.md fallback) + palettes.json
 - The BRIEF.md content
 - The Design System Architect prompt (01)
-- The system output template
+- The patterns output template
 - The design tokens reference
 - The `system_strategy` and `tech_stack` values
 - The `style_base` value + preset `.yml`/`.md` files (if loaded)
 - The `.design/system/STACK.md`, `COMPONENTS.md`, `TOKENS.md` content (when exist)
 - **Execution mode:** `"foundations"`
-- **Output path:** `{BRAND_PATH}/system/`
+- **Output path:** `{BRAND_PATH}/patterns/`
 
 The agent writes foundations only:
-- `system/foundations/` (6 foundation chunks)
-- `system/principles.md`
-- `system/tokens.json` (foundations-only)
+- `patterns/foundations/` (6 foundation chunks)
+- `patterns/principles.md`
+- `patterns/tokens.json` (foundations-only)
 
 ## Step 3.5: Foundation review (interactive)
 
@@ -159,9 +159,9 @@ Before building components, load persona profiles from `{BRAND_PATH}/BRIEF.md` a
 If user wants changes → update foundations.
 If confirmed → proceed to components pass.
 
-## Step 4: Spawn system architect — Pass 2: Components
+## Step 4: Spawn pattern architect — Pass 2: Components
 
-Spawn the `gsp-system-architect` agent with:
+Spawn the `gsp-pattern-architect` agent with:
 - The existing foundations from Pass 1
 - All identity chunks + palettes.json
 - Strategy chunks: voice-and-tone.md, archetype.md, positioning.md (needed for custom style output)
@@ -169,25 +169,25 @@ Spawn the `gsp-system-architect` agent with:
 - The `style_base` value + preset `.yml`/`.md` files (if loaded)
 - **Execution mode:** `"components"`
 - Confirmed component scope from Step 1.5
-- **Output path:** `{BRAND_PATH}/system/`
+- **Output path:** `{BRAND_PATH}/patterns/`
 
 The agent writes components + custom style:
-- `system/components/` (one per component)
-- Updates `system/tokens.json` (adds component tokens)
-- `system/{brand-name}.yml` (custom style preset — portable, reusable)
-- `system/{brand-name}.md` (custom style prompt — AI-ready)
-- `system/INDEX.md`
+- `patterns/components/` (one per component)
+- Updates `patterns/tokens.json` (adds component tokens)
+- `patterns/{brand-name}.yml` (custom style preset — portable, reusable)
+- `patterns/{brand-name}.md` (custom style prompt — AI-ready)
+- `patterns/INDEX.md`
 
 ## Step 4.5: Update state
 
 Update `{BRAND_PATH}/STATE.md`:
-- Set Phase 4 (System) status to `complete`
+- Set Phase 4 (Patterns) status to `complete`
 - Record completion date
 - Set Prettiness Level to 100%
 
-## Step 4.75: Generate brand preview
+## Step 4.75: Generate brand guidelines
 
-Create a self-contained HTML file at `{BRAND_PATH}/preview.html`.
+Create a self-contained HTML file at `{BRAND_PATH}/guidelines.html`.
 
 Read all available brand outputs:
 - `{BRAND_PATH}/identity/palettes.json` — color palette data
@@ -208,30 +208,15 @@ Generate a single self-contained HTML file with:
 - **Logo direction descriptions** — each direction with rationale
 - **Archetype summary** — the selected archetype and its expression
 
-Tell the user: "Brand preview saved — open it in your browser to see the full brand at a glance."
+Tell the user: "Brand kit saved to `guidelines.html` — open it in your browser to see your colors, typography, voice, and messaging in one page. You can also print or export to PDF as a shareable brand guide."
 
 ## Step 5: Phase transition output
 
-Render the phase transition screen (see `references/phase-transitions.md` for styling):
+Render phase transition (see `references/phase-transitions.md`).
 
-```
-  ◆ system complete — design system built
-
-    system/
-    ├── foundations/
-    │   ├── {foundation files}
-    ├── components/
-    │   ├── {component files}
-    ├── principles.md
-    ├── tokens.json
-    ├── {brand-name}.yml
-    ├── {brand-name}.md
-    └── INDEX.md
-
-  ──────────────────────────────
-```
+**Critical:** When the user chooses "Start a project", invoke `/gsp:start` via the Skill tool. Do NOT attempt to handle project setup inline — `/gsp:start` has the codebase scanning, questioning rounds, and brief-writing logic needed for a proper project setup. The branding agent's context is spent on brand work and lacks the project setup methodology.
 
-Then display the brand summary:
+Also display a brand summary after the standard transition — this is the final branding phase:
 
 ```
   brand complete — {brand-name}
@@ -239,13 +224,8 @@ Then display the brand summary:
     discover       {key finding}
     strategy       {archetype}, {positioning}, {top voice attributes}
     identity       {colors}, {typefaces}
-    system         {N} foundations, {N} components
+    patterns       {N} foundations, {N} components
 
-    preview: {BRAND_PATH}/preview.html
+    guidelines: {BRAND_PATH}/guidelines.html
 ```
-
-Then use `AskUserQuestion` with 3 options:
-- **Start a project** — "scope what you're building with this brand"
-- **View progress** — "see the full dashboard"
-- **Done for now** — "pick up later with /gsp:start"
 </process>

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

@@ -53,8 +53,14 @@ Present a compact research plan, then use `AskUserQuestion`:
 - **Looks good** — "Start research with this scope"
 - **Adjust** — "I want to add competitors or shift emphasis"
 
+## Step 2.5: Pre-fetch competitor sites (background)
+
+While preparing the agent context, use `WebFetch` with `run_in_background: true` for each competitor URL or website found in BRIEF.md's competitive landscape. This warms the cache so the researcher agent has content ready instead of fetching sequentially during research.
+
 ## Step 3: Spawn researcher
 
+Include any pre-fetched competitor content in the agent context.
+
 Spawn the `gsp-researcher` agent with:
 - BRIEF.md content
 - Discover output template
@@ -78,8 +84,5 @@ Update `{BRAND_PATH}/STATE.md`: set Phase 1 (Discover) to `complete`.
 
 ## Step 5: Phase transition
 
-Render phase transition screen, then use `AskUserQuestion`:
-- **Continue to strategy** — "define positioning, voice, and messaging"
-- **View progress** — "see the full dashboard"
-- **Done for now** — "pick up later with /gsp:start"
+Render phase transition (see `references/phase-transitions.md`).
 </process>

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

@@ -142,8 +142,5 @@ If adjust → loop back. If confirmed → proceed.
 
 Update `{BRAND_PATH}/STATE.md`: set Phase 2 (Strategy) to `complete`.
 
-Render phase transition, then use `AskUserQuestion`:
-- **Continue to identity** — "create visual identity"
-- **View progress** — "see the full dashboard"
-- **Done for now** — "pick up later with /gsp:start"
+Render phase transition (see `references/phase-transitions.md`).
 </process>

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

@@ -0,0 +1,101 @@
+---
+name: brand-sync
+description: Sync brand to match a project's shipped state — tokens, voice, visual patterns, personality
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<context>
+Standalone brand feedback skill. After a project ships (or mid-development), the codebase and content may have diverged from the brand system — adjusted colors, shifted tone of voice, evolved visual patterns. This skill detects those divergences across all brand dimensions and updates the brand to match.
+
+This is the standalone version of the feedback loop built into `/gsp:project-build` (build-time). Use this when:
+- A project evolved beyond its original brand during development
+- Manual tweaks were made post-build
+- The voice/tone landed differently than the strategy specified
+- You want to capture a project's shipped look and feel as the new brand baseline
+</context>
+
+<objective>
+Compare a project's shipped state against its source brand across all dimensions — tokens, voice, visual patterns, and personality — surface divergences, and update the brand if confirmed.
+
+**Input:** A project with a linked brand (via project config or `.design/branding/`)
+**Output:** Updated brand tokens, strategy chunks, identity chunks, and style preset (as applicable)
+**Agent:** `gsp-brand-syncer`
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- Never update the brand without explicit user confirmation
+- Show before/after for every change — no silent updates
+- Only update dimensions that actually diverged — don't regenerate the entire brand
+</rules>
+
+<process>
+## Step 0: Resolve brand and project
+
+Scan `.design/branding/` for brand directories. One brand → use it. Multiple → use `AskUserQuestion`.
+
+Set `BRAND_PATH` = `.design/branding/{brand}`
+
+Check that the brand has at least one of: `patterns/tokens.json`, `strategy/`, `identity/`. If none exist, tell the user: "No brand system found. Run `/gsp:brand-patterns` first."
+
+Verify the project codebase has shipped output — source files with components, copy, or styles.
+
+## Step 1: Spawn syncer agent
+
+```bash
+mkdir -p {BRAND_PATH}/sync
+```
+
+Spawn the `gsp-brand-syncer` agent with:
+- `BRAND_PATH` and all available brand files (tokens.json, strategy chunks, identity chunks, foundation chunks)
+- Project codebase location (working directory)
+- **Output path:** `{BRAND_PATH}/sync/`
+
+The agent writes `SYNC-REPORT.md` with divergences across four dimensions: tokens, voice & tone, visual patterns, personality. Each divergence includes evidence (file paths, line numbers, before/after values).
+
+## Step 2: Present findings
+
+Read `{BRAND_PATH}/sync/SYNC-REPORT.md`. Present a compact summary per dimension, then use `AskUserQuestion`:
+
+- **Sync all** — update brand across all dimensions
+- **Tokens only** — just sync the quantitative token changes
+- **Pick by dimension** — choose which dimensions to sync
+- **Review each** — walk through every divergence individually
+- **Skip** — don't update the brand
+
+If "Pick by dimension", ask per dimension. If "Review each", walk through the Update Map from the report.
+
+For "Removed" tokens: ask whether to remove from brand or keep (may be used by other projects).
+
+## Step 3: Apply confirmed updates
+
+Use the Update Map from the sync report. For each confirmed change:
+
+**Tokens** — edit `tokens.json` in place (preserve W3C structure). Update corresponding foundation chunks in `{BRAND_PATH}/patterns/foundations/` and style preset `.yml` if it exists.
+
+**Voice & tone** — update `{BRAND_PATH}/strategy/voice-and-tone.md` (adjust attributes, tone positions, style rules). Update `messaging.md` if messaging shifted.
+
+**Visual patterns** — update foundation chunks in `{BRAND_PATH}/patterns/foundations/`. Update component specs and identity chunks if visual identity evolved.
+
+**Personality** — update `{BRAND_PATH}/strategy/archetype.md` and `positioning.md`. Update `brand-platform.md` if values/promise shifted.
+
+Preserve chunk format per `references/chunk-format.md`. Update INDEX.md files if chunks were added.
+
+## Step 4: Summary
+
+Show which files were updated per dimension, then use `AskUserQuestion`: "Brand synced to project. Other projects using this brand will inherit these changes on their next build."
+
+</process>

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

@@ -99,7 +99,7 @@ mkdir -p .design/system
 2. **CSS custom properties** in `globals.css` / `global.css`
 3. **Theme files** — `theme.ts`, `tokens.json`, `tokens.ts`
 4. **Dark mode setup** — next-themes, class strategy, media query
-5. **Prior GSP tokens** — scan `.design/branding/*/system/` for existing brand tokens
+5. **Prior GSP tokens** — scan `.design/branding/*/patterns/` for existing brand tokens
 
 6. **Write `.design/system/TOKENS.md`** from the TOKENS template
 

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

@@ -55,23 +55,23 @@ For each instance, read:
 
 **Check B1: Brand Structure**
 Required: config.json, STATE.md, BRIEF.md
-Required dirs: discover/, strategy/, identity/, system/
+Required dirs: discover/, strategy/, identity/, patterns/
 Missing → FAIL
 
 **Check B2: Brand Phase Ordering**
-No phase complete if earlier phase is pending (discover < strategy < identity < system).
+No phase complete if earlier phase is pending (discover < strategy < identity < patterns).
 Exception: strategy can proceed without discover.
 
 **Check B3: Brand Completeness**
 If all 4 phases complete, check:
 - `identity/INDEX.md` exists (chunk format)
 - `identity/palettes.json` exists (WARN if missing)
-- `system/INDEX.md` exists (chunk format)
-- `system/tokens.json` exists (WARN if missing)
+- `patterns/INDEX.md` exists (chunk format)
+- `patterns/tokens.json` exists (WARN if missing)
 - If monolith exists without INDEX.md → WARN: "Legacy monolith format"
 
 **Check B4: Legacy Monolith Detection**
-For each brand phase directory (discover, strategy, identity, system):
+For each brand phase directory (discover, strategy, identity, patterns):
 - If monolith exists but no INDEX.md → WARN: "Legacy format in {phase}/ — re-run /gsp:brand-{phase} for chunk output"
 
 ### Per-Project Checks (6-phase)
@@ -128,7 +128,7 @@ All phases in order (or validly skipped) → PASS
 Only check phases that are `complete`. All paths relative to the project instance directory.
 
 **When `system_strategy` is `extend`:**
-- Check if brand's `system/` output contains "Component Audit" or "KEEP" or "RESTYLE" or "REFACTOR" or "REPLACE"
+- Check if brand's `patterns/` output contains "Component Audit" or "KEEP" or "RESTYLE" or "REFACTOR" or "REPLACE"
 - If none found → WARN: "Strategy is `extend` but system output lacks component audit table. Re-run `/gsp:brand-patterns`."
 
 **When `implementation_target` is `shadcn`:**
@@ -235,7 +235,7 @@ No upgrade concerns → PASS
 ### Installation Health Checks
 
 **Check I1: Skills have `user-invocable: true`**
-Glob for all SKILL.md files in the skills directory (`.claude/skills/*/SKILL.md` or equivalent runtime path). For each skill (except the plugin entry point `get-shit-pretty`), check frontmatter for `user-invocable: true`.
+Glob for all SKILL.md files in the skills directory (`{runtime-dir}/skills/*/SKILL.md` — e.g. `.claude/skills/` for Claude Code, `.opencode/skills/` for OpenCode, `.gemini/skills/` for Gemini). For each skill (except the plugin entry point `get-shit-pretty`), check frontmatter for `user-invocable: true`.
 - All present → PASS
 - Missing → WARN: "Skills missing `user-invocable: true`: {list}. They won't appear in the slash-command menu. Re-run the installer or add the field manually."
 

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

@@ -41,6 +41,7 @@ Skill names are left-padded with 4 spaces. Descriptions start at column 27 (4 in
     /gsp:brand-strategy    define positioning, personality, voice and messaging
     /gsp:brand-identity    create visual identity
     /gsp:brand-patterns    build design system tokens and components
+    /gsp:brand-sync        sync brand to match a project's shipped state
     /gsp:brand-audit       audit existing brand before evolving (optional)
 
   ─── Project ──────────────────────────
@@ -96,7 +97,7 @@ Skill names are left-padded with 4 spaces. Descriptions start at column 27 (4 in
     │       ├── discover/         research chunks
     │       ├── strategy/         strategy + voice and messaging
     │       ├── identity/         visual identity
-    │       └── system/           tokens + components
+    │       └── patterns/         tokens + components
     └── projects/
         └── {project}/
             ├── config.json       project config

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

@@ -88,8 +88,7 @@ Update `{PROJECT_PATH}/STATE.md`:
 - Add Launch status to `complete` under the Launch section
 - Record completion date
 
-## Step 4: Done
+## Step 4: Phase transition output
 
-Display campaign summary and:
-"Launch assets complete! Run `/gsp:progress` to see the full journey."
+Render phase transition (see `references/phase-transitions.md`). This is the final phase.
 </process>

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

@@ -15,7 +15,7 @@ Phase 1 of the GSP project diamond. Scopes the project by determining what scree
 
 Encourages treating the project as a bounded issue (or set of issues) and a PR — ship small, ship complete.
 
-Works with the dual-diamond architecture: reads brand system from `.design/branding/{brand}/system/` via `brand.ref`, reads/writes project assets in `.design/projects/{project}/`.
+Works with the dual-diamond architecture: reads brand system from `.design/branding/{brand}/patterns/` via `brand.ref`, reads/writes project assets in `.design/projects/{project}/`.
 </context>
 
 <objective>
@@ -46,15 +46,15 @@ If brand.ref doesn't exist, tell the user to run `/gsp:start` to set up the proj
 
 ## Step 1: Load context
 
-### Brand system (chunk-first)
+### Brand patterns (chunk-first)
 
-Read `{BRAND_PATH}/system/INDEX.md`. If it exists, load all foundation chunks + selective component chunks.
+Read `{BRAND_PATH}/patterns/INDEX.md`. If it exists, load all foundation chunks + selective component chunks.
 
-Fallback: read `{BRAND_PATH}/system/SYSTEM.md` (legacy monolith). Log: "⚠️ Legacy system format detected."
+Fallback: read `{BRAND_PATH}/patterns/SYSTEM.md` (legacy monolith). Log: "⚠️ Legacy format detected."
 
-If neither exists, tell the user to run `/gsp:brand-patterns` first to create the brand's design system.
+If neither exists, tell the user to run `/gsp:brand-patterns` first to create the brand's design patterns.
 
-Also read `{BRAND_PATH}/system/tokens.json`.
+Also read `{BRAND_PATH}/patterns/tokens.json`.
 
 ### Project context
 
@@ -138,21 +138,6 @@ Update `{PROJECT_PATH}/STATE.md`:
 
 ## Step 5: Phase transition output
 
-Render the phase transition screen (see `references/phase-transitions.md` for styling):
-
-```
-  ◆ brief complete — project scoped
-
-    brief/
-    ├── {actual files written}
-    └── INDEX.md
-
-  ──────────────────────────────
-```
-
-Then use `AskUserQuestion` with 3 options:
-- **Continue to research** — "research UX patterns and approaches"
-- **View progress** — "see the full dashboard"
-- **Done for now** — "pick up later with /gsp:start"
+Render phase transition (see `references/phase-transitions.md`).
 </process>
 </output>

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

@@ -15,7 +15,7 @@ allowed-tools:
 <context>
 Phase 5 of the GSP project diamond. Uses a 4-phase pipeline with verification checkpoints to implement designs directly in the codebase as production-ready frontend components.
 
-Works with the dual-diamond architecture: reads brand system from `.design/branding/{brand}/system/` via `brand.ref`, reads/writes project assets in `.design/projects/{project}/`.
+Works with the dual-diamond architecture: reads brand system from `.design/branding/{brand}/patterns/` via `brand.ref`, reads/writes project assets in `.design/projects/{project}/`.
 
 **Pipeline architecture:**
 ```
@@ -49,6 +49,9 @@ Implement designs as production-ready code in the codebase via phased pipeline w
 <execution_context>
 @${CLAUDE_SKILL_DIR}/../../prompts/09-design-to-code-translator.md
 @${CLAUDE_SKILL_DIR}/../../templates/phases/build.md
+@${CLAUDE_SKILL_DIR}/../../references/visual-effects.md
+@${CLAUDE_SKILL_DIR}/../../references/block-patterns.md
+@${CLAUDE_SKILL_DIR}/../../references/anti-patterns.md
 </execution_context>
 
 <process>
@@ -61,6 +64,13 @@ Set `PROJECT_PATH` = `.design/projects/{project}`
 Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
 - Set `BRAND_PATH` = `.design/branding/{brand}`
 
+## Step 0.5: Validate prerequisites
+
+Read `{PROJECT_PATH}/STATE.md`. Check that Design (Phase 3) is `complete` or `needs-revision` (revision means critique ran and is feeding back).
+If design is `pending` or missing: "No designs found. Run `/gsp:project-design` first — building without designs leads to poor results." Then stop.
+
+Exception: if `design_scope` is `tokens` in config.json, skip this check (tokens-only projects don't need design).
+
 ## Step 1: Load config and check state
 
 Read `{PROJECT_PATH}/config.json` to get `implementation_target`, `design_scope`, `codebase_type`.
@@ -111,7 +121,8 @@ Spawn `gsp-builder` agent with **execution_mode: foundations**.
 
 | File | Purpose |
 |------|---------|
-| `{BRAND_PATH}/system/tokens.json` | Design tokens |
+| `{BRAND_PATH}/patterns/tokens.json` | Design tokens |
+| `{BRAND_PATH}/patterns/{brand-name}.md` | Brand visual DNA — effects, component stylings, bold bets (if exists) |
 | `{PROJECT_PATH}/brief/target-adaptations.md` | Component adaptations for target |
 | `.design/system/STACK.md` | Stack state |
 | `.design/system/CONVENTIONS.md` | Codebase conventions (if exists) |
@@ -129,9 +140,10 @@ Spawn `gsp-builder` agent with **execution_mode: foundations**.
 > 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. Do NOT build individual screens or page content
-> 6. Write code directly to the codebase, not to `.design/`
-> 7. Leave changes unstaged
+> 5. Apply the brand style prompt's visual effects and signature patterns — create CSS utilities or Tailwind extensions for the brand's signature effects (glass, glow, gradients, shadows, motion patterns)
+> 6. Do NOT build individual screens or page content
+> 7. Write code directly to the codebase, not to `.design/`
+> 8. Leave changes unstaged
 >
 > After completing foundations, write `{PROJECT_PATH}/build/BUILD-LOG.md` with what was done (foundations section only).
 
@@ -146,9 +158,24 @@ After the foundations agent completes, run the build command:
 | TypeScript only | `npx tsc --noEmit` |
 | Generic | `npm run build` |
 
-**Pass:** Continue to Step 4.
+**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.
 
+### Preview verification (opt-in)
+
+After compile passes, verify the foundations actually render:
+
+1. Check if dev server is already running (`lsof -i :3000` or `:5173`)
+2. If running, use `curl -s http://localhost:{port}` to fetch the page
+3. Check the HTML response for:
+   - **Not blank** — response body has more than just the shell/boilerplate (>500 chars of content)
+   - **Tokens resolved** — grep the response for CSS variables or Tailwind classes from the token config. If `var(--` appears but no matching custom property is defined, tokens may be broken.
+   - **Font loaded** — check for the expected Google Fonts import or `@font-face` rule
+
+If dev server is not running, skip verification silently — do not start one. This keeps it zero-config.
+
+Report any issues found: "⚠️ Preview check: {issue}. This may be cosmetic — continue or investigate?"
+
 ## Step 4: Phase 3 — FOUNDATION REVIEW
 
 Present a summary of what the foundations phase produced:
@@ -169,6 +196,21 @@ Present a summary of what the foundations phase produced:
 Use `AskUserQuestion`: "Foundations look good? Continue building screens, or review first?"
 - **Continue** → proceed to Step 5
 - **Review first** → pause, let user inspect, resume when ready
+- **Adjust** → user requests changes (colors, typography, spacing, etc.)
+
+### 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-pattern-architect` agent to update brand patterns:
+   - Pass: the specific changes made (what tokens/values changed, old → new)
+   - Pass: `{BRAND_PATH}/patterns/tokens.json` and relevant identity chunks
+   - Agent updates tokens.json, foundation chunks, and style preset YAML if applicable
+   - Agent writes to `{BRAND_PATH}/` — the brand source of truth
+   - Run in background (`run_in_background: true`) so the build pipeline continues
+4. Continue to Step 5 without waiting for brand sync
 
 ## Step 5: Phase 4 — SCREENS
 
@@ -179,7 +221,7 @@ Build screens sequentially. For each screen in `SCREENS`:
 | File | Purpose |
 |------|---------|
 | `{PROJECT_PATH}/design/screen-{NN}-{name}.md` | This screen's design chunk |
-| Referenced component chunks from `{BRAND_PATH}/system/components/` | Only components referenced in this screen's chunk |
+| Referenced component chunks from `{BRAND_PATH}/patterns/components/` | Only components referenced in this screen's chunk |
 | `{PROJECT_PATH}/brief/target-adaptations.md` | Component adaptations |
 | `{PROJECT_PATH}/research/reference-specs.md` (if exists) | Technical specs |
 | `{PROJECT_PATH}/critique/prioritized-fixes.md` (if exists) | Critique fixes relevant to this screen |
@@ -200,6 +242,7 @@ Build screens sequentially. For each screen in `SCREENS`:
 > 4. Do NOT modify foundation files (global CSS, layout, tokens, theme provider)
 > 5. Write code directly to the codebase, not to `.design/`
 > 6. Leave changes unstaged
+> 7. The brand's visual effects were implemented as utilities during foundations — use those utilities/classes rather than re-reading the brand style document
 >
 > After completing this screen, append to `{PROJECT_PATH}/build/BUILD-LOG.md` — add this screen's files and status to the existing log.
 
@@ -213,6 +256,53 @@ After each screen agent completes, run the build command.
 - **Skip** → mark screen as `partial` in BUILD-LOG, continue
 - **Stop** → halt pipeline, save progress
 
+## Step 5.5: Component extraction checkpoint
+
+After all screens complete, audit the codebase for duplicated patterns before review.
+
+### Automated scan
+
+Run these checks in the built codebase:
+
+1. **Duplicated Tailwind class clusters** — Use Grep to find identical `className` strings (>3 classes) appearing in 2+ files. These are extraction candidates.
+2. **Inline color/spacing values** — Grep for hardcoded hex colors, rgb(), pixel values that should be tokens. Flag any that don't reference CSS variables or Tailwind tokens.
+3. **Repeated component patterns** — Look for similar JSX structures across screen files (e.g., similar card layouts, repeated list items, identical button groups).
+
+### Surface proposals
+
+Present findings to the user as a numbered list:
+
+```
+  ◆ extraction candidates
+
+    1. Card pattern in 3 screens (landing, changelog-list, dashboard)
+       className="rounded-lg border bg-card p-6 shadow-sm"
+       → extract to <Card> component
+
+    2. Hardcoded colors in 2 files
+       text-[#FF6B35] in hero.tsx, cta.tsx
+       → use text-brand-accent token
+
+    3. Badge pattern in changelog-list, changelog-post
+       → extract to <Badge> component
+
+  ──────────────────────────────
+```
+
+Use `AskUserQuestion`: "Apply these extractions, skip, or cherry-pick?"
+- **Apply all** → make the changes inline (no agent spawn needed, these are mechanical refactors)
+- **Cherry-pick** → apply selected ones
+- **Skip** → continue to finalize
+
+This step is **not auto-applied** — the user decides what to extract.
+
+### Brand feedback on extraction
+
+If the extraction scan finds hardcoded values that should be tokens (finding type #2), and those tokens are missing from the brand system:
+
+1. After applying fixes in the project, ask: "These token gaps also exist in the brand. Update brand patterns?"
+2. If yes, spawn a background `gsp-pattern-architect` agent with the missing token definitions to add them to `{BRAND_PATH}/patterns/tokens.json` and relevant foundation chunks.
+
 ## Step 6: Finalize
 
 After all screens complete (or pipeline stops):
@@ -251,24 +341,7 @@ Update `{PROJECT_PATH}/STATE.md`:
 
 ### Phase transition output
 
-```
-  ◆ build complete — code implemented
-
-    build/
-    ├── SCAFFOLD-LOG.md
-    ├── BUILD-LOG.md
-    └── INDEX.md
-
-    Screens: {done}/{total}
-    Build: compiles ✓
-
-  ──────────────────────────────
-```
-
-Then use `AskUserQuestion` with 3 options:
-- **Continue to review** — "QA validate implementation against designs"
-- **View progress** — "see the full dashboard"
-- **Done for now** — "pick up later with /gsp:start"
+Render phase transition (see `references/phase-transitions.md`). Include screen count and build status in the output.
 
 ---
 
@@ -278,5 +351,14 @@ For `implementation_target: figma`, skip the phased pipeline. Spawn a single `gs
 
 ## Step 8: Revision mode
 
-For `needs-revision` status, spawn a single `gsp-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. Then continue from Step 6 (finalize).
+For `needs-revision` status, spawn a single `gsp-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.
+
+### 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-pattern-architect` agent with the changed values to update `{BRAND_PATH}/patterns/`.
+
+Then continue from Step 6 (finalize).
 </process>