get-shit-pretty 0.6.2 → 0.6.3

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

@@ -0,0 +1,233 @@
+---
+name: gsp-brand-guidelines
+description: Operationalize your brand — assemble tokens, STYLE.md, component mapping, and guidelines
+user-invocable: true
+model: opus
+effort: high
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Agent
+  - Grep
+  - Glob
+---
+<context>
+Phase 4 of the GSP branding diamond. Transforms the brand identity into operational artifacts that designer and builder agents consume — the `.yml` preset (source of truth), STYLE.md (agent contract), component token mapping, and `guidelines.html` (what the user sees).
+
+Identity made the creative decisions. This phase makes them work in code.
+</context>
+
+<objective>
+Operationalize brand identity into project-ready artifacts and complete the branding diamond.
+
+**Input:** Brand identity (enriched by domain skills) + strategy + BRIEF.md
+**Output:** `{brand}/patterns/` ({brand-name}.yml, STYLE.md, guidelines.html, components/, INDEX.md)
+**Agent:** `gsp-brand-engineer`
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../templates/phases/patterns.md
+@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user-facing questions — never raw text prompts
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
+<process>
+## Step 0: Resolve brand
+
+Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
+If BRAND_PATH doesn't exist, tell the user to run `/gsp-start` first.
+
+## Step 1: Load context
+
+### Identity (chunk-first)
+
+Read `{BRAND_PATH}/identity/INDEX.md`. If it exists, load all identity chunks + `palettes.json`.
+
+If INDEX.md doesn't exist, check if identity phase is complete in brand STATE.md. If not, tell the user to complete brand identity first (run `/gsp-brand-identity`).
+
+### Strategy (selective, chunk-first)
+
+Read `{BRAND_PATH}/strategy/INDEX.md`. If it exists, load: voice-and-tone.md, archetype.md, positioning.md.
+
+### Brand context
+
+Read:
+- `{BRAND_PATH}/BRIEF.md` — business, personas, goals
+- `{BRAND_PATH}/config.json` — get `system_config.system_strategy`, `system_config.tech_stack`, `system_config.style_base`
+
+### Style base presets
+
+If `style_base` is a non-empty array, load each preset's files from `${CLAUDE_SKILL_DIR}/../gsp-style/styles/`:
+- `{preset-name}.yml` — structural scaffold (tokens + intensity + patterns + constraints + effects)
+- `{preset-name}.md` — design philosophy, bold bets, implementation patterns (CSS recipes, textures, animations)
+
+Both files are needed: the `.yml` provides the structure to inherit from, the `.md` provides the philosophy and implementation content for STYLE.md rendering.
+
+If `style_base` is empty or missing, load `${CLAUDE_SKILL_DIR}/../gsp-style/styles/professional.yml` and `professional.md` as the default format reference. The agent always needs at least one example to produce the custom style output.
+
+## Step 1.5: Codebase awareness
+
+**Always scan:** If `.design/system/` docs don't exist, invoke `/gsp-design-system` via Skill tool to scan the codebase. If they already exist, read them. Either way, load STACK.md, COMPONENTS.md, and TOKENS.md before continuing.
+
+Then ask the user (each as its own `AskUserQuestion`):
+
+1. Tech stack — if the scan detected a stack, use `AskUserQuestion`:
+   - **Yes, build on {framework} + {styling}** — "Use what's already here"
+   - **Different stack** — "I want to target a different tech stack"
+   If no stack detected, use open-ended `AskUserQuestion`: "What tech stack will this brand target?"
+   Store answer in `{BRAND_PATH}/config.json` → `system_config.tech_stack`
+
+2. System strategy — only ask if scan found existing tokens/components. Use `AskUserQuestion`:
+   - **Evolve** — "Extend the existing design system"
+   - **Rethink** — "Redesign from scratch, informed by what exists"
+   - **Ignore** — "Start fresh, don't reference the existing system"
+   Store strategy in `{BRAND_PATH}/config.json` → `system_config.system_strategy`
+   If scan found no tokens/components (greenfield/boilerplate): default to `generate`, skip this question
+
+## Step 2: Determine system strategy
+
+Read `system_config.system_strategy` from config.json (defaults to `generate` if missing).
+
+Three strategies:
+
+**GENERATE** (when `system_strategy` is `generate` or missing):
+Full system from scratch. For `boilerplate` codebases, respect existing config structure (extend tailwind.config, not replace) and output tokens in the format the existing config uses (Tailwind extend, CSS custom properties, etc).
+
+**EXTEND** (when `system_strategy` is `extend`):
+Evolve the existing system rather than replacing it.
+1. Audit existing tokens against the brand identity — keep what works, adjust what doesn't, fill gaps
+2. Classify each existing component: KEEP / RESTYLE / REFACTOR / REPLACE
+3. Design only net-new components not covered by existing ones
+4. Output delta tokens — only new and changed values
+5. Preserve existing naming conventions from `.design/system/CONVENTIONS.md`
+
+**REFACTOR** (when `system_strategy` is `refactor`):
+Redesign the system from the ground up, informed by what exists.
+1. Read and understand existing tokens, components, patterns from `.design/system/` docs
+2. Design a complete new system — same scope as GENERATE
+3. Produce a migration mapping for every change
+4. Preserve conventions unless the brand requires changes
+5. Flag breaking changes explicitly
+
+## Step 3: Spawn brand engineer — Pass 1: Core
+
+Spawn the `gsp-brand-engineer` agent. **Inline all content** — the agent should not need to read input files.
+
+Pass in the agent prompt:
+- **Content of** all identity chunks + palettes.json (loaded in Step 1)
+- **Content of** strategy chunks: voice-and-tone.md, archetype.md, positioning.md (loaded in Step 1)
+- **Content of** BRIEF.md (loaded in Step 1)
+- **Content of** style base preset `.yml` + `.md` (loaded in Step 1) — `.yml` as structural scaffold, `.md` as philosophy + implementation content for STYLE.md
+- Patterns output template, design tokens reference (from execution_context)
+- The `system_strategy` and `tech_stack` values
+- **Output path:** `{BRAND_PATH}/patterns/`
+
+> Produce the core brand artifacts ONLY:
+> 1. `{brand-name}.yml` — source of truth (tokens + intensity + patterns + constraints + effects)
+> 2. `STYLE.md` — agent contract (rendered from `.yml` + philosophy + bold bets)
+> 3. `guidelines.html` — visual brand guide (what the user sees in their browser)
+> 4. `INDEX.md` — core files only for now
+>
+> Do NOT produce component artifacts yet (token-mapping, overrides, custom specs). Those come after the user reviews the visual output.
+
+## Step 3.5: Visual review
+
+Tell the user: "Open `{BRAND_PATH}/patterns/guidelines.html` in your browser — this is your brand in one page."
+
+Present a compact summary:
+
+```
+  {brand-name} guidelines
+  ═══════════════════════════════════════
+
+    .yml preset
+      colors:     {primary}, {secondary}, {accent}
+      typography: {primary font}, {secondary font}
+      intensity:  variance {N}/10, motion {N}/10, density {N}/10
+
+    STYLE.md
+      patterns:   {N} components defined
+      constraints: {N} never, {N} always rules
+      effects:    {interaction vocabulary list}
+      bold bets:  {1-line summary of boldest bet}
+
+    → open guidelines.html in your browser to preview
+
+  ─────────────────────────────────────
+```
+
+Use `AskUserQuestion`:
+- **Looks good** — "The brand looks right, build components"
+- **Adjust tokens** — "I want to tweak colors, typography, or spacing"
+- **Adjust patterns** — "I want to change component rules or constraints"
+- **Adjust intensity** — "More/less creative, more/less motion, more/less density"
+
+If adjustments needed, use `/gsp-brand-refine` with the feedback to surgically update the `.yml`, regenerate `STYLE.md`, and regenerate `guidelines.html`. Then re-present.
+
+## Step 3.75: Perspective check
+
+Load persona profiles from `{BRAND_PATH}/BRIEF.md` and present stakeholder reactions:
+
+"Stress-testing the brand visuals:
+
+ {primary persona name}: {would this visual language feel trustworthy and appropriate?}
+ Skeptic: {are the constraints too restrictive or too loose? Is the intensity calibrated right?}
+ {top competitor}: {is the brand visually differentiated?}"
+
+Use `AskUserQuestion`:
+- **Lock it in** — "The brand is solid, build components"
+- **Adjust** — "One of these concerns resonates — I want to change something"
+
+If adjust → use `/gsp-brand-refine` with the concern, then re-present. If confirmed → proceed to components.
+
+## Step 4: Spawn brand engineer — Pass 2: Components
+
+Spawn the `gsp-brand-engineer` agent with:
+- **Content of** the confirmed `{BRAND_PATH}/patterns/{brand-name}.yml`
+- **Content of** `{BRAND_PATH}/patterns/STYLE.md`
+- **Content of** `.design/system/STACK.md`, `COMPONENTS.md`, `TOKENS.md` (when loaded in Step 1.5)
+- The `system_strategy` and `tech_stack` values
+- Design tokens reference (from execution_context)
+- **Output path:** `{BRAND_PATH}/patterns/`
+
+> Produce the component artifacts:
+> 1. `components/token-mapping.md` — brand tokens → library theming API (always)
+> 2. Component override specs (selective — only when tokens aren't enough)
+> 3. Custom component specs (selective — brand-distinctive with no library equivalent)
+> 4. Update `INDEX.md` with the components section
+>
+> The `.yml` and `STYLE.md` are confirmed — do not modify them. Focus on mapping tokens to the detected component library and specifying overrides.
+
+## Step 4.5: Update state
+
+Update `{BRAND_PATH}/STATE.md`:
+- Set Phase 4 (Patterns) status to `complete`
+- Record completion date
+- Set Prettiness Level to 100%
+
+## Step 5: Phase transition output
+
+Render phase transition (see `references/phase-transitions.md`).
+
+**E2E mode:** Read `{BRAND_PATH}/config.json`. If `e2e` is `true`, auto-invoke `/gsp-start` via Skill tool — it will detect the completed brand and route directly to project setup (Step 4). No need to ask the user.
+
+**Non-E2E:** 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.
+
+Also display a brand summary after the standard transition — this is the final branding phase:
+
+```
+  brand complete — {brand-name}
+
+    discover       {key finding}
+    strategy       {archetype}, {positioning}, {top voice attributes}
+    identity       {colors}, {typefaces}
+    guidelines     .yml + STYLE.md + {N} components + guidelines.html
+
+    open: {BRAND_PATH}/patterns/guidelines.html
+```
+</process>

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

@@ -1,5 +1,5 @@
 ---
-name: brand-identity
+name: gsp-brand-identity
 description: Create your visual identity — logo, color, typography
 user-invocable: true
 model: opus
@@ -22,11 +22,10 @@ Build the brand's visual identity.
 
 **Input:** Strategy chunks + BRIEF.md + discover/mood-board-direction.md
 **Output:** `.design/branding/{brand}/identity/` (6 chunks + palettes.json + INDEX.md)
-**Agent:** `gsp-identity-designer`
+**Agent:** `gsp-creative-director`
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../prompts/02-brand-identity-creator.md
 @${CLAUDE_SKILL_DIR}/../../templates/phases/identity.md
 @${CLAUDE_SKILL_DIR}/../../references/color-composition.md
 </execution_context>
@@ -43,12 +42,12 @@ Build the brand's visual identity.
 ## Step 0: Resolve brand
 
 Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
-If missing, tell user to run `/gsp:start` first.
+If missing, tell user to run `/gsp-start` first.
 
 ## Step 1: Validate prerequisites
 
 Read `{BRAND_PATH}/STATE.md`. Strategy (Phase 2) must be complete.
-If not: "Strategy isn't done yet. Run `/gsp:brand-strategy` first."
+If not: "Strategy isn't done yet. Run `/gsp-brand-strategy` first."
 
 Load:
 - `{BRAND_PATH}/BRIEF.md`
@@ -59,10 +58,10 @@ Load:
 ### Style base presets
 
 If `style_base` is a non-empty array, load each preset's files from `${CLAUDE_SKILL_DIR}/../gsp-style/styles/`:
-- `{preset-name}.yml` — structured tokens (palette, typography, spacing)
-- `{preset-name}.md` — design philosophy and AI prompt
+- `{preset-name}.yml` — tokens + intensity + patterns + constraints + effects (structural scaffold)
+- `{preset-name}.md` — design philosophy, signature techniques, implementation patterns (creative context)
 
-These will be passed to the identity-designer agent as the aesthetic seed.
+Both files matter: the `.yml` gives the creative-director the aesthetic rules to respect, the `.md` gives the emotional DNA and visual signatures to channel. The creative-director adapts the brand within the preset's structure — respecting intensity dials, patterns, and constraints while bringing the brand's unique personality.
 
 ## Step 2: Visual direction
 
@@ -85,28 +84,38 @@ After visual direction is confirmed, ask as a separate `AskUserQuestion`:
 - **No constraints** — "Go ahead with this direction"
 - **Add constraints** — "I have specific requirements (colors to avoid, accessibility needs, existing assets to match)"
 
-## Step 3: Spawn identity designer
+## Step 3: Spawn creative director
 
-Spawn the `gsp-identity-designer` agent. **Inline all content** — the agent should not need to read any input files.
+Spawn the `gsp-creative-director` agent. **Inline all content** — the agent should not need to read any input files.
 
 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** discover/mood-board-direction.md (loaded in Step 1)
-- **Content of** style base preset files `.yml` + `.md` (when 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)
-- Brand Identity Creator prompt (02), identity output template, color composition reference (from execution_context)
+- Identity output template, color composition reference (from execution_context)
 - User-confirmed visual direction + constraints
 - **Output path:** `{BRAND_PATH}/identity/`
 
-The agent writes 5 chunks + palettes.json + INDEX.md:
+The agent writes 5 chunks + INDEX.md (creative decisions only — no technical execution):
 1. `logo-directions.md`
-2. `color-system.md`
-3. `typography.md`
-4. `imagery-style.md`
+2. `color-system.md` (chosen colors + rationale, no OKLCH/contrast math)
+3. `typography.md` (chosen typefaces + rationale, no scale math)
+4. `imagery-style.md` (creative direction, no icon library specifics)
 5. `brand-applications.md`
-6. `palettes.json`
-7. `INDEX.md`
+6. `INDEX.md`
+
+## Step 3.5: Enrich with domain skills
+
+After the creative-director finishes, invoke domain skills to add technical precision to the creative decisions. Each skill reads the chunk the agent wrote, enriches it, and overwrites.
+
+1. **Invoke `/gsp-logo --enrich`** — reads `logo-directions.md`, enriches each direction with detailed construction geometry, complete variation specs, clear space rules, and minimum size calculations.
+2. **Invoke `/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.
+3. **Invoke `/gsp-typography --enrich`** — reads `typography.md`, generates mathematical type scale, adds fluid type formulas, enriches with font loading instructions.
+4. **Invoke `/gsp-images --enrich`** — reads `imagery-style.md`, adds icon library specifics, CSS texture/treatment recipes, enriches with technical implementation details.
+
+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

@@ -1,5 +1,5 @@
 ---
-name: brand-refine
+name: gsp-brand-refine
 description: Targeted brand adjustments mid-project — tweak colors, typography, or spacing without re-running the full branding diamond
 user-invocable: true
 model: sonnet
@@ -13,16 +13,16 @@ allowed-tools:
   - WebFetch
 ---
 <context>
-You are a GSP brand refinement skill. You take targeted feedback about brand visual issues and surgically update token values — no need to re-run strategy or identity.
+You are a GSP brand refinement skill. You take targeted feedback about brand visual issues and surgically update the brand's `.yml` preset — no need to re-run strategy or identity.
 
-This skill modifies **tokens.json** and **palettes.json** only. If the user's feedback is strategic ("make the tone more playful") or narrative ("the brand story feels off"), redirect to `/gsp:brand-strategy` or `/gsp:brand-identity`.
+This skill modifies **`{brand-name}.yml`** — the single source of truth for brand tokens, patterns, constraints, effects, and intensity. If the user's feedback is strategic ("make the tone more playful") or narrative ("the brand story feels off"), redirect to `/gsp-brand-strategy` or `/gsp-brand-identity`.
 </context>
 
 <objective>
-Accept natural language feedback about brand visuals, identify which tokens are affected, apply targeted value changes, and log what changed.
+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", "heading weight too heavy")
-**Output:** Updated `tokens.json` and/or `palettes.json` + `REFINE-LOG.md`
+**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`
 **Agent:** None — inline skill, surgical edits
 </objective>
 
@@ -43,33 +43,40 @@ Accept natural language feedback about brand visuals, identify which tokens are
 <process>
 ## Step 0: Locate brand and parse feedback
 
-Extract feedback from the user's input (everything after `/gsp:brand-refine`).
+Extract feedback from the user's input (everything after `/gsp-brand-refine`).
 
 If no feedback provided, use `AskUserQuestion`: "What would you like to adjust? (e.g., 'accent is too muted', 'heading font feels too heavy', 'spacing too tight')"
 
 Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
-Check that `{BRAND_PATH}/patterns/tokens.json` exists. If not: "No tokens found. Run `/gsp:brand-patterns` first."
+Find the brand's `.yml` file: scan `{BRAND_PATH}/patterns/` for a `.yml` file that is NOT in `foundations/` or `components/`. If not found: "No brand style found. Run `/gsp-brand-guidelines` first."
+
+Also check if `{BRAND_PATH}/patterns/STYLE.md` exists (will need regeneration after changes).
 
 ## Step 1: Read current state
 
-Read `{BRAND_PATH}/patterns/tokens.json` once. Extract all sections relevant to the feedback:
+Read the brand `.yml` once. Map feedback to the relevant section:
 
-| Feedback signals | Token section |
+| Feedback signals | `.yml` section |
 |-----------------|---------------|
-| color, accent, muted, vibrant, contrast, tint, shade, hue | `color` |
-| font, heading, body, weight, size, line-height | `typography` |
-| spacing, padding, gap, tight, loose, dense | `spacing` |
-| shadow, elevation, depth, flat | `shadow` |
-| radius, rounded, sharp, corners | `borderRadius` |
-
-Also read `{BRAND_PATH}/identity/palettes.json` if it exists and feedback involves colors.
+| color, accent, muted, vibrant, contrast, tint, shade, hue | `tokens.color` + `dark_mode.color` |
+| font, heading, body, weight, size, line-height | `tokens.typography` |
+| spacing, padding, gap, tight, loose, dense | `tokens.spacing` |
+| shadow, elevation, depth, flat | `tokens.elevation` |
+| radius, rounded, sharp, corners | `tokens.shape` |
+| motion, speed, slow, fast, bounce, snap | `tokens.motion` + `intensity.motion` |
+| creative, playful, restrained, chaos, calm | `intensity.variance` |
+| dense, airy, packed, spacious | `intensity.density` |
+| button, card, input, badge, nav | `patterns.{component}` |
+| never, always, forbidden, required | `constraints` |
+| hover, click, press, animation, effect | `effects` |
+| dark mode, dark background, dark theme, night | `dark_mode.color` (+ any section above if the feedback applies to dark mode specifically) |
 
 ## Step 2: Propose changes
 
 Show a clear before/after for each affected token:
 
 ```
-  /gsp:brand-refine
+  /gsp-brand-refine
   ═══════════════════════════════════════
 
   Feedback: "the accent is too muted"
@@ -101,7 +108,7 @@ If regenerating, call the tints.dev API:
 ```
 WebFetch: https://www.tints.dev/api/{colorName}/{hexWithoutHash}
 ```
-Parse the response for the 11-stop OKLCH scale (50–950) and update `palettes.json`.
+Parse the response for the 11-stop OKLCH scale (50–950) and update `identity/palettes.json` as a reference artifact, then update the `.yml` color tokens from the new ramp.
 
 ### Typography changes involving scale ratio
 
@@ -115,8 +122,8 @@ Use `AskUserQuestion`:
 - **Cancel** — "keep current values"
 
 Apply confirmed changes:
-1. **tokens.json** — edit values in place with `Edit`. Preserve structure.
-2. **palettes.json** — update if palette was regenerated.
+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
 
@@ -134,7 +141,7 @@ Append to `{BRAND_PATH}/REFINE-LOG.md`:
 Display summary:
 
 ```
-  /gsp:brand-refine — {n} tokens updated
+  /gsp-brand-refine — {n} tokens updated
   ═══════════════════════════════════════
 
   Updated: {list of tokens}

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

@@ -1,5 +1,5 @@
 ---
-name: brand-research
+name: gsp-brand-research
 description: Research your market and competitors
 user-invocable: true
 model: sonnet
@@ -43,7 +43,7 @@ Research market context that will inform brand strategy.
 
 Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
 
-Read `{BRAND_PATH}/BRIEF.md`. If missing, tell user to run `/gsp:start` first.
+Read `{BRAND_PATH}/BRIEF.md`. If missing, tell user to run `/gsp-start` first.
 Read `{BRAND_PATH}/config.json` for `brand_mode`.
 
 ## Step 2: Confirm research scope

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

@@ -1,5 +1,5 @@
 ---
-name: brand-strategy
+name: gsp-brand-strategy
 description: Define positioning, voice, and messaging
 user-invocable: true
 model: opus
@@ -45,7 +45,7 @@ Define brand strategy and voice through interactive creative direction, then pro
 ## Step 0: Resolve brand
 
 Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
-If missing, tell user to run `/gsp:start` first.
+If missing, tell user to run `/gsp-start` first.
 
 ## Step 1: Load context
 
@@ -65,7 +65,7 @@ Frame as: "Here's where this brand can win." Keep it to 4-6 lines.
 
 ## Step 3: Archetype selection
 
-Read the personality direction from BRIEF.md (gathered during `/gsp:start`). Use it as the starting point — don't re-ask for personality. Deepen it into a structural archetype.
+Read the personality direction from BRIEF.md (gathered during `/gsp-start`). Use it as the starting point — don't re-ask for personality. Deepen it into a structural archetype.
 
 Use `AskUserQuestion` with 2-3 archetype candidates that align with the chosen personality direction. Each option:
 - **Label:** archetype name

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

@@ -1,5 +1,5 @@
 ---
-name: brand-sync
+name: gsp-brand-sync
 description: Sync brand to match a project's shipped state — tokens, voice, visual patterns, personality
 user-invocable: true
 model: opus
@@ -17,7 +17,7 @@ allowed-tools:
 <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:
+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
@@ -49,7 +49,7 @@ Compare a project's shipped state against its source brand across all dimensions
 ## Step 0: Resolve brand and project
 
 Resolve brand from `.design/branding/` (one → use it, multiple → ask). Set `BRAND_PATH`.
-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."
+Check that the brand has at least one of: `patterns/{brand-name}.yml`, `strategy/`, `identity/`. If none exist, tell the user: "No brand system found. Run `/gsp-brand-guidelines` first."
 
 Verify the project codebase has shipped output — source files with components, copy, or styles.
 
@@ -60,7 +60,7 @@ 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)
+- `BRAND_PATH` and all available brand files ({brand-name}.yml, strategy chunks, identity chunks, foundation chunks)
 - Project codebase location (working directory)
 - **Output path:** `{BRAND_PATH}/sync/`
 
