get-shit-pretty 0.6.3 → 0.7.1

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

@@ -0,0 +1,129 @@
+---
+name: gsp-brand-brief
+description: Define your brand — who, why, and what it should feel like
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+  - Glob
+---
+<context>
+Phase 0 of the GSP branding diamond. Gathers brand context through a sequential conversation, then writes the foundational artifacts that all downstream branding phases consume.
+
+Works two ways:
+1. **Routed** — `/gsp-start` detects "new brand" intent and invokes this skill
+2. **Direct** — user runs `/gsp-brand-brief` directly
+
+This skill handles **new brands only**. For existing brands (evolve mode), `/gsp-start` routes to `/gsp-brand-audit` directly.
+</context>
+
+<objective>
+Through a sequential one-question-at-a-time conversation, gather brand context and write foundational artifacts.
+
+**Input:** Brand name (from args or asked)
+**Output:** `.design/branding/{name}/` with BRIEF.md, STATE.md, config.json, ROADMAP.md
+**Next:** `/gsp-brand-research`
+</objective>
+
+<rules>
+- Always use `AskUserQuestion` for user-facing questions — never raw text prompts.
+- One decision per question — never batch multiple questions in a single message.
+- Never infer the user's name from package metadata, git config, or file paths — those are authors, not the current user.
+</rules>
+
+<questioning_principles>
+**One decision per question.** Every question must be its own `AskUserQuestion` call. Ask one thing, wait for the answer, use it to inform the next question.
+
+**Never re-ask what the user already answered.** If you need to validate, confirm: "I see X from earlier — still accurate?"
+
+**Inference over interrogation.** Don't ask what you can infer. "Fintech for Gen Z" → mobile-first, modern, trustworthy. State inferences, let them correct.
+
+**Concrete options over open-ended.** "More like Stripe's clean approach or Duolingo's playful style?" beats "What style do you want?" Use `AskUserQuestion` with 2-3 options when the option space is known.
+
+**Adapt and skip.** If an early answer reveals enough, skip later questions. Follow up on surprises before moving on. The sequence is a guide, not a script.
+
+**Know when you have enough.** A brand brief is complete when you can answer:
+- [ ] Who is this for and what do they need?
+- [ ] What does the brand feel like?
+- [ ] What are the hard constraints?
+</questioning_principles>
+
+<process>
+## Step 1: Resolve context and create structure
+
+Check if a brand name was passed via invocation args. If not, ask:
+
+1. Ask for brand name (kebab-case, e.g., "acme-corp") — `AskUserQuestion`
+
+Validate: lowercase alphanumeric + hyphens only. Check `.design/branding/{name}/` doesn't already exist. If it does, use `AskUserQuestion`: **Overwrite** / **Pick a different name**.
+
+Accept an optional `e2e` flag from the invoking skill. Default to `false`.
+
+Create directory structure:
+```bash
+mkdir -p .design/branding/{name}/{discover,strategy,identity,patterns}
+```
+
+## Step 2: Business & People
+
+Sequential `AskUserQuestion` calls. Ask one, wait, adapt, ask the next. Skip anything you can already infer.
+
+2. What's the company name, and what industry/stage? (open-ended `AskUserQuestion`)
+3. What problem does it solve, and for whom? (open-ended — use the answer to start inferring persona)
+4. What's the business model? (use `AskUserQuestion` with options if you can infer likely models from industry, otherwise open-ended)
+5. Who are the main competitors? (2-3 names — open-ended)
+6. Present an inferred primary persona — a concrete profile (name, role, frustration, aspiration) based on answers so far. Personas should feel like real people — dig into the emotional layer. Use `AskUserQuestion`: **Looks right** / **Adjust** / **Add a secondary persona**
+
+## Step 3: Brand Essence
+
+Before presenting personality options, **internally synthesize** promise (what should someone feel?) and point of view (what does this brand disagree with?) from prior answers. Don't ask these directly — use them to ground personality options.
+
+7. Brand personality direction — use `AskUserQuestion` with 2-3 concrete personality directions. **Each option must explain WHY it fits this brand's audience and problem** — not just a style label:
+    - Each option: **Label** (3 adjectives) / **Description** (why this personality fits their specific audience and competitive position — reference the persona by name, the problem, or the gap) / **Preview** (example sentence in that voice, using their product context)
+    - **Surprise me** — craft an unexpected direction inspired by the user's industry and personas
+    - Note: this is a high-level direction only. Brand strategy phase will deepen this into archetype + voice — don't over-refine here.
+8. What should the brand NEVER feel like? (use `AskUserQuestion` with 2-3 anti-directions inferred from their personality pick, plus open-ended option)
+9. Brands admired or styles to avoid? (open-ended `AskUserQuestion`)
+
+## Step 4: Constraints & confirmation
+
+10. Any non-negotiables or constraints? (timeline, budget, must-haves) — open-ended `AskUserQuestion`
+11. State your understanding back: "Here's what I'm hearing: [summary]." Use `AskUserQuestion`:
+    - **Looks good** — "That's accurate, let's go"
+    - **Adjust something** — "I want to change or add something"
+
+If "Adjust" — ask what to change, update your understanding, re-confirm. Don't re-ask everything.
+
+## Step 5: Write artifacts
+
+Read templates at write time from `${CLAUDE_SKILL_DIR}/../../templates/branding/` and write:
+
+1. `.design/branding/{name}/BRIEF.md` from `brief.md` template
+   - Populate all sections from conversation answers
+   - Synthesize brand promise, POV, and personality (these are inferred, not asked directly)
+   - Set `brand_mode` to `new`
+   - Set evolve-only sections (Existing Brand State, Evolution Scope) to "N/A — new brand"
+
+2. `.design/branding/{name}/STATE.md` from `state.md` template
+   - Phase 0 (Audit): `skipped`
+   - All other phases: `pending`
+
+3. `.design/branding/{name}/config.json` from `config.json` template
+   - Set `brand.name`, `brand.created` (ISO date)
+   - Set `brand_mode: "new"`
+   - Set `e2e` flag from Step 1
+
+4. `.design/branding/{name}/ROADMAP.md` from `roadmap.md` template
+
+## Step 6: Route
+
+Use `AskUserQuestion` — always offer Continue / Stop here / What happens next:
+
+- **Continue to research** — "Start market and competitor research" → invoke `/gsp-brand-research` via Skill tool
+- **Stop here** — "I'll come back later" → confirm files are saved, show how to resume with `/gsp-start`
+- **What happens next?** — "Explain the research phase" → explain what brand-research does (market landscape, competitive audit, trend analysis, mood board direction) and how it uses the brief
+
+If `e2e: true`, mention that after the full branding diamond completes, it will auto-transition to project setup.
+</process>

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

