get-shit-pretty 0.6.3 → 0.7.0

package/bin/install.js

@@ -1205,8 +1205,26 @@ function installLocalSymlinks(targetDir, src) {
     forceSymlink(path.join('..', '..', 'gsp', 'skills', dir.name), path.join(skillsDest, dir.name));
     skillCount++;
   }
+  // ── Dev skill symlinks (local only — not shipped in npm package) ──
+  const devSkillsSrc = path.join(cwd, 'dev', 'skills');
+  let devSkillCount = 0;
+  try {
+    if (fs.existsSync(devSkillsSrc)) {
+      for (const dir of fs.readdirSync(devSkillsSrc, { withFileTypes: true })) {
+        if (!dir.isDirectory()) continue;
+        forceSymlink(path.join('..', '..', 'dev', 'skills', dir.name), path.join(skillsDest, dir.name));
+        devSkillCount++;
+      }
+    }
+  } catch {
+    console.log(`  ${c.secondary}! Could not read dev/skills/ — skipping dev skills${c.reset}`);
+  }
+
   if (skillCount > 0) {
-    console.log(`  ${c.success}✓${c.reset} Symlinked ${skillCount} skills`);
+    const msg = devSkillCount > 0
+      ? `Symlinked ${skillCount} skills + ${devSkillCount} dev`
+      : `Symlinked ${skillCount} skills`;
+    console.log(`  ${c.success}✓${c.reset} ${msg}`);
   } else { failures.push('skills'); }
 
   // Clean up legacy commands/gsp dir (may be broken symlink)
@@ -1217,24 +1235,25 @@ function installLocalSymlinks(targetDir, src) {
     console.log(`  ${c.success}✓${c.reset} Removed legacy commands/gsp`);
   } catch {}
 
-  // ── Bundle symlinks (templates, references → runtime root) ──
+  // ── Bundle symlinks (templates → runtime root) ──
   // Clean up legacy dirs
   const legacyBundleDest = path.join(targetDir, 'get-shit-pretty');
   if (fs.existsSync(legacyBundleDest)) {
     fs.rmSync(legacyBundleDest, { recursive: true });
     console.log(`  ${c.success}✓${c.reset} Removed legacy get-shit-pretty/ bundle`);
   }