@@ -74,7 +74,7 @@ Read `{BRAND_PATH}/sync/SYNC-REPORT.md`. Present a compact summary per dimension
 - **Tokens only** — just sync the quantitative token changes
 - **Pick by dimension** — choose which dimensions to sync
 - **Review each** — walk through every divergence individually
-- **Refine manually** — run `/gsp:brand-refine` to make targeted token adjustments instead
+- **Refine manually** — run `/gsp-brand-refine` to make targeted token adjustments instead
 - **Skip** — don't update the brand
 
 If "Pick by dimension", ask per dimension. If "Review each", walk through the Update Map from the report.
@@ -85,11 +85,11 @@ For "Removed" tokens: ask whether to remove from brand or keep (may be used by o
 
 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.
+**Tokens** — edit the brand `.yml` preset in place. Regenerate affected STYLE.md sections if they exist.
 
 **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.
+**Visual patterns** — update the brand `.yml` patterns/constraints/effects blocks. Update component specs in `{BRAND_PATH}/patterns/components/` 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.
 

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

@@ -0,0 +1,105 @@
+---
+name: gsp-color
+description: Design color systems — palettes, contrast, semantic mapping, dark mode
+user-invocable: true
+model: sonnet
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+  - Glob
+  - Grep
+  - WebFetch
+---
+<context>
+You are a GSP color director. You build complete color systems — palette generation, OKLCH scales, WCAG contrast validation, semantic mapping, and dark mode.
+
+This is a standalone composable skill. It works two ways:
+1. **Standalone** — user runs `/gsp-color` directly for palette exploration and contrast checking
+2. **As a building block** — the creative-director invokes `/gsp-color --enrich` to add technical precision to creative color choices
+
+Absorbs the capabilities of the current `gsp-palette` (OKLCH generation) and the color audit mode of `gsp-accessibility` (contrast checking).
+</context>
+
+<objective>
+Build a production-ready color system from brand colors or user input.
+
+**Input:** Hex colors + brand context, OR `--enrich` mode with existing `color-system.md`
+**Output:** `color-system.md` chunk + `palettes.json` (OKLCH scales)
+**Agent:** None — inline skill, deterministic palette generation + contrast math
+</objective>
+
+<execution_context>
+@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+</execution_context>
+
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
+- Every palette gets the full 11-stop OKLCH scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
+- Color names must be semantic (primary, secondary, accent, neutral) not literal (red, blue)
+- All foreground/background pairs must report WCAG AA contrast ratios
+- Dark mode mapping must maintain equivalent contrast relationships
+</rules>
+
+<process>
+## Step 0: Determine mode
+
+| Input | Mode |
+|-------|------|
+| `/gsp-color --enrich` | Enrich existing color-system.md |
+| `/gsp-color #FF5733 #3366FF` | Generate from hex values |
+| `/gsp-color` | Interactive — explore and build |
+
+## Step 1: Enrich mode (`--enrich`)
+
+Read existing `{BRAND_PATH}/identity/color-system.md`. Extract chosen hex values and rationale.
+
+Read `references/color-composition.md` for domain expertise.
+
+Enrich the file with:
+- OKLCH 11-stop scales via tints.dev API: `https://tints.dev/api/{colorName}/{hexWithout#}`
+- WCAG AA contrast ratios for every semantic foreground/background pair
+- Semantic color mapping (error, success, warning, info)
+- Dark mode color mapping with equivalent contrast
+- Write `palettes.json` alongside color-system.md
+
+Overwrite `color-system.md` with enriched version. Preserve the creative rationale — add technical data around it.
+
+## Step 2: Interactive mode (no args)
+
+One `AskUserQuestion` at a time:
+
+1. Starting point — use `AskUserQuestion`:
+   - **I have hex values** — "I know my brand colors"
+   - **From a style preset** — "Start from a GSP preset palette"
+   - **Explore** — "Help me find the right palette"
+2. If exploring: ask about mood (warm/cool/neutral), energy (vibrant/muted/earthy), context (tech/health/luxury/etc.)
+3. Propose a palette with primary + secondary + accent + neutral, show hex swatches
+4. Confirm or iterate
+
+## Step 3: Generate palette system
+
+For each brand color (primary, secondary, accent, neutral):
+1. Call tints.dev API: `WebFetch https://tints.dev/api/{colorName}/{hexWithout#}`
+2. Parse the 11-stop OKLCH scale (50–950)
+
+Define semantic colors:
+- Map brand colors to semantic roles (primary → CTAs, secondary → supporting, accent → highlights)
+- Define standard semantic colors (error, success, warning, info)
+- Map dark mode equivalents
+
+Calculate contrast:
+- Every text/background pair → WCAG AA ratio (4.5:1 normal, 3:1 large)
+- Flag failures with suggested alternatives
+
+## Step 4: Write output
+
+Write `color-system.md` + `palettes.json` to the resolved output path.
+
+Target: 100-150 lines for color-system.md.
+
+## Step 5: Completion
+
+Display palette summary with contrast status. Offer next steps.
+</process>