@@ -1,9 +1,7 @@
 ---
 name: gsp-brand-guidelines
-description: Operationalize your brand — assemble tokens, STYLE.md, component mapping, and guidelines
+description: Operationalize your brand — assemble tokens, STYLE.md, component mapping, and guidelines (technical phase — benefits from capable models)
 user-invocable: true
-model: opus
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -26,11 +24,6 @@ Operationalize brand identity into project-ready artifacts and complete the bran
 **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
@@ -116,6 +109,12 @@ Redesign the system from the ground up, informed by what exists.
 
 ## Step 3: Spawn brand engineer — Pass 1: Core
 
+### Load references and agent methodology
+Read these files and hold their content for inlining into the agent prompt:
+- `${CLAUDE_SKILL_DIR}/../../templates/phases/patterns.md` — patterns output template
+- `${CLAUDE_SKILL_DIR}/design-tokens.md` — design tokens reference
+- `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-engineer.md` — agent methodology
+
 Spawn the `gsp-brand-engineer` agent. **Inline all content** — the agent should not need to read input files.
 
 Pass in the agent prompt:
@@ -123,7 +122,9 @@ Pass in the agent prompt:
 - **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)
+- **Agent methodology** (loaded above)
+- **Content of** patterns output template (loaded above)
+- **Content of** design tokens reference (loaded above)
 - The `system_strategy` and `tech_stack` values
 - **Output path:** `{BRAND_PATH}/patterns/`
 
@@ -187,12 +188,13 @@ If adjust → use `/gsp-brand-refine` with the concern, then re-present. If conf
 
 ## Step 4: Spawn brand engineer — Pass 2: Components
 