-  const legacyPrompts = path.join(targetDir, 'prompts');
-  if (fs.existsSync(legacyPrompts)) {
-    fs.rmSync(legacyPrompts, { recursive: true });
-    console.log(`  ${c.success}✓${c.reset} Removed legacy prompts/`);
+  for (const legacyDir of ['prompts', 'references']) {
+    const legacyPath = path.join(targetDir, legacyDir);
+    try {
+      fs.lstatSync(legacyPath);
+      fs.rmSync(legacyPath, { recursive: true });
+      console.log(`  ${c.success}✓${c.reset} Removed legacy ${legacyDir}/`);
+    } catch {}
   }
 
-  for (const dir of ['templates', 'references']) {
-    if (fs.existsSync(path.join(gspRoot, dir))) {
-      forceSymlink(path.join('..', 'gsp', dir), path.join(targetDir, dir));
-      console.log(`  ${c.success}✓${c.reset} Symlinked ${dir}/`);
-    }
+  if (fs.existsSync(path.join(gspRoot, 'templates'))) {
+    forceSymlink(path.join('..', 'gsp', 'templates'), path.join(targetDir, 'templates'));
+    console.log(`  ${c.success}✓${c.reset} Symlinked templates/`);
   }
 
   // Write VERSION from package.json (local dev uses repo root VERSION via symlinks)
@@ -1435,15 +1454,12 @@ function install(isGlobal, runtime = 'claude') {
     console.log(`  ${c.success}✓${c.reset} Removed legacy prompts/`);
   }
 
-  const bundleDirs = ['templates', 'references'];
-  for (const dir of bundleDirs) {
-    const dirSrc = path.join(gspRoot, dir);
-    if (fs.existsSync(dirSrc)) {
-      copyWithPathReplacement(dirSrc, path.join(targetDir, dir), pathPrefix, runtime);
-      if (verifyInstalled(path.join(targetDir, dir), dir)) {
-        console.log(`  ${c.success}✓${c.reset} Installed ${dir}/`);
-      } else { failures.push(dir); }
-    }
+  const templatesSrc = path.join(gspRoot, 'templates');
+  if (fs.existsSync(templatesSrc)) {
+    copyWithPathReplacement(templatesSrc, path.join(targetDir, 'templates'), pathPrefix, runtime);
+    if (verifyInstalled(path.join(targetDir, 'templates'), 'templates')) {
+      console.log(`  ${c.success}✓${c.reset} Installed templates/`);
+    } else { failures.push('templates'); }
   }
 
   // Write VERSION file

package/gsp/agents/gsp-accessibility-auditor.md

@@ -58,7 +58,7 @@ Write your audit as chunks to the output directory (path provided by the skill t
 
 ### Chunk files
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`accessibility-audit.md`** (~100-150 lines) — Perceivable, Operable, Understandable, Robust checklists (pass/fail per criterion with notes), Mobile accessibility, Cognitive accessibility, summary (total pass/fail/not-applicable counts, overall conformance level), accessibility statement draft
 2. **`accessibility-fixes.md`** (~50-100 lines) — Violations table (issue, severity Critical/Major/Minor, WCAG criterion, remediation steps). Only Critical and Major severity items.

package/gsp/agents/gsp-ascii-artist.md

@@ -19,7 +19,7 @@ You are a creative who happens to work in a grid of fixed-width cells. Every pie
 </role>
 
 <reference>
-@references/terminal-art.md
+@skills/gsp-art/terminal-art.md
 </reference>
 
 <methodology>

package/gsp/agents/gsp-brand-auditor.md

@@ -38,7 +38,7 @@ Assess existing brand identities — coherence, market fit, equity, evolution op
 <output>
 Write 5 chunks + INDEX.md to the audit directory (path provided by the skill that spawned you).
 
-Each chunk follows `references/chunk-format.md`.
+Each chunk follows the standard chunk format.
 
 1. **`brand-inventory.md`** — structured inventory of all current assets (logo, colors with hex, typefaces, voice samples, messaging, positioning)
 2. **`coherence-assessment.md`** — strategy coherence (1-5), strategy↔visual alignment (1-5), key disconnects

package/gsp/agents/gsp-brand-strategist.md

@@ -50,7 +50,7 @@ Act as Head of Strategy at a top branding agency. Define the strategic foundatio
 <output>
 Write 5 chunks + INDEX.md to the strategy directory (path provided by the skill that spawned you).
 
-Each chunk follows `references/chunk-format.md`.
+Each chunk follows the standard chunk format.
 
 1. **`positioning.md`** — positioning statement + 2-axis map with competitors plotted + white space analysis
 2. **`archetype.md`** — primary + secondary archetype, rationale, shadow traits, communication style, visual tendencies

package/gsp/agents/gsp-builder.md

@@ -165,7 +165,7 @@ When in **revision mode** (addressing QA issues), append a revision section:
 
 ### `build/INDEX.md`
 
-After writing BUILD-LOG.md, write `build/INDEX.md` following the standard chunk INDEX format (see `references/chunk-format.md`). Reference BUILD-LOG.md (and CODE.md + components/ in figma mode).
+After writing BUILD-LOG.md, write `build/INDEX.md` following the standard chunk INDEX format (standard chunk format). Reference BUILD-LOG.md (and CODE.md + components/ in figma mode).
 
 > **Note:** `codebase/MANIFEST.md` is written by the skill (`project-build`), not by this agent.
 

package/gsp/agents/gsp-campaign-director.md

@@ -50,7 +50,7 @@ Write your campaign as chunks to the project's launch directory (path provided b
 
 ### Chunk files
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`campaign-strategy.md`** (~50-80 lines) — Objective, audience, key message, tone, channels
 2. **`digital-ads.md`** (~80-120 lines) — Google Ads + Meta/Instagram + TikTok (all formats and A/B variants)

package/gsp/agents/gsp-creative-director.md

@@ -12,7 +12,7 @@ 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 +42,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 +55,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/agents/gsp-critic.md

@@ -104,11 +104,11 @@ The gap between "correct" and "good." Evaluate:
 - **Craft in details** — tinted shadows, considered spacing rhythm, typographic hierarchy through weight+color+spacing not just size
 - **Would someone ask "who designed this?"** — or does it look like any other product?
 
-Full scoring via `references/visual-taste.md` (15 items, X/75) — Read when you want to produce a formal taste score.
+Full scoring via `skills/gsp-project-critique/visual-taste.md` (15 items, X/75) — Read when you want to produce a formal taste score.
 
 ### Supplementary (Read from disk when needed)
 
-8. **Full anti-pattern scan** — Read `references/anti-patterns.md` for typography, color, and code quality patterns beyond the core checks above.
+8. **Full anti-pattern scan** — Read `skills/gsp-project-critique/anti-patterns.md` for typography, color, and code quality patterns beyond the core checks above.
 9. **Color composition** — Evaluate palette strategy using the inlined color-composition reference (60-30-10 rule, monochrome vs accent, warm/cool consistency).
 
 ### Synthesis
@@ -129,7 +129,7 @@ Write your critique as chunks to the project's critique directory (path provided
 
 ### Chunk files
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`critique.md`** (~120-180 lines) — Strategy evaluation, brand compliance (X/25 when STYLE.md), usability evaluation (10 heuristics scored 1-5, total X/50), accessibility findings, content quality, implementation quality, taste assessment. Taste scoring (X/75) included when `visual-taste.md` was read.
 2. **`prioritized-fixes.md`** (~50-100 lines) — Critical / Important / Polish fix lists with specific remediation per screen/component. **Tag style-level issues** with `[STYLE]` prefix — these need `/gsp-brand-refine` to update the `.yml` source, not just a design revision. Style-level: constraint violations, pattern mismatches, intensity miscalibration, missing bold bets. Screen-level: layout choices, content placement, component selection.

package/gsp/agents/gsp-designer.md

@@ -64,7 +64,7 @@ Baseline design principles — **STYLE.md overrides these** when present. A brut
 - Accessibility: VoiceOver labels on every element, respect `prefers-reduced-motion`, support all 12 text sizes
 - Gestures: never override system back, tap for primary action, long press for context menu
 
-Full reference: `references/apple-hig-patterns.md` (available via Read for specific HIG pattern details).
+Full reference: `skills/gsp-project-design/apple-hig-patterns.md` (available via Read for specific HIG pattern details).
 
 ## Anti-Pattern Awareness (distilled)
 
@@ -93,7 +93,7 @@ Write your screens as chunks to the project's design directory (path provided by
 
 ### Screen chunks
 
-Write one chunk per screen (~150-200 lines each), following `references/chunk-format.md`:
+Write one chunk per screen (~150-200 lines each), following the standard chunk format:
 
 **Naming:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`, `screen-03-user-profile.md`)
 

package/gsp/agents/gsp-project-researcher.md

@@ -44,7 +44,7 @@ Write your research as chunks to the project's research directory (path provided
 
 ### Research chunks
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`ux-patterns.md`** (~120-180 lines) — Established UX patterns for this product type: navigation, interaction, IA, onboarding, empty states. With sources and examples.
 2. **`competitor-ux.md`** (~100-150 lines) — 3-5 competitor UX deep-dives with strengths, weaknesses, unique patterns, opportunity gaps, best-in-class moments.

package/gsp/agents/gsp-researcher.md

@@ -46,7 +46,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/agents/gsp-reviewer.md

@@ -50,7 +50,7 @@ Write your review as chunks to the project's review directory (path provided by
 
 ### Review chunks
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`acceptance-report.md`** (~100-150 lines) — Overall verdict (Pass/Conditional Pass/Fail), implementation checklist (per-screen status with codebase file paths), token audit summary, screen coverage, component coverage, accessibility compliance, responsive verification
 2. **`issues.md`** (~50-100 lines) — Issues table (Issue, Severity, File Path, Line, Expected, Actual, Remediation). Critical issues block acceptance. All file paths reference actual codebase locations.

package/gsp/agents/gsp-scoper.md

@@ -44,7 +44,7 @@ Write your brief as chunks to the project's brief directory (path provided by th
 
 ### Brief chunks
 
-Write each chunk following the format in `references/chunk-format.md`:
+Write each chunk following the standard chunk format:
 
 1. **`scope.md`** (~80-120 lines) — Prioritized screen list, component scope, project boundaries, success criteria, dependencies, issue framing
 2. **`target-adaptations.md`** (~60-100 lines) — Token overrides, component adaptations, platform considerations, implementation target mapping

package/gsp/skills/get-shit-pretty/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: get-shit-pretty
-description: "Design engineering for AI coding tools. Full pipeline: brand research, strategy, identity, design system, UI design, critique, accessibility audit, build, and launch. Runs specialized agents with Apple HIG, Nielsen's heuristics, WCAG 2.2 AA, and design token standards baked in."
+description: "Design engineering for AI coding tools. Full pipeline: brand research, strategy, identity, guidelines, UI design, critique, accessibility audit, build, and launch. Expertise skills (color, typography, visuals) serve the entire pipeline. 15 specialized agents with Apple HIG, Nielsen's heuristics, WCAG 2.2 AA, and design token standards."
 user-invocable: false
 model: opus
 effort: high
@@ -12,8 +12,6 @@ Design engineering system for AI coding tools. Brand identity + design projects,
 
 ## Install
 
-GSP requires a full installation to work — agents, prompts, templates, and references that power the pipeline. Run:
-
 ```bash
 npx get-shit-pretty
 ```
@@ -22,11 +20,14 @@ Pick your runtime (Claude Code, OpenCode, Gemini CLI, or Codex CLI), choose glob
 
 ## What You Get
 
-A dual-diamond design pipeline with 23 commands:
+A dual-diamond design pipeline with 34 skills across two layers:
 
 ```
+◆ Expertise (knowledge owners — serve the full pipeline)
+color · typography · visuals · accessibility · style
+
 ◆ Branding
-research → strategy → identity → patterns
+research → strategy → identity → guidelines
 
 ◆ Project
 brief → research → design → critique → build → review → launch
@@ -34,12 +35,12 @@ brief → research → design → critique → build → review → launch
                                 └──── loop ────────┘
 ```
 
-Each skill spawns a specialized agent modeled after a real design discipline:
+Each pipeline phase spawns specialized agents. Expertise skills carry domain knowledge as sibling files — loaded on demand, zero session-start cost.
 
 - **Brand Research** — market landscape, audience, competitors
-- **Brand Strategy** — archetype, positioning, personality, voice, tone, messaging (Kapferer Prism)
-- **Brand Identity** — logo directions, color palette, typography
-- **Brand Patterns** — design tokens, component foundations
+- **Brand Strategy** — archetype, positioning, voice, messaging (Kapferer Prism)
+- **Brand Identity** — logo directions, color, typography, imagery
+- **Brand Guidelines** — design tokens, STYLE.md, component mapping
 - **Project Brief** — scope, screen list, gap analysis
 - **Project Research** — UX patterns, competitor experiences
 - **Project Design** — screens and flows (Apple HIG)

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

@@ -35,7 +35,7 @@ Run lightweight accessibility checks inline — contrast ratio lookups and token
 - Quick check mode (`--check`) produces display output only — no files written
 - Token audit mode runs inline — no agent spawned
 - Default conformance level is AA unless overridden by `--level AAA` or config
-- Foundation chunks follow `references/chunk-format.md` format
+- Foundation chunks follow `chunk-format.md` format
 </rules>
 
 <process>

package/gsp/skills/gsp-accessibility-audit/SKILL.md

@@ -33,7 +33,7 @@ Run full accessibility audits — design screen reviews, codebase ARIA/keyboard/
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/wcag-checklist.md
+@${CLAUDE_SKILL_DIR}/wcag-checklist.md
 </execution_context>
 
 <rules>
@@ -41,7 +41,7 @@ Run full accessibility audits — design screen reviews, codebase ARIA/keyboard/
 - One decision per question — never batch multiple questions in a single message
 - Statement mode reads prior audit results — fails gracefully if none exist
 - Default conformance level is AA unless overridden by `--level AAA` or config
-- Foundation chunks follow `references/chunk-format.md` format
+- Foundation chunks follow `chunk-format.md` format
 </rules>
 
 <process>

package/gsp/skills/gsp-add-reference/SKILL.md

@@ -23,6 +23,11 @@ Add reference material to a project for downstream agents to consume.
 **Output:** `{project}/references/` with organized reference files + `references/INDEX.md`
 </objective>
 
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
 <process>
 ## Step 0: Resolve project
 

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

@@ -23,6 +23,11 @@ Create terminal art with the user in the loop — gather intent, create, iterate
 **Agent:** `gsp-ascii-artist`
 </objective>
 
+<rules>
+- Always use `AskUserQuestion` for user interaction — never prompt via plain text
+- One decision per question — never batch multiple questions in a single message
+</rules>
+
 <process>
 ## Step 1: Gather intent
 

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

@@ -26,7 +26,7 @@ Audit an existing brand. Produce evolution map that guides research, strategy, a
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+@${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 
 <rules>
@@ -88,5 +88,5 @@ Update `evolution_scope` in `{BRAND_PATH}/config.json` with confirmed decisions.
 
 Update `{BRAND_PATH}/STATE.md`: set Phase 0 (Audit) to `complete`.
 
-Render phase transition (see `references/phase-transitions.md`).
+Invoke `/gsp-phase-transition` with phase `audit` and output directory `{BRAND_PATH}/audit/`.
 </process>

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

@@ -28,7 +28,7 @@ Operationalize brand identity into project-ready artifacts and complete the bran
 
 <execution_context>
 @${CLAUDE_SKILL_DIR}/../../templates/phases/patterns.md
-@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
+@${CLAUDE_SKILL_DIR}/design-tokens.md
 </execution_context>
 
 <rules>
@@ -212,7 +212,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-identity/SKILL.md

@@ -27,7 +27,7 @@ Build the brand's visual identity.
 
 <execution_context>
 @${CLAUDE_SKILL_DIR}/../../templates/phases/identity.md
-@${CLAUDE_SKILL_DIR}/../../references/color-composition.md
+@${CLAUDE_SKILL_DIR}/../gsp-color/references/color-composition.md
 </execution_context>
 
 <rules>
@@ -113,7 +113,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 +137,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/skills/gsp-brand-refine/SKILL.md

@@ -27,7 +27,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

@@ -27,7 +27,7 @@ Research market context that will inform brand strategy.
 
 <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}/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>
 
@@ -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/skills/gsp-brand-strategy/SKILL.md

@@ -27,9 +27,9 @@ Define brand strategy and voice through interactive creative direction, then pro
 
 <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
+@${CLAUDE_SKILL_DIR}/brand-archetypes.md
+@${CLAUDE_SKILL_DIR}/positioning-frameworks.md
+@${CLAUDE_SKILL_DIR}/voice-tone.md
 </execution_context>
 
 <rules>
@@ -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>

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

@@ -33,8 +33,8 @@ Compare a project's shipped state against its source brand across all dimensions
 </objective>
 
 <execution_context>
-@${CLAUDE_SKILL_DIR}/../../references/design-tokens.md
-@${CLAUDE_SKILL_DIR}/../../references/chunk-format.md
+@${CLAUDE_SKILL_DIR}/../gsp-brand-guidelines/design-tokens.md
+@${CLAUDE_SKILL_DIR}/chunk-format.md
 </execution_context>
 
 <rules>
@@ -93,7 +93,7 @@ Use the Update Map from the sync report. For each confirmed change:
 
 **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.
+Preserve chunk format per `chunk-format.md`. Update INDEX.md files if chunks were added.
 
 ## Step 4: Summary
 

package/gsp/skills/gsp-brand-sync/chunk-format.md

@@ -0,0 +1,79 @@
+# Chunk Format Reference
+
+Standard format for all GSP phase output files. Chunks are the primary output — agents write chunks directly, not monoliths.
+
+## File Format
+
+Every chunk follows this structure:
+
+    # {Section/Component/Screen Name}
+
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    ---
+
+    {Content for this chunk}
+
+    ---
+
+    ## Related
+
+    - [{Related chunk name}]({relative-path-to-related-chunk})
+
+## Naming Conventions
+
+- **Singular, kebab-case, lowercase:** "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
+- **Screen files:** `screen-{NN}-{kebab-case-name}.md` (e.g., `screen-01-home.md`)
+
+## INDEX.md Format
+
+Each phase directory gets an INDEX.md manifest:
+
+    # {Phase Name}
+    > Phase: {phase} | Brand/Project: {name} | Generated: {DATE}
+
+    | Chunk | File | ~Lines |
+    |-------|------|--------|
+    | {Section} | [{filename}](./{filename}) | ~{N} |
+
+Lightweight — just a lookup table. No prose.
+
+## Rules
+
+- **Chunks are primary output** — agents write chunks directly to the phase directory
+- **No monoliths** — do not write a single large file then re-chunk it
+- **Size target:** 50-200 lines per chunk
+- **Self-contained:** each chunk must be understandable without loading other chunks
+- **Cross-references:** `## Related` section uses relative paths to related chunks
+- **Idempotent:** re-running a phase regenerates all chunks in that phase directory
+
+## Output Budgets
+
+Context is finite. Every line in a chunk is consumed by downstream agents. Budget accordingly.
+
+### Per-chunk budgets
+
+| Chunk type | Target | Hard max | Notes |
+|-----------|--------|----------|-------|
+| Phase chunk (design, research, etc.) | 50-150 lines | 200 lines | Self-contained, one concept per chunk |
+| INDEX.md | 10-30 lines | 50 lines | Lookup table only, no prose |
+| BUILD-LOG.md | 50-100 lines | 150 lines | Summary + tables, not narrative |
+| Component spec | 30-80 lines | 120 lines | Props, states, behavior — not full implementation |
+| Screen spec | 80-150 lines | 200 lines | Layout, components, interactions, states |
+
+### Per-phase budgets (total across all chunks)
+
+| Phase | Target total | Hard max | Typical chunks |
+|-------|-------------|----------|----------------|
+| Brief | 100-200 lines | 300 lines | 2-4 |
+| Research | 200-400 lines | 600 lines | 5-8 |
+| Design | 300-600 lines | 800 lines | 6-12 |
+| Critique | 100-200 lines | 300 lines | 2-4 |
+| Build log | 50-100 lines | 150 lines | 1 |
+| Review | 100-200 lines | 300 lines | 2-4 |
+
+### Terminal output (inline skills)
+
+- **Diagnostic** (doctor, progress): uncapped — user needs to see it, does not persist in agent context
+- **Greeting/status** (start): 20-40 lines
+- **Phase transitions**: 10-20 lines