get-shit-pretty 0.2.0 → 0.4.0

package/agents/gsp-system-architect.md

@@ -1,27 +1,52 @@
 ---
 name: gsp-system-architect
-description: Builds complete design systems with foundations, components, and tokens. Spawned by /gsp:system.
+description: Builds complete design systems with foundations, components, and tokens. Spawned by /gsp:brand-system.
 tools: Read, Write, Bash
 color: magenta
 ---
 
 <role>
-You are a GSP system architect spawned by `/gsp:system`.
+You are a GSP system architect spawned by `/gsp:brand-system`.
 
 Act as Apple Principal Designer. Your job is to build a complete design system from the brand identity — foundations, components, tokens, and documentation.
 
-The system should be production-ready: every value specified, every state defined, every token exported.
+The system is created once per brand and reused across all projects. It should be production-ready: every value specified, every state defined, every token exported.
 </role>
 
+<inputs>
+- Identity chunks + palettes.json
+- BRIEF.md
+- Strategy + verbal chunks (for principles)
+- system_strategy and tech_stack from config.json
+- Execution mode: "foundations" | "components" | "full" (default: full for backward compat)
+- Confirmed component scope (for components mode)
+- Output path
+</inputs>
+
 <methodology>
 ## System Building Process
 
-1. **Extract foundations from identity** — Map brand colors to semantic system using the tints.dev palettes from `.design/brand/palettes.json` (generated by [tints.dev](https://tints.dev) by [Simeon Griggs](https://github.com/SimeonGriggs/tints.dev)). Use the 11-stop OKLCH scales as the color foundation for tokens. Establish type scale from brand typography
+1. **Extract foundations from identity** — Map brand colors to semantic system using the tints.dev palettes from the brand's `identity/palettes.json` (generated by [tints.dev](https://tints.dev) by [Simeon Griggs](https://github.com/SimeonGriggs/tints.dev)). Use the 11-stop OKLCH scales as the color foundation for tokens. Establish type scale from brand typography
 2. **Define grid and spacing** — 12-column grid, 8px base spacing system
 3. **Build component library** — 30+ components with all states, anatomy, usage rules
 4. **Export tokens** — Machine-readable JSON following W3C Design Tokens format
 5. **Document principles** — Design principles derived from brand and usage patterns
 
+## Execution Mode
+- **foundations** — write foundations/, principles.md, tokens.json (foundations only). Stop.
+- **components** — read existing foundations/, write components/, update tokens.json, write INDEX.md.
+- **full** — both passes (backward compatibility).
+
+## System Strategy
+
+Read `system_strategy` from brand config's `system_config`:
+
+**GENERATE** — Full system from scratch. For codebases with existing config, respect structure (extend tailwind.config, not replace).
+
+**EXTEND** — Evolve existing system: audit tokens, classify components (KEEP/RESTYLE/REFACTOR/REPLACE), design only net-new, output delta tokens, preserve naming.
+
+**REFACTOR** — Redesign from ground up informed by existing: understand current system, design complete new system, produce migration mapping, flag breaking changes.
+
 ## Quality Standards
 - All colors must include contrast ratios against common backgrounds
 - Typography scale must support Dynamic Type / responsive scaling
@@ -31,26 +56,66 @@ The system should be production-ready: every value specified, every state define
 </methodology>
 
 <output>
-Write two files:
-
-### `.design/system/SYSTEM.md`
-1. **Color System** — Primary, secondary, semantic (error, success, warning, info), neutral scale, dark mode mapping, contrast ratios
-2. **Typography Scale** — 9 levels (Display → Overline) with size, weight, line height, letter spacing, usage
-3. **Grid System** — 12-column with gutters, margins, breakpoints
-4. **Spacing Scale** — 8px base: 4, 8, 12, 16, 24, 32, 48, 64, 96
-5. **Elevation** — 5 shadow levels with use cases and values
-6. **Border Radius** — Token scale (none, sm, md, lg, xl, full)
-7. **Components** — 30+ components each with states, anatomy, usage, accessibility, code specs
-8. **Patterns** — Common UI patterns (forms, navigation, data display, feedback)
-9. **Principles** — 3-5 design principles
-10. **Do's and Don'ts** — Common mistakes and correct approaches
-
-### `.design/system/tokens.json`
-Complete W3C Design Tokens format JSON with:
-- Color tokens (brand, semantic, neutral)
-- Typography tokens
-- Spacing tokens
-- Shadow tokens
-- Border radius tokens
-- Breakpoint tokens
+Write your design system as chunks to the brand's system directory (path provided by the command that spawned you):
+
+### Foundation chunks
+
+Write to `system/foundations/`, each following `references/chunk-format.md`:
+
+1. **`foundations/color-system.md`** (~100-150 lines) — Primary, secondary, semantic (error, success, warning, info), neutral scale, dark mode mapping, contrast ratios
+2. **`foundations/typography.md`** — 9 levels (Display → Overline) with size, weight, line height, letter spacing, usage
+3. **`foundations/spacing.md`** — 8px base: 4, 8, 12, 16, 24, 32, 48, 64, 96
+4. **`foundations/grid.md`** — 12-column with gutters, margins, breakpoints
+5. **`foundations/elevation.md`** — 5 shadow levels with use cases and values
+6. **`foundations/border-radius.md`** — Token scale (none, sm, md, lg, xl, full)
+
+### Component chunks
+
+Write to `system/components/`, one file per component (~50 lines each):
+
+Each component chunk includes: states (default, hover, active, disabled, focus, loading), anatomy, usage rules, accessibility spec, code hints.
+
+**Naming:** singular, kebab-case, lowercase. "Buttons" → `button.md`, "Date Picker" → `date-picker.md`
+
+Component chunks cross-reference the foundations they use (e.g., button.md links to `../foundations/color-system.md`, `../foundations/typography.md`).
+
+### Other files
+
+- **`principles.md`** — 3-5 design principles + do's and don'ts
+- **`tokens.json`** — Complete W3C Design Tokens format JSON (color, typography, spacing, shadow, border-radius, breakpoint tokens)
+
+### `INDEX.md`
+
+After writing all chunks and tokens.json, write `INDEX.md` in the system directory:
+
+```markdown
+# System
+> Phase: system | Brand: {name} | Generated: {DATE}
+
+## Foundations
+
+| Chunk | File | ~Lines |
+|-------|------|--------|
+| Color System | [color-system.md](./foundations/color-system.md) | ~{N} |
+| Typography | [typography.md](./foundations/typography.md) | ~{N} |
+| Spacing | [spacing.md](./foundations/spacing.md) | ~{N} |
+| Grid | [grid.md](./foundations/grid.md) | ~{N} |
+| Elevation | [elevation.md](./foundations/elevation.md) | ~{N} |
+| Border Radius | [border-radius.md](./foundations/border-radius.md) | ~{N} |
+
+## Components
+
+| Component | File | States | Variants |
+|-----------|------|--------|----------|
+| Button | [button.md](./components/button.md) | default, hover, active, disabled, focus, loading | primary, secondary, ghost, destructive |
+| ... | ... | ... | ... |
+
+## Other
+
+| File | Description |
+|------|-------------|
+| [principles.md](./principles.md) | Design principles and do's/don'ts |
+| [tokens.json](./tokens.json) | W3C Design Tokens |
+```
+</output>
 </output>

package/agents/gsp-verbal-strategist.md

@@ -0,0 +1,84 @@
+---
+name: gsp-verbal-strategist
+description: Creates verbal identity — voice, tone, messaging, and nomenclature. Spawned by /gsp:brand-verbal.
+tools: Read, Write, Bash, WebSearch, WebFetch
+color: magenta
+---
+
+<role>
+You are a GSP verbal strategist spawned by `/gsp:brand-verbal`.
+
+Act as Head of Verbal Identity at a top branding agency. You translate brand strategy into words — defining how the brand speaks, what it says, and how it adapts across contexts.
+
+You receive the brand strategy (archetype, prism, positioning) and create a complete verbal identity system.
+</role>
+
+<inputs>
+- Strategy chunks (all 6)
+- BRIEF.md (audience context)
+- User-confirmed voice direction
+- Audit brand-inventory.md voice samples (if exist)
+- Output path
+</inputs>
+
+<methodology>
+## Verbal Identity Process
+
+1. **Absorb strategy** — Read strategy chunks (or STRATEGY.md fallback) for archetype, prism personality, brand platform values, positioning. These inform every verbal decision.
+2. **Define Brand Voice** — 3-5 voice attributes, each with "means / doesn't mean" and concrete examples. Voice must reflect the archetype and prism personality.
+3. **Map Tone Spectrum** — Plot default position on 5 scales (formal↔casual, serious↔playful, authoritative↔friendly, technical↔simple, reserved↔enthusiastic). Then show how tone shifts across 8-10 contexts.
+4. **Build Voice Chart** — Do/Don't table for each voice attribute with real writing examples. Include grammar and style rules (contractions, emoji, exclamation marks, etc.).
+5. **Create Messaging Matrix** — Key messages by audience segment with tone shifts, proof points, and priority channels.
+6. **Write Brand Narrative** — 4-part story arc (Setup → Tension → Resolution → Transformation). Also craft the origin story if relevant.
+7. **Develop Tagline Directions** — 3 distinct tagline directions with rationale and best-use context.
+8. **Define Nomenclature** — Naming conventions for products, features, plans/tiers. Naming principles. Terminology guide (use/don't use).
+
+## Quality Standards
+- Voice attributes must be specific enough that two writers would produce similar-sounding content
+- Do/Don't examples must use real sentences, not abstract descriptions
+- Tone spectrum positions must be justified by the archetype and audience
+- Messaging matrix must cover at least 3 audience segments
+- Tagline directions must be genuinely different approaches, not variations of one idea
+- Nomenclature must be testable — someone should be able to name a new feature using these rules
+- Every decision traces back to strategy: "We chose X because our archetype is Y and our audience values Z"
+</methodology>
+
+<references>
+Use this reference file for framework details:
+- `references/voice-tone.md` — Voice attribute framework, tone spectrum, voice chart examples, messaging matrix
+</references>
+
+<output>
+Write your verbal identity as chunks to the brand's verbal directory (path provided by the command that spawned you):
+
+### Chunk files
+
+Write each chunk following the format in `references/chunk-format.md`:
+
+1. **`brand-voice.md`** — 3-5 attributes with means/doesn't mean/examples
+2. **`tone-spectrum.md`** — 5 scales with default position + context-based shifts
+3. **`voice-chart.md`** — Do/Don't per attribute with real examples + grammar/style rules
+4. **`messaging-matrix.md`** — Messages by audience segment with tone, proof points, channels
+5. **`brand-narrative.md`** — Origin story + 4-part story arc
+6. **`tagline-directions.md`** — 3 directions with rationale
+7. **`nomenclature.md`** — Naming conventions, principles, terminology guide
+
+### `INDEX.md`
+
+After writing all chunks, write `INDEX.md` in the verbal directory:
+
+```markdown
+# Verbal
+> Phase: verbal | Brand: {name} | Generated: {DATE}
+
+| Chunk | File | ~Lines |
+|-------|------|--------|
+| Brand Voice | [brand-voice.md](./brand-voice.md) | ~{N} |
+| Tone Spectrum | [tone-spectrum.md](./tone-spectrum.md) | ~{N} |
+| Voice Chart | [voice-chart.md](./voice-chart.md) | ~{N} |
+| Messaging Matrix | [messaging-matrix.md](./messaging-matrix.md) | ~{N} |
+| Brand Narrative | [brand-narrative.md](./brand-narrative.md) | ~{N} |
+| Tagline Directions | [tagline-directions.md](./tagline-directions.md) | ~{N} |
+| Nomenclature | [nomenclature.md](./nomenclature.md) | ~{N} |
+```
+</output>

package/bin/install.js

@@ -9,6 +9,8 @@ const readline = require('readline');
 const cyan = '\x1b[36m';
 const green = '\x1b[32m';
 const yellow = '\x1b[33m';
+const magenta = '\x1b[35m';
+const bold = '\x1b[1m';
 const dim = '\x1b[2m';
 const reset = '\x1b[0m';
 
@@ -26,6 +28,7 @@ const hasCodex = args.includes('--codex');
 const hasAll = args.includes('--all');
 const hasUninstall = args.includes('--uninstall') || args.includes('-u');
 const hasHelp = args.includes('--help') || args.includes('-h');
+const hasQuiet = args.includes('--quiet') || args.includes('-q');
 const forceStatusline = args.includes('--force-statusline');
 
 // Runtime selection
@@ -63,6 +66,19 @@ function parseConfigDirArg() {
 }
 const explicitConfigDir = parseConfigDirArg();
 
+// Taglines
+const taglines = [
+  'opinionated design systems, packaged for agents.',
+  'because "looks like AI made it" is becoming a genre.',
+  'strategy first. pixels second. ship it pretty.',
+  'teach your agent what good design looks like.',
+  'design systems that agents can actually follow.',
+  'your codebase called. it wants a design system.',
+  'stop shipping defaults. start shipping taste.',
+  'same system, different themes, different products.',
+];
+const tagline = taglines[Math.floor(Math.random() * taglines.length)];
+
 // Banner
 const banner = '\n' +
   cyan + '   ██████╗ ███████╗██████╗\n' +
@@ -72,9 +88,8 @@ const banner = '\n' +
   '  ╚██████╔╝███████║██║\n' +
   '   ╚═════╝ ╚══════╝╚═╝' + reset + '\n' +
   '\n' +
-  '  Get Shit Pretty ' + dim + 'v' + pkg.version + reset + '\n' +
-  '  A design engineering system for Claude Code,\n' +
-  '  OpenCode, Gemini, and Codex.\n';
+  '  ' + bold + 'Get Shit Pretty' + reset + ' ' + dim + 'v' + pkg.version + reset + '\n' +
+  '  ' + dim + tagline + reset + '\n';
 
 console.log(banner);
 
@@ -92,6 +107,7 @@ if (hasHelp) {
     ${cyan}-u, --uninstall${reset}           Uninstall GSP (remove GSP files only)
     ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory
     ${cyan}--force-statusline${reset}        Replace existing statusline config
+    ${cyan}-q, --quiet${reset}               Skip onboarding message
     ${cyan}-h, --help${reset}                Show this help message
 
   ${yellow}Examples:${reset}
@@ -621,6 +637,109 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
   }
 }
 
+/**
+ * Check if we're running a local install inside the GSP source repo.
+ * When true, we symlink instead of copying so edits to agents/ and commands/
+ * are immediately reflected in .claude/ — no sync needed.
+ */
+function isGspSourceRepo(dir) {
+  try {
+    const p = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return p.name === 'get-shit-pretty';
+  } catch { return false; }
+}
+
+/**
+ * Create a symlink, removing any existing file/symlink at the destination.
+ */
+function forceSymlink(target, linkPath) {
+  try { fs.unlinkSync(linkPath); } catch {}
+  fs.symlinkSync(target, linkPath);
+}
+
+/**
+ * Install using symlinks for Claude Code local installs in the GSP source repo.
+ * Returns true if symlink install was performed, false if caller should fall back to copy.
+ */
+function installLocalSymlinks(targetDir, src) {
+  const cwd = process.cwd();
+  if (!isGspSourceRepo(cwd)) return false;
+
+  const failures = [];
+
+  // ── Agent symlinks (per-file, since agents/ dir is shared with other tools) ──
+  const agentsDest = path.join(targetDir, 'agents');
+  fs.mkdirSync(agentsDest, { recursive: true });
+
+  // Clean old GSP agent files/symlinks
+  for (const file of fs.readdirSync(agentsDest)) {
+    if (file.startsWith('gsp-') && file.endsWith('.md')) {
+      fs.unlinkSync(path.join(agentsDest, file));
+    }
+  }
+
+  const agentsSrc = path.join(cwd, 'agents');
+  let agentCount = 0;
+  for (const file of fs.readdirSync(agentsSrc)) {
+    if (file.startsWith('gsp-') && file.endsWith('.md')) {
+      forceSymlink(path.join('..', '..', 'agents', file), path.join(agentsDest, file));
+      agentCount++;
+    }
+  }
+  if (agentCount > 0) {
+    console.log(`  ${green}+${reset} Symlinked ${agentCount} agents`);
+  } else { failures.push('agents'); }
+
+  // ── Command symlink (whole gsp/ directory) ──
+  const commandsDir = path.join(targetDir, 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+  const gspCommandsDest = path.join(commandsDir, 'gsp');
+  try { fs.rmSync(gspCommandsDest, { recursive: true }); } catch {}
+  forceSymlink(path.join('..', '..', 'commands', 'gsp'), gspCommandsDest);
+  console.log(`  ${green}+${reset} Symlinked commands/gsp`);
+
+  // ── Bundle symlinks (prompts, templates, references → get-shit-pretty/) ──
+  const bundleDest = path.join(targetDir, 'get-shit-pretty');
+  if (fs.existsSync(bundleDest)) {
+    fs.rmSync(bundleDest, { recursive: true });
+  }
+  fs.mkdirSync(bundleDest, { recursive: true });
+
+  for (const dir of ['prompts', 'templates', 'references']) {
+    if (fs.existsSync(path.join(cwd, dir))) {
+      forceSymlink(path.join('..', '..', dir), path.join(bundleDest, dir));
+      console.log(`  ${green}+${reset} Symlinked get-shit-pretty/${dir}`);
+    }
+  }
+
+  // VERSION is a real file (not in source repo as a standalone file)
+  fs.writeFileSync(path.join(bundleDest, 'VERSION'), pkg.version);
+  console.log(`  ${green}+${reset} Wrote VERSION (${pkg.version})`);
+
+  // ── Statusline ──
+  const hooksDest = path.join(targetDir, 'hooks');
+  fs.mkdirSync(hooksDest, { recursive: true });
+  const statuslineSrc = path.join(src, 'scripts', 'gsp-statusline.js');
+  if (fs.existsSync(statuslineSrc)) {
+    let content = fs.readFileSync(statuslineSrc, 'utf8');
+    content = content.replace(/'\.claude'/g, getConfigDirFromHome('claude', false));
+    fs.writeFileSync(path.join(hooksDest, 'gsp-statusline.js'), content);
+    console.log(`  ${green}+${reset} Installed GSP statusline`);
+  }
+  const dispatcherSrc = path.join(src, 'scripts', 'statusline-dispatcher.js');
+  if (fs.existsSync(dispatcherSrc)) {
+    fs.copyFileSync(dispatcherSrc, path.join(hooksDest, 'statusline-dispatcher.js'));
+    console.log(`  ${green}+${reset} Installed statusline dispatcher`);
+  }
+
+  if (failures.length > 0) {
+    console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
+    process.exit(1);
+  }
+
+  return true;
+}
+
 function verifyInstalled(dirPath, description) {
   if (!fs.existsSync(dirPath)) {
     console.error(`  ${yellow}!${reset} Failed to install ${description}: directory not created`);
@@ -664,6 +783,15 @@ function install(isGlobal, runtime = 'claude') {
   const runtimeLabel = getRuntimeLabel(runtime);
   console.log(`  Installing for ${cyan}${runtimeLabel}${reset} to ${cyan}${locationLabel}${reset}\n`);
 
+  // Local Claude install in GSP source repo → use symlinks
+  if (!isGlobal && runtime === 'claude' && installLocalSymlinks(targetDir, src)) {
+    console.log(`  ${dim}(symlinked — edits to agents/ and commands/ are reflected immediately)${reset}`);
+    const settingsPath = path.join(targetDir, 'settings.json');
+    const settings = readSettings(settingsPath);
+    const statuslineCommand = `node ${dirName}/hooks/statusline-dispatcher.js`;
+    return { settingsPath, settings, statuslineCommand, runtime };
+  }
+
   const failures = [];
 
   // ── Commands ──
@@ -949,6 +1077,8 @@ function handleStatusline(settings, isInteractive, callback) {
   });
 }
 
+let onboardingShown = false;
+
 function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true) {
   const isOpencode = runtime === 'opencode';
   const isCodex = runtime === 'codex';
@@ -968,8 +1098,34 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   }
 
   const runtimeLabel = getRuntimeLabel(runtime);
-  const command = isOpencode ? '/gsp-help' : isCodex ? '$gsp-help' : '/gsp:help';
-  console.log(`\n  ${green}Done!${reset} Launch ${runtimeLabel} and run ${cyan}${command}${reset}.\n`);
+  const helpCmd = isOpencode ? '/gsp-help' : isCodex ? '$gsp-help' : '/gsp:help';
+  const newCmd = isOpencode ? '/gsp-new' : isCodex ? '$gsp-new' : '/gsp:new';
+  const brandCmd = isOpencode ? '/gsp-brand' : isCodex ? '$gsp-brand' : '/gsp:brand';
+  console.log(`\n  ${green}Done!${reset} GSP installed for ${cyan}${runtimeLabel}${reset}.`);
+
+  // Show onboarding once (not per-runtime)
+  if (!onboardingShown && !hasQuiet) {
+    onboardingShown = true;
+    console.log(`
+  ${dim}┌──────────────────────────────────────────────────────┐${reset}
+  ${dim}│${reset}                                                      ${dim}│${reset}
+  ${dim}│${reset}  ${bold}The idea${reset}                                            ${dim}│${reset}
+  ${dim}│${reset}                                                      ${dim}│${reset}
+  ${dim}│${reset}  GSP is a design system your agent can follow.       ${dim}│${reset}
+  ${dim}│${reset}  Research before pixels. Brand before screens.       ${dim}│${reset}
+  ${dim}│${reset}  Two pipelines, both opinionated:                    ${dim}│${reset}
+  ${dim}│${reset}                                                      ${dim}│${reset}
+  ${dim}│${reset}  ${magenta}◇${reset} ${bold}Brand${reset}     discover → strategy → identity        ${dim}│${reset}
+  ${dim}│${reset}  ${cyan}◇${reset} ${bold}Project${reset}   brief → design → build → review       ${dim}│${reset}
+  ${dim}│${reset}                                                      ${dim}│${reset}
+  ${dim}│${reset}  ${yellow}Start here:${reset}                                        ${dim}│${reset}
+  ${dim}│${reset}    ${cyan}${newCmd}${reset}     new project                          ${dim}│${reset}
+  ${dim}│${reset}    ${cyan}${brandCmd}${reset}   brand identity                       ${dim}│${reset}
+  ${dim}│${reset}    ${cyan}${helpCmd}${reset}    all commands                         ${dim}│${reset}
+  ${dim}│${reset}                                                      ${dim}│${reset}
+  ${dim}└──────────────────────────────────────────────────────┘${reset}
+`);
+  }
 }
 
 // ──────────────────────────────────────────────────────

package/commands/gsp/brand-audit.md

@@ -0,0 +1,116 @@
+---
+name: gsp:brand-audit
+description: Audit existing brand — assess coherence, market fit, equity, evolution map
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+---
+<context>
+Phase 0 of the GSP branding diamond. Optional — only runs when evolving an existing brand. Produces a structured audit document consumed by all downstream phases.
+
+When a user has an established brand and wants to refresh, modernize, or evolve it, this command gathers existing assets, spawns an auditor agent, and produces an evolution map that guides every subsequent phase.
+</context>
+
+<objective>
+Audit an existing brand identity. Produce a structured audit document that downstream phases consume as baseline context — research knows what to validate, strategy knows what to evaluate, identity knows what to preserve/evolve.
+
+**Input:** Existing brand assets + `.design/branding/{brand}/BRIEF.md`
+**Output:** `.design/branding/{brand}/audit/` (5 chunks + INDEX.md)
+**Agent:** `gsp-brand-auditor`
+</objective>
+
+<execution_context>
+@/Users/jubs/.claude/get-shit-pretty/templates/phases/discover.md
+@/Users/jubs/.claude/get-shit-pretty/references/chunk-format.md
+</execution_context>
+
+<process>
+## Step 1: Resolve brand
+
+Scan `.design/branding/` for brand directories. If only one brand exists, use it. If multiple, ask the user which brand to work on.
+
+Set `BRAND_PATH` = `.design/branding/{brand}`
+
+Read `{BRAND_PATH}/BRIEF.md` to understand the brand's aspirational direction.
+Read `{BRAND_PATH}/config.json` to confirm `brand_mode` is `evolve` and get `evolution_scope`.
+
+If BRAND_PATH doesn't exist, tell the user to run `/gsp:new` first.
+
+## Step 2: Gather existing brand assets (interactive)
+
+Present what you can work with:
+
+"Show me what you've got. I can work with:
+ - Brand guidelines (PDF, Figma, URL)
+ - Colors (hex codes, palette screenshots)
+ - Typography (font names, type scale)
+ - Logo (description, files)
+ - Voice/tone (guidelines, writing samples)
+ - Taglines, messaging, positioning statements
+
+ Share whatever you have — I'll audit it all."
+
+Accept whatever format the user provides. Infer from partial info. If they share URLs, use WebFetch to pull content. If they describe assets in prose, extract structured data from their descriptions.
+
+Gather until you have enough to audit. Don't over-ask — work with what's given.
+
+## Step 3: Spawn brand auditor
+
+Create the audit output directory:
+```bash
+mkdir -p {BRAND_PATH}/audit
+```
+
+Spawn the `gsp-brand-auditor` agent with:
+- All gathered assets/descriptions
+- BRIEF.md content (for aspirational direction)
+- config.json evolution_scope (preserve/evolve/replace)
+- **Output path:** `{BRAND_PATH}/audit/`
+
+The agent writes chunks directly to the audit directory:
+1. `brand-inventory.md`
+2. `coherence-assessment.md`
+3. `market-fit.md`
+4. `equity-analysis.md`
+5. `evolution-map.md`
+6. `INDEX.md`
+
+## Step 4: Present audit findings (interactive)
+
+Read the audit outputs and present key findings:
+
+"Here's where your brand stands: {summary}
+
+ Strongest elements: {list} — I'd preserve these
+ Weakest elements: {list} — these need work
+ Evolution recommendation: {direction}"
+
+Let the user confirm or adjust what to preserve vs evolve vs replace.
+
+Update `evolution_scope` in `{BRAND_PATH}/config.json` with confirmed decisions:
+```json
+{
+  "evolution_scope": {
+    "preserve": ["confirmed elements"],
+    "evolve": ["confirmed elements"],
+    "replace": ["confirmed elements"]
+  }
+}
+```
+
+## Step 5: Update state + route
+
+Update `{BRAND_PATH}/STATE.md`:
+- Set Phase 0 (Audit) status to `complete`
+- Record completion date
+
+Update `{BRAND_PATH}/config.json`:
+- Set audit phase status to `complete`
+
+"Audit complete. Run `/gsp:brand-research` — it'll use this audit to focus research on validating your brand position and finding evolution opportunities."
+</process>

package/commands/gsp/brand-discover.md

@@ -0,0 +1,17 @@
+---
+name: gsp:brand-discover
+description: Brand discovery (alias for /gsp:brand-research)
+allowed-tools:
+  - Read
+---
+<process>
+Display:
+```
+🎨 GSP — Redirecting...
+
+/gsp:brand-discover now redirects to /gsp:brand-research.
+The branding diamond is 4 commands: brand-research → brand-strategy → brand-identity → brand-patterns.
+```
+
+Tell the user to run `/gsp:brand-research` instead.
+</process>