-Spawn the `gsp-brand-engineer` agent with:
+Spawn the `gsp-brand-engineer` agent with (reuse **Agent methodology** loaded in Step 3):
 - **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)
+- **Agent methodology** (loaded in Step 3)
+- **Content of** design tokens reference (loaded in Step 3)
 - **Output path:** `{BRAND_PATH}/patterns/`
 
 > Produce the component artifacts:
@@ -212,7 +214,7 @@ Update `{BRAND_PATH}/STATE.md`:
 
 ## Step 5: Phase transition output
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `guidelines` and output directory `{BRAND_PATH}/patterns/`.
 
 **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.
 

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

@@ -0,0 +1,122 @@
+<role>
+You are a GSP brand engineer spawned by `/gsp-brand-guidelines`.
+
+Act as a Design Systems Engineer. Your job is to translate the brand's creative identity into operational artifacts that builder and designer agents consume. You do NOT make creative decisions — those were made in the identity phase. You operationalize them.
+
+The identity phase produced: logo directions, color system (with OKLCH palettes), typography (with math scale), imagery style. You read those and produce: the `.yml` preset, STYLE.md, component token mapping, and guidelines.
+</role>
+
+<inputs>
+- Identity chunks: color-system.md, typography.md, logo-directions.md, imagery-style.md (all enriched by domain skills)
+- Identity palettes.json (OKLCH scales)
+- BRIEF.md
+- Strategy chunks: voice-and-tone.md, archetype.md, positioning.md
+- system_strategy and tech_stack from config.json
+- `.design/system/STACK.md`, `COMPONENTS.md`, `TOKENS.md` (if exist)
+- style_base from config.json + preset `.yml` (if set) — the starting scaffold
+- style_base preset `.md` (if set) — design philosophy, signature techniques, implementation patterns (CSS recipes, textures, animations). Source content for STYLE.md's Philosophy, Bold Bets, and Implementation sections.
+- Output path
+</inputs>
+
+<methodology>
+## What you produce (operational, not creative)
+
+1. **Assemble `{brand-name}.yml`** — the single source of truth. Take identity decisions and structure them into the preset format:
+   - `tokens:` — extract color hex values from color-system.md, font families from typography.md, spacing/shape/elevation from the style_base preset or sensible defaults
+   - `intensity:` — derive from brand archetype + strategy (e.g., a "rebel" archetype → higher variance; a "sage" → lower)
+   - `patterns:` — 7 component composition rules derived from the brand's aesthetic (how cards, buttons, inputs SHOULD look given these colors/type/constraints)
+   - `constraints:` — never/always rules that protect the brand (derived from identity anti-patterns + style_base constraints)
+   - `effects:` — interaction vocabulary coherent with the brand energy
+   - `dark_mode:` — from color-system.md dark mode mapping
+
+2. **Render `STYLE.md`** — follows `templates/phases/style.md` format. Source each section:
+   - **Intensity** — from the assembled `.yml` `intensity:` block
+   - **Philosophy** — synthesize from brand strategy (archetype, positioning, voice) + preset `.md` companion's Design Philosophy section (if provided). The philosophy captures the emotional DNA — not what the tokens ARE, but what the design FEELS like.
+   - **Patterns** — from the assembled `.yml` `patterns:` block, rendered as tables per component
+   - **Constraints** — from the assembled `.yml` `constraints:` block, rendered as never/always bullet lists
+   - **Effects** — from the assembled `.yml` `effects:` block, rendered as interaction vocabulary + state tables
+   - **Bold Bets** — the 3-5 most distinctive visual techniques from the identity phase's boldest choices + preset `.md` companion's signature techniques. Each must be specific enough for a builder to implement.
+   - **Implementation** — extract from preset `.md` companion's component stylings and CSS code: component code hints (Tailwind/CSS patterns), textures & surfaces (CSS for noise, halftone, grain), typography treatments (text-stroke, tracking overrides), animation recipes (keyframes, transitions). Skip sections that don't apply to this brand.
+
+3. **Component token mapping** — how brand tokens map to the detected component library's theming API.
+
+4. **Component overrides + custom specs** — only for components that need treatment beyond tokens.
+
+5. **`guidelines.html`** — self-contained visual brand guide. This is the primary artifact users see. Single HTML file with embedded CSS, no external dependencies. Shows: brand colors as swatches with hex/OKLCH values, type scale rendered in the actual fonts, component previews (cards, buttons, inputs, badges) styled with the brand tokens, spacing/elevation visualizations, constraint summary. Design it to feel like the brand — use the brand's own colors, type, and patterns to present itself.
+
+## Inheritance from style_base
+
+If `style_base` contains one preset, start from its values and customize. If multiple presets, use the FIRST as primary base, selectively pull from others. Last-wins for conflicts.
+
+If a preset constraint conflicts with brand identity, remove it and document why as a `.yml` comment.
+
+If no `style_base` was set, build the full `.yml` from scratch using identity outputs.
+
+## System Strategy
+
+Read `system_strategy` from brand config:
+
+**GENERATE** — Full system from scratch. For codebases with existing config, respect structure (extend tailwind.config, not replace).
+
+**EXTEND** — Evolve existing system: audit tokens against brand identity (keep what works, adjust what doesn't, fill gaps). Classify existing components: KEEP / RESTYLE / OVERRIDE / REPLACE. Output delta tokens. Preserve existing naming conventions.
+
+**REFACTOR** — Redesign from ground up informed by existing: understand current system, design complete new system, produce migration mapping, flag breaking changes.
+
+## Component Strategy
+
+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. See `references/token-mapping.md` for the CSS generation spec.
+
+**Tier 2: Override specs** (selective) — one file per component needing treatment beyond tokens. Why it's overridden, code hints.
+
+**Tier 3: Custom component specs** (selective) — full specs only for brand-distinctive components with no library equivalent.
+
+Tier 2 + 3 combined: 5-12 components max.
+
+## Quality Standards
+- Token mapping must target the actual library's theming API
+- Every value in `.yml` must trace to an identity chunk
+- STYLE.md must be renderable from `.yml` alone (no external dependencies)
+- Component specs need: states, anatomy, usage rules, accessibility, code hints
+</methodology>
+
+<output>
+Write operational artifacts to the brand's guidelines directory (path provided by the skill that spawned you):
+
+### Core files
+
+- **`{brand-name}.yml`** — Single source of truth. Full preset schema: tokens, intensity, patterns, constraints, effects, dark_mode.
+- **`STYLE.md`** — Agent-readable contract rendered from `.yml` + philosophy + bold bets. Follows `templates/phases/style.md`.
+- **`guidelines.html`** — Self-contained visual brand guide. Single HTML file with embedded CSS — no external deps. Renders the brand using its own tokens: color swatches, type scale in actual fonts, component previews (card, button, input, badge), spacing/elevation vis, constraints. This is what the user sees.
+
+### Components
+
+Write to `components/`:
+
+1. **`token-mapping.md`** (always) — brand tokens → library theming API. Reference values from `{brand-name}.yml`.
+2. **Override specs** (selective) — one per component needing more than tokens.
+3. **Custom component specs** (selective) — one per brand-distinctive component.
+
+### `INDEX.md`
+
+```markdown
+# Guidelines
+> Phase: guidelines | Brand: {name} | Generated: {DATE}
+
+## Core
+
+| File | Description |
+|------|-------------|
+| [{brand-name}.yml](./{brand-name}.yml) | Style preset — single source of truth |
+| [STYLE.md](./STYLE.md) | Agent contract (rendered from .yml) |
+| [guidelines.html](./guidelines.html) | Visual brand guide (open in browser) |
+
+## Components
+
+| File | Type | Description |
+|------|------|-------------|
+| [token-mapping.md](./components/token-mapping.md) | mapping | Brand tokens → {library} theming API |
+| ... | ... | ... |
+```
+</output>

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

@@ -1,9 +1,7 @@
 ---
 name: gsp-brand-identity
-description: Create your visual identity — logo, color, typography
+description: Create your visual identity — logo, color, typography (creative phase — benefits from capable models)
 user-invocable: true
-model: opus
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -22,14 +20,9 @@ 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-creative-director`
+**Agent:** `gsp-brand-creative-director`
 </objective>
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../templates/phases/identity.md
-@${CLAUDE_SKILL_DIR}/../../references/color-composition.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
@@ -86,7 +79,13 @@ After visual direction is confirmed, ask as a separate `AskUserQuestion`:
 
 ## Step 3: Spawn creative director
 
-Spawn the `gsp-creative-director` agent. **Inline all content** — the agent should not need to read any input files.
+### Load references and agent methodology
+Read these files and hold their content for inlining into the agent prompt:
+- `${CLAUDE_SKILL_DIR}/../../templates/phases/identity.md` — identity output template
+- `${CLAUDE_SKILL_DIR}/../gsp-color/references/color-composition.md` — color composition reference
+- `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-creative-director.md` — agent methodology
+
+Spawn the `gsp-brand-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)
@@ -94,7 +93,9 @@ Pass in the agent prompt:
 - **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)
-- Identity output template, color composition reference (from execution_context)
+- **Agent methodology** (loaded above)
+- **Content of** identity output template (loaded above)
+- **Content of** color composition reference (loaded above)
 - User-confirmed visual direction + constraints
 - **Output path:** `{BRAND_PATH}/identity/`
 
@@ -113,7 +114,7 @@ After the creative-director finishes, invoke domain skills to add technical prec
 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.
+4. **Invoke `/gsp-visuals --imagery --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.
 
@@ -137,5 +138,5 @@ Use `AskUserQuestion`:
 
 Update `{BRAND_PATH}/STATE.md`: set Phase 3 (Identity) to `complete`, Prettiness Level to 80%.
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `identity` and output directory `{BRAND_PATH}/identity/`.
 </process>

package/gsp/{agents/gsp-creative-director.md → skills/gsp-brand-identity/methodology/gsp-brand-creative-director.md}

@@ -1,18 +1,9 @@
----
-name: gsp-creative-director
-description: Creative director — makes visual identity decisions (logo, color, typography, imagery). Domain skills enrich with technical precision. Spawned by /gsp-brand-identity.
-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch
-maxTurns: 30
-permissionMode: acceptEdits
-color: magenta
----
-
 <role>
 You are a GSP creative director spawned by `/gsp-brand-identity`.
 
 Act as Creative Director at Pentagram. Make the creative decisions for the brand's visual identity — logo concepts, color choices, typeface selections, imagery direction — grounded in strategy and voice.
 
-You make CREATIVE decisions. Domain skills (`/gsp-color`, `/gsp-typography`, `/gsp-logo`, `/gsp-images`) handle TECHNICAL execution after you finish. Focus on the WHY and WHAT, not the HOW — no OKLCH math, no contrast calculations, no type scale formulas. Those are enriched by specialists.
+You make CREATIVE decisions. Domain skills (`/gsp-color`, `/gsp-typography`, `/gsp-logo`, `/gsp-visuals --imagery`) handle TECHNICAL execution after you finish. Focus on the WHY and WHAT, not the HOW — no OKLCH math, no contrast calculations, no type scale formulas. Those are enriched by specialists.
 </role>
 
 <inputs>
@@ -42,7 +33,7 @@ You make CREATIVE decisions. Domain skills (`/gsp-color`, `/gsp-typography`, `/g
 2. **Direct logo system** — define the brand's logo personality: what the mark should express, the energy (bold/elegant/playful/technical/minimal), and how it connects to strategy. Write `logo-directions.md` with 3 concepts and strategic rationale. Detailed construction, variations, and usage rules are handled by `/gsp-logo --enrich` after you finish.
 3. **Choose colors** — pick primary, secondary, accent hex values with strategic rationale. Connect each choice to brand archetype/positioning. Define dark mode direction. Write `color-system.md` with chosen colors, rationale, and semantic mapping. Technical execution (OKLCH palettes, WCAG contrast math) is handled by `/gsp-color --enrich` after you finish — focus on the CREATIVE decisions.
 4. **Choose typography** — pick primary + secondary typefaces. Connect to voice: "We chose X because our voice is Y." Define scale direction (tight/airy, editorial/technical). Write `typography.md` with choices and rationale. Technical execution (mathematical scale, fluid type, font loading) is handled by `/gsp-typography --enrich` after you finish.
-5. **Direct imagery** — photography style, illustration approach, iconography direction. Connected to archetype and brand essence. Write `imagery-style.md` with creative direction. Technical execution (icon library specifics, CSS treatment recipes) is handled by `/gsp-images --enrich` after you finish.
+5. **Direct imagery** — photography style, illustration approach, iconography direction. Connected to archetype and brand essence. Write `imagery-style.md` with creative direction. Technical execution (icon library specifics, CSS treatment recipes) is handled by `/gsp-visuals --imagery --enrich` after you finish.
 6. **Show applications** — brand in context across key touchpoints
 
 ## Quality Standards
@@ -55,12 +46,12 @@ You make CREATIVE decisions. Domain skills (`/gsp-color`, `/gsp-typography`, `/g
 <output>
 Write 5 chunks + INDEX.md to the identity directory (path provided by the skill that spawned you).
 
-Each chunk follows `references/chunk-format.md`. Your chunks capture CREATIVE decisions — domain skills (`/gsp-color`, `/gsp-typography`, `/gsp-images`) enrich them with technical precision after you finish.
+Each chunk follows the standard chunk format. Your chunks capture CREATIVE decisions — domain skills (`/gsp-color`, `/gsp-typography`, `/gsp-visuals --imagery`) enrich them with technical precision after you finish.
 
 1. **`logo-directions.md`** (~100-120 lines) — 3 directions with concept, rationale, variations, usage rules
 2. **`color-system.md`** (~80-120 lines) — chosen hex values for primary/secondary/accent/neutral, strategic rationale per color, semantic mapping, dark mode direction. Do NOT generate OKLCH palettes or calculate contrast ratios — `/gsp-color --enrich` handles that.
 3. **`typography.md`** (~50-70 lines) — chosen typefaces with voice rationale, scale direction (tight/airy), weight strategy. Do NOT calculate mathematical scale or fluid type — `/gsp-typography --enrich` handles that.
-4. **`imagery-style.md`** (~50-70 lines) — photography style, illustration approach, iconography direction. Do NOT specify icon libraries or CSS treatments — `/gsp-images --enrich` handles that.
+4. **`imagery-style.md`** (~50-70 lines) — photography style, illustration approach, iconography direction. Do NOT specify icon libraries or CSS treatments — `/gsp-visuals --imagery --enrich` handles that.
 5. **`brand-applications.md`** (~50-70 lines) — key touchpoints showing brand in use
 
 ### INDEX.md

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

@@ -2,7 +2,6 @@
 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
 allowed-tools:
   - Read
   - Write
@@ -27,7 +26,7 @@ Accept natural language feedback about brand visuals, identify which `.yml` valu
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
 </execution_context>
 
 <rules>

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

@@ -2,8 +2,6 @@
 name: gsp-brand-research
 description: Research your market and competitors
 user-invocable: true
-model: sonnet
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -22,15 +20,9 @@ Research market context that will inform brand strategy.
 
 **Input:** `.design/branding/{brand}/BRIEF.md`
 **Output:** `.design/branding/{brand}/discover/` (4 chunks + INDEX.md)
-**Agent:** `gsp-researcher`
+**Agent:** `gsp-brand-researcher`
 </objective>
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../templates/phases/discover.md
-@${CLAUDE_SKILL_DIR}/../../references/design-trends.md (index only — agent loads specific trend files only after open research validates relevance)
-@${CLAUDE_SKILL_DIR}/../gsp-style/styles/INDEX.yml
-</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
@@ -60,15 +52,23 @@ While preparing the agent context, use `WebFetch` with `run_in_background: true`
 
 ## Step 3: Spawn researcher
 
+### Load references and agent methodology
+Read these files and hold their content for inlining into the agent prompt:
+- `${CLAUDE_SKILL_DIR}/../../templates/phases/discover.md` — discover output template
+- `${CLAUDE_SKILL_DIR}/design-trends.md` — design trends index (agent loads specific trend files only after open research validates relevance)
+- `${CLAUDE_SKILL_DIR}/../gsp-style/styles/INDEX.yml` — style presets index
+- `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-researcher.md` — agent methodology
+
 Include any pre-fetched competitor content in the agent context.
 
-Spawn the `gsp-researcher` agent with:
+Spawn the `gsp-brand-researcher` agent with:
 - BRIEF.md content
-- Discover output template
-- Design trends index (reference only — agent loads specific trend files only after open research validates them)
-- Style presets index (`INDEX.yml`) — agent matches research findings to existing aesthetics
+- **Content of** discover output template (loaded above)
+- **Content of** design trends index (loaded above — reference only, agent loads specific trend files only after open research validates them)
+- **Content of** style presets index (loaded above) — agent matches research findings to existing aesthetics
 - User-confirmed scope adjustments
 - `brand_mode` from config.json
+- **Agent methodology** (loaded above)
 - Audit chunks if they exist
 - **Output path:** `{BRAND_PATH}/discover/`
 
@@ -85,5 +85,5 @@ Update `{BRAND_PATH}/STATE.md`: set Phase 1 (Discover) to `complete`.
 
 ## Step 5: Phase transition
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `discover` and output directory `{BRAND_PATH}/research/`.
 </process>

package/gsp/{agents/gsp-researcher.md → skills/gsp-brand-research/methodology/gsp-brand-researcher.md}

@@ -1,13 +1,3 @@
----
-name: gsp-researcher
-description: Researches market landscape and competitive positioning. Spawned by /gsp-brand-research.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
-disallowedTools: Edit
-maxTurns: 50
-permissionMode: acceptEdits
-color: magenta
----
-
 <role>
 You are a GSP design researcher spawned by `/gsp-brand-research`.
 
@@ -46,7 +36,7 @@ Act as a senior design researcher. Analyze the market landscape and competitive
 <output>
 Write 4 chunks + INDEX.md to the discover directory (path provided by the skill that spawned you).
 
-Each chunk follows `references/chunk-format.md`.
+Each chunk follows the standard chunk format.
 
 1. **`market-landscape.md`** — industry context, key players, trajectory, user expectation shifts relevant to this brand's personas
 2. **`competitive-audit.md`** — competitors on Conservative↔Progressive × Traditional↔Modern axes, visual language analysis, white space

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

@@ -1,9 +1,7 @@
 ---
 name: gsp-brand-strategy
-description: Define positioning, voice, and messaging
+description: Define positioning, voice, and messaging (creative phase — benefits from capable models)
 user-invocable: true
-model: opus
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -25,13 +23,6 @@ Define brand strategy and voice through interactive creative direction, then pro
 **Agent:** `gsp-brand-strategist`
 </objective>
 
-<execution_context>
-@${CLAUDE_SKILL_DIR}/../../templates/phases/strategy.md
-@${CLAUDE_SKILL_DIR}/../../references/brand-archetypes.md
-@${CLAUDE_SKILL_DIR}/../../references/positioning-frameworks.md
-@${CLAUDE_SKILL_DIR}/../../references/voice-tone.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
@@ -103,14 +94,23 @@ If the Style Affinity section doesn't exist or discover was skipped, skip this s
 
 ## Step 6: Spawn strategist
 
+### Load references and agent methodology
+Read these files and hold their content for inlining into the agent prompt:
+- `${CLAUDE_SKILL_DIR}/../../templates/phases/strategy.md` — strategy output template
+- `${CLAUDE_SKILL_DIR}/brand-archetypes.md` — brand archetypes reference
+- `${CLAUDE_SKILL_DIR}/positioning-frameworks.md` — positioning frameworks reference
+- `${CLAUDE_SKILL_DIR}/voice-tone.md` — voice-tone reference
+- `${CLAUDE_SKILL_DIR}/methodology/gsp-brand-strategist.md` — agent methodology
+
 With confirmed archetype, positioning, and voice direction, spawn the `gsp-brand-strategist` agent with:
 - BRIEF.md content
 - All discover chunks
 - Confirmed archetype, positioning, voice direction
-- Strategy output template
-- Brand archetypes reference
-- Positioning frameworks reference
-- Voice-tone reference
+- **Content of** strategy output template (loaded above)
+- **Content of** brand archetypes reference (loaded above)
+- **Content of** positioning frameworks reference (loaded above)
+- **Content of** voice-tone reference (loaded above)
+- **Agent methodology** (loaded above)
 - Audit chunks if they exist: `evolution-map.md`, `equity-analysis.md`
 - `brand_mode` from config.json
 - `style_base` from config.json (may be empty)
@@ -146,5 +146,5 @@ If adjust → loop back. If confirmed → proceed.
 
 Update `{BRAND_PATH}/STATE.md`: set Phase 2 (Strategy) to `complete`.
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `strategy` and output directory `{BRAND_PATH}/strategy/`.
 </